@request-seal/core 0.2.0 → 0.4.0

package/dist/errors/parity.d.ts

@@ -1,5 +1,5 @@
 /** The immutable reference release used for the error vocabulary. */
-export declare const ELIXIR_ERROR_PIN = "0a6568aa246326617f760e94e21b359285c6ddfc";
+export declare const ELIXIR_ERROR_PIN = "53b6690ccd5036d58b280d08cf0cacc6427262fe";
 declare const retryableRules: {
     readonly core: {
         readonly actor_unbound: {
@@ -38,6 +38,10 @@ declare const retryableRules: {
             readonly kind: "constant";
             readonly value: false;
         };
+        readonly deadline: {
+            readonly kind: "constant";
+            readonly value: true;
+        };
         readonly digest_mismatch: {
             readonly kind: "constant";
             readonly value: false;
@@ -66,6 +70,10 @@ declare const retryableRules: {
             readonly kind: "constant";
             readonly value: false;
         };
+        readonly internal: {
+            readonly kind: "constant";
+            readonly value: false;
+        };
         readonly invalid_accept_signature: {
             readonly kind: "constant";
             readonly value: false;
@@ -644,6 +652,10 @@ declare const retryableRules: {
             readonly kind: "constant";
             readonly value: false;
         };
+        readonly domain_not_found: {
+            readonly kind: "constant";
+            readonly value: false;
+        };
         readonly invalid_key_set: {
             readonly kind: "constant";
             readonly value: false;
@@ -674,7 +686,7 @@ declare const retryableRules: {
         };
         readonly resolution_failed: {
             readonly kind: "constant";
-            readonly value: false;
+            readonly value: true;
         };
         readonly revoked_key: {
             readonly kind: "constant";
@@ -701,7 +713,7 @@ declare const retryableRules: {
             readonly minimum: 500;
             readonly maximum: 599;
             readonly path: "lib/request_seal/discovery.ex";
-            readonly line: 301;
+            readonly line: 517;
         };
         readonly unknown_key: {
             readonly kind: "constant";
@@ -1119,6 +1131,11 @@ export declare const ERROR_PARITY: readonly Readonly<{
     readonly layer: "input";
     readonly reason: "unsupported_component";
     readonly rule_id: "core/input.unsupported_component";
+} | {
+    readonly kind: "core";
+    readonly layer: "internal";
+    readonly reason: "internal";
+    readonly rule_id: "core/internal.internal";
 } | {
     readonly kind: "core";
     readonly layer: "key";
@@ -1204,6 +1221,11 @@ export declare const ERROR_PARITY: readonly Readonly<{
     readonly layer: "quorum";
     readonly reason: "binding_unsatisfied";
     readonly rule_id: "core/quorum.binding_unsatisfied";
+} | {
+    readonly kind: "core";
+    readonly layer: "quorum";
+    readonly reason: "deadline";
+    readonly rule_id: "core/quorum.deadline";
 } | {
     readonly kind: "core";
     readonly layer: "quorum";
@@ -1614,6 +1636,10 @@ export declare const ERROR_PARITY: readonly Readonly<{
     readonly kind: "discovery";
     readonly reason: "directory_unsigned";
     readonly rule_id: "discovery/directory_unsigned";
+} | {
+    readonly kind: "discovery";
+    readonly reason: "domain_not_found";
+    readonly rule_id: "discovery/domain_not_found";
 } | {
     readonly kind: "discovery";
     readonly reason: "invalid_key_set";

package/dist/errors/parity.js

@@ -1,6 +1,6 @@
 // Derived from pinned Elixir constructors and call sites; regenerate with scripts/generate-parity.ts or scripts/render-parity.ts --update-table.
 /** The immutable reference release used for the error vocabulary. */
-export const ELIXIR_ERROR_PIN = '0a6568aa246326617f760e94e21b359285c6ddfc';
+export const ELIXIR_ERROR_PIN = '53b6690ccd5036d58b280d08cf0cacc6427262fe';
 const entries = [
     {
         "kind": "core",
@@ -254,6 +254,12 @@ const entries = [
         "reason": "unsupported_component",
         "rule_id": "core/input.unsupported_component"
     },
+    {
+        "kind": "core",
+        "layer": "internal",
+        "reason": "internal",
+        "rule_id": "core/internal.internal"
+    },
     {
         "kind": "core",
         "layer": "key",
@@ -356,6 +362,12 @@ const entries = [
         "reason": "binding_unsatisfied",
         "rule_id": "core/quorum.binding_unsatisfied"
     },
+    {
+        "kind": "core",
+        "layer": "quorum",
+        "reason": "deadline",
+        "rule_id": "core/quorum.deadline"
+    },
     {
         "kind": "core",
         "layer": "quorum",
@@ -866,6 +878,11 @@ const entries = [
         "reason": "directory_unsigned",
         "rule_id": "discovery/directory_unsigned"
     },
+    {
+        "kind": "discovery",
+        "reason": "domain_not_found",
+        "rule_id": "discovery/domain_not_found"
+    },
     {
         "kind": "discovery",
         "reason": "invalid_key_set",
@@ -1245,6 +1262,10 @@ const retryableRules = {
             "kind": "constant",
             "value": false
         },
+        "deadline": {
+            "kind": "constant",
+            "value": true
+        },
         "digest_mismatch": {
             "kind": "constant",
             "value": false
@@ -1273,6 +1294,10 @@ const retryableRules = {
             "kind": "constant",
             "value": false
         },
+        "internal": {
+            "kind": "constant",
+            "value": false
+        },
         "invalid_accept_signature": {
             "kind": "constant",
             "value": false
@@ -1851,6 +1876,10 @@ const retryableRules = {
             "kind": "constant",
             "value": false
         },
+        "domain_not_found": {
+            "kind": "constant",
+            "value": false
+        },
         "invalid_key_set": {
             "kind": "constant",
             "value": false
@@ -1881,7 +1910,7 @@ const retryableRules = {
         },
         "resolution_failed": {
             "kind": "constant",
-            "value": false
+            "value": true
         },
         "revoked_key": {
             "kind": "constant",
@@ -1908,7 +1937,7 @@ const retryableRules = {
             "minimum": 500,
             "maximum": 599,
             "path": "lib/request_seal/discovery.ex",
-            "line": 301
+            "line": 517
         },
         "unknown_key": {
             "kind": "constant",

package/dist/errors/types.d.ts

@@ -1,13 +1,13 @@
 import { type Reason, type Layer } from './parity.ts';
 /** The bounded detail vocabulary for core failures. */
-export type CoreDetail = Reason<'core'> | Reason<'signature_base'> | 'legacy_string' | 'invalid_dictionary' | 'duplicate_member' | 'invalid_member' | 'missing_member' | 'unsupported_type' | 'not_an_origin' | 'untrusted_agent' | 'source_mismatch' | 'revoked_key' | 'source_unavailable' | 'timeout';
+export type CoreDetail = Reason<'core'> | Reason<'signature_base'> | 'legacy_string' | 'invalid_dictionary' | 'duplicate_member' | 'invalid_member' | 'missing_member' | 'unsupported_type' | 'not_an_origin' | 'untrusted_agent' | 'source_mismatch' | 'revoked_key' | 'source_unavailable' | 'timeout' | 'TypeError' | 'RangeError' | 'URIError' | 'EvalError' | 'ReferenceError' | 'SyntaxError' | 'Error' | 'throw';
 /** A core failure with layer, correlation, and optional bounded source. */
 export type CoreError = Readonly<{
     kind: 'core';
     reason: Reason<'core'>;
     layer: Layer<'core'>;
     correlation: string;
-    retryable: false;
+    retryable: boolean;
     detail: CoreDetail | null;
     message: string | null;
     source: CustodyError | null;
@@ -62,6 +62,8 @@ export type RequestSealError = CoreError | {
 }[SimpleKind] | CustodyError | DiscoveryError | JoseError | ReplayError | AdapterError;
 /** Check whether an error belongs to the private error brand. */
 export declare function isRequestSealError(value: unknown): value is RequestSealError;
+/** The bounded exception class for an internal-fault detail. */
+export declare function faultClass(e: unknown): CoreDetail;
 export declare function coreError(reason: Reason<'core'>, layer: Layer<'core'>, detail?: CoreDetail | null, source?: CustodyError | null): CoreError;
 export declare const messageError: (reason: Reason<'message'>) => Readonly<{
     kind: "message";

package/dist/errors/types.js

@@ -14,13 +14,25 @@ function reasonFor(kind, reason) {
 const signatureDetails = new Set(['limit', 'wrong_message_kind', 'missing_request_context', 'unavailable_origin', 'unavailable_trailers', 'missing_field', 'non_ascii', 'unknown_field_schema', 'invalid_field_schema', 'invalid_structured_field', 'missing_dictionary_key', 'noncanonical_query_name', 'invalid_query_encoding', 'missing_query_parameter', 'ambiguous_query_parameter']);
 const agentDetails = new Set(['missing_member', 'unsupported_type', 'not_an_origin', 'untrusted_agent', 'source_mismatch', 'unknown_key', 'revoked_key', 'source_unavailable', 'timeout']);
 const fieldDetails = new Set(['legacy_string', 'invalid_dictionary', 'duplicate_member', 'invalid_member']);
+// The bounded exception-class vocabulary an internal fault can name: the
+// global error classes, a closed "Error" for any other Error subclass, and
+// "throw" for non-error throws. No message or stack text ever enters a detail.
+const internalDetails = new Set(['TypeError', 'RangeError', 'URIError', 'EvalError', 'ReferenceError', 'SyntaxError', 'Error', 'throw']);
+/** The bounded exception class for an internal-fault detail. */
+export function faultClass(e) {
+    if (e instanceof Error) {
+        const name = e.constructor?.name;
+        return typeof name === "string" && internalDetails.has(name) ? name : "Error";
+    }
+    return "throw";
+}
 export function coreError(reason, layer, detail = null, source = null) {
     if (!ERROR_PARITY.some(e => e.kind === 'core' && e.layer === layer && e.reason === reason))
         throw new TypeError('Unknown core error pair');
     if (source !== null && (reason !== 'signing_failed' || !isRequestSealError(source) || source.kind !== 'custody'))
         throw new TypeError('Invalid core source');
-    const allowed = reason === 'signature_base_failed' ? signatureDetails : reason === 'agent_unresolved' ? agentDetails : reason === 'invalid_signature_agent' ? fieldDetails : reason === 'nonqualifying_signature' ? new Set(ERROR_PARITY.filter(e => e.kind === 'core').map(e => e.reason)) : new Set();
-    return freeze({ kind: 'core', reason, layer, correlation: correlation(), retryable: false, source, message: reason === 'signer_algorithm_mismatch' ? 'signer algorithm does not match signature specification' : null, detail: typeof detail === 'string' && allowed.has(detail) ? detail : null });
+    const allowed = reason === 'signature_base_failed' ? signatureDetails : reason === 'agent_unresolved' ? agentDetails : reason === 'invalid_signature_agent' ? fieldDetails : reason === 'internal' ? internalDetails : reason === 'nonqualifying_signature' ? new Set(ERROR_PARITY.filter(e => e.kind === 'core').map(e => e.reason)) : new Set();
+    return freeze({ kind: 'core', reason, layer, correlation: correlation(), retryable: reason === 'deadline', source, message: reason === 'signer_algorithm_mismatch' ? 'signer algorithm does not match signature specification' : null, detail: typeof detail === 'string' && allowed.has(detail) ? detail : null });
 }
 function simple(kind, reason) {
     return freeze({ kind, reason: reasonFor(kind, reason) });

package/dist/index.d.ts

@@ -36,6 +36,7 @@ export { KeyManagement, type KeyManagementHandle, isKeyManagementHandle, type Wr
 export { Nested, isNestedResult, type NestedResult } from './jose/nested.ts';
 export { Claim, Replay, createClaim, isReplayClaim, isReplayReceipt, createReplayStore, isReplayStore } from './replay/index.ts';
 export { createMemoryStore } from './replay/memory.ts';
+export { Telemetry, type TelemetryEvent, type TelemetryEventName, type TelemetryHandle, type TelemetryOutcome, type TelemetrySubscriber } from './telemetry.ts';
 export * from './discovery/index.ts';
 export { Quorum, createQuorum, isQuorum } from './quorum.ts';
 export type { QuorumMode, QuorumUnit, SignerSlot, QuorumBinding } from './quorum.ts';

package/dist/index.js

@@ -27,6 +27,7 @@ export { KeyManagement, isKeyManagementHandle } from './jose/key-management.js';
 export { Nested, isNestedResult } from './jose/nested.js';
 export { Claim, Replay, createClaim, isReplayClaim, isReplayReceipt, createReplayStore, isReplayStore } from './replay/index.js';
 export { createMemoryStore } from './replay/memory.js';
+export { Telemetry } from './telemetry.js';
 export * from './discovery/index.js';
 export { Quorum, createQuorum, isQuorum } from './quorum.js';
 export { AcceptSignature, parseAcceptSignature, serializeAcceptSignature, fulfillAcceptSignature, isAcceptSignature } from './accept-signature.js';

package/dist/jose/nested.js

@@ -15,6 +15,28 @@ 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 () => {
@@ -44,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);

package/dist/key_handle.js

@@ -10,6 +10,7 @@ import { dataBytes, boundedBinary, binaryByteLength } from './crypto/primitive.j
 import { isPublicKey } from './public_key.js';
 import { isKeyIdentity } from './key_identity.js';
 import { isUnwrappedKey } from './custody/content_key.js';
+import { emit, monotonicMs, span } from "./telemetry.js";
 const handles = new WeakSet();
 const token = Object.freeze({});
 /** Check the private brand of a custody handle. */
@@ -75,7 +76,28 @@ class ManagedHandle {
         return resolved.ok && resolved.value.id === this.#spec.id;
     }
     async sign(algorithm, data, context, options = {}) {
-        const maximum = byteLimit(options);
+        // Byte options precede every handle touch, so a hostile receiver with bad
+        // options still reports invalid_options; the span covers the whole call.
+        const early = byteLimit(options);
+        const start = monotonicMs();
+        if (!early.ok) {
+            const error = custodyError('invalid_options');
+            emit("custodySign", monotonicMs() - start, "error", error);
+            return err(error);
+        }
+        return span("custodySign", () => {
+            try {
+                return this == null ? Promise.resolve(err(custodyError('invalid_data'))) : this.#signSpanned(algorithm, data, context, early);
+            }
+            catch {
+                // An unbranded receiver cannot reach the private path; the failure
+                // stays a bounded custody error, never an escaping TypeError.
+                return Promise.resolve(err(custodyError('invalid_data')));
+            }
+        }, r => r.ok ? "ok" : "error", r => r.ok ? undefined : r.error);
+    }
+    async #signSpanned(algorithm, data, context, maximum) {
+        // Options were read once and validated by the public wrapper.
         if (!maximum.ok)
             return err(custodyError('invalid_options'));
         try {

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';
@@ -329,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 {

package/dist/policy.d.ts

@@ -65,6 +65,18 @@ export declare function normalizeFreshness(input: unknown): Freshness | "not_eva
 export declare function createPolicy(input: unknown): Result<Policy>;
 /** Verification policy construction. */
 export declare const Policy: Readonly<{
-    /** Snapshot, validate, and brand an explicit verification policy. */
+    /**
+     * 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;
 }>;

package/dist/policy.js

@@ -178,6 +178,18 @@ export function createPolicy(input) {
 }
 /** Verification policy construction. */
 export const Policy = Object.freeze({
-    /** Snapshot, validate, and brand an explicit verification policy. */
+    /**
+     * 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: createPolicy
 });

package/dist/quorum/evaluation.d.ts

@@ -16,7 +16,7 @@ export type Assignment = Readonly<{
     pool: readonly Candidate[];
     count: number;
     nodes: number;
-    exhausted: boolean;
+    exhausted: false | "nodes" | "deadline";
 }>;
 /** Evaluation yields after about 10 ms of search work, preserving reference accounting. */
 export declare function evaluateQuorum(records: readonly Candidate[], q: Quorum, requests: AcceptSignature, context?: Context): Promise<Result<Assignment>>;

package/dist/quorum/evaluation.js

@@ -249,13 +249,19 @@ function* evaluate(records, q, requests, context) {
                 if (exhausted)
                     return;
                 if (nodes >= QUORUM_MAX_NODES) {
-                    exhausted = true;
+                    exhausted = "nodes";
                     return;
                 }
                 nodes++;
                 if (now() - sliceStart >= 10) {
                     yield;
-                    tick();
+                    // The caller's wall-clock bound marks deadline exhaustion like the
+                    // node bound: best-so-far acceptance is preserved, and only a
+                    // rejection surfaces it (retryable, unlike the node limit).
+                    if (context && remainingMs(context) <= 0) {
+                        exhausted = "deadline";
+                        return;
+                    }
                     sliceStart = now();
                 }
                 if (i === slots.length) {
@@ -351,13 +357,21 @@ function* evaluate(records, q, requests, context) {
                 }
             }
             yield* search(0, new Map(), new Map(), new Map());
-            if (exhausted && (chosen === null || !modeMet(chosen, q)))
+            if (exhausted !== false && (chosen === null || !modeMet(chosen, q))) {
+                if (exhausted === "deadline")
+                    fail("deadline", "quorum");
                 fail("limit", "input");
+            }
             ensure(chosen !== null, "binding_unsatisfied", "quorum");
         }
         ensure(holds(new Map(chosen.map(r => [r.slot.id, r])), q.bindings), "binding_unsatisfied", "quorum");
         ensure(modeMet(chosen, q), "quorum_not_met", "quorum");
-        tick();
+        // A deadline-exhausted acceptance is the whole point of the bound: the
+        // wall clock already passed, and the satisfying assignment still returns.
+        // (The search closure mutates the marker, which narrowing cannot see.)
+        const exhaustedNow = exhausted;
+        if (exhaustedNow !== "deadline")
+            tick();
         return ok(Object.freeze({
             chosen: Object.freeze(chosen),
             pool: Object.freeze(pool),

package/dist/replay/postgres.d.ts

@@ -7,5 +7,7 @@ export type Query = (sql: string, params: readonly string[], context: Readonly<{
 }>) => 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

@@ -9,6 +9,12 @@ const tableName = (value) => typeof value === 'string' && value.length >= 1 && v
 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/sign.d.ts

@@ -35,5 +35,26 @@ export type SigningSpec = Readonly<{
     digest?: readonly string[] | null;
     fieldSchemas?: unknown;
 }>;
-/** Sign a lossless HTTP message with explicit components and caller-owned custody. */
+/**
+ * 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,10 +11,11 @@ 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";
+import { span } from "./telemetry.js";
 function take(input, keys) {
     const r = snapshotOptions(input, keys);
     ensure(r.ok, "invalid_options", "input");
@@ -36,7 +37,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. */
+/**
+ * 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, [
@@ -117,7 +139,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");
             }
         }
@@ -254,7 +276,7 @@ export async function sign(message, spec, signer, options = {}) {
         try {
             signed = isKeyHandle(signer)
                 ? await custodySign(signer, algorithm, base.value, c.value)
-                : await run(c.value, async (context) => {
+                : await span("custodySign", () => run(c.value, async (context) => {
                     try {
                         const r = await signer(algorithm, new Uint8Array(base.value), context);
                         if (!r ||
@@ -268,7 +290,7 @@ export async function sign(message, spec, signer, options = {}) {
                     catch {
                         return err(bounded(null, "signer_failed", "crypto"));
                     }
-                });
+                }), r => r.ok ? "ok" : "error", r => r.ok ? undefined : r.error);
         }
         finally {
             if (ownedSigningContext)
@@ -309,6 +331,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-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 &&