@request-seal/core 0.1.0 → 0.3.0

package/dist/replay/claim.d.ts

@@ -4,7 +4,9 @@ export declare function validSeconds(value: unknown): value is number;
 /** Exact signed-64-bit lower bound; bigint preserves ends outside safe numbers. */
 export declare function validRetention(value: unknown): value is number | bigint;
 export declare function boundedReplayBytes(v: unknown): v is Uint8Array;
+/** Check the private brand of an atomic replay claim. */
 export declare function isReplayClaim(value: unknown): value is ReplayClaim;
+/** Copy, validate, and brand a replay claim. */
 export declare function createClaim(input: unknown): Result<ReplayClaim>;
 /** Exclusive expiration, inclusive max age. Authenticate the window before deriving retention. */
 export declare function retentionEnd(input: unknown): Result<number>;
@@ -13,7 +15,10 @@ export declare function retainUntil(input: unknown): Result<number>;
 /** Injective byte encoding, also suitable for PostgreSQL decode($n,'hex'). */
 export declare function hex(bytes: Uint8Array): string;
 export declare function claimRow(input: unknown): Result<readonly [string, string, string]>;
+/** Replay-claim construction and private-brand validation. */
 export declare const Claim: Readonly<{
+    /** Copy, validate, and brand an atomic replay claim. */
     create: typeof createClaim;
+    /** Check the private brand of a replay claim. */
     valid: typeof isReplayClaim;
 }>;

package/dist/replay/claim.js

@@ -22,9 +22,11 @@ export function boundedReplayBytes(v) {
     return length >= 1 && length <= KEY_IDENTITY_MAX_BYTES;
 }
 ;
+/** Check the private brand of an atomic replay claim. */
 export function isReplayClaim(value) {
     return typeof value === 'object' && value !== null && claims.has(value);
 }
