@ultimat3/action 22.5.0 → 22.5.1

package/README.md

@@ -358,6 +358,16 @@ post-commit: a handler that took the money and then failed its own `output:` sch
 The reservation is settled as a FAILURE and the retry re-throws it under the first attempt's own
 code. Releasing it there is what made idempotency the cause of a double charge.
 
+**The stored payload fingerprint is keyed.** `requestHash` is `keyedFingerprint(input, …)` from
+`@ultimat3/core`: `h1:<key id>:<HMAC-SHA-256/128>` under a key derived from the app's signing
+secret (`ULTIMATE_CURSOR_SECRET` / `configureCursorSigning`), never a bare hash — the row lives a
+day, and an unkeyed hash of an input holding a short account or ID number is brute-forced offline
+from a table read. A row fingerprinted by a pre-22.5.1 build (16 bare hex characters) is still
+compared exactly until it ages out. A row keyed under a secret this process does not hold (a
+rotation inside the window) is answered on its status alone — replay, never re-run — and logs
+`action.idempotency.fingerprint-unverifiable`: a mismatched body under that key is not diagnosed
+for that window, and no honest retry gets a false 409.
+
 **Where the records live is declared, and refused at registration.** The default store is process
 memory — bounded, swept on a 24h window, and `scope: 'process'`. An app on more than one replica
 must say so and bring a store that can keep it, or the retry that lands on another replica finds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "22.5.0",
+  "version": "22.5.1",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -34,11 +34,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.5.0",
-    "@ultimat3/core": "22.5.0",
-    "@ultimat3/entity": "22.5.0",
-    "@ultimat3/http": "22.5.0",
-    "@ultimat3/policy": "22.5.0",
-    "@ultimat3/schema": "22.5.0"
+    "@ultimat3/cache": "22.5.1",
+    "@ultimat3/core": "22.5.1",
+    "@ultimat3/entity": "22.5.1",
+    "@ultimat3/http": "22.5.1",
+    "@ultimat3/policy": "22.5.1",
+    "@ultimat3/schema": "22.5.1"
   }
 }

package/src/idempotency.ts

@@ -4,7 +4,7 @@
  * a value or a failure — and a concurrent duplicate is refused rather than run twice, because a
  * double charge is worse than a 409.
  */
-import { fingerprint, isUltimateError, logger } from '@ultimat3/core';
+import { compareFingerprint, isUltimateError, keyedFingerprint, logger } from '@ultimat3/core';
 import {
   IdempotencyConflictError,
   IdempotencyNotSharedError,
@@ -57,7 +57,12 @@ export function isIdempotencyStatus(value: string): value is IdempotencyStatus {
 export interface IdempotencyRecord {
   readonly id: string;
   readonly key: string;
-  /** Fingerprint of the parsed input — a reused key with a new payload is a bug. */
+  /**
+   * KEYED fingerprint of the parsed input (`keyedFingerprint`, HMAC under the app's signing
+   * secret) — a reused key with a new payload is a bug. Never a bare hash: the record outlives the
+   * request by a day, and an unkeyed hash of an input holding a short account number is an
+   * offline oracle for that number to anyone who can read the table.
+   */
   readonly requestHash: string;
   readonly status: IdempotencyStatus;
   readonly value: unknown;
@@ -172,6 +177,9 @@ export function assertIdempotencyScope(
   if (store.scope !== 'shared') throw new IdempotencyNotSharedError(store.scope);
 }
 
+/** The `purpose` the request fingerprint is keyed under — one derived key, for this use only. */
+export const IDEMPOTENCY_FINGERPRINT_PURPOSE = 'action.idempotency.request';
+
 export interface IdempotentOutcome<T> {
   readonly value: T;
   readonly replayed: boolean;
@@ -196,11 +204,9 @@ export async function withIdempotency<T>(
   input: unknown,
   run: () => Promise<T>,
 ): Promise<IdempotentOutcome<T>> {
-  const requestHash = fingerprint(input);
+  const requestHash = keyedFingerprint(input, IDEMPOTENCY_FINGERPRINT_PURPOSE);
   const { record, created } = await store.reserve(key, requestHash);
-  if (record.requestHash !== requestHash) {
-    throw new IdempotencyConflictError(key, 'payload-mismatch');
-  }
+  if (record.requestHash !== requestHash) assertSamePayload(key, record.requestHash, input);
   if (!created) {
     if (record.status === 'in-flight') throw new IdempotencyConflictError(key, 'in-flight');
     if (record.status === 'failed') throw new IdempotencyReplayedFailureError(key, record.failure);
@@ -224,6 +230,21 @@ export async function withIdempotency<T>(
   return { value, replayed: false };
 }
 
+/**
+ * A stored fingerprint that is not this request's exact string. A legacy unkeyed one (a row
+ * written before keying) is still checked exactly. One keyed under a secret this process does not
+ * hold — the signing secret rotated inside the window — cannot be checked either way, and is
+ * answered by its STATUS alone: replay, never re-run. Refusing it would 409 every honest retry
+ * across a rotation; running it would be the double charge. What is lost for that window only is
+ * the "same key, different body" diagnosis, and a warning says so.
+ */
+function assertSamePayload(key: string, stored: string, input: unknown): void {
+  const verdict = compareFingerprint(stored, input, IDEMPOTENCY_FINGERPRINT_PURPOSE);
+  if (verdict === 'mismatch') throw new IdempotencyConflictError(key, 'payload-mismatch');
+  if (verdict === 'unverifiable')
+    logger.warn('action.idempotency.fingerprint-unverifiable', { key });
+}
+
 /**
  * Record the failure, and never let recording it replace the failure itself. A store that refuses
  * here would otherwise surface as the caller's error, hiding the `X_OUTPUT_INVALID` or the