@request-seal/core 0.1.0 → 0.2.0

package/dist/verify.js

@@ -50,6 +50,14 @@ async function freshness(params, policy, context) {
         skew: policy.skew,
     });
 }
+/** Internal coverage/freshness pipeline shared by selected verification and preflight. */
+export async function authenticationPreflight(input, components, extra, freshnessPolicy, context) {
+    const covered = new Set(identities(input)), needed = new Set(identities(components));
+    ensure([...needed].every((id) => covered.has(id)), "missing_required_component", "policy");
+    ensure(extra === "allow" ||
+        [...covered].every((id) => needed.has(id)), "unexpected_component", "policy");
+    return freshness(parameters(input), typeof freshnessPolicy === "function" ? freshnessPolicy() : freshnessPolicy, context);
+}
 async function content(m, input, policy, options) {
     if (policy === "not_required")
         return policy;
@@ -90,7 +98,7 @@ async function content(m, input, policy, options) {
     }
     return checked.value;
 }
-async function replay(params, algorithm, fresh, policy, context) {
+async function replay(params, algorithm, fresh, policy, context, profile) {
     if (policy === "not_required")
         return policy;
     ensure(typeof params.nonce === "string" && params.nonce.length > 0, "missing_replay_identifier", "replay");
@@ -112,7 +120,7 @@ async function replay(params, algorithm, fresh, policy, context) {
         tag: (params.tag ?? null),
         created: f.created,
         expires: f.expires,
-        profile: Object.freeze({ name: "rfc9421" }),
+        profile,
     });
     return commitReplay(facts, retainUntil, policy, context);
 }
@@ -172,7 +180,7 @@ export async function commitReplay(facts, retainUntil, policy, context) {
         releaseContext(child.value);
     }
 }
