@sempdev/semp 0.4.3

package/dist/handshake/messages.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Handshake message builders per HANDSHAKE.md §2.
+ *
+ * Five message kinds in the v1 handshake flow:
+ *
+ *   INIT      client -> server (step="init", no signature)
+ *   RESPONSE  server -> client (step="response", server_signature)
+ *   CONFIRM   client -> server (step="confirm", carries identity_proof)
+ *   ACCEPTED  server -> client (step="accepted", server_signature)
+ *   REJECTED  server -> client (step="rejected", reason_code,
+ *                               server_signature)
+ *
+ * The signed messages share the canonical-bytes pattern every other
+ * SEMP-signed document uses: blank `server_signature`, canonicalize,
+ * prepend `SEMP-HANDSHAKE:`, Ed25519-sign with the server domain
+ * signing key, write the signature back into the message.
+ *
+ * @module
+ */
+/** Domain-separation prefix for all handshake signatures. */
+export declare const HandshakePrefix = "SEMP-HANDSHAKE:";
+/** Common version string. */
+export declare const HandshakeVersion = "1.0.0";
+/** A keyref (algorithm + key bytes + fingerprint) shared by both parties. */
+export interface KeyRef {
+    algorithm: string;
+    /** base64 encoding of the public key bytes */
+    key: string;
+    /** lowercase-hex SHA-256 fingerprint of the key */
+    key_id: string;
+}
+/** Capabilities section advertised by the client in INIT. */
+export interface Capabilities {
+    encryption_algorithms: string[];
+    extensions: string[];
+}
+/** Negotiated subset agreed on in RESPONSE. */
+export interface Negotiated {
+    encryption_algorithm: string;
+    extensions: string[];
+    /**
+     * Optional max envelope size negotiation. The server may pin a
+     * stricter ceiling than the protocol default; the client honors
+     * whichever value the server returns.
+     */
+    max_envelope_size?: number;
+}
+/** Server's identity-proof signature reference attached to RESPONSE. */
+export interface ServerIdentityProof {
+    domain: string;
+    key_id: string;
+    /** base64 of the identity-proof signature; computation defined in §2.3. */
+    signature: string;
+}
+export interface InitMessage {
+    type: "SEMP_HANDSHAKE";
+    step: "init";
+    party: "client";
+    version: string;
+    /** base64 of 32-byte client nonce */
+    nonce: string;
+    /** Transport identifier; one of "ws", "h2", "quic". */
+    transport: string;
+    /** Client ephemeral public key for the negotiated KEM. */
+    client_ephemeral_key: KeyRef;
+    capabilities: Capabilities;
+    extensions: Record<string, unknown>;
+}
+export interface BuildInitInput {
+    nonce: string;
+    transport: string;
+    clientEphemeralKey: KeyRef;
+    capabilities: Capabilities;
+    extensions?: Record<string, unknown>;
+}
+/** Build a canonical-shape INIT message. INIT is unsigned. */
+export declare function buildInit(input: BuildInitInput): InitMessage;
+export interface ResponseMessage {
+    type: "SEMP_HANDSHAKE";
+    step: "response";
+    party: "server";
+    version: string;
+    session_id: string;
+    client_nonce: string;
+    server_nonce: string;
+    server_ephemeral_key: KeyRef;
+    server_identity_proof: ServerIdentityProof;
+    negotiated: Negotiated;
+    server_signature: string;
+    extensions: Record<string, unknown>;
+}
+export interface BuildResponseInput {
+    sessionId: string;
+    clientNonce: string;
+    serverNonce: string;
+    serverEphemeralKey: KeyRef;
+    serverIdentityProof: ServerIdentityProof;
+    negotiated: Negotiated;
+    /** 32-byte Ed25519 secret seed for the server domain signing key. */
+    serverDomainSigningSeed: Uint8Array;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Build a signed RESPONSE message. Composes the canonical pre-sign
+ * shape, signs over `SEMP-HANDSHAKE: || canonical(blanked)`, and
+ * writes the base64-encoded signature back into `server_signature`.
+ */
+export declare function buildResponse(input: BuildResponseInput): ResponseMessage;
+export interface ConfirmMessage {
+    type: "SEMP_HANDSHAKE";
+    step: "confirm";
+    party: "client";
+    version: string;
+    session_id: string;
+    /** base64 of the SHA-256 confirmation hash; see handshake.confirmationHash. */
+    confirmation_hash: string;
+    /** Opaque identity-proof ciphertext (encrypted under the agreed session key). */
+    identity_proof: string;
+    extensions: Record<string, unknown>;
+}
+export interface BuildConfirmInput {
+    sessionId: string;
+    confirmationHashB64: string;
+    identityProofB64: string;
+    extensions?: Record<string, unknown>;
+}
+/** Build a canonical-shape CONFIRM message. CONFIRM is unsigned at this layer. */
+export declare function buildConfirm(input: BuildConfirmInput): ConfirmMessage;
+export interface ResumptionTicket {
+    /** Opaque ticket value (server-defined opaque blob). */
+    value: string;
+    /** ISO 8601 timestamp at which the ticket stops being valid. */
+    expires_at: string;
+}
+export interface AcceptedMessage {
+    type: "SEMP_HANDSHAKE";
+    step: "accepted";
+    party: "server";
+    version: string;
+    session_id: string;
+    session_ttl: number;
+    permissions: string[];
+    resumption_ticket?: ResumptionTicket;
+    server_signature: string;
+    extensions: Record<string, unknown>;
+}
+export interface BuildAcceptedInput {
+    sessionId: string;
+    sessionTTL: number;
+    permissions: string[];
+    resumptionTicket?: ResumptionTicket;
+    serverDomainSigningSeed: Uint8Array;
+    extensions?: Record<string, unknown>;
+}
+export declare function buildAccepted(input: BuildAcceptedInput): AcceptedMessage;
+export interface RejectedMessage {
+    type: "SEMP_HANDSHAKE";
+    step: "rejected";
+    party: "server";
+    version: string;
+    session_id: string;
+    reason_code: string;
+    /** Optional human-readable reason. */
+    reason?: string;
+    server_signature: string;
+    extensions: Record<string, unknown>;
+}
+export interface BuildRejectedInput {
+    sessionId: string;
+    reasonCode: string;
+    reason?: string;
+    serverDomainSigningSeed: Uint8Array;
+    extensions?: Record<string, unknown>;
+}
+export declare function buildRejected(input: BuildRejectedInput): RejectedMessage;
+//# sourceMappingURL=messages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/handshake/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,6DAA6D;AAC7D,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,6BAA6B;AAC7B,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,6EAA6E;AAC7E,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAKD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAY5D;AAKD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qBAAqB,EAAE,mBAAmB,CAAC;IAC3C,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,UAAU,EAAE,UAAU,CAAC;IACvB,qEAAqE;IACrE,uBAAuB,EAAE,UAAU,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,CAsBxE;AAKD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,cAAc,CAWrE;AAKD,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,uBAAuB,EAAE,UAAU,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,CAsBxE;AAKD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB,EAAE,UAAU,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,CAqBxE"}

package/dist/handshake/messages.js

@@ -0,0 +1,125 @@
+/**
+ * Handshake message builders per HANDSHAKE.md §2.
+ *
+ * Five message kinds in the v1 handshake flow:
+ *
+ *   INIT      client -> server (step="init", no signature)
+ *   RESPONSE  server -> client (step="response", server_signature)
+ *   CONFIRM   client -> server (step="confirm", carries identity_proof)
+ *   ACCEPTED  server -> client (step="accepted", server_signature)
+ *   REJECTED  server -> client (step="rejected", reason_code,
+ *                               server_signature)
+ *
+ * The signed messages share the canonical-bytes pattern every other
+ * SEMP-signed document uses: blank `server_signature`, canonicalize,
+ * prepend `SEMP-HANDSHAKE:`, Ed25519-sign with the server domain
+ * signing key, write the signature back into the message.
+ *
+ * @module
+ */
+import { signSignedDoc } from "../keys/signed.js";
+/** Domain-separation prefix for all handshake signatures. */
+export const HandshakePrefix = "SEMP-HANDSHAKE:";
+/** Common version string. */
+export const HandshakeVersion = "1.0.0";
+/** Build a canonical-shape INIT message. INIT is unsigned. */
+export function buildInit(input) {
+    return {
+        type: "SEMP_HANDSHAKE",
+        step: "init",
+        party: "client",
+        version: HandshakeVersion,
+        nonce: input.nonce,
+        transport: input.transport,
+        client_ephemeral_key: input.clientEphemeralKey,
+        capabilities: input.capabilities,
+        extensions: input.extensions ?? {},
+    };
+}
+/**
+ * Build a signed RESPONSE message. Composes the canonical pre-sign
+ * shape, signs over `SEMP-HANDSHAKE: || canonical(blanked)`, and
+ * writes the base64-encoded signature back into `server_signature`.
+ */
+export function buildResponse(input) {
+    const preSign = {
+        type: "SEMP_HANDSHAKE",
+        step: "response",
+        party: "server",
+        version: HandshakeVersion,
+        session_id: input.sessionId,
+        client_nonce: input.clientNonce,
+        server_nonce: input.serverNonce,
+        server_ephemeral_key: input.serverEphemeralKey,
+        server_identity_proof: input.serverIdentityProof,
+        negotiated: input.negotiated,
+        server_signature: "",
+        extensions: input.extensions ?? {},
+    };
+    const { signedJSON } = signSignedDoc({
+        preSignJSON: preSign,
+        seed: input.serverDomainSigningSeed,
+        signaturePath: "server_signature",
+        prefix: HandshakePrefix,
+    });
+    return signedJSON;
+}
+/** Build a canonical-shape CONFIRM message. CONFIRM is unsigned at this layer. */
+export function buildConfirm(input) {
+    return {
+        type: "SEMP_HANDSHAKE",
+        step: "confirm",
+        party: "client",
+        version: HandshakeVersion,
+        session_id: input.sessionId,
+        confirmation_hash: input.confirmationHashB64,
+        identity_proof: input.identityProofB64,
+        extensions: input.extensions ?? {},
+    };
+}
+export function buildAccepted(input) {
+    const preSign = {
+        type: "SEMP_HANDSHAKE",
+        step: "accepted",
+        party: "server",
+        version: HandshakeVersion,
+        session_id: input.sessionId,
+        session_ttl: input.sessionTTL,
+        permissions: input.permissions,
+        server_signature: "",
+        extensions: input.extensions ?? {},
+    };
+    if (input.resumptionTicket !== undefined) {
+        preSign.resumption_ticket = input.resumptionTicket;
+    }
+    const { signedJSON } = signSignedDoc({
+        preSignJSON: preSign,
+        seed: input.serverDomainSigningSeed,
+        signaturePath: "server_signature",
+        prefix: HandshakePrefix,
+    });
+    return signedJSON;
+}
+export function buildRejected(input) {
+    const preSign = {
+        type: "SEMP_HANDSHAKE",
+        step: "rejected",
+        party: "server",
+        version: HandshakeVersion,
+        session_id: input.sessionId,
+        reason_code: input.reasonCode,
+        server_signature: "",
+        extensions: input.extensions ?? {},
+    };
+    if (input.reason !== undefined) {
+        preSign.reason = input.reason;
+    }
+    const { signedJSON } = signSignedDoc({
+        preSignJSON: preSign,
+        seed: input.serverDomainSigningSeed,
+        signaturePath: "server_signature",
+        prefix: HandshakePrefix,
+    });
+    return signedJSON;
+}
+//# sourceMappingURL=messages.js.map

package/dist/handshake/messages.js.map

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

package/dist/handshake/pow.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Proof-of-Work verification per HANDSHAKE.md §2.2b and REPUTATION.md §8.3.
+ *
+ * Two PoW preimages exist in the spec:
+ *
+ * - **Challenge PoW** (this module): preimage is the UTF-8 string
+ *   `base64(prefix) || ":" || challenge_id || ":" || base64(nonce)`.
+ *   Used by the standard handshake-time difficulty challenge.
+ * - **First-contact PoW** (HANDSHAKE.md §2.2a.4): preimage is the
+ *   raw byte concatenation `prefix || nonce`. Different shape because
+ *   §2.2a.4 binds the first-contact tuple via the prefix derivation
+ *   itself, not via the preimage. See {@link verifyFirstContactSolution}.
+ *
+ * @module
+ */
+/** Maximum difficulty the verifier accepts (HANDSHAKE.md §2.2b). */
+export declare const MaxPoWDifficulty = 28;
+/**
+ * Verify a challenge-PoW solution. Returns null on success; an Error
+ * on rejection so callers can surface a specific failure reason.
+ *
+ * - `prefix` is the raw 16-byte challenge prefix.
+ * - `challengeId` is the ULID of the issued challenge.
+ * - `nonceB64` is the candidate nonce as base64 (RFC 4648 §4).
+ * - `claimedHashHex` is the hex digest the sender claims; the
+ *   verifier MUST recompute and compare.
+ * - `difficulty` is the required leading-zero-bit count of the SHA-256
+ *   digest; verification rejects if the recomputed hash has fewer
+ *   leading zeros.
+ *
+ * Cap at {@link MaxPoWDifficulty}: a verifier that accepts a higher
+ * difficulty would silently validate a non-conformant challenge.
+ */
+export declare function verifyChallengeSolution(prefix: Uint8Array, challengeId: string, nonceB64: string, claimedHashHex: string, difficulty: number): Error | null;
+/**
+ * First-contact PoW verifier per HANDSHAKE.md §2.2a.4. The
+ * preimage is the raw concatenation `prefix || nonce`, hashed with
+ * SHA-256. Returns the recomputed hash and the leading-zero bit
+ * count; the caller decides whether the bit count meets its
+ * difficulty threshold (the difficulty is a recipient policy, not a
+ * protocol constant here).
+ */
+export declare function firstContactDigest(prefix: Uint8Array, nonce: Uint8Array): {
+    hash: Uint8Array;
+    leadingZeroBits: number;
+};
+/**
+ * Count the number of leading zero bits in a hash. Used by both
+ * PoW preimages to assess whether a candidate solution meets the
+ * required difficulty.
+ */
+export declare function leadingZeroBits(hash: Uint8Array): number;
+//# sourceMappingURL=pow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pow.d.ts","sourceRoot":"","sources":["../../src/handshake/pow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GACjB,KAAK,GAAG,IAAI,CA+Bd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,GAChB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAM/C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAkBxD"}

package/dist/handshake/pow.js

@@ -0,0 +1,142 @@
+/**
+ * Proof-of-Work verification per HANDSHAKE.md §2.2b and REPUTATION.md §8.3.
+ *
+ * Two PoW preimages exist in the spec:
+ *
+ * - **Challenge PoW** (this module): preimage is the UTF-8 string
+ *   `base64(prefix) || ":" || challenge_id || ":" || base64(nonce)`.
+ *   Used by the standard handshake-time difficulty challenge.
+ * - **First-contact PoW** (HANDSHAKE.md §2.2a.4): preimage is the
+ *   raw byte concatenation `prefix || nonce`. Different shape because
+ *   §2.2a.4 binds the first-contact tuple via the prefix derivation
+ *   itself, not via the preimage. See {@link verifyFirstContactSolution}.
+ *
+ * @module
+ */
+import { sha256 } from "@noble/hashes/sha2.js";
+/** Maximum difficulty the verifier accepts (HANDSHAKE.md §2.2b). */
+export const MaxPoWDifficulty = 28;
+/**
+ * Verify a challenge-PoW solution. Returns null on success; an Error
+ * on rejection so callers can surface a specific failure reason.
+ *
+ * - `prefix` is the raw 16-byte challenge prefix.
+ * - `challengeId` is the ULID of the issued challenge.
+ * - `nonceB64` is the candidate nonce as base64 (RFC 4648 §4).
+ * - `claimedHashHex` is the hex digest the sender claims; the
+ *   verifier MUST recompute and compare.
+ * - `difficulty` is the required leading-zero-bit count of the SHA-256
+ *   digest; verification rejects if the recomputed hash has fewer
+ *   leading zeros.
+ *
+ * Cap at {@link MaxPoWDifficulty}: a verifier that accepts a higher
+ * difficulty would silently validate a non-conformant challenge.
+ */
+export function verifyChallengeSolution(prefix, challengeId, nonceB64, claimedHashHex, difficulty) {
+    if (difficulty < 0) {
+        return new Error("handshake: negative PoW difficulty");
+    }
+    if (difficulty > MaxPoWDifficulty) {
+        return new Error("handshake: PoW difficulty exceeds protocol cap (28)");
+    }
+    if (challengeId === "") {
+        return new Error("handshake: empty PoW challenge_id");
+    }
+    if (nonceB64 === "") {
+        return new Error("handshake: empty PoW nonce");
+    }
+    // Nonce must be valid base64 — but we accept its bytes as-is in
+    // the preimage (the spec hashes the base64 string, not the
+    // decoded bytes).
+    try {
+        decodeBase64Strict(nonceB64);
+    }
+    catch {
+        return new Error("handshake: PoW nonce is not valid base64");
+    }
+    const preimage = challengePreimage(prefix, challengeId, nonceB64);
+    const sum = sha256(preimage);
+    const computedHex = bytesToHex(sum);
+    if (computedHex.toLowerCase() !== claimedHashHex.toLowerCase()) {
+        return new Error("handshake: PoW hash mismatch");
+    }
+    if (leadingZeroBits(sum) < difficulty) {
+        return new Error("handshake: PoW insufficient difficulty");
+    }
+    return null;
+}
+/**
+ * First-contact PoW verifier per HANDSHAKE.md §2.2a.4. The
+ * preimage is the raw concatenation `prefix || nonce`, hashed with
+ * SHA-256. Returns the recomputed hash and the leading-zero bit
+ * count; the caller decides whether the bit count meets its
+ * difficulty threshold (the difficulty is a recipient policy, not a
+ * protocol constant here).
+ */
+export function firstContactDigest(prefix, nonce) {
+    const buf = new Uint8Array(prefix.length + nonce.length);
+    buf.set(prefix, 0);
+    buf.set(nonce, prefix.length);
+    const sum = sha256(buf);
+    return { hash: sum, leadingZeroBits: leadingZeroBits(sum) };
+}
+/**
+ * Count the number of leading zero bits in a hash. Used by both
+ * PoW preimages to assess whether a candidate solution meets the
+ * required difficulty.
+ */
+export function leadingZeroBits(hash) {
+    let n = 0;
+    for (let i = 0; i < hash.length; i++) {
+        const b = hash[i] ?? 0;
+        if (b === 0) {
+            n += 8;
+            continue;
+        }
+        let bb = b;
+        let bits = 8;
+        while (bb !== 0) {
+            bb = bb >>> 1;
+            bits--;
+        }
+        n += bits;
+        return n;
+    }
+    return n;
+}
+function challengePreimage(prefix, challengeId, nonceB64) {
+    const prefixB64 = bytesToBase64(prefix);
+    return new TextEncoder().encode(`${prefixB64}:${challengeId}:${nonceB64}`);
+}
+function bytesToHex(b) {
+    let s = "";
+    for (let i = 0; i < b.length; i++) {
+        s += (b[i] ?? 0).toString(16).padStart(2, "0");
+    }
+    return s;
+}
+function bytesToBase64(b) {
+    // Node and modern browsers both support btoa via TextDecoder, but
+    // the cleanest portable path is Buffer when available, falling
+    // back to a binary-string + btoa for browsers.
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(b).toString("base64");
+    }
+    let bin = "";
+    for (let i = 0; i < b.length; i++) {
+        bin += String.fromCharCode(b[i] ?? 0);
+    }
+    return btoa(bin);
+}
+function decodeBase64Strict(s) {
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(s, "base64"));
+    }
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) {
+        out[i] = bin.charCodeAt(i);
+    }
+    return out;
+}
+//# sourceMappingURL=pow.js.map

