@sempdev/semp 0.4.3

package/dist/extensions/index.js

@@ -0,0 +1,7 @@
+/**
+ * Extensions layer per EXTENSIONS.md.
+ *
+ * @module
+ */
+export { KeyError, MaxKeyLength, NamespacePrefixCore, Registry, SizeError, UnsupportedError, maxBytesFor, validate, validateKey, validateSize, } from "./limits.js";
+//# sourceMappingURL=index.js.map

package/dist/extensions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAKL,QAAQ,EACR,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,aAAa,CAAC"}

package/dist/extensions/limits.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Extension validation per EXTENSIONS.md §2-§4.
+ *
+ * Each extension entry on the wire conforms to:
+ *
+ * ```json
+ * { "required": false, "data": { ... } }
+ * ```
+ *
+ * Per-layer byte-size ceilings (§4) are enforced before signature
+ * verification — an over-large `extensions` map MUST be rejected
+ * outright, regardless of any signature it might carry.
+ *
+ * Required extensions a recipient does not understand MUST be
+ * rejected per §3, regardless of namespace. The semp.dev/ namespace
+ * is reserved for spec-defined keys; vendor.* and x-* keys are at
+ * the operator's own risk but are subject to the same
+ * required-must-be-understood rule.
+ *
+ * @module
+ */
+/** Layers an `extensions` object can attach to. */
+export type Layer = "postmark" | "seal" | "brief" | "enclosure";
+/** A single extension entry on the wire. */
+export interface Entry {
+    required: boolean;
+    data: unknown;
+}
+/** Wire-level container: keys are namespaced extension identifiers. */
+export type Map = Record<string, Entry>;
+/** Per-layer byte-size ceiling per §4.1. */
+export declare function maxBytesFor(layer: Layer): number;
+/** Reserved namespace prefix for spec-defined extension keys. */
+export declare const NamespacePrefixCore = "semp.dev/";
+/** A registered extension. */
+export interface RegistryEntry {
+    identifier: string;
+    layers: Layer[];
+}
+/**
+ * Registry of known extensions an implementation supports. Used by
+ * {@link validate} to decide whether a required extension is
+ * understood (registered) or unknown (rejected).
+ */
+export declare class Registry {
+    private readonly entries;
+    register(entry: RegistryEntry): void;
+    lookup(identifier: string): RegistryEntry | undefined;
+}
+/** Error thrown when a required extension is not registered. */
+export declare class UnsupportedError extends Error {
+    readonly key: string;
+    readonly layer: Layer;
+    readonly reasonCode: "extension_unsupported";
+    constructor(key: string, layer: Layer);
+}
+/** Error thrown when the serialized map exceeds the layer's ceiling. */
+export declare class SizeError extends Error {
+    readonly layer: Layer;
+    readonly size: number;
+    readonly limit: number;
+    readonly reasonCode: "extension_size_exceeded";
+    constructor(layer: Layer, size: number, limit: number);
+}
+/** Error thrown when an extension key fails {@link validateKey}. */
+export declare class KeyError extends Error {
+    readonly key: string;
+    readonly layer: Layer;
+    constructor(key: string, layer: Layer, reason: string);
+}
+/** Maximum byte length of an extension key (the namespaced identifier). */
+export declare const MaxKeyLength = 128;
+/**
+ * Validate an extension key per EXTENSIONS.md §2.2: ASCII only,
+ * non-empty, MaxKeyLength cap, must contain a `/` after a vendor
+ * namespace OR start with `x-` for experimental.
+ */
+export declare function validateKey(key: string): Error | null;
+/**
+ * Validate an extensions map at a specific layer. Returns null on
+ * accept; an Error on first reject.
+ *
+ * Rejects:
+ *   - Malformed key shape ({@link KeyError})
+ *   - Required extension not in registry, regardless of namespace
+ *     ({@link UnsupportedError})
+ *   - Required extension registered but for a different layer
+ *     ({@link UnsupportedError})
+ *   - Total serialized size over the layer's ceiling
+ *     ({@link SizeError})
+ *
+ * Non-required (`required: false`) extensions are passed through
+ * unconditionally — the receiver is free to ignore them.
+ */
+export declare function validate(registry: Registry | null, layer: Layer, m: Map | null | undefined): Error | null;
+/**
+ * Validate the serialized byte length of an extensions map against
+ * the layer ceiling. Empty / missing maps pass through.
+ */
+export declare function validateSize(layer: Layer, m: Map | null | undefined): Error | null;
+//# sourceMappingURL=limits.d.ts.map

