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

package/README.md

@@ -13,8 +13,8 @@ pnpm add @spfn/auth drizzle-orm@1.0.0-rc.4
 
 ## Import paths
 
-Five entry points (from `package.json` `exports`). Picking the wrong one breaks the build —
-`/server` and `/nextjs/*` pull in Node/`server-only` code and must never reach the browser bundle.
+Entry points (from `package.json` `exports`). Picking the wrong one breaks the build —
+`/server`, `/client-proof` and `/nextjs/*` pull in Node code and must never reach the browser bundle.
 
 ```typescript
 import { authApi, authRouteMap }      from '@spfn/auth';          // isomorphic: client + route map + types/constants
@@ -25,6 +25,7 @@ import { InvalidCredentialsError }    from '@spfn/auth/errors';    // error clas
 import '@spfn/auth/nextjs/api';                                    // SERVER: auto-registers RPC interceptors (side-effect)
 import { RequireAuth, getSession }    from '@spfn/auth/nextjs/server'; // SERVER: RSC guards, session helpers, OAuth handler
 import { OAuthCallback }              from '@spfn/auth/nextjs/client';  // 'use client' OAuth callback component
+import { createClientProofDevHandler } from '@spfn/auth/client-proof';  // SERVER: mobile clientProofV1 profile (see below)
 ```
 
 > Database entities (`users`, `userPublicKeys`, …) and all services/repositories are exported
@@ -268,10 +269,13 @@ no Google account is linked or no refresh token is available).
 Kakao's `is_email_valid` and `is_email_verified` claims are both required before its email can
 link an existing SPFN account. GitHub uses the primary email from `/user/emails` (needs the
 `user:email` scope) and treats it as verified only when GitHub marks it verified; without that
-scope it falls back to the public profile email, unverified. Naver provides an email address but no verified-email claim, so
-Naver login never links an existing account by email; new Naver users can verify and add their
-email through the application's normal onboarding flow. Until then, the OAuth account is identified
-by its provider and provider user ID, so its user row may have both email and phone unset.
+scope it falls back to the public profile email, unverified. Naver's profile email is either the
+Naver account email or a contact email that passed Naver's own verification, so a present email
+is treated as verified — it is stored on the user row and may link an existing account by email,
+the same trust level as Kakao. Accounts created before this policy (user row with `email` null)
+are backfilled on their next login: if the provider reports a verified email and no other account
+owns it, `email` and `emailVerifiedAt` are filled in (best-effort; a conflict skips the backfill
+and the login continues).
 
 ### Provider-initiated unlink notifications (`unlink-notify`)
 
@@ -546,6 +550,36 @@ For short-lived authenticated handshakes (e.g. SSE) where a `Bearer` header is a
 with `authApi.issueOneTimeToken`, protect the consuming route with the `oneTimeTokenAuth`
 middleware. Call `initOneTimeTokenManager({ ttl, store })` during setup for a custom TTL/store.
 
+## 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
+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).
+
+- Wire headers (D23, ratified): `x-spfn-auth-profile`, `x-spfn-client-id`, `x-spfn-key-id`,
+  `x-spfn-nonce`, `x-spfn-issued-at`, `x-spfn-proof`, `x-spfn-session`.
+- A request body must be **byte-canonical** — a body that parses but re-encodes differently is
+  refused even when its proof verifies (the proof binds the received bytes).
+- `createClientProofDevHandler(...)` — framework-free `fetch(Request) → Response` dev surface
+  with the three contract operations and the `/control` test hooks the spfn-mobile integration
+  suites drive (`examples/04-mobile-contract-dev` is the runnable wiring).
+- `createClientProofGuard(state)` — Hono middleware for mounting `requiresSession` operations
+  on an SPFN server; tags admitted requests `clientType: 'mobile'` (the attestation slot
+  proxy-guard reserved). hono is a type-only import here.
+- Replay ledger is module-local, NOT core's `NonceStore` — `checkAndSet` records on check,
+  which would spend a nonce on a refused request; the contract requires spending only on
+  admission.
+- 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.
+
 ## Account Deletion & Recovery
 
 Grace-period deletion with in-window recovery, an admin/GDPR-response entry point for immediate

package/dist/client-proof.d.ts

@@ -0,0 +1,412 @@
+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`):
+ * - 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;
+
+/** 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;
+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 MAC 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.
+ *
+ * Length is checked first (its leak reveals nothing — the expected length is
+ * public), then the bytes are compared with `timingSafeEqual`.
+ */
+declare function constantTimeEqualsProof(expected: string, presented: string): boolean;
+
+/** 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;
+    static profileRejected(): ClientProofRefusal;
+    static sessionRevoked(): ClientProofRefusal;
+    static proofExpired(): ClientProofRefusal;
+    static proofReplayed(): 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;
+}
+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 → 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.
+     */
+    keys: Record<string, string | Uint8Array>;
+    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 keys;
+    private readonly sessions;
+    /** replayKeyOf(...) → the issuedAtMillis it was spent at. */
+    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);
+    /**
+     * 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 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 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`.
+ *
+ * @module server/client-proof/contract-types
+ */
+
+interface ContractOperation {
+    id: 'auth.clientProof.handshake' | 'echo.send' | 'items.list';
+    method: 'POST';
+    path: string;
+    requiresSession: boolean;
+}
+declare const CONTRACT_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;
+
+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 };