package/dist/handshake/pow.js.map

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

package/dist/handshake/resume_driver.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Session-resume driver per HANDSHAKE.md §2.8.
+ *
+ * Wraps the stateful {@link HandshakeClient} for the resume path:
+ *
+ *   1. Send `step="resume"` with the ticket value + a fresh client
+ *      nonce.
+ *   2. Receive ACCEPTED (or REJECTED).
+ *   3. On ACCEPTED, derive resumed session keys and return both
+ *      the new session and the new ticket the server issued for
+ *      chaining a future resume.
+ *
+ * On REJECTED with `reason_code` ∈ {`resumption_failed`,
+ * `configuration_stale`, `no_session`}, throw an error that
+ * satisfies {@link "./abort".isResumptionFailed}; the caller MUST
+ * discard the resume attempt and fall back to a fresh full
+ * handshake. {@link runClientResumeOrFull} composes this for callers
+ * who want one-call fallback.
+ *
+ * @module
+ */
+import type { Transport } from "../transport/index.js";
+import { type HandshakeClient, type HandshakeClientSession } from "./client_state.js";
+/**
+ * Drive a client-side resume exchange to completion over `transport`.
+ * Returns the resumed session plus the new ticket bytes the server
+ * issued for chaining (`undefined` if the server didn't issue one).
+ */
+export declare function runClientResume(transport: Transport, client: HandshakeClient, ticket: string): Promise<{
+    session: HandshakeClientSession;
+    newTicket: string | undefined;
+}>;
+/**
+ * Try a resume against `resumeTransport` / `resumeClient` /
+ * `ticket` per §2.8.5. If the resume fails with a fallback-eligible
+ * reason (resumption_failed / configuration_stale / no_session),
+ * discard the resume attempt and perform a full handshake against a
+ * fresh transport + client supplied by the caller.
+ *
+ * The caller supplies factories rather than reusing the prior
+ * transport / client because:
+ *
+ *   - The prior transport was already used for the failed Resume
+ *     exchange.
+ *   - The prior client has accumulated state from `resume()` that
+ *     would interfere with a fresh `init()`.
+ *
+ * Returns `{ session, newTicket, fellBack }`. `fellBack` is `true`
+ * when the function fell back to a full handshake.
+ */
+export declare function runClientResumeOrFull(resumeTransport: Transport, resumeClient: HandshakeClient, ticket: string, freshTransport: () => Promise<Transport>, fullHandshake: (transport: Transport) => Promise<HandshakeClientSession>): Promise<{
+    session: HandshakeClientSession;
+    newTicket: string | undefined;
+    fellBack: boolean;
+}>;
+//# sourceMappingURL=resume_driver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resume_driver.d.ts","sourceRoot":"","sources":["../../src/handshake/resume_driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAE5B,MAAM,mBAAmB,CAAC;AAG3B;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,sBAAsB,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC,CAW7E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CACzC,eAAe,EAAE,SAAS,EAC1B,YAAY,EAAE,eAAe,EAC7B,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EACxC,aAAa,EAAE,CACb,SAAS,EAAE,SAAS,KACjB,OAAO,CAAC,sBAAsB,CAAC,GACnC,OAAO,CAAC;IACT,OAAO,EAAE,sBAAsB,CAAC;IAChC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC,CAgBD"}

