@ultimat3/core 22.4.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.4.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.4.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/config-health.ts

@@ -0,0 +1,58 @@
+// Single responsibility: the `health` and `drain` sections of `app.config.ts` — what `/readyz`
+// means and how a SIGTERM'd process leaves the load balancer — and the domain of the readiness
+// mode, so the config validator and `configureLifecycle` refuse the same values.
+
+import { UltimateError } from './errors';
+
+/**
+ * `'dependencies'` (the default): `/readyz` is 503 while starting, draining, or while ANY registered
+ * check fails. `'process'`: 503 only while starting or draining — a failing check is REPORTED in the
+ * body (`checks.database: 'failing'`) and the status stays 200.
+ *
+ * Why the second exists: every replica shares the dependency, so one database blip marks the WHOLE
+ * fleet unready at once and the ingress answers "no available server" for every URL — pages that
+ * never touch the database included — where the app itself would have served them, or answered its
+ * own 503 for the ones that do. `/readyz?deep=1` always answers in `'dependencies'` mode, so
+ * monitoring still sees the dependency fail.
+ */
+export type ReadinessMode = 'dependencies' | 'process';
+
+export const READINESS_MODES: readonly ReadinessMode[] = ['dependencies', 'process'];
+
+/** `app.config.ts`'s `health` section. Read by the production boot into `configureLifecycle`. */
+export interface HealthConfig {
+  readonly readiness: ReadinessMode;
+}
+
+/**
+ * How a SIGTERM'd process leaves the load balancer. Read by `@ultimat3/http`'s `createServer`
+ * (`ServerOptions.drain`), which hands it to core's `configureLifecycle`.
+ */
+export interface DrainConfig {
+  /**
+   * `/readyz` answers 503 for this long before the listener closes, so endpoints stop routing here
+   * first. Default 0 in development/test and 5000 everywhere else — a process naming NO environment
+   * included. A whole number, 0–60000. The chart's `terminationGracePeriodSeconds` must exceed it
+   * plus the drain budget.
+   */
+  readonly readinessGraceMs: number;
+}
+
+/** Why a value is not a readiness mode, or `undefined` when it is one. */
+export function readinessModeIssue(value: unknown): string | undefined {
+  if (READINESS_MODES.some((mode) => mode === value)) return undefined;
+  const said = typeof value === 'string' ? `"${value}"` : typeof value;
+  return `health.readiness ${said} is not one of ${READINESS_MODES.join(', ')}`;
+}
+
+/** `configureLifecycle`'s screen: the mode, or `X_CONFIG_INVALID` naming the key. */
+export function assertReadinessMode(value: unknown): ReadinessMode {
+  const issue = readinessModeIssue(value);
+  if (issue === undefined) return value as ReadinessMode;
+  throw new UltimateError({
+    code: 'X_CONFIG_INVALID',
+    cause: issue,
+    fix: "set health: { readiness: 'process' } (or 'dependencies', the default) in app.config.ts",
+    meta: { key: 'health.readiness' },
+  });
+}

package/src/config.ts

@@ -9,6 +9,8 @@ import { CURRENCY_CODE_PATTERN } from '@ultimat3/schema';
 import { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 import { countIssue } from './config-count';
 import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
+import type { DrainConfig, HealthConfig } from './config-health';
+import { readinessModeIssue } from './config-health';
 import { type Input, lastSaid, layered } from './config-merge';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
@@ -183,20 +185,6 @@ export interface AiConfig {
   readonly mcp: McpConfig;
 }
 
-/**
- * How a SIGTERM'd process leaves the load balancer. Read by `@ultimat3/http`'s `createServer`
- * (`ServerOptions.drain`), which hands it to core's `configureLifecycle`.
- */
-export interface DrainConfig {
-  /**
-   * `/readyz` answers 503 for this long before the listener closes, so endpoints stop routing here
-   * first. Default 0 in development/test and 5000 everywhere else — a process naming NO environment
-   * included. A whole number, 0–60000. The chart's `terminationGracePeriodSeconds` must exceed it
-   * plus the drain budget.
-   */
-  readonly readinessGraceMs: number;
-}
-
 export interface AppConfig {
   readonly name: string;
   readonly locales: readonly string[];
@@ -214,6 +202,7 @@ export interface AppConfig {
   readonly notify: NotifyConfig;
   readonly ai: AiConfig;
   readonly drain: DrainConfig;
+  readonly health: HealthConfig;
   readonly site: SiteConfig;
   readonly seo: SeoConfig;
 }
@@ -251,6 +240,7 @@ export interface AppConfigInput extends SiteSectionsInput {
   readonly notify?: Input<NotifyConfig> | undefined;
   readonly ai?: AiConfigInput | undefined;
   readonly drain?: Input<DrainConfig> | undefined;
+  readonly health?: Input<HealthConfig> | undefined;
 }
 
 /** An overlay from `config/<concern>.ts`. No `name` — the base owns it. */
@@ -308,6 +298,7 @@ function defaults(name: string): Omit<AppConfig, 'name' | 'site' | 'seo'> {
     ai: { mcp: { expose: true, path: '/mcp' } },
     // Read from the process env when the config is DEFINED — the same env the drain will run in.
     drain: { readinessGraceMs: defaultReadinessGraceMs() },
+    health: { readiness: 'dependencies' },
   };
 }
 
@@ -352,6 +343,7 @@ function validate(config: AppConfig): void {
     countIssue('jobs.visibilityTimeoutMs', config.jobs.visibilityTimeoutMs, 1),
     countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0),
     readinessGraceIssue(config.drain.readinessGraceMs),
+    readinessModeIssue(config.health.readiness),
   ];
   for (const issue of counts) if (issue !== undefined) issues.push(issue);
   if (config.jobs.queues.length === 0) issues.push('jobs.queues must list at least one queue');
