@spfn/auth 0.3.0-beta.2 → 0.3.0-beta.21

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' | 'auth.device.start' | 'auth.device.poll' | 'auth.device.info' | 'auth.device.approve' | 'auth.device.deny' | typeof CORE_TIME_OPERATION_ID;
+    method: 'GET' | 'POST';
     path: string;
     /**
      * How a call is admitted. `clientProofV1` operations run the proof
@@ -408,8 +409,13 @@ interface ContractOperation {
      */
     authProfile: 'clientProofV1' | 'none';
     requiresSession: boolean;
-    requestType: string;
-    responseType: string;
+    /** Absent only when the operation has no request body. */
+    requestType?: string;
+    /**
+     * Absent only when the operation answers with no body — a 204, which has
+     * nothing for a consumer to decode and therefore names no type.
+     */
+    responseType?: string;
     summary: string;
     /**
      * The contract version this operation first appeared in. Required, so an
@@ -439,18 +445,42 @@ 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
- * 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.
+ * The `/_auth` surface exported into the mobile contract: enrollment, login,
+ * key rotation and device-code login. 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 `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.
+ *
+ * Device-code login is in both classes at once, because two devices run it. The
+ * device being let in calls `start` and `poll` unproven — it has no registered
+ * key to sign with, and getting one is the point of the flow. The approver calls
+ * `info`, `approve` and `deny` proven, from a device that is already signed in,
+ * which is what lets the server read the approving account from the caller
+ * rather than from the request body.
  */
 declare const AUTH_SURFACE_OPERATIONS: readonly ContractOperation[];
 /** The body is canonical JSON but not the declared request type. */
