@agentsbloom/sdk 0.4.0 → 0.5.0

package/lib/shared-store.js

@@ -1,172 +1,298 @@
-/**
- * Shared replay-cache store for multi-instance deployments.
- *
- * The mandate-jti and signature-nonce replay caches were in-memory Maps:
- * correct per process, but a second instance (or a restart mid-attack)
- * forgets every consumed nonce, so a captured mandate/signature replays
- * cleanly against the other instance. When an Upstash Redis REST endpoint
- * is configured (UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN), the
- * caches become cluster-wide through plain fetch - no new dependency.
- *
- * Semantics (deliberately conservative):
- *   - Reads check the local Map first, then the shared store.
- *   - Writes go to both; shared writes are fire-and-forget with TTL, and
- *     shared-store OUTAGES degrade to local-only behavior (logged once)
- *     rather than failing requests - same fail-open-with-logging posture
- *     as the rest of the bookkeeping.
- *   - `has()` returns a boolean in local-only mode and a Promise<boolean>
- *     when the shared store is configured. Callers must treat it as
- *     maybe-async (`const hit = await has(k)` works for both).
- */
-
-const UPSTASH_URL = () => process.env.UPSTASH_REDIS_REST_URL || '';
-const UPSTASH_TOKEN = () => process.env.UPSTASH_REDIS_REST_TOKEN || '';
-
-export function isSharedStoreConfigured() {
-  return Boolean(UPSTASH_URL() && UPSTASH_TOKEN());
-}
-
-let outageLogged = false;
-
-async function sharedRequest(path, body) {
-  try {
-    const res = await fetch(`${UPSTASH_URL().replace(/\/$/, '')}${path}`, {
-      method: body === undefined ? 'GET' : 'POST',
-      headers: { Authorization: `Bearer ${UPSTASH_TOKEN()}` },
-      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-      signal: AbortSignal.timeout(3000),
-    });
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    return await res.json();
-  } catch (err) {
-    if (!outageLogged) {
-      console.warn(`🌸 AgentsBloom: shared replay store unreachable (${err.message}); replay protection is local-only for this instance.`);
-      outageLogged = true;
-    }
-    return null;
-  }
-}
-/** Returns the parsed value or null. Never throws. */
-export async function sharedGetJSON(key) {
-  if (!isSharedStoreConfigured()) return null;
-  const result = await sharedRequest(`/get/${encodeURIComponent(key)}`);
-  const value = result?.result;
-  return value === null || value === undefined ? null : JSON.parse(value);
-}
-
-/** Fire-and-forget set with TTL seconds. Never throws. */
-export async function sharedSetJSON(key, value, ttlSec) {
-  if (!isSharedStoreConfigured()) return;
-  await sharedRequest(`/set/${encodeURIComponent(key)}?EX=${Math.max(1, Math.floor(ttlSec))}`, value);
-}
-
-/**
- * A bounded local Map + optional shared-store write-through, exposing a
- * replay-cache interface: `has(key) -> boolean | Promise<boolean>` and
- * `set(key, expiresAtMs) -> void`.
- *
- * @param {string} namespace - key prefix in the shared store
- * @param {number} maxLocalSize - bound for the in-memory Map
- */
-export function createReplayCache(namespace, maxLocalSize = 50_000) {
-  const local = new Map(); // key -> expiresAtMs
-
-  const evict = (now) => {
-    for (const [key, expiresAtMs] of local) {
-      if (expiresAtMs < now) local.delete(key);
-    }
-  };
-
-  return {
-    /** Local-first; falls through to the shared store when configured. */
-    has(key) {
-      const now = Date.now();
-      const expiresAtMs = local.get(key);
-      if (expiresAtMs !== undefined) {
-        if (expiresAtMs >= now) return true;
-        local.delete(key);
-      }
-      if (!isSharedStoreConfigured()) {
-        // Bounded like the previous plain-Map implementation.
-        if (local.size >= maxLocalSize) {
-          evict(now);
-          if (local.size >= maxLocalSize) return false;
-        }
-        return false;
-      }
-      return sharedGetJSON(`${namespace}:${key}`).then((value) => value !== null);
-    },
-
-    /** Write-through; the shared write is fire-and-forget. */
-    set(key, expiresAtMs) {
-      if (local.size >= maxLocalSize) {
-        evict(Date.now());
-        if (local.size >= maxLocalSize) return; // refuse rather than grow unbounded
-      }
-      local.set(key, expiresAtMs);
-      if (isSharedStoreConfigured()) {
-        const ttlSec = Math.max(1, Math.ceil((expiresAtMs - Date.now()) / 1000));
-        sharedSetJSON(`${namespace}:${key}`, { e: expiresAtMs }, ttlSec);
-      }
-    },
-
-    /**
-     * v4: ATOMIC check-and-set for replay protection.
-     *
-     * The previous has()-then-set() sequence had a race window: two
-     * concurrent identical requests could both observe "not seen" before
-     * either recorded the nonce/jti, letting a captured signed request or
-     * mandate replay in parallel. claim() is a single atomic operation:
-     * locally it is a synchronous Map check-and-set; against the shared
-     * store it uses SET NX EX (set-if-not-exists), so only one of N
-     * concurrent claims across ALL instances wins.
-     *
-     * Returns true when this caller won the key (first use), false when
-     * the key was already claimed (replay). Returns a Promise<boolean>
-     * when a shared store is configured. If the shared store is
-     * unreachable, degrades to the local-only decision (same fail-open
-     * posture as the rest of the bookkeeping - documented).
-     */
-    claim(key, expiresAtMs) {
-      const now = Date.now();
-      const expiresAt = local.get(key);
-      if (expiresAt !== undefined && expiresAt >= now) return false;
-      local.delete(key);
-
-      const claimLocally = () => {
-        if (local.size >= maxLocalSize) {
-          evict(Date.now());
-          if (local.size >= maxLocalSize) {
-            // Cannot track locally; treat as claimed-but-untracked so we
-            // never fail OPEN on capacity pressure.
-            return true;
-          }
-        }
-        local.set(key, expiresAtMs);
-        return true;
-      };
-
-      if (!isSharedStoreConfigured()) {
-        return claimLocally();
-      }
-
-      const ttlSec = Math.max(1, Math.ceil((expiresAtMs - now) / 1000));
-      return sharedRequest(`/set/${encodeURIComponent(`${namespace}:${key}`)}?NX&EX=${ttlSec}`, { e: expiresAtMs })
-        .then((result) => {
-          // Upstash SET NX returns { result: 'OK' } when the key was set,
-          // { result: null } when it already existed, and null on outage.
-          if (result === null) return claimLocally(); // outage: degrade to local
-          if (result?.result === 'OK') {
-            local.set(key, expiresAtMs);
-            return true;
-          }
-          return false;
-        });
-    },
-
-    /** Test hook. */
-    clear() {
-      local.clear();
-    },
-  };
-}
+/**
+ * Shared replay-cache store for multi-instance deployments.
+ *
+ * The mandate-jti and signature-nonce replay caches are in-memory Maps:
+ * correct per process, but a second instance (or a restart mid-attack)
+ * forgets every consumed nonce, so a captured mandate/signature replays
+ * cleanly against the other instance. When an Upstash Redis REST endpoint is
+ * configured (UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN) the caches
+ * become cluster-wide through plain `fetch` — no new dependency.
+ *
+ * ---------------------------------------------------------------------------
+ * Fail-closed by default (changed)
+ * ---------------------------------------------------------------------------
+ *
+ * This module used to swallow every shared-store error and silently fall back
+ * to the local Map. For a replay cache that guards payment authorization,
+ * "the coordination layer is down, so let it through" is the wrong default:
+ * an attacker who can degrade the store (or simply wait for an Upstash
+ * incident) gets cluster-wide replay for free, and the operator finds out
+ * from a single `console.warn` emitted once per process lifetime.
+ *
+ * So: when a shared store is CONFIGURED but unreachable, `claim()` now
+ * returns false — the request is rejected as if the key were already claimed.
+ * Operators who prefer availability over replay protection can opt out with
+ * `AGENTSBLOOM_REPLAY_FAIL_OPEN=true`, which is loud about itself.
+ *
+ * When no shared store is configured at all, behavior is unchanged
+ * (local-only, bounded), because there is nothing to fail closed against.
+ *
+ * ---------------------------------------------------------------------------
+ * Semantics
+ * ---------------------------------------------------------------------------
+ *   - `claim(key, expiresAtMs)` is the primitive: an atomic check-and-set.
+ *     Locally it is a synchronous Map operation; against Upstash it is
+ *     `SET key value NX EX ttl`, so exactly one of N concurrent claimers
+ *     across ALL instances wins. Returns `boolean` in local-only mode and
+ *     `Promise<boolean>` when a shared store is configured — callers must
+ *     treat it as maybe-async (`await` works for both).
+ *   - `has(key)` is advisory only. Never gate a decision on it; use `claim`.
+ */
+
+import crypto from 'crypto';
+
+const UPSTASH_URL = () => process.env.UPSTASH_REDIS_REST_URL || '';
+const UPSTASH_TOKEN = () => process.env.UPSTASH_REDIS_REST_TOKEN || '';
+
+/** Redis rejects very long keys and they bloat memory; hash beyond this. */
+const MAX_RAW_KEY_LENGTH = 320;
+const SHARED_REQUEST_TIMEOUT_MS = 3000;
+/** Re-log a shared-store outage at most this often (was: once per process). */
+const OUTAGE_LOG_INTERVAL_MS = 60 * 1000;
+
+export function isSharedStoreConfigured() {
+  return Boolean(UPSTASH_URL() && UPSTASH_TOKEN());
+}
+
+/**
+ * True when the operator has explicitly chosen availability over replay
+ * protection during a shared-store outage.
+ */
+export function isReplayFailOpenEnabled() {
+  return String(process.env.AGENTSBLOOM_REPLAY_FAIL_OPEN || '').toLowerCase() === 'true';
+}
+
+let lastOutageLogMs = 0;
+let outageCount = 0;
+
+function logOutage(message) {
+  outageCount += 1;
+  const now = Date.now();
+  if (now - lastOutageLogMs < OUTAGE_LOG_INTERVAL_MS) return;
+  lastOutageLogMs = now;
+  const posture = isReplayFailOpenEnabled()
+    ? 'AGENTSBLOOM_REPLAY_FAIL_OPEN=true, so replay protection is LOCAL-ONLY for this instance'
+    : 'replay-protected requests are being REJECTED until it recovers (set AGENTSBLOOM_REPLAY_FAIL_OPEN=true to trade replay protection for availability)';
+  console.error(
+    `🌸 AgentsBloom: shared replay store unreachable (${message}); ${posture}. `
+    + `Failures since start: ${outageCount}.`,
+  );
+}
+
+/** Test/diagnostic hook. */
+export function sharedStoreOutageCount() {
+  return outageCount;
+}
+
+/** Test hook: resets outage bookkeeping. */
+export function resetSharedStoreDiagnostics() {
+  outageCount = 0;
+  lastOutageLogMs = 0;
+}
+
+/**
+ * Bounds a cache key so an attacker-supplied identifier (a multi-megabyte
+ * `jti`, say) cannot become a multi-megabyte Redis key.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+function boundKey(key) {
+  const text = String(key);
+  if (text.length <= MAX_RAW_KEY_LENGTH) return text;
+  return `h:${crypto.createHash('sha256').update(text).digest('base64url')}`;
+}
+
+/**
+ * Performs one Upstash REST call.
+ *
+ * @returns {Promise<{ ok: true, body: unknown } | { ok: false, error: string }>}
+ */
+async function sharedRequest(path, body) {
+  try {
+    const response = await fetch(`${UPSTASH_URL().replace(/\/$/, '')}${path}`, {
+      method: body === undefined ? 'GET' : 'POST',
+      headers: {
+        Authorization: `Bearer ${UPSTASH_TOKEN()}`,
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      redirect: 'error',
+      signal: AbortSignal.timeout(SHARED_REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      const error = `HTTP ${response.status}`;
+      logOutage(error);
+      return { ok: false, error };
+    }
+    return { ok: true, body: await response.json() };
+  } catch (err) {
+    const error = err?.message || String(err);
+    logOutage(error);
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Reads a JSON value from the shared store.
+ *
+ * @returns {Promise<{ ok: boolean, value: unknown }>} `ok:false` signals an
+ *   outage so callers can distinguish "absent" from "unknown".
+ */
+export async function sharedGetJSON(key) {
+  if (!isSharedStoreConfigured()) return { ok: true, value: null };
+  const result = await sharedRequest(`/get/${encodeURIComponent(boundKey(key))}`);
+  if (!result.ok) return { ok: false, value: null };
+  const raw = result.body?.result;
+  if (raw === null || raw === undefined) return { ok: true, value: null };
+  try {
+    // Previously this JSON.parse sat OUTSIDE the error handling, so one
+    // malformed stored value threw an unhandled rejection out of has().
+    return { ok: true, value: JSON.parse(raw) };
+  } catch {
+    return { ok: true, value: null };
+  }
+}
+
+/**
+ * Writes a JSON value with a TTL. Best effort; reports whether it landed.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function sharedSetJSON(key, value, ttlSec) {
+  if (!isSharedStoreConfigured()) return false;
+  const ttl = Math.max(1, Math.floor(ttlSec));
+  const result = await sharedRequest(
+    `/set/${encodeURIComponent(boundKey(key))}?EX=${ttl}`,
+    value,
+  );
+  return result.ok;
+}
+
+/**
+ * A bounded local Map plus optional cluster-wide coordination, exposing a
+ * replay-cache interface.
+ *
+ * @param {string} namespace - key prefix in the shared store
+ * @param {number} [maxLocalSize] - bound for the in-memory Map
+ */
+export function createReplayCache(namespace, maxLocalSize = 50_000) {
+  /** @type {Map<string, number>} key -> expiresAtMs */
+  const local = new Map();
+  let capacityEvictions = 0;
+  let sharedFailures = 0;
+
+  const sweep = (now) => {
+    for (const [key, expiresAtMs] of local) {
+      if (expiresAtMs < now) local.delete(key);
+    }
+  };
+
+  /**
+   * Records a key locally, evicting the oldest-inserted entry if the map is
+   * full. TTLs are uniform in practice, so oldest-inserted is also nearest to
+   * expiry — the least-bad choice. The counter exists so an operator can see
+   * that they are running against the bound.
+   */
+  const recordLocally = (key, expiresAtMs) => {
+    if (local.size >= maxLocalSize) {
+      sweep(Date.now());
+      if (local.size >= maxLocalSize) {
+        const oldest = local.keys().next().value;
+        if (oldest !== undefined) {
+          local.delete(oldest);
+          capacityEvictions += 1;
+        }
+      }
+    }
+    local.set(key, expiresAtMs);
+  };
+
+  return {
+    /**
+     * Advisory presence check. Prefer `claim()` for anything that gates a
+     * decision: `has()` cannot be atomic across instances.
+     */
+    has(key) {
+      const now = Date.now();
+      const expiresAtMs = local.get(key);
+      if (expiresAtMs !== undefined) {
+        if (expiresAtMs >= now) return true;
+        local.delete(key);
+      }
+      if (!isSharedStoreConfigured()) return false;
+      return sharedGetJSON(`${namespace}:${key}`).then((result) => result.value !== null);
+    },
+
+    /** Write-through record. Prefer `claim()`. */
+    set(key, expiresAtMs) {
+      recordLocally(key, expiresAtMs);
+      if (isSharedStoreConfigured()) {
+        const ttlSec = Math.max(1, Math.ceil((expiresAtMs - Date.now()) / 1000));
+        void sharedSetJSON(`${namespace}:${key}`, { e: expiresAtMs }, ttlSec);
+      }
+    },
+
+    /**
+     * Atomic check-and-set. Returns true when this caller won the key (first
+     * use), false when it was already claimed (replay) OR when a configured
+     * shared store could not be reached and fail-open is not enabled.
+     *
+     * @param {string} key
+     * @param {number} expiresAtMs - absolute time the record may be dropped
+     * @returns {boolean|Promise<boolean>}
+     */
+    claim(key, expiresAtMs) {
+      const now = Date.now();
+      const existing = local.get(key);
+      if (existing !== undefined && existing >= now) return false;
+      local.delete(key);
+
+      if (!isSharedStoreConfigured()) {
+        recordLocally(key, expiresAtMs);
+        return true;
+      }
+
+      const ttlSec = Math.max(1, Math.ceil((expiresAtMs - now) / 1000));
+      const sharedKey = boundKey(`${namespace}:${key}`);
+      return sharedRequest(`/set/${encodeURIComponent(sharedKey)}?NX&EX=${ttlSec}`, { e: expiresAtMs })
+        .then((result) => {
+          if (!result.ok) {
+            sharedFailures += 1;
+            if (isReplayFailOpenEnabled()) {
+              // Explicit operator choice: degrade to per-instance protection.
+              recordLocally(key, expiresAtMs);
+              return true;
+            }
+            // Fail closed. A replay cache that cannot coordinate must not
+            // hand out authorizations it can no longer deduplicate.
+            return false;
+          }
+          // Upstash SET NX returns { result: 'OK' } when the key was set and
+          // { result: null } when it already existed.
+          if (result.body?.result === 'OK') {
+            recordLocally(key, expiresAtMs);
+            return true;
+          }
+          return false;
+        });
+    },
+
+    /** Clears LOCAL state only; consumed keys remain in the shared store. */
+    clear() {
+      local.clear();
+    },
+
+    /** Diagnostics for tests and operators. */
+    stats() {
+      return {
+        localSize: local.size,
+        maxLocalSize,
+        capacityEvictions,
+        sharedFailures,
+        shared: isSharedStoreConfigured(),
+        failOpen: isReplayFailOpenEnabled(),
+      };
+    },
+  };
+}