@@ -492,6 +484,10 @@ export function defineConfig(
       base.drain,
       layers.map((layer) => layer.drain),
     ),
+    health: layered(
+      base.health,
+      layers.map((layer) => layer.health),
+    ),
     ...mergeSite(layers),
   };
 

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

@@ -98,7 +98,6 @@ export type {
   AuthConfig,
   CacheConfig,
   DatabaseConfig,
-  DrainConfig,
   JobsConfig,
   McpConfig,
   NotifyConfig,
@@ -109,6 +108,8 @@ export type {
   ThemeMode,
 } from './config';
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
+export type { DrainConfig, HealthConfig, ReadinessMode } from './config-health';
+export { READINESS_MODES } from './config-health';
 export type {
   PwaColors,
   PwaConfig,
@@ -508,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,
@@ -515,8 +522,6 @@ export type {
   LifecycleOptions,
   OnShutdownOptions,
   ProcessSignal,
-  ReadinessCheck,
-  ReadinessStatus,
   ShutdownHook,
   ShutdownPhase,
   ShutdownReason,
@@ -548,6 +553,7 @@ export {
   READINESS_GRACE_DEFAULT_MS,
   READINESS_GRACE_MAX_MS,
 } from './lifecycle-grace';
+export type { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
 export type { SignalHandlerOptions } from './lifecycle-signals';
 export { installSignalHandlers } from './lifecycle-signals';
 export { isSelfOrigin, listeningOrigins, markListening, resetListeners } from './listeners';

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/lifecycle-readiness.ts

@@ -0,0 +1,21 @@
+// Single responsibility: the readiness CHECK — its signature and its two answers. The mode that
+// decides what a failing one does to `/readyz` is `config-health.ts`'s.
+
+export type ReadinessStatus = 'ok' | 'failing';
+
+/**
+ * Synchronous, and that is the design, not a limitation. **Do not widen this to
+ * `() => Promise<boolean>`** — the signature is the mechanism.
+ *
+ * A readiness endpoint that does I/O is a liveness bomb. A probe that awaits a network call takes
+ * as long as the dependency does, so a slow database makes the endpoint miss its `timeoutSeconds`,
+ * the kubelet reads that as unready, and capacity is pulled from an already-struggling system —
+ * the outage the probe existed to prevent, caused by the probe. Worse under a liveness probe
+ * sharing the handler: the pod is killed and restarts into the same slow database, cold.
+ *
+ * So the owner of the dependency keeps a boolean fresh — a pool exposes `isOpen`, a background
+ * poller flips a flag on its own schedule with its own timeout — and this reads it. That puts the
+ * waiting where a timeout can be tuned, and leaves this path unable to block. A check that throws
+ * is `failing`.
+ */
+export type ReadinessCheck = () => boolean;

package/src/lifecycle.ts

@@ -3,11 +3,14 @@
 // and reports the same /healthz + /readyz state.
 
 import { type Clock, systemClock } from './clock';
+import type { ReadinessMode } from './config-health';
+import { assertReadinessMode } from './config-health';
 import { UltimateError } from './errors';
 import { finiteCount } from './finite-option';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
 import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
+import type { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
 import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
 export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
@@ -64,29 +67,12 @@ export interface LifecycleOptions {
    * A whole number from 0 to 60000; 0 is no grace.
    */
   readonly readinessGraceMs?: number | undefined;
+  /** What a failing check does to `/readyz` — see `ReadinessMode`. Default `'dependencies'`. */
+  readonly readiness?: ReadinessMode | undefined;
   readonly clock?: Clock | undefined;
   readonly logger?: Logger | undefined;
 }
 
-export type ReadinessStatus = 'ok' | 'failing';
-
-/**
- * Synchronous, and that is the design, not a limitation. **Do not widen this to
- * `() => Promise<boolean>`** — the signature is the mechanism.
- *
- * A readiness endpoint that does I/O is a liveness bomb. A probe that awaits a network call takes
- * as long as the dependency does, so a slow database makes the endpoint miss its `timeoutSeconds`,
- * the kubelet reads that as unready, and capacity is pulled from an already-struggling system —
- * the outage the probe existed to prevent, caused by the probe. Worse under a liveness probe
- * sharing the handler: the pod is killed and restarts into the same slow database, cold.
- *
- * So the owner of the dependency keeps a boolean fresh — a pool exposes `isOpen`, a background
- * poller flips a flag on its own schedule with its own timeout — and this reads it. That puts the
- * waiting where a timeout can be tuned, and leaves this path unable to block. A check that throws
- * is `failing`.
- */
-export type ReadinessCheck = () => boolean;
-
 export interface HealthReport {
   readonly state: HealthState;
   readonly ready: boolean;
@@ -123,6 +109,7 @@ const DEFAULT_DEADLINE_MS = 25_000;
 let deadlineMs = DEFAULT_DEADLINE_MS;
 /** `undefined` means "the environment's default", read when a drain starts, not at import. */
 let graceMs: number | undefined;
+let readinessMode: ReadinessMode = 'dependencies';
 let clock: Clock = systemClock;
 let log: Logger = rootLogger;
 let state: HealthState = 'starting';
@@ -155,6 +142,7 @@ export function configureLifecycle(options: LifecycleOptions): void {
     }
     graceMs = options.readinessGraceMs;
   }
+  if (options.readiness !== undefined) readinessMode = assertReadinessMode(options.readiness);
   if (options.clock !== undefined) {
     clock = options.clock;
     startedAtMono = clock.monotonic();
@@ -451,13 +439,15 @@ export function drain(signal = 'manual'): Promise<void> {
   return drainPromise;
 }
 
-export function healthReport(): HealthReport {
+export function healthReport(mode: ReadinessMode = readinessMode): HealthReport {
   const checks = readinessChecks();
+  const dependencies = Object.values(checks).every((status) => status === 'ok');
   return {
     state,
     // `ready` is the same predicate `/readyz` answers on, so a body and its status can never
     // disagree — a 200 whose body says `ready: false` is the bug this shares one source to avoid.
-    ready: state === 'ready' && Object.values(checks).every((status) => status === 'ok'),
+    // `'process'` mode leaves the checks OUT of it, and still reports every one of them below.
+    ready: state === 'ready' && (mode === 'process' || dependencies),
     uptimeMs: Math.round(clock.monotonic() - startedAtMono),
     inflight,
     buildId: process.env['BUILD_ID'] ?? 'dev',
@@ -477,9 +467,12 @@ export function healthzPayload(): HealthPayload {
   return { ok, status: ok ? 200 : 503, body };
 }
 
-/** Readiness: may this instance receive traffic? 503 while starting, draining or any check fails. */
-export function readyzPayload(): HealthPayload {
-  const body = healthReport();
+/**
+ * Readiness: may this instance receive traffic? 503 while starting or draining, and — in the
+ * default `'dependencies'` mode, or always with `deep` (`/readyz?deep=1`) — while any check fails.
+ */
+export function readyzPayload(options: { readonly deep?: boolean } = {}): HealthPayload {
+  const body = healthReport(options.deep === true ? 'dependencies' : readinessMode);
   return { ok: body.ready, status: body.ready ? 200 : 503, body };
 }
 
@@ -487,6 +480,7 @@ export function readyzPayload(): HealthPayload {
 export function resetLifecycle(): void {
   deadlineMs = DEFAULT_DEADLINE_MS;
   graceMs = undefined;
+  readinessMode = 'dependencies';
   clock = systemClock;
   log = rootLogger;
   state = 'starting';