SignedTimestampCodec
SignedTimestampCodec<
Brand> =object
Defined in: src/codecs/signed/index.ts:81
Codec returned by createSignedTimestampId.
Keeps the 6-byte millisecond timestamp readable and sortable like the Timestamp codec, but replaces half of the 10-byte random tail with a truncated HMAC tag, making IDs tamper-evident and verifiable without a database lookup.
Byte layout: ts6 ‖ rand5 ‖ tag5 where the 40-bit tag =
trunc(HMAC-SHA256(hmacKey, brand ‖ ts6 ‖ rand5), 40).
- Async (HMAC):
generate,generateAt,verify,safeVerify. - Sync (no key / plaintext timestamp): all other methods.
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/signed/index.ts:140
Standard Schema validate entry point.
Methods
Section titled “Methods”extractTimestamp()
Section titled “extractTimestamp()”extractTimestamp(
id):Date
Defined in: src/codecs/signed/index.ts:113
Decodes the creation Date from an Id<Brand>.
Sync — the 6-byte timestamp is plaintext. Trusts the type; use safeParse() at boundaries first.
Best-effort: the timestamp is returned without checking the HMAC tag — a tampered
or unsigned ID yields the attacker-controlled timestamp without error. Call
verify() / safeVerify() first if you need an authenticated timestamp.
Parameters
Section titled “Parameters”Id<Brand>
Returns
Section titled “Returns”Date
fromUUID()
Section titled “fromUUID()”fromUUID(
value):Id<Brand>
Defined in: src/codecs/signed/index.ts:152
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/signed/index.ts:83
Produces a canonical ID signed with the current (first) key.
Returns
Section titled “Returns”Promise<Id<Brand>>
generateAt()
Section titled “generateAt()”generateAt(
date):Promise<Id<Brand>>
Defined in: src/codecs/signed/index.ts:88
Produces a canonical ID with timestamp from date, signed with the current key.
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/signed/index.ts:128
Strict type guard: true only for already-canonical Id<Brand> strings.
For untrusted input, use safeParse() or safeVerify() instead.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”value is Id<Brand>
maxIdForTime()
Section titled “maxIdForTime()”maxIdForTime(
date):Id<Brand>
Defined in: src/codecs/signed/index.ts:123
Tight upper bound sentinel for range scans (ts(t) ‖ 0xff×10).
Not verifiable — carries no valid tag.
Parameters
Section titled “Parameters”Date
Returns
Section titled “Returns”Id<Brand>
minIdForTime()
Section titled “minIdForTime()”minIdForTime(
date):Id<Brand>
Defined in: src/codecs/signed/index.ts:118
Tight lower bound sentinel for range scans (ts(t) ‖ 0x00×10).
Not verifiable — carries no valid tag.
Parameters
Section titled “Parameters”Date
Returns
Section titled “Returns”Id<Brand>
parse()
Section titled “parse()”parse(
value):Id<Brand>
Defined in: src/codecs/signed/index.ts:130
Normalise to canonical form, or throw on parse failure.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”Id<Brand>
safeFromUUID()
Section titled “safeFromUUID()”safeFromUUID(
value):ParseResult<Brand>
Defined in: src/codecs/signed/index.ts:157
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/signed/index.ts:132
Normalise to canonical form, or return { ok: false, error }.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”ParseResult<Brand>
safeVerify()
Section titled “safeVerify()”safeVerify(
input):Promise<SafeVerifyResult<Brand>>
Defined in: src/codecs/signed/index.ts:104
Non-throwing path for untrusted input.
Structurally parses input first (same rules as safeParse), then
verifies the HMAC tag. Returns { ok: false, error } on any failure —
ParseError for structural problems or "verification_failed" for tag
mismatch — without throwing.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”Promise<SafeVerifyResult<Brand>>
toJsonSchema()
Section titled “toJsonSchema()”toJsonSchema():
JsonSchema
Defined in: src/codecs/signed/index.ts:138
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.
Returns
Section titled “Returns”toUUID()
Section titled “toUUID()”toUUID(
id):string
Defined in: src/codecs/signed/index.ts:146
Converts a trusted Id<Brand> to an RFC 9562 canonical (lowercase, hyphenated)
UUID string by reinterpreting the 16-byte payload verbatim. Total — cannot fail.
Returns a plain string (brand is shed). See ADR-0024.
Parameters
Section titled “Parameters”Id<Brand>
Returns
Section titled “Returns”string
verify()
Section titled “verify()”verify(
id):Promise<void>
Defined in: src/codecs/signed/index.ts:95
Recomputes the HMAC tag across every keyring entry.
Throws IdsError with code: "verification_failed" if no entry matches.
Tamper of the brand, timestamp bytes, or random bytes all fail here.
Parameters
Section titled “Parameters”Id<Brand>
Returns
Section titled “Returns”Promise<void>