@farthershore/backend 0.19.0 → 0.20.0

package/dist/types/core/deadline.d.ts

@@ -0,0 +1,80 @@
+import { FartherShoreError } from "./errors.js";
+/**
+ * Per-operation deadlines. Verification-path calls are tighter than reporting
+ * calls: JWKS sits in front of every inbound request, while a metering flush is
+ * a background economic report that is retried anyway.
+ */
+export declare const DEADLINE_MS: {
+    /** Boot-blocking; generous because it runs once and gates startup. */
+    readonly bootstrap: 10000;
+    /** On the inbound verification path — must not hold a request open. */
+    readonly jwks: 5000;
+    /** Background economic report, retried by the caller. */
+    readonly metering: 10000;
+    /** Background attested usage callback. */
+    readonly postStreamUsage: 10000;
+    /** Best-effort heartbeat; never blocks anything. */
+    readonly health: 5000;
+    /** Boot-time route drift report; fail-open at the caller. */
+    readonly report: 10000;
+};
+export type DeadlineOperation = keyof typeof DEADLINE_MS;
+/**
+ * Byte cap for response bodies the SDK parses. Core's JWKS and bootstrap
+ * documents are kilobytes; a megabyte is orders of magnitude of headroom while
+ * still refusing an unbounded stream.
+ */
+export declare const MAX_RESPONSE_BYTES = 1048576;
+/**
+ * True when `cause` is this module's deadline firing (as opposed to a caller
+ * cancellation or a transport error). `AbortSignal.timeout` rejects with a
+ * `TimeoutError` DOMException; we also accept our own typed marker.
+ */
+export declare function isDeadlineExceeded(cause: unknown): boolean;
+/** Raised when a bounded read exceeds {@link MAX_RESPONSE_BYTES}. */
+export declare class ResponseTooLargeError extends Error {
+    constructor(limit: number);
+}
+/** Marker for a deadline that fired, preserved across helper boundaries. */
+export declare class DeadlineExceededError extends Error {
+    readonly operation: DeadlineOperation;
+    constructor(operation: DeadlineOperation, timeoutMs: number);
+}
+export type DeadlineOptions = {
+    /** Host cancellation to compose with the SDK deadline. */
+    callerSignal?: AbortSignal;
+    /**
+     * Override the operation default. For callers with a tighter budget than the
+     * SDK default (and for tests, which cannot wait out a 10s deadline).
+     */
+    timeoutMs?: number;
+};
+/**
+ * Compose the SDK deadline for `operation` with an optional caller signal.
+ * Either aborting aborts the fetch, so host cancellation still works and the
+ * SDK can never outlive its own timeout.
+ */
+export declare function deadlineSignal(operation: DeadlineOperation, options?: DeadlineOptions): AbortSignal;
+/**
+ * `fetch` with a mandatory deadline. Every outbound SDK call goes through here;
+ * the CI guard (`fetch-timeouts:check:backend-sdk`) fails the build on a raw
+ * `fetch(` added anywhere else in the package.
+ *
+ * Rethrows a {@link DeadlineExceededError} when OUR timeout fired, so the
+ * failure is classifiable even though `AbortSignal.any` erases which input
+ * aborted. A caller-driven abort propagates unchanged.
+ */
+export declare function fetchWithDeadline(fetchImpl: typeof fetch, input: string, init: RequestInit, operation: DeadlineOperation, options?: DeadlineOptions): Promise<Response>;
+/**
+ * Read a response body as text, cancelling the stream once `limit` bytes have
+ * arrived. Returns the decoded text; throws {@link ResponseTooLargeError} when
+ * the cap is crossed so a caller never sees a silently truncated document.
+ */
+export declare function readBoundedText(response: Response, limit?: number): Promise<string>;
+/**
+ * Bounded JSON read. Same cap as {@link readBoundedText}; a body that is not
+ * valid JSON raises the underlying SyntaxError for the caller to classify.
+ */
+export declare function readBoundedJson<T>(response: Response, limit?: number): Promise<T>;
+/** Wrap a deadline failure in the SDK's typed error with a stable code. */
+export declare function deadlineError(operation: DeadlineOperation, cause: unknown): FartherShoreError;

