@spfn/auth 0.2.0-beta.85 → 0.2.0-beta.87

package/README.md

@@ -552,11 +552,14 @@ middleware. Call `initOneTimeTokenManager({ ttl, store })` during setup for a cu
 
 ## Mobile clientProofV1 (`@spfn/auth/client-proof`)
 
-Server side of the spfn-mobile native SDK auth profile (issue #46). Implements the pinned
-mobile contract exactly: SPFN-CANON-JSON-1 canonical JSON (custom parser/encoder — int64 via
-BigInt, duplicate-key rejection, UTF-8 byte key order), SPFN-PROOF-INPUT-1 HMAC-SHA-256 proof
-verification (constant-time), the contract admission order (revoked → session → expired →
-replayed → HMAC; a nonce is spent only on admission), in-memory session issuance/expiry, and
+Server side of the spfn-mobile native SDK auth profile (issue #46; asymmetric revision in
+contract 0.2.0). Implements the pinned mobile contract exactly: SPFN-CANON-JSON-1 canonical
+JSON (custom parser/encoder — int64 via BigInt, duplicate-key rejection, UTF-8 byte key
+order), SPFN-PROOF-INPUT-1 proof assembly with ECDSA P-256 + SHA-256 signature verification
+(wire form: raw `r‖s`, 64 bytes, base16-lower; DER is rejected, low-S is not required — the
+nonce + replay window own uniqueness), the contract admission order (revoked → session →
+expired → replayed → signature; a nonce is spent only on admission), in-memory session
+issuance/expiry, and
 the fixed-string contract error envelope (`PROOF_INVALID` · `PROOF_REPLAYED` · `PROOF_EXPIRED` ·
 `SESSION_REVOKED` · `PROFILE_REJECTED` · `CONTRACT_UNSUPPORTED` — SDKs classify by code, never
 HTTP status).
@@ -577,8 +580,70 @@ HTTP status).
 - Conformance: spfn-mobile fixtures are vendored under
   `src/server/client-proof/__tests__/fixtures/` (digest-pinned to upstream `MANIFEST.json`,
   dev bundle sha256 `07fd8268…a433e45`) and run in the unit suite.
-- Dev/test scope: key provisioning is injection at construction; no persistence. A production
-  key/issuance story is a separate work item.
+- Dev/test scope: public keys (SPKI DER base64, keyed by `x-spfn-key-id`) are registered at
+  construction or through the `/control/register-key` hook; the private half never reaches
+  the server. No persistence — a production enrollment/rotation story is phase 2.
+
+### Usage — dev surface (mobile integration target)
+
+The fastest path: run the packaged dev handler, which already serves the three contract
+operations and `/control`. `examples/04-mobile-contract-dev` is exactly this, runnable.
+
+```typescript
+import { serve } from '@hono/node-server';
+import { createClientProofDevHandler } from '@spfn/auth/client-proof';
+
+const handler = createClientProofDevHandler({
+    // keyId → registered public key (SPKI DER base64); the private key stays on the client
+    publicKeys: { 'key-dev-0001': process.env.SPFN_CLIENT_PROOF_PUBLIC_KEY! },
+    sessionTtlMillis: 600_000,
+});
+serve({ fetch: handler.fetch, port: 8791, hostname: '127.0.0.1' });
+// handler.controlToken — pass to the test harness for /control routes
+// handler.state       — revokeKey() / expireSessions() / stats() from code
+```
+
+### Usage — mounting on your own Hono/SPFN server
+
+Protect `requiresSession` operations with the guard, and assemble the handshake route from
+the exported primitives (`admitClientProofRequest` + `state.openSession`):
+
+```typescript
+import { Hono } from 'hono';
+import {
+    ClientProofState, createClientProofGuard, admitClientProofRequest,
+    decodeHandshakeRequest, encodeHandshakeResponse, encodeCanonicalJson,
+    ClientProofRefusal, newHexId,
+} from '@spfn/auth/client-proof';
+
+const state = new ClientProofState({ publicKeys: { 'key-dev-0001': process.env.SPFN_CLIENT_PROOF_PUBLIC_KEY! } });
+const app = new Hono();
+
+app.post('/v1/auth/client-proof/handshake', async (c) =>
+{
+    const body = new Uint8Array(await c.req.arrayBuffer());
+    const admission = admitClientProofRequest({
+        state, headers: c.req.raw.headers, method: 'POST',
+        path: '/v1/auth/client-proof/handshake', requiresSession: false, body,
+    });
+    if (!admission.admitted)
+    {
+        return c.newResponse(admission.refusal.envelopeBytes(newHexId()).slice().buffer,
+            admission.refusal.httpStatus as 401, { 'content-type': 'application/json' });
+    }
+    const request = decodeHandshakeRequest(admission.value);
+    const opened = state.openSession(request.clientId, request.keyId);
+    return c.newResponse(
+        encodeCanonicalJson(encodeHandshakeResponse(opened.sessionId, BigInt(opened.expiresAtMillis))).slice().buffer,
+        200, { 'content-type': 'application/json' });
+});
+
+// Any route behind the guard sees clientType='mobile' and c.get('clientProof')
+app.post('/v1/echo', createClientProofGuard(state), (c) => { /* handler */ });
+```
+
+Responses and errors MUST be canonical bytes with the contract envelope — build them with
+`encodeCanonicalJson`/`ClientProofRefusal`, never `c.json()` (key order and int64 differ).
 
 ## Account Deletion & Recovery
 

