@spfn/auth 0.2.0-beta.9 → 0.2.0-beta.90

package/dist/client-proof.d.ts

@@ -0,0 +1,677 @@
+import { KeyObject } from 'node:crypto';
+import { MiddlewareHandler } from 'hono';
+
+/**
+ * SPFN-CANON-JSON-1 — the canonical JSON form the mobile contract pins.
+ *
+ * The rules (contracts/mobile/spfn-mobile-contract.json `canonicalJson`):
+ * - object keys sorted ascending by UTF-8 byte sequence
+ * - no insignificant whitespace
+ * - numbers are signed 64-bit integers only
+ * - string escapes: `"` and `\` escaped; C0 controls use \b \f \n \r \t where
+ *   defined and lowercase \u00XX otherwise; every other scalar is emitted
+ *   literally as UTF-8
+ * - absent optional fields are omitted, never null
+ *
+ * JSON.parse cannot implement this: it loses int64 precision, accepts duplicate
+ * keys and (in V8) raw control characters, so both directions are hand-rolled.
+ * A proof binds the received bytes — parse-then-re-encode equality is what makes
+ * canonicity a rule a client can actually break.
+ *
+ * @module server/client-proof/canonical-json
+ */
+type CanonicalObject = Map<string, CanonicalValue>;
+type CanonicalValue = null | boolean | bigint | string | CanonicalValue[] | CanonicalObject;
+/**
+ * Parse failures carry the code the mobile conformance fixtures name
+ * (Contracts/fixtures/canonical/rejects.json), so the fixtures can assert on it.
+ */
+type CanonicalJsonErrorCode = 'DUPLICATE_KEY' | 'NON_INTEGER_NUMBER' | 'TRAILING_CONTENT' | 'UNEXPECTED_END' | 'INVALID_TOKEN' | 'INVALID_ESCAPE' | 'INTEGER_OUT_OF_RANGE' | 'INVALID_UTF8';
+declare class CanonicalJsonError extends Error {
+    readonly code: CanonicalJsonErrorCode;
+    constructor(code: CanonicalJsonErrorCode);
+}
+/**
+ * Parse bytes as SPFN-CANON-JSON-1.
+ *
+ * Arbitrary whitespace and key order are accepted here — parsing alone proves
+ * nothing about canonicity. Callers that must enforce it re-encode the result
+ * and compare bytes (see `isCanonicalBytes`).
+ */
+declare function parseCanonicalJson(bytes: Uint8Array): CanonicalValue;
+/** True when `bytes` are exactly the canonical encoding of the value they parse to. */
+declare function isCanonicalBytes(bytes: Uint8Array, value: CanonicalValue): boolean;
+/** Encode a value as SPFN-CANON-JSON-1 bytes. */
+declare function encodeCanonicalJson(value: CanonicalValue): Uint8Array;
+
+/**
+ * SPFN-PROOF-INPUT-1 — proof-input assembly and verification for clientProofV1.
+ *
+ * The proof input is 8 fields joined by `\n` in fixed order: profile, method,
+ * path, clientId, keyId, nonce, issuedAtMillis, bodySha256. Any C0 control
+ * character in any field is a hard refusal (the separator would otherwise be
+ * ambiguous), never something to escape. The proof is an ECDSA P-256 signature
+ * with SHA-256 over the canonical input's UTF-8 bytes, wire-encoded as the raw
+ * `r ‖ s` 64 bytes in base16-lower (128 hex characters). DER is never accepted
+ * on the wire: a platform signer that emits DER (Java `Signature`) converts to
+ * raw before sending. Low-S normalization is not required — uniqueness is owned
+ * by the nonce and replay window, so signature malleability cannot replay.
+ *
+ * @module server/client-proof/proof
+ */
+
+/** The only auth profile this module implements. */
+declare const CLIENT_PROOF_PROFILE = "clientProofV1";
+/** `bodySha256` when an operation carries no body: 64 zero characters. */
+declare const ABSENT_BODY_SHA256: string;
+/** The contract's `clientProofV1.replayWindowMillis`. */
+declare const DEFAULT_REPLAY_WINDOW_MILLIS = 300000;
+/** Raw `r ‖ s`: two 32-byte big-endian integers, always exactly this long. */
+declare const PROOF_SIGNATURE_BYTES = 64;
+/** The wire form is base16-lower of the raw signature: 128 hex characters. */
+declare const PROOF_SIGNATURE_HEX_LENGTH: number;
+interface ClientProofInput {
+    method: string;
+    path: string;
+    clientId: string;
+    keyId: string;
+    nonce: string;
+    issuedAtMillis: bigint;
+    bodySha256: string;
+}
+/** A C0 control character appeared in a proof field. */
+declare class ProofInputError extends Error {
+    constructor();
+}
+/**
+ * The canonical proof-input string the signature is taken over.
+ *
+ * @throws ProofInputError when any field contains a C0 control character.
+ */
+declare function canonicalProofInput(input: ClientProofInput): string;
+/**
+ * The contract's public-key representation — SPKI DER, base64 (the same
+ * representation `user_public_keys` and the web ES256 path store) — as a key
+ * object. Anything that is not a P-256 EC key is refused at parse time, so a
+ * key that could never verify a proof is never registered.
+ *
+ * @throws when the input is not base64 SPKI DER naming a P-256 key.
+ */
+declare function parseClientProofPublicKey(spkiDerBase64: string): KeyObject;
+/**
+ * Verifies a presented proof against `input` and a registered public key.
+ *
+ * The input is assembled first, so a C0 control character throws no matter
+ * what was presented — an unassemblable input is a contract violation, never
+ * a proof answer. Then the wire-format gate: a value that is not exactly 128
+ * lowercase hex characters — a DER signature, a truncated one, uppercase hex —
+ * is invalid before any cryptography happens.
+ *
+ * @throws ProofInputError when an input field contains a C0 control character.
+ */
+declare function verifyClientProof(input: ClientProofInput, presentedProof: string, publicKey: KeyObject): boolean;
+/**
+ * Signs `input` with a PKCS#8 DER base64 private key, producing the wire form
+ * (raw `r ‖ s`, base16-lower).
+ *
+ * The verifying half's counterpart, here for tests and dev clients — a
+ * production signer lives in the mobile SDKs against hardware-held keys.
+ */
+declare function signClientProof(input: ClientProofInput, privateKeyPkcs8DerBase64: string): string;
+/** Lowercase base16 SHA-256 of `bytes`. */
+declare function sha256Hex(bytes: Uint8Array): string;
+
+/** The six wire codes. The SDKs classify by code, never HTTP status. */
+type ClientProofErrorCode = 'PROOF_INVALID' | 'PROOF_REPLAYED' | 'PROOF_EXPIRED' | 'SESSION_REVOKED' | 'PROFILE_REJECTED' | 'CONTRACT_UNSUPPORTED';
+/** 128 random bits as lowercase base16 — request ids and control tokens. */
+declare function newHexId(): string;
+declare class ClientProofRefusal {
+    readonly code: ClientProofErrorCode;
+    readonly message: string;
+    constructor(code: ClientProofErrorCode, message: string);
+    get httpStatus(): number;
+    /** The canonical bytes of `{"error":{"code":…,"message":…,"requestId":…}}`. */
+    envelopeBytes(requestId: string): Uint8Array;
+    /** Nothing request-derived reaches a log through this. */
+    toString(): string;
+    static unroutable(): ClientProofRefusal;
+    static malformedHeaders(): ClientProofRefusal;
+    static missingContentType(): ClientProofRefusal;
+    static bodyTooLarge(): ClientProofRefusal;
+    /**
+     * The body parsed but its bytes are not the canonical form of what it
+     * parsed to. Not PROOF_INVALID even though it is discovered next to the
+     * proof: the proof over these bytes verifies perfectly well, and an
+     * auth-family answer would tell the client to re-handshake and send the
+     * same non-canonical bytes again.
+     */
+    static bodyNotCanonical(): ClientProofRefusal;
+    static bodyNotTheDeclaredType(): ClientProofRefusal;
+    static sessionHeaderMisplaced(): ClientProofRefusal;
+    static unprocessable(): ClientProofRefusal;
+    /**
+     * A client that ships separately from the server said nothing about which
+     * contract it was built against. Without it the server cannot tell whether
+     * the two ends agree, and answering as though they do is what produces the
+     * undecodable body this check exists to replace.
+     */
+    static contractVersionMissing(): ClientProofRefusal;
+    static contractVersionUnsupported(): ClientProofRefusal;
+    static profileRejected(): ClientProofRefusal;
+    static sessionRevoked(): ClientProofRefusal;
+    static proofExpired(): ClientProofRefusal;
+    static proofReplayed(): ClientProofRefusal;
+    static proofInvalid(): ClientProofRefusal;
+}
+
+/** Millisecond clock. Injectable so expiry paths are testable without waiting. */
+interface ClientProofClock {
+    nowMillis(): number;
+}
+declare function systemClock(): ClientProofClock;
+/** A clock a test (or the dev control surface) can move forward. */
+declare class TestClock implements ClientProofClock {
+    private millis;
+    constructor(millis: number);
+    nowMillis(): number;
+    advance(byMillis: number): void;
+}
+/** What `stats()` reports. Counters only; nothing a request carried. */
+interface ClientProofStats {
+    requestCount: number;
+    handshakeCount: number;
+    echoCount: number;
+    itemsListCount: number;
+    refusalCount: number;
+    liveSessionCount: number;
+    spentNonceCount: number;
+}
+interface ClientProofStateOptions {
+    /**
+     * keyId → registered public key, as SPKI DER base64. The private half
+     * never reaches the server: a client generates its keypair (hardware-held
+     * on mobile) and only the public key is registered — at construction here,
+     * or later through `registerPublicKey` (the dev `/control/register-key`
+     * route).
+     */
+    publicKeys: Record<string, string>;
+    clock?: ClientProofClock;
+    /** @default 600000 */
+    sessionTtlMillis?: number;
+    /** The contract's replay window. @default 300000 */
+    replayWindowMillis?: number;
+}
+declare const DEFAULT_SESSION_TTL_MILLIS = 600000;
+declare class ClientProofState {
+    readonly replayWindowMillis: number;
+    private readonly clock;
+    private readonly initialPublicKeys;
+    private readonly publicKeys;
+    private readonly sessions;
+    /** The replay ledger — the shared memory implementation, used dev-only here. */
+    private readonly spentNonces;
+    private readonly revokedKeyIds;
+    private readonly holds;
+    private readonly initialSessionTtlMillis;
+    private sessionTtlMillis;
+    private requestCount;
+    private handshakeCount;
+    private echoCount;
+    private itemsListCount;
+    private refusalCount;
+    constructor(options: ClientProofStateOptions);
+    /**
+     * Registers (or replaces) the public key `keyId` presents proofs under.
+     *
+     * @throws when the key is not base64 SPKI DER naming a P-256 key.
+     */
+    registerPublicKey(keyId: string, publicKeySpkiDerBase64: string): void;
+    /**
+     * Runs the contract's checks in the contract's order and returns the
+     * refusal, or null when the request is admitted (spending its nonce).
+     */
+    admit(args: {
+        clientId: string;
+        keyId: string;
+        presentedSessionId: string | null;
+        requiresSession: boolean;
+        proofInput: ClientProofInput;
+        presentedProof: string;
+    }): ClientProofRefusal | null;
+    /** Opens a session and returns its id and the expiry the server advertises. */
+    openSession(clientId: string, keyId: string): {
+        sessionId: string;
+        expiresAtMillis: number;
+    };
+    /** Test hook: installs a session with a chosen id (wire-fixture replays). */
+    seedSession(sessionId: string, clientId: string, keyId: string, expiresAtMillis: number): void;
+    /** Drops every session, as a restart would. Advertised expiries stay told. */
+    expireSessions(): void;
+    /** Revokes a key and drops the sessions it opened. */
+    revokeKey(keyId: string): void;
+    setSessionTtlMillis(millis: number): void;
+    /** Returns the state to how it started, counters and registered keys included. */
+    reset(): void;
+    /** Makes the next `count` requests to `path` wait `millis` before processing. */
+    holdPath(path: string, millis: number, count: number): void;
+    /** Consumes one configured delay for `path`; returns how long to wait, or 0. */
+    takeHoldMillis(path: string): number;
+    recordRequest(): void;
+    recordOperation(operationId: string): void;
+    recordRefusal(): void;
+    stats(): ClientProofStats;
+    nowMillis(): number;
+    /** The clock, exposed for the dev control surface's advance-clock route. */
+    get clockRef(): ClientProofClock;
+    /**
+     * Drops what can no longer affect an answer. The nonce predicate is the
+     * exact negation of the window check in `admit`: an entry is dropped only
+     * once a proof carrying that issuedAtMillis would be refused as expired
+     * anyway. Dropping one moment earlier would let a nonce inside the window
+     * be spent twice.
+     */
+    private prune;
+}
+
+/**
+ * The checks between a clientProofV1 request arriving and being applied.
+ *
+ * Shape first, then the profile allowlist, then the proof. That order is
+ * forced: none of the proof checks can run until the fields they read are
+ * known to be present and the body is known to be the bytes the digest is
+ * supposed to cover. The order *inside* the proof checks is the contract's and
+ * lives in `ClientProofState.admit`.
+ *
+ * @module server/client-proof/admission
+ */
+
+/** D23 wire-header names, ratified as proposed by the mobile dev bundle. */
+declare const CLIENT_PROOF_HEADERS: {
+    readonly profile: "x-spfn-auth-profile";
+    readonly clientId: "x-spfn-client-id";
+    readonly keyId: "x-spfn-key-id";
+    readonly nonce: "x-spfn-nonce";
+    readonly issuedAtMillis: "x-spfn-issued-at";
+    readonly proof: "x-spfn-proof";
+    readonly session: "x-spfn-session";
+};
+declare const CLIENT_PROOF_CONTENT_TYPE = "application/json";
+/** The contract header fields one request presented. */
+interface ClientProofCredentials {
+    profile: string;
+    clientId: string;
+    keyId: string;
+    nonce: string;
+    issuedAtMillis: bigint;
+    proof: string;
+    sessionId: string | null;
+}
+type Admission = {
+    admitted: false;
+    refusal: ClientProofRefusal;
+} | {
+    admitted: true;
+    value: CanonicalValue;
+    credentials: ClientProofCredentials;
+};
+/**
+ * Runs every check for one operation over already-read body bytes.
+ *
+ * `path` must be the operation's contract path (what the client signed), not a
+ * proxied or rewritten one.
+ */
+declare function admitClientProofRequest(args: {
+    state: ClientProofState;
+    headers: Headers;
+    method: string;
+    path: string;
+    requiresSession: boolean;
+    body: Uint8Array;
+}): Admission;
+/**
+ * The contract header fields, or null when any is absent or malformed.
+ *
+ * Fetch `Headers` folds a repeated field into one comma-joined value, so
+ * "sent more than once" is not directly observable here; a folded value fails
+ * either the issuedAt grammar or proof verification instead.
+ *
+ * Exported for the authenticate middleware's profile path, which runs the
+ * same shape checks over arbitrary routes.
+ */
+declare function readCredentials(headers: Headers): ClientProofCredentials | null;
+/** Exported for the authenticate middleware's profile path. */
+declare function isRequestContentType(value: string | null): boolean;
+
+/**
+ * The ledger key. `JSON.stringify` of the pair, so no crafted clientId/nonce
+ * concatenation can collide with another pair — the fields are checked for C0
+ * controls only later, at proof verification, so the key must be unambiguous
+ * for arbitrary strings.
+ */
+declare function replayLedgerKey(clientId: string, nonce: string): string;
+/**
+ * What the middleware's replay ledger must answer. Both methods may reject;
+ * the caller refuses the request when they do (fail-closed).
+ */
+interface ClientProofReplayStore {
+    /** True when (clientId, nonce) was already spent inside the window. */
+    isSpent(clientId: string, nonce: string): Promise<boolean>;
+    /**
+     * Records the pair as spent. False when it was already spent — the caller
+     * lost a race and must answer PROOF_REPLAYED, not accept twice.
+     */
+    spend(clientId: string, nonce: string): Promise<boolean>;
+}
+/**
+ * The in-memory ledger — the single implementation of the window semantics.
+ *
+ * Entries carry the millisecond they were recorded at; `prune` drops an entry
+ * only once a proof carrying that timestamp would be refused as expired
+ * anyway (the exact negation of the admission window check). All methods are
+ * synchronous so `ClientProofState.admit` can stay atomic on Node's single
+ * thread.
+ */
+declare class MemoryReplayLedger {
+    /** replayLedgerKey(...) → the millis it was spent at. */
+    private readonly spent;
+    isSpent(clientId: string, nonce: string): boolean;
+    /** Records the pair at `atMillis`; false when it was already spent. */
+    spend(clientId: string, nonce: string, atMillis: number): boolean;
+    /** Drops entries older than the window, judged against `nowMillis`. */
+    prune(nowMillis: number, windowMillis: number): void;
+    get size(): number;
+    clear(): void;
+}
+/**
+ * The default store: a process-local `MemoryReplayLedger` on the wall clock.
+ *
+ * Correct for a single process. Behind a multi-instance deployment each
+ * instance keeps its own ledger, so a replay against a *different* instance
+ * is not seen — that deployment opts into `RedisReplayStore`.
+ */
+declare class MemoryReplayStore implements ClientProofReplayStore {
+    private readonly windowMillis;
+    private readonly ledger;
+    constructor(windowMillis?: number);
+    isSpent(clientId: string, nonce: string): Promise<boolean>;
+    spend(clientId: string, nonce: string): Promise<boolean>;
+}
+/**
+ * The opt-in shared ledger over `getCache()` (ioredis): `SET NX PX <window>`.
+ *
+ * The key hashes the pair, so arbitrary clientId/nonce strings become short,
+ * safe Redis keys with no ambiguity. `PX` makes Redis expire the entry itself
+ * exactly when a proof reusing the nonce would pass the window check again.
+ *
+ * Fail-closed by construction: when the cache is not configured or a command
+ * rejects, the error propagates and the caller refuses the request. Nothing
+ * here answers "not spent" on a store it could not reach.
+ */
+declare class RedisReplayStore implements ClientProofReplayStore {
+    private readonly windowMillis;
+    constructor(windowMillis?: number);
+    isSpent(clientId: string, nonce: string): Promise<boolean>;
+    spend(clientId: string, nonce: string): Promise<boolean>;
+    private cache;
+    private key;
+}
+/**
+ * Installs the replay store the authenticate middleware uses. Pass
+ * `new RedisReplayStore()` to opt into the shared ledger; pass null to return
+ * to the in-memory default.
+ */
+declare function configureClientProofReplayStore(store: ClientProofReplayStore | null): void;
+/** The configured store, or a lazily created in-memory default. */
+declare function getClientProofReplayStore(): ClientProofReplayStore;
+
+/**
+ * The mobile dev-contract types and operations, decoded from / encoded to
+ * canonical values. Strict on purpose: a missing required field, a wrong type
+ * or an unknown field is "not the request type this operation declares".
+ *
+ * This module is the source of truth for `operations`. The exported contract
+ * bundle (`contracts/mobile/spfn-mobile-contract.json`) is generated from it
+ * by `contract-bundle.ts`; spfn-mobile consumes that export rather than the
+ * other way round.
+ *
+ * @module server/client-proof/contract-types
+ */
+
+interface ContractOperation {
+    id: 'auth.clientProof.handshake' | 'echo.send' | 'items.list' | 'auth.enroll.register' | 'auth.enroll.login' | 'auth.enroll.oauthNative' | 'auth.keys.rotate' | 'auth.keys.list' | 'auth.keys.revoke' | 'auth.keys.revokeAll';
+    method: 'POST';
+    path: string;
+    /**
+     * How a call is admitted. `clientProofV1` operations run the proof
+     * admission order; `none` operations are the unproven class — accepted
+     * with neither proof headers nor a session header, because enrollment is
+     * called before any key exists to sign with.
+     */
+    authProfile: 'clientProofV1' | 'none';
+    requiresSession: boolean;
+    requestType: string;
+    responseType: string;
+    summary: string;
+}
+declare const CONTRACT_OPERATIONS: readonly ContractOperation[];
+/**
+ * The `/_auth` surface exported into the mobile contract: enrollment, login
+ * and key rotation. These are ordinary SPFN REST routes, not canonical-JSON
+ * operations — the dev handler never serves them, and their wire rules are
+ * the `restOperations` section of the bundle, not `canonicalJson`.
+ *
+ * The three `authProfile: 'none'` operations are the unproven class: they are
+ * accepted with neither proof headers nor a session header, because they are
+ * how a client obtains a key in the first place. `auth.keys.rotate` requires
+ * an authenticated caller (a clientProofV1 proof on this surface); an
+ * unproven call to it is refused like any failed admission.
+ */
+declare const AUTH_SURFACE_OPERATIONS: readonly ContractOperation[];
+/** The body is canonical JSON but not the declared request type. */
+declare class ContractTypeError extends Error {
+    constructor();
+}
+interface HandshakeRequest {
+    clientId: string;
+    keyId: string;
+    nonce: string;
+    issuedAtMillis: bigint;
+}
+interface EchoRequest {
+    message: string;
+    sequence: bigint;
+}
+interface ListItemsRequest {
+    limit: bigint;
+    cursor?: string;
+}
+interface ContractItem {
+    id: string;
+    name: string;
+    updatedAtMillis: bigint;
+}
+declare function decodeHandshakeRequest(value: CanonicalValue): HandshakeRequest;
+declare function decodeEchoRequest(value: CanonicalValue): EchoRequest;
+declare function decodeListItemsRequest(value: CanonicalValue): ListItemsRequest;
+declare function encodeHandshakeResponse(sessionId: string, expiresAtMillis: bigint): CanonicalValue;
+declare function encodeEchoResponse(message: string, sequence: bigint, serverTimeMillis: bigint): CanonicalValue;
+declare function encodeListItemsResponse(items: ContractItem[], nextCursor: string | null): CanonicalValue;
+
+/**
+ * The items `items.list` pages through — fixed and small on purpose, matching
+ * the spfn-mobile reference catalogue byte for byte so an integration test can
+ * assert exact values against either server.
+ */
+declare const DEV_CATALOGUE: readonly ContractItem[];
+/** The largest `items.list` page this server will answer with. */
+declare const DEV_MAX_LIMIT = 100n;
+interface ClientProofDevHandlerOptions extends ClientProofStateOptions {
+    /**
+     * Token the `/control` routes require (header `x-spfn-reference-control`).
+     * Generated per construction when omitted; never logged.
+     */
+    controlToken?: string;
+    /** Disables the `/control` surface entirely. @default true */
+    enableControl?: boolean;
+    /** One line per request: method, path, status. Nothing a request carried. */
+    log?: (line: string) => void;
+}
+interface ClientProofDevHandler {
+    fetch(request: Request): Promise<Response>;
+    state: ClientProofState;
+    controlToken: string;
+}
+declare function createClientProofDevHandler(options: ClientProofDevHandlerOptions): ClientProofDevHandler;
+
+declare const CONTROL_PREFIX = "/control/";
+declare const CONTROL_TOKEN_HEADER = "x-spfn-reference-control";
+
+/**
+ * Hono middleware adapter for clientProofV1 — the `requiresSession` guard for
+ * SPFN servers that mount contract operations as ordinary routes.
+ *
+ * Runs the full admission sequence over the raw request bytes and, on
+ * acceptance, tags the request `clientType: 'mobile'` (the attestation slot
+ * PROXY-BACKEND-AUTH-SPEC reserved) and exposes the parsed canonical body and
+ * credentials under the `clientProof` context key.
+ *
+ * hono is imported as types only — the middleware itself is a plain async
+ * function, so this module adds no runtime dependency.
+ *
+ * @module server/client-proof/guard
+ */
+
+/** What the guard leaves in the context for the route handler. */
+interface ClientProofContext {
+    credentials: ClientProofCredentials;
+    /** The request body as a canonical value (already byte-verified). */
+    value: CanonicalValue;
+}
+interface ClientProofGuardOptions {
+    /**
+     * The contract path the client signed, when it differs from the mounted
+     * path (e.g. behind a stripped ingress prefix). Defaults to the request
+     * path.
+     */
+    contractPath?: string;
+}
+/**
+ * A guard for operations with `requiresSession: true`.
+ *
+ * Refusals are answered with the contract envelope and never reach the route.
+ */
+declare function createClientProofGuard(state: ClientProofState, options?: ClientProofGuardOptions): MiddlewareHandler;
+
+/**
+ * The header names each end announces itself under.
+ *
+ * Separated from the logic that reads them so the contract bundle can name them
+ * without importing the version comparison, which reads the bundle back. These
+ * are declarations and depend on nothing.
+ *
+ * @module server/client-proof/wire-headers
+ */
+/** What a client says about itself, one header each. */
+declare const CLIENT_IDENTITY_HEADERS: {
+    readonly kind: "x-spfn-client-kind";
+    readonly version: "x-spfn-client-version";
+    readonly contractVersion: "x-spfn-client-contract-version";
+};
+/**
+ * What the server says about itself, on every response.
+ *
+ * Distinct names from the request headers on purpose: a proxy that echoes a
+ * request header into the response would otherwise make the client's own
+ * version look like the server's.
+ */
+declare const SERVER_CONTRACT_HEADERS: {
+    readonly version: "x-spfn-server-contract-version";
+    readonly supportedRange: "x-spfn-supported-contract-range";
+};
+/**
+ * The client kinds the server distinguishes.
+ *
+ * `web` is separated from the two app kinds because it carries no contract
+ * version: a browser bundle is deployed with the server that serves it, so
+ * there is no second version to reconcile.
+ */
+declare const CLIENT_KINDS: readonly ["web", "ios", "android"];
+type ClientKind = typeof CLIENT_KINDS[number];
+/** A kind that ships independently of the server, so its contract version matters. */
+declare function isAppKind(kind: ClientKind): boolean;
+
+/** What one request announced about the client that sent it. */
+interface ClientIdentity {
+    kind: ClientKind;
+    /** The client's own release — a store version, or a bundle build. */
+    version: string | null;
+    /** The contract version the client was generated from. Never set for `web`. */
+    contractVersion: string | null;
+}
+/**
+ * Reads the identity headers, or null when the kind is absent or unrecognised.
+ *
+ * Null is not by itself a refusal — a request from something that predates
+ * these headers reaches here too. `judgeClientIdentity` decides.
+ */
+declare function readClientIdentity(headers: Headers): ClientIdentity | null;
+/**
+ * Whether the server serves what the client was generated against.
+ *
+ * Under 0.x the minor carries breaking changes, so a supported client agrees on
+ * major and minor. From 1.0.0 the major alone decides. This is the rule
+ * `CONTRACT_SUPPORTED_RANGE` spells out; keeping it as a comparison rather than
+ * parsing that string leaves one place to change when the line reaches 1.0.0.
+ */
+declare function isContractVersionSupported(clientVersion: string): boolean;
+/**
+ * The refusal a request's announced identity earns, or null to let it through.
+ *
+ * An app kind must state a contract version this server serves. A version it
+ * does not serve, and the absence of one, are the same answer: the two ends do
+ * not agree on what the contract is, which is what CONTRACT_UNSUPPORTED means.
+ * The response carries the server's version and range, so the client can say
+ * which way the gap runs.
+ *
+ * `web` is exempt from the contract check by construction, not by leniency.
+ *
+ * A request with no recognised kind passes. The check is on what a client says
+ * about itself, and a caller that says nothing — a curl, a health probe, a
+ * server-to-server call — is not a deployed client this rule is about.
+ */
+declare function judgeClientIdentity(identity: ClientIdentity | null): ClientProofRefusal | null;
+/** Writes the server's own announcement onto a response's headers. */
+declare function applyServerContractHeaders(headers: Headers): void;
+/** The same announcement as a plain object, for a response built from one. */
+declare function serverContractHeaders(): Record<string, string>;
+
+/**
+ * The version announcement, applied to every request rather than to the proven
+ * ones.
+ *
+ * Enrollment and login are the first calls a client makes and they carry no
+ * proof — there is no key to sign with yet. A check that lives inside proof
+ * admission therefore never sees the client it is meant to catch: an outdated
+ * app fails at login, before it reaches anything proven. This runs ahead of all
+ * of it.
+ *
+ * hono is imported as types only, so this module adds no runtime dependency.
+ *
+ * @module server/client-proof/version-middleware
+ */
+
+/** The context key the identity is left under, for a handler that wants it. */
+declare const CLIENT_IDENTITY_CONTEXT_KEY = "clientIdentity";
+/**
+ * Announces the server's contract version on every response and refuses a
+ * client whose own contract version this server does not serve.
+ *
+ * The announcement goes out either way. A refused client needs it most — the
+ * refusal says the two ends disagree, and the range is what says how.
+ *
+ * Mount this before authentication, not after: the point is to answer a stale
+ * client before anything else has a chance to fail confusingly.
+ */
+declare function createClientVersionMiddleware(): MiddlewareHandler;
+
+export { ABSENT_BODY_SHA256, AUTH_SURFACE_OPERATIONS, type Admission, CLIENT_IDENTITY_CONTEXT_KEY, CLIENT_IDENTITY_HEADERS, CLIENT_KINDS, CLIENT_PROOF_CONTENT_TYPE, CLIENT_PROOF_HEADERS, CLIENT_PROOF_PROFILE, CONTRACT_OPERATIONS, CONTROL_PREFIX, CONTROL_TOKEN_HEADER, CanonicalJsonError, type CanonicalJsonErrorCode, type CanonicalObject, type CanonicalValue, type ClientIdentity, type ClientKind, type ClientProofClock, type ClientProofContext, type ClientProofCredentials, type ClientProofDevHandler, type ClientProofDevHandlerOptions, type ClientProofErrorCode, type ClientProofGuardOptions, type ClientProofInput, ClientProofRefusal, type ClientProofReplayStore, ClientProofState, type ClientProofStateOptions, type ClientProofStats, type ContractItem, type ContractOperation, ContractTypeError, DEFAULT_REPLAY_WINDOW_MILLIS, DEFAULT_SESSION_TTL_MILLIS, DEV_CATALOGUE, DEV_MAX_LIMIT, type EchoRequest, type HandshakeRequest, type ListItemsRequest, MemoryReplayLedger, MemoryReplayStore, PROOF_SIGNATURE_BYTES, PROOF_SIGNATURE_HEX_LENGTH, ProofInputError, RedisReplayStore, SERVER_CONTRACT_HEADERS, TestClock, admitClientProofRequest, applyServerContractHeaders, canonicalProofInput, configureClientProofReplayStore, createClientProofDevHandler, createClientProofGuard, createClientVersionMiddleware, decodeEchoRequest, decodeHandshakeRequest, decodeListItemsRequest, encodeCanonicalJson, encodeEchoResponse, encodeHandshakeResponse, encodeListItemsResponse, getClientProofReplayStore, isAppKind, isCanonicalBytes, isContractVersionSupported, isRequestContentType, judgeClientIdentity, newHexId, parseCanonicalJson, parseClientProofPublicKey, readClientIdentity, readCredentials, replayLedgerKey, serverContractHeaders, sha256Hex, signClientProof, systemClock, verifyClientProof };