@request-seal/core 0.1.0 → 0.2.0

package/dist/message/index.js

@@ -7,15 +7,19 @@ const messages = new WeakSet();
 const fieldOccurrences = new WeakSet();
 const bodies = new WeakSet();
 const transportFacts = new WeakSet();
+/** Check the private brand of an HTTP message. */
 export function isMessage(value) {
     return typeof value === 'object' && value !== null && messages.has(value);
 }
+/** Check the private brand of a field occurrence. */
 export function isFieldOccurrence(value) {
     return typeof value === 'object' && value !== null && fieldOccurrences.has(value);
 }
+/** Check the private brand of a body snapshot. */
 export function isBody(value) {
     return typeof value === 'object' && value !== null && bodies.has(value);
 }
+/** Check the private brand of captured transport facts. */
 export function isTransportFacts(value) {
     return typeof value === 'object' && value !== null && transportFacts.has(value);
 }
@@ -265,21 +269,32 @@ function message(input, related = false) {
         relatedRequest: request,
     }, messages);
 }
+/** Field occurrence construction and validation. */
 export const FieldOccurrence = Object.freeze({
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a) => protect(() => field(a), 'invalid_field'),
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a) => protect(() => field(a), 'invalid_field'),
 });
+/** Body snapshot construction and validation. */
 export const Body = Object.freeze({
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a) => protect(() => body(a), 'invalid_body'),
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a) => protect(() => body(a), 'invalid_body'),
 });
+/** Transport snapshot construction and validation. */
 export const TransportFacts = Object.freeze({
+    /** Validate and brand the supplied HTTP snapshot. */
     create: (a) => protect(() => transport(a), 'invalid_transport'),
+    /** Validate the snapshot using the same boundary as construction. */
     validate: (a) => protect(() => transport(a), 'invalid_transport'),
 });
+/** Validate and brand a lossless HTTP message snapshot. */
 export function createMessage(a) {
     return protect(() => message(a), 'invalid_message');
 }
+/** Validate a message snapshot through the same constructor boundary. */
 export const validateMessage = createMessage;
 async function builder(kind, first, target, headers, bytes, options) {
     try {
@@ -347,9 +362,14 @@ async function builder(kind, first, target, headers, bytes, options) {
             : messageError('invalid_message'));
     }
 }
+/** Lossless HTTP message construction and validation. */
 export const Message = Object.freeze({
+    /** Validate and brand the supplied HTTP snapshot. */
     create: createMessage,
+    /** Validate the snapshot using the same boundary as construction. */
     validate: validateMessage,
+    /** Build a branded HTTP request with owned field and body bytes. */
     request: (method, target, fields, bytes, options = {}) => builder('request', method, target, fields, bytes, options),
+    /** Build a branded HTTP response with owned field and body bytes. */
     response: (status, fields, bytes, options = {}) => builder('response', status, null, fields, bytes, options),
 });

package/dist/numbers.d.ts

@@ -1,12 +1,18 @@
 import { type Result } from './result.ts';
+/** Check whether a value is a JavaScript safe integer. */
 export declare const safeInteger: (value: unknown) => value is number;
+/** Validate the Structured Fields integer range and reject negative zero. */
 export declare function structuredInteger(value: unknown): Result<number>;
+/** Validate a Structured Fields date using the integer range. */
 export declare const structuredDate: typeof structuredInteger;
+/** A decimal stored as an integer scaled by one thousand. */
 export type Decimal = Readonly<{
     scaled: number;
     scale: 3;
 }>;
 /** Parse decimal source text without rounding or a floating-point conversion. */
 export declare function parseDecimal(value: unknown): Result<Decimal>;
+/** Validate a nonnegative Unix clock value within the supported range. */
 export declare function clockSeconds(value: unknown): Result<number>;
+/** Validate a positive timeout within the custody time limit. */
 export declare function timeoutMs(value: unknown): Result<number>;

package/dist/numbers.js

@@ -1,10 +1,13 @@
 import { SF_MAX_INTEGER, CLOCK_MAX_SECONDS, TIMEOUT_MAX_MS } from './constants.js';
 import { ok, err } from './result.js';
 import { structuredFieldsError, coreError, custodyError } from './errors/types.js';
+/** Check whether a value is a JavaScript safe integer. */
 export const safeInteger = (value) => typeof value === 'number' && Number.isSafeInteger(value);
+/** Validate the Structured Fields integer range and reject negative zero. */
 export function structuredInteger(value) {
     return safeInteger(value) && !Object.is(value, -0) && Math.abs(value) <= SF_MAX_INTEGER ? ok(value) : err(structuredFieldsError('invalid_value'));
 }
+/** Validate a Structured Fields date using the integer range. */
 export const structuredDate = structuredInteger;
 /** Parse decimal source text without rounding or a floating-point conversion. */
 export function parseDecimal(value) {
@@ -16,9 +19,11 @@ export function parseDecimal(value) {
     const magnitude = Number(match[2]) * 1000 + Number(match[3].padEnd(3, '0'));
     return ok(Object.freeze({ scaled: match[1] === '-' && magnitude !== 0 ? -magnitude : magnitude, scale: 3 }));
 }
+/** Validate a nonnegative Unix clock value within the supported range. */
 export function clockSeconds(value) {
     return safeInteger(value) && value >= 0 && value <= CLOCK_MAX_SECONDS ? ok(value) : err(coreError('invalid_clock', 'freshness'));
 }
+/** Validate a positive timeout within the custody time limit. */
 export function timeoutMs(value) {
     return safeInteger(value) && value >= 1 && value <= TIMEOUT_MAX_MS ? ok(value) : err(custodyError('invalid_options'));
 }

package/dist/policy.d.ts

@@ -6,36 +6,45 @@ import type { KeyIdentity } from "./key_identity.ts";
 import type { KeyHandle } from "./key_handle.ts";
 import type { PublicKey } from "./public_key.ts";
 import type { ReplayStore, ReplayFacts } from "./replay-port.ts";
+/** A caller-owned signature verification callback receiving a bounded context. */
 export type Verifier = (algorithm: SigningAlgorithm, base: Uint8Array, signature: Uint8Array, context: Context) => Result<boolean> | Promise<Result<boolean>>;
+/** A resolved algorithm and key or verification capability with optional identity. */
 export type ResolvedKey = Readonly<{
     algorithm: SigningAlgorithm;
     key?: PublicKey | KeyHandle | Verifier;
     verify?: Verifier;
     identity?: KeyIdentity;
 }>;
+/** Resolve a verification key from signature facts and an operation context. */
 export type KeyResolver = (facts: Readonly<{
     keyid: string | null;
     label: string;
     tag: string | null;
 }>, context: Context) => Result<ResolvedKey | null> | Promise<Result<ResolvedKey | null>>;
+/** Clock, age, skew, and expiration rules for signature freshness. */
 export type Freshness = Readonly<{
+    /** Return the current Unix time in seconds. */
     clock: () => number;
     maxAge: number | null;
     skew: number;
     requireExpires: boolean;
 }>;
+/** Digest algorithms and field section required for content verification. */
 export type ContentPolicy = Readonly<{
     kind: "content" | "representation";
     algorithms: readonly string[];
     section: "headers" | "trailers";
 }>;
+/** Nonce namespace, commitment, atomic store, and timeout rules. */
 export type ReplayPolicy = Readonly<{
     identifier: "nonce";
     namespace: Uint8Array;
+    /** Derive caller-owned replay commitment bytes from verified facts. */
     commitment: (facts: ReplayFacts, context: Context) => Result<Uint8Array> | Promise<Result<Uint8Array>>;
     store: ReplayStore;
     timeoutMs: number;
 }>;
+/** A branded verification policy with explicit key, freshness, content, and replay rules. */
 export type Policy = Readonly<{
     algorithms: readonly SigningAlgorithm[];
     components: InnerList;
@@ -48,8 +57,14 @@ export type Policy = Readonly<{
     maxSignatures: number;
 }>;
 export declare function fieldSchemas(input: unknown): Result<Readonly<Record<string, Schema>>>;
+/** Check the private brand of a verification policy. */
 export declare function isPolicy(value: unknown): value is Policy;
+/** Internal shared freshness boundary for policies and extension preflight. */
+export declare function normalizeFreshness(input: unknown): Freshness | "not_evaluated";
+/** Snapshot, validate, and brand an explicit verification policy. */
 export declare function createPolicy(input: unknown): Result<Policy>;
+/** Verification policy construction. */
 export declare const Policy: Readonly<{
+    /** Snapshot, validate, and brand an explicit verification policy. */
     create: typeof createPolicy;
 }>;

package/dist/policy.js

@@ -53,9 +53,33 @@ export function fieldSchemas(input) {
         return err(bounded(e, "invalid_policy", "input"));
     }
 }
+/** Check the private brand of a verification policy. */
 export function isPolicy(value) {
     return typeof value === "object" && value !== null && policies.has(value);
 }
+/** Internal shared freshness boundary for policies and extension preflight. */
+export function normalizeFreshness(input) {
+    if (input === "not_evaluated")
+        return input;
+    const f = snapshot(input, [
+        "clock",
+        "maxAge",
+        "skew",
+        "requireExpires",
+    ]);
+    ensure(Object.keys(f).length === 4 &&
+        typeof f.clock === "function" &&
+        (f.maxAge === null || integer(f.maxAge, 1, CLOCK_MAX_SECONDS)) &&
+        integer(f.skew, 0, FRESHNESS_MAX_SKEW_SECONDS) &&
+        typeof f.requireExpires === "boolean", "invalid_policy", "input");
+    return Object.freeze({
+        clock: f.clock,
+        maxAge: f.maxAge,
+        skew: f.skew,
+        requireExpires: f.requireExpires,
+    });
+}
+/** Snapshot, validate, and brand an explicit verification policy. */
 export function createPolicy(input) {
     try {
         const a = snapshot(input, [
@@ -80,26 +104,7 @@ export function createPolicy(input) {
         const algorithms = algorithmList(a.algorithms), components = inner(a.components);
         ensure(components.ok && components.value.parameters.length === 0, "invalid_policy", "input");
         ensure(typeof a.keyResolver === "function", "invalid_policy", "input");
-        let freshness = "not_evaluated";
-        if (a.freshness !== "not_evaluated") {
-            const f = snapshot(a.freshness, [
-                "clock",
-                "maxAge",
-                "skew",
-                "requireExpires",
-            ]);
-            ensure(Object.keys(f).length === 4 &&
-                typeof f.clock === "function" &&
-                (f.maxAge === null || integer(f.maxAge, 1, CLOCK_MAX_SECONDS)) &&
-                integer(f.skew, 0, FRESHNESS_MAX_SKEW_SECONDS) &&
-                typeof f.requireExpires === "boolean", "invalid_policy", "input");
-            freshness = Object.freeze({
-                clock: f.clock,
-                maxAge: f.maxAge,
-                skew: f.skew,
-                requireExpires: f.requireExpires,
-            });
-        }
+        const freshness = normalizeFreshness(a.freshness);
         let content = "not_required";
         if (a.content !== "not_required") {
             const c = snapshot(a.content, ["kind", "algorithms", "section"]);
@@ -171,4 +176,8 @@ export function createPolicy(input) {
         return err(bounded(e, "invalid_policy", "input"));
     }
 }
-export const Policy = Object.freeze({ create: createPolicy });
+/** Verification policy construction. */
+export const Policy = Object.freeze({
+    /** Snapshot, validate, and brand an explicit verification policy. */
+    create: createPolicy
+});

package/dist/profile.d.ts

@@ -0,0 +1,36 @@
+import { type Result } from "./result.ts";
+import { type InnerList, type Item } from "./structured-fields/index.ts";
+import type { Verification, FreshnessFacts } from "./verification.ts";
+/** Descriptive extension selection; source-specific enforcement belongs to the extension. */
+export type ProfileMetadataValue = string | boolean | null | number;
+/** A namespaced extension profile name and bounded public metadata. */
+export type ProfileStamp<MetadataKey extends string = never> = Readonly<{
+    name: readonly [packageName: string, kind: string];
+}> & Readonly<Record<Exclude<MetadataKey, "name">, ProfileMetadataValue>>;
+/** Paired parsed Signature-Input and Signature dictionaries. */
+export type SignatureDictionaries = readonly [
+    readonly (readonly [string, InnerList])[],
+    Readonly<Record<string, Item>>
+];
+/** The predicate checks signature semantics, not wire grammar or key trust. */
+declare function validSignatureInput(input: unknown): boolean;
+/** Parse paired Signature-Input and Signature dictionaries within the member limit. */
+declare function dictionaries(message: unknown, max: number): Result<SignatureDictionaries>;
+/** Validate covered components and signature freshness before verification. */
+declare function preflight(input: unknown, components: unknown, extra: "allow" | "reject", freshness: unknown): Promise<Result<FreshnessFacts | "not_evaluated">>;
+/** Verify a selected signature label under an explicit extension profile stamp. */
+declare function verifyLabel<K extends string>(message: unknown, policy: unknown, selectedLabel: unknown, input: unknown, signature: unknown, stamp: ProfileStamp<K>): Promise<Result<Verification>>;
+/** Verify a selected signature label under an explicit extension profile stamp. */
+declare function verifyLabel(message: unknown, policy: unknown, selectedLabel: unknown, input: unknown, signature: unknown, stamp: unknown): Promise<Result<Verification>>;
+/** Unstable extension boundary. Pin the package exactly and keep profile names constant. */
+export declare const Profile: Readonly<{
+    /** Check the brand and shape of a signature-input inner list. */
+    validSignatureInput: typeof validSignatureInput;
+    /** Parse paired Signature-Input and Signature dictionaries within the member limit. */
+    dictionaries: typeof dictionaries;
+    /** Validate covered components and signature freshness before verification. */
+    preflight: typeof preflight;
+    /** Verify a selected signature label under an explicit extension profile stamp. */
+    verifyLabel: typeof verifyLabel;
+}>;
+export {};

package/dist/profile.js

@@ -0,0 +1,215 @@
+import { encodeUtf8 } from "./runtime.js";
+import { isMessage, Message } from "./message/index.js";
+import { isPolicy, normalizeFreshness } from "./policy.js";
+import { withDeadline, releaseContext } from "./context.js";
+import { SF_MAX_INTEGER, SIGNATURE_MAX_BYTES, STRUCTURED_FIELDS_LIMITS, PROFILE_MAX_ATOM_CODE_POINTS, PROFILE_MAX_MEMBERS, PROFILE_MAX_VALUE_BYTES } from "./constants.js";
+import { dictionaries as parseDictionaries, validInner, inner, label, ensure } from "./signature-fields.js";
+import { verifyLabel as authenticateLabel, authenticationPreflight } from "./verify.js";
+import { coreError, isRequestSealError } from "./errors/types.js";
+import { ok, err } from "./result.js";
+import { decimalSource } from "./structured-fields/index.js";
+const reserved = new Set(["request_seal", "request-seal", "rfc9421", "web_bot_auth", "web-bot-auth"]);
+function stampString(value, max) {
+    if (value.length > max * 2)
+        return false;
+    let count = 0;
+    for (const point of value) {
+        const code = point.codePointAt(0);
+        if (code >= 0xd800 && code <= 0xdfff || ++count > max)
+            return false;
+    }
+    return true;
+}
+function plain(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Read the dynamic metadata vocabulary once, without retaining caller objects. */
+function snapshotStamp(value) {
+    ensure(plain(value), "invalid_profile", "input");
+    const keys = Reflect.ownKeys(value);
+    ensure(keys.length <= PROFILE_MAX_MEMBERS && keys.includes("name") && keys.every(k => typeof k === "string" && stampString(k, PROFILE_MAX_ATOM_CODE_POINTS)), "invalid_profile", "input");
+    const ordered = ["name", ...keys.filter(k => k !== "name").sort()];
+    const owned = Object.create(null);
+    for (const key of ordered)
+        owned[key] = value[key];
+    const name = owned.name;
+    ensure(Array.isArray(name), "invalid_profile", "input");
+    const nameKeys = Reflect.ownKeys(name);
+    ensure(nameKeys.length === 3 && nameKeys.includes("length") && nameKeys.includes("0") && nameKeys.includes("1") && name.length === 2, "invalid_profile", "input");
+    const packageName = name[0], kind = name[1];
+    ensure(typeof packageName === "string" && stampString(packageName, PROFILE_MAX_ATOM_CODE_POINTS) && typeof kind === "string" && stampString(kind, PROFILE_MAX_ATOM_CODE_POINTS) && !reserved.has(packageName), "invalid_profile", "input");
+    for (const key of keys) {
+        if (key === "name")
+            continue;
+        const v = owned[key];
+        ensure(v === null || typeof v === "boolean" ||
+            (typeof v === "number" && Number.isSafeInteger(v) && Math.abs(v) <= SF_MAX_INTEGER) ||
+            (typeof v === "string" && stampString(v, PROFILE_MAX_VALUE_BYTES) && encodeUtf8(v).length <= PROFILE_MAX_VALUE_BYTES), "invalid_profile", "input");
+        if (typeof v === "number" && Object.is(v, -0))
+            owned[key] = 0;
+    }
+    owned.name = Object.freeze([packageName, kind]);
+    // Sorted insertion gives equal stamps one key order; JavaScript lists array-index keys first.
+    return Object.freeze(owned);
+}
+function protectedError(e) {
+    return isRequestSealError(e) ? e : coreError("invalid_policy", "input");
+}
+/** The predicate checks signature semantics, not wire grammar or key trust. */
+function validSignatureInput(input) {
+    try {
+        return validInner(input);
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse paired Signature-Input and Signature dictionaries within the member limit. */
+function dictionaries(message, max) {
+    try {
+        ensure(isMessage(message) && Number.isSafeInteger(max) && max >= 1 && max <= STRUCTURED_FIELDS_LIMITS.maxMembers, "invalid_policy", "input");
+        const [inputs, signatures] = paired(message, max);
+        const entries = Object.freeze([...inputs].map(([k, v]) => Object.freeze([k, v])));
+        const lookup = Object.create(null);
+        for (const [key, value] of signatures)
+            lookup[key] = value;
+        return ok(Object.freeze([entries, Object.freeze(lookup)]));
+    }
+    catch (e) {
+        return err(protectedError(e));
+    }
+}
+function paired(message, max) {
+    const values = parseDictionaries(message, max);
+    const [inputs, signatures] = values;
+    ensure(inputs.size === signatures.size && [...inputs.keys()].every(k => signatures.has(k)), "label_mismatch", "fields");
+    return values;
+}
+/** Validate covered components and signature freshness before verification. */
+async function preflight(input, components, extra, freshness) {
+    try {
+        const required = inner(components);
+        if (!required.ok)
+            throw required.error.reason === "limit" ? coreError("limit", "input") : coreError("invalid_signature_input", "fields");
+        ensure(extra === "allow" || extra === "reject", "invalid_policy", "input");
+        const context = withDeadline();
+        if (!context.ok)
+            throw context.error;
+        try {
+            return ok(await authenticationPreflight(input, required.value, extra, () => normalizeFreshness(freshness), context.value));
+        }
+        finally {
+            releaseContext(context.value);
+        }
+    }
+    catch (e) {
+        return err(protectedError(e));
+    }
+}
+/** Expected parser structure bounds traversal; unknown keys cannot hide extra values.
+ * Ordered parameters/components and decoded byte equality mirror the reference values.
+ * Each caller property is read once, independent of object insertion order or identity.
+ */
+function equalParsed(actual, expected) {
+    if (expected === null || typeof expected !== "object")
+        return actual === expected;
+    if (expected instanceof Uint8Array) {
+        if (!(actual instanceof Uint8Array) || actual.length !== expected.length)
+            return false;
+        const bytes = new Uint8Array(actual);
+        return bytes.every((b, i) => b === expected[i]);
+    }
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual))
+            return false;
+        const keys = Reflect.ownKeys(actual);
+        if (actual.length !== expected.length || keys.length !== expected.length + 1 || !keys.includes("length"))
+            return false;
+        for (let i = 0; i < expected.length; i++)
+            if (!Object.hasOwn(actual, String(i)) || !equalParsed(actual[i], expected[i]))
+                return false;
+        return true;
+    }
+    if (!plain(actual))
+        return false;
+    const keys = Reflect.ownKeys(actual), expectedKeys = Object.keys(expected);
+    if (keys.length !== expectedKeys.length || !keys.every(k => typeof k === "string" && Object.hasOwn(expected, k)))
+        return false;
+    const fields = Object.create(null);
+    for (const key of expectedKeys)
+        fields[key] = actual[key];
+    const parsed = expected;
+    if (parsed.kind === "decimal") {
+        if (fields.kind !== "decimal")
+            return false;
+        const selected = decimalParts(actual, fields.value);
+        const authoritative = decimalParts(expected, parsed.value, decimalSource(actual) !== undefined);
+        return selected !== null && authoritative !== null && selected[0] === authoritative[0] && selected[1] === authoritative[1];
+    }
+    for (const key of expectedKeys)
+        if (!equalParsed(fields[key], parsed[key]))
+            return false;
+    return true;
+}
+/** Parsed decimals retain source coefficient/scale separately from numeric normalization.
+ * Leading zero and negative-zero spellings do not change the reference integer coefficient.
+ */
+function decimalParts(node, value, useSource = true) {
+    if (!plain(value))
+        return null;
+    const keys = Reflect.ownKeys(value);
+    if (keys.length !== 2 || !keys.includes("scaled") || !keys.includes("scale"))
+        return null;
+    const scaled = value.scaled, scale = value.scale;
+    if (!(typeof scaled === "bigint" || typeof scaled === "number" && Number.isSafeInteger(scaled)) || typeof scale !== "number" || !Number.isSafeInteger(scale) || scale < 1 || scale > 3)
+        return null;
+    const source = useSource ? decimalSource(node) : undefined;
+    return source === undefined ? [BigInt(scaled), scale] : [BigInt(source.replace(".", "")), source.length - source.indexOf(".") - 1];
+}
+function signatureSnapshot(value) {
+    ensure(plain(value), "invalid_signature_field", "fields");
+    const keys = Reflect.ownKeys(value);
+    ensure(keys.length === 3 && keys.every(k => typeof k === "string" && ["kind", "value", "parameters"].includes(k)), "invalid_signature_field", "fields");
+    const kind = value.kind, bare = value.value, parameters = value.parameters;
+    ensure(kind === "item" && plain(bare), "invalid_signature_field", "fields");
+    const bareKeys = Reflect.ownKeys(bare);
+    ensure(bareKeys.length === 2 && bareKeys.includes("kind") && bareKeys.includes("value"), "invalid_signature_field", "fields");
+    const bareKind = bare.kind, bytes = bare.value;
+    ensure(bareKind === "bytes" && bytes instanceof Uint8Array && bytes.length >= 1 && bytes.length <= SIGNATURE_MAX_BYTES, "invalid_signature_field", "fields");
+    return { kind: "item", value: { kind: "bytes", value: new Uint8Array(bytes) }, parameters: parameters };
+}
+/** Verify a selected signature label under an explicit extension profile stamp. */
+async function verifyLabel(message, policy, selectedLabel, input, signature, stamp) {
+    try {
+        const profile = snapshotStamp(stamp);
+        ensure(isPolicy(policy), "invalid_policy", "input");
+        ensure(label(selectedLabel), "invalid_options", "input");
+        ensure(isMessage(message), "invalid_message", "input");
+        const validated = Message.create(message);
+        ensure(validated.ok, "invalid_message", "input");
+        const selectedSignature = signatureSnapshot(signature);
+        const [inputs, signatures] = paired(validated.value, policy.maxSignatures);
+        ensure(inputs.has(selectedLabel), "unknown_label", "fields");
+        const selectedInput = inputs.get(selectedLabel);
+        ensure(equalParsed(input, selectedInput), "invalid_signature_input", "fields");
+        ensure(equalParsed(selectedSignature, signatures.get(selectedLabel)), "invalid_signature_field", "fields");
+        return await authenticateLabel(validated.value, policy, { label: selectedLabel }, undefined, { input: selectedInput, signature: signatures.get(selectedLabel), baseCache: new Map() }, profile);
+    }
+    catch (e) {
+        return err(protectedError(e));
+    }
+}
+/** Unstable extension boundary. Pin the package exactly and keep profile names constant. */
+export const Profile = Object.freeze({
+    /** Check the brand and shape of a signature-input inner list. */
+    validSignatureInput,
+    /** Parse paired Signature-Input and Signature dictionaries within the member limit. */
+    dictionaries,
+    /** Validate covered components and signature freshness before verification. */
+    preflight,
+    /** Verify a selected signature label under an explicit extension profile stamp. */
+    verifyLabel
+});

package/dist/public_key.d.ts

@@ -1,23 +1,32 @@
 import { type Result } from './result.ts';
 import { type Jwk } from './custody/jwk.ts';
+/** Check the private brand of a public key. */
 export declare function isPublicKey(value: unknown): value is PublicKey;
 /** Public components only. Metadata restrictions survive every use and export. */
 export declare class PublicKey {
     #private;
     private constructor();
+    /** Import public JWK, PEM, or SPKI material without discarding metadata restrictions. */
     static import(material: unknown, format?: 'jwk' | 'pem' | 'spki' | 'der'): Promise<Result<PublicKey>>;
+    /** Export a defensive copy of the public JWK and its metadata restrictions. */
     jwk(): Result<Jwk>;
+    /** Export public SPKI bytes when metadata restrictions permit a lossless export. */
     spki(): Result<Uint8Array<ArrayBuffer>>;
+    /** Export public SPKI PEM when metadata restrictions permit a lossless export. */
     pem(): Result<string>;
+    /** Compute the public key thumbprint defined by RFC 7638. */
     thumbprint(): Promise<Result<string>>;
     /** Internal equivalence ignores PSS-only type and JWK metadata. */
     identityBytes(): Result<Uint8Array<ArrayBuffer>>;
+    /** Check compatibility and metadata permission for the selected algorithm. */
     bind(algorithm: unknown): Result<true>;
-    verify(algorithm: unknown, signature: unknown, data: unknown): Promise<Result<true>>;
+    /** Verify a signature with bounded input and preserved key metadata restrictions. */
+    verify(algorithm: unknown, signature: unknown, data: unknown, options?: unknown): Promise<Result<true>>;
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON(): Readonly<{
         kind: string;
         pssOnly: boolean;
     }>;
 }
-export declare function verifyPublicKey(key: PublicKey, algorithm: unknown, signature: unknown, data: unknown): Promise<Result<true>>;
+export declare function verifyPublicKey(key: PublicKey, algorithm: unknown, signature: unknown, data: unknown, maximum?: number): Promise<Result<true>>;
 export declare function bindPublicKey(key: PublicKey, algorithm: unknown): Result<true>;

package/dist/public_key.js

@@ -1,14 +1,19 @@
+import { denoInspection } from './brand.js';
+import { byteLimit } from './crypto/options.js';
+import { CRYPTO_DEFAULT_MAX_BYTES } from './constants.js';
 import { encodeUtf8 } from './runtime.js';
 import { ok, err } from './result.js';
 import { cryptoError } from './errors/types.js';
 import { encodeBase64Url } from './bytes.js';
 import { resolveAlgorithm, importParameters, } from './crypto/algorithm.js';
 import * as subtle from './crypto/subtle.js';
-import { verifyKey } from './crypto/primitive.js';
+import { boundedData, verifyKey } from './crypto/primitive.js';
 import { decodeKey, publicSpki, writePem } from './custody/der.js';
 import { snapshotJwk, publicMembers, compatible, permitted, } from './custody/jwk.js';
+const verifiers = new WeakMap();
 const branded = new WeakSet();
 const token = Object.freeze({});
+/** Check the private brand of a public key. */
 export function isPublicKey(value) {
     return typeof value === 'object' && value !== null && branded.has(value);
 }
@@ -23,9 +28,11 @@ export class PublicKey {
         this.#jwk = jwk;
         this.#pssOnly = pssOnly;
         this.#spki = new Uint8Array(spki);
+        verifiers.set(this, this.#verify.bind(this));
         branded.add(this);
         Object.freeze(this);
     }
+    /** Import public JWK, PEM, or SPKI material without discarding metadata restrictions. */
     static async import(material, format = 'jwk') {
         try {
             let jwk, pssOnly = false;
@@ -76,16 +83,19 @@ export class PublicKey {
             return err(cryptoError('invalid_key'));
         }
     }
+    /** Export a defensive copy of the public JWK and its metadata restrictions. */
     jwk() {
         return this.#pssOnly
             ? err(cryptoError('unsupported_format'))
             : ok(this.#jwk);
     }
+    /** Export public SPKI bytes when metadata restrictions permit a lossless export. */
     spki() {
         return ['alg', 'use', 'key_ops'].some((k) => Object.hasOwn(this.#jwk, k))
             ? err(cryptoError('unsupported_format'))
             : ok(new Uint8Array(this.#spki));
     }
+    /** Export public SPKI PEM when metadata restrictions permit a lossless export. */
     pem() {
         const r = this.spki();
         if (!r.ok)
@@ -93,6 +103,7 @@ export class PublicKey {
         const p = writePem('PUBLIC KEY', r.value);
         return p.ok ? p : err(cryptoError('invalid_key'));
     }
+    /** Compute the public key thumbprint defined by RFC 7638. */
     async thumbprint() {
         try {
             return ok(encodeBase64Url(new Uint8Array(await subtle.digest('SHA-256', encodeUtf8(JSON.stringify(publicMembers(this.#jwk)))))));
@@ -105,6 +116,7 @@ export class PublicKey {
     identityBytes() {
         return ok(encodeUtf8(JSON.stringify(publicMembers(this.#jwk))));
     }
+    /** Check compatibility and metadata permission for the selected algorithm. */
     bind(algorithm) {
         const resolved = resolveAlgorithm(algorithm, true);
         if (!resolved.ok)
@@ -118,38 +130,49 @@ export class PublicKey {
             ? ok(true)
             : err(cryptoError('key_mismatch'));
     }
-    async verify(algorithm, signature, data) {
+    /** Verify a signature with bounded input and preserved key metadata restrictions. */
+    async verify(algorithm, signature, data, options = {}) {
+        const maximum = byteLimit(options);
+        if (!maximum.ok)
+            return maximum;
+        return this.#verify(algorithm, signature, data, maximum.value);
+    }
+    async #verify(algorithm, signature, data, maximum) {
         const resolved = resolveAlgorithm(algorithm);
         if (!resolved.ok)
             return resolved;
         const spec = resolved.value;
+        // Same order as Crypto.verify: options, algorithm, data bound, then key compatibility.
+        if (!boundedData(data, maximum))
+            return err(cryptoError('invalid_data'));
         try {
             if (!compatible(this.#jwk, spec, this.#pssOnly) ||
                 !permitted(this.#jwk, spec, 'verify'))
                 return err(cryptoError('key_mismatch'));
             const key = await subtle.importKey('jwk', publicMembers(this.#jwk), importParameters(spec), false, ['verify']);
-            return await verifyKey(spec, key, signature, data);
+            return await verifyKey(spec, key, signature, data, maximum);
         }
         catch {
             return err(cryptoError('invalid_key'));
         }
     }
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON() {
         return Object.freeze({ kind: 'PublicKey', pssOnly: this.#pssOnly });
     }
     [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.toJSON();
     }
-    [Symbol.for('Deno.customInspect')]() {
-        return this.toJSON();
+    [Symbol.for('Deno.customInspect')](render) {
+        return denoInspection(render, this.toJSON());
     }
 }
 Object.freeze(PublicKey.prototype);
 Object.freeze(PublicKey);
-const publicVerify = Function.prototype.call.bind(PublicKey.prototype.verify);
 const publicBind = Function.prototype.call.bind(PublicKey.prototype.bind);
-export function verifyPublicKey(key, algorithm, signature, data) {
-    return publicVerify(key, algorithm, signature, data);
+export function verifyPublicKey(key, algorithm, signature, data, maximum = CRYPTO_DEFAULT_MAX_BYTES) {
+    const verify = verifiers.get(key);
+    return verify ? verify(algorithm, signature, data, maximum) : Promise.resolve(err(cryptoError('invalid_key')));
 }
 export function bindPublicKey(key, algorithm) {
     return publicBind(key, algorithm);