package/dist/{authenticate-ngWdlWWL.d.ts → authenticate-C7w-pLOR.d.ts}

@@ -2,6 +2,7 @@ import * as _spfn_core_route from '@spfn/core/route';
 import { K as KeyAlgorithmType, e as SocialProvider } from './types-1BMx0OX1.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
+import { Context } from 'hono';
 import { User } from '@spfn/auth/server';
 
 /**
@@ -1104,13 +1105,67 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }>;
 }>;
 
+/**
+ * The auth-profile registry the authenticate middleware dispatches on.
+ *
+ * A request that names `x-spfn-auth-profile` is answered by the verifier
+ * registered for that profile — an O(1) map lookup, never a per-profile if
+ * chain in the middleware body. A request that names no profile falls through
+ * to the existing Bearer path untouched.
+ *
+ * Every verifier converges on the same `AuthContext` the Bearer path sets, so
+ * downstream permission/tenant code consumes one principal shape and never
+ * branches on how it was authenticated.
+ *
+ * The clientProofV1 verifier reuses the phase-1 admission pieces (header
+ * shape, canonical body, proof-input assembly, ECDSA verification) with two
+ * production substitutions: the key directory is `user_public_keys` via
+ * `keysRepository`, and the replay ledger is the pluggable store from
+ * `client-proof/replay-store` (memory default, Redis opt-in). The admission
+ * order is the contract's — revocation → session → expiry → replay → proof —
+ * and the non-disclosure rule holds: an unregistered keyId shares
+ * PROOF_INVALID with a failed signature, while a revoked or expired key
+ * answers SESSION_REVOKED before the proof is ever examined.
+ *
+ * @module server/middleware/auth-profiles
+ */
+
+/** What a verified request leaves in the context — one shape for every scheme. */
 interface AuthContext {
     user: User;
     userId: string;
     keyId: string;
     role: string | null;
     locale: string;
+    /** How the principal was authenticated. Informational — downstream code never branches on it. */
+    scheme: 'bearer' | 'clientProofV1' | 'oneTimeToken';
+}
+/** A profile's verifier: admits the request and returns the principal, or throws. */
+interface AuthProfileVerifier {
+    verify(c: Context): Promise<AuthContext>;
 }