package/dist/types/core/jwks.d.ts

@@ -1,28 +1,53 @@
 export type Jwk = JsonWebKey & {
     kid?: string;
 };
+/** Freshness of the key set backing a verification decision. */
+export type JwksCacheState = "fresh" | "soft_stale" | "hard_stale" | "cold";
+export type JwksObservation = {
+    state: JwksCacheState;
+    /** Age of the cached key set in ms (0 when cold). */
+    ageMs: number;
+    /** The `kid` being resolved, when the observation is tied to one. */
+    kid?: string;
+};
+/**
+ * Observability hook. Fires on every decision that depends on cache freshness,
+ * so an operator can alarm on `soft_stale` (Core is failing) long before
+ * `hard_stale` (requests are now being rejected).
+ */
+export type JwksObserver = (observation: JwksObservation) => void;
 export type JwksClientOptions = {
     jwksUrl: string;
     /** Injectable fetch (tests). Defaults to globalThis.fetch. */
     fetchImpl?: typeof fetch;
     /** How long a successful fetch stays fresh before a background refresh. */
     cacheTtlMs?: number;
+    /**
+     * Hard ceiling on serving a key set whose refresh is failing. Past this age
+     * the client FAILS CLOSED rather than vouching for keys it can no longer
+     * confirm. Must be ≥ cacheTtlMs.
+     */
+    hardStaleMs?: number;
     /** How long an unknown-kid result is negatively cached (avoids hammering). */
     negativeCacheMs?: number;
     /** Injectable clock (tests). */
     now?: () => number;
+    /** Freshness//staleness observations for metrics. */
+    onObservation?: JwksObserver;
 };
 /**
- * Caching JWKS client. Holds the last successful key set indefinitely as a
- * warm fallback (stale-while-revalidate) and only fails closed when it has
- * NEVER successfully fetched (cold cache).
+ * Caching JWKS client. Serves the last successful key set as a warm fallback
+ * while a refresh is failing, but only until {@link JwksClientOptions.hardStaleMs};
+ * fails closed on a cold cache and past the hard-stale ceiling.
  */
 export declare class JwksClient {
     private readonly jwksUrl;
     private readonly fetchImpl;
     private readonly cacheTtlMs;
+    private readonly hardStaleMs;
     private readonly negativeCacheMs;
     private readonly now;
+    private readonly onObservation;
     private keysByKid;
     private fetchedAt;
     private hasFetchedOnce;
@@ -31,18 +56,28 @@ export declare class JwksClient {
     constructor(options: JwksClientOptions);
     /**
      * Resolve a public JWK for `kid`, fail-closed. Throws FartherShoreError with
-     * `jwks_unavailable` (cold cache + fetch failed) or `unknown_key_id`.
+     * `jwks_unavailable` (cold cache, or a hard-stale cache whose refresh is
+     * failing) or `unknown_key_id`.
      */
     getKey(kid: string): Promise<Jwk>;
     /** Record a confirmed-missing kid, evicting the oldest if at capacity. */
     private rememberMissingKid;
+    private ageMs;
     private isStale;
+    private isHardStale;
+    /** Current freshness of the cached key set. */
+    private cacheState;
+    private observe;
+    /** Fail closed when the cached key set is past the hard-stale ceiling. */
+    private assertWithinHardStale;
     /** Single-flight refresh: concurrent callers share one fetch. */
     private refresh;
     private doFetch;
     /**
-     * Stale-while-revalidate: with a warm cache, swallow the refresh failure and
-     * keep serving the last-known keys. With a COLD cache, fail closed.
+     * BOUNDED stale-while-revalidate. A COLD cache fails closed. A warm cache
+     * inside the soft window swallows the failure and keeps serving. Past the
+     * hard-stale ceiling it fails closed too — availability is worth a bounded
+     * window of degraded trust, not an unbounded one.
      */
-    private failOnColdCache;
+    private handleRefreshFailure;
 }

package/dist/types/core/post-stream-usage.d.ts

@@ -26,6 +26,8 @@ export type PostStreamUsageClientOptions = {
     sleep?: (delayMs: number) => Promise<void>;
     /** Backoff after each request-not-found response. */
     retryDelaysMs?: readonly number[];
+    /** Upper bound for Retry-After sleeps; defaults to 10 seconds. */
+    maxRetryDelayMs?: number;
 };
 /**
  * Best-effort, attested post-stream billing reporter. The callback is
@@ -40,6 +42,8 @@ export declare class PostStreamUsageClient {
     private readonly logger;
     private readonly sleep;
     private readonly retryDelaysMs;
+    private readonly maxRetryDelayMs;
     constructor(options: PostStreamUsageClientOptions);
     reportUsage(input: ReportUsageInput): Promise<ReportUsageResult>;
+    private retryDelayForAttempt;
 }

package/dist/types/core/replay-protection.d.ts

@@ -0,0 +1,28 @@
+import { type NonceStore } from "./nonceCache.js";
+/** How far one-time-use enforcement actually reaches. */
+export type ReplayProtectionMode = "shared" | "single-instance";
+export type ReplayProtectionDiagnostic = {
+    mode: ReplayProtectionMode;
+    /** True when replay is enforced across every replica, not just this process. */
+    crossReplica: boolean;
+};
+export type ResolveReplayProtectionInput = {
+    /** Shared store injected by the host, if any. */
+    nonceStore?: NonceStore | undefined;
+};
+export type ResolvedReplayProtection = {
+    store: NonceStore;
+    diagnostic: ReplayProtectionDiagnostic;
+};
+/**
+ * Select the replay store and report which mode it is. Never throws — the
+ * zero-config default is the in-memory cache, and the time window is what
+ * bounds exposure regardless.
+ */
+export declare function resolveReplayProtection(input?: ResolveReplayProtectionInput): ResolvedReplayProtection;
+/**
+ * Wrap an injected shared store so an OUTAGE fails closed. Only applies when a
+ * builder opted into a shared store; the in-memory default cannot fail this
+ * way.
+ */
+export declare function failClosed(store: NonceStore): NonceStore;

package/dist/types/core/runtime.d.ts

@@ -3,6 +3,7 @@ import type { ReconcileResult } from "../reflect/reconcile.js";
 import { type MeterOptions } from "./metering.js";
 import { type ReportUsageInput, type ReportUsageResult } from "./post-stream-usage.js";
 import { type NonceStore } from "./nonceCache.js";
+import { type ReplayProtectionDiagnostic } from "./replay-protection.js";
 import { type SpawnFn } from "./tunnel.js";
 import { type FartherShoreRequestContext, type VerifyRequestInput } from "./verifyRequest.js";
 /** Advanced opt-in tunnel config. The embedded runner is the default DX. */
@@ -57,14 +58,16 @@ export type FartherShoreInitOptions = {
      */
     contextSecrets?: readonly string[];
     /**
-     * OPTIONAL shared replay-prevention store. The default is an IN-MEMORY,
-     * PER-PROCESS {@link NonceCache} — it stops replay against a single instance
-     * only. A horizontally-scaled backend (multiple replicas / serverless
-     * instances) where a captured, still-valid signed request could be replayed
-     * to a DIFFERENT replica should inject a SHARED store (Redis / Memcached /
-     * Cloudflare KV / Durable Object) implementing {@link NonceStore}. The signed
-     * request's ~300s validity window bounds the exposure either way, but a shared
-     * store closes the cross-replica gap. `checkAndRemember` may be async.
+     * OPTIONAL shared replay-prevention store. Not required: the signature's
+     * ~305s time window is the always-on defense, and the zero-config default is
+     * an in-memory per-process cache. Inject a shared atomic store (Redis /
+     * Memcached / Cloudflare KV / Durable Object) implementing {@link NonceStore}
+     * only if you want one-time-use enforced ACROSS replicas rather than within
+     * each one. `checkAndRemember` may be async, and should be TTL-bound to the
+     * signature validity window.
+     *
+     * If you do inject one, an outage of that store fails requests CLOSED — it
+     * never degrades to "not a replay".
      */
     nonceStore?: NonceStore;
 };
@@ -85,6 +88,7 @@ export declare class FartherShore {
     /** OPTIONAL HS256 secret(s) — defense-in-depth over the cv=2 X-Fs-Context. */
     private readonly contextSecrets;
     private readonly nonceCache;
+    private readonly replayProtectionDiagnostic;
     private readonly shutdownManager;
     private jwks;
     private meteringClient;
@@ -133,6 +137,13 @@ export declare class FartherShore {
     meter(meter: string, qty: number, options?: MeterOptions): Promise<void>;
     /** Best-effort attested post-stream usage callback. Never rejects. */
     reportUsage(input: ReportUsageInput): Promise<ReportUsageResult>;
+    /**
+     * How far replay protection actually reaches — `"shared"` (enforced across
+     * every replica) or `"single-instance"` (this process only). Deployment
+     * diagnostic: log it at boot, or assert on it in a smoke test, so the mode is
+     * never a surprise. See {@link FartherShoreInitOptions.nonceStore}.
+     */
+    replayProtection(): ReplayProtectionDiagnostic;
     /** Current local health report. */
     health(): RuntimeHealthReport;
     /** Graceful shutdown: flush metering + send a stopping heartbeat. */

package/dist/types/index.d.ts

@@ -10,6 +10,7 @@ export { requireMember, requireService, credentialKind, isPortalSession, type Me
 export { hasPermission, requirePermission, permissionGrants, permissionSatisfies, FartherShorePermissionError, type PermissionCarrier, } from "./core/permissions.js";
 export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
 export { NonceCache, type NonceCacheOptions, type NonceStore, } from "./core/nonceCache.js";
+export { type ReplayProtectionDiagnostic, type ReplayProtectionMode, } from "./core/replay-protection.js";
 export { BootstrapClient, type BootstrapClientOptions, } from "./core/bootstrap.js";
 export { MeteringClient, type MeteringClientOptions, type MeterOptions, } from "./core/metering.js";
 export { PostStreamUsageClient, type PostStreamUsageClientOptions, type ReportUsageInput, type RequestScopedReportUsageInput, type ReportUsageResult, } from "./core/post-stream-usage.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Farther Shore backend SDK for builder upstreams: signed response usage, fail-closed gateway request verification, health, and lifecycle from FS_RUNTIME_TOKEN",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,10 +37,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@farthershore/cloudflared-linux-arm64": "0.0.0",
-    "@farthershore/cloudflared-linux-x64": "0.0.0",
     "@farthershore/cloudflared-darwin-arm64": "0.0.0",
-    "@farthershore/cloudflared-darwin-x64": "0.0.0"
+    "@farthershore/cloudflared-darwin-x64": "0.0.0",
+    "@farthershore/cloudflared-linux-arm64": "0.0.0",
+    "@farthershore/cloudflared-linux-x64": "0.0.0"
   },
   "peerDependencies": {
     "express": "^4.0.0 || ^5.0.0"
@@ -51,13 +51,13 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.19.17",
-    "esbuild": "^0.27.7",
-    "eslint": "^9.39.4",
-    "eslint-plugin-sonarjs": "^4.0.3",
-    "typescript": "^6.0.2",
-    "typescript-eslint": "^8.59.0",
-    "vitest": "^4.1.6",
+    "@types/node": "^22.20.1",
+    "esbuild": "^0.28.1",
+    "eslint": "^9.39.5",
+    "eslint-plugin-sonarjs": "^4.2.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.66.0",
+    "vitest": "^4.1.10",
     "@farthershore/contracts": "0.62.0"
   },
   "engines": {