@request-seal/core 0.2.0 → 0.4.0

package/dist/telemetry.d.ts

@@ -0,0 +1,43 @@
+import { type Result } from "./result.ts";
+/** The versioned event names (v1), mirroring the reference telemetry contract. */
+export type TelemetryEventName = "verify" | "verifyQuorum" | "webBotAuthVerify" | "replayClaim" | "custodySign";
+/** What an event reports: the operation's outcome within a closed vocabulary. */
+export type TelemetryOutcome = "ok" | "error" | "claimed" | "already_claimed";
+/** One bounded, low-cardinality observation of a RequestSeal operation. */
+export type TelemetryEvent = Readonly<{
+    event: TelemetryEventName;
+    outcome: TelemetryOutcome;
+    reason: string | null;
+    layer: string | null;
+    detail: string | null;
+    durationMs: number;
+}>;
+/** A caller-owned subscriber; handlers own storage and aggregation. */
+export type TelemetrySubscriber = (event: TelemetryEvent) => void;
+/** A caller-owned attachment; `detach` stops delivery and is idempotent. */
+export type TelemetryHandle = Readonly<{
+    /** Stop delivering events to this attachment; calling it again does nothing. */
+    detach(): void;
+}>;
+/**
+ * Emit one event to every attached subscriber. Telemetry is an optional path:
+ * a throwing subscriber degrades silently and never fails the operation it
+ * observes. Payloads carry closed vocabulary only — never labels, key IDs,
+ * URLs, principals, nonces, bytes, or exception text.
+ */
+export declare function emit(event: TelemetryEventName, durationMs: number, outcome: TelemetryOutcome, error?: unknown): void;
+/** Measure an operation and emit its stop event with the result's metadata. */
+export declare function span<T>(event: TelemetryEventName, work: () => Promise<T>, outcome: (result: T) => TelemetryOutcome, errorOf: (result: T) => unknown): Promise<T>;
+/** The captured monotonic clock used for event durations, in milliseconds. */
+export declare function monotonicMs(): number;
+/** Attach a telemetry subscriber; at most sixteen run at once. */
+export declare function attach(input: unknown): Result<TelemetryHandle>;
+/** The v1 event names, as documented in the observability reference. */
+export declare const Telemetry: Readonly<{
+    /** The v1 event names. */
+    events(): readonly TelemetryEventName[];
+    /** Attach a telemetry subscriber; the handle's `detach` stops delivery. */
+    attach: typeof attach;
+    /** Check the private brand of a telemetry attachment handle. */
+    isHandle(value: unknown): value is TelemetryHandle;
+}>;

package/dist/telemetry.js

@@ -0,0 +1,86 @@
+import { err, ok } from "./result.js";
+import { coreError, isRequestSealError, ruleId } from "./errors/types.js";
+const names = Object.freeze([
+    "verify",
+    "verifyQuorum",
+    "webBotAuthVerify",
+    "replayClaim",
+    "custodySign",
+]);
+const MAX_SUBSCRIBERS = 16;
+const handles = new WeakSet();
+let subscribers = Object.freeze([]);
+// A captured monotonic clock: replacing the global later cannot change a duration.
+const now = performance.now.bind(performance);
+/**
+ * Emit one event to every attached subscriber. Telemetry is an optional path:
+ * a throwing subscriber degrades silently and never fails the operation it
+ * observes. Payloads carry closed vocabulary only — never labels, key IDs,
+ * URLs, principals, nonces, bytes, or exception text.
+ */
+export function emit(event, durationMs, outcome, error) {
+    if (subscribers.length === 0)
+        return;
+    const payload = Object.freeze({
+        event,
+        outcome,
+        reason: isRequestSealError(error) ? ruleId(error) : null,
+        layer: isRequestSealError(error) && "layer" in error ? error.layer : null,
+        detail: isRequestSealError(error) && "detail" in error && typeof error.detail === "string" ? error.detail : null,
+        durationMs,
+    });
+    for (const subscriber of subscribers) {
+        try {
+            subscriber(payload);
+        }
+        catch {
+            // Degrade: a defective observer is not the observed operation's failure.
+        }
+    }
+}
+/** Measure an operation and emit its stop event with the result's metadata. */
+export async function span(event, work, outcome, errorOf) {
+    const start = now();
+    const result = await work();
+    emit(event, now() - start, outcome(result), errorOf(result));
+    return result;
+}
+/** The captured monotonic clock used for event durations, in milliseconds. */
+export function monotonicMs() { return now(); }
+/** Attach a telemetry subscriber; at most sixteen run at once. */
+export function attach(input) {
+    if (typeof input !== "function")
+        return err(coreError("invalid_options", "input"));
+    if (subscribers.length >= MAX_SUBSCRIBERS)
+        return err(coreError("invalid_options", "input"));
+    const subscriber = input;
+    subscribers = Object.freeze([...subscribers, subscriber]);
+    let live = true;
+    const handle = Object.freeze({
+        detach() {
+            if (!live)
+                return;
+            live = false;
+            // Remove exactly one occurrence: two attachments of one function are
+            // independently detachable, mirroring the reference's handler ids.
+            const index = subscribers.indexOf(subscriber);
+            if (index >= 0)
+                subscribers = Object.freeze(subscribers.slice(0, index).concat(subscribers.slice(index + 1)));
+        },
+    });
+    handles.add(handle);
+    return ok(handle);
+}
+/** The v1 event names, as documented in the observability reference. */
+export const Telemetry = Object.freeze({
+    /** The v1 event names. */
+    events() {
+        return names;
+    },
+    /** Attach a telemetry subscriber; the handle's `detach` stops delivery. */
+    attach,
+    /** Check the private brand of a telemetry attachment handle. */
+    isHandle(value) {
+        return !!value && typeof value === "object" && handles.has(value);
+    },
+});