+/**
+ * Routes a request to its profile verifier.
+ *
+ * - no profile header → null: the caller continues on the Bearer path;
+ * - profile header + Authorization header → rejected (mixing prohibited);
+ * - unknown profile value → rejected (unknownProfilePolicy: reject).
+ *
+ * Shared by authenticate and optionalAuth so "presented but invalid" refuses
+ * identically on both — only the "presented nothing" outcome differs.
+ */
+declare function selectAuthProfile(c: Context): AuthProfileVerifier | null;
+/**
+ * Loads the user for an authenticated key and applies the account-status
+ * rules. One implementation for every scheme: the Bearer path and the profile
+ * verifiers call this, so a status added here gates both identically.
+ */
+declare function resolveAuthenticatedUser(userId: number): Promise<{
+    user: User;
+    role: string | null;
+    locale: string;
+}>;
+
 declare module 'hono' {
     interface ContextVariableMap {
         auth: AuthContext;
@@ -1176,4 +1231,4 @@ declare const authenticate: _spfn_core_route.NamedMiddleware<"auth">;
  */
 declare const optionalAuth: _spfn_core_route.NamedMiddleware<"optionalAuth">;
 
-export { type OAuthCallbackResult as $, type AuthSession as A, rotateKeyService as B, type ChangePasswordParams as C, revokeKeyService as D, type RegisterPublicKeyParams as E, type RotateKeyParams as F, type RevokeKeyParams as G, issueOneTimeTokenService as H, type IssueOneTimeTokenResult as I, verifyOneTimeTokenService as J, oauthStartService as K, type LoginResult as L, oauthCallbackService as M, buildOAuthErrorUrl as N, type OAuthStartResult as O, type PermissionConfig as P, isOAuthProviderEnabled as Q, type RoleConfig as R, type SendVerificationCodeResult as S, requireEnabledProvider as T, type UserProfile as U, type VerificationTargetType as V, getEnabledOAuthProviders as W, getGoogleAccessToken as X, oauthUnlinkNotifyService as Y, type OAuthStartParams as Z, type OAuthCallbackParams as _, type RegisterResult as a, type UnlinkNotifyResult as a0, oauthNativeService as a1, type OAuthNativeParams as a2, authenticate as a3, optionalAuth as a4, EmailSchema as a5, PhoneSchema as a6, PasswordSchema as a7, TargetTypeSchema as a8, VerificationPurposeSchema as a9, type NormalizedIdentity as aa, type OAuthTokens as ab, type NativeVerifyOptions as ac, type OAuthCodeExchangeOptions as ad, type UnlinkNotifyRequest as ae, type UnlinkNotification as af, UnlinkNotifyRejection as ag, registerOAuthProvider as ah, getOAuthProvider as ai, getRegisteredProviders as aj, type RotateKeyResult as b, type OAuthNativeResult as c, type ProfileInfo as d, type VerificationPurpose as e, VERIFICATION_TARGET_TYPES as f, VERIFICATION_PURPOSES as g, PERMISSION_CATEGORIES as h, type PermissionCategory as i, type AuthInitOptions as j, type OAuthProvider as k, type AuthContext as l, mainAuthRouter as m, loginService as n, logoutService as o, changePasswordService as p, type RegisterParams as q, registerService as r, type LoginParams as s, type LogoutParams as t, sendVerificationCodeService as u, verifyCodeService as v, type SendVerificationCodeParams as w, type VerifyCodeParams as x, type VerifyCodeResult as y, registerPublicKeyService as z };
+export { type OAuthCallbackResult as $, type AuthSession as A, rotateKeyService as B, type ChangePasswordParams as C, revokeKeyService as D, type RegisterPublicKeyParams as E, type RotateKeyParams as F, type RevokeKeyParams as G, issueOneTimeTokenService as H, type IssueOneTimeTokenResult as I, verifyOneTimeTokenService as J, oauthStartService as K, type LoginResult as L, oauthCallbackService as M, buildOAuthErrorUrl as N, type OAuthStartResult as O, type PermissionConfig as P, isOAuthProviderEnabled as Q, type RoleConfig as R, type SendVerificationCodeResult as S, requireEnabledProvider as T, type UserProfile as U, type VerificationTargetType as V, getEnabledOAuthProviders as W, getGoogleAccessToken as X, oauthUnlinkNotifyService as Y, type OAuthStartParams as Z, type OAuthCallbackParams as _, type RegisterResult as a, type UnlinkNotifyResult as a0, oauthNativeService as a1, type OAuthNativeParams as a2, selectAuthProfile as a3, resolveAuthenticatedUser as a4, type AuthProfileVerifier as a5, authenticate as a6, optionalAuth as a7, EmailSchema as a8, PhoneSchema as a9, PasswordSchema as aa, TargetTypeSchema as ab, VerificationPurposeSchema as ac, type NormalizedIdentity as ad, type OAuthTokens as ae, type NativeVerifyOptions as af, type OAuthCodeExchangeOptions as ag, type UnlinkNotifyRequest as ah, type UnlinkNotification as ai, UnlinkNotifyRejection as aj, registerOAuthProvider as ak, getOAuthProvider as al, getRegisteredProviders as am, type RotateKeyResult as b, type OAuthNativeResult as c, type ProfileInfo as d, type VerificationPurpose as e, VERIFICATION_TARGET_TYPES as f, VERIFICATION_PURPOSES as g, PERMISSION_CATEGORIES as h, type PermissionCategory as i, type AuthInitOptions as j, type OAuthProvider as k, type AuthContext as l, mainAuthRouter as m, loginService as n, logoutService as o, changePasswordService as p, type RegisterParams as q, registerService as r, type LoginParams as s, type LogoutParams as t, sendVerificationCodeService as u, verifyCodeService as v, type SendVerificationCodeParams as w, type VerifyCodeParams as x, type VerifyCodeResult as y, registerPublicKeyService as z };

package/dist/client-proof.d.ts

@@ -1,9 +1,10 @@
+import { KeyObject } from 'node:crypto';
 import { MiddlewareHandler } from 'hono';
 
 /**
  * SPFN-CANON-JSON-1 — the canonical JSON form the mobile contract pins.
  *
- * The rules (Contracts/spfn-mobile-contract.v1.json `canonicalJson`):
+ * 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
@@ -43,12 +44,32 @@ declare function isCanonicalBytes(bytes: Uint8Array, value: CanonicalValue): boo
 /** 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;
@@ -63,22 +84,42 @@ declare class ProofInputError extends Error {
     constructor();
 }
 /**
- * The canonical proof-input string the MAC is taken over.
+ * 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 base16-lower HMAC-SHA-256 proof for `input` under `key`. */
-declare function computeClientProof(input: ClientProofInput, key: Uint8Array): string;
-/** Lowercase base16 SHA-256 of `bytes`. */
-declare function sha256Hex(bytes: Uint8Array): string;
 /**
- * Constant-time comparison of two proof strings.
+ * 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.
  *
- * Length is checked first (its leak reveals nothing — the expected length is
- * public), then the bytes are compared with `timingSafeEqual`.
+ * @throws when the input is not base64 SPKI DER naming a P-256 key.
  */
-declare function constantTimeEqualsProof(expected: string, presented: string): boolean;
+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';
@@ -115,31 +156,6 @@ declare class ClientProofRefusal {
     static proofInvalid(): ClientProofRefusal;
 }
 
-/**
- * Everything a clientProofV1 server remembers between requests: issued
- * sessions, the replay ledger, revoked keys and the key directory.
- *
- * The admission order is the contract's, not this file's invention
- * (`clientProofV1.revocationRule` + the replay fixtures):
- *
- * 1. revoked keyId / invalid session → SESSION_REVOKED — before proof
- *    verification, so revocation stays distinguishable from a bad proof;
- * 2. issuedAtMillis outside the replay window (0 <= age <= window) → PROOF_EXPIRED;
- * 3. a repeated (clientId, nonce) pair inside the window → PROOF_REPLAYED;
- * 4. only then HMAC verification → PROOF_INVALID on mismatch.
- *
- * A nonce is recorded as spent only on admission: a request refused for any
- * earlier reason has not spent anything, so a client that fixes the reason and
- * retries with the same nonce is not punished twice for one mistake. This is
- * why core's `NonceStore.checkAndSet` (which records on check) is not reused
- * here — its semantics would spend a nonce on a refused request.
- *
- * `admit` is synchronous, so on Node's single thread the whole sequence is
- * atomic: two requests presenting the same nonce cannot interleave inside it.
- *
- * @module server/client-proof/state
- */
-
 /** Millisecond clock. Injectable so expiry paths are testable without waiting. */
 interface ClientProofClock {
     nowMillis(): number;
@@ -164,11 +180,13 @@ interface ClientProofStats {
 }
 interface ClientProofStateOptions {
     /**
-     * keyId → HMAC key. A string is taken as UTF-8 bytes. Dev provisioning is
-     * injection at construction; any issuance flow works as long as
-     * clientId/keyId/key triples exist on both ends.
+     * 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).
      */
-    keys: Record<string, string | Uint8Array>;
+    publicKeys: Record<string, string>;
     clock?: ClientProofClock;
     /** @default 600000 */
     sessionTtlMillis?: number;
@@ -179,9 +197,10 @@ declare const DEFAULT_SESSION_TTL_MILLIS = 600000;
 declare class ClientProofState {
     readonly replayWindowMillis: number;
     private readonly clock;
-    private readonly keys;
+    private readonly initialPublicKeys;
+    private readonly publicKeys;
     private readonly sessions;
-    /** replayKeyOf(...) → the issuedAtMillis it was spent at. */
+    /** The replay ledger — the shared memory implementation, used dev-only here. */
     private readonly spentNonces;
     private readonly revokedKeyIds;
     private readonly holds;
@@ -193,6 +212,12 @@ declare class ClientProofState {
     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).
@@ -217,7 +242,7 @@ declare class ClientProofState {
     /** 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 included. */
+    /** 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;
@@ -295,25 +320,145 @@ declare function admitClientProofRequest(args: {
     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".
  *
- * Source of truth: spfn-mobile Contracts/spfn-mobile-contract.v1.json
- * (dev bundle sha256 07fd8268…a433e45) — `types` and `operations`.
+ * 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';
+    id: 'auth.clientProof.handshake' | 'echo.send' | 'items.list' | 'auth.enroll.register' | 'auth.enroll.login' | 'auth.enroll.oauthNative' | 'auth.keys.rotate';
     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();
@@ -409,4 +554,4 @@ interface ClientProofGuardOptions {
  */
 declare function createClientProofGuard(state: ClientProofState, options?: ClientProofGuardOptions): MiddlewareHandler;
 
-export { ABSENT_BODY_SHA256, type Admission, 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 ClientProofClock, type ClientProofContext, type ClientProofCredentials, type ClientProofDevHandler, type ClientProofDevHandlerOptions, type ClientProofErrorCode, type ClientProofGuardOptions, type ClientProofInput, ClientProofRefusal, 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, ProofInputError, TestClock, admitClientProofRequest, canonicalProofInput, computeClientProof, constantTimeEqualsProof, createClientProofDevHandler, createClientProofGuard, decodeEchoRequest, decodeHandshakeRequest, decodeListItemsRequest, encodeCanonicalJson, encodeEchoResponse, encodeHandshakeResponse, encodeListItemsResponse, isCanonicalBytes, newHexId, parseCanonicalJson, sha256Hex, systemClock };
+export { ABSENT_BODY_SHA256, AUTH_SURFACE_OPERATIONS, type Admission, 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 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, TestClock, admitClientProofRequest, canonicalProofInput, configureClientProofReplayStore, createClientProofDevHandler, createClientProofGuard, decodeEchoRequest, decodeHandshakeRequest, decodeListItemsRequest, encodeCanonicalJson, encodeEchoResponse, encodeHandshakeResponse, encodeListItemsResponse, getClientProofReplayStore, isCanonicalBytes, isRequestContentType, newHexId, parseCanonicalJson, parseClientProofPublicKey, readCredentials, replayLedgerKey, sha256Hex, signClientProof, systemClock, verifyClientProof };