package/dist/extensions/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/extensions/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,mDAAmD;AACnD,MAAM,MAAM,KAAK,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;AAEhE,4CAA4C;AAC5C,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,uEAAuE;AACvE,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAExC,4CAA4C;AAC5C,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAWhD;AAED,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAE/C,8BAA8B;AAC9B,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+C;IAEvE,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAIpC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;CAGtD;AAED,gEAAgE;AAChE,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAG,uBAAuB,CAAU;gBAC3C,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAOtC;AAED,wEAAwE;AACxE,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAG,yBAAyB,CAAU;gBAC7C,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAQtD;AAED,oEAAoE;AACpE,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;gBACV,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM;CAKtD;AAED,2EAA2E;AAC3E,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAiBrD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,QAAQ,GAAG,IAAI,EACzB,KAAK,EAAE,KAAK,EACZ,CAAC,EAAE,GAAG,GAAG,IAAI,GAAG,SAAS,GACxB,KAAK,GAAG,IAAI,CA4Bd;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,GAAG,IAAI,CAelF"}

package/dist/extensions/limits.js

@@ -0,0 +1,175 @@
+/**
+ * Extension validation per EXTENSIONS.md §2-§4.
+ *
+ * Each extension entry on the wire conforms to:
+ *
+ * ```json
+ * { "required": false, "data": { ... } }
+ * ```
+ *
+ * Per-layer byte-size ceilings (§4) are enforced before signature
+ * verification — an over-large `extensions` map MUST be rejected
+ * outright, regardless of any signature it might carry.
+ *
+ * Required extensions a recipient does not understand MUST be
+ * rejected per §3, regardless of namespace. The semp.dev/ namespace
+ * is reserved for spec-defined keys; vendor.* and x-* keys are at
+ * the operator's own risk but are subject to the same
+ * required-must-be-understood rule.
+ *
+ * @module
+ */
+/** Per-layer byte-size ceiling per §4.1. */
+export function maxBytesFor(layer) {
+    switch (layer) {
+        case "postmark":
+            return 4096;
+        case "seal":
+            return 4096;
+        case "brief":
+            return 16_384;
+        case "enclosure":
+            return 65_536;
+    }
+}
+/** Reserved namespace prefix for spec-defined extension keys. */
+export const NamespacePrefixCore = "semp.dev/";
+/**
+ * Registry of known extensions an implementation supports. Used by
+ * {@link validate} to decide whether a required extension is
+ * understood (registered) or unknown (rejected).
+ */
+export class Registry {
+    entries = new globalThis.Map();
+    register(entry) {
+        this.entries.set(entry.identifier, entry);
+    }
+    lookup(identifier) {
+        return this.entries.get(identifier);
+    }
+}
+/** Error thrown when a required extension is not registered. */
+export class UnsupportedError extends Error {
+    key;
+    layer;
+    reasonCode = "extension_unsupported";
+    constructor(key, layer) {
+        super(`extensions: ${layer} layer required extension "${key}" is not supported`);
+        this.key = key;
+        this.layer = layer;
+    }
+}
+/** Error thrown when the serialized map exceeds the layer's ceiling. */
+export class SizeError extends Error {
+    layer;
+    size;
+    limit;
+    reasonCode = "extension_size_exceeded";
+    constructor(layer, size, limit) {
+        super(`extensions: ${layer} layer extensions object ${size} bytes exceeds limit ${limit}`);
+        this.layer = layer;
+        this.size = size;
+        this.limit = limit;
+    }
+}
+/** Error thrown when an extension key fails {@link validateKey}. */
+export class KeyError extends Error {
+    key;
+    layer;
+    constructor(key, layer, reason) {
+        super(`extensions: ${layer} layer key "${key}": ${reason}`);
+        this.key = key;
+        this.layer = layer;
+    }
+}
+/** Maximum byte length of an extension key (the namespaced identifier). */
+export const MaxKeyLength = 128;
+/**
+ * Validate an extension key per EXTENSIONS.md §2.2: ASCII only,
+ * non-empty, MaxKeyLength cap, must contain a `/` after a vendor
+ * namespace OR start with `x-` for experimental.
+ */
+export function validateKey(key) {
+    if (key.length === 0) {
+        return new Error("empty key");
+    }
+    if (key.length > MaxKeyLength) {
+        return new Error(`key length ${key.length} exceeds ${MaxKeyLength}`);
+    }
+    for (let i = 0; i < key.length; i++) {
+        const code = key.charCodeAt(i);
+        if (code < 0x21 || code > 0x7e) {
+            return new Error(`non-printable-ASCII byte at offset ${i}`);
+        }
+    }
+    if (!key.startsWith("x-") && !key.includes("/")) {
+        return new Error("expected `<vendor>/<name>` or `x-<name>`");
+    }
+    return null;
+}
+/**
+ * Validate an extensions map at a specific layer. Returns null on
+ * accept; an Error on first reject.
+ *
+ * Rejects:
+ *   - Malformed key shape ({@link KeyError})
+ *   - Required extension not in registry, regardless of namespace
+ *     ({@link UnsupportedError})
+ *   - Required extension registered but for a different layer
+ *     ({@link UnsupportedError})
+ *   - Total serialized size over the layer's ceiling
+ *     ({@link SizeError})
+ *
+ * Non-required (`required: false`) extensions are passed through
+ * unconditionally — the receiver is free to ignore them.
+ */
+export function validate(registry, layer, m) {
+    if (m === null || m === undefined || Object.keys(m).length === 0) {
+        return null;
+    }
+    const keys = Object.keys(m).sort();
+    for (const k of keys) {
+        const keyErr = validateKey(k);
+        if (keyErr !== null) {
+            return new KeyError(k, layer, keyErr.message);
+        }
+        const entry = m[k];
+        if (entry === undefined || !entry.required) {
+            continue;
+        }
+        if (registry === null) {
+            // No registry == no extension knowledge. A required extension
+            // is definitionally unsupported.
+            return new UnsupportedError(k, layer);
+        }
+        const reg = registry.lookup(k);
+        if (reg === undefined) {
+            return new UnsupportedError(k, layer);
+        }
+        if (!reg.layers.includes(layer)) {
+            return new UnsupportedError(k, layer);
+        }
+    }
+    return validateSize(layer, m);
+}
+/**
+ * Validate the serialized byte length of an extensions map against
+ * the layer ceiling. Empty / missing maps pass through.
+ */
+export function validateSize(layer, m) {
+    if (m === null || m === undefined || Object.keys(m).length === 0) {
+        return null;
+    }
+    const limit = maxBytesFor(layer);
+    // Count UTF-8 byte length of the JSON serialization. The exact
+    // canonical bytes are determined later by the seal computation;
+    // for size-limit purposes plain JSON.stringify is within the same
+    // order of magnitude (whitespace differences only).
+    const serialized = JSON.stringify(m) ?? "";
+    const bytes = new TextEncoder().encode(serialized).byteLength;
+    if (bytes > limit) {
+        return new SizeError(layer, bytes, limit);
+    }
+    return null;
+}
+//# sourceMappingURL=limits.js.map

