@ultimat3/core 22.5.0 → 22.5.1

package/CLAUDE.md

@@ -95,9 +95,12 @@ top-level `UltimateError` use in `error-codes.ts`.
   derives their retry classification from the same set. It is a `SIDE_EFFECTS_ANCHORS` entry.
 - `timing-safe-equal.ts` is the one constant-time comparison (`@ultimat3/auth`, `@ultimat3/storage`).
 - **`canonical-json.ts`: `canonicalJson` is INJECTIVE and `fingerprint` is SHA-256/16 of it** — the
-  hash every sharing key is taken over (`action`'s `requestHash`, `query`'s `queryHash`, `realtime`'s
-  `qid`). `NaN`, `±Infinity` and `-0` are bare tokens; `Date`, `Map` and `Set` are TAGGED. Never a
+  hash every in-memory sharing key is taken over (`query`'s `queryHash`, `realtime`'s `qid`).
+  `NaN`, `±Infinity` and `-0` are bare tokens; `Date`, `Map` and `Set` are TAGGED. Never a
   fourth copy, never parseable (`@ultimat3/action`'s `stableStringify` is the document form).
+- **A PERSISTED fingerprint is `keyedFingerprint`** (`keyed-fingerprint.ts`: HMAC under a per-purpose
+  key derived from the cursor secret, `h1:` versioned) — `action`'s idempotency `requestHash`. An
+  unkeyed prefix in a table is an offline oracle for a short account number in the input.
 - **`decimal-order.ts`'s `compareDecimalText` answers `undefined` for a non-decimal**, and only a
   caller that knows the column's kind may ask (`@ultimat3/entity`'s `compareByKind`) — never
   `@ultimat3/query`, whose `OrderKey` has no kind.

package/README.md

@@ -498,6 +498,7 @@ never a silently wrong page.
 |---|---|
 | Signature | truncated HMAC-SHA256, compared in constant time |
 | Secret | `configureCursorSigning()` at boot, else `ULTIMATE_CURSOR_SECRET`. **Read when a cursor is signed, never at import** — an app whose `openSecrets()` sets the variable during boot would otherwise sign every cursor with the dev key. Rotating it invalidates every open cursor |
+| Also keys | `keyedFingerprint(value, purpose)` — `h1:<key id>:<HMAC>` over `canonicalJson`, under a per-purpose key derived from this secret; the fingerprint to PERSIST (`@ultimat3/action`'s idempotency `requestHash`). `compareFingerprint` answers `match` / `mismatch` / `unverifiable` (other key), and still checks a legacy bare `fingerprint()` exactly. Rotating the secret makes in-window stored fingerprints `unverifiable` |
 | Signed, not encrypted | the client already has these rows; what it must not do is *invent* a position |
 | `usesDevCursorSecret()` | true while the shipped dev key is in use |
 | `resetCursorSigning()` | test seam: forget `configureCursorSigning` and fall back to the environment |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "22.5.0",
+  "version": "22.5.1",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "22.5.0"
+    "@ultimat3/schema": "22.5.1"
   }
 }

package/src/canonical-json.ts