package/dist/handshake/resume_driver.js

@@ -0,0 +1,75 @@
+/**
+ * Session-resume driver per HANDSHAKE.md §2.8.
+ *
+ * Wraps the stateful {@link HandshakeClient} for the resume path:
+ *
+ *   1. Send `step="resume"` with the ticket value + a fresh client
+ *      nonce.
+ *   2. Receive ACCEPTED (or REJECTED).
+ *   3. On ACCEPTED, derive resumed session keys and return both
+ *      the new session and the new ticket the server issued for
+ *      chaining a future resume.
+ *
+ * On REJECTED with `reason_code` ∈ {`resumption_failed`,
+ * `configuration_stale`, `no_session`}, throw an error that
+ * satisfies {@link "./abort".isResumptionFailed}; the caller MUST
+ * discard the resume attempt and fall back to a fresh full
+ * handshake. {@link runClientResumeOrFull} composes this for callers
+ * who want one-call fallback.
+ *
+ * @module
+ */
+import { HandshakeRejectedError, } from "./client_state.js";
+import { isResumptionFailed } from "./abort.js";
+/**
+ * Drive a client-side resume exchange to completion over `transport`.
+ * Returns the resumed session plus the new ticket bytes the server
+ * issued for chaining (`undefined` if the server didn't issue one).
+ */
+export async function runClientResume(transport, client, ticket) {
+    if (ticket === "") {
+        throw new Error("handshake: empty resumption ticket");
+    }
+    const resumeBytes = client.resume(ticket);
+    await transport.send(resumeBytes);
+    const respBytes = await transport.receive();
+    if (respBytes === null) {
+        throw new Error("handshake: connection closed waiting for resume response");
+    }
+    return client.onResumeAccepted(respBytes);
+}
+/**
+ * Try a resume against `resumeTransport` / `resumeClient` /
+ * `ticket` per §2.8.5. If the resume fails with a fallback-eligible
+ * reason (resumption_failed / configuration_stale / no_session),
+ * discard the resume attempt and perform a full handshake against a
+ * fresh transport + client supplied by the caller.
+ *
+ * The caller supplies factories rather than reusing the prior
+ * transport / client because:
+ *
+ *   - The prior transport was already used for the failed Resume
+ *     exchange.
+ *   - The prior client has accumulated state from `resume()` that
+ *     would interfere with a fresh `init()`.
+ *
+ * Returns `{ session, newTicket, fellBack }`. `fellBack` is `true`
+ * when the function fell back to a full handshake.
+ */
+export async function runClientResumeOrFull(resumeTransport, resumeClient, ticket, freshTransport, fullHandshake) {
+    try {
+        const r = await runClientResume(resumeTransport, resumeClient, ticket);
+        return { session: r.session, newTicket: r.newTicket, fellBack: false };
+    }
+    catch (err) {
+        if (!(err instanceof HandshakeRejectedError) ||
+            !isResumptionFailed(err)) {
+            throw err;
+        }
+        // Fall back to a full handshake on a fresh transport + client.
+        const t = await freshTransport();
+        const session = await fullHandshake(t);
+        return { session, newTicket: undefined, fellBack: true };
+    }
+}
+//# sourceMappingURL=resume_driver.js.map

package/dist/handshake/resume_driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume_driver.js","sourceRoot":"","sources":["../../src/handshake/resume_driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAGL,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,SAAoB,EACpB,MAAuB,EACvB,MAAc;IAEd,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC;IAC5C,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,eAA0B,EAC1B,YAA6B,EAC7B,MAAc,EACd,cAAwC,EACxC,aAEoC;IAMpC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,eAAe,CAAC,eAAe,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;QACvE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACzE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IACE,CAAC,CAAC,GAAG,YAAY,sBAAsB,CAAC;YACxC,CAAC,kBAAkB,CAAC,GAAG,CAAC,EACxB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,+DAA+D;QAC/D,MAAM,CAAC,GAAG,MAAM,cAAc,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,CAAC,CAAC,CAAC;QACvC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC3D,CAAC;AACH,CAAC"}