@sempdev/semp 0.4.3

package/dist/handshake/client_state.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Stateful handshake client per HANDSHAKE.md §2.
+ *
+ * Mirror of `semp-go/handshake.Client`: a state machine the caller
+ * drives over a transport. The class never performs network I/O
+ * directly — the caller moves bytes between this object and the
+ * underlying transport.
+ *
+ * Lifecycle:
+ *
+ * ```ts
+ * const c = new HandshakeClient({ ... });
+ * const initBytes = c.init();
+ * await transport.send(initBytes);
+ *
+ * // optional challenge interstitial:
+ * const m = await transport.receive();
+ * if (peekStep(m) === "challenge") {
+ *   const sol = await c.onChallenge(m);
+ *   await transport.send(sol);
+ *   m = await transport.receive();
+ * }
+ *
+ * const confirmBytes = c.onResponse(m);
+ * await transport.send(confirmBytes);
+ *
+ * const accepted = await transport.receive();
+ * c.onAccepted(accepted);
+ * // c.session() now usable
+ * ```
+ *
+ * Resume flow uses {@link HandshakeClient.resume} +
+ * {@link HandshakeClient.onResumeAccepted}; see
+ * {@link "./resume_driver"}.
+ *
+ * The high-level {@link "./driver".runClient} wraps this state
+ * machine with the transport plumbing for callers who don't want
+ * to manage step ordering manually.
+ *
+ * @module
+ */
+import { type SessionKeys } from "../crypto/index.js";
+import { HandshakeRejectedError } from "./driver.js";
+import { type Capabilities } from "./messages.js";
+/**
+ * Configuration for a {@link HandshakeClient}. Same fields as
+ * {@link "./driver".ClientConfig} but the client class owns its own
+ * lifecycle.
+ */
+export interface HandshakeClientConfig {
+    suite: "x25519-chacha20-poly1305";
+    capabilities: Capabilities;
+    /** Transport identifier ("ws", "h2", "quic"). */
+    transport: string;
+    /** Server domain Ed25519 public key, pre-shared via discovery. */
+    serverDomainPub: Uint8Array;
+    /** Optional pre-generated client ephemeral private (deterministic tests). */
+    clientEphemeralPriv?: Uint8Array;
+    /** Optional pre-generated 32-byte client nonce. */
+    clientNonce?: Uint8Array;
+    /**
+     * Optional identity-proof material. When supplied, {@link onResponse}
+     * builds the §2.5.2 encrypted identity_proof block; when omitted,
+     * the proof field is left empty.
+     */
+    identity?: {
+        clientId: string;
+        clientIdentity: string;
+        longTermSeed: Uint8Array;
+        longTermKeyId: string;
+        /** Optional 12-byte AEAD nonce for deterministic tests. */
+        proofNonce?: Uint8Array;
+    };
+}
+/** Outcome of a successful client-side handshake. */
+export interface HandshakeClientSession {
+    sessionId: string;
+    sessionTTL: number;
+    permissions: string[];
+    keys: SessionKeys;
+    serverIdentityProofKeyId: string;
+    serverIdentityProofSignature: string;
+    extensions: Record<string, unknown>;
+    resumptionTicket?: {
+        value: string;
+        expires_at: string;
+    };
+}
+export { HandshakeRejectedError };
+/**
+ * Stateful handshake client. One instance handles exactly one
+ * handshake — discard after success or error. Re-using an instance
+ * is a programming error (the state machine is single-shot).
+ */
+export declare class HandshakeClient {
+    private readonly suite;
+    private readonly serverDomainPub;
+    private readonly capabilities;
+    private readonly transportId;
+    private readonly identity;
+    private nonce;
+    private ephPriv;
+    private ephPub;
+    private initCanonical;
+    private sessionId;
+    private sessionKeys;
+    private serverIdProofKeyId;
+    private serverIdProofSignature;
+    private resumptionSecret;
+    private resumeNonce;
+    /** Final session — populated by {@link onAccepted}. */
+    private finalSession;
+    constructor(cfg: HandshakeClientConfig);
+    /**
+     * Build INIT bytes (HANDSHAKE.md §2.2). Generates a fresh nonce
+     * and ephemeral keypair if not pre-pinned. Returns canonical
+     * bytes ready to send.
+     */
+    init(): Uint8Array;
+    /**
+     * Process a `step="challenge"` message and produce
+     * `step="challenge_response"` bytes per HANDSHAKE.md §2.2a.
+     *
+     * Throws {@link ChallengeInvalidError} when the difficulty
+     * exceeds the protocol cap or the challenge has already
+     * expired — the caller follows up with a §2.2a.6 client abort.
+     */
+    onChallenge(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Process the server's RESPONSE, derive session keys, and produce
+     * CONFIRM bytes per §2.3 — §2.5. The ephemeral private key is
+     * zeroed before return.
+     */
+    onResponse(data: Uint8Array): Uint8Array;
+    /**
+     * Process the server's ACCEPTED and finalize the session record
+     * exposed by {@link session}.
+     *
+     * Throws {@link HandshakeRejectedError} if the server sent
+     * a REJECTED instead.
+     */
+    onAccepted(data: Uint8Array): void;
+    /**
+     * Decode a `step="rejected"` message into a typed error. Use when
+     * the caller wants to surface a rejection without needing to
+     * dispatch via `onResponse` / `onAccepted` first.
+     */
+    onRejected(data: Uint8Array): HandshakeRejectedError;
+    /**
+     * Build a `step="resume"` message for HANDSHAKE.md §2.8.2 session
+     * resumption.
+     *
+     * `ticket` is the opaque value stored by the caller from a prior
+     * `accepted.resumption_ticket.value`. The returned bytes are sent
+     * on the new transport; the server replies with ACCEPTED (handle
+     * via {@link onResumeAccepted}) or REJECTED.
+     *
+     * The caller MUST also have the prior session's `K_resumption`
+     * loaded via {@link loadResumptionSecret} before this call so the
+     * resumed session keys can be derived.
+     */
+    resume(ticket: string): Uint8Array;
+    /**
+     * Process a server ACCEPTED in response to {@link resume} and
+     * derive resumed session keys per §2.8.3. Returns the new
+     * resumption ticket the server issued for chaining.
+     */
+    onResumeAccepted(data: Uint8Array): {
+        session: HandshakeClientSession;
+        newTicket: string | undefined;
+    };
+    /**
+     * Load the prior session's `K_resumption` before calling
+     * {@link resume}. The key is mixed into the resumed-session HKDF
+     * input keying material per §2.8.3 and zeroized after use.
+     */
+    loadResumptionSecret(secret: Uint8Array): void;
+    /** Final session, populated by {@link onAccepted} or {@link onResumeAccepted}. */
+    session(): HandshakeClientSession;
+    /**
+     * Wipe in-memory secret state. Idempotent. Call when abandoning a
+     * partial handshake.
+     */
+    erase(): void;
+}
+//# sourceMappingURL=client_state.d.ts.map

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

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