@@ -119,6 +119,10 @@ export function canonicalJson(value: unknown): string {
  * hands one caller another's rows. FNV-1a/32, which two of the three copies started as, is
  * 4x10^9 values and brute-forceable offline in seconds: an input landing on another read's key was
  * something an attacker could mint rather than something they had to wait for.
+ *
+ * UNKEYED, so never the thing to PERSIST beside input that may hold a low-entropy secret — a
+ * 64-bit prefix of a known hash is an offline oracle for a short account number. A stored
+ * fingerprint is `keyedFingerprint` (`keyed-fingerprint.ts`).
  */
 export function fingerprint(value: unknown): string {
   return new Bun.CryptoHasher('sha256').update(canonicalJson(value)).digest('hex').slice(0, 16);

package/src/cursor.ts

@@ -52,6 +52,14 @@ function currentSecret(): string {
   return configured ?? Bun.env['ULTIMATE_CURSOR_SECRET'] ?? DEV_SECRET;
 }
 
+/**
+ * The app's signing secret, exactly as cursor signing reads it. Internal to `@ultimat3/core`:
+ * `keyed-fingerprint.ts` derives its own key from it, so an app has one secret to set, not two.
+ */
+export function currentSigningSecret(): string {
+  return currentSecret();
+}
+
 /** Set once at boot from the app secret. Rotating it invalidates every open cursor. */
 export function configureCursorSigning(next: string): void {
   configured = next;

package/src/index.ts

@@ -509,6 +509,12 @@ export {
 } from './intl-cache';
 export { isIsoDateTime } from './iso-date';
 export { isJsonObject } from './json-object';
+export type { FingerprintMatch } from './keyed-fingerprint';
+export {
+  compareFingerprint,
+  KEYED_FINGERPRINT_VERSION,
+  keyedFingerprint,
+} from './keyed-fingerprint';
 export type {
   HealthPayload,
   HealthReport,

package/src/keyed-fingerprint.ts

@@ -0,0 +1,69 @@
+// Single responsibility: a fingerprint of caller input that is safe to PERSIST. `fingerprint()` is
+// an unkeyed SHA-256 prefix — fine as an in-memory sharing key, but stored beside a row it is an
+// offline oracle: a 6–20-digit account number or an ID number in an input, with the other fields
+// known, is brute-forced from a database read. Keyed with HMAC-SHA-256, the stored value proves
+// nothing to anyone without the app's signing secret.
+
+import { canonicalJson, fingerprint } from './canonical-json';
+import { currentSigningSecret } from './cursor';
+import { timingSafeEqual } from './timing-safe-equal';
+
+/** The format tag. A stored value without it predates keying (see `compareFingerprint`). */
+export const KEYED_FINGERPRINT_VERSION = 'h1';
+
+/**
+ * What a stored fingerprint says about an input:
+ * - `match` / `mismatch` — computed under the key in force now (or the legacy unkeyed form);
+ * - `unverifiable` — keyed under a secret this process does not hold (a rotation), or a format this
+ *   build does not know. The input can be neither confirmed nor refused.
+ */
+export type FingerprintMatch = 'match' | 'mismatch' | 'unverifiable';
+
+const LEGACY = /^[0-9a-f]{16}$/;
+
+/** One key per purpose, derived from the signing secret, so no two uses share a MAC key. */
+function derivedKey(purpose: string): string {
+  return new Bun.CryptoHasher('sha256', currentSigningSecret())
+    .update(`ultimate:keyed-fingerprint:${purpose}`)
+    .digest('hex');
+}
+
+/**
+ * Names the key a fingerprint was made under, so a rotation reads as `unverifiable` rather than as
+ * a mismatch. 32 bits of a hash of a 256-bit derived key: a label, useless for recovering it.
+ */
+function keyId(key: string): string {
+  return new Bun.CryptoHasher('sha256').update(key).digest('hex').slice(0, 8);
+}
+
+/**
+ * `h1:<key id>:<HMAC-SHA-256 over canonical JSON, 128 bits>`. `purpose` separates uses: the same
+ * input fingerprints differently for two purposes. Under the shipped development secret this is as
+ * public as `fingerprint()` — production boot refuses that secret (`X_CURSOR_SECRET_DEV`).
+ */
+export function keyedFingerprint(value: unknown, purpose: string): string {
+  const key = derivedKey(purpose);
+  const mac = new Bun.CryptoHasher('sha256', key)
+    .update(canonicalJson(value))
+    .digest('hex')
+    .slice(0, 32);
+  return `${KEYED_FINGERPRINT_VERSION}:${keyId(key)}:${mac}`;
+}
+
+/**
+ * Compare a STORED fingerprint with an input. A legacy unkeyed value (16 hex characters, written by
+ * a build before keying) is checked against `fingerprint()` computed here and never stored, so rows
+ * written across an upgrade keep their exact semantics until they age out.
+ */
+export function compareFingerprint(
+  stored: string,
+  value: unknown,
+  purpose: string,
+): FingerprintMatch {
+  if (LEGACY.test(stored))
+    return timingSafeEqual(stored, fingerprint(value)) ? 'match' : 'mismatch';
+  const current = keyedFingerprint(value, purpose);
+  const prefix = current.slice(0, current.lastIndexOf(':') + 1);
+  if (!stored.startsWith(prefix)) return 'unverifiable';
+  return timingSafeEqual(stored, current) ? 'match' : 'mismatch';
+}