-async function verifyLabel(message, policy, options, observeIdentity, parsed) {
+export async function verifyLabel(message, policy, options, observeIdentity, parsed, profile = Object.freeze({ name: "rfc9421" })) {
     try {
         // Reserved stamps have their own bounded reason even when other options reject.
         ensure(options !== null && typeof options === "object" && !Array.isArray(options), "invalid_options", "input");
@@ -222,11 +230,7 @@ async function verifyLabel(message, policy, options, observeIdentity, parsed) {
         ensure(params.nonce === undefined ||
             (typeof params.nonce === "string" &&
                 params.nonce.length <= SIGNATURE_MAX_BYTES), "limit", "input");
-        const covered = new Set(identities(input)), needed = new Set(identities(policy.components));
-        ensure([...needed].every((id) => covered.has(id)), "missing_required_component", "policy");
-        ensure(policy.extraComponents === "allow" ||
-            [...covered].every((id) => needed.has(id)), "unexpected_component", "policy");
-        const fresh = await freshness(params, policy.freshness, c.value);
+        const fresh = await authenticationPreflight(input, policy.components, policy.extraComponents, policy.freshness, c.value);
         ensure(!Object.hasOwn(params, "alg") ||
             policy.algorithms.some(a => typeof a === "string" && a === params.alg), "algorithm_not_permitted", "policy");
         const resolution = await run(c.value, async (context) => {
@@ -336,7 +340,7 @@ async function verifyLabel(message, policy, options, observeIdentity, parsed) {
                 throw contentResult.error;
             fail("digest_unsupported", "content");
         }
-        const replayFacts = await replay(params, algorithm, fresh, policy.replay, c.value);
+        const replayFacts = await replay(params, algorithm, fresh, policy.replay, c.value, profile);
         let identity;
         if (observeIdentity) {
             const id = await run(c.value, async () => {
@@ -364,7 +368,7 @@ async function verifyLabel(message, policy, options, observeIdentity, parsed) {
                 keyid: (params.keyid ?? null),
                 crypto: "valid",
             },
-            profile: { name: "rfc9421" }, content: contentResult.value, freshness: fresh,
+            profile, content: contentResult.value, freshness: fresh,
             replay: replayFacts, principal: "unattributed", authorization: "not_evaluated",
         });
         if (result.ok && identity)
@@ -374,9 +378,10 @@ async function verifyLabel(message, policy, options, observeIdentity, parsed) {
     catch (e) {
         if (isRequestSealError(e) && e.kind === "custody" && e.reason === "deadline_exceeded")
             return err(e);
-        return err(bounded(e, "invalid_options", "input"));
+        return err(bounded(e, typeof profile.name === "string" ? "invalid_options" : "invalid_policy", "input"));
     }
 }
+/** Verify one HTTP signature under an explicit branded policy. */
 export function verify(message, policy, options) {
     return verifyLabel(message, policy, options);
 }

package/dist/web-bot-auth/index.d.ts

@@ -1,10 +1,13 @@
 import { verifyWebBotAuth } from "./verify.ts";
 import { signWebBotAuth } from "./sign.ts";
+/** Web Bot Auth policy construction, signing, and verification operations. */
 export declare const WebBotAuth: Readonly<{
     Policy: Readonly<{
         create: typeof import("./policy.ts").createPolicy;
     }>;
+    /** Verify an agent signature envelope under explicit trust, freshness, and replay rules. */
     verify: typeof verifyWebBotAuth;
+    /** Add a Web Bot Auth signature using explicit agent and freshness parameters. */
     sign: typeof signWebBotAuth;
 }>;
 export { isWebBotAuthVerification } from "./verification.ts";

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

@@ -1,9 +1,12 @@
 import { WebBotAuthPolicy } from "./policy.js";
 import { verifyWebBotAuth } from "./verify.js";
 import { signWebBotAuth } from "./sign.js";
+/** Web Bot Auth policy construction, signing, and verification operations. */
 export const WebBotAuth = Object.freeze({
     Policy: WebBotAuthPolicy,
+    /** Verify an agent signature envelope under explicit trust, freshness, and replay rules. */
     verify: verifyWebBotAuth,
+    /** Add a Web Bot Auth signature using explicit agent and freshness parameters. */
     sign: signWebBotAuth,
 });
 export { isWebBotAuthVerification } from "./verification.js";

package/dist/web-bot-auth/policy.d.ts

@@ -5,15 +5,20 @@ import type { KeySet } from "../discovery/body.ts";
 import type { Context } from "../context.ts";
 import type { Result } from "../result.ts";
 import type { WebBotAuthReplayFacts } from "./verification.ts";
+/** Agent location, type, and deadline context passed to a trust callback. */
 export type AgentRequest = Readonly<{
     identifier: string;
     location: string;
     type: DiscoverySource["type"];
 }>;
+/** Resolve a trusted discovery key set for an agent request. */
 export type AgentTrust = (agent: AgentRequest) => Result<DiscoverySource | KeySet | null> | Promise<Result<DiscoverySource | KeySet | null>>;
+/** Replay rules with a commitment callback over the verified signature envelope. */
 export type WebBotAuthReplayPolicy = Omit<ReplayPolicy, "commitment"> & Readonly<{
+    /** Derive caller-owned replay commitment bytes from verified facts. */
     commitment: (facts: WebBotAuthReplayFacts, context: Context) => Result<Uint8Array> | Promise<Result<Uint8Array>>;
 }>;
+/** A branded agent-trust policy for Web Bot Auth verification. */
 export type WebBotAuthPolicy = Omit<GenericPolicy, "keyResolver" | "replay" | "freshness"> & Readonly<{
     agents: AgentTrust;
     cache: DiscoveryCache | null;
@@ -26,8 +31,11 @@ export type WebBotAuthPolicy = Omit<GenericPolicy, "keyResolver" | "replay" | "f
     testKeys: "reject" | "allow";
     untagged: "reject" | "ignore";
 }>;
+/** Check the private brand of a Web Bot Auth policy. */
 export declare function isWebBotAuthPolicy(v: unknown): v is WebBotAuthPolicy;
 export declare function createPolicy(input: unknown): Result<WebBotAuthPolicy>;
+/** A branded agent-trust policy for Web Bot Auth verification. */
 export declare const WebBotAuthPolicy: Readonly<{
+    /** Snapshot, validate, and brand a Web Bot Auth trust policy. */
     create: typeof createPolicy;
 }>;

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

@@ -1,10 +1,11 @@
-import { snapshotOptions } from "../brand.js";
+import { inspection, snapshotOptions } from "../brand.js";
 import { Policy, } from "../policy.js";
 import { isDiscoveryCache } from "../discovery/cache.js";
 import { ok, err } from "../result.js";
 import { ensure, bounded } from "../signature-fields.js";
 import { resolveAlgorithm } from "../crypto/algorithm.js";
 const policies = new WeakSet();
+/** Check the private brand of a Web Bot Auth policy. */
 export function isWebBotAuthPolicy(v) {
     return !!v && typeof v === "object" && policies.has(v);
 }
@@ -92,8 +93,7 @@ export function createPolicy(input) {
         });
         Object.defineProperties(p, {
             toJSON: { value: inspect },
-            [Symbol.for("nodejs.util.inspect.custom")]: { value: inspect },
-            [Symbol.for("Deno.customInspect")]: { value: inspect },
+            ...inspection(inspect),
         });
         Object.freeze(p);
         policies.add(p);
@@ -103,4 +103,8 @@ export function createPolicy(input) {
         return err(bounded(e, "invalid_policy", "input"));
     }
 }
-export const WebBotAuthPolicy = Object.freeze({ create: createPolicy });
+/** A branded agent-trust policy for Web Bot Auth verification. */
+export const WebBotAuthPolicy = Object.freeze({
+    /** Snapshot, validate, and brand a Web Bot Auth trust policy. */
+    create: createPolicy
+});

package/dist/web-bot-auth/verification.d.ts

@@ -2,11 +2,14 @@ import type { Verification } from "../verification.ts";
 import type { ReplayReceipt } from "../replay-port.ts";
 import type { SigningAlgorithm } from "../crypto/algorithm.ts";
 import type { Proof } from "../discovery/body.ts";
+/** Pinned Web Bot Auth profile metadata. */
 export declare const WEB_BOT_AUTH_PROFILE: Readonly<{
     name: "web_bot_auth";
     revision: "draft-ietf-webbotauth-httpsig-protocol-00";
 }>;
+/** Profile name `web_bot_auth` and revision `draft-ietf-webbotauth-httpsig-protocol-00`. */
 export type WebBotAuthProfile = typeof WEB_BOT_AUTH_PROFILE;
+/** A verified agent identity with discovery provenance and key thumbprint. */
 export type AgentPrincipal = Readonly<{
     kind: "agent";
     identifier: string;
@@ -20,14 +23,17 @@ export type AgentPrincipal = Readonly<{
         revision: string | null;
     }>;
 }>;
+/** A verified held-key principal identified by its thumbprint. */
 export type HeldPrincipal = Readonly<{
     kind: "key";
     thumbprint: string;
 }>;
+/** Single-signature verification facts narrowed to Web Bot Auth principals. */
 export type WebBotAuthSignature = Omit<Verification, "profile" | "principal"> & Readonly<{
     profile: WebBotAuthProfile;
     principal: AgentPrincipal | HeldPrincipal;
 }>;
+/** Verified Web Bot Auth envelope facts supplied to a replay commitment callback. */
 export type WebBotAuthReplayFacts = Readonly<{
     profile: WebBotAuthProfile;
     signatures: readonly Readonly<{
@@ -40,6 +46,7 @@ export type WebBotAuthReplayFacts = Readonly<{
         expires: number;
     }>[];
 }>;
+/** A branded Web Bot Auth envelope with per-label facts, evidence, and replay status. */
 export type WebBotAuthVerification = Readonly<{
     profile: WebBotAuthProfile;
     signatures: Readonly<Record<string, WebBotAuthSignature>>;
@@ -49,6 +56,7 @@ export type WebBotAuthVerification = Readonly<{
     authorization: "not_evaluated";
 }>;
 import { type Result } from "../result.ts";
+/** Check the private brand of a Web Bot Auth verification envelope. */
 export declare function isWebBotAuthVerification(v: unknown): v is WebBotAuthVerification;
 /** Internal constructor; single-label facts retain their independent brands. */
 export declare function completedEnvelope(signatures: Record<string, WebBotAuthSignature>, evidence: Record<string, readonly string[]>, ignored: readonly string[], replay: WebBotAuthVerification["replay"]): Result<WebBotAuthVerification>;

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

@@ -1,3 +1,5 @@
+import { inspection } from "../brand.js";
+/** Pinned Web Bot Auth profile metadata. */
 export const WEB_BOT_AUTH_PROFILE = Object.freeze({
     name: "web_bot_auth",
     revision: "draft-ietf-webbotauth-httpsig-protocol-00",
@@ -7,6 +9,7 @@ import { coreError } from "../errors/types.js";
 import { verificationFacts, isVerification } from "../verification.js";
 import { isReplayReceipt } from "../replay/receipt.js";
 const envelopes = new WeakSet();
+/** Check the private brand of a Web Bot Auth verification envelope. */
 export function isWebBotAuthVerification(v) {
     return !!v && typeof v === "object" && envelopes.has(v);
 }
@@ -31,8 +34,7 @@ export function completedEnvelope(signatures, evidence, ignored, replay) {
     });
     Object.defineProperties(result, {
         toJSON: { value: inspect },
-        [Symbol.for("nodejs.util.inspect.custom")]: { value: inspect },
-        [Symbol.for("Deno.customInspect")]: { value: inspect },
+        ...inspection(inspect),
     });
     envelopes.add(result);
     return ok(Object.freeze(result));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@request-seal/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Standards-based HTTP message signatures and JOSE for web-standard runtimes.",
   "type": "module",
   "license": "Apache-2.0",
@@ -61,19 +61,30 @@
     "url": "https://github.com/baselabs/request-seal-typescript/issues"
   },
   "scripts": {
-    "typecheck": "tsc -p tsconfig.json",
-    "typecheck:web": "tsc -p tsconfig.web.json",
+    "typecheck": "node node_modules/typescript/bin/tsc -p tsconfig.json",
+    "typecheck:web": "node node_modules/typescript/bin/tsc -p tsconfig.web.json",
     "test": "node --unhandled-rejections=strict --experimental-strip-types --no-warnings --test-concurrency=4 --test test/*.test.ts",
     "test:red": "node --unhandled-rejections=strict --experimental-strip-types --no-warnings --test test/red/planted.test.ts",
     "self-checks": "node --experimental-strip-types --no-warnings self-checks.ts",
-    "build": "node --experimental-strip-types --no-warnings scripts/clean-dist.ts && tsc -p tsconfig.build.json",
+    "build": "node --experimental-strip-types --no-warnings scripts/clean-dist.ts && node node_modules/typescript/bin/tsc -p tsconfig.build.json",
     "conformance": "node --experimental-strip-types --no-warnings tools/conformance/cli.ts --corpus test/fixtures/corpus-smoke --smoke && node --experimental-strip-types --no-warnings tools/conformance/cli.ts --corpus conformance --pending-ok",
     "pack:check": "node --experimental-strip-types --no-warnings scripts/pack-check.ts",
-    "check": "npm run typecheck && npm run typecheck:web && npm test && npm run self-checks && npm run build && npm run conformance && npm run pack:check"
+    "check": "npm run typecheck && npm run typecheck:web && npm run build && npm test && npm run self-checks && npm run conformance && npm run pack:check",
+    "docs": "node --import ./scripts/typedoc-register.mjs node_modules/typedoc/bin/typedoc --options typedoc.json"
   },
   "devDependencies": {
+    "@types/markdown-it": "14.1.2",
     "@types/node": "26.6.4",
     "fast-check": "4.10.2",
-    "typescript": "7.0.2"
+    "github-slugger": "2.0.0",
+    "markdown-it": "14.3.2",
+    "typedoc": "0.28.20",
+    "typescript": "7.0.2",
+    "typescript-docs": "npm:typescript@6.0.3"
+  },
+  "overrides": {
+    "typedoc": {
+      "typescript": "$typescript"
+    }
   }
 }