@request-seal/core 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,7 +2,10 @@
 
 ## Unreleased
 
-## 0.3.0 - October 17, 2026
+## 0.4.0 - October 17, 2026
+- Upgrade notes for callers: the new telemetry surface is entirely opt-in — no code changes unless you attach a subscriber; `Telemetry.attach` accepts at most sixteen subscribers and every event is a frozen six-field object whose `reason` values are the same parity rule ids the errors carry.
+- Add the versioned telemetry contract v1, mirroring RequestSeal for Elixir's `:telemetry` surface with zero dependencies: `Telemetry.attach(subscriber)` returns a caller-owned handle whose `detach` stops delivery, and five events carry bounded, low-cardinality payloads — `verify`, `verifyQuorum`, and `webBotAuthVerify` report `ok` or `error` with the parity rule id, layer, and bounded detail exactly as the caller receives them; `replayClaim` reports `claimed`, `already_claimed`, or `error`; `custodySign` reports `ok` or `error` with the custody reason. `durationMs` is monotonic milliseconds over the emitting call. No signature label, key ID, URL, principal, nonce, bytes, or exception message ever enters an event; internal faults (`core/internal.internal`) are countable through the closed reason vocabulary. A throwing subscriber degrades silently and never fails the operation it observes; attachment is bounded to sixteen concurrent subscribers. The event names, outcomes, and fields are additive-only within minor versions.
+
 
 Upgrade notes for callers: the discovery `Resolution.assertedAlgorithm` is now the normalized JOSE name (`JwsAlgorithm | null`) and an asserted key's `Resolution.algorithm` is the `{jws}` selector, so code matching the raw HTTP token string must compare JOSE names; a cache `fetch` callback may now receive a `validators` option and return a `NotModified` outcome (a callback that ignores both still works); `CoreError.retryable` is `boolean` and `discovery/resolution_failed` is retryable; a first `103` no longer fails a discovery fetch.
 - Re-run the reciprocal exchange against the published RequestSeal for Elixir 0.5.2: both interop peers pin Hex `request_seal == 0.5.2` with the release checksum, the CI reference clone tracks the v0.5.2 tag, and the executed exchange agrees with zero disagreements in every family and both directions (receipt under the project's check records).

package/README.md

@@ -384,7 +384,7 @@ RequestSeal reports what was cryptographically established and nothing more: the
 
 API: [generated reference](https://baselabs.github.io/request-seal-typescript/). Build it locally with `npm ci --ignore-scripts && npm run docs`, then open the generated `site-dist/index.html`.
 
-Reference: [glossary](docs/reference/glossary.md), [error reasons](docs/reference/errors.md), [signing and verification](docs/reference/sign-and-verify.md), [adapters](docs/reference/adapters.md), [Web Bot Auth](docs/reference/web-bot-auth.md), [replay](docs/reference/replay.md), [discovery](docs/reference/discovery.md), [JOSE](docs/reference/jose.md), [wire APIs](docs/reference/wire.md), [multiple signatures](docs/reference/quorum.md), [extension profiles](docs/reference/profiles.md), [error parity](docs/reference/error-parity.md), and [corpus format](docs/reference/corpus-format.md). Design record: the [threat model](docs/design/threat-model.md). To contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
+Reference: [glossary](docs/reference/glossary.md), [error reasons](docs/reference/errors.md), [signing and verification](docs/reference/sign-and-verify.md), [adapters](docs/reference/adapters.md), [Web Bot Auth](docs/reference/web-bot-auth.md), [replay](docs/reference/replay.md), [discovery](docs/reference/discovery.md), [JOSE](docs/reference/jose.md), [wire APIs](docs/reference/wire.md), [multiple signatures](docs/reference/quorum.md), [extension profiles](docs/reference/profiles.md), [error parity](docs/reference/error-parity.md), [telemetry](docs/reference/telemetry.md), and [corpus format](docs/reference/corpus-format.md). Design record: the [threat model](docs/design/threat-model.md). To contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Compatibility
 

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 /** The public package version. */
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.4.0";
 /** The immutable public conformance corpus release and index digest. */
 export declare const CORPUS_PIN: Readonly<{
     tag: "v0.5.2";

package/dist/constants.js

@@ -1,5 +1,5 @@
 /** The public package version. */
-export const VERSION = '0.3.0';
+export const VERSION = '0.4.0';
 /** The immutable public conformance corpus release and index digest. */
 export const CORPUS_PIN = Object.freeze({ tag: 'v0.5.2', commit: '53b6690ccd5036d58b280d08cf0cacc6427262fe', indexSha256: 'ceb30bf713a6e34e6a15847b658a618d8f7568ee6a6c07bfbbf58fa5d143995e' });
 // RequestSeal.StructuredFields ceilings at v0.4.0 (b239287).

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/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/sign.js

@@ -15,6 +15,7 @@ import { inner, label, dictionaries, signatureSchema, parameters, fail, ensure,
 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");
@@ -275,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 ||
@@ -289,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)

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

@@ -5,12 +5,16 @@ import { isContext, withDeadline, remainingMs } from "./context.js";
 import { isAcceptSignature, applicable, } from "./accept-signature.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");

package/dist/verify.js

@@ -11,6 +11,7 @@ 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, 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 {
@@ -410,7 +424,8 @@ export async function verifyLabel(message, policy, options, observeIdentity, par
  *   [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

@@ -15,6 +15,7 @@ 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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@request-seal/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Standards-based HTTP message signatures and JOSE for web-standard runtimes.",
   "type": "module",
   "license": "Apache-2.0",