@cross-deck/node 1.1.1 → 1.3.1

package/CHANGELOG.md

@@ -4,6 +4,146 @@ All notable changes to `@cross-deck/node` will be documented here. The
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] — 2026-05-24
+
+Patch fix for the 1.3.0 dist-load contract. Mirrors the
+`@cross-deck/web@1.3.1` patch — `SDK_VERSION` is now sourced from a
+generated `src/_version.ts` file (produced by
+`scripts/sync-sdk-versions.mjs` from `package.json`) instead of a
+runtime `import { version } from "../package.json"` that needs a
+`with { type: "json" }` assertion to load as ESM. Wire contract is
+unchanged. 1.3.0 was never published to npm; 1.3.1 is the first
+1.3.x line to reach npm.
+
+## [1.3.0] — 2026-05-24
+
+KPMG bank-grade audit closure. Six review batches landed five SDK PRs
+and a backend wiring fix that closes every P0 plus 12 of 13 P1 findings.
+No public method renames; one internal contract change
+(`ErrorTracker.beforeSend` is now a getter) that also removes the
+`Object.defineProperty` workaround the node SDK shipped to compensate
+for the same broken contract on web. Behavioural changes to the queue
+and the PII scrub strictly improve correctness. The wire
+`Crossdeck-Sdk-Version` header now reads from `package.json` so it
+cannot drift from the published bundle.
+
+### Fixed (P0)
+
+- **PII scrub sentinel tokens aligned with the backend.** `[email]` /
+  `[card]` → `<email>` / `<card>`, matching `backend/src/api/lib/scrub.ts`.
+  The same event scrubbed by SDK + backend now carries the same
+  sentinel — dashboard aggregation works again.
+- **`setErrorBeforeSend` contract cleaned up.** The
+  `ErrorTracker.beforeSend` field is now a getter
+  (`() => fn | null`). Removed the `Object.defineProperty` hack on
+  `tracker.opts` that worked around the old captured-by-value bug —
+  cleaner contract, lockstep with web.
+- **Event queue drops 4xx batches.** Pre-fix every `catch` triggered
+  `scheduleRetry` with the same `Idempotency-Key`. A 401 (key revoked),
+  400/422 (malformed batch), 403 (permission), 404 (wrong baseUrl)
+  spun the retry timer indefinitely while the backlog grew silently.
+  New `isPermanent4xx()` helper hard-stops on any 4xx EXCEPT 408 / 429
+  (transient by spec). On permanent failure: drop the batch, increment
+  `dropped`, fire `onPermanentFailure(info)`, emit
+  `queue.permanent_failure` on the EventEmitter, log via
+  `console.error` regardless of debug mode.
+- **Error-capture self-skip derived from `baseUrl`.** Pre-fix hardcoded
+  to `api.cross-deck.com`; customers on staging / regional / self-hosted
+  base URLs recursed (5xx → captureHttp → enqueue → /events →
+  captureHttp → ∞). Now strict-hostname compare against `selfHostname`
+  extracted from constructor `baseUrl`. Closes the substring-match
+  bypass (`api.cross-deck.com.attacker.example` would have matched).
+
+### Added
+
+- **`onPermanentFailure` callback** on `EventQueueConfig`, surfaced
+  via `CrossdeckServer.on("queue.permanent_failure", …)` for host-app
+  paging.
+- **`sdk.flush_permanent_failure` debug signal** in the
+  `DebugSignal` vocabulary.
+
+### Changed
+
+- **`SDK_VERSION` is now imported from `package.json`.** The
+  `Crossdeck-Sdk-Version` header always matches the published bundle.
+  Single source of truth.
+- **Event ingest envelope now ships `environment`.** Pre-fix web sent
+  it and node didn't; backend `v1-events.ts` cross-checks it against
+  the API-key-derived env and rejects mismatches loudly
+  (`env_mismatch`). Defence-in-depth so a "live key, env: sandbox"
+  misconfig fails fast instead of polluting the wrong dashboard.
+- **`syncPurchases` body spread bug.** Pre-fix
+  `{ rail: input.rail ?? "apple", ...input }` — the `...input` ran
+  LAST and overrode the default when the caller passed
+  `rail: undefined` explicitly. Reversed: `{ ...input, rail }`.
+- **PII scrub regex uses `.replace()` unconditionally.** Dropped the
+  `.test()`-gating that carried `lastIndex` state between calls.
+- **`bootHeartbeat: false` no longer silences the
+  `sdk.no_durable_store` warning.** Pre-fix the warning lived inside
+  `emitBootTelemetry()` which sat inside the `bootHeartbeat` gate, so
+  the opt-out silenced the entire reason `entitlementStore` exists.
+  Split into two methods: `emitDurabilityWarning()` (local-only,
+  unconditional) and `emitBootTelemetryEvent()` (phone-home, still
+  gated).
+- **`isEntitled(string)` requires the `cdcust_` prefix** for canonical-
+  path resolution. Pre-fix any string with a cache entry resolved
+  through the canonical path — a small cross-tenant primitive if a
+  tenant's userId collided with another tenant's `crossdeckCustomerId`.
+  Non-prefixed strings now drop to alias lookup only.
+- **Self-skip applies to breadcrumbs too**, not just `captureHttp`.
+  Error reports no longer carry noisy `POST https://api.cross-deck.com/v1/events`
+  crumb entries.
+
+### Wiring (backend, paired)
+
+- **`v1-events` ingest now honours the per-project `piiAllowList`.**
+  The admin management surface (`v1-pii-allow-list.ts`) was persisted +
+  audit-logged but the hot ingest path never read it. The new
+  `backend/src/api/lib/pii-allow-list-cache.ts` (60s TTL,
+  single-flight) feeds the project's allow-list to `scrubProperties()`
+  on every batch. `HARD_LOCKED_PATTERNS` are always stripped from the
+  effective list regardless of what's in storage. (Backend-only —
+  listed here so server-SDK consumers know defence-in-depth is fully
+  closed.)
+
+## [1.2.0] — 2026-05-18
+
+### Added
+
+- **Pluggable durable entitlement store (`entitlementStore`).** A new
+  constructor option taking an async `EntitlementStore` (a `load` /
+  `save` pair) — back it with Redis, your own database, or a KV. Every
+  successful `getEntitlements()` persists the result to it, and on a
+  network failure the SDK falls back to the stored snapshot. This is
+  what gives serverless deployments (Cloud Run / Lambda) cold-start
+  durability that an in-memory cache alone cannot. `EntitlementStore`
+  and `StoredEntitlements` are exported.
+- **Staleness fields in `diagnostics()`.** `entitlements.staleCustomers`,
+  `isStale`, `durableStore`, and `coldStartDurable` — so serving
+  last-known-good through a Crossdeck outage is observable, not silent.
+- **`sdk.no_durable_store` debug signal**, emitted once on a serverless
+  runtime with no `entitlementStore` configured, alongside a
+  `durability` fact on the boot telemetry event — so the cold-start gap
+  is measurable rather than a surprise in production.
+
+### Changed
+
+- **The entitlement cache is now durable last-known-good.**
+  `isEntitled()` and `list()` no longer expire to `false` / `[]` when
+  `entitlementCacheTtlMs` elapses — they keep serving the last
+  successfully-fetched entitlements. The TTL is now a refresh hint, not
+  an invalidation. Each entitlement is still honoured against its own
+  `validUntil`. A brief Crossdeck outage can no longer fail a paying
+  customer down to free 60 seconds after a warm.
+
+## [1.1.1] — 2026-05-14
+
+### Changed
+
+- Ported the "never silently surface an `Unknown` error" hardening to
+  `@cross-deck/node` — a captured error with no usable type or message
+  is now labelled precisely instead of collapsing to `Unknown error`.
+
 ## [1.1.0] — 2026-05-13
 
 ### Added