@@ -603,4 +633,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",
@@ -1047,6 +1078,60 @@ var AUTH_SURFACE_OPERATIONS = [
     responseType: "RevokeAllKeysResponse",
     summary: "Revokes every key the caller has, sparing the calling device unless asked otherwise.",
     since: "0.4.1"
+  },
+  {
+    id: "auth.device.start",
+    method: "POST",
+    path: "/_auth/device/start",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "StartDeviceAuthRequest",
+    responseType: "StartDeviceAuthResponse",
+    summary: "Parks a new device's public key and returns the codes it shows and polls with.",
+    since: "0.10.0"
+  },
+  {
+    id: "auth.device.poll",
+    method: "POST",
+    path: "/_auth/device/poll",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "PollDeviceAuthRequest",
+    responseType: "PollDeviceAuthResponse",
+    summary: "Asks whether the request has been answered; the approved answer is the login it produced.",
+    since: "0.10.0"
+  },
+  {
+    id: "auth.device.info",
+    method: "POST",
+    path: "/_auth/device/info",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    requestType: "DeviceAuthInfoRequest",
+    responseType: "DeviceAuthInfoResponse",
+    summary: "Describes the device waiting on a user code, so the approver can recognise it before deciding.",
+    since: "0.10.0"
+  },
+  {
+    id: "auth.device.approve",
+    method: "POST",
+    path: "/_auth/device/approve",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    requestType: "ApproveDeviceAuthRequest",
+    responseType: "DeviceAuthInfoResponse",
+    summary: "Lets the waiting device in, answering with the device it just let in.",
+    since: "0.10.0"
+  },
+  {
+    id: "auth.device.deny",
+    method: "POST",
+    path: "/_auth/device/deny",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    requestType: "DenyDeviceAuthRequest",
+    summary: "Refuses the waiting device. Answers 204 with no body, so it names no response type.",
+    since: "0.10.0"
   }
 ];
 var ContractTypeError = class extends Error {
@@ -1287,9 +1372,14 @@ 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"];
+var KEY_PLATFORM = ["ios", "android", "web", "desktop"];
 
 // src/server/client-proof/wire-headers.ts
 var CLIENT_IDENTITY_HEADERS = {
@@ -1307,16 +1397,34 @@ function isAppKind(kind) {
 }
 
 // src/server/client-proof/contract-bundle.ts
-var CONTRACT_VERSION = "0.8.0";
+var CONTRACT_VERSION = "0.11.0";
 var CONTRACT_MAJOR = 0;
-var CONTRACT_SUPPORTED_RANGE = ">=0.8.0 <0.9.0";
+var CONTRACT_SUPPORTED_RANGE = ">=0.11.0 <0.12.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: [
@@ -1462,7 +1570,7 @@ var CONTRACT_TYPES = [
     fields: [
       required("keyId", "string"),
       optional("deviceName", "string"),
-      optional("platform", "string"),
+      optional("platform", "KeyPlatform"),
       required("algorithm", "KeyAlgorithm"),
       required("fingerprintPrefix", "string"),
       required("createdAtMillis", "integer"),
@@ -1470,7 +1578,9 @@ var CONTRACT_TYPES = [
       optional("expiresAtMillis", "integer"),
       required("isExpired", "boolean"),
       required("isActive", "boolean"),
-      optional("revokedAtMillis", "integer")
+      optional("revokedAtMillis", "integer"),
+      optional("registeredIp", "string"),
+      optional("registeredUserAgent", "string")
     ]
   },
   {
@@ -1504,10 +1614,94 @@ var CONTRACT_TYPES = [
       required("revokedCount", "integer"),
       required("currentKeyRevoked", "boolean")
     ]
+  },
+  {
+    name: "StartDeviceAuthRequest",
+    fields: [
+      required("publicKey", "string"),
+      required("keyId", "string"),
+      required("fingerprint", "string"),
+      optional("algorithm", "KeyAlgorithm"),
+      optional("deviceName", "string"),
+      optional("platform", "KeyPlatform")
+    ]
+  },
+  {
+    name: "StartDeviceAuthResponse",
+    fields: [
+      required("deviceCode", "string"),
+      required("userCode", "string"),
+      required("expiresAtMillis", "integer"),
+      required("intervalMillis", "integer")
+    ]
+  },
+  {
+    name: "PollDeviceAuthRequest",
+    fields: [
+      required("deviceCode", "string")
+    ]
+  },
+  /**
+   * The poll union, flattened into the one shape this grammar can carry.
+   *
+   * `status` is the discriminant and the only required field; everything else
+   * belongs to one branch and is therefore optional. `intervalMillis` is the
+   * pending branch, and the five after it are the approved branch — the same
+   * fields `LoginResponse` carries, because an approved poll is the login the
+   * approval produced. `deviceAuthorization.pollStatusRule` states the pairing
+   * the grammar cannot.
+   */
+  {
+    name: "PollDeviceAuthResponse",
+    fields: [
+      required("status", "DeviceAuthPollStatus"),
+      optional("intervalMillis", "integer"),
+      optional("userId", "string"),
+      optional("publicId", "string"),
+      optional("email", "string"),
+      optional("phone", "string"),
+      optional("passwordChangeRequired", "boolean")
+    ]
+  },
+  /**
+   * Info, approve and deny each declare their own request type although all
+   * three carry nothing but `userCode`. An operation's request shape is its
+   * own: a field added to one of them later must not appear on the other two
+   * by accident, which is what a shared type would do.
+   */
+  {
+    name: "DeviceAuthInfoRequest",
+    fields: [
+      required("userCode", "string")
+    ]
+  },
+  {
+    name: "DeviceAuthInfoResponse",
+    fields: [
+      optional("deviceName", "string"),
+      optional("platform", "KeyPlatform"),
+      required("fingerprintPrefix", "string"),
+      required("requestedAtMillis", "integer"),
+      required("expiresAtMillis", "integer")
+    ]
+  },
+  {
+    name: "ApproveDeviceAuthRequest",
+    fields: [
+      required("userCode", "string")
+    ]
+  },
+  {
+    name: "DenyDeviceAuthRequest",
+    fields: [
+      required("userCode", "string")
+    ]
   }
 ];
 var CONTRACT_ENUMS = [
-  { name: "KeyAlgorithm", values: [...KEY_ALGORITHM] }
+  { name: "KeyAlgorithm", values: [...KEY_ALGORITHM] },
+  { name: "KeyPlatform", values: [...KEY_PLATFORM] },
+  { name: "DeviceAuthPollStatus", values: ["pending", "approved"] }
 ];
 var BUNDLE_FILENAME = "spfn-mobile-contract.json";
 var BUNDLE_REPO_PATH = `contracts/mobile/${BUNDLE_FILENAME}`;
@@ -1790,6 +1984,7 @@ export {
   CONTRACT_OPERATIONS,
   CONTROL_PREFIX,
   CONTROL_TOKEN_HEADER,
+  CORE_PREREQUISITE_OPERATIONS,
   CanonicalJsonError,
   ClientProofRefusal,
   ClientProofState,
@@ -1798,6 +1993,7 @@ export {
   DEFAULT_SESSION_TTL_MILLIS,
   DEV_CATALOGUE,
   DEV_MAX_LIMIT,
+  IMPORTED_CORE_TIME_CONTRACT,
   MemoryReplayLedger,
   MemoryReplayStore,
   PROOF_SIGNATURE_BYTES,