@ultimat3/core 22.5.0 → 22.6.0

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.6.0",
   "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.6.0"
   }
 }

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/client-paths.ts

@@ -51,12 +51,42 @@ export function pluralize(word: string): string {
   return `${word}s`;
 }
 
+/**
+ * How an action's export name becomes its URL. Declared once per app
+ * (`defineApi({ http: { pathStyle } })`), never per action — one app, one rule.
+ *
+ * | style | `publishPost` | `signIn` | `health` |
+ * |---|---|---|---|
+ * | `'resource'` (default) | `/api/posts/publish` | `/api/ins/sign` | `/api/healths/invoke` |
+ * | `'readable'` | `/api/publish-post` | `/api/sign-in` | `/api/health` |
+ *
+ * `'resource'` guesses a noun from the words after the first and pluralizes it, which is right for
+ * `verbNoun` names and ungrammatical for everything else. `'readable'` guesses nothing: the path IS
+ * the name, kebab-cased — the rule `/_x/query/<kebab>` has always followed for reads.
+ */
+export type ActionPathStyle = 'resource' | 'readable';
+
+export const ACTION_PATH_STYLES: readonly ActionPathStyle[] = ['resource', 'readable'];
+
+/** Every action is served under one prefix, whichever style derives the rest. */
+export const ACTION_PATH_PREFIX = '/api';
+
 /**
  * `publishPost` -> `/api/posts/publish`, `updateUserProfile` -> `/api/user-profiles/update`,
- * `checkout` -> `/api/checkouts/invoke` (single-word fallback).
+ * `checkout` -> `/api/checkouts/invoke` (single-word fallback) — the `'resource'` style.
+ * `'readable'` -> `/api/publish-post`, `/api/update-user-profile`, `/api/checkout`: `verb` is the
+ * first word and `resource` the rest, both unpluralized, and neither is part of the path.
  */
-export function actionRoute(name: string): ActionRoute {
+export function actionRoute(name: string, style: ActionPathStyle = 'resource'): ActionRoute {
   const words = splitWords(name);
+  if (style === 'readable') {
+    const kebab = words.length === 0 ? 'invoke' : words.join('-');
+    return {
+      verb: words[0] ?? 'invoke',
+      resource: words.length < 2 ? kebab : words.slice(1).join('-'),
+      path: `${ACTION_PATH_PREFIX}/${kebab}`,
+    };
+  }
   const head = words[0] ?? 'invoke';
   if (words.length < 2) {
     const resource = pluralize(head);
@@ -68,9 +98,9 @@ export function actionRoute(name: string): ActionRoute {
   return { verb: head, resource, path: `/api/${resource}/${head}` };
 }
 
-/** The path an action is POSTed to — `actionRoute(name).path`. */
-export function actionPath(name: string): string {
-  return actionRoute(name).path;
+/** The path an action is POSTed to — `actionRoute(name, style).path`. */
+export function actionPath(name: string, style: ActionPathStyle = 'resource'): string {
+  return actionRoute(name, style).path;
 }
 
 /** `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. */

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

@@ -68,8 +68,10 @@ export type {
   FlightPlan,
 } from './client-flight';
 export { createClientFlight, DEFAULT_CLIENT_RETRY, isTransientFailure } from './client-flight';
-export type { ActionRoute } from './client-paths';
+export type { ActionPathStyle, ActionRoute } from './client-paths';
 export {
+  ACTION_PATH_PREFIX,
+  ACTION_PATH_STYLES,
   actionPath,
   actionRoute,
   pluralize,
@@ -509,6 +511,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';
+}

package/src/telemetry.ts

@@ -69,6 +69,12 @@ export interface Span {
   addEvent(name: string, attributes?: SpanAttributes): Span;
   recordError(error: unknown): Span;
   setStatus(code: SpanStatusCode, message?: string): Span;
+  /**
+   * Rename a span that learned what it is only after it started — an HTTP server span is opened
+   * before the router matches, and its name must be the route PATTERN (`GET /r/:token`), never the
+   * concrete URL, which carries capability tokens. A no-op once the span has ended.
+   */
+  updateName(name: string): Span;
   end(): void;
 }
 
@@ -194,7 +200,8 @@ function inboundParent(parent: SpanContext | undefined): SpanContext | undefined
   return parent === undefined || parent.spanId === '' ? undefined : parent;
 }
 
-export function startSpan(name: string, options?: StartSpanOptions): Span {
+export function startSpan(initialName: string, options?: StartSpanOptions): Span {
+  let name = initialName;
   // A live span is what gives an outbound typed call a trace to continue; see the module.
   installTraceHeaders();
   const parent = options?.parent ?? currentSpanContext();
@@ -219,7 +226,9 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
   let ended = false;
 
   const span: Span = {
-    name,
+    get name(): string {
+      return name;
+    },
     context,
     get ended(): boolean {
       return ended;
@@ -260,6 +269,10 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
       status = { code, message };
       return span;
     },
+    updateName(next) {
+      if (!ended) name = next;
+      return span;
+    },
     end(): void {
       if (ended) return;
       ended = true;