@request-seal/core 0.1.0 → 0.2.0

package/dist/jose/jws.js

@@ -1,3 +1,4 @@
+import { denoInspection } from "../brand.js";
 import { encodeBase64Url, decodeBase64Url } from "../bytes.js";
 import { encodeUtf8 } from "../runtime.js";
 import { isKeyHandle } from "../key_handle.js";
@@ -10,9 +11,11 @@ import { joseError, isRequestSealError } from "../errors/types.js";
 import { bytes, json, serialize, parse, compact, need, } from "./header.js";
 import { JWS_ALGORITHMS, context, policy, resolve, selected, bounded, publicSafe, alive, take, ok, err, } from "./support.js";
 const branded = new WeakSet(), token = Object.freeze({});
+/** Check the private brand of a verified JWS result. */
 export function isJwsResult(value) {
     return typeof value === "object" && value !== null && branded.has(value);
 }
+/** A branded verified JWS result that confines payload bytes. */
 export class JwsResult {
     algorithm;
     header;
@@ -34,6 +37,7 @@ export class JwsResult {
     get payload() {
         return new Uint8Array(this.#payload);
     }
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON() {
         return Object.freeze({
             algorithm: this.algorithm,
@@ -45,8 +49,8 @@ export class JwsResult {
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toJSON();
     }
-    [Symbol.for("Deno.customInspect")]() {
-        return this.toJSON();
+    [Symbol.for("Deno.customInspect")](render) {
+        return denoInspection(render, this.toJSON());
     }
 }
 Object.freeze(JwsResult.prototype);
@@ -106,6 +110,7 @@ async function signing(protectedPart, h, payload, handle, c) {
         data.fill(0);
     }
 }
+/** Sign a compact JWS with an explicit algorithm and caller-owned signer. */
 export async function sign(protectedPairs, payload, handle, options = {}) {
     return publicSafe(async () => {
         const c = context(options, 5000, true);
@@ -120,6 +125,7 @@ export async function sign(protectedPairs, payload, handle, options = {}) {
         }
     });
 }
+/** Sign a compact JWS while preserving the supplied protected-header bytes. */
 export async function signProtected(protectedBytes, payload, handle, options = {}) {
     return publicSafe(async () => {
         const c = context(options, 5000, true);
@@ -134,6 +140,7 @@ export async function signProtected(protectedBytes, payload, handle, options = {
         }
     });
 }
+/** Verify a compact JWS under an explicit algorithm and key policy. */
 export async function verify(input, inputPolicy, options = {}) {
     return publicSafe(async () => {
         const p = policy(inputPolicy, "jws"), c = context(options, p.timeout);
@@ -183,9 +190,14 @@ export async function verify(input, inputPolicy, options = {}) {
         }, "invalid_signature");
     });
 }
+/** Compact JWS signing and verification operations. */
 export const JWS = Object.freeze({
+    /** Sign a compact JWS with an explicit algorithm and caller-owned signer. */
     sign,
+    /** Sign a compact JWS while preserving the supplied protected-header bytes. */
     signProtected,
+    /** Verify a compact JWS under an explicit algorithm and key policy. */
     verify,
+    /** Check the private brand of the operation result. */
     isResult: isJwsResult,
 });

package/dist/jose/key-management.d.ts

@@ -4,10 +4,12 @@ import { type PublicKey } from "../public_key.ts";
 import { type KeyHandle } from "../key_handle.ts";
 import { type Result } from "../result.ts";
 import { type Header } from "./header.ts";
+/** Owned encrypted-key and content-encryption-key bytes from key wrapping. */
 export type WrapResult = Readonly<{
     encrypted_key: Uint8Array<ArrayBuffer>;
     header: Header;
 }>;
+/** Check the private brand of a JOSE key-management handle. */
 export declare function isKeyManagementHandle(value: unknown): value is KeyManagementHandle;
 /** Caller-owned custodian primitives. RSA private and AES keys never escape as
  * CryptoKey references. Primitive decrypt releases bytes only after authentication. */
@@ -15,16 +17,25 @@ export declare class KeyManagementHandle {
     #private;
     readonly algorithm: string;
     private constructor();
+    /** Import caller-owned local key material into a confined capability. */
     static local(algorithm: unknown, material: unknown): Promise<Result<KeyManagementHandle>>;
+    /** Wrap a generated content-encryption key with the bound key-management algorithm. */
     wrap(algorithm: unknown, content: unknown, context?: Context): Promise<Result<WrapResult>>;
+    /** Authenticate and decrypt content using the bound direct-encryption key. */
     decrypt(encryptedKey: unknown, header: Header, context?: Context): Promise<Result<Uint8Array<ArrayBuffer>>>;
+    /** Confine an unwrapped content-encryption key in a decryption capability. */
     unwrap(encryptedKey: unknown, header: Header, context?: Context): Promise<Result<UnwrappedKey>>;
+    /** Release retained key-management custody and invalidate the capability. */
     release(): Promise<Result<true>>;
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON(): unknown;
 }
 export declare function random(length: number): Uint8Array<ArrayBuffer>;
 export declare function wrapPublic(key: PublicKey | KeyHandle, algorithm: string, content: Uint8Array, context: Context): Promise<Result<WrapResult>>;
+/** Constructors and branding checks for JOSE key-management capabilities. */
 export declare const KeyManagement: Readonly<{
+    /** Import caller-owned local key material into a confined capability. */
     local: typeof KeyManagementHandle.local;
+    /** Check the private brand of a key-management capability. */
     isHandle: typeof isKeyManagementHandle;
 }>;

package/dist/jose/key-management.js

@@ -1,3 +1,4 @@
+import { denoInspection } from "../brand.js";
 import { now } from "../runtime.js";
 import { isContext, withDeadline } from "../context.js";
 import { Custody } from "../custody/index.js";
@@ -14,6 +15,7 @@ import { resolveAlgorithm, importParameters } from "../crypto/algorithm.js";
 import { bytes, headerValue, need, take } from "./header.js";
 import { bounded, publicSafe, alive, JWE_ALGORITHMS } from "./support.js";
 const branded = new WeakSet(), token = Object.freeze({});
+/** Check the private brand of a JOSE key-management handle. */
 export function isKeyManagementHandle(value) {
     return typeof value === "object" && value !== null && branded.has(value);
 }
@@ -32,6 +34,7 @@ export class KeyManagementHandle {
         branded.add(this);
         Object.freeze(this);
     }
+    /** Import caller-owned local key material into a confined capability. */
     static async local(algorithm, material) {
         return publicSafe(async () => {
             need(typeof algorithm === "string" && JWE_ALGORITHMS.includes(algorithm), "algorithm_not_permitted");
@@ -96,6 +99,7 @@ export class KeyManagementHandle {
             }
         });
     }
+    /** Wrap a generated content-encryption key with the bound key-management algorithm. */
     async wrap(algorithm, content, context) {
         return publicSafe(async () => {
             need(algorithm === this.algorithm && this.algorithm.endsWith("GCMKW"), "algorithm_mismatch", "key");
@@ -128,6 +132,7 @@ export class KeyManagementHandle {
             }, "signer_failed");
         });
     }
+    /** Authenticate and decrypt content using the bound direct-encryption key. */
     async decrypt(encryptedKey, header, context) {
         return publicSafe(async () => {
             const c = context === undefined ? take(withDeadline()) : context;
@@ -170,6 +175,7 @@ export class KeyManagementHandle {
             }, "decryption_failed");
         });
     }
+    /** Confine an unwrapped content-encryption key in a decryption capability. */
     async unwrap(encryptedKey, header, context) {
         return publicSafe(async () => {
             const c = context === undefined ? take(withDeadline()) : context;
@@ -214,10 +220,12 @@ export class KeyManagementHandle {
             }, "decryption_failed");
         });
     }
+    /** Release retained key-management custody and invalidate the capability. */
     async release() {
         this.#key = undefined;
         return ok(true);
     }
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON() {
         return Object.freeze({
             kind: "KeyManagementHandle",
@@ -227,8 +235,8 @@ export class KeyManagementHandle {
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toJSON();
     }
-    [Symbol.for("Deno.customInspect")]() {
-        return this.toJSON();
+    [Symbol.for("Deno.customInspect")](render) {
+        return denoInspection(render, this.toJSON());
     }
 }
 Object.freeze(KeyManagementHandle.prototype);
@@ -259,7 +267,10 @@ export async function wrapPublic(key, algorithm, content, context) {
         return ok(Object.freeze({ encrypted_key: encrypted, header: Object.freeze([]) }));
     }, "signer_failed");
 }
+/** Constructors and branding checks for JOSE key-management capabilities. */
 export const KeyManagement = Object.freeze({
+    /** Import caller-owned local key material into a confined capability. */
     local: KeyManagementHandle.local,
+    /** Check the private brand of a key-management capability. */
     isHandle: isKeyManagementHandle,
 });

package/dist/jose/nested.d.ts

@@ -1,14 +1,20 @@
 import { type Result } from "../result.ts";
 import { type JweResult } from "./jwe.ts";
 import { type JwsResult } from "./jws.ts";
+/** A branded pair of authenticated outer JWE and verified inner JWS results. */
 export type NestedResult = Readonly<{
     jwe: JweResult;
     jws: JwsResult;
 }>;
+/** Check the private brand of a nested JOSE result. */
 export declare function isNestedResult(value: unknown): value is NestedResult;
 export declare function innerCompact(input: Uint8Array): Result<readonly string[]>;
+/** Authenticate an outer JWE and verify its inner compact JWS. */
 export declare function decrypt(input: unknown, policy: unknown, options: unknown): Promise<Result<NestedResult>>;
+/** One-level nested JWE decryption and JWS verification operations. */
 export declare const Nested: Readonly<{
+    /** Authenticate an outer JWE and verify its inner compact JWS. */
     decrypt: typeof decrypt;
+    /** Check the private brand of the operation result. */
     isResult: typeof isNestedResult;
 }>;

package/dist/jose/nested.js

@@ -7,6 +7,7 @@ import { compact, headerValue, need, take } from "./header.js";
 import { joseError } from "../errors/types.js";
 import { publicSafe, ok } from "./support.js";
 const branded = new WeakSet();
+/** Check the private brand of a nested JOSE result. */
 export function isNestedResult(value) {
     return typeof value === "object" && value !== null && branded.has(value);
 }
@@ -14,6 +15,7 @@ export function innerCompact(input) {
     const framed = compact(input, 3, false);
     return !framed.ok && framed.error.reason === 'invalid_serialization' ? err(joseError('nesting_depth', 'nesting')) : framed;
 }
+/** Authenticate an outer JWE and verify its inner compact JWS. */
 export async function decrypt(input, policy, options) {
     return publicSafe(async () => {
         const opts = snapshotOptions(options, ["content_types", "context"]);
@@ -52,4 +54,10 @@ export async function decrypt(input, policy, options) {
         }
     });
 }
-export const Nested = Object.freeze({ decrypt, isResult: isNestedResult });
+/** One-level nested JWE decryption and JWS verification operations. */
+export const Nested = Object.freeze({
+    /** Authenticate an outer JWE and verify its inner compact JWS. */
+    decrypt,
+    /** Check the private brand of the operation result. */
+    isResult: isNestedResult
+});

package/dist/json.d.ts

@@ -1,17 +1,22 @@
 import { type Result } from './result.ts';
+/** An ordered JSON tree that retains numeric source text. */
 export type JsonNode = null | boolean | string | JsonNumber | JsonObject | JsonArray;
+/** A JSON number represented by its original lexeme. */
 export type JsonNumber = {
     readonly kind: 'number';
     readonly lexeme: string;
 };
+/** A JSON object represented by ordered key-value pairs. */
 export type JsonObject = {
     readonly kind: 'object';
     readonly pairs: readonly (readonly [string, JsonNode])[];
 };
+/** A JSON array represented by an ordered sequence of nodes. */
 export type JsonArray = {
     readonly kind: 'array';
     readonly items: readonly JsonNode[];
 };
+/** Byte, depth, and container limits for JSON decoding. */
 export type JsonLimits = {
     maxBytes: number;
     maxDepth: number;
@@ -19,10 +24,12 @@ export type JsonLimits = {
     maxArrayLength: number;
     maxStringBytes: number;
 };
+/** JSON limits and explicit duplicate and noncharacter policies. */
 export type JsonDecodeOptions = Partial<JsonLimits> & {
     rejectDuplicates?: boolean;
     acceptNoncharacters?: boolean;
 };
+/** A decoded JSON tree and its duplicate member names. */
 export type DecodedJson = {
     readonly node: JsonNode;
     readonly duplicates: readonly string[];

package/dist/key_handle.d.ts

@@ -4,18 +4,27 @@ import { type CustodyAlgorithm } from './crypto/algorithm.ts';
 import { type PublicKey } from './public_key.ts';
 import { type KeyIdentity } from './key_identity.ts';
 import { type UnwrappedKey } from './custody/content_key.ts';
+/** A branded algorithm-bound capability that confines private key operations. */
 export type KeyHandle = Readonly<{
     algorithm: CustodyAlgorithm;
     capabilities: readonly ('sign' | 'verify' | 'unwrap')[];
-    sign: (algorithm: unknown, data: unknown, context: Context) => Promise<Result<Uint8Array<ArrayBuffer>>>;
-    verify: (algorithm: unknown, signature: unknown, data: unknown, context: Context) => Promise<Result<true>>;
+    /** Sign bounded bytes with the algorithm-bound custody capability. */
+    sign: (algorithm: unknown, data: unknown, context: Context, options?: unknown) => Promise<Result<Uint8Array<ArrayBuffer>>>;
+    /** Verify a signature through the algorithm-bound custody capability. */
+    verify: (algorithm: unknown, signature: unknown, data: unknown, context: Context, options?: unknown) => Promise<Result<true>>;
+    /** Return the handle's branded public key. */
     publicKey: (context?: Context) => Promise<Result<PublicKey>>;
+    /** Return the handle's branded key identity. */
     identity: (context?: Context) => Promise<Result<KeyIdentity>>;
+    /** Unwrap an encrypted key into a confined decryption capability. */
     unwrap: (algorithm: unknown, wrappedKey: unknown, context: Context, options?: unknown) => Promise<Result<UnwrappedKey>>;
+    /** Release retained custody and invalidate the capability. */
     release: () => Promise<Result<true>>;
 }>;
+/** The caller-provided operation port wrapped by a branded key handle. */
 export type Custodian = Pick<KeyHandle, 'sign' | 'verify' | 'publicKey' | 'identity' | 'unwrap' | 'release'>;
+/** Check the private brand of a custody handle. */
 export declare function isKeyHandle(value: unknown): value is KeyHandle;
 /** Wrap trusted custodian code under deadline, result validation, and fault containment. */
 export declare function createKeyHandle(algorithm: unknown, port: Custodian, capabilities?: KeyHandle['capabilities']): Result<KeyHandle>;
-export declare function verifyHandle(key: KeyHandle, algorithm: unknown, signature: unknown, data: unknown, context: Context): Promise<Result<true>>;
+export declare function verifyHandle(key: KeyHandle, algorithm: unknown, signature: unknown, data: unknown, context: Context, options?: unknown): Promise<Result<true>>;

package/dist/key_handle.js

@@ -1,15 +1,18 @@
+import { denoInspection } from './brand.js';
+import { byteLimit } from './crypto/options.js';
 import { snapshotOptions } from './brand.js';
 import { withDeadline, isContext, remainingMs, run, } from './context.js';
-import { SIGNATURE_MAX_BYTES, CUSTODY_SIGNATURE_MAX_BYTES } from './constants.js';
+import { CRYPTO_MAX_BYTES_CEILING, SIGNATURE_MAX_BYTES, CUSTODY_SIGNATURE_MAX_BYTES } from './constants.js';
 import { custodyError, isRequestSealError } from './errors/types.js';
 import { ok, err } from './result.js';
 import { resolveAlgorithm, selection, } from './crypto/algorithm.js';
-import { dataBytes } from './crypto/primitive.js';
+import { dataBytes, boundedBinary, binaryByteLength } from './crypto/primitive.js';
 import { isPublicKey } from './public_key.js';
 import { isKeyIdentity } from './key_identity.js';
 import { isUnwrappedKey } from './custody/content_key.js';
 const handles = new WeakSet();
 const token = Object.freeze({});
+/** Check the private brand of a custody handle. */
 export function isKeyHandle(value) {
     return typeof value === 'object' && value !== null && handles.has(value);
 }
@@ -71,7 +74,10 @@ class ManagedHandle {
         const resolved = resolveAlgorithm(algorithm, true);
         return resolved.ok && resolved.value.id === this.#spec.id;
     }
-    async sign(algorithm, data, context) {
+    async sign(algorithm, data, context, options = {}) {
+        const maximum = byteLimit(options);
+        if (!maximum.ok)
+            return err(custodyError('invalid_options'));
         try {
             if (!this.#port)
                 return err(custodyError('key_not_found'));
@@ -81,25 +87,27 @@ class ManagedHandle {
                 return err(custodyError('key_mismatch'));
             if (!this.capabilities.includes('sign'))
                 return err(custodyError('unsupported_operation'));
-            const bytes = dataBytes(data);
+            const bytes = dataBytes(data, maximum.value);
             if (!bytes.ok)
                 return err(custodyError('invalid_data'));
             return this.#invoke('sign', context, async (p, c) => {
                 try {
-                    return await p.sign(this.algorithm, bytes.value, c);
+                    return await p.sign(this.algorithm, bytes.value, c, { maxBytes: CRYPTO_MAX_BYTES_CEILING });
                 }
                 finally {
                     bytes.value.fill(0);
                 }
-            }, (v) => v instanceof Uint8Array &&
-                v.length > 0 &&
-                v.length <= CUSTODY_SIGNATURE_MAX_BYTES);
+            }, (v) => boundedBinary(v, CUSTODY_SIGNATURE_MAX_BYTES) &&
+                binaryByteLength(v) > 0);
         }
         catch {
             return err(custodyError('invalid_data'));
         }
     }
-    async verify(algorithm, signature, data, context) {
+    async verify(algorithm, signature, data, context, options = {}) {
+        const maximum = byteLimit(options);
+        if (!maximum.ok)
+            return err(custodyError('invalid_options'));
         try {
             if (!this.#port)
                 return err(custodyError('key_not_found'));
@@ -109,17 +117,17 @@ class ManagedHandle {
                 return err(custodyError('key_mismatch'));
             if (!this.capabilities.includes('verify'))
                 return err(custodyError('unsupported_operation'));
-            const bytes = dataBytes(data);
+            const bytes = dataBytes(data, maximum.value);
             if (!bytes.ok)
                 return err(custodyError('invalid_data'));
             if (!(signature instanceof Uint8Array))
                 return err(custodyError('invalid_signature'));
-            if (signature.length > CUSTODY_SIGNATURE_MAX_BYTES)
+            if (!boundedBinary(signature, CUSTODY_SIGNATURE_MAX_BYTES))
                 return err(custodyError('limit'));
             const copied = new Uint8Array(signature);
             return this.#invoke('verify', context, async (p, c) => {
                 try {
-                    return await p.verify(this.algorithm, copied, bytes.value, c);
+                    return await p.verify(this.algorithm, copied, bytes.value, c, { maxBytes: CRYPTO_MAX_BYTES_CEILING });
                 }
                 finally {
                     copied.fill(0);
@@ -138,6 +146,12 @@ class ManagedHandle {
         return this.#invoke('identity', context, (p, c) => p.identity(c), isKeyIdentity);
     }
     async unwrap(algorithm, wrappedKey, context, options = {}) {
+        const opts = snapshotOptions(options, ['length']);
+        if (!opts.ok ||
+            (Object.hasOwn(opts.value, 'length') &&
+                opts.value.length !== 128 &&
+                opts.value.length !== 256))
+            return err(custodyError('invalid_options'));
         try {
             if (!this.#port)
                 return err(custodyError('key_not_found'));
@@ -147,16 +161,9 @@ class ManagedHandle {
                 return err(custodyError('key_mismatch'));
             if (!this.capabilities.includes('unwrap'))
                 return err(custodyError('unsupported_operation'));
-            if (!(wrappedKey instanceof Uint8Array) ||
-                wrappedKey.length === 0 ||
-                wrappedKey.length > SIGNATURE_MAX_BYTES)
+            if (!boundedBinary(wrappedKey, SIGNATURE_MAX_BYTES) ||
+                binaryByteLength(wrappedKey) === 0)
                 return err(custodyError('invalid_data'));
-            const opts = snapshotOptions(options, ['length']);
-            if (!opts.ok ||
-                (Object.hasOwn(opts.value, 'length') &&
-                    opts.value.length !== 128 &&
-                    opts.value.length !== 256))
-                return err(custodyError('invalid_options'));
             const copied = new Uint8Array(wrappedKey);
             return this.#invoke('unwrap', context, async (p, c) => {
                 try {
@@ -196,8 +203,8 @@ class ManagedHandle {
     [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.toJSON();
     }
-    [Symbol.for('Deno.customInspect')]() {
-        return this.toJSON();
+    [Symbol.for('Deno.customInspect')](render) {
+        return denoInspection(render, this.toJSON());
     }
 }
 /** Wrap trusted custodian code under deadline, result validation, and fault containment. */
@@ -251,6 +258,6 @@ export function createKeyHandle(algorithm, port, capabilities) {
 Object.freeze(ManagedHandle.prototype);
 Object.freeze(ManagedHandle);
 const managedVerify = Function.prototype.call.bind(ManagedHandle.prototype.verify);
-export function verifyHandle(key, algorithm, signature, data, context) {
-    return managedVerify(key, algorithm, signature, data, context);
+export function verifyHandle(key, algorithm, signature, data, context, options = {}) {
+    return managedVerify(key, algorithm, signature, data, context, options);
 }

package/dist/key_identity.d.ts

@@ -2,15 +2,22 @@ import { type Result } from './result.ts';
 import { type PublicKey } from './public_key.ts';
 /** Internal, nonserialized canonical equivalence key for scoped identity merging. */
 export declare function identityClassKey(identity: KeyIdentity): string | undefined;
+/** Check the private brand of a key identity. */
 export declare function isKeyIdentity(value: unknown): value is KeyIdentity;
+/** A branded public, symmetric, or unknown key identity. */
 export declare class KeyIdentity {
     #private;
     readonly kind: 'public' | 'symmetric' | 'unknown';
     private constructor();
+    /** Derive an identity from a branded public key's canonical components. */
     static fromPublic(key: PublicKey): Result<KeyIdentity>;
+    /** Create a symmetric identity from caller-supplied nonsecret bytes. */
     static symmetric(value: unknown): Result<KeyIdentity>;
+    /** Create an identity that cannot establish key equivalence. */
     static unknown(): Result<KeyIdentity>;
+    /** Compare branded key identities using their canonical identity bytes. */
     static same(a: unknown, b: unknown): Result<boolean>;
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON(): Readonly<{
         kind: KeyIdentity['kind'];
     }>;

package/dist/key_identity.js

@@ -1,3 +1,4 @@
+import { denoInspection } from './brand.js';
 import { ok, err } from './result.js';
 import { custodyError } from './errors/types.js';
 import { KEY_IDENTITY_MAX_BYTES } from './constants.js';
@@ -8,9 +9,11 @@ const classKeys = new WeakMap();
 /** Internal, nonserialized canonical equivalence key for scoped identity merging. */
 export function identityClassKey(identity) { return classKeys.get(identity); }
 const token = Object.freeze({});
+/** Check the private brand of a key identity. */
 export function isKeyIdentity(value) {
     return typeof value === 'object' && value !== null && identities.has(value);
 }
+/** A branded public, symmetric, or unknown key identity. */
 export class KeyIdentity {
     kind;
     #bytes;
@@ -24,6 +27,7 @@ export class KeyIdentity {
         identities.add(this);
         Object.freeze(this);
     }
+    /** Derive an identity from a branded public key's canonical components. */
     static fromPublic(key) {
         if (!isPublicKey(key))
             return err(custodyError('invalid_key'));
@@ -32,6 +36,7 @@ export class KeyIdentity {
             ? ok(new KeyIdentity(token, 'public', r.value))
             : err(custodyError('invalid_key'));
     }
+    /** Create a symmetric identity from caller-supplied nonsecret bytes. */
     static symmetric(value) {
         try {
             if ((!(value instanceof Uint8Array) && typeof value !== 'string') ||
@@ -48,9 +53,11 @@ export class KeyIdentity {
             return err(custodyError('invalid_options'));
         }
     }
+    /** Create an identity that cannot establish key equivalence. */
     static unknown() {
         return ok(new KeyIdentity(token, 'unknown'));
     }
+    /** Compare branded key identities using their canonical identity bytes. */
     static same(a, b) {
         if (!isKeyIdentity(a) || !isKeyIdentity(b))
             return err(custodyError('invalid_key'));
@@ -63,14 +70,15 @@ export class KeyIdentity {
             diff |= a.#bytes[i] ^ b.#bytes[i];
         return ok(diff === 0);
     }
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON() {
         return Object.freeze({ kind: this.kind });
     }
     [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.toJSON();
     }
-    [Symbol.for('Deno.customInspect')]() {
-        return this.toJSON();
+    [Symbol.for('Deno.customInspect')](render) {
+        return denoInspection(render, this.toJSON());
     }
 }
 Object.freeze(KeyIdentity.prototype);

package/dist/message/index.d.ts

@@ -1,10 +1,12 @@
 import { type Result } from '../result.ts';
+/** An owned HTTP field occurrence with its section and byte value. */
 export type FieldOccurrence = Readonly<{
     name: string;
     value: Uint8Array;
     section: 'headers' | 'trailers';
     provenance: 'caller' | 'http1' | 'http2' | 'http3';
 }>;
+/** Owned or unavailable body bytes with explicit retention and completeness facts. */
 export type Body = Readonly<{
     state: 'retained' | 'streaming' | 'consumed' | 'unavailable';
     bytes: Uint8Array | null;
@@ -12,11 +14,13 @@ export type Body = Readonly<{
     ownership: 'caller';
     maxBytes: number;
 }>;
+/** Branded TLS and peer-certificate facts captured by an adapter. */
 export type TransportFacts = Readonly<{
     httpVersion: 'unknown' | 'http1_0' | 'http1_1' | 'http2' | 'http3';
     tls: 'unknown' | 'plain' | 'tls';
     evidence: 'declared';
 }>;
+/** A branded HTTP request or response preserving target and field bytes. */
 export type Message = Readonly<{
     kind: 'request' | 'response';
     method: string | null;
@@ -31,30 +35,50 @@ export type Message = Readonly<{
     relatedRequest: Message | null;
     transport: TransportFacts;
 }>;
+/** Check the private brand of an HTTP message. */
 export declare function isMessage(value: unknown): value is Message;
+/** Check the private brand of a field occurrence. */
 export declare function isFieldOccurrence(value: unknown): value is FieldOccurrence;
+/** Check the private brand of a body snapshot. */
 export declare function isBody(value: unknown): value is Body;
+/** Check the private brand of captured transport facts. */
 export declare function isTransportFacts(value: unknown): value is TransportFacts;
 export declare function token(value: unknown, max?: number): value is string;
 export declare function uriBytes(s: string): boolean;
 export declare function authority(value: unknown, requirePort?: boolean): value is string;
+/** Field occurrence construction and validation. */
 export declare const FieldOccurrence: Readonly<{
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a: unknown) => Result<FieldOccurrence>;
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a: unknown) => Result<FieldOccurrence>;
 }>;
+/** Body snapshot construction and validation. */
 export declare const Body: Readonly<{
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a: unknown) => Result<Body>;
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a: unknown) => Result<Body>;
 }>;
+/** Transport snapshot construction and validation. */
 export declare const TransportFacts: Readonly<{
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a: unknown) => Result<TransportFacts>;
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a: unknown) => Result<TransportFacts>;
 }>;
+/** Validate and brand a lossless HTTP message snapshot. */
 export declare function createMessage(a: unknown): Result<Message>;
+/** Validate a message snapshot through the same constructor boundary. */
 export declare const validateMessage: typeof createMessage;
+/** Lossless HTTP message construction and validation. */
 export declare const Message: Readonly<{
+    /** Validate and brand the supplied HTTP snapshot. */
     create: typeof createMessage;
+    /** Validate the snapshot using the same boundary as construction. */
     validate: typeof createMessage;
+    /** Build a branded HTTP request with owned field and body bytes. */
     request: (method: unknown, target: unknown, fields: unknown, bytes: unknown, options?: unknown) => Promise<Result<Message>>;
+    /** Build a branded HTTP response with owned field and body bytes. */
     response: (status: unknown, fields: unknown, bytes: unknown, options?: unknown) => Promise<Result<Message>>;
 }>;