@spfn/auth 0.2.0-beta.86 → 0.2.0-beta.88

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,6 +320,101 @@ 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
@@ -302,7 +422,7 @@ declare function admitClientProofRequest(args: {
  * 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.v1.json`) is generated from it
+ * 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.
  *
@@ -310,16 +430,35 @@ declare function admitClientProofRequest(args: {
  */
 
 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' | 'auth.keys.list' | 'auth.keys.revoke' | 'auth.keys.revokeAll';
     method: 'POST';
     path: string;
-    authProfile: 'clientProofV1';
+    /**
+     * 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();
@@ -415,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 };