+/** Copy, validate, and brand a replay claim. */
 export function createClaim(input) {
     try {
         const r = snapshotOptions(input, ['namespace', 'key', 'retainUntil']);
@@ -68,4 +70,10 @@ export function claimRow(input) {
         return err(replayError('invalid_claim'));
     return ok(Object.freeze([hex(input.namespace), hex(input.key), input.retainUntil.toString()]));
 }
-export const Claim = Object.freeze({ create: createClaim, valid: isReplayClaim });
+/** Replay-claim construction and private-brand validation. */
+export const Claim = Object.freeze({
+    /** Copy, validate, and brand an atomic replay claim. */
+    create: createClaim,
+    /** Check the private brand of a replay claim. */
+    valid: isReplayClaim
+});

package/dist/replay/index.d.ts

@@ -3,10 +3,16 @@ import { retainUntil, claimRow } from './claim.ts';
 export { Claim, createClaim, isReplayClaim } from './claim.ts';
 export { isReplayReceipt } from './receipt.ts';
 export { createReplayStore, isReplayStore } from './store.ts';
+/** Atomic claim, expiration sweep, and retention helper operations. */
 export declare const Replay: Readonly<{
+    /** Atomically reserve the claim or report that it was already claimed. */
     claim: typeof claim;
+    /** Remove expired replay claims and return the removal count. */
     sweep: typeof sweep;
+    /** Compute the retention deadline from validated freshness facts. */
     retainUntil: typeof retainUntil;
+    /** Encode a branded claim as namespace, key, and retention database values. */
     row: typeof claimRow;
+    /** Validate and brand a caller-owned atomic replay store. */
     store: typeof createReplayStore;
 }>;

package/dist/replay/index.js

@@ -3,4 +3,16 @@ import { retainUntil, claimRow } from './claim.js';
 export { Claim, createClaim, isReplayClaim } from './claim.js';
 export { isReplayReceipt } from './receipt.js';
 export { createReplayStore, isReplayStore } from './store.js';
-export const Replay = Object.freeze({ claim, sweep, retainUntil, row: claimRow, store: createReplayStore });
+/** Atomic claim, expiration sweep, and retention helper operations. */
+export const Replay = Object.freeze({
+    /** Atomically reserve the claim or report that it was already claimed. */
+    claim,
+    /** Remove expired replay claims and return the removal count. */
+    sweep,
+    /** Compute the retention deadline from validated freshness facts. */
+    retainUntil,
+    /** Encode a branded claim as namespace, key, and retention database values. */
+    row: claimRow,
+    /** Validate and brand a caller-owned atomic replay store. */
+    store: createReplayStore
+});

package/dist/replay/postgres.d.ts

@@ -5,6 +5,9 @@ export type Query = (sql: string, params: readonly string[], context: Readonly<{
     signal: AbortSignal;
     remainingMs: number;
 }>) => Promise<number>;
+/** Validate a table name and return replay-store creation SQL. */
 export declare function ddl(table: unknown): Result<string>;
+/** Validate a table name and return the retention-sweep index SQL: without it the sweep's DELETE is a growing full-table scan. The name is bounded to 46 bytes so the derived index identifier fits PostgreSQL's 63-byte limit. */
+export declare function ddlIndex(table: unknown): Result<string>;
 /** No database, pool, transaction, or timer starts here. Late commits remain indeterminate. */
 export declare function createStore(options: unknown): Result<ReplayStore>;

package/dist/replay/postgres.js

@@ -5,9 +5,16 @@ import { ok, err } from '../result.js';
 import { claimRow, isReplayClaim, validSeconds } from './claim.js';
 import { createReplayStore, storeOperation } from './store.js';
 const tableName = (value) => typeof value === 'string' && value.length >= 1 && value.length <= 63 && /^[a-z][a-z0-9_]*$/.test(value);
+/** Validate a table name and return replay-store creation SQL. */
 export function ddl(table) {
     return tableName(table) ? ok(`CREATE TABLE "${table}" (namespace bytea NOT NULL, key bytea NOT NULL, retain_until bigint NOT NULL, PRIMARY KEY (namespace, key))`) : err(replayError('invalid_store'));
 }
+/** Validate a table name and return the retention-sweep index SQL: without it the sweep's DELETE is a growing full-table scan. The name is bounded to 46 bytes so the derived index identifier fits PostgreSQL's 63-byte limit. */
+export function ddlIndex(table) {
+    return tableName(table) && table.length <= 46
+        ? ok(`CREATE INDEX "${table}_retain_until_idx" ON "${table}" (retain_until)`)
+        : err(replayError('invalid_store'));
+}
 function failure(error) {
     try {
         if (error !== null && typeof error === 'object') {

package/dist/replay/receipt.d.ts

@@ -1,4 +1,5 @@
 import { type Result } from '../result.ts';
 import type { ReplayReceipt } from '../replay-port.ts';
+/** Check the private brand of a successful replay receipt. */
 export declare function isReplayReceipt(value: unknown): value is ReplayReceipt;
 export declare function createReceipt(input: unknown): Result<ReplayReceipt>;

package/dist/replay/receipt.js

@@ -4,6 +4,7 @@ import { ok, err } from '../result.js';
 import { validRetention } from './claim.js';
 // Verification produces safe-number ends; share the claim bounds for those ends.
 const receipts = new WeakSet();
+/** Check the private brand of a successful replay receipt. */
 export function isReplayReceipt(value) {
     return typeof value === 'object' && value !== null && receipts.has(value);
 }

package/dist/replay/store.d.ts

@@ -1,6 +1,7 @@
 import { type Context } from '../context.ts';
 import { type Result } from '../result.ts';
 import type { ReplayStore } from '../replay-port.ts';
+/** Check the private brand of a replay store. */
 export declare function isReplayStore(value: unknown): value is ReplayStore;
 /** Normalize caller ports once, binding own methods to the caller's receiver. */
 export declare function createReplayStore(input: unknown): Result<ReplayStore>;

package/dist/replay/store.js

@@ -4,6 +4,7 @@ import { isRequestSealError, replayError } from '../errors/types.js';
 import { ok, err } from '../result.js';
 import { isReplayClaim, validSeconds } from './claim.js';
 const stores = new WeakSet();
+/** Check the private brand of a replay store. */
 export function isReplayStore(value) {
     return typeof value === 'object' && value !== null && stores.has(value);
 }

package/dist/replay-port.d.ts

@@ -8,16 +8,21 @@ export type ReplayClaim = Readonly<{
 }>;
 /** Bounded callback vocabulary; normalized by Replay.claim and Replay.sweep. */
 export type ReplayStoreFailure = "unavailable" | "timeout" | "full" | "failure";
+/** A store result with branded errors or the bounded callback failure vocabulary. */
 export type ReplayStoreResult<T> = Result<T> | Readonly<{
     ok: false;
     error: ReplayStoreFailure;
 }>;
+/** A caller-owned atomic claim and expiration-sweep port. */
 export type ReplayStore = Readonly<{
     /** Public adapter identity; unnamed caller implementations use "caller". */
     identity?: string;
+    /** Atomically reserve the claim or report that it was already claimed. */
     claim: (claim: ReplayClaim, context: Context) => ReplayStoreResult<"claimed" | "already_claimed"> | Promise<ReplayStoreResult<"claimed" | "already_claimed">>;
+    /** Remove expired replay claims and return the removal count. */
     sweep: (now: number, context: Context) => ReplayStoreResult<number> | Promise<ReplayStoreResult<number>>;
 }>;
+/** Verified signature and profile facts supplied to a replay commitment callback. */
 export type ReplayFacts = Readonly<{
     identifier: string;
     algorithm: import("./crypto/algorithm.ts").SigningAlgorithm;
@@ -27,7 +32,7 @@ export type ReplayFacts = Readonly<{
     expires: number | null;
     profile: Readonly<{
         name: "rfc9421";
-    }>;
+    }> | import("./profile.ts").ProfileStamp;
 }>;
 /** Successful atomic claim; contains only public adapter identity and retention. */
 export type ReplayReceipt = Readonly<{

package/dist/result.d.ts

@@ -1,4 +1,5 @@
 import { type RequestSealError } from './errors/types.ts';
+/** A success value or a branded, bounded error. */
 export type Result<T> = {
     readonly ok: true;
     readonly value: T;
@@ -6,5 +7,7 @@ export type Result<T> = {
     readonly ok: false;
     readonly error: RequestSealError;
 };
+/** Freeze a successful result containing the supplied value. */
 export declare const ok: <T>(value: T) => Result<T>;
+/** Freeze a failed result after checking its error brand. */
 export declare const err: <T = never>(error: RequestSealError) => Result<T>;

package/dist/result.js

@@ -1,5 +1,7 @@
 import { isRequestSealError } from './errors/types.js';
+/** Freeze a successful result containing the supplied value. */
 export const ok = (value) => Object.freeze({ ok: true, value });
+/** Freeze a failed result after checking its error brand. */
 export const err = (error) => {
     if (!isRequestSealError(error))
         throw new TypeError('Unbranded Result error');

package/dist/sign.d.ts

@@ -3,12 +3,15 @@ import { type SigningAlgorithm } from "./crypto/algorithm.ts";
 import { type Message as HttpMessage } from "./message/index.ts";
 import { type InnerList } from "./structured-fields/index.ts";
 import { type Result } from "./result.ts";
+/** A caller-owned signing callback receiving the algorithm, base bytes, and context. */
 export type Signer = (algorithm: SigningAlgorithm, base: Uint8Array, context: Context) => Result<Uint8Array> | Promise<Result<Uint8Array>>;
+/** A label, signature-input value, and signing algorithm. */
 export type SignatureSpec = Readonly<{
     label: string;
     signatureInput: string | Uint8Array | InnerList;
     algorithm: SigningAlgorithm;
 }>;
+/** Explicit freshness, key identifier, nonce, and tag parameters for signing. */
 export type SigningParameters = Readonly<{
     created?: boolean;
     expiresIn: number | null;
@@ -17,6 +20,7 @@ export type SigningParameters = Readonly<{
     keyid?: string | null;
     tag?: string | null;
 }>;
+/** Components, algorithm, and optional digest and freshness settings for signing. */
 export type SigningSpec = Readonly<{
     label: string;
     components: string;
@@ -31,4 +35,26 @@ export type SigningSpec = Readonly<{
     digest?: readonly string[] | null;
     fieldSchemas?: unknown;
 }>;
+/**
+ * Sign a lossless HTTP message with explicit components and caller-owned custody.
+ *
+ * Appends one `Signature-Input` and one `Signature` field occurrence and returns a new
+ * branded Message. The input message is never modified, and existing signatures stay.
+ *
+ * @param message - A branded Message from `Message.request`, `Message.response`, or `Message.create`.
+ * @param spec - A generated spec with `label`, `components`, `algorithm`, and `expiresIn`, plus
+ *   optional `created`, `nonce`, `alg`, `keyid`, `tag` (or the same choices nested under
+ *   `parameters`), `digest`, and `fieldSchemas`; or an exact-input spec with only `label`,
+ *   `signatureInput`, and `algorithm`.
+ * @param signer - A KeyHandle for the same algorithm, or a {@link Signer} callback.
+ * @param options - Generated specs accept `clock`, `nonce`, `signingTimeout`, and `context`;
+ *   exact-input specs accept `fieldSchemas`, `signingTimeout`, and `context`. `signingTimeout`
+ *   is 1 through 300,000 milliseconds (default 5,000).
+ * @returns `ok(message)`, or a `core` error such as `input.invalid_options`,
+ *   `fields.label_in_use`, `input.signer_algorithm_mismatch`, `crypto.signing_failed`, or
+ *   `crypto.signer_failed`.
+ * @see [Signing and verifying guide](https://github.com/baselabs/request-seal-typescript/blob/main/docs/guides/signing-and-verifying.md),
+ *   [reference](https://github.com/baselabs/request-seal-typescript/blob/main/docs/reference/sign-and-verify.md), and the
+ *   [error reasons](https://github.com/baselabs/request-seal-typescript/blob/main/docs/reference/errors.md).
+ */
 export declare function sign(message: unknown, spec: unknown, signer: unknown, options?: unknown): Promise<Result<HttpMessage>>;

package/dist/sign.js

@@ -11,7 +11,7 @@ import { build } from "./signature-base/index.js";
 import { serialize, } from "./structured-fields/index.js";
 import { checkDigest, digest } from "./digest.js";
 import { fieldSchemas } from "./policy.js";
-import { inner, label, dictionaries, signatureSchema, parameters, fail, ensure, bounded, } from "./signature-fields.js";
+import { inner, label, dictionaries, signatureSchema, parameters, fail, ensure, bounded, envelope, } from "./signature-fields.js";
 import { coreError, isRequestSealError } from "./errors/types.js";
 import { timeoutMs } from "./numbers.js";
 import { ok, err } from "./result.js";
@@ -36,6 +36,28 @@ function append(m, name, bytes) {
         result(FieldOccurrence.create({ name, value: bytes, section: "headers" })),
     ]);
 }
+/**
+ * Sign a lossless HTTP message with explicit components and caller-owned custody.
+ *
+ * Appends one `Signature-Input` and one `Signature` field occurrence and returns a new
+ * branded Message. The input message is never modified, and existing signatures stay.
+ *
+ * @param message - A branded Message from `Message.request`, `Message.response`, or `Message.create`.
+ * @param spec - A generated spec with `label`, `components`, `algorithm`, and `expiresIn`, plus
+ *   optional `created`, `nonce`, `alg`, `keyid`, `tag` (or the same choices nested under
+ *   `parameters`), `digest`, and `fieldSchemas`; or an exact-input spec with only `label`,
+ *   `signatureInput`, and `algorithm`.
+ * @param signer - A KeyHandle for the same algorithm, or a {@link Signer} callback.
+ * @param options - Generated specs accept `clock`, `nonce`, `signingTimeout`, and `context`;
+ *   exact-input specs accept `fieldSchemas`, `signingTimeout`, and `context`. `signingTimeout`
+ *   is 1 through 300,000 milliseconds (default 5,000).
+ * @returns `ok(message)`, or a `core` error such as `input.invalid_options`,
+ *   `fields.label_in_use`, `input.signer_algorithm_mismatch`, `crypto.signing_failed`, or
+ *   `crypto.signer_failed`.
+ * @see [Signing and verifying guide](https://github.com/baselabs/request-seal-typescript/blob/main/docs/guides/signing-and-verifying.md),
+ *   [reference](https://github.com/baselabs/request-seal-typescript/blob/main/docs/reference/sign-and-verify.md), and the
+ *   [error reasons](https://github.com/baselabs/request-seal-typescript/blob/main/docs/reference/errors.md).
+ */
 export async function sign(message, spec, signer, options = {}) {
     try {
         const s = take(spec, [
@@ -116,7 +138,7 @@ export async function sign(message, spec, signer, options = {}) {
             }
             input = r.value;
             if (Object.hasOwn(o, "context") || !isKeyHandle(signer)) {
-                c = Object.hasOwn(o, "context") ? (isContext(o.context) ? ok(o.context) : err(bounded(null, "invalid_options", "input"))) : withDeadline({ timeoutMs: 5000 });
+                c = Object.hasOwn(o, "context") ? (isContext(o.context) ? ok(o.context) : err(bounded(null, "invalid_options", "input"))) : withDeadline({ timeoutMs: signingTimeout });
                 ensure(c.ok, "invalid_options", "input");
             }
         }
@@ -308,6 +330,6 @@ export async function sign(message, spec, signer, options = {}) {
     catch (e) {
         if (isRequestSealError(e) && e.kind === "custody" && e.reason === "deadline_exceeded")
             return err(e);
-        return err(bounded(e, "invalid_options", "input"));
+        return err(envelope(e));
     }
 }

package/dist/signature-base/index.d.ts

@@ -1,6 +1,8 @@
 import { type Result } from '../result.ts';
 /** Ordered identifiers and parameters are serialized exactly once for each output line. */
 export declare function build(input: unknown, parameters: unknown, options?: unknown): Result<Uint8Array>;
+/** RFC 9421 signature-base construction operations. */
 export declare const SignatureBase: Readonly<{
+    /** Build RFC 9421 signature-base bytes from a lossless message. */
     build: typeof build;
 }>;

package/dist/signature-base/index.js

@@ -317,4 +317,8 @@ export function build(input, parameters, options = {}) {
             : signatureBaseError('invalid_signature_parameters'));
     }
 }
-export const SignatureBase = Object.freeze({ build });
+/** RFC 9421 signature-base construction operations. */
+export const SignatureBase = Object.freeze({
+    /** Build RFC 9421 signature-base bytes from a lossless message. */
+    build
+});

package/dist/signature-fields.d.ts

@@ -10,11 +10,15 @@ export declare function bounded(e: unknown, reason: Reason<"core">, layer: Layer
     reason: Reason<'core'>;
     layer: Layer<'core'>;
     correlation: string;
-    retryable: false;
+    retryable: boolean;
     detail: CoreDetail | null;
     message: string | null;
     source: import("./errors/types.ts").CustodyError | null;
 }>;
+/** The entry-point fault envelope: verify and sign are total, and an
+ * unexpected fault is a bounded internal error — never an escaping throw —
+ * with the exception class observable in detail. */
+export declare function envelope(e: unknown): import("./errors/types.ts").RequestSealError;
 export declare function label(value: unknown): value is string;
 export declare const signatureSchema: Schema;
 export declare function identities(value: InnerList): string[];

package/dist/signature-fields.js

@@ -1,7 +1,7 @@
 import { parse, parseField, serialize, } from "./structured-fields/index.js";
 import { byteString } from "./bytes.js";
 import { token } from "./message/index.js";
-import { coreError, isRequestSealError, } from "./errors/types.js";
+import { coreError, isRequestSealError, faultClass, } from "./errors/types.js";
 import { ok, err } from "./result.js";
 import { SIGNATURE_MAX_BYTES, SIGNATURE_BASE_MAX_COMPONENTS, MESSAGE_MAX_TOKEN_BYTES, STRUCTURED_FIELDS_LIMITS, } from "./constants.js";
 export function fail(reason, layer, detail = null) {
@@ -16,6 +16,14 @@ export function bounded(e, reason, layer) {
         ? e
         : coreError(reason, layer);
 }
+/** The entry-point fault envelope: verify and sign are total, and an
+ * unexpected fault is a bounded internal error — never an escaping throw —
+ * with the exception class observable in detail. */
+export function envelope(e) {
+    return isRequestSealError(e)
+        ? e
+        : coreError("internal", "internal", faultClass(e));
+}
 export function label(value) {
     return (typeof value === "string" &&
         value.length > 0 &&

package/dist/structured-fields/index.d.ts

@@ -1,5 +1,6 @@
 import { STRUCTURED_FIELDS_LIMITS as CEILINGS } from '../constants.ts';
 import { type Result } from '../result.ts';
+/** A typed Structured Fields bare value. */
 export type Bare = Readonly<{
     kind: 'integer' | 'date';
     value: number;
@@ -21,29 +22,39 @@ export type Bare = Readonly<{
 }>;
 export declare function decimalSource(value: Bare): string | undefined;
 export declare function copyDecimalSource(from: Bare, to: Bare): void;
+/** Ordered Structured Fields parameter names and bare values. */
 export type Parameters = readonly (readonly [string, Bare])[];
+/** A Structured Fields item and its ordered parameters. */
 export type Item = Readonly<{
     kind: 'item';
     value: Bare;
     parameters: Parameters;
 }>;
+/** A Structured Fields inner list and its ordered parameters. */
 export type InnerList = Readonly<{
     kind: 'inner_list';
     value: readonly Item[];
     parameters: Parameters;
 }>;
+/** A Structured Fields item or inner list. */
 export type Member = Item | InnerList;
+/** An ordered Structured Fields list. */
 export type List = Readonly<{
     kind: 'list';
     value: readonly Member[];
 }>;
+/** An ordered Structured Fields dictionary. */
 export type Dictionary = Readonly<{
     kind: 'dictionary';
     value: readonly (readonly [string, Member])[];
 }>;
+/** A branded Structured Fields item, inner list, list, or dictionary. */
 export type Value = Item | InnerList | List | Dictionary;
+/** The supported Structured Fields root kinds. */
 export type FieldType = 'item' | 'list' | 'dictionary';
+/** The supported Structured Fields specification revisions. */
 export type Revision = 'rfc8941' | 'rfc9651';
+/** A branded field schema with revision, combination, and byte policies. */
 export type Schema = Readonly<{
     revision: Revision;
     type: FieldType;
@@ -51,7 +62,9 @@ export type Schema = Readonly<{
     parameterTypes: readonly Bare['kind'][];
     innerLists: boolean;
 }>;
+/** Structured Fields parser ceilings. @inline */
 export type Limits = typeof CEILINGS;
+/** Parser limits, schema selection, and duplicate policies. */
 export type Options = {
     schema: Revision | Schema;
     uniqueKeys?: 'all' | string[];
@@ -61,8 +74,11 @@ export type Options = {
         -readonly [K in keyof Limits]: number;
     }>;
 };
+/** Check the private brand of a Structured Fields value. */
 export declare function isStructuredFieldsValue(value: unknown): value is Value;
+/** Check the private brand of a Structured Fields schema. */
 export declare function isStructuredFieldsSchema(value: unknown): value is Schema;
+/** Validate and brand a Structured Fields schema. */
 export declare function createSchema(input: unknown): Result<Schema>;
 /** A single cursor, bounded container depth, and encounter counts before deduplication. */
 export declare function parse(fieldType: FieldType | unknown, raw: unknown, options?: unknown): Result<Value>;
@@ -70,9 +86,14 @@ export declare function parse(fieldType: FieldType | unknown, raw: unknown, opti
 export declare function serialize(value: unknown, options?: unknown): Result<Uint8Array>;
 /** Select ordered occurrences, combine with comma-space, and parse under explicit policy. */
 export declare function parseField(message: unknown, name: unknown, schema: Schema, section?: 'headers' | 'trailers', options?: unknown): Result<Value>;
+/** Bounded parsing, serialization, and field-schema construction. */
 export declare const StructuredFields: Readonly<{
+    /** Parse and validate the supported wire representation. */
     parse: typeof parse;
+    /** Combine field occurrences according to a branded schema and parse them. */
     parseField: typeof parseField;
+    /** Serialize validated values to their canonical wire representation. */
     serialize: typeof serialize;
+    /** Validate and brand a Structured Fields schema. */
     createSchema: typeof createSchema;
 }>;

package/dist/structured-fields/index.js

@@ -26,9 +26,11 @@ const allTypes = [...baseTypes, 'date', 'display_string'];
 const schemas = new WeakMap();
 const values = new WeakSet();
 const schemaValues = new WeakSet();
+/** Check the private brand of a Structured Fields value. */
 export function isStructuredFieldsValue(value) {
     return typeof value === 'object' && value !== null && values.has(value);
 }
+/** Check the private brand of a Structured Fields schema. */
 export function isStructuredFieldsSchema(value) {
     return typeof value === 'object' && value !== null && schemaValues.has(value);
 }
@@ -39,6 +41,7 @@ function ensure(value, reason) {
     if (!value)
         fail(reason);
 }
+/** Validate and brand a Structured Fields schema. */
 export function createSchema(input) {
     try {
         const s = snapshotOptions(input, [
@@ -655,4 +658,14 @@ export function parseField(message, name, schema, section = 'headers', options =
         return err(error(e, 'invalid_message'));
     }
 }
-export const StructuredFields = Object.freeze({ parse, parseField, serialize, createSchema });
+/** Bounded parsing, serialization, and field-schema construction. */
+export const StructuredFields = Object.freeze({
+    /** Parse and validate the supported wire representation. */
+    parse,
+    /** Combine field occurrences according to a branded schema and parse them. */
+    parseField,
+    /** Serialize validated values to their canonical wire representation. */
+    serialize,
+    /** Validate and brand a Structured Fields schema. */
+    createSchema
+});

package/dist/verification.d.ts

@@ -1,6 +1,7 @@
 import { type Parameters } from "./structured-fields/index.ts";
 import type { DigestFacts } from "./digest.ts";
 import { type Result } from "./result.ts";
+/** The clock, age, skew, and timestamps used in successful freshness validation. */
 export type FreshnessFacts = Readonly<{
     now: number;
     created: number | null;
@@ -8,6 +9,7 @@ export type FreshnessFacts = Readonly<{
     maxAge: number | null;
     skew: number;
 }>;
+/** Branded signature, content, freshness, replay, and principal verification facts. */
 export type Verification = Readonly<{
     label: string;
     signature: Readonly<{
@@ -19,15 +21,17 @@ export type Verification = Readonly<{
     }>;
     profile: Readonly<{
         name: "rfc9421";
-    }> | import("./web-bot-auth/verification.ts").WebBotAuthProfile;
+    }> | import("./web-bot-auth/verification.ts").WebBotAuthProfile | import("./profile.ts").ProfileStamp;
     content: "not_required" | DigestFacts;
     freshness: "not_evaluated" | FreshnessFacts;
     replay: "not_required" | import("./replay-port.ts").ReplayReceipt;
     principal: "unattributed" | import("./web-bot-auth/verification.ts").AgentPrincipal | import("./web-bot-auth/verification.ts").HeldPrincipal;
     authorization: "not_evaluated";
 }>;
+/** Check the private brand of a single-signature verification result. */
 export declare function isVerification(value: unknown): value is Verification;
 export declare function completed(value: Verification): Result<Verification>;
 /** Ordered language-neutral facts; cryptographic material is never serialized. */
 export declare function verificationFacts(value: unknown): Result<unknown>;
+/** Encode the canonical public verification facts as JSON bytes. */
 export declare function serializeVerification(value: unknown): Result<Uint8Array>;

package/dist/verification.js

@@ -1,12 +1,13 @@
 import { isWebBotAuthVerification, webBotAuthFacts } from './web-bot-auth/verification.js';
 import { isQuorumVerification, quorumFacts } from './quorum/verification.js';
-import { deepFreeze } from "./brand.js";
-import { byteString } from "./bytes.js";
+import { deepFreeze, inspection } from "./brand.js";
+import { encodeUtf8 } from "./runtime.js";
 import { decimalSource, copyDecimalSource } from "./structured-fields/index.js";
 import { isReplayReceipt } from "./replay/receipt.js";
 import { coreError } from "./errors/types.js";
 import { ok, err } from "./result.js";
 const verifications = new WeakSet();
+/** Check the private brand of a single-signature verification result. */
 export function isVerification(value) {
     return (typeof value === "object" && value !== null && verifications.has(value));
 }
@@ -60,8 +61,7 @@ export function completed(value) {
     });
     Object.defineProperties(result, {
         toJSON: { value: inspect },
-        [Symbol.for("nodejs.util.inspect.custom")]: { value: inspect },
-        [Symbol.for("Deno.customInspect")]: { value: inspect },
+        ...inspection(inspect),
     });
     Object.freeze(result);
     verifications.add(result);
@@ -124,7 +124,9 @@ export function verificationFacts(value) {
             keyid: value.signature.keyid,
             crypto: "valid",
         },
-        profile: value.profile,
+        profile: Array.isArray(value.profile.name)
+            ? Object.fromEntries(Object.entries(value.profile).map(([k, v]) => [k, typeof v === "boolean" ? String(v) : v === null ? "" : v]))
+            : value.profile,
         content: value.content === "not_required"
             ? "not_required"
             : { ...value.content, bytes: number(value.content.bytes) },
@@ -134,6 +136,7 @@ export function verificationFacts(value) {
         authorization: value.authorization,
     });
 }
+/** Encode the canonical public verification facts as JSON bytes. */
 export function serializeVerification(value) {
     const r = verificationFacts(value);
     if (!r.ok)
@@ -147,6 +150,6 @@ export function serializeVerification(value) {
             : v && typeof v === "object"
                 ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, encode(x)]))
                 : v;
-    return byteString(JSON.stringify(encode(r.value)));
+    return ok(encodeUtf8(JSON.stringify(encode(r.value))));
 }
 import { encodeBase64Url as base64url } from "./bytes.js";

package/dist/verify-quorum.d.ts

@@ -1,3 +1,4 @@
 import { type QuorumVerification } from "./quorum/verification.ts";
 import { type Result } from "./result.ts";
+/** Verify bounded HTTP signatures and evaluate the configured quorum policy. */
 export declare function verifyQuorum(message: unknown, quorum: unknown, options: unknown): Promise<Result<QuorumVerification>>;