@request-seal/core 0.1.0 → 0.3.0

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,29 @@ export function innerCompact(input) {
     const framed = compact(input, 3, false);
     return !framed.ok && framed.error.reason === 'invalid_serialization' ? err(joseError('nesting_depth', 'nesting')) : framed;
 }
+// RFC 7515 Section 4.1.10: a cty value with no "/" is read with "application/"
+// prepended. The recursion-implying set is the registered JOSE media types
+// (Section 9.2.1: application/jose and application/jose+json), their
+// per-structure spellings application/jws and application/jwe, and RFC 7519's
+// application/jwt (abbreviated "JWT"): each declares the payload is another
+// JOSE envelope, which this one-level module refuses. Any other cty names
+// ordinary typed payload content and is the application's business.
+function nestingCty(cty) {
+    if (typeof cty !== "string")
+        return false;
+    // Media-type parameters do not change the type/subtype classification, so
+    // strip them before the abbreviation rule.
+    const base = cty.split(";", 1)[0].trim();
+    const expanded = base.includes("/") ? base : `application/${base}`;
+    return [
+        "application/jose",
+        "application/jose+json",
+        "application/jws",
+        "application/jwe",
+        "application/jwt",
+    ].includes(expanded.toLowerCase());
+}
+/** 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"]);
@@ -42,7 +66,7 @@ export async function decrypt(input, policy, options) {
             const inner = await JWS.verify(plaintext, p.jws, stageOptions);
             if (!inner.ok)
                 return inner;
-            need(!inner.value.header.some((pair) => pair[0] === "cty"), "nesting_depth", "nesting");
+            need(!nestingCty(headerValue(inner.value.header, "cty")), "nesting_depth", "nesting");
             const result = Object.freeze({ jwe: outer.value, jws: inner.value });
             branded.add(result);
             return ok(result);
@@ -52,4 +76,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>>;
 }>;

package/dist/message/index.js

@@ -1,4 +1,5 @@
 import { byteString, encodeBase64 } from '../bytes.js';
+import { digest as capturedDigest } from '../crypto/subtle.js';
 import { snapshotOptions } from '../brand.js';
 import { BODY_MAX_BYTES, MESSAGE_MAX_TARGET_BYTES, MESSAGE_MAX_FIELD_BYTES, MESSAGE_MAX_FIELDS_BYTES, MESSAGE_MAX_OCCURRENCES, MESSAGE_MAX_TOKEN_BYTES, MESSAGE_MAX_SCHEME_BYTES, MESSAGE_MAX_AUTHORITY_BYTES, MESSAGE_MAX_URL_BYTES, } from '../constants.js';
 import { messageError, isRequestSealError } from '../errors/types.js';
@@ -7,15 +8,19 @@ const messages = new WeakSet();
 const fieldOccurrences = new WeakSet();
 const bodies = new WeakSet();
 const transportFacts = new WeakSet();
+/** Check the private brand of an HTTP message. */
 export function isMessage(value) {
     return typeof value === 'object' && value !== null && messages.has(value);
 }
+/** Check the private brand of a field occurrence. */
 export function isFieldOccurrence(value) {
     return typeof value === 'object' && value !== null && fieldOccurrences.has(value);
 }
+/** Check the private brand of a body snapshot. */
 export function isBody(value) {
     return typeof value === 'object' && value !== null && bodies.has(value);
 }
+/** Check the private brand of captured transport facts. */
 export function isTransportFacts(value) {
     return typeof value === 'object' && value !== null && transportFacts.has(value);
 }
@@ -265,21 +270,32 @@ function message(input, related = false) {
         relatedRequest: request,
     }, messages);
 }
+/** Field occurrence construction and validation. */
 export const FieldOccurrence = Object.freeze({
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a) => protect(() => field(a), 'invalid_field'),
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a) => protect(() => field(a), 'invalid_field'),
 });
+/** Body snapshot construction and validation. */
 export const Body = Object.freeze({
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a) => protect(() => body(a), 'invalid_body'),
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a) => protect(() => body(a), 'invalid_body'),
 });
+/** Transport snapshot construction and validation. */
 export const TransportFacts = Object.freeze({
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a) => protect(() => transport(a), 'invalid_transport'),
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a) => protect(() => transport(a), 'invalid_transport'),
 });