package/dist/extensions/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/extensions/limits.ts"],"names":[],"mappings":"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"}

package/dist/handshake/abort.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Handshake abort + rejection helpers per HANDSHAKE.md §2.2a.6 + §4.
+ *
+ * - {@link ChallengeInvalidError}: error type a client raises when a
+ *   received challenge violates §2.2a.3 binding rules. Drivers catch
+ *   it and emit a `challenge_invalid` rejection.
+ * - {@link buildClientRejection}: produce an unsigned client-side
+ *   rejection message (party=client). The client has not authenticated
+ *   to the server at this point, so the wire form has no
+ *   `server_signature` and uses canonical bytes directly.
+ * - {@link isResumptionFailed}: classifies a `HandshakeRejectedError`
+ *   as a recoverable resumption failure that callers should fall back
+ *   from to a full handshake.
+ *
+ * @module
+ */
+/**
+ * Error a client raises when a received challenge violates §2.2a.3
+ * binding rules. The handshake driver catches this, sends a
+ * `challenge_invalid` rejection, then re-raises to the caller.
+ */
+export declare class ChallengeInvalidError extends Error {
+    readonly name = "ChallengeInvalidError";
+    /** Detail emitted verbatim in the abort message's `reason` field. */
+    readonly detail: string;
+    constructor(detail: string);
+}
+/** Type guard for {@link ChallengeInvalidError}. */
+export declare function isChallengeInvalid(err: unknown): err is ChallengeInvalidError;
+/**
+ * Build an unsigned client-initiator abort message per §2.2a.6.
+ *
+ * The wire shape is `party: "client"` with no `server_signature` —
+ * the initiator has not authenticated to the server at this point
+ * and MUST NOT do so as part of an abort.
+ *
+ * Returns canonical UTF-8 JSON bytes ready to send on the handshake
+ * stream. The caller closes the transport after sending.
+ */
+export declare function buildClientRejection(reasonCode: string, reason?: string): Uint8Array;
+/**
+ * Report whether `err` is a {@link HandshakeRejectedError} whose
+ * reason code indicates the resume attempt failed in a way the
+ * client should retry as a full handshake. Per HANDSHAKE.md §2.8:
+ * if the server has lost session state or the ticket has expired,
+ * the client falls back to a fresh handshake.
+ */
+export declare function isResumptionFailed(err: unknown): boolean;
+//# sourceMappingURL=abort.d.ts.map

