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

package/dist/client-proof.js

@@ -345,10 +345,25 @@ function encodeString(value) {
 }
 
 // src/server/client-proof/proof.ts
-import { createHash, createHmac, timingSafeEqual } from "crypto";
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from "crypto";
 var CLIENT_PROOF_PROFILE = "clientProofV1";
 var ABSENT_BODY_SHA256 = "0".repeat(64);
 var DEFAULT_REPLAY_WINDOW_MILLIS = 3e5;
+var PROOF_INPUT_FIELDS = [
+  "profile",
+  "method",
+  "path",
+  "clientId",
+  "keyId",
+  "nonce",
+  "issuedAtMillis",
+  "bodySha256"
+];
+var PROOF_INPUT_SEPARATOR = "\n";
+var PROOF_SIGNATURE_BYTES = 64;
+var PROOF_SIGNATURE_HEX_LENGTH = PROOF_SIGNATURE_BYTES * 2;
+var PROOF_SIGNATURE_PATTERN = /^[0-9a-f]{128}$/;
+var RAW_SIGNATURE_ENCODING = "ieee-p1363";
 var ProofInputError = class extends Error {
   constructor() {
     super("proof input field contains a C0 control character");
@@ -356,16 +371,17 @@ var ProofInputError = class extends Error {
   }
 };
 function canonicalProofInput(input) {
-  const fields = [
-    CLIENT_PROOF_PROFILE,
-    input.method,
-    input.path,
-    input.clientId,
-    input.keyId,
-    input.nonce,
-    input.issuedAtMillis.toString(),
-    input.bodySha256
-  ];
+  const values = {
+    profile: CLIENT_PROOF_PROFILE,
+    method: input.method,
+    path: input.path,
+    clientId: input.clientId,
+    keyId: input.keyId,
+    nonce: input.nonce,
+    issuedAtMillis: input.issuedAtMillis.toString(),
+    bodySha256: input.bodySha256
+  };
+  const fields = PROOF_INPUT_FIELDS.map((name) => values[name]);
   for (const field of fields) {
     for (const ch of field) {
       if (ch.codePointAt(0) < 32) {
@@ -373,21 +389,45 @@ function canonicalProofInput(input) {
       }
     }
   }
-  return fields.join("\n");
+  return fields.join(PROOF_INPUT_SEPARATOR);
 }
-function computeClientProof(input, key) {
-  return createHmac("sha256", key).update(canonicalProofInput(input), "utf8").digest("hex");
-}
-function sha256Hex(bytes) {
-  return createHash("sha256").update(bytes).digest("hex");
+function parseClientProofPublicKey(spkiDerBase64) {
+  const key = createPublicKey({
+    key: Buffer.from(spkiDerBase64, "base64"),
+    format: "der",
+    type: "spki"
+  });
+  if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") {
+    throw new Error("a clientProofV1 public key must be an ECDSA P-256 key");
+  }
+  return key;
 }
-function constantTimeEqualsProof(expected, presented) {
-  const a = Buffer.from(expected, "utf8");
-  const b = Buffer.from(presented, "utf8");
-  if (a.length !== b.length) {
+function verifyClientProof(input, presentedProof, publicKey) {
+  const data = Buffer.from(canonicalProofInput(input), "utf8");
+  if (!PROOF_SIGNATURE_PATTERN.test(presentedProof)) {
     return false;
   }
-  return timingSafeEqual(a, b);
+  return verify(
+    "sha256",
+    data,
+    { key: publicKey, dsaEncoding: RAW_SIGNATURE_ENCODING },
+    Buffer.from(presentedProof, "hex")
+  );
+}
+function signClientProof(input, privateKeyPkcs8DerBase64) {
+  const key = createPrivateKey({
+    key: Buffer.from(privateKeyPkcs8DerBase64, "base64"),
+    format: "der",
+    type: "pkcs8"
+  });
+  return sign(
+    "sha256",
+    Buffer.from(canonicalProofInput(input), "utf8"),
+    { key, dsaEncoding: RAW_SIGNATURE_ENCODING }
+  ).toString("hex");
+}
+function sha256Hex(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
 }
 
 // src/server/client-proof/refusal.ts
@@ -478,6 +518,86 @@ function contractViolation(message) {
   return new ClientProofRefusal("CONTRACT_UNSUPPORTED", message);
 }
 
+// src/server/client-proof/replay-store.ts
+import { getCache } from "@spfn/core/cache";
+function replayLedgerKey(clientId, nonce) {
+  return JSON.stringify([clientId, nonce]);
+}
+var MemoryReplayLedger = class {
+  /** replayLedgerKey(...) → the millis it was spent at. */
+  spent = /* @__PURE__ */ new Map();
+  isSpent(clientId, nonce) {
+    return this.spent.has(replayLedgerKey(clientId, nonce));
+  }
+  /** Records the pair at `atMillis`; false when it was already spent. */
+  spend(clientId, nonce, atMillis) {
+    const key = replayLedgerKey(clientId, nonce);
+    if (this.spent.has(key)) {
+      return false;
+    }
+    this.spent.set(key, atMillis);
+    return true;
+  }
+  /** Drops entries older than the window, judged against `nowMillis`. */
+  prune(nowMillis, windowMillis) {
+    for (const [key, spentAtMillis] of this.spent) {
+      if (nowMillis - spentAtMillis > windowMillis) {
+        this.spent.delete(key);
+      }
+    }
+  }
+  get size() {
+    return this.spent.size;
+  }
+  clear() {
+    this.spent.clear();
+  }
+};
+var MemoryReplayStore = class {
+  constructor(windowMillis = DEFAULT_REPLAY_WINDOW_MILLIS) {
+    this.windowMillis = windowMillis;
+  }
+  ledger = new MemoryReplayLedger();
+  async isSpent(clientId, nonce) {
+    this.ledger.prune(Date.now(), this.windowMillis);
+    return this.ledger.isSpent(clientId, nonce);
+  }
+  async spend(clientId, nonce) {
+    const now = Date.now();
+    this.ledger.prune(now, this.windowMillis);
+    return this.ledger.spend(clientId, nonce, now);
+  }
+};
+var RedisReplayStore = class {
+  constructor(windowMillis = DEFAULT_REPLAY_WINDOW_MILLIS) {
+    this.windowMillis = windowMillis;
+  }
+  async isSpent(clientId, nonce) {
+    return await this.cache().exists(this.key(clientId, nonce)) === 1;
+  }
+  async spend(clientId, nonce) {
+    return await this.cache().set(this.key(clientId, nonce), "1", "PX", this.windowMillis, "NX") === "OK";
+  }
+  cache() {
+    const cache = getCache();
+    if (!cache) {
+      throw new Error("client-proof replay ledger: cache is not available");
+    }
+    return cache;
+  }
+  key(clientId, nonce) {
+    return `spfn:auth:client-proof:replay:${sha256Hex(Buffer.from(replayLedgerKey(clientId, nonce), "utf8"))}`;
+  }
+};
+var configured = null;
+function configureClientProofReplayStore(store) {
+  configured = store;
+}
+function getClientProofReplayStore() {
+  configured ??= new MemoryReplayStore();
+  return configured;
+}
+
 // src/server/client-proof/state.ts
 function systemClock() {
   return { nowMillis: () => Date.now() };
@@ -494,16 +614,14 @@ var TestClock = class {
   }
 };
 var DEFAULT_SESSION_TTL_MILLIS = 6e5;
-function replayKeyOf(clientId, nonce) {
-  return `${clientId}${nonce}`;
-}
 var ClientProofState = class {
   replayWindowMillis;
   clock;
-  keys = /* @__PURE__ */ new Map();
+  initialPublicKeys;
+  publicKeys = /* @__PURE__ */ new Map();
   sessions = /* @__PURE__ */ new Map();
-  /** replayKeyOf(...) → the issuedAtMillis it was spent at. */
-  spentNonces = /* @__PURE__ */ new Map();
+  /** The replay ledger — the shared memory implementation, used dev-only here. */
+  spentNonces = new MemoryReplayLedger();
   revokedKeyIds = /* @__PURE__ */ new Set();
   holds = /* @__PURE__ */ new Map();
   initialSessionTtlMillis;
@@ -518,10 +636,22 @@ var ClientProofState = class {
     this.initialSessionTtlMillis = options.sessionTtlMillis ?? DEFAULT_SESSION_TTL_MILLIS;
     this.sessionTtlMillis = this.initialSessionTtlMillis;
     this.replayWindowMillis = options.replayWindowMillis ?? DEFAULT_REPLAY_WINDOW_MILLIS;
-    for (const [keyId, key] of Object.entries(options.keys)) {
-      this.keys.set(keyId, typeof key === "string" ? new TextEncoder().encode(key) : key);
+    this.initialPublicKeys = new Map(
+      Object.entries(options.publicKeys).map(([keyId, spki]) => [keyId, parseClientProofPublicKey(spki)])
+    );
+    for (const [keyId, key] of this.initialPublicKeys) {
+      this.publicKeys.set(keyId, key);
     }
   }
+  // ---- key registration --------------------------------------------------
+  /**
+   * Registers (or replaces) the public key `keyId` presents proofs under.
+   *
+   * @throws when the key is not base64 SPKI DER naming a P-256 key.
+   */
+  registerPublicKey(keyId, publicKeySpkiDerBase64) {
+    this.publicKeys.set(keyId, parseClientProofPublicKey(publicKeySpkiDerBase64));
+  }
   // ---- admission ---------------------------------------------------------
   /**
    * Runs the contract's checks in the contract's order and returns the
@@ -543,18 +673,17 @@ var ClientProofState = class {
     if (age < 0 || age > this.replayWindowMillis) {
       return ClientProofRefusal.proofExpired();
     }
-    const replayKey = replayKeyOf(args.clientId, args.proofInput.nonce);
-    if (this.spentNonces.has(replayKey)) {
+    if (this.spentNonces.isSpent(args.clientId, args.proofInput.nonce)) {
       return ClientProofRefusal.proofReplayed();
     }
-    const key = this.keys.get(args.keyId);
-    if (key === void 0) {
+    const publicKey = this.publicKeys.get(args.keyId);
+    if (publicKey === void 0) {
       return ClientProofRefusal.proofInvalid();
     }
-    if (!constantTimeEqualsProof(computeClientProof(args.proofInput, key), args.presentedProof)) {
+    if (!verifyClientProof(args.proofInput, args.presentedProof, publicKey)) {
       return ClientProofRefusal.proofInvalid();
     }
-    this.spentNonces.set(replayKey, Number(args.proofInput.issuedAtMillis));
+    this.spentNonces.spend(args.clientId, args.proofInput.nonce, Number(args.proofInput.issuedAtMillis));
     return null;
   }
   // ---- sessions ----------------------------------------------------------
@@ -587,8 +716,12 @@ var ClientProofState = class {
   setSessionTtlMillis(millis) {
     this.sessionTtlMillis = millis;
   }
-  /** Returns the state to how it started, counters included. */
+  /** Returns the state to how it started, counters and registered keys included. */
   reset() {
+    this.publicKeys.clear();
+    for (const [keyId, key] of this.initialPublicKeys) {
+      this.publicKeys.set(keyId, key);
+    }
     this.sessions.clear();
     this.spentNonces.clear();
     this.revokedKeyIds.clear();
@@ -666,11 +799,7 @@ var ClientProofState = class {
         this.sessions.delete(sessionId);
       }
     }
-    for (const [key, issuedAtMillis] of this.spentNonces) {
-      if (nowMillis - issuedAtMillis > this.replayWindowMillis) {
-        this.spentNonces.delete(key);
-      }
-    }
+    this.spentNonces.prune(nowMillis, this.replayWindowMillis);
   }
 };
 
@@ -783,9 +912,78 @@ function isRequestContentType(value) {
 
 // src/server/client-proof/contract-types.ts
 var CONTRACT_OPERATIONS = [
-  { id: "auth.clientProof.handshake", method: "POST", path: "/v1/auth/client-proof/handshake", requiresSession: false },
-  { id: "echo.send", method: "POST", path: "/v1/echo", requiresSession: true },
-  { id: "items.list", method: "POST", path: "/v1/items/list", requiresSession: true }
+  {
+    id: "auth.clientProof.handshake",
+    method: "POST",
+    path: "/v1/auth/client-proof/handshake",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    requestType: "HandshakeRequest",
+    responseType: "HandshakeResponse",
+    summary: "Presents a client proof and opens a session."
+  },
+  {
+    id: "echo.send",
+    method: "POST",
+    path: "/v1/echo",
+    authProfile: "clientProofV1",
+    requiresSession: true,
+    requestType: "EchoRequest",
+    responseType: "EchoResponse",
+    summary: "Authenticated round trip used as the smallest real vertical slice."
+  },
+  {
+    id: "items.list",
+    method: "POST",
+    path: "/v1/items/list",
+    authProfile: "clientProofV1",
+    requiresSession: true,
+    requestType: "ListItemsRequest",
+    responseType: "ListItemsResponse",
+    summary: "Authenticated paged read covering optional fields and arrays."
+  }
+];
+var AUTH_SURFACE_OPERATIONS = [
+  {
+    id: "auth.enroll.register",
+    method: "POST",
+    path: "/_auth/register",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "RegisterRequest",
+    responseType: "RegisterResponse",
+    summary: "Registers an account with a verification token and enrolls the client-generated public key."
+  },
+  {
+    id: "auth.enroll.login",
+    method: "POST",
+    path: "/_auth/login",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "LoginRequest",
+    responseType: "LoginResponse",
+    summary: "Authenticates with password credentials and enrolls a fresh client-generated public key."
+  },
+  {
+    id: "auth.enroll.oauthNative",
+    method: "POST",
+    path: "/_auth/oauth/{provider}/native",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "OauthNativeRequest",
+    responseType: "OauthNativeResponse",
+    summary: "Verifies a native/web social id_token server-side and enrolls the client-generated public key."
+  },
+  {
+    id: "auth.keys.rotate",
+    method: "POST",
+    path: "/_auth/keys/rotate",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    requestType: "RotateKeyRequest",
+    responseType: "RotateKeyResponse",
+    summary: "Replaces the authenticated key with a new client-generated public key before its TTL runs out."
+  }
 ];
 var ContractTypeError = class extends Error {
   constructor() {
@@ -898,6 +1096,8 @@ async function handleControlRequest(state, controlToken, path, request) {
     case "/control/expire-sessions":
       state.expireSessions();
       return ok();
+    case "/control/register-key":
+      return registerKey(state, body);
     case "/control/revoke-key":
       return revokeKey(state, body);
     case "/control/session-ttl":
@@ -922,6 +1122,22 @@ function stats(state) {
     ["spentNonceCount", BigInt(counters.spentNonceCount)]
   ])));
 }
+function registerKey(state, body) {
+  const keyId = stringField(body, "keyId");
+  const publicKey = stringField(body, "publicKey");
+  if (keyId === null) {
+    return badRequest("keyId");
+  }
+  if (publicKey === null) {
+    return badRequest("publicKey");
+  }
+  try {
+    state.registerPublicKey(keyId, publicKey);
+  } catch {
+    return badRequest("publicKey");
+  }
+  return ok();
+}
 function revokeKey(state, body) {
   const keyId = stringField(body, "keyId");
   if (keyId === null) {
@@ -1187,6 +1403,7 @@ function createClientProofGuard(state, options = {}) {
 }
 export {
   ABSENT_BODY_SHA256,
+  AUTH_SURFACE_OPERATIONS,
   CLIENT_PROOF_CONTENT_TYPE,
   CLIENT_PROOF_HEADERS,
   CLIENT_PROOF_PROFILE,
@@ -1201,12 +1418,16 @@ export {
   DEFAULT_SESSION_TTL_MILLIS,
   DEV_CATALOGUE,
   DEV_MAX_LIMIT,
+  MemoryReplayLedger,
+  MemoryReplayStore,
+  PROOF_SIGNATURE_BYTES,
+  PROOF_SIGNATURE_HEX_LENGTH,
   ProofInputError,
+  RedisReplayStore,
   TestClock,
   admitClientProofRequest,
   canonicalProofInput,
-  computeClientProof,
-  constantTimeEqualsProof,
+  configureClientProofReplayStore,
   createClientProofDevHandler,
   createClientProofGuard,
   decodeEchoRequest,
@@ -1216,10 +1437,17 @@ export {
   encodeEchoResponse,
   encodeHandshakeResponse,
   encodeListItemsResponse,
+  getClientProofReplayStore,
   isCanonicalBytes,
+  isRequestContentType,
   newHexId,
   parseCanonicalJson,
+  parseClientProofPublicKey,
+  readCredentials,
+  replayLedgerKey,
   sha256Hex,
-  systemClock
+  signClientProof,
+  systemClock,
+  verifyClientProof
 };
 //# sourceMappingURL=client-proof.js.map