+/** Validate and brand a lossless HTTP message snapshot. */
 export function createMessage(a) {
     return protect(() => message(a), 'invalid_message');
 }
+/** Validate a message snapshot through the same constructor boundary. */
 export const validateMessage = createMessage;
 async function builder(kind, first, target, headers, bytes, options) {
     try {
@@ -314,7 +330,7 @@ async function builder(kind, first, target, headers, bytes, options) {
             const digests = [];
             for (const alg of algorithms) {
                 try {
-                    const hash = await crypto.subtle.digest(alg === 'sha-256' ? 'SHA-256' : 'SHA-512', new Uint8Array(content.bytes));
+                    const hash = await capturedDigest(alg === 'sha-256' ? 'SHA-256' : 'SHA-512', new Uint8Array(content.bytes));
                     digests.push(alg + '=:' + encodeBase64(new Uint8Array(hash)) + ':');
                 }
                 catch {
@@ -347,9 +363,14 @@ async function builder(kind, first, target, headers, bytes, options) {
             : messageError('invalid_message'));
     }
 }
+/** Lossless HTTP message construction and validation. */
 export const Message = Object.freeze({
+    /** Validate and brand the supplied HTTP snapshot. */
     create: createMessage,
+    /** Validate the snapshot using the same boundary as construction. */
     validate: validateMessage,
+    /** Build a branded HTTP request with owned field and body bytes. */
     request: (method, target, fields, bytes, options = {}) => builder('request', method, target, fields, bytes, options),
+    /** Build a branded HTTP response with owned field and body bytes. */
     response: (status, fields, bytes, options = {}) => builder('response', status, null, fields, bytes, options),
 });

package/dist/numbers.d.ts

@@ -1,12 +1,18 @@
 import { type Result } from './result.ts';
+/** Check whether a value is a JavaScript safe integer. */
 export declare const safeInteger: (value: unknown) => value is number;
+/** Validate the Structured Fields integer range and reject negative zero. */
 export declare function structuredInteger(value: unknown): Result<number>;
+/** Validate a Structured Fields date using the integer range. */
 export declare const structuredDate: typeof structuredInteger;
+/** A decimal stored as an integer scaled by one thousand. */
 export type Decimal = Readonly<{
     scaled: number;
     scale: 3;
 }>;
 /** Parse decimal source text without rounding or a floating-point conversion. */
 export declare function parseDecimal(value: unknown): Result<Decimal>;
+/** Validate a nonnegative Unix clock value within the supported range. */
 export declare function clockSeconds(value: unknown): Result<number>;
+/** Validate a positive timeout within the custody time limit. */
 export declare function timeoutMs(value: unknown): Result<number>;

package/dist/numbers.js

@@ -1,10 +1,13 @@
 import { SF_MAX_INTEGER, CLOCK_MAX_SECONDS, TIMEOUT_MAX_MS } from './constants.js';
 import { ok, err } from './result.js';
 import { structuredFieldsError, coreError, custodyError } from './errors/types.js';
+/** Check whether a value is a JavaScript safe integer. */
 export const safeInteger = (value) => typeof value === 'number' && Number.isSafeInteger(value);
+/** Validate the Structured Fields integer range and reject negative zero. */
 export function structuredInteger(value) {
     return safeInteger(value) && !Object.is(value, -0) && Math.abs(value) <= SF_MAX_INTEGER ? ok(value) : err(structuredFieldsError('invalid_value'));
 }
+/** Validate a Structured Fields date using the integer range. */
 export const structuredDate = structuredInteger;
 /** Parse decimal source text without rounding or a floating-point conversion. */
 export function parseDecimal(value) {
@@ -16,9 +19,11 @@ export function parseDecimal(value) {
     const magnitude = Number(match[2]) * 1000 + Number(match[3].padEnd(3, '0'));
     return ok(Object.freeze({ scaled: match[1] === '-' && magnitude !== 0 ? -magnitude : magnitude, scale: 3 }));
 }
+/** Validate a nonnegative Unix clock value within the supported range. */
 export function clockSeconds(value) {
     return safeInteger(value) && value >= 0 && value <= CLOCK_MAX_SECONDS ? ok(value) : err(coreError('invalid_clock', 'freshness'));
 }
+/** Validate a positive timeout within the custody time limit. */
 export function timeoutMs(value) {
     return safeInteger(value) && value >= 1 && value <= TIMEOUT_MAX_MS ? ok(value) : err(custodyError('invalid_options'));
 }

package/dist/policy.d.ts

@@ -6,36 +6,45 @@ import type { KeyIdentity } from "./key_identity.ts";
 import type { KeyHandle } from "./key_handle.ts";
 import type { PublicKey } from "./public_key.ts";
 import type { ReplayStore, ReplayFacts } from "./replay-port.ts";
+/** A caller-owned signature verification callback receiving a bounded context. */
 export type Verifier = (algorithm: SigningAlgorithm, base: Uint8Array, signature: Uint8Array, context: Context) => Result<boolean> | Promise<Result<boolean>>;
+/** A resolved algorithm and key or verification capability with optional identity. */
 export type ResolvedKey = Readonly<{
     algorithm: SigningAlgorithm;
     key?: PublicKey | KeyHandle | Verifier;
     verify?: Verifier;
     identity?: KeyIdentity;
 }>;
+/** Resolve a verification key from signature facts and an operation context. */
 export type KeyResolver = (facts: Readonly<{
     keyid: string | null;
     label: string;
     tag: string | null;
 }>, context: Context) => Result<ResolvedKey | null> | Promise<Result<ResolvedKey | null>>;
+/** Clock, age, skew, and expiration rules for signature freshness. */
 export type Freshness = Readonly<{
+    /** Return the current Unix time in seconds. */
     clock: () => number;
     maxAge: number | null;
     skew: number;
     requireExpires: boolean;
 }>;
+/** Digest algorithms and field section required for content verification. */
 export type ContentPolicy = Readonly<{
     kind: "content" | "representation";
     algorithms: readonly string[];
     section: "headers" | "trailers";
 }>;
+/** Nonce namespace, commitment, atomic store, and timeout rules. */
 export type ReplayPolicy = Readonly<{
     identifier: "nonce";
     namespace: Uint8Array;
+    /** Derive caller-owned replay commitment bytes from verified facts. */
     commitment: (facts: ReplayFacts, context: Context) => Result<Uint8Array> | Promise<Result<Uint8Array>>;
     store: ReplayStore;
     timeoutMs: number;
 }>;
+/** A branded verification policy with explicit key, freshness, content, and replay rules. */
 export type Policy = Readonly<{
     algorithms: readonly SigningAlgorithm[];
     components: InnerList;
@@ -48,8 +57,26 @@ export type Policy = Readonly<{
     maxSignatures: number;
 }>;
 export declare function fieldSchemas(input: unknown): Result<Readonly<Record<string, Schema>>>;
+/** Check the private brand of a verification policy. */
 export declare function isPolicy(value: unknown): value is Policy;
+/** Internal shared freshness boundary for policies and extension preflight. */
+export declare function normalizeFreshness(input: unknown): Freshness | "not_evaluated";
+/** Snapshot, validate, and brand an explicit verification policy. */
 export declare function createPolicy(input: unknown): Result<Policy>;
+/** Verification policy construction. */
 export declare const Policy: Readonly<{
+    /**
+     * Snapshot, validate, and brand an explicit verification policy.
+     *
+     * Six choices are required and none is defaulted: `algorithms`, `components`,
+     * `keyResolver`, `freshness`, `content`, and `replay`. Optional members are
+     * `extraComponents` (`"allow"` or `"reject"`), `maxSignatures` (1 through 64, default 16),
+     * and `fieldSchemas`.
+     *
+     * @returns `ok(policy)`, or `core` `input.invalid_policy` when any choice is missing,
+     *   unknown, or malformed.
+     * @see [Signing and verifying guide](https://github.com/baselabs/request-seal-typescript/blob/main/docs/guides/signing-and-verifying.md#verify) and
+     *   [reference](https://github.com/baselabs/request-seal-typescript/blob/main/docs/reference/sign-and-verify.md).
+     */
     create: typeof createPolicy;
 }>;