package/dist/handshake/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/handshake/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAkB,IAAI,2BAA2B;IACjD,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAI3B;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,qBAAqB,CAE7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CAcZ;AASD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAKxD"}

package/dist/handshake/abort.js

@@ -0,0 +1,82 @@
+/**
+ * Handshake abort + rejection helpers per HANDSHAKE.md §2.2a.6 + §4.
+ *
+ * - {@link ChallengeInvalidError}: error type a client raises when a
+ *   received challenge violates §2.2a.3 binding rules. Drivers catch
+ *   it and emit a `challenge_invalid` rejection.
+ * - {@link buildClientRejection}: produce an unsigned client-side
+ *   rejection message (party=client). The client has not authenticated
+ *   to the server at this point, so the wire form has no
+ *   `server_signature` and uses canonical bytes directly.
+ * - {@link isResumptionFailed}: classifies a `HandshakeRejectedError`
+ *   as a recoverable resumption failure that callers should fall back
+ *   from to a full handshake.
+ *
+ * @module
+ */
+import { marshal as canonicalMarshal } from "../canonical/index.js";
+import { HandshakeRejectedError } from "./driver.js";
+import { HandshakeVersion } from "./messages.js";
+/**
+ * Error a client raises when a received challenge violates §2.2a.3
+ * binding rules. The handshake driver catches this, sends a
+ * `challenge_invalid` rejection, then re-raises to the caller.
+ */
+export class ChallengeInvalidError extends Error {
+    name = "ChallengeInvalidError";
+    /** Detail emitted verbatim in the abort message's `reason` field. */
+    detail;
+    constructor(detail) {
+        super(`handshake: challenge_invalid: ${detail}`);
+        this.detail = detail;
+    }
+}
+/** Type guard for {@link ChallengeInvalidError}. */
+export function isChallengeInvalid(err) {
+    return err instanceof ChallengeInvalidError;
+}
+/**
+ * Build an unsigned client-initiator abort message per §2.2a.6.
+ *
+ * The wire shape is `party: "client"` with no `server_signature` —
+ * the initiator has not authenticated to the server at this point
+ * and MUST NOT do so as part of an abort.
+ *
+ * Returns canonical UTF-8 JSON bytes ready to send on the handshake
+ * stream. The caller closes the transport after sending.
+ */
+export function buildClientRejection(reasonCode, reason) {
+    if (reasonCode === "") {
+        throw new Error("handshake: empty reason_code in client rejection");
+    }
+    const msg = {
+        type: "SEMP_HANDSHAKE",
+        step: "rejected",
+        party: "client",
+        version: HandshakeVersion,
+        reason_code: reasonCode,
+        reason: reason ?? "",
+        extensions: {},
+    };
+    return canonicalMarshal(msg);
+}
+/** Reason codes per HANDSHAKE.md §2.8 that the spec treats as recoverable resumption failures. */
+const RECOVERABLE_RESUMPTION_REASONS = new Set([
+    "resumption_failed",
+    "session_expired",
+    "no_session",
+]);
+/**
+ * Report whether `err` is a {@link HandshakeRejectedError} whose
+ * reason code indicates the resume attempt failed in a way the
+ * client should retry as a full handshake. Per HANDSHAKE.md §2.8:
+ * if the server has lost session state or the ticket has expired,
+ * the client falls back to a fresh handshake.
+ */
+export function isResumptionFailed(err) {
+    if (!(err instanceof HandshakeRejectedError)) {
+        return false;
+    }
+    return RECOVERABLE_RESUMPTION_REASONS.has(err.reasonCode);
+}
+//# sourceMappingURL=abort.js.map