package/dist/verify-quorum.js

@@ -3,14 +3,18 @@ import { isMessage, Message } from "./message/index.js";
 import { isQuorum } from "./quorum.js";
 import { isContext, withDeadline, remainingMs } from "./context.js";
 import { isAcceptSignature, applicable, } from "./accept-signature.js";
-import { dictionaries, parameters, identities, ensure, fail, bounded, } from "./signature-fields.js";
+import { dictionaries, parameters, identities, ensure, fail, envelope, } from "./signature-fields.js";
 import { verifyCandidate } from "./verify.js";
+import { span } from "./telemetry.js";
 import { evaluateQuorum } from "./quorum/evaluation.js";
 import { completeQuorum, } from "./quorum/verification.js";
 import { custodyError, isRequestSealError } from "./errors/types.js";
 import { ok, err } from "./result.js";
 /** Verify bounded HTTP signatures and evaluate the configured quorum policy. */
-export async function verifyQuorum(message, quorum, options) {
+export function verifyQuorum(message, quorum, options) {
+    return span("verifyQuorum", () => verifyQuorumSpanned(message, quorum, options), r => r.ok ? "ok" : "error", r => r.ok ? undefined : r.error);
+}
+async function verifyQuorumSpanned(message, quorum, options) {
     try {
         const a = snapshotOptions(options, ["acceptSignature", "context"]);
         ensure(a.ok, "invalid_options", "input");
@@ -56,10 +60,30 @@ export async function verifyQuorum(message, quorum, options) {
             let qualified = false, last;
             const baseCache = new Map();
             for (const slot of slots) {
-                const r = await verifyCandidate(m, slot.policy, {
-                    label: l,
-                    context: c.value,
-                }, { input, signature: signatures.get(l), baseCache });
+                let r;
+                try {
+                    r = await verifyCandidate(m, slot.policy, {
+                        label: l,
+                        context: c.value,
+                    }, { input, signature: signatures.get(l), baseCache });
+                }
+                catch (fault) {
+                    // Per-label rescue isolates a defective label as its own
+                    // nonqualifying internal fact, never a whole-call failure.
+                    if (isRequestSealError(fault) && fault.kind === "custody")
+                        return err(fault);
+                    const faulted = envelope(fault);
+                    if (faulted.kind !== "core")
+                        throw fault;
+                    last = {
+                        label: l,
+                        slot: slot.id,
+                        reason: faulted.reason,
+                        layer: faulted.layer,
+                    };
+                    facts.push(last);
+                    continue;
+                }
                 if (r.ok) {
                     const record = Object.freeze({
                         slot,
@@ -108,8 +132,9 @@ export async function verifyQuorum(message, quorum, options) {
             const original = candidates.find((c) => c.slot === r.slot && c.label === r.label);
             results[r.label] = verified.get(original);
         }
-        if (remainingMs(c.value) <= 0)
-            throw custodyError("deadline_exceeded");
+        // The wall-clock bound lives in the assignment search: an accepted
+        // assignment, including one accepted at deadline exhaustion, completes.
+        // The remaining work here is synchronous and bounded.
         return completeQuorum({
             profile: { name: "rfc9421" },
             mode: quorum.mode,
@@ -140,6 +165,6 @@ export async function verifyQuorum(message, quorum, options) {
     catch (e) {
         if (isRequestSealError(e) && e.kind === "custody")
             return err(e);
-        return err(bounded(e, "invalid_options", "input"));
+        return err(envelope(e));
     }
 }

package/dist/verify.d.ts

@@ -20,7 +20,25 @@ type ParsedCandidate = Readonly<{
     baseCache: BaseCache;
 }>;
 export declare function verifyLabel(message: unknown, policy: unknown, options: unknown, observeIdentity?: (identity: KeyIdentity) => void, parsed?: ParsedCandidate, profile?: ReplayFacts["profile"]): Promise<Result<Verification>>;
-/** Verify one HTTP signature under an explicit branded policy. */
+/**
+ * Verify one HTTP signature under an explicit branded policy.
+ *
+ * Checks exactly the named label; it never tries other labels. Success means the
+ * cryptography, coverage, freshness, content, and replay layers all passed. It does not
+ * authorize: the Verification records `authorization: "not_evaluated"`.
+ *
+ * @param message - A branded Message carrying the signature.
+ * @param policy - A branded Policy from `Policy.create`.
+ * @param options - `{label, context?, representation?, digestState?}`. `representation` is a
+ *   complete retained Body and needs a `"representation"` content policy. `digestState` is a
+ *   DigestState of the policy's content kind that you fed with a streamed body; verify finishes
+ *   it. The two are mutually exclusive.
+ * @returns `ok(verification)`, or a bounded error such as `core` `crypto.invalid_signature`,
+ *   `freshness.expired`, `content.digest_mismatch`, `key.unknown_key`, or `replay.replayed`.
+ * @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 verify(message: unknown, policy: unknown, options: unknown): Promise<Result<Verification>>;
 /** Internal composition of the single-label pipeline; identities stay private. */
 export declare function verifyCandidate(message: unknown, policy: Policy, options: unknown, parsed?: ParsedCandidate): Promise<Result<Readonly<{

package/dist/verify.js

@@ -10,7 +10,8 @@ import { isPublicKey } from "./public_key.js";
 import { isKeyIdentity, KeyIdentity } from "./key_identity.js";
 import { build } from "./signature-base/index.js";
 import { digestField, checkDigest, isDigestState } from "./digest.js";
-import { label, dictionaries, validInner, parameters, identities, ensure, fail, bounded, } from "./signature-fields.js";
+import { label, dictionaries, validInner, parameters, identities, ensure, fail, bounded, envelope, } from "./signature-fields.js";
+import { emit, monotonicMs, span } from "./telemetry.js";
 import { completed, } from "./verification.js";
 import { createClaim, retainUntil as retention } from "./replay/claim.js";
 import { createReceipt } from "./replay/receipt.js";
@@ -126,6 +127,19 @@ async function replay(params, algorithm, fresh, policy, context, profile) {
 }
 /** Internal shared commit boundary; profile facts are supplied only after authentication. */
 export async function commitReplay(facts, retainUntil, policy, context) {
+    const start = monotonicMs();
+    try {
+        const result = await commitReplaySpanned(facts, retainUntil, policy, context);
+        emit("replayClaim", monotonicMs() - start, "claimed");
+        return result;
+    }
+    catch (error) {
+        const replayed = isRequestSealError(error) && error.kind === "core" && error.reason === "replayed";
+        emit("replayClaim", monotonicMs() - start, replayed ? "already_claimed" : "error", error);
+        throw error;
+    }
+}
+async function commitReplaySpanned(facts, retainUntil, policy, context) {
     const child = withDeadline({ parent: context, timeoutMs: policy.timeoutMs });
     ensure(child.ok, "store_timeout", "replay");
     try {
@@ -371,19 +385,47 @@ export async function verifyLabel(message, policy, options, observeIdentity, par
             profile, content: contentResult.value, freshness: fresh,
             replay: replayFacts, principal: "unattributed", authorization: "not_evaluated",
         });
-        if (result.ok && identity)
-            observeIdentity(identity);
+        if (result.ok && identity) {
+            // An extension pipeline step is a caller callback: its fault keeps the
+            // profile's deliberate invalid_policy classification, like a failing
+            // signer keeps signer_failed.
+            try {
+                observeIdentity(identity);
+            }
+            catch {
+                fail("invalid_policy", "input");
+            }
+        }
         return result;
     }
     catch (e) {
         if (isRequestSealError(e) && e.kind === "custody" && e.reason === "deadline_exceeded")
             return err(e);
-        return err(bounded(e, typeof profile.name === "string" ? "invalid_options" : "invalid_policy", "input"));
+        return err(envelope(e));
     }
 }
-/** Verify one HTTP signature under an explicit branded policy. */
+/**
+ * Verify one HTTP signature under an explicit branded policy.
+ *
+ * Checks exactly the named label; it never tries other labels. Success means the
+ * cryptography, coverage, freshness, content, and replay layers all passed. It does not
+ * authorize: the Verification records `authorization: "not_evaluated"`.
+ *
+ * @param message - A branded Message carrying the signature.
+ * @param policy - A branded Policy from `Policy.create`.
+ * @param options - `{label, context?, representation?, digestState?}`. `representation` is a
+ *   complete retained Body and needs a `"representation"` content policy. `digestState` is a
+ *   DigestState of the policy's content kind that you fed with a streamed body; verify finishes
+ *   it. The two are mutually exclusive.
+ * @returns `ok(verification)`, or a bounded error such as `core` `crypto.invalid_signature`,
+ *   `freshness.expired`, `content.digest_mismatch`, `key.unknown_key`, or `replay.replayed`.
+ * @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 function verify(message, policy, options) {
-    return verifyLabel(message, policy, options);
+    // The public entry carries the telemetry span; internal per-label calls do not.
+    return span("verify", () => verifyLabel(message, policy, options), r => r.ok ? "ok" : "error", r => r.ok ? undefined : r.error);
 }
 /** Internal composition of the single-label pipeline; identities stay private. */
 export async function verifyCandidate(message, policy, options, parsed) {

package/dist/web-bot-auth/verify.js

@@ -10,11 +10,12 @@ import { isDiscoverySource, sourceOrigin, thumbprintId, } from "../discovery/sou
 import { isKeySet, isResolution } from "../discovery/body.js";
 import { isPublicKey } from "../public_key.js";
 import { coreError, isRequestSealError, } from "../errors/types.js";
-import { dictionaries, validInner, parameters, identities, ensure, fail, bounded, } from "../signature-fields.js";
+import { dictionaries, validInner, parameters, identities, ensure, fail, envelope, } from "../signature-fields.js";
 import { CLOCK_MAX_SECONDS } from "../constants.js";
 import { retentionEnd } from "../replay/claim.js";
 import { agents, identifier, originAgent, component, required, nested, schemas, } from "./support.js";
 import { WEB_BOT_AUTH_PROFILE, completedEnvelope, } from "./verification.js";
+import { span } from "../telemetry.js";
 const testKeys = new Set([
     "BHj8s0GPnMEQtkaULIM-PLgEhLBbuGUQ1vMxmBWZzEo",
     "oD0HwocPBSfpNy5W3bpJeyFGY_IQ_YpqxSjQ3Yd-CLA",
@@ -180,7 +181,10 @@ async function resolve(agent, label, params, p, c) {
         };
     }
 }
-export async function verifyWebBotAuth(message, policy, options = {}) {
+export function verifyWebBotAuth(message, policy, options = {}) {
+    return span("webBotAuthVerify", () => verifyWebBotAuthSpanned(message, policy, options), r => r.ok ? "ok" : "error", r => r.ok ? undefined : r.error);
+}
+async function verifyWebBotAuthSpanned(message, policy, options = {}) {
     let owned;
     try {
         ensure(isWebBotAuthPolicy(policy), "invalid_policy", "input");
@@ -336,7 +340,7 @@ export async function verifyWebBotAuth(message, policy, options = {}) {
     catch (e) {
         if (isRequestSealError(e))
             return err(e);
-        return err(bounded(e, "invalid_options", "input"));
+        return err(envelope(e));
     }
     finally {
         if (owned)

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@request-seal/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Standards-based HTTP message signatures and JOSE for web-standard runtimes.",
   "type": "module",
   "license": "Apache-2.0",
+  "keywords": [
+    "http-message-signatures",
+    "rfc9421",
+    "rfc9530",
+    "content-digest",
+    "web-bot-auth",
+    "jose",
+    "jws",
+    "jwe",
+    "webcrypto",
+    "replay-protection"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {