@request-seal/core 0.1.0 → 0.3.0

package/dist/custody/ssh-agent/index.js

@@ -1,185 +1,11 @@
-import { connect } from "node:net";
 import { snapshotOptions } from "../../brand.js";
-import { withDeadline, isContext, run } from "../../context.js";
-import { custodyError, isRequestSealError } from "../../errors/types.js";
-import { createKeyHandle, } from "../../key_handle.js";
-import { KeyIdentity } from "../../key_identity.js";
-import { isPublicKey, bindPublicKey, verifyPublicKey, } from "../../public_key.js";
-import { resolveAlgorithm, selection, } from "../../crypto/algorithm.js";
+import { withDeadline, isContext } from "../../context.js";
+import { custodyError } from "../../errors/types.js";
+import { createKeyHandle } from "../../key_handle.js";
+import { isPublicKey, bindPublicKey } from "../../public_key.js";
+import { resolveAlgorithm, selection } from "../../crypto/algorithm.js";
 import { ok, err } from "../../result.js";
-import { MAX_FRAME, uint32, string, identities, signature, keyBlob, } from "./wire.js";
-function failure(e) {
-    return err(isRequestSealError(e) && e.kind === "custody"
-        ? e
-        : custodyError("custodian_protocol"));
-}
-class AgentPort {
-    #path;
-    #public;
-    #spec;
-    #blob;
-    #live = true;
-    #sockets = new Set();
-    constructor(path, publicKey, spec) {
-        this.#path = path;
-        this.#public = publicKey;
-        this.#spec = spec;
-        this.#blob = keyBlob(publicKey);
-        Object.freeze(this);
-    }
-    async #connect(c) {
-        return new Promise((resolve) => {
-            const s = connect(this.#path);
-            this.#sockets.add(s);
-            let settled = false;
-            const done = (r) => {
-                if (settled)
-                    return;
-                settled = true;
-                s.removeListener("error", error);
-                c.signal.removeEventListener("abort", abort);
-                resolve(r);
-            };
-            const abort = () => {
-                s.destroy();
-                done(err(custodyError("deadline_exceeded")));
-            };
-            const error = (e) => {
-                s.destroy();
-                done(err(custodyError(["ENOENT", "ECONNREFUSED", "ECONNRESET"].includes(e.code ?? "")
-                    ? "custodian_unavailable"
-                    : "custodian_failure")));
-            };
-            s.once("close", () => this.#sockets.delete(s));
-            s.once("error", error);
-            s.once("connect", () => done(ok(s)));
-            c.signal.addEventListener("abort", abort, { once: true });
-            if (c.signal.aborted)
-                abort();
-        });
-    }
-    async #exchange(socket, request, c) {
-        return new Promise((resolve) => {
-            let buffer = Buffer.alloc(0), settled = false;
-            const done = (r) => {
-                if (settled)
-                    return;
-                settled = true;
-                socket.removeListener("data", data);
-                socket.removeListener("error", error);
-                socket.removeListener("end", error);
-                socket.removeListener("close", error);
-                c.signal.removeEventListener("abort", abort);
-                resolve(r);
-            };
-            const error = () => done(err(custodyError("custodian_protocol")));
-            const abort = () => {
-                socket.destroy();
-                done(err(custodyError("deadline_exceeded")));
-            };
-            const data = (chunk) => {
-                if (buffer.length + chunk.length > MAX_FRAME + 4) {
-                    socket.destroy();
-                    error();
-                    return;
-                }
-                buffer = Buffer.concat([buffer, chunk]);
-                if (buffer.length < 4)
-                    return;
-                const length = buffer.readUInt32BE(0);
-                if (length < 1 || length > MAX_FRAME || buffer.length > length + 4) {
-                    socket.destroy();
-                    error();
-                    return;
-                }
-                if (buffer.length === length + 4)
-                    done(ok(new Uint8Array(buffer.subarray(4))));
-            };
-            socket.on("data", data);
-            socket.once("error", error);
-            socket.once("end", error);
-            socket.once("close", error);
-            c.signal.addEventListener("abort", abort, { once: true });
-            if (c.signal.aborted) {
-                abort();
-                return;
-            }
-            if (request.length > MAX_FRAME) {
-                done(err(custodyError("limit")));
-                return;
-            }
-            socket.write(Buffer.concat([uint32(request.length), request]), (e) => {
-                if (e)
-                    error();
-            });
-        });
-    }
-    async possession(c, initial = false) {
-        return this.#sign(new Uint8Array(), c, initial);
-    }
-    async #sign(data, c, initial = false) {
-        return run(c, async () => {
-            if (!this.#live)
-                return err(custodyError("key_not_found"));
-            const connected = await this.#connect(c);
-            if (!connected.ok)
-                return connected;
-            const socket = connected.value;
-            try {
-                const reply = await this.#exchange(socket, Buffer.from([11]), c);
-                if (!reply.ok)
-                    return reply;
-                const keys = identities(reply.value);
-                if (!keys.some((k) => k.equals(this.#blob)))
-                    return err(custodyError(initial ? "custodian_rejected" : "key_not_found"));
-                const signed = await this.#exchange(socket, Buffer.concat([
-                    Buffer.from([13]),
-                    string(this.#blob),
-                    string(data),
-                    uint32(this.#spec.jose === "RS256" ? 2 : 0),
-                ]), c);
-                if (!signed.ok)
-                    return signed;
-                const raw = signature(signed.value, this.#spec, this.#public);
-                const checked = await verifyPublicKey(this.#public, selection(this.#spec), raw, data);
-                if (!checked.ok) {
-                    raw.fill(0);
-                    return err(custodyError("custodian_rejected"));
-                }
-                return ok(raw);
-            }
-            catch (e) {
-                return failure(e);
-            }
-            finally {
-                socket.destroy();
-            }
-        });
-    }
-    async sign(_algorithm, data, c) {
-        if (!(data instanceof Uint8Array))
-            return err(custodyError("invalid_data"));
-        return this.#sign(new Uint8Array(data), c);
-    }
-    async verify(algorithm, sig, data, _c) {
-        return verifyPublicKey(this.#public, algorithm, sig, data);
-    }
-    async publicKey() {
-        return ok(this.#public);
-    }
-    async identity() {
-        return KeyIdentity.fromPublic(this.#public);
-    }
-    async unwrap() {
-        return err(custodyError("unsupported_operation"));
-    }
-    async release() {
-        this.#live = false;
-        for (const s of this.#sockets)
-            s.destroy();
-        return ok(true);
-    }
-}
+import { AgentPort, failure } from "./port.js";
 /** Caller-selected local socket and trusted public components; no environment discovery. */
 export async function createSshAgent(algorithm, socketPath, publicKey, options = {}) {
     try {
@@ -225,4 +51,8 @@ export async function createSshAgent(algorithm, socketPath, publicKey, options =
         return failure(e);
     }
 }
-export const SSHAgent = Object.freeze({ create: createSshAgent });
+/** Caller-selected OpenSSH agent custody construction. */
+export const SSHAgent = Object.freeze({
+    /** Bind an algorithm and public key to a caller-selected OpenSSH agent socket. */
+    create: createSshAgent
+});

package/dist/custody/ssh-agent/port.d.ts

@@ -0,0 +1,19 @@
+import { type Context } from "../../context.ts";
+import { type Custodian } from "../../key_handle.ts";
+import { KeyIdentity } from "../../key_identity.ts";
+import { type PublicKey } from "../../public_key.ts";
+import { type Spec } from "../../crypto/algorithm.ts";
+import { type Result } from "../../result.ts";
+export declare function failure<T>(e: unknown): Result<T>;
+/** @internal Direct custodian implementation; use the public factory for handles. */
+export declare class AgentPort implements Custodian {
+    #private;
+    constructor(path: string, publicKey: PublicKey, spec: Spec);
+    possession(c: Context, initial?: boolean): Promise<Result<Uint8Array<ArrayBuffer>>>;
+    sign(_algorithm: unknown, data: unknown, c: Context): Promise<Result<Uint8Array<ArrayBuffer>>>;
+    verify(algorithm: unknown, sig: unknown, data: unknown, _c: Context): Promise<Result<true>>;
+    publicKey(): Promise<Result<PublicKey>>;
+    identity(): Promise<Result<KeyIdentity>>;
+    unwrap(): Promise<ReturnType<Custodian["unwrap"]> extends Promise<infer T> ? T : never>;
+    release(): Promise<Result<true>>;
+}

package/dist/custody/ssh-agent/port.js

@@ -0,0 +1,183 @@
+import { CRYPTO_MAX_BYTES_CEILING } from "../../constants.js";
+import { boundedBinary } from "../../crypto/primitive.js";
+import { connect } from "node:net";
+import { run } from "../../context.js";
+import { custodyError, isRequestSealError } from "../../errors/types.js";
+import { KeyIdentity } from "../../key_identity.js";
+import { verifyPublicKey, } from "../../public_key.js";
+import { selection, } from "../../crypto/algorithm.js";
+import { ok, err } from "../../result.js";
+import { MAX_FRAME, uint32, string, identities, signature, keyBlob, } from "./wire.js";
+export function failure(e) {
+    return err(isRequestSealError(e) && e.kind === "custody"
+        ? e
+        : custodyError("custodian_protocol"));
+}
+/** @internal Direct custodian implementation; use the public factory for handles. */
+export class AgentPort {
+    #path;
+    #public;
+    #spec;
+    #blob;
+    #live = true;
+    #sockets = new Set();
+    constructor(path, publicKey, spec) {
+        this.#path = path;
+        this.#public = publicKey;
+        this.#spec = spec;
+        this.#blob = keyBlob(publicKey);
+        Object.freeze(this);
+    }
+    async #connect(c) {
+        return new Promise((resolve) => {
+            const s = connect(this.#path);
+            this.#sockets.add(s);
+            let settled = false;
+            const done = (r) => {
+                if (settled)
+                    return;
+                settled = true;
+                s.removeListener("error", error);
+                c.signal.removeEventListener("abort", abort);
+                resolve(r);
+            };
+            const abort = () => {
+                s.destroy();
+                done(err(custodyError("deadline_exceeded")));
+            };
+            const error = (e) => {
+                s.destroy();
+                done(err(custodyError(["ENOENT", "ECONNREFUSED", "ECONNRESET"].includes(e.code ?? "")
+                    ? "custodian_unavailable"
+                    : "custodian_failure")));
+            };
+            // A write error can arrive after an exchange has settled; keep it contained until close.
+            s.on("error", () => s.destroy());
+            s.once("close", () => this.#sockets.delete(s));
+            s.once("error", error);
+            s.once("connect", () => done(ok(s)));
+            c.signal.addEventListener("abort", abort, { once: true });
+            if (c.signal.aborted)
+                abort();
+        });
+    }
+    async #exchange(socket, request, c) {
+        return new Promise((resolve) => {
+            let buffer = Buffer.alloc(0), settled = false;
+            const done = (r) => {
+                if (settled)
+                    return;
+                settled = true;
+                socket.removeListener("data", data);
+                socket.removeListener("error", error);
+                socket.removeListener("end", error);
+                socket.removeListener("close", error);
+                c.signal.removeEventListener("abort", abort);
+                resolve(r);
+            };
+            const error = () => done(err(custodyError("custodian_protocol")));
+            const abort = () => {
+                socket.destroy();
+                done(err(custodyError("deadline_exceeded")));
+            };
+            const data = (chunk) => {
+                if (buffer.length + chunk.length > MAX_FRAME + 4) {
+                    socket.destroy();
+                    error();
+                    return;
+                }
+                buffer = Buffer.concat([buffer, chunk]);
+                if (buffer.length < 4)
+                    return;
+                const length = buffer.readUInt32BE(0);
+                if (length < 1 || length > MAX_FRAME || buffer.length > length + 4) {
+                    socket.destroy();
+                    error();
+                    return;
+                }
+                if (buffer.length === length + 4)
+                    done(ok(new Uint8Array(buffer.subarray(4))));
+            };
+            socket.on("data", data);
+            socket.once("error", error);
+            socket.once("end", error);
+            socket.once("close", error);
+            c.signal.addEventListener("abort", abort, { once: true });
+            if (c.signal.aborted) {
+                abort();
+                return;
+            }
+            socket.write(Buffer.concat([uint32(request.length), request]), (e) => {
+                if (e)
+                    error();
+            });
+        });
+    }
+    async possession(c, initial = false) {
+        return this.#sign(new Uint8Array(), c, initial);
+    }
+    async #sign(data, c, initial = false) {
+        return run(c, async () => {
+            if (!this.#live)
+                return err(custodyError("key_not_found"));
+            const connected = await this.#connect(c);
+            if (!connected.ok)
+                return connected;
+            const socket = connected.value;
+            try {
+                const reply = await this.#exchange(socket, Buffer.from([11]), c);
+                if (!reply.ok)
+                    return reply;
+                const keys = identities(reply.value);
+                if (!keys.some((k) => k.equals(this.#blob)))
+                    return err(custodyError(initial ? "custodian_rejected" : "key_not_found"));
+                const signed = await this.#exchange(socket, Buffer.concat([
+                    Buffer.from([13]),
+                    string(this.#blob),
+                    string(data),
+                    uint32(this.#spec.jose === "RS256" ? 2 : 0),
+                ]), c);
+                if (!signed.ok)
+                    return signed;
+                const raw = signature(signed.value, this.#spec, this.#public);
+                const checked = await verifyPublicKey(this.#public, selection(this.#spec), raw, data, CRYPTO_MAX_BYTES_CEILING);
+                if (!checked.ok) {
+                    raw.fill(0);
+                    return err(custodyError("custodian_rejected"));
+                }
+                return ok(raw);
+            }
+            catch (e) {
+                return failure(e);
+            }
+            finally {
+                socket.destroy();
+            }
+        });
+    }
+    async sign(_algorithm, data, c) {
+        if (!boundedBinary(data, CRYPTO_MAX_BYTES_CEILING))
+            return err(custodyError("invalid_data"));
+        return this.#sign(new Uint8Array(data), c);
+    }
+    async verify(algorithm, sig, data, _c) {
+        if (!boundedBinary(data, CRYPTO_MAX_BYTES_CEILING))
+            return err(custodyError("invalid_data"));
+        return verifyPublicKey(this.#public, algorithm, sig, data, CRYPTO_MAX_BYTES_CEILING);
+    }
+    async publicKey() {
+        return ok(this.#public);
+    }
+    async identity() {
+        return KeyIdentity.fromPublic(this.#public);
+    }
+    async unwrap() {
+        return err(custodyError("unsupported_operation"));
+    }
+    async release() {
+        this.#live = false;
+        for (const s of this.#sockets)
+            s.destroy();
+        return ok(true);
+    }
+}

package/dist/digest.d.ts

@@ -1,42 +1,64 @@
 import { type Dictionary } from "./structured-fields/index.ts";
 import { type Message } from "./message/index.ts";
 import { type Result } from "./result.ts";
+/** Supported content-digest algorithm identifiers. */
 export type DigestAlgorithm = "sha-256" | "sha-512";
+/** Content or representation digest field selection. */
 export type DigestKind = "content" | "representation";
+/** A caller-owned incremental hashing session. */
 export type HashSession = {
+    /** Hash an owned chunk while enforcing state and total byte limits. */
     update: (chunk: Uint8Array) => void | Promise<void>;
+    /** Finalize the selected digest algorithms into a canonical digest field. */
     finish: () => Uint8Array | Promise<Uint8Array>;
 };
 /** create, update, and finish must be own properties; bind class prototype methods explicitly. */
 export type IncrementalHasher = {
+    /** Create a bounded digest state after validating the incremental hasher. */
     create: (algorithm: DigestAlgorithm) => HashSession | Promise<HashSession>;
 };
+/** Verified digest kind, algorithms, section, and processed byte count. */
 export type DigestFacts = Readonly<{
     kind: "content-digest" | "repr-digest";
     checked: readonly string[];
     bytes: number;
     unsupported: readonly string[];
 }>;
+/** Parse a Content-Digest dictionary and validate its members. */
 export declare function parseDigest(bytes: unknown): Result<Dictionary>;
+/** Serialize and validate a digest dictionary. */
 export declare function serializeDigest(value: unknown): Result<Uint8Array>;
+/** Compute a canonical digest field for the selected algorithms. */
 export declare function digest(content: unknown, names: unknown, options?: unknown): Promise<Result<Uint8Array>>;
+/** Check the private brand of an incremental digest state. */
 export declare function isDigestState(value: unknown): value is DigestState;
+/** A branded, bounded incremental digest computation. */
 export declare class DigestState {
     #private;
     readonly kind: DigestKind;
     readonly maxBytes: number;
     constructor(t: object, kind: DigestKind, max: number, sessions: readonly (readonly [DigestAlgorithm, HashSession])[]);
     get bytes(): number;
+    /** Create a bounded digest state after validating the incremental hasher. */
     static create(kind: unknown, names: unknown, hasher: unknown, options?: unknown): Promise<Result<DigestState>>;
+    /** Hash an owned chunk while enforcing state and total byte limits. */
     update(chunk: unknown): Promise<Result<DigestState>>;
+    /** Finalize the selected digest algorithms into a canonical digest field. */
     finish(): Promise<Result<Uint8Array>>;
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON(): unknown;
 }
 export declare function digestField(message: Message, kind: DigestKind, section: "headers" | "trailers"): Result<Dictionary>;
+/** Check required digest fields against retained bytes or an incremental state. */
 export declare function checkDigest(message: unknown, kind: unknown, options?: unknown): Promise<Result<DigestFacts>>;
+/** Content-digest computation, parsing, serialization, and checking. */
 export declare const Digest: Readonly<{
+    /** Compute the selected content digests over owned body bytes. */
     content: typeof digest;
+    /** Parse and validate the supported wire representation. */
     parse: typeof parseDigest;
+    /** Serialize validated values to their canonical wire representation. */
     serialize: typeof serializeDigest;
+    /** Check required content digests against retained body bytes. */
     check: typeof checkDigest;
 }>;

package/dist/digest.js

@@ -89,10 +89,12 @@ function validate(value) {
         return err(error(e, "invalid_field"));
     }
 }
+/** Parse a Content-Digest dictionary and validate its members. */
 export function parseDigest(bytes) {
     const r = sfParse("dictionary", bytes, { schema });
     return r.ok ? validate(r.value) : r;
 }
+/** Serialize and validate a digest dictionary. */
 export function serializeDigest(value) {
     const r = sfSerialize(value, { schema });
     if (!r.ok)
@@ -100,6 +102,7 @@ export function serializeDigest(value) {
     const parsed = parseDigest(r.value);
     return parsed.ok ? r : parsed;
 }
+/** Compute a canonical digest field for the selected algorithms. */
 export async function digest(content, names, options = {}) {
     try {
         ensure(content instanceof Uint8Array, "invalid_body");
@@ -132,11 +135,13 @@ const knownAnswers = Object.freeze({
     ]),
 });
 const states = new WeakSet();
+/** Check the private brand of an incremental digest state. */
 export function isDigestState(value) {
     return typeof value === "object" && value !== null && states.has(value);
 }
 const token = Object.freeze({});
 const busySessions = new WeakSet();
+/** A branded, bounded incremental digest computation. */
 export class DigestState {
     kind;
     maxBytes;
@@ -157,6 +162,7 @@ export class DigestState {
     get bytes() {
         return this.#bytes;
     }
+    /** Create a bounded digest state after validating the incremental hasher. */
     static async create(kind, names, hasher, options = {}) {
         try {
             ensure(kind === "content" || kind === "representation", "invalid_kind");
@@ -226,6 +232,7 @@ export class DigestState {
             return err(error(e, "invalid_state"));
         }
     }
+    /** Hash an owned chunk while enforcing state and total byte limits. */
     async update(chunk) {
         try {
             ensure(isDigestState(this) && !this.#invalid && !this.#finished && !this.#busy, "invalid_state");
@@ -251,6 +258,7 @@ export class DigestState {
             return err(error(e, "invalid_state"));
         }
     }
+    /** Finalize the selected digest algorithms into a canonical digest field. */
     async finish() {
         try {
             ensure(isDigestState(this) && !this.#invalid && !this.#busy, "invalid_state");
@@ -283,6 +291,7 @@ export class DigestState {
             return err(error(e, "invalid_state"));
         }
     }
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON() {
         return { kind: this.kind, bytes: this.#bytes, maxBytes: this.maxBytes };
     }
@@ -297,6 +306,7 @@ export function digestField(message, kind, section) {
             : r;
     return validate(r.value);
 }
+/** Check required digest fields against retained bytes or an incremental state. */
 export async function checkDigest(message, kind, options = {}) {
     try {
         ensure(isMessage(message), "invalid_message");
@@ -362,9 +372,14 @@ export async function checkDigest(message, kind, options = {}) {
         return err(error(e, "invalid_state"));
     }
 }
+/** Content-digest computation, parsing, serialization, and checking. */
 export const Digest = Object.freeze({
+    /** Compute the selected content digests over owned body bytes. */
     content: digest,
+    /** Parse and validate the supported wire representation. */
     parse: parseDigest,
+    /** Serialize validated values to their canonical wire representation. */
     serialize: serializeDigest,
+    /** Check required content digests against retained body bytes. */
     check: checkDigest,
 });

package/dist/discovery/body.d.ts

@@ -1,15 +1,25 @@
 import { type Context } from "../context.ts";
 import { PublicKey } from "../public_key.ts";
-import { type HttpAlgorithm, type SigningAlgorithm } from "../crypto/algorithm.ts";
+import { type JwsAlgorithm, type SigningAlgorithm } from "../crypto/algorithm.ts";
 import { type Result } from "../result.ts";
 import { type DiscoverySource } from "./source.ts";
+/** Discovery proof status. @inline */
 export type Proof = "signed" | "unsigned" | "not_applicable";
+/** A conditional revalidation outcome: the stored representation is unchanged (RFC 9111 Section 4.3.4). */
+export type NotModified = Readonly<{
+    notModified: true;
+    etag: string;
+    fetchedAt: number;
+    expiresAt: number;
+}>;
+/** A branded resolved public key with origin, proof, and expiration facts. */
 export type Resolution = Readonly<{
     key: PublicKey;
     keyId: string;
     thumbprint: string;
     algorithm: SigningAlgorithm;
-    assertedAlgorithm: HttpAlgorithm | null;
+    /** The source's alg assertion normalized once at import to its JOSE name. */
+    assertedAlgorithm: JwsAlgorithm | null;
     origin: string;
     sourceType: DiscoverySource["type"];
     location: string;
@@ -18,9 +28,12 @@ export type Resolution = Readonly<{
     proof: Proof;
     revision: string | null;
 }>;
+/** Check the private brand of a discovery resolution. */
 export declare function isResolution(v: unknown): v is Resolution;
+/** Check the private brand of a discovery key set. */
 export declare function isKeySet(v: unknown): v is KeySet;
 export declare function resolution(data: Resolution): Resolution;
+/** A branded immutable discovery key set with bounded key lookup. */
 export type KeySet = Readonly<{
     source: DiscoverySource;
     origin: string;
@@ -29,10 +42,14 @@ export type KeySet = Readonly<{
     expiresAt: number;
     revision: string;
     proof: Proof;
+    /** The source's ETag validator, if it sent one; the cache revalidates with it. */
+    etag: string | null;
+    /** Resolve an eligible key by identifier, allowed algorithms, and current time. */
     lookup: (keyId: unknown, algorithms: unknown, now?: number) => Promise<Result<Resolution>>;
 }>;
 export declare function algorithmList(input: unknown): readonly SigningAlgorithm[];
 export declare function keySet(data: Omit<KeySet, "lookup">): KeySet;
+/** Resolve an eligible key by identifier, allowed algorithms, and current time. */
 export declare function lookup(set: unknown, kid: unknown, allowed: unknown, now?: number, transient?: boolean): Promise<Result<Resolution>>;
 export declare function bodyDocument(bytes: unknown, source: DiscoverySource): Record<string, unknown>;
 export declare function bodyKeys(doc: Record<string, unknown>, source: DiscoverySource, now: number, location?: string, context?: Context): Promise<Readonly<Record<string, Resolution>>>;