@farthershore/backend 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to the runtime backend SDK are documented here. This SDK
 versions independently from the frontend and business SDKs. Pre-1.0: minor
 versions may include breaking changes.
 
+## [0.20.0] - 2026-08-07
+
+### Changed
+
+- **An injected shared nonce store now fails closed on outage.** If you supply
+  `nonceStore`, a throw from it rejects the request instead of falling through
+  to "not a replay" — otherwise knocking that store over would switch
+  one-time-use enforcement off entirely. No effect on the default in-memory
+  cache, which cannot fail this way.
+
+  `fs.replayProtection()` reports whether enforcement is `"shared"`
+  (cross-replica) or `"single-instance"` (this process), for boot logging.
+
+  Replay protection remains **zero-config**: the signature's ~305s time window
+  is the always-on defense and needs nothing from you. A shared store is purely
+  an opt-in upgrade for builders who want one-time-use enforced across replicas
+  rather than within each one. (FAR-760)
+
+### Security
+
+- **A stale JWKS key set is no longer trusted forever.** The client held the
+  last successful fetch indefinitely, so during a prolonged Core/JWKS outage a
+  revoked signing key kept verifying. Stale-while-revalidate now has a ceiling:
+  fresh (<5m) → soft-stale (<15m, still served if refresh fails) → hard-stale
+  (fail closed). Adds an `onObservation` hook reporting
+  `fresh` / `soft_stale` / `hard_stale` / `cold`. (FAR-759)
+
+### Fixed
+
+- **Every outbound SDK call now has a deadline.** Bootstrap, JWKS refresh,
+  metering flush, post-stream usage, the health heartbeat and the drift report
+  all awaited without an `AbortSignal`; a half-open connection could wedge
+  request verification, boot, readiness, or usage reporting indefinitely.
+  Caller cancellation composes with the SDK deadline, timeouts are classifiable,
+  and parsed response bodies are byte-bounded. (FAR-785)
+
 ## [0.19.0]
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@ graceful lifecycle (health + shutdown). Everything else — your business, backe
 and environment ids, the verification keys, and the metering endpoint — is
 fetched automatically from the token at startup.
 
-> **Status: `0.19.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.20.0`.** Pre-1.0: minor releases may include breaking changes, so
 > pin this package to an exact version (or a patch-only range) and upgrade
 > deliberately.
 
@@ -99,6 +99,34 @@ wrong-route / body-hash-mismatch / replayed-nonce / unknown-key /
 keys-unavailable) throws a typed `FartherShoreError` that maps to **HTTP 401**
 (413 for oversized bodies). There is no fail-open path.
 
+### Replay protection (nothing to configure)
+
+A signed request is one-time-use, and two things enforce that:
+
+- **A time window, always on.** The gateway signs a timestamp into the request;
+  anything older than ~305s (replay window + clock skew) is rejected outright.
+  This holds for every deployment shape and needs nothing from you.
+- **A seen-id list.** Inside that window, the SDK remembers each
+  `X-Fs-Request-Id` it has accepted and rejects a second sighting. The default
+  list is in-memory and per-process.
+
+That default is deliberate: running more than one replica means each has its own
+list, so a captured request could be replayed once per replica **within the
+~305s window** — and closing that would mean asking you to provision and operate
+a distributed cache. We would rather keep your setup to one environment variable
+and let the time window bound the exposure.
+
+If you do want one-time-use enforced across replicas, inject a shared store:
+
+```ts
+initFromEnv({ nonceStore: myStore }); // checkAndRemember(id) => boolean | Promise<boolean>
+```
+
+Make it TTL-bound to the signature validity window. If that store goes down,
+requests fail **closed** — it never degrades to "not a replay".
+`fs.replayProtection()` reports which mode is active (`"shared"` |
+`"single-instance"`) if you want it in your boot logs.
+
 ## Response-bound usage reporting
 
 Use `withUsage()` (or the builder-style `createUsage()`) when you know the usage