package/dist/auto-events/index.d.mts

@@ -1,4 +1,4 @@
-import { p as CrossdeckServer } from '../crossdeck-server-BXQaFjVx.mjs';
+import { p as CrossdeckServer } from '../crossdeck-server-DhnHvUhh.mjs';
 import 'node:events';
 
 /**

package/dist/auto-events/index.d.ts

@@ -1,4 +1,4 @@
-import { p as CrossdeckServer } from '../crossdeck-server-BXQaFjVx.js';
+import { p as CrossdeckServer } from '../crossdeck-server-DhnHvUhh.js';
 import 'node:events';
 
 /**

package/dist/{crossdeck-server-BXQaFjVx.d.mts → crossdeck-server-DhnHvUhh.d.mts}

@@ -221,6 +221,22 @@ interface RuntimeInfo {
     platformRelease: string;
     hostname: string;
     host: RuntimeHost;
+    /**
+     * Whether the host is a scale-to-zero / per-request-instance platform
+     * where a cold start begins with empty process memory.
+     *
+     * `true` for FaaS + serverless-container platforms (Lambda, Cloud
+     * Run, Firebase Functions v1/v2, Vercel, Netlify, Azure Functions,
+     * App Engine). `false` for long-lived process hosts (Heroku, Render,
+     * Railway, Fly, Kubernetes, plain Node) where the process — and thus
+     * the in-memory entitlement cache — persists across requests.
+     *
+     * The entitlement-cache durability layer reads this: a serverless
+     * host with no `entitlementStore` has no cold-start durability, and
+     * the SDK surfaces that explicitly (debug warning + a `durability`
+     * fact on the boot telemetry event).
+     */
+    isServerless: boolean;
     region: string | null;
     serviceName: string | null;
     serviceVersion: string | null;
