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

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
@@ -917,6 +918,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 +951,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 +1022,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.

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,