OpaqueTimestampCodec
OpaqueTimestampCodec<
Brand> =object
Defined in: src/codecs/opaque/index.ts:68
A brand-scoped codec for generating and validating Opaque Timestamp IDs.
Same wire shape as the Timestamp codec ({brand}_ + 26 base32 chars) but the
payload is AES-CBC encrypted. generate, generateAt, and extractTimestamp
are async; parsing methods are sync. No minIdForTime / maxIdForTime —
encrypted payloads do not sort by creation time.
Remarks
Section titled “Remarks”Security properties (unauthenticated, deterministic, and malleable by design):
- The payload is AES-CBC encrypted but unauthenticated — there is no integrity tag. A tampered or wrong-key payload decrypts to garbage bytes without throwing.
- Opaque IDs must be treated as opaque handles, not as trusted or authenticated tokens.
extractTimestampis best-effort on untrusted input: a wrong or tampered key returns a plausible-lookingDatewithout error, not a verification failure. Do not treat the returned timestamp as proof of origin.
Type Parameters
Section titled “Type Parameters”Brand extends string
Properties
Section titled “Properties”~standard
Section titled “~standard”
readonly~standard:StandardSchemaProps<Brand>
Defined in: src/codecs/opaque/index.ts:102
Standard Schema validate entry point.
Methods
Section titled “Methods”extractTimestamp()
Section titled “extractTimestamp()”extractTimestamp(
id):Promise<Date>
Defined in: src/codecs/opaque/index.ts:93
Decrypts and decodes the creation Date from an Id<Brand>. Trusts the type — use safeParse() at boundaries first. See ADR-0002.
Requires the same key used at generation; a wrong key returns a plausible
but wrong Date, never an error. With rotation, select the codec for the
ID’s key epoch from your own records — the library cannot. See ADR-0013.
Parameters
Section titled “Parameters”Id<Brand>
Returns
Section titled “Returns”Promise<Date>
fromUUID()
Section titled “fromUUID()”fromUUID(
value):Id<Brand>
Defined in: src/codecs/opaque/index.ts:115
Parses a UUID string into an Id<Brand>. Accepts case-insensitive 8-4-4-4-12
hyphenated form only. Throws IdsError with code: "invalid_id" on bad input.
See ADR-0024.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Id<Brand>
generate()
Section titled “generate()”generate():
Promise<Id<Brand>>
Defined in: src/codecs/opaque/index.ts:70
Produces a new canonical encrypted ID using the codec’s now and rng.
Returns
Section titled “Returns”Promise<Id<Brand>>
generateAt()
Section titled “generateAt()”generateAt(
date):Promise<Id<Brand>>
Defined in: src/codecs/opaque/index.ts:72
Produces a new canonical encrypted ID with timestamp bytes from date. Throws on invalid dates.
Parameters
Section titled “Parameters”Date
Returns
Section titled “Returns”Promise<Id<Brand>>
is(
value):value is Id<Brand>
Defined in: src/codecs/opaque/index.ts:77
Strict type guard: true only for already-canonical strings for this brand.
For untrusted input, use safeParse() or parse() instead. See ADR-0003.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”value is Id<Brand>
parse()
Section titled “parse()”parse(
value):Id<Brand>
Defined in: src/codecs/opaque/index.ts:81
Lenient parse: normalises case and Crockford aliases, returns canonical Id<Brand>, or throws.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”Id<Brand>
safeFromUUID()
Section titled “safeFromUUID()”safeFromUUID(
value):ParseResult<Brand>
Defined in: src/codecs/opaque/index.ts:120
Non-throwing UUID parse. Returns { ok: true, id } or
{ ok: false, error: "not_string" | "invalid_uuid" }. See ADR-0024.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”ParseResult<Brand>
safeParse()
Section titled “safeParse()”safeParse(
value):ParseResult<Brand>
Defined in: src/codecs/opaque/index.ts:85
Lenient parse without throwing: normalises to canonical form, or returns { ok: false, error }.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”ParseResult<Brand>
toJsonSchema()
Section titled “toJsonSchema()”toJsonSchema():
JsonSchema
Defined in: src/codecs/opaque/index.ts:100
JSON Schema for the canonical wire form. The pattern matches the canonical stored
form only and is deliberately stricter than parse()/safeParse(), which accept
uppercase letters and Crockford aliases (o/i/l) before normalising. See ADR-0003.
The example is a structural placeholder (generated at construction time).
Returns
Section titled “Returns”toUUID()
Section titled “toUUID()”toUUID(
id):string
Defined in: src/codecs/opaque/index.ts:109
Converts a trusted Id<Brand> to an RFC 9562 canonical (lowercase, hyphenated)
UUID string by reinterpreting the 16-byte payload verbatim. The payload is the
encrypted ciphertext — toUUID does not decrypt it. Total — cannot fail.
Returns a plain string (brand is shed). See ADR-0024.
Parameters
Section titled “Parameters”Id<Brand>
Returns
Section titled “Returns”string