WrappedKeyCodec
WrappedKeyCodec<
Brand,Kind> =object
Defined in: src/codecs/wrapped/index.ts:102
Codec returned by createWrappedKeyId.
Wraps a caller-owned integer lookup key into a public Id and recovers it on unwrap. The codec is deterministic under fixed key material: the same lookup key always yields the same public ID (equality leakage).
wrap/unwrap/safeUnwrap/safeVerifyare async (WebCrypto).is,parse,safeParse, andtoJsonSchemaare synchronous and require no key material — they validate prefix and base32 shape only.- The
Kindtype parameter drives value types at the TypeScript boundary:u32/i32→number;u64/i64→bigint.
Remarks
Section titled “Remarks”Security properties (correctness-grade verification, not AEAD):
- The construction is deterministic — the same lookup key always yields the same public ID (equality leakage).
- The verification tag is a fixed 64-bit (8-byte) truncation of a domain-separated HMAC over the brand, kind, and lookup key lane.
- False-accept rate is approximately
keyring_size / 2^64perunwraptrial — correctness-grade verification, not AEAD-strength origin authentication. - Consumers requiring full AEAD guarantees must use a different construction.
Type Parameters
Section titled “Type Parameters”Brand extends string
Kind extends WrappedKind
Properties
Section titled “Properties”~standard
Section titled “~standard”
readonly~standard:StandardSchemaProps<Brand>
Defined in: src/codecs/wrapped/index.ts:147
Methods
Section titled “Methods”fromUUID()
Section titled “fromUUID()”fromUUID(
value):Id<Brand>
Defined in: src/codecs/wrapped/index.ts:159
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>
is(
value):value is Id<Brand>
Defined in: src/codecs/wrapped/index.ts:141
Strict type guard: true only for already-canonical Id<Brand> strings.
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/wrapped/index.ts:143
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/wrapped/index.ts:164
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/wrapped/index.ts:145
Normalise to canonical form, or return { ok: false, error }.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”ParseResult<Brand>
safeUnwrap()
Section titled “safeUnwrap()”safeUnwrap(
input):Promise<UnwrapResult<Brand,Kind>>
Defined in: src/codecs/wrapped/index.ts:126
Non-throwing path for untrusted input.
Structurally parses input first (same rules as safeParse), then
verifies the payload. Returns { ok: false, error } on any failure —
ParseError for structural problems or "verification_failed" for tag
mismatch — without throwing. Tamper, wrong keyring, and revoked-key cases
all surface as "verification_failed".
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”Promise<UnwrapResult<Brand, Kind>>
safeVerify()
Section titled “safeVerify()”safeVerify(
input):Promise<SafeVerifyResult<Brand>>
Defined in: src/codecs/wrapped/index.ts:139
Verify-only alias of safeUnwrap for untrusted input.
Structurally parses input, then verifies the payload — returning
{ ok: true, id } on success (dropping the recovered lookupKey) or
{ ok: false, error } on any failure, without throwing. Deliberately
redundant with safeUnwrap (a wrapped ID cannot be verified without
unwrapping it): use safeUnwrap when the lookup key is needed, and
safeVerify to gate on authenticity alone. This is the method that lets the
codec satisfy the HTTP adapters’ IdVerifiableCodec interface under
verify: true. See ADR-0036.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”Promise<SafeVerifyResult<Brand>>
toJsonSchema()
Section titled “toJsonSchema()”toJsonSchema():
JsonSchema
Defined in: src/codecs/wrapped/index.ts:146
Returns
Section titled “Returns”toUUID()
Section titled “toUUID()”toUUID(
id):string
Defined in: src/codecs/wrapped/index.ts:153
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
unwrap()
Section titled “unwrap()”unwrap(
id):Promise<LookupKeyForKind<Kind>>
Defined in: src/codecs/wrapped/index.ts:116
Verify the payload of a trusted Id<Brand> and return the lookup key.
Throws IdsError with code: "verification_failed" if no entry in the
wrapping keyring matches the payload tag. Use safeUnwrap for
untrusted input.
Parameters
Section titled “Parameters”Id<Brand>
Returns
Section titled “Returns”Promise<LookupKeyForKind<Kind>>
wrap()
Section titled “wrap()”wrap(
lookupKey):Promise<Id<Brand>>
Defined in: src/codecs/wrapped/index.ts:108
Wrap lookupKey into a public ID using the current (first) wrapping key.
Throws if lookupKey is out of range or the wrong JS type for Kind.
Parameters
Section titled “Parameters”lookupKey
Section titled “lookupKey”LookupKeyForKind<Kind>
Returns
Section titled “Returns”Promise<Id<Brand>>