package/dist/handshake/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/handshake/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC5B,IAAI,GAAG,uBAAuB,CAAC;IACjD,qEAAqE;IAC5D,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,iCAAiC,MAAM,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,oDAAoD;AACpD,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,GAAG,YAAY,qBAAqB,CAAC;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAkB,EAClB,MAAe;IAEf,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,GAAG,GAA4B;QACnC,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,QAAQ;QACf,OAAO,EAAE,gBAAgB;QACzB,WAAW,EAAE,UAAU;QACvB,MAAM,EAAE,MAAM,IAAI,EAAE;QACpB,UAAU,EAAE,EAAE;KACf,CAAC;IACF,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,kGAAkG;AAClG,MAAM,8BAA8B,GAAwB,IAAI,GAAG,CAAC;IAClE,mBAAmB;IACnB,iBAAiB;IACjB,YAAY;CACb,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,IAAI,CAAC,CAAC,GAAG,YAAY,sBAAsB,CAAC,EAAE,CAAC;QAC7C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,8BAA8B,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAC5D,CAAC"}

package/dist/handshake/capabilities.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Capability negotiation helpers per HANDSHAKE.md §6.4 + SESSION.md §4.3.
+ *
+ * `negotiateCapabilities` returns the agreed session parameters from
+ * the client's offered capabilities and the server's accepted set,
+ * preferring the post-quantum hybrid suite when both peers support
+ * it.
+ *
+ * Selection rules:
+ *
+ *  - Encryption algorithm: walk the spec preference order (PQ hybrid
+ *    first, then baseline). The strongest mutually supported and
+ *    library-implemented suite wins.
+ *  - Extensions: the intersection of `offered.extensions` and
+ *    `accepted.extensions`, in the order they appear in `offered`.
+ *  - max_envelope_size / max_batch_size: the smaller of the two
+ *    when both sides advertise; the side that advertises when only
+ *    one does; absent when neither does.
+ *
+ * @module
+ */
+import type { Capabilities, Negotiated } from "./messages.js";
+/**
+ * Suite preference order from strongest to weakest. Library MUST
+ * walk this list and return the first suite that appears in both
+ * `offered` AND `accepted` AND is implemented locally.
+ *
+ * The `pq-kyber768-x25519` hybrid is RECOMMENDED for new
+ * deployments per SESSION.md §4; the baseline
+ * `x25519-chacha20-poly1305` is mandatory for interoperability
+ * per ENVELOPE.md §7.3.2.
+ */
+export declare const SuitePreferenceOrder: readonly string[];
+/** Library-implemented suite identifiers. */
+export declare const ImplementedSuites: readonly string[];
+/** Default capabilities a baseline conformant client advertises. */
+export declare function defaultClientCapabilities(): Capabilities;
+/** Default capabilities a baseline conformant server accepts. */
+export declare function defaultServerCapabilities(): Capabilities;
+/**
+ * Compute the negotiated session parameters per §6.4. Throws when
+ * no encryption suite is mutually supported (caller surfaces this
+ * as a `policy_forbidden` rejection).
+ */
+export declare function negotiateCapabilities(offered: Capabilities, accepted: Capabilities): Negotiated;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/handshake/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/handshake/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAGjD,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAG9C,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,yBAAyB,IAAI,YAAY,CAQxD;AAED,iEAAiE;AACjE,wBAAgB,yBAAyB,IAAI,YAAY,CAQxD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,YAAY,GACrB,UAAU,CA0CZ"}

package/dist/handshake/capabilities.js

