@spfn/auth 0.3.0-beta.3 → 0.3.0-beta.5

package/README.md

@@ -236,12 +236,13 @@ await authApi.revokeAllKeys.call({ body: {} });               // other devices o
 await authApi.revokeAllKeys.call({ body: { includeCurrent: true } });   // everything
 ```
 
-> **All three are POST with their arguments in the body, deliberately.** The mobile auth
+> **All three key-management operations are POST with their arguments in the body, deliberately.** The mobile auth
 > profile (clientProofV1) signs the request body, and `canonical-json` fixes exactly how those
 > bytes are written. A `GET` has no body to sign, and a value in the path has no such rule —
 > client and server could disagree on the signed string over percent-encoding, a trailing
 > slash, or a proxy rewrite alone, and the request would be refused with nothing in the logs
-> naming the cause. Every operation in the contract is shaped this way.
+> naming the cause. Proof-bearing auth operations are shaped this way; the unproven,
+> bodyless `core.time` synchronization prerequisite is the explicit exception.
 
 - **The public key never leaves the server**, and the fingerprint is truncated to 8 characters.
   The list exists to recognise a device and point at it; the full fingerprint is what a native
@@ -826,6 +827,8 @@ Notes:
   seeding in `initializeAuth()`.
 - OAuth signups have no client-typed fields unless you pass `metadata` at OAuth start — decide
   per channel (reject, or allow and collect during onboarding).
+- `email` arrives trimmed and lower-cased, the same form the account is stored under, so a
+  denylist or domain allowlist keyed on the address is not walked past by capitalizing it.
 - On the `oauth` channel `email` is the provider-reported address and may be **unverified**
   (the created account then stores `email` as `null`). The context carries
   `emailVerified` — an email-based allow/block policy must check it before trusting `email`.
@@ -917,6 +920,12 @@ the fixed-string contract error envelope (`PROOF_INVALID` · `PROOF_REPLAYED` ·
 `SESSION_REVOKED` · `PROFILE_REJECTED` · `CONTRACT_UNSUPPORTED` — SDKs classify by code, never
 HTTP status).
 
+Before minting the first proof in each client process, the client calls the built-in
+`GET /_core/time` operation (`core.time`) and establishes its proof epoch from
+`serverTimeMillis`. This prerequisite is unproven and session-free. If the operation is
+unavailable or its response cannot be decoded, proof minting fails closed — there is no silent
+fallback to the device's unsynchronized wall clock.
+
 - 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
@@ -944,6 +953,29 @@ HTTP status).
   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.
 
+### Clock synchronization and proof-time boundaries (contract 0.9.0)
+
+`core.time` is imported from `@spfn/core` rather than restated by auth: operation ID, method,
+path, auth class, session requirement, and the closed `ServerTimeResponse` schema all come from
+the core route contract. The mobile contract records it as a bodyless GET prerequisite and
+requires one synchronization before the first proof minted in each process. It does not prescribe
+persistent offset storage, retry sleeps, or device-specific margins.
+
+The server admission rule remains strict: `age = serverNow - issuedAtMillis` must satisfy
+`0 <= age <= 300000`. Synchronization does not widen the replay window or change nonce retention.
+A refused request still leaves its nonce unused; only admission spends it.
+
+| `serverNow - issuedAtMillis` | Result |
+|---:|---|
+| `0` | accept |
+| `-1` (proof is 1 ms in the future) | `PROOF_EXPIRED` |
+| `300000` | accept |
+| `300001` | `PROOF_EXPIRED` |
+
+When `core.time` cannot be read, the client must surface that synchronization failure and stop
+before sending a proof. Using `Date.now()` or a platform wall clock as an implicit fallback would
+reintroduce the skew failure this prerequisite closes.
+
 ### The contract version on the wire (contract 0.6.0)
 
 A client compiled and shipped separately from the server cannot be fixed by redeploying. Until
@@ -992,6 +1024,7 @@ Every operation in the exported bundle carries `since` — the contract version
 | `auth.clientProof.handshake`, `echo.send`, `items.list` | 0.1.0 |
 | `auth.enroll.register`, `auth.enroll.login`, `auth.enroll.oauthNative`, `auth.keys.rotate` | 0.3.0 |
 | `auth.keys.list`, `auth.keys.revoke`, `auth.keys.revokeAll` | 0.4.1 |
+| `core.time` | 0.9.0 |
 
 - **This is history, not policy.** The mobile contract's compatibility policy is `allOrNothing`: one
   contract version passes or refuses the whole surface, so these three fields change no verdict here.
@@ -1208,6 +1241,23 @@ authorization.
 The environment, seeded on startup by `createAuthLifecycle()`. Seeded accounts are email
 verified, active, and required to change their password on first login.
 
+**Is `Foo@Example.com` the same account as `foo@example.com`?**
+Yes. Addresses are trimmed and lower-cased on the way in and on the way out, so one person
+who capitalizes differently on different days reaches one account instead of creating a
+second. Nothing else is folded — Gmail's dot and `+` rules are that provider's delivery
+behaviour, not an internet rule, and applying them would merge addresses other providers
+treat as different people.
+
+`createAuthLifecycle()` brings existing rows into the same form on startup. If two accounts
+differ only by capitalization, both are left exactly as they are and their user ids are
+logged as an error: which one is the real account, and what becomes of the other's data, is
+not a question the package can answer for you. Until you resolve it, the mixed-case one
+cannot sign in.
+
+Admin seeding is unaffected either way. It recognizes a configured admin in whatever form
+the address was stored, so an account the backfill has not reached is skipped rather than
+duplicated into a second privileged row holding the configured password.
+
 ## Pitfalls & anti-patterns
 
 - **"relation \"auth.users\" does not exist" — tables come from bundled migrations, not push.**

package/dist/client-proof.d.ts

@@ -1,6 +1,7 @@
 import { KeyObject } from 'node:crypto';
 import { C as ClientProofRefusal } from './wire-version-CtzMKvBB.js';
 export { a as CLIENT_IDENTITY_HEADERS, b as CLIENT_KINDS, c as ClientIdentity, d as ClientKind, e as ClientProofErrorCode, S as SERVER_CONTRACT_HEADERS, f as applyServerContractHeaders, i as isAppKind, g as isContractVersionSupported, j as judgeClientIdentity, n as newHexId, r as readClientIdentity, s as serverContractHeaders } from './wire-version-CtzMKvBB.js';
+import { CORE_TIME_OPERATION_ID } from '@spfn/core/server';
 import { MiddlewareHandler, Context } from 'hono';
 
 /**
@@ -397,8 +398,8 @@ declare function getClientProofReplayStore(): ClientProofReplayStore;
  */
 
 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';
+    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' | typeof CORE_TIME_OPERATION_ID;
+    method: 'GET' | 'POST';
     path: string;
     /**
      * How a call is admitted. `clientProofV1` operations run the proof
@@ -408,7 +409,8 @@ interface ContractOperation {
      */
     authProfile: 'clientProofV1' | 'none';
     requiresSession: boolean;
-    requestType: string;
+    /** Absent only when the operation has no request body. */
+    requestType?: string;
     responseType: string;
     summary: string;
     /**
@@ -439,6 +441,23 @@ interface ContractOperation {
      */
     removedIn?: string;
 }
+/** Validated projection of the imported core route contract. */
+declare const IMPORTED_CORE_TIME_CONTRACT: {
+    readonly id: "core.time";
+    readonly method: "GET";
+    readonly path: string;
+    readonly authProfile: "none";
+    readonly requiresSession: false;
+    readonly sourceSince: string;
+};
+/**
+ * The core capability clientProofV1 needs before the client can mint a proof.
+ *
+ * Transport and admission fields come from core's exported route contract so
+ * auth cannot silently restate a different path or policy. `since` is the
+ * mobile-contract history, not core's package-contract history.
+ */
+declare const CORE_PREREQUISITE_OPERATIONS: readonly ContractOperation[];
 declare const CONTRACT_OPERATIONS: readonly ContractOperation[];
 /**
  * The `/_auth` surface exported into the mobile contract: enrollment, login
@@ -603,4 +622,4 @@ declare const CLIENT_IDENTITY_CONTEXT_KEY = "clientIdentity";
  */
 declare function createClientVersionMiddleware(): MiddlewareHandler;
 
-export { ABSENT_BODY_SHA256, AUTH_SURFACE_OPERATIONS, type Admission, CLIENT_IDENTITY_CONTEXT_KEY, 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 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, clientProofRefusalResponse, configureClientProofReplayStore, createClientProofDevHandler, createClientProofGuard, createClientVersionMiddleware, decodeEchoRequest, decodeHandshakeRequest, decodeListItemsRequest, encodeCanonicalJson, encodeEchoResponse, encodeHandshakeResponse, encodeListItemsResponse, getClientProofReplayStore, isCanonicalBytes, isRequestContentType, parseCanonicalJson, parseClientProofPublicKey, readCredentials, replayLedgerKey, sha256Hex, signClientProof, systemClock, verifyClientProof };
+export { ABSENT_BODY_SHA256, AUTH_SURFACE_OPERATIONS, type Admission, CLIENT_IDENTITY_CONTEXT_KEY, CLIENT_PROOF_CONTENT_TYPE, CLIENT_PROOF_HEADERS, CLIENT_PROOF_PROFILE, CONTRACT_OPERATIONS, CONTROL_PREFIX, CONTROL_TOKEN_HEADER, CORE_PREREQUISITE_OPERATIONS, CanonicalJsonError, type CanonicalJsonErrorCode, type CanonicalObject, type CanonicalValue, type ClientProofClock, type ClientProofContext, type ClientProofCredentials, type ClientProofDevHandler, type ClientProofDevHandlerOptions, 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, IMPORTED_CORE_TIME_CONTRACT, type ListItemsRequest, MemoryReplayLedger, MemoryReplayStore, PROOF_SIGNATURE_BYTES, PROOF_SIGNATURE_HEX_LENGTH, ProofInputError, RedisReplayStore, TestClock, admitClientProofRequest, canonicalProofInput, clientProofRefusalResponse, configureClientProofReplayStore, createClientProofDevHandler, createClientProofGuard, createClientVersionMiddleware, decodeEchoRequest, decodeHandshakeRequest, decodeListItemsRequest, encodeCanonicalJson, encodeEchoResponse, encodeHandshakeResponse, encodeListItemsResponse, getClientProofReplayStore, isCanonicalBytes, isRequestContentType, parseCanonicalJson, parseClientProofPublicKey, readCredentials, replayLedgerKey, sha256Hex, signClientProof, systemClock, verifyClientProof };

package/dist/client-proof.js

@@ -935,6 +935,37 @@ function isRequestContentType(value) {
 }
 
 // src/server/client-proof/contract-types.ts
+import {
+  CORE_TIME_OPERATION_ID,
+  CORE_TIME_ROUTE
+} from "@spfn/core/server";
+function importCoreTimeContract() {
+  const { method, path, contract } = CORE_TIME_ROUTE;
+  if (method !== "GET" || typeof path !== "string" || contract?.auth !== "none" || contract.requiresSession !== false || typeof contract.since !== "string") {
+    throw new Error("core.time does not match the clientProofV1 synchronization prerequisite");
+  }
+  return {
+    id: CORE_TIME_OPERATION_ID,
+    method,
+    path,
+    authProfile: contract.auth,
+    requiresSession: contract.requiresSession,
+    sourceSince: contract.since
+  };
+}
+var IMPORTED_CORE_TIME_CONTRACT = importCoreTimeContract();
+var CORE_PREREQUISITE_OPERATIONS = [
+  {
+    id: IMPORTED_CORE_TIME_CONTRACT.id,
+    method: IMPORTED_CORE_TIME_CONTRACT.method,
+    path: IMPORTED_CORE_TIME_CONTRACT.path,
+    authProfile: IMPORTED_CORE_TIME_CONTRACT.authProfile,
+    requiresSession: IMPORTED_CORE_TIME_CONTRACT.requiresSession,
+    responseType: "ServerTimeResponse",
+    summary: "Returns the server epoch used to timestamp clientProofV1 proofs.",
+    since: "0.9.0"
+  }
+];
 var CONTRACT_OPERATIONS = [
   {
     id: "auth.clientProof.handshake",
@@ -1287,6 +1318,10 @@ function answer(status, value) {
 
 // src/server/client-proof/contract-bundle.ts
 import { createHash as createHash2 } from "crypto";
+import {
+  CORE_TIME_OPERATION_ID as CORE_TIME_OPERATION_ID2,
+  ServerTimeResponseSchema
+} from "@spfn/core/server";
 
 // src/server/types.ts
 var KEY_ALGORITHM = ["ES256", "RS256"];
@@ -1307,16 +1342,34 @@ function isAppKind(kind) {
 }
 
 // src/server/client-proof/contract-bundle.ts
-var CONTRACT_VERSION = "0.8.0";
+var CONTRACT_VERSION = "0.9.0";
 var CONTRACT_MAJOR = 0;
-var CONTRACT_SUPPORTED_RANGE = ">=0.8.0 <0.9.0";
+var CONTRACT_SUPPORTED_RANGE = ">=0.9.0 <0.10.0";
 function required(name, type) {
   return { name, type, optional: false };
 }
 function optional(name, type) {
   return { name, type, optional: true };
 }
+function coreTimeResponseDeclaration() {
+  if (ServerTimeResponseSchema.type !== "object" || ServerTimeResponseSchema.additionalProperties !== false) {
+    throw new Error("core.time response must remain a closed object");
+  }
+  const requiredFields = new Set(ServerTimeResponseSchema.required);
+  const fields = Object.entries(ServerTimeResponseSchema.properties).map(([name, schema]) => {
+    if (schema.type !== "integer") {
+      throw new Error(`core.time response field ${name} is outside the mobile type grammar`);
+    }
+    return {
+      name,
+      type: "integer",
+      optional: !requiredFields.has(name)
+    };
+  });
+  return { name: "ServerTimeResponse", fields };
+}
 var CONTRACT_TYPES = [
+  coreTimeResponseDeclaration(),
   {
     name: "HandshakeRequest",
     fields: [
@@ -1790,6 +1843,7 @@ export {
   CONTRACT_OPERATIONS,
   CONTROL_PREFIX,
   CONTROL_TOKEN_HEADER,
+  CORE_PREREQUISITE_OPERATIONS,
   CanonicalJsonError,
   ClientProofRefusal,
   ClientProofState,
@@ -1798,6 +1852,7 @@ export {
   DEFAULT_SESSION_TTL_MILLIS,
   DEV_CATALOGUE,
   DEV_MAX_LIMIT,
+  IMPORTED_CORE_TIME_CONTRACT,
   MemoryReplayLedger,
   MemoryReplayStore,
   PROOF_SIGNATURE_BYTES,