@@ -235,8 +251,6 @@ interface RuntimeInfo {
     appVersion: string | null;
 }
 
-declare const SDK_NAME = "@cross-deck/node";
-declare const SDK_VERSION = "1.1.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 declare const DEFAULT_TIMEOUT_MS = 15000;
 /**
@@ -310,6 +324,63 @@ interface EntitlementsListResponse {
     crossdeckCustomerId: string;
     env: Environment;
 }
+/**
+ * Snapshot of one customer's last-known-good entitlements, as written
+ * to / read from a durable `EntitlementStore`. Versioned for forward-
+ * compat — a future SDK can refuse a blob whose `v` it doesn't know.
+ *
+ * Carries enough to fully reconstruct an `EntitlementsListResponse` on
+ * a cold start (the durable read path in `getEntitlements()` rebuilds
+ * the response from this), plus `savedAt` so staleness is measurable
+ * after a process restart.
+ */
+interface StoredEntitlements {
+    v: 1;
+    /** Canonical Crossdeck customer ID this snapshot belongs to. */
+    crossdeckCustomerId: string;
+    /** The entitlement set exactly as the server last returned it. */
+    entitlements: PublicEntitlement[];
+    env: Environment;
+    /** Epoch ms of the successful server fetch that produced this snapshot. */
+    savedAt: number;
+}
+/**
+ * Pluggable async durable store for last-known-good entitlements.
+ *
+ * The Node SDK's entitlement cache is an in-memory per-customer `Map`.
+ * On serverless (Cloud Run / AWS Lambda) a cold start is an empty Map,
+ * and a brief Crossdeck outage during that window would otherwise read
+ * a paying customer as un-entitled. An `EntitlementStore` is the
+ * developer-supplied durability layer — Redis, their primary DB, a KV —
+ * that survives both a cold start and an outage.
+ *
+ * Contract:
+ *   - `load` returns the most recent snapshot for a customer, or `null`
+ *     if none exists. It MUST NOT throw for a missing key — return
+ *     `null`. (The SDK additionally guards every call in a try/catch,
+ *     but a well-behaved store returns `null`.)
+ *   - `save` persists a snapshot. Called only after a SUCCESSFUL server
+ *     fetch, so the store never holds anything but server-confirmed
+ *     truth.
+ *   - Both are awaited inside `getEntitlements()` (already async). They
+ *     are NEVER called from the synchronous `isEntitled()` — that stays
+ *     a pure in-memory `Map` read with zero I/O.
+ *   - The SDK swallows store errors: a failed `save` never fails a
+ *     successful fetch, a failed `load` degrades to "no durable copy".
+ *     A broken store weakens durability; it never breaks the SDK.
+ *
+ * The `key` passed to `load` / `save` is whatever identity string the
+ * caller used — a canonical `crossdeckCustomerId`, or a developer
+ * `userId` / `anonymousId` hint. The SDK saves a snapshot under every
+ * identity it knows for a customer so a cold-start `load` succeeds even
+ * before the in-memory alias map is populated.
+ */
+interface EntitlementStore {
+    /** Resolve a customer's last-known-good snapshot, or `null` if none. */
+    load(key: string): Promise<StoredEntitlements | null>;
+    /** Persist a customer's last-known-good snapshot. */
+    save(key: string, value: StoredEntitlements): Promise<void>;
+}
 interface AliasResult {
     object: "alias_result";
     crossdeckCustomerId: string;
@@ -462,8 +533,46 @@ interface CrossdeckServerOptions {
      *
      * Pass `0` to disable caching (every `isEntitled` requires a fresh
      * `getEntitlements()` call to populate the cache — useful for tests).
+     *
+     * NOTE: the TTL is a REFRESH HINT, not an invalidation. Once a
+     * customer is warm, `isEntitled()` keeps serving last-known-good past
+     * the TTL — a brief Crossdeck outage can never flip a paying customer
+     * to `false`. The TTL only tells `needsRefresh()` when a re-fetch is
+     * due, and (with no failed refresh) when the cache is flagged stale.
+     * Each entitlement's own `validUntil` is still honoured at read time.
      */
     entitlementCacheTtlMs?: number;
+    /**
+     * Age (ms) past which last-known-good entitlement data is flagged
+     * STALE in `diagnostics()` even with no failed refresh. Default 24h.
+     *
+     * Staleness never changes what `isEntitled()` returns — the cache
+     * keeps serving last-known-good. This window only makes "we have been
+     * serving an un-refreshed answer for a long time" observable, so an
+     * event-based revoke (chargeback / refund — which has no `validUntil`)
+     * riding out a long outage is visible instead of silent.
+     */
+    entitlementStaleAfterMs?: number;
+    /**
+     * Durable last-known-good store for entitlements. Optional.
+     *
+     * The entitlement cache is in-memory. On serverless (Cloud Run /
+     * Lambda) every cold start begins with an empty cache — and if
+     * Crossdeck is briefly unreachable during that window, a paying
+     * customer would read as un-entitled. Wiring an `EntitlementStore`
+     * (Redis / your DB / a KV) closes that gap: every successful
+     * `getEntitlements()` persists the result, and a network failure
+     * falls back to the stored snapshot instead of throwing.
+     *
+     * Without a store on a serverless host the SDK has NO cold-start
+     * durability — that is unavoidable and the SDK says so explicitly
+     * (a `debug.emit` warning plus a `durability` fact on the boot
+     * telemetry event). It is not hidden.
+     *
+     * `isEntitled()` stays synchronous regardless — the store is only
+     * ever touched from the already-async `getEntitlements()`.
+     */
+    entitlementStore?: EntitlementStore;
     /**
      * Service name for runtime enrichment. Attached to every event + error
      * as `properties.serviceName`. Default: env-detected via
@@ -674,6 +783,32 @@ interface Diagnostics {
         ttlMs: number;
         /** Cumulative count of listener invocations that threw. Swallowed inside the cache; surfaced here. */
         listenerErrors: number;
+        /**
+         * Number of cached customers currently flagged STALE — their most
+         * recent refresh attempt failed, or their data has aged past
+         * `entitlementStaleAfterMs`. The cache keeps serving last-known-good
+         * for them; this count makes "serving through an outage" observable.
+         */
+        staleCustomers: number;
+        /**
+         * Whether ANY cached customer is stale. Quick boolean for health
+         * checks / alerting without inspecting `staleCustomers`.
+         */
+        isStale: boolean;
+        /**
+         * Most recent failed-refresh timestamp across all customers (epoch
+         * ms), or 0 if every customer's last refresh succeeded.
+         */
+        lastRefreshFailedAt: number;
+        /**
+         * Durable-store posture. `durableStore` is true iff an
+         * `EntitlementStore` is configured. `coldStartDurable` is true iff
+         * the SDK has cold-start durability — which on a serverless host
+         * requires a store, and on a long-lived host is inherently true
+         * (the process, hence the in-memory cache, survives).
+         */
+        durableStore: boolean;
+        coldStartDurable: boolean;
     };
     events: {
         buffered: number;
@@ -844,8 +979,8 @@ interface GroupMembership {
 }
 
 /**
- * Per-customer entitlement cache with TTL — the third Crossdeck USP
- * on the server.
+ * Per-customer durable last-known-good entitlement cache — the third
+ * Crossdeck USP on the server.
  *
  * Why this exists: server-side gating code looks like
  *
@@ -856,29 +991,68 @@ interface GroupMembership {
  * per request, every request, for every customer. The cache makes
  * `isEntitled()` a `Map.get()` after the first warm.
  *
- * Differences from `@cross-deck/web/src/entitlement-cache.ts`:
+ * Durability contract (mirrors `@cross-deck/web/src/entitlement-cache.ts`,
+ * adapted for a multi-tenant server):
+ *   - This cache is NOT a second source of truth. Crossdeck remains the
+ *     only source; this is the SDK's local copy of what the server last
+ *     told us — a cache that does not forget during a network partition.
+ *   - Only a SUCCESSFUL fetch replaces a customer's entry (via
+ *     `setForCustomer`). A failed refresh never reaches it, so an outage
+ *     can never fail a paying customer down to free.
+ *   - **The TTL is a REFRESH HINT, not an invalidation.** `isEntitled()`
+ *     and `list()` keep serving last-known-good after `ttlMs` elapses —
+ *     they do NOT return `false` / `[]` because the entry aged. The TTL
+ *     only drives `needsRefresh()` ("a re-fetch is due") and, with no
+ *     failed refresh, the stale flag. This is the central fix: on
+ *     serverless a paying customer must not be locked out 60s after a
+ *     warm just because Crossdeck was briefly unreachable.
+ *   - Staleness alone never returns false. Each entitlement is honoured
+ *     against its OWN `validUntil` instead — a time-based trial expiry
+ *     still applies even mid-partition; a still-valid Pro entitlement
+ *     rides the outage out.
+ *   - Staleness is VISIBLE, not silent. `validUntil` covers time-based
+ *     expiry; it does NOT cover an event-based revoke (chargeback,
+ *     refund, fraud) — that has no `validUntil`, so the cache would keep
+ *     serving a revoked customer through an outage. Serving them is the
+ *     right trade (don't lock real payers out), but unbounded-and-
+ *     invisible is the bug. So once a refresh ATTEMPT fails
+ *     (`markRefreshFailed`) or the data ages past `staleAfterMs`, the
+ *     customer is flagged stale — `isStale()` / `staleCustomerCount` are
+ *     surfaced in `diagnostics()`. It keeps serving last-known-good; the
+ *     staleness is just no longer hidden.
+ *
+ * Cold-start durability lives one layer up: `getEntitlements()` in
+ * `crossdeck-server.ts` persists every successful fetch to an optional
+ * `EntitlementStore` and, on a network failure, loads last-known-good
+ * back from it and into this cache. This cache stays a pure in-memory
+ * structure with NO I/O — `isEntitled()` is and remains synchronous.
+ *
+ * Differences from the web SDK's cache:
  *   - **Per-customer**, not singleton. Web SDK has one user per browser
  *     tab; Node SDK has many users hitting one server. The cache is
- *     keyed by `crossdeckCustomerId`.
- *   - **TTL-bounded**. Each customer's entry expires after `ttlMs`
- *     (default 60_000) and the next read returns `false` until
- *     `getEntitlements()` refreshes. Stripe + Mixpanel ship the same
- *     pattern server-side.
+ *     keyed by `crossdeckCustomerId`. Staleness, freshness and the
+ *     failed-refresh marker are therefore all per-customer too.
+ *   - **No synchronous storage hydration** in the constructor. The web
+ *     SDK hydrates from `localStorage` on boot; the Node durable store
+ *     is async, so hydration happens lazily inside `getEntitlements()`.
+ *   - **LRU-bounded** by `maxCustomers` — a long-running multi-tenant
+ *     server would otherwise leak Map entries forever.
  *   - **Subscriber API unchanged** — `subscribe(listener)` fires after
- *     any mutation (set / clear / per-customer expiry-driven eviction
- *     is NOT considered a mutation, by design — listeners shouldn't
- *     re-render just because a TTL elapsed).
- *
- * The cache holds only ACTIVE entitlements — `setForCustomer` filters.
- * `isEntitled()` returns `false` when:
- *   - the customer has no cached entry
- *   - the entry has expired
- *   - the requested key isn't in the active set
+ *     any mutation (set / clear). Passive LRU eviction and a TTL
+ *     elapsing are NOT mutations, by design.
  */
 
 type EntitlementsListener = (customerId: string, entitlements: PublicEntitlement[]) => void;
 interface EntitlementCacheOptions {
-    /** TTL in ms. Default 60_000 (60s). 0 disables caching (every read is cold). */
+    /**
+     * Refresh-hint TTL in ms. Default 60_000 (60s).
+     *
+     * After `ttlMs` a customer's entry is "refresh due" — `needsRefresh()`
+     * returns true and the caller should re-fetch. It is NOT an expiry:
+     * `isEntitled()` keeps serving last-known-good past it. `0` makes
+     * every entry immediately refresh-due (useful for tests) but STILL
+     * does not invalidate — last-known-good is served regardless.
+     */
     ttlMs?: number;
     /**
      * Maximum number of customers cached at once. Long-running multi-tenant
@@ -889,6 +1063,16 @@ interface EntitlementCacheOptions {
      * (passive eviction is not a mutation by design).
      */
     maxCustomers?: number;
+    /**
+     * Age (ms) past which a customer's last-known-good data is flagged
+     * STALE even with no failed refresh. Default 24h.
+     *
+     * Staleness never changes what `isEntitled()` returns; it only makes a
+     * long un-refreshed window observable via `isStale()` / diagnostics —
+     * so an event-based revoke (no `validUntil`) riding out an outage is
+     * visible instead of silent.
+     */
+    staleAfterMs?: number;
 }
 
 /**
@@ -995,6 +1179,16 @@ declare class CrossdeckServer extends EventEmitter {
     private readonly flushOnExit;
     private readonly superProps;
     private readonly entitlementCache;
+    /**
+     * Optional developer-supplied durable store for last-known-good
+     * entitlements (Redis / their DB / a KV). `undefined` when not
+     * configured — the SDK then has no cold-start durability on
+     * serverless, which it states explicitly at boot.
+     *
+     * Touched ONLY from the async `getEntitlements()` — never from the
+     * synchronous `isEntitled()`.
+     */
+    private readonly entitlementStore;
     private readonly debug;
     /**
      * Alias map — `developerUserId` / `anonymousId` → canonical
@@ -1014,9 +1208,67 @@ declare class CrossdeckServer extends EventEmitter {
     private errorTags;
     private errorBeforeSend;
     constructor(options: CrossdeckServerOptions);
+    /**
+     * Emit the honest "no cold-start durability" warning when the runtime
+     * is serverless AND no `entitlementStore` is wired. Local-only debug
+     * signal — no network call, no phone-home. Safe to fire from the
+     * constructor before `setImmediate` because there is no I/O on this
+     * path.
+     *
+     * `isServerless` AND no store is the gap: a cold start begins with an
+     * empty in-memory cache and a brief Crossdeck outage in that window
+     * would read a paying customer as un-entitled. That gap is
+     * unavoidable without a store — so the SDK STATES it (a
+     * `sdk.no_durable_store` debug warning) rather than hiding it.
+     *
+     * Audit P1 #9: this used to live INSIDE `emitBootTelemetry()` which
+     * itself sat inside the `bootHeartbeat` gate, so any developer who
+     * set `bootHeartbeat: false` silently disabled the entire reason
+     * `entitlementStore` exists. Now split: warning fires
+     * unconditionally; the boot phone-home stays gated.
+     */
+    private emitDurabilityWarning;
+    /**
+     * Emit the one-time `sdk.boot` telemetry event — the aggregatable
+     * fact the backend pivots on (compute fleet-wide
+     * "% serverless-with-no-durable-store"). Rides the batched + retried
+     * + idempotent queue and is drained by flush-on-exit, so it survives
+     * a serverless teardown.
+     *
+     * Why a `track()` event and not the heartbeat: `GET /v1/sdk/heartbeat`
+     * carries no request body, so it cannot transport a structured
+     * `durability` fact.
+     *
+     * Gated by `bootHeartbeat` (and `testMode`) because it IS a phone-
+     * home — the unconditional surface is `emitDurabilityWarning()`,
+     * which has no network call.
+     */
+    private emitBootTelemetryEvent;
     identify(userId: string, anonymousId: string, options?: IdentifyOptions & RequestOptions): Promise<AliasResult>;
     aliasIdentity(input: AliasIdentityInput, options?: RequestOptions): Promise<AliasResult>;
     forget(hints: IdentityHints, options?: RequestOptions): Promise<ForgetResult>;
+    /**
+     * Fetch a customer's entitlements from Crossdeck and warm the cache.
+     *
+     * Durability — this is where last-known-good lives, NOT in the
+     * synchronous `isEntitled()`:
+     *   - On a SUCCESSFUL fetch: the entitlement cache is populated and,
+     *     if an `entitlementStore` is configured, the result is persisted
+     *     to it (`await store.save(...)`). The cache + store now hold
+     *     server-confirmed truth.
+     *   - On a network FAILURE: the cache is marked refresh-failed for the
+     *     customer (so `diagnostics()` shows the staleness), then — if a
+     *     store is configured — last-known-good is loaded back from it
+     *     (`await store.load(...)`). If the store yields a snapshot, the
+     *     cache is populated from it and that snapshot is RETURNED as a
+     *     normal `EntitlementsListResponse` — a cold-start / outage no
+     *     longer fails a paying customer. If there is no store, or the
+     *     store is empty, the network error is rethrown unchanged so the
+     *     caller still sees the failure.
+     *
+     * The store is touched only here, inside the `await` that already
+     * existed. `isEntitled()` remains a pure synchronous `Map` read.
+     */
     getEntitlements(hints: IdentityHints, options?: RequestOptions): Promise<EntitlementsListResponse>;
     getCustomerEntitlements(customerId: string, options?: RequestOptions): Promise<EntitlementsListResponse>;
     /**
@@ -1389,11 +1641,58 @@ declare class CrossdeckServer extends EventEmitter {
      * with the entitlement cache's max-customers cap.
      */
     private populateEntitlementCache;
+    /**
+     * Persist a successful entitlements fetch to the durable store, if
+     * one is configured. No-op when there is no store.
+     *
+     * Saved under EVERY identity the caller might later look up by — the
+     * canonical `crossdeckCustomerId` plus any `userId` / `anonymousId`
+     * hint. The Node cache resolves a hint to a canonical ID via an
+     * in-memory alias map; on a cold start that map is empty, so a
+     * failure-path `load()` must be able to hit the store with the raw
+     * hint the caller passed. Saving under all keys makes that work.
+     *
+     * Best-effort: a store `save()` that throws is swallowed (logged in
+     * debug) — it weakens durability for that customer but must never
+     * fail an otherwise-successful `getEntitlements()`.
+     */
+    private saveEntitlementsToStore;
+    /**
+     * Load last-known-good entitlements from the durable store on a
+     * network-failure path. Returns the first snapshot found across the
+     * caller's identity keys, or `null` if there is no store / no stored
+     * snapshot / every read failed.
+     *
+     * Tries the canonical `customerId` hint first, then `userId`, then
+     * `anonymousId` — the order callers most commonly key by. A corrupt
+     * or wrong-shaped blob is treated as a miss (the store is developer-
+     * supplied; the SDK validates rather than trusts).
+     */
+    private loadEntitlementsFromStore;
+    /**
+     * Resolve the customer ID to stamp a failed-refresh marker against.
+     *
+     * Prefers a canonical ID the cache already knows (so the marker lands
+     * on the existing warm entry), then falls back to whatever raw hint
+     * the caller supplied — on a true cold-start failure there is no
+     * cache entry yet, and marking under the hint still makes "we tried
+     * for this customer and Crossdeck was down" observable.
+     */
+    private resolveFailedRefreshCustomerId;
     private touchAlias;
     /**
      * Resolve any hint shape (canonical customerId / userId hint /
      * anonymousId hint / raw string) to a `crossdeckCustomerId` if we
      * have a cache entry for it.
+     *
+     * String overload is STRICT on the canonical-id shape. Pre-fix
+     * `isFresh(raw)` treated any string with a cache entry as a valid
+     * canonical id — if tenant A's userId happened to collide with
+     * tenant B's crossdeckCustomerId, A's call would resolve to B's
+     * cached entitlements. Bounded by the `cdcust_` prefix convention
+     * (which both SDKs and the backend mint, see
+     * backend/src/lib/customers.ts) — anything else is treated purely
+     * as an alias lookup, never as a canonical id. Audit P1 #19.
      */
     private resolveCacheCustomerId;
     private identityPayload;
@@ -1411,4 +1710,4 @@ declare class CrossdeckServer extends EventEmitter {
     private normalizeIngestEvent;
 }
 
-export { type StackFrame as $, type AliasIdentityInput as A, type Breadcrumb as B, CROSSDECK_API_VERSION as C, DEFAULT_BASE_URL as D, type EntitlementCacheOptions as E, type EventProperties as F, type ForgetResult as G, type GrantDuration as H, type GrantEntitlementInput as I, type GroupMembership as J, type HeartbeatResponse as K, type HttpRequestInfo as L, type HttpResponseInfo as M, type HttpRetriesConfig as N, type IdentifyOptions as O, type IdentityHints as P, type IngestOptions as Q, type IngestResponse as R, type PublicEntitlement as S, type PurchaseResult as T, type RequestOptions as U, type RevokeEntitlementInput as V, type RuntimeHost as W, type RuntimeInfo as X, SDK_NAME as Y, SDK_VERSION as Z, type ServerEvent as _, type AliasResult as a, type SyncPurchaseInput as a0, makeCrossdeckError as a1, type AuditDecision as b, type AuditEntry as c, type BreadcrumbCategory as d, type BreadcrumbLevel as e, type CapturedError as f, CrossdeckAuthenticationError as g, CrossdeckConfigurationError as h, CrossdeckError as i, type CrossdeckErrorPayload as j, type CrossdeckErrorType as k, CrossdeckInternalError as l, CrossdeckNetworkError as m, CrossdeckPermissionError as n, CrossdeckRateLimitError as o, CrossdeckServer as p, type CrossdeckServerOptions as q, CrossdeckValidationError as r, DEFAULT_TIMEOUT_MS as s, type Diagnostics as t, type EntitlementMutationResult as u, type EntitlementsListResponse as v, type EntitlementsListener as w, type Environment as x, type ErrorCaptureConfig as y, type ErrorLevel as z };
+export { type StoredEntitlements as $, type AliasIdentityInput as A, type Breadcrumb as B, CROSSDECK_API_VERSION as C, DEFAULT_BASE_URL as D, type EntitlementCacheOptions as E, type ErrorLevel as F, type EventProperties as G, type ForgetResult as H, type GrantDuration as I, type GrantEntitlementInput as J, type GroupMembership as K, type HeartbeatResponse as L, type HttpRequestInfo as M, type HttpResponseInfo as N, type HttpRetriesConfig as O, type IdentifyOptions as P, type IdentityHints as Q, type IngestOptions as R, type IngestResponse as S, type PublicEntitlement as T, type PurchaseResult as U, type RequestOptions as V, type RevokeEntitlementInput as W, type RuntimeHost as X, type RuntimeInfo as Y, type ServerEvent as Z, type StackFrame as _, type AliasResult as a, type SyncPurchaseInput as a0, makeCrossdeckError as a1, type AuditDecision as b, type AuditEntry as c, type BreadcrumbCategory as d, type BreadcrumbLevel as e, type CapturedError as f, CrossdeckAuthenticationError as g, CrossdeckConfigurationError as h, CrossdeckError as i, type CrossdeckErrorPayload as j, type CrossdeckErrorType as k, CrossdeckInternalError as l, CrossdeckNetworkError as m, CrossdeckPermissionError as n, CrossdeckRateLimitError as o, CrossdeckServer as p, type CrossdeckServerOptions as q, CrossdeckValidationError as r, DEFAULT_TIMEOUT_MS as s, type Diagnostics as t, type EntitlementMutationResult as u, type EntitlementStore as v, type EntitlementsListResponse as w, type EntitlementsListener as x, type Environment as y, type ErrorCaptureConfig as z };