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

package/README.md

@@ -213,11 +213,24 @@ cut off anything they no longer recognise.
 
 ```typescript
 const { keys } = await authApi.listKeys.call({ body: {} });
-// → [{ keyId, deviceName?, platform?, algorithm, fingerprintPrefix, createdAt,
-//      lastUsedAt?, expiresAt?, isExpired, isActive, revokedAt? }]
+// → [{ keyId, deviceName?, platform?, algorithm, fingerprintPrefix, createdAtMillis,
+//      lastUsedAtMillis?, expiresAtMillis?, isExpired, isActive, revokedAtMillis? }]
 
 await authApi.listKeys.call({ body: { includeRevoked: true } });   // also what was cut off
+```
+
+Every moment is epoch milliseconds, not an ISO string — one representation across the whole
+surface, so a generated Swift or Kotlin client reads an integer instead of choosing a date
+formatter. This changed in mobile contract 0.5.0; an app still reading `createdAt` moves to
+`createdAtMillis`.
 
+`algorithm` is the `KeyAlgorithm` enum from contract 0.6.0 rather than a bare string — the routes
+have always constrained it to those values, and the contract had been understating the server. The
+declared values are the ones the server accepts and sends **now**: one can be added, and one can be
+withdrawn for a weakness found later, so a generated client should be built to meet a value it does
+not recognise rather than assume the set is closed.
+
+```typescript
 await authApi.revokeKey.call({ body: { keyId } });            // → { keyId, selfRevoked }
 await authApi.revokeAllKeys.call({ body: {} });               // other devices only
 await authApi.revokeAllKeys.call({ body: { includeCurrent: true } });   // everything
@@ -853,6 +866,44 @@ 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.
 
+### 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
+0.6.0 a mismatch between what that client was generated against and what the server serves
+surfaced as an undecodable body: the app looked broken and nothing said why.
+
+Both ends now say what they are.
+
+| Header | Direction | Sent by |
+|--------|-----------|---------|
+| `x-spfn-client-kind` | request | every client — `web`, `ios` or `android` |
+| `x-spfn-client-version` | request | the client's own release: a store version, or a bundle build |
+| `x-spfn-client-contract-version` | request | `ios` and `android` only |
+| `x-spfn-server-contract-version` | response | the server, on every response including a refusal |
+| `x-spfn-supported-contract-range` | response | the server, likewise |
+
+```typescript
+import { createClientVersionMiddleware } from '@spfn/auth/client-proof';
+
+// Mount before authentication: enrollment and login carry no proof, and they are
+// where a stale client arrives first.
+app.use('*', createClientVersionMiddleware());
+```
+
+- **`web` states no contract version**, because a browser bundle is deployed with the server that
+  serves it and has no second version to reconcile. It is exempt by construction, not by leniency.
+- **An `ios` or `android` client that states no contract version, or one outside the range, is
+  refused** `CONTRACT_UNSUPPORTED` (409) with the usual envelope.
+- **A request naming no kind passes** — a curl, a health probe, a server-to-server call is not a
+  deployed client this rule is about.
+- **None of it enters the proof input.** These are diagnostic; `PROOF_INPUT_FIELDS` is unchanged.
+- **The server states facts and stops there.** Comparing the announced range against its own version
+  and deciding a user should see an update prompt is the client's judgment, made in the client. The
+  server has no way to make an app update and does not pretend to.
+
+Response header names are deliberately distinct from the request ones: a proxy that echoes a request
+header into the response would otherwise make the client's own version look like the server's.
+
 ### Usage — dev surface (mobile integration target)
 
 The fastest path: run the packaged dev handler, which already serves the three contract

package/dist/{authenticate-ZssfqJ7d.d.ts → authenticate-DK-hLSOW.d.ts}

@@ -270,15 +270,23 @@ interface KeySummary {
     algorithm: KeyAlgorithmType;
     /** First bytes of the fingerprint — enough to tell two entries apart. */
     fingerprintPrefix: string;
-    createdAt: string;
-    lastUsedAt?: string;
-    expiresAt?: string;
+    /**
+     * Milliseconds since the Unix epoch, not an ISO string.
+     *
+     * One representation of a moment across the whole surface: a generated Swift
+     * or Kotlin client reads an integer with no date formatter, and
+     * `ISO8601DateFormatter` rejecting fractional seconds by default stops being
+     * a way for the two SDKs to disagree about the same value.
+     */
+    createdAtMillis: number;
+    lastUsedAtMillis?: number;
+    expiresAtMillis?: number;
     /** The TTL has run out. The key still reads as active; authenticate refuses it. */
     isExpired: boolean;
     /** False once revoked. Only ever false when the caller asked for revoked keys. */
     isActive: boolean;
     /** When it was revoked, for the "what did I cut off, and when" reading. */
-    revokedAt?: string;
+    revokedAtMillis?: number;
 }
 interface ListKeysParams {
     userId: number;
@@ -871,7 +879,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
             id: number;
             name: string;
             displayName: string;
-            category: "custom" | "user" | "auth" | "rbac" | "system" | undefined;
+            category: "auth" | "custom" | "user" | "rbac" | "system" | undefined;
         }[];
         userId: number;
         publicId: string;
@@ -1171,8 +1179,8 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }, {}, {
         roles: {
             description: string | null;
-            id: number;
             name: string;
+            id: number;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;
@@ -1193,8 +1201,8 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }, {}, {
         role: {
             description: string | null;
-            id: number;
             name: string;
+            id: number;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;
@@ -1217,8 +1225,8 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }, {}, {
         role: {
             description: string | null;
-            id: number;
             name: string;
+            id: number;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;

package/dist/client-proof.d.ts

@@ -149,6 +149,14 @@ declare class ClientProofRefusal {
     static bodyNotTheDeclaredType(): ClientProofRefusal;
     static sessionHeaderMisplaced(): ClientProofRefusal;
     static unprocessable(): ClientProofRefusal;
+    /**
+     * A client that ships separately from the server said nothing about which
+     * contract it was built against. Without it the server cannot tell whether
+     * the two ends agree, and answering as though they do is what produces the
+     * undecodable body this check exists to replace.
+     */
+    static contractVersionMissing(): ClientProofRefusal;
+    static contractVersionUnsupported(): ClientProofRefusal;
     static profileRejected(): ClientProofRefusal;
     static sessionRevoked(): ClientProofRefusal;
     static proofExpired(): ClientProofRefusal;
@@ -554,4 +562,116 @@ interface ClientProofGuardOptions {
  */
 declare function createClientProofGuard(state: ClientProofState, options?: ClientProofGuardOptions): MiddlewareHandler;
 
-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 };
+/**
+ * The header names each end announces itself under.
+ *
+ * Separated from the logic that reads them so the contract bundle can name them
+ * without importing the version comparison, which reads the bundle back. These
+ * are declarations and depend on nothing.
+ *
+ * @module server/client-proof/wire-headers
+ */
+/** What a client says about itself, one header each. */
+declare const CLIENT_IDENTITY_HEADERS: {
+    readonly kind: "x-spfn-client-kind";
+    readonly version: "x-spfn-client-version";
+    readonly contractVersion: "x-spfn-client-contract-version";
+};
+/**
+ * What the server says about itself, on every response.
+ *
+ * Distinct names from the request headers on purpose: a proxy that echoes a
+ * request header into the response would otherwise make the client's own
+ * version look like the server's.
+ */
+declare const SERVER_CONTRACT_HEADERS: {
+    readonly version: "x-spfn-server-contract-version";
+    readonly supportedRange: "x-spfn-supported-contract-range";
+};
+/**
+ * The client kinds the server distinguishes.
+ *
+ * `web` is separated from the two app kinds because it carries no contract
+ * version: a browser bundle is deployed with the server that serves it, so
+ * there is no second version to reconcile.
+ */
+declare const CLIENT_KINDS: readonly ["web", "ios", "android"];
+type ClientKind = typeof CLIENT_KINDS[number];
+/** A kind that ships independently of the server, so its contract version matters. */
+declare function isAppKind(kind: ClientKind): boolean;
+
+/** What one request announced about the client that sent it. */
+interface ClientIdentity {
+    kind: ClientKind;
+    /** The client's own release — a store version, or a bundle build. */
+    version: string | null;
+    /** The contract version the client was generated from. Never set for `web`. */
+    contractVersion: string | null;
+}
+/**
+ * Reads the identity headers, or null when the kind is absent or unrecognised.
+ *
+ * Null is not by itself a refusal — a request from something that predates
+ * these headers reaches here too. `judgeClientIdentity` decides.
+ */
+declare function readClientIdentity(headers: Headers): ClientIdentity | null;
+/**
+ * Whether the server serves what the client was generated against.
+ *
+ * Under 0.x the minor carries breaking changes, so a supported client agrees on
+ * major and minor. From 1.0.0 the major alone decides. This is the rule
+ * `CONTRACT_SUPPORTED_RANGE` spells out; keeping it as a comparison rather than
+ * parsing that string leaves one place to change when the line reaches 1.0.0.
+ */
+declare function isContractVersionSupported(clientVersion: string): boolean;
+/**
+ * The refusal a request's announced identity earns, or null to let it through.
+ *
+ * An app kind must state a contract version this server serves. A version it
+ * does not serve, and the absence of one, are the same answer: the two ends do
+ * not agree on what the contract is, which is what CONTRACT_UNSUPPORTED means.
+ * The response carries the server's version and range, so the client can say
+ * which way the gap runs.
+ *
+ * `web` is exempt from the contract check by construction, not by leniency.
+ *
+ * A request with no recognised kind passes. The check is on what a client says
+ * about itself, and a caller that says nothing — a curl, a health probe, a
+ * server-to-server call — is not a deployed client this rule is about.
+ */
+declare function judgeClientIdentity(identity: ClientIdentity | null): ClientProofRefusal | null;
+/** Writes the server's own announcement onto a response's headers. */
+declare function applyServerContractHeaders(headers: Headers): void;
+/** The same announcement as a plain object, for a response built from one. */
+declare function serverContractHeaders(): Record<string, string>;
+
+/**
+ * The version announcement, applied to every request rather than to the proven
+ * ones.
+ *
+ * Enrollment and login are the first calls a client makes and they carry no
+ * proof — there is no key to sign with yet. A check that lives inside proof
+ * admission therefore never sees the client it is meant to catch: an outdated
+ * app fails at login, before it reaches anything proven. This runs ahead of all
+ * of it.
+ *
+ * hono is imported as types only, so this module adds no runtime dependency.
+ *
+ * @module server/client-proof/version-middleware
+ */
+
+/** The context key the identity is left under, for a handler that wants it. */
+declare const CLIENT_IDENTITY_CONTEXT_KEY = "clientIdentity";
+/**
+ * Announces the server's contract version on every response and refuses a
+ * client whose own contract version this server does not serve.
+ *
+ * The announcement goes out either way. A refused client needs it most — the
+ * refusal says the two ends disagree, and the range is what says how.
+ *
+ * Mount this before authentication, not after: the point is to answer a stale
+ * client before anything else has a chance to fail confusingly.
+ */
+declare function createClientVersionMiddleware(): MiddlewareHandler;
+
+export { ABSENT_BODY_SHA256, AUTH_SURFACE_OPERATIONS, type Admission, CLIENT_IDENTITY_CONTEXT_KEY, CLIENT_IDENTITY_HEADERS, CLIENT_KINDS, 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 ClientIdentity, type ClientKind, 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, SERVER_CONTRACT_HEADERS, TestClock, admitClientProofRequest, applyServerContractHeaders, canonicalProofInput, configureClientProofReplayStore, createClientProofDevHandler, createClientProofGuard, createClientVersionMiddleware, decodeEchoRequest, decodeHandshakeRequest, decodeListItemsRequest, encodeCanonicalJson, encodeEchoResponse, encodeHandshakeResponse, encodeListItemsResponse, getClientProofReplayStore, isAppKind, isCanonicalBytes, isContractVersionSupported, isRequestContentType, judgeClientIdentity, newHexId, parseCanonicalJson, parseClientProofPublicKey, readClientIdentity, readCredentials, replayLedgerKey, serverContractHeaders, sha256Hex, signClientProof, systemClock, verifyClientProof };

package/dist/client-proof.js

@@ -496,6 +496,18 @@ var ClientProofRefusal = class _ClientProofRefusal {
   static unprocessable() {
     return contractViolation("the request could not be processed");
   }
+  /**
+   * A client that ships separately from the server said nothing about which
+   * contract it was built against. Without it the server cannot tell whether
+   * the two ends agree, and answering as though they do is what produces the
+   * undecodable body this check exists to replace.
+   */
+  static contractVersionMissing() {
+    return contractViolation("a client of this kind must state the contract version it was generated from");
+  }
+  static contractVersionUnsupported() {
+    return contractViolation("the stated contract version is outside the range this server serves");
+  }
   // ---- the profile allowlist ----------------------------------------------
   static profileRejected() {
     return new _ClientProofRefusal("PROFILE_REJECTED", "the named auth profile is not on this contract's allowlist");
@@ -1045,17 +1057,17 @@ function decodeListItemsRequest(value) {
   }
   return request;
 }
-function objectWithKeys(value, required, optional) {
+function objectWithKeys(value, required2, optional2) {
   if (!(value instanceof Map)) {
     throw new ContractTypeError();
   }
-  for (const key of required) {
+  for (const key of required2) {
     if (!value.has(key)) {
       throw new ContractTypeError();
     }
   }
   for (const key of value.keys()) {
-    if (!required.includes(key) && !optional.includes(key)) {
+    if (!required2.includes(key) && !optional2.includes(key)) {
       throw new ContractTypeError();
     }
   }
@@ -1251,6 +1263,289 @@ function answer(status, value) {
   return new Response(buffer, { status, headers: { "content-type": "application/json" } });
 }
 
+// src/server/client-proof/contract-bundle.ts
+import { createHash as createHash2 } from "crypto";
+
+// src/server/types.ts
+var KEY_ALGORITHM = ["ES256", "RS256"];
+
+// src/server/client-proof/wire-headers.ts
+var CLIENT_IDENTITY_HEADERS = {
+  kind: "x-spfn-client-kind",
+  version: "x-spfn-client-version",
+  contractVersion: "x-spfn-client-contract-version"
+};
+var SERVER_CONTRACT_HEADERS = {
+  version: "x-spfn-server-contract-version",
+  supportedRange: "x-spfn-supported-contract-range"
+};
+var CLIENT_KINDS = ["web", "ios", "android"];
+function isAppKind(kind) {
+  return kind !== "web";
+}
+
+// src/server/client-proof/contract-bundle.ts
+var CONTRACT_VERSION = "0.6.0";
+var CONTRACT_MAJOR = 0;
+var CONTRACT_SUPPORTED_RANGE = ">=0.6.0 <0.7.0";
+function required(name, type) {
+  return { name, type, optional: false };
+}
+function optional(name, type) {
+  return { name, type, optional: true };
+}
+var CONTRACT_TYPES = [
+  {
+    name: "HandshakeRequest",
+    fields: [
+      required("clientId", "string"),
+      required("keyId", "string"),
+      required("nonce", "string"),
+      required("issuedAtMillis", "integer")
+    ]
+  },
+  {
+    name: "HandshakeResponse",
+    fields: [
+      required("sessionId", "string"),
+      required("expiresAtMillis", "integer")
+    ]
+  },
+  {
+    name: "EchoRequest",
+    fields: [
+      required("message", "string"),
+      required("sequence", "integer")
+    ]
+  },
+  {
+    name: "EchoResponse",
+    fields: [
+      required("message", "string"),
+      required("sequence", "integer"),
+      required("serverTimeMillis", "integer")
+    ]
+  },
+  {
+    name: "ListItemsRequest",
+    fields: [
+      required("limit", "integer"),
+      optional("cursor", "string")
+    ]
+  },
+  {
+    name: "Item",
+    fields: [
+      required("id", "string"),
+      required("name", "string"),
+      required("updatedAtMillis", "integer")
+    ]
+  },
+  {
+    name: "ListItemsResponse",
+    fields: [
+      required("items", "array<Item>"),
+      optional("nextCursor", "string")
+    ]
+  },
+  {
+    name: "RegisterRequest",
+    fields: [
+      optional("email", "string"),
+      optional("phone", "string"),
+      required("verificationToken", "string"),
+      required("password", "string"),
+      required("publicKey", "string"),
+      required("keyId", "string"),
+      required("fingerprint", "string"),
+      required("algorithm", "KeyAlgorithm")
+    ]
+  },
+  {
+    name: "RegisterResponse",
+    fields: [
+      required("userId", "string"),
+      required("publicId", "string"),
+      optional("email", "string"),
+      optional("phone", "string")
+    ]
+  },
+  {
+    name: "LoginRequest",
+    fields: [
+      optional("email", "string"),
+      optional("phone", "string"),
+      required("password", "string"),
+      required("publicKey", "string"),
+      required("keyId", "string"),
+      required("fingerprint", "string"),
+      required("algorithm", "KeyAlgorithm"),
+      optional("oldKeyId", "string")
+    ]
+  },
+  {
+    name: "LoginResponse",
+    fields: [
+      required("userId", "string"),
+      required("publicId", "string"),
+      optional("email", "string"),
+      optional("phone", "string"),
+      required("passwordChangeRequired", "boolean")
+    ]
+  },
+  {
+    name: "OauthNativeRequest",
+    fields: [
+      required("idToken", "string"),
+      required("nonce", "string"),
+      optional("accessToken", "string"),
+      required("publicKey", "string"),
+      required("keyId", "string"),
+      required("fingerprint", "string"),
+      required("algorithm", "KeyAlgorithm")
+    ]
+  },
+  {
+    name: "OauthNativeResponse",
+    fields: [
+      required("userId", "string"),
+      required("keyId", "string"),
+      required("isNewUser", "boolean")
+    ]
+  },
+  {
+    name: "RotateKeyRequest",
+    fields: [
+      required("publicKey", "string"),
+      required("keyId", "string"),
+      required("fingerprint", "string"),
+      required("algorithm", "KeyAlgorithm")
+    ]
+  },
+  {
+    name: "RotateKeyResponse",
+    fields: [
+      required("success", "boolean"),
+      required("keyId", "string")
+    ]
+  },
+  {
+    name: "ListKeysRequest",
+    fields: [
+      optional("includeRevoked", "boolean")
+    ]
+  },
+  {
+    name: "KeySummary",
+    fields: [
+      required("keyId", "string"),
+      optional("deviceName", "string"),
+      optional("platform", "string"),
+      required("algorithm", "KeyAlgorithm"),
+      required("fingerprintPrefix", "string"),
+      required("createdAtMillis", "integer"),
+      optional("lastUsedAtMillis", "integer"),
+      optional("expiresAtMillis", "integer"),
+      required("isExpired", "boolean"),
+      required("isActive", "boolean"),
+      optional("revokedAtMillis", "integer")
+    ]
+  },
+  {
+    name: "ListKeysResponse",
+    fields: [
+      required("keys", "array<KeySummary>")
+    ]
+  },
+  {
+    name: "RevokeKeyRequest",
+    fields: [
+      required("keyId", "string")
+    ]
+  },
+  {
+    name: "RevokeKeyResponse",
+    fields: [
+      required("keyId", "string"),
+      required("selfRevoked", "boolean")
+    ]
+  },
+  {
+    name: "RevokeAllKeysRequest",
+    fields: [
+      optional("includeCurrent", "boolean")
+    ]
+  },
+  {
+    name: "RevokeAllKeysResponse",
+    fields: [
+      required("revokedCount", "integer"),
+      required("currentKeyRevoked", "boolean")
+    ]
+  }
+];
+var CONTRACT_ENUMS = [
+  { name: "KeyAlgorithm", values: [...KEY_ALGORITHM] }
+];
+var BUNDLE_FILENAME = "spfn-mobile-contract.json";
+var BUNDLE_REPO_PATH = `contracts/mobile/${BUNDLE_FILENAME}`;
+
+// src/server/client-proof/wire-version.ts
+function readClientIdentity(headers) {
+  const kind = headers.get(CLIENT_IDENTITY_HEADERS.kind);
+  if (kind === null || !isClientKind(kind)) {
+    return null;
+  }
+  return {
+    kind,
+    version: headers.get(CLIENT_IDENTITY_HEADERS.version),
+    contractVersion: headers.get(CLIENT_IDENTITY_HEADERS.contractVersion)
+  };
+}
+function isClientKind(value) {
+  return CLIENT_KINDS.includes(value);
+}
+function isContractVersionSupported(clientVersion) {
+  const client = parseVersion(clientVersion);
+  if (client === null) {
+    return false;
+  }
+  const server = parseVersion(CONTRACT_VERSION);
+  if (server === null || client.major !== server.major) {
+    return false;
+  }
+  return CONTRACT_MAJOR > 0 || client.minor === server.minor;
+}
+function parseVersion(raw) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(raw);
+  if (match === null) {
+    return null;
+  }
+  return { major: Number(match[1]), minor: Number(match[2]) };
+}
+function judgeClientIdentity(identity) {
+  if (identity === null || !isAppKind(identity.kind)) {
+    return null;
+  }
+  if (identity.contractVersion === null) {
+    return ClientProofRefusal.contractVersionMissing();
+  }
+  if (!isContractVersionSupported(identity.contractVersion)) {
+    return ClientProofRefusal.contractVersionUnsupported();
+  }
+  return null;
+}
+function applyServerContractHeaders(headers) {
+  headers.set(SERVER_CONTRACT_HEADERS.version, CONTRACT_VERSION);
+  headers.set(SERVER_CONTRACT_HEADERS.supportedRange, CONTRACT_SUPPORTED_RANGE);
+}
+function serverContractHeaders() {
+  return {
+    [SERVER_CONTRACT_HEADERS.version]: CONTRACT_VERSION,
+    [SERVER_CONTRACT_HEADERS.supportedRange]: CONTRACT_SUPPORTED_RANGE
+  };
+}
+
 // src/server/client-proof/dev-handler.ts
 var MAX_BODY_BYTES = 1 << 20;
 var HTTP_OK2 = 200;
@@ -1368,7 +1663,7 @@ function listItems(request) {
 function contractResponse(status, body) {
   return new Response(toArrayBuffer(body), {
     status,
-    headers: { "content-type": "application/json" }
+    headers: { "content-type": "application/json", ...serverContractHeaders() }
   });
 }
 async function readBodyCapped(request) {
@@ -1419,7 +1714,8 @@ function createClientProofGuard(state, options = {}) {
       const bytes = admission.refusal.envelopeBytes(newHexId());
       const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
       return c.newResponse(buffer, admission.refusal.httpStatus, {
-        "content-type": "application/json"
+        "content-type": "application/json",
+        ...serverContractHeaders()
       });
     }
     c.set("clientType", "mobile");
@@ -1431,9 +1727,36 @@ function createClientProofGuard(state, options = {}) {
     return void 0;
   };
 }
+
+// src/server/client-proof/version-middleware.ts
+var CLIENT_IDENTITY_CONTEXT_KEY = "clientIdentity";
+function createClientVersionMiddleware() {
+  return async (c, next) => {
+    const identity = readClientIdentity(c.req.raw.headers);
+    const refusal = judgeClientIdentity(identity);
+    if (refusal !== null) {
+      const bytes = refusal.envelopeBytes(newHexId());
+      const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+      const response = c.newResponse(buffer, refusal.httpStatus, {
+        "content-type": "application/json"
+      });
+      applyServerContractHeaders(response.headers);
+      return response;
+    }
+    if (identity !== null) {
+      c.set(CLIENT_IDENTITY_CONTEXT_KEY, identity);
+    }
+    await next();
+    applyServerContractHeaders(c.res.headers);
+    return void 0;
+  };
+}
 export {
   ABSENT_BODY_SHA256,
   AUTH_SURFACE_OPERATIONS,
+  CLIENT_IDENTITY_CONTEXT_KEY,
+  CLIENT_IDENTITY_HEADERS,
+  CLIENT_KINDS,
   CLIENT_PROOF_CONTENT_TYPE,
   CLIENT_PROOF_HEADERS,
   CLIENT_PROOF_PROFILE,
@@ -1454,12 +1777,15 @@ export {
   PROOF_SIGNATURE_HEX_LENGTH,
   ProofInputError,
   RedisReplayStore,
+  SERVER_CONTRACT_HEADERS,
   TestClock,
   admitClientProofRequest,
+  applyServerContractHeaders,
   canonicalProofInput,
   configureClientProofReplayStore,
   createClientProofDevHandler,
   createClientProofGuard,
+  createClientVersionMiddleware,
   decodeEchoRequest,
   decodeHandshakeRequest,
   decodeListItemsRequest,
@@ -1468,13 +1794,18 @@ export {
   encodeHandshakeResponse,
   encodeListItemsResponse,
   getClientProofReplayStore,
+  isAppKind,
   isCanonicalBytes,
+  isContractVersionSupported,
   isRequestContentType,
+  judgeClientIdentity,
   newHexId,
   parseCanonicalJson,
   parseClientProofPublicKey,
+  readClientIdentity,
   readCredentials,
   replayLedgerKey,
+  serverContractHeaders,
   sha256Hex,
   signClientProof,
   systemClock,