@@ -0,0 +1,114 @@
+/**
+ * Capability negotiation helpers per HANDSHAKE.md §6.4 + SESSION.md §4.3.
+ *
+ * `negotiateCapabilities` returns the agreed session parameters from
+ * the client's offered capabilities and the server's accepted set,
+ * preferring the post-quantum hybrid suite when both peers support
+ * it.
+ *
+ * Selection rules:
+ *
+ *  - Encryption algorithm: walk the spec preference order (PQ hybrid
+ *    first, then baseline). The strongest mutually supported and
+ *    library-implemented suite wins.
+ *  - Extensions: the intersection of `offered.extensions` and
+ *    `accepted.extensions`, in the order they appear in `offered`.
+ *  - max_envelope_size / max_batch_size: the smaller of the two
+ *    when both sides advertise; the side that advertises when only
+ *    one does; absent when neither does.
+ *
+ * @module
+ */
+/**
+ * Suite preference order from strongest to weakest. Library MUST
+ * walk this list and return the first suite that appears in both
+ * `offered` AND `accepted` AND is implemented locally.
+ *
+ * The `pq-kyber768-x25519` hybrid is RECOMMENDED for new
+ * deployments per SESSION.md §4; the baseline
+ * `x25519-chacha20-poly1305` is mandatory for interoperability
+ * per ENVELOPE.md §7.3.2.
+ */
+export const SuitePreferenceOrder = [
+    "pq-kyber768-x25519",
+    "x25519-chacha20-poly1305",
+];
+/** Library-implemented suite identifiers. */
+export const ImplementedSuites = [
+    "pq-kyber768-x25519",
+    "x25519-chacha20-poly1305",
+];
+/** Default capabilities a baseline conformant client advertises. */
+export function defaultClientCapabilities() {
+    return {
+        encryption_algorithms: [
+            "pq-kyber768-x25519",
+            "x25519-chacha20-poly1305",
+        ],
+        extensions: [],
+    };
+}
+/** Default capabilities a baseline conformant server accepts. */
+export function defaultServerCapabilities() {
+    return {
+        encryption_algorithms: [
+            "pq-kyber768-x25519",
+            "x25519-chacha20-poly1305",
+        ],
+        extensions: [],
+    };
+}
+/**
+ * Compute the negotiated session parameters per §6.4. Throws when
+ * no encryption suite is mutually supported (caller surfaces this
+ * as a `policy_forbidden` rejection).
+ */
+export function negotiateCapabilities(offered, accepted) {
+    const offeredSet = new Set(offered.encryption_algorithms);
+    const acceptedSet = new Set(accepted.encryption_algorithms);
+    const implementedSet = new Set(ImplementedSuites);
+    let chosen = null;
+    for (const id of SuitePreferenceOrder) {
+        if (offeredSet.has(id) && acceptedSet.has(id) && implementedSet.has(id)) {
+            chosen = id;
+            break;
+        }
+    }
+    if (chosen === null) {
+        throw new Error("handshake: no mutually supported encryption suite");
+    }
+    const negotiatedExtensions = intersectStrings(offered.extensions, accepted.extensions);
+    // max_envelope_size: the smaller of the two when both sides advertise.
+    let maxEnvelope;
+    const oMax = offered.max_envelope_size;
+    const aMax = accepted.max_envelope_size;
+    if (typeof oMax === "number" && oMax > 0) {
+        maxEnvelope = oMax;
+    }
+    if (typeof aMax === "number" && aMax > 0) {
+        maxEnvelope = maxEnvelope === undefined ? aMax : Math.min(maxEnvelope, aMax);
+    }
+    const out = {
+        encryption_algorithm: chosen,
+        extensions: negotiatedExtensions,
+    };
+    if (maxEnvelope !== undefined) {
+        out.max_envelope_size = maxEnvelope;
+    }
+    return out;
+}
+/** Intersection of `a` and `b`, ordered by `a`. */
+function intersectStrings(a, b) {
+    if (a.length === 0 || b.length === 0) {
+        return [];
+    }
+    const set = new Set(b);
+    const out = [];
+    for (const v of a) {
+        if (set.has(v)) {
+            out.push(v);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/handshake/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/handshake/capabilities.ts"],"names":[],"mappings":"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"}