@shelbyb/daywalker-sdk 0.3.0 → 0.4.0

package/dist/next.js

@@ -1,4 +1,5 @@
 import { daywalker, Daywalker } from "./client.js";
+import { toAuthFailureResponse } from "./middleware.js";
 /**
  * Real Server Action IDs are hex hashes. Scanners probing for CVE-2025-55182 (React2Shell)
  * send junk like `Next-Action: x`, which Next.js rejects with an internal error.
@@ -12,36 +13,123 @@ export const DEFAULT_BYPASS_PATHS = [
     "/robots.txt",
     "/sitemap.xml",
 ];
-/** File extensions treated as static assets (outside /api/) and passed through without auth. */
+/**
+ * A suggested value for the opt-in `staticFileExtensions` option. It is NOT applied by default:
+ * an extension says nothing about whether a route is public (`/users/123.js` can be a dynamic page).
+ * Prefer excluding public files with Next's `matcher` (see `createDaywalkerMiddleware`).
+ */
 export const STATIC_FILE_EXTENSIONS = /\.(?:js|css|png|jpe?g|gif|webp|avif|svg|ico|woff2?|map|txt)$/i;
 /**
- * Static assets that skip auth: Next's build output and image optimizer, the favicon, and files with
- * an allowlisted extension. `/_next/data/` (getServerSideProps JSON) and `/api/*` are never static.
+ * Decodes and normalizes a URL pathname the way a router sees it: percent-decoded once, `//`
+ * collapsed and `.`/`..` segments resolved. Returns null (never bypass auth) for malformed
+ * encoding, encoded slashes/backslashes, raw backslashes or control characters.
  */
-export function isStaticAssetPath(pathname) {
-    if (pathname === "/api" || pathname.startsWith("/api/"))
+export function normalizePathname(pathname) {
+    if (typeof pathname !== "string" || !pathname.startsWith("/"))
+        return null;
+    if (pathname.includes("\\") || /%(?:2f|5c)/i.test(pathname))
+        return null;
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        return null;
+    }
+    if (/[\u0000-\u001f\u007f\\]/.test(decoded))
+        return null;
+    const segments = [];
+    for (const segment of decoded.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..")
+            segments.pop();
+        else
+            segments.push(segment);
+    }
+    const trailingSlash = segments.length > 0 && /\/\.{0,2}$/.test(decoded);
+    return `/${segments.join("/")}${trailingSlash ? "/" : ""}`;
+}
+function isApiPath(pathname) {
+    return pathname === "/api" || pathname.startsWith("/api/");
+}
+function extensionMatcher(extensions) {
+    if (!extensions)
+        return null;
+    if (extensions instanceof RegExp) {
+        // Copy without the stateful g/y flags so repeated .test() calls are consistent.
+        const re = new RegExp(extensions.source, extensions.flags.replace(/[gy]/g, ""));
+        return (pathname) => re.test(pathname);
+    }
+    const list = extensions.map((e) => e.replace(/^\./, "").toLowerCase()).filter(Boolean);
+    if (list.length === 0)
+        return null;
+    return (pathname) => {
+        const last = pathname.slice(pathname.lastIndexOf("/") + 1).toLowerCase();
+        return list.some((ext) => last.endsWith(`.${ext}`) && last.length > ext.length + 1);
+    };
+}
+/** `pathname` must already be normalized. */
+function isBuiltInStaticPath(pathname) {
+    return pathname.startsWith("/_next/static/") || pathname === "/_next/image" || pathname.startsWith("/_next/image/") || pathname === "/favicon.ico";
+}
+function isStaticNormalized(pathname, matchesExtension) {
+    if (isApiPath(pathname))
         return false;
-    if (pathname.startsWith("/_next/static/") || pathname === "/_next/image" || pathname.startsWith("/_next/image/"))
-        return true;
-    if (pathname === "/favicon.ico")
+    if (isBuiltInStaticPath(pathname))
         return true;
     if (pathname.startsWith("/_next/"))
         return false;
-    return STATIC_FILE_EXTENSIONS.test(pathname);
+    return matchesExtension ? matchesExtension(pathname) : false;
+}
+/**
+ * Static assets that skip auth: Next's build output (`/_next/static/`), image optimizer
+ * (`/_next/image`) and `/favicon.ico`. Files matching `staticFileExtensions` are included only when
+ * that list is passed explicitly. The path is decoded and normalized first; `/_next/data/`
+ * (getServerSideProps JSON) and `/api` / `/api/*` are never static.
+ */
+export function isStaticAssetPath(pathname, staticFileExtensions) {
+    const normalized = normalizePathname(pathname);
+    if (normalized === null)
+        return false;
+    return isStaticNormalized(normalized, extensionMatcher(staticFileExtensions));
 }
+const REDIRECT_ORIGIN = "https://redirect-check.invalid";
 /**
  * Sanitizes open redirect path parameter (`from`).
- * Prevents protocol-relative URLs (`//evil.com`), backslashes (`/\evil.com`), and control characters.
+ * Accepts only same-origin relative paths: rejects protocol-relative URLs (`//evil.com`), any
+ * backslash, whitespace or control character (browsers strip tabs/newlines, so `/\t/evil.com` would
+ * become `//evil.com`), and anything that resolves to another origin.
  */
 export function sanitizeRedirectPath(path) {
     if (!path || typeof path !== "string")
         return null;
-    const clean = path.trim().replace(/[\r\n\0]/g, "");
-    if (!clean.startsWith("/") || clean.startsWith("//") || clean.startsWith("/\\")) {
+    if (/[\s\u0000-\u001f\u007f-\u009f\\]/.test(path))
         return null;
+    if (!path.startsWith("/") || path.startsWith("//"))
+        return null;
+    let resolved;
+    try {
+        resolved = new URL(path, REDIRECT_ORIGIN);
     }
-    return clean;
+    catch {
+        return null;
+    }
+    if (resolved.origin !== REDIRECT_ORIGIN || !resolved.pathname.startsWith("/") || resolved.pathname.startsWith("//")) {
+        return null;
+    }
+    return path;
 }
+/** Error codes the error page may receive in its `error` query parameter. */
+const REDIRECT_ERROR_CODES = new Set([
+    "INVALID_TOKEN",
+    "EXPIRED",
+    "REVOKED",
+    "RATE_LIMITED",
+    "NETWORK_ERROR",
+    "SERVICE_UNAVAILABLE",
+    "CONFIGURATION_ERROR",
+]);
 function extractToken(req) {
     const authHeader = req.headers.get("authorization");
     if (authHeader && authHeader.toLowerCase().startsWith("bearer ")) {
@@ -62,14 +150,17 @@ function extractToken(req) {
  * 3. Per-request token auth: requests without `Authorization: Bearer` / `x-api-token` get 401
  * 4. Distinct handling for API routes (JSON + CORS) vs UI pages (redirect to `errorPath` with `from`)
  *
+ * Only `/_next/static/`, `/_next/image`, `/favicon.ico` and `bypassPaths` skip auth by default.
+ * Exclude other public files with Next's `matcher` (recommended) or opt into `staticFileExtensions`.
+ *
  * Example:
- *   // middleware.ts
+ *   // middleware.ts (Next.js 16+: proxy.ts, `export const proxy = createDaywalkerProxy();`)
  *   import { createDaywalkerMiddleware } from "@shelbyb/daywalker-sdk/next";
  *
  *   export const middleware = createDaywalkerMiddleware();
  *
  *   export const config = {
- *     matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+ *     matcher: ["/((?!_next/static|_next/image|favicon.ico|images/).*)"],
  *   };
  */
 export function createDaywalkerMiddleware(options = {}) {
@@ -96,14 +187,21 @@ function buildMiddleware(options, authenticate) {
     const errorPath = options.errorPath ?? "/service-error";
     const homePath = options.homePath ?? "/";
     const validateServerActions = options.validateServerActions ?? true;
+    const matchesExtension = extensionMatcher(options.staticFileExtensions);
+    const normalizedErrorPath = normalizePathname(errorPath) ?? errorPath;
     return async function middleware(request) {
         const url = new URL(request.url);
-        const pathname = url.pathname;
+        const rawPathname = url.pathname;
         const search = url.search;
-        // Host header validation if allowedHosts configured
+        // Routing decisions use the decoded, normalized path (`/%61pi/x` is `/api/x`). A path that
+        // cannot be normalized safely (encoded slashes, bad encoding) is never bypassed and is treated
+        // as an API route, so it is authenticated even with `protectApiOnly`.
+        const pathname = normalizePathname(rawPathname);
+        const isApi = pathname === null || isApiPath(pathname);
+        // Host header validation if allowedHosts configured; a missing Host is refused too.
         if (options.allowedHosts && options.allowedHosts.length > 0) {
-            const host = request.headers.get("host")?.toLowerCase().replace(/:\d+$/, "");
-            if (host && !options.allowedHosts.some((h) => h.toLowerCase() === host)) {
+            const host = request.headers.get("host")?.trim().toLowerCase().replace(/:\d+$/, "");
+            if (!host || !options.allowedHosts.some((h) => h.toLowerCase() === host)) {
                 return Response.json({ error: "Forbidden", message: "Invalid host header." }, { status: 403 });
             }
         }
@@ -115,7 +213,8 @@ function buildMiddleware(options, authenticate) {
             }
         }
         // 1. Bypass static files and health check probes
-        if (bypassPaths.some((path) => pathname === path || pathname.startsWith(`${path}/`)) || isStaticAssetPath(pathname)) {
+        if (pathname !== null &&
+            (bypassPaths.some((path) => pathname === path || pathname.startsWith(`${path}/`)) || isStaticNormalized(pathname, matchesExtension))) {
             return globalThis.NextResponse?.next
                 ? globalThis.NextResponse.next()
                 : new Response(null, { headers: { "x-middleware-next": "1" } });
@@ -123,7 +222,7 @@ function buildMiddleware(options, authenticate) {
         // 2. Authenticate (caller's token, or the service key for the health gate)
         const authResult = await authenticate(request);
         // 3. Handle service error page route
-        if (pathname === errorPath) {
+        if (pathname === normalizedErrorPath) {
             if (authResult.ok) {
                 // Authorized again: heal/redirect back to home
                 const redirectUrl = new URL(homePath, request.url);
@@ -138,20 +237,21 @@ function buildMiddleware(options, authenticate) {
         }
         // 4. Handle invalid token for all other routes
         if (!authResult.ok) {
+            const failure = toAuthFailureResponse(authResult);
             // API routes: return JSON error response
-            if (pathname.startsWith("/api/")) {
+            if (isApi) {
                 return Response.json({
-                    error: authResult.error || "Unauthorized",
-                    message: authResult.message || "Service authorization check failed with Daywalker Auth.",
-                    retryAfter: authResult.retryAfter,
+                    error: failure.error,
+                    message: failure.message || "Service authorization check failed with Daywalker Auth.",
+                    retryAfter: failure.retryAfter,
                 }, {
-                    status: authResult.status || 401,
+                    status: failure.status,
                     headers: {
                         "Content-Type": "application/json",
                         "Access-Control-Allow-Origin": "*",
                         "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
                         "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Api-Token",
-                        ...(authResult.retryAfter ? { "Retry-After": String(authResult.retryAfter) } : {}),
+                        ...(failure.retryAfter ? { "Retry-After": String(failure.retryAfter) } : {}),
                     },
                 });
             }
@@ -161,13 +261,14 @@ function buildMiddleware(options, authenticate) {
                     ? globalThis.NextResponse.next()
                     : new Response(null, { headers: { "x-middleware-next": "1" } });
             }
-            // Web UI routes: redirect to diagnostic service error screen
+            // Web UI routes: redirect to diagnostic service error screen. Only a fixed error code and
+            // status are passed: the free-text message may carry server details and would let anyone
+            // put arbitrary text on the error page via a crafted link.
             const redirectUrl = new URL(errorPath, request.url);
-            redirectUrl.searchParams.set("error", authResult.error || "Unauthorized");
-            redirectUrl.searchParams.set("message", authResult.message || "Service authorization check failed.");
-            redirectUrl.searchParams.set("status", String(authResult.status || 401));
-            if (pathname !== "/" || search) {
-                const rawTarget = `${pathname}${search}`;
+            redirectUrl.searchParams.set("error", REDIRECT_ERROR_CODES.has(failure.error) ? failure.error : "UNAUTHORIZED");
+            redirectUrl.searchParams.set("status", String(failure.status));
+            if (rawPathname !== "/" || search) {
+                const rawTarget = `${rawPathname}${search}`;
                 const sanitized = sanitizeRedirectPath(rawTarget);
                 if (sanitized) {
                     redirectUrl.searchParams.set("from", sanitized);
@@ -185,7 +286,8 @@ function buildMiddleware(options, authenticate) {
 /**
  * Next.js App Router route handler wrapper with Daywalker token validation.
  * Extracts `Authorization: Bearer <token>` or `x-api-token`, validates via client,
- * returns 401/429 JSON response on error, or passes validated `auth` payload in context.
+ * returns a JSON error on failure (401 bad token, 429 rate limited, 503 Daywalker Auth unavailable,
+ * 500 misconfiguration), or passes validated `auth` payload in context.
  *
  * Example:
  *   // app/api/protected/route.ts
@@ -207,9 +309,10 @@ export function withDaywalkerAuth(handler, clientOrOptions) {
         }
         const result = await client.validateToken(token, { serviceSlug });
         if (!result.ok) {
-            return Response.json({ error: result.error, message: result.message, retryAfter: result.retryAfter }, {
-                status: result.status === 429 ? 429 : 401,
-                headers: result.retryAfter ? { "Retry-After": String(result.retryAfter) } : undefined,
+            const { status, ...body } = toAuthFailureResponse(result);
+            return Response.json(body, {
+                status,
+                headers: body.retryAfter ? { "Retry-After": String(body.retryAfter) } : undefined,
             });
         }
         const mergedContext = {
@@ -219,3 +322,14 @@ export function withDaywalkerAuth(handler, clientOrOptions) {
         return handler(req, mergedContext);
     };
 }
+/**
+ * Next.js 16 renamed `middleware.ts` to `proxy.ts` (export `proxy` instead of `middleware`).
+ * These aliases are identical to the `*Middleware` factories, which remain supported:
+ *
+ *   // proxy.ts
+ *   import { createDaywalkerProxy } from "@shelbyb/daywalker-sdk/next";
+ *   export const proxy = createDaywalkerProxy();
+ *   export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
+ */
+export const createDaywalkerProxy = createDaywalkerMiddleware;
+export const createDaywalkerServiceHealthProxy = createDaywalkerServiceHealthMiddleware;

package/dist/openfeature/server.d.ts

@@ -15,6 +15,9 @@ export declare class DevPulseServerProvider implements Provider {
     readonly runsOn: "server";
     readonly events: OpenFeatureEventEmitter;
     readonly client: DevPulseNodeClient;
+    /** Only a client this provider created is closed by onClose(); an injected one belongs to the caller. */
+    private readonly ownsClient;
+    private readonly detach;
     constructor(sdkKeyOrClient: string | DevPulseNodeClient, options?: NodeClientOptions);
     initialize(): Promise<void>;
     onClose(): Promise<void>;

package/dist/openfeature/server.js

@@ -13,15 +13,27 @@ export class DevPulseServerProvider {
     runsOn = "server";
     events = new OpenFeatureEventEmitter();
     client;
+    /** Only a client this provider created is closed by onClose(); an injected one belongs to the caller. */
+    ownsClient;
+    detach;
     constructor(sdkKeyOrClient, options) {
+        this.ownsClient = typeof sdkKeyOrClient === "string";
         this.client = typeof sdkKeyOrClient === "string" ? init(sdkKeyOrClient, options) : sdkKeyOrClient;
-        this.client.on("update", ({ key }) => this.events.emit(ProviderEvents.ConfigurationChanged, { flagsChanged: [key] }));
+        const onUpdate = ({ key }) => this.events.emit(ProviderEvents.ConfigurationChanged, { flagsChanged: [key] });
+        // Before initialization a failure rejects initialize() instead, which OpenFeature reports itself.
+        const onFailed = (err) => this.client.isInitialized && this.events.emit(ProviderEvents.Error, { message: err?.message ?? "DevPulse client failed" });
+        const onStale = (err) => this.events.emit(ProviderEvents.Stale, { message: err?.message ?? "DevPulse connection lost; serving last known flags" });
+        const onRecovered = () => this.events.emit(ProviderEvents.Ready);
+        this.client.on("update", onUpdate).on("failed", onFailed).on("stale", onStale).on("recovered", onRecovered);
+        this.detach = () => void this.client.off("update", onUpdate).off("failed", onFailed).off("stale", onStale).off("recovered", onRecovered);
     }
     async initialize() {
         await this.client.waitForInitialization();
     }
     async onClose() {
-        await this.client.close();
+        this.detach();
+        if (this.ownsClient)
+            await this.client.close();
     }
     resolve(key, def, ctx, type) {
         const detail = this.client.variationDetailSync(key, toDevPulseContext(ctx), def);

package/dist/openfeature/shared.d.ts

@@ -10,7 +10,7 @@ type Detail<T> = {
     reason: Reason;
 };
 /**
- * OpenFeature context → DevPulse context. `targetingKey` becomes the key;
+ * OpenFeature context → DevPulse context. Dates become ISO 8601 strings. `targetingKey` becomes the key;
  * `kind` selects the context kind (default "user"); multi-kind contexts pass through.
  */
 export declare function toDevPulseContext(ctx: EvaluationContext): Record<string, unknown>;

package/dist/openfeature/shared.js

@@ -1,10 +1,30 @@
 import { ErrorCode, StandardResolutionReasons } from "@openfeature/core";
 /**
- * OpenFeature context → DevPulse context. `targetingKey` becomes the key;
+ * OpenFeature context values may be Dates; DevPulse compares RFC 3339 strings (or epoch ms) for
+ * `before`/`after`, so Dates become ISO strings at any depth (invalid Dates are dropped).
+ */
+function toJsonValue(v) {
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? undefined : v.toISOString();
+    if (Array.isArray(v))
+        return v.map(toJsonValue);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const [k, x] of Object.entries(v)) {
+            const j = toJsonValue(x);
+            if (j !== undefined)
+                out[k] = j;
+        }
+        return out;
+    }
+    return v;
+}
+/**
+ * OpenFeature context → DevPulse context. Dates become ISO 8601 strings. `targetingKey` becomes the key;
  * `kind` selects the context kind (default "user"); multi-kind contexts pass through.
  */
 export function toDevPulseContext(ctx) {
-    const { targetingKey, ...rest } = ctx;
+    const { targetingKey, ...rest } = toJsonValue(ctx);
     if (rest.kind === "multi")
         return rest;
     return { ...rest, kind: typeof rest.kind === "string" ? rest.kind : "user", key: targetingKey ?? rest.key };

package/dist/openfeature/web.js

@@ -20,9 +20,15 @@ export class DevPulseWebProvider {
         this.options = options;
     }
     async initialize(context) {
-        this.client = createClient(this.clientSideId, toDevPulseContext(context ?? {}), { ...this.options, withReasons: true });
-        this.client.on("change", (changes) => this.events.emit(ProviderEvents.ConfigurationChanged, { flagsChanged: Object.keys(changes) }));
-        await this.client.waitForInitialization();
+        void this.client?.close(); // re-initialized: don't leak the previous client
+        const client = createClient(this.clientSideId, toDevPulseContext(context ?? {}), { ...this.options, withReasons: true });
+        this.client = client;
+        client.on("change", (changes) => this.events.emit(ProviderEvents.ConfigurationChanged, { flagsChanged: Object.keys(changes) }));
+        // Before initialization a failure rejects initialize() instead, which OpenFeature reports itself.
+        client.on("failed", (err) => client.isInitialized && this.events.emit(ProviderEvents.Error, { message: err?.message ?? "DevPulse client failed" }));
+        client.on("stale", (err) => this.events.emit(ProviderEvents.Stale, { message: err?.message ?? "DevPulse stream lost; serving last known flags" }));
+        client.on("recovered", () => this.events.emit(ProviderEvents.Ready));
+        await client.waitForInitialization();
     }
     async onContextChange(_old, next) {
         await this.client?.identify(toDevPulseContext(next));

package/dist/types.d.ts

@@ -15,7 +15,13 @@ export interface TokenPayload {
     offlineVerified?: boolean;
     [key: string]: unknown;
 }
-export type ValidateErrorCode = "EXPIRED" | "REVOKED" | "INVALID_TOKEN" | "RATE_LIMITED" | "NETWORK_ERROR" | "CONFIGURATION_ERROR" | string;
+export type ValidateErrorCode = "EXPIRED" | "REVOKED" | "INVALID_TOKEN" | "RATE_LIMITED" | "NETWORK_ERROR" | "SERVICE_UNAVAILABLE" | "CONFIGURATION_ERROR" | string;
+/**
+ * Failures that say nothing about the token: Daywalker Auth was unreachable, timed out, answered 5xx
+ * or answered with something that isn't a validation result. Both carry status 503 and are never cached;
+ * adapters should answer 503 rather than 401 for them.
+ */
+export declare const UNAVAILABLE_ERROR_CODES: readonly ValidateErrorCode[];
 export type ValidateResult = {
     ok: true;
     data: TokenPayload;
@@ -26,6 +32,9 @@ export type ValidateResult = {
     message: string;
     retryAfter?: number;
 };
+export interface PublicJwks {
+    keys: PublicJwk[];
+}
 export interface PublicJwk {
     kty: "OKP";
     crv: "Ed25519";
@@ -43,19 +52,38 @@ export interface SigningKey {
 export interface RetryOptions {
     maxRetries?: number;
     initialDelayMs?: number;
+    /** Cap on the exponential backoff delay. Default 30000ms. */
     maxDelayMs?: number;
     backoffFactor?: number;
     jitter?: boolean;
+    /**
+     * Longest `Retry-After` honored on a 429 (default 60000ms). A longer one is not waited out:
+     * the 429 response is returned to the caller.
+     */
+    maxRetryAfterMs?: number;
+    /**
+     * Retry after network errors / timeouts. Defaults to true only for GET, HEAD and OPTIONS (or when an
+     * `idempotencyKey` is given), since the server may already have processed a request whose response was lost.
+     */
+    retryNetworkErrors?: boolean;
 }
 export interface DaywalkerConfig {
     apiKey?: string;
     signingKey?: string | SigningKey;
+    /**
+     * Previous private key during rotation (env DAYWALKER_SIGNING_KEY_PREVIOUS). Never used to sign; its public
+     * JWK is published by `keys()` next to the current one so requests from instances still on the old key verify.
+     */
     previousSigningKey?: string | SigningKey;
     keyId?: string;
     serviceSlug?: string;
     domain?: string;
-    daywalkerPublicKey?: string | PublicJwk;
-    /** Expected `iss` of offline-verified JWT leases (env DAYWALKER_LEASE_ISSUER). Unchecked when unset. */
+    /** A JWK, a JWKS (`{ keys: [...] }`, selected by the lease's `kid`), PEM, or Base64 SPKI / raw key. */
+    daywalkerPublicKey?: string | PublicJwk | PublicJwks;
+    /**
+     * Expected `iss` of offline-verified JWT leases (env DAYWALKER_LEASE_ISSUER). Daywalker documents no fixed
+     * issuer, so `iss` is unchecked when unset; set it whenever leases from other issuers could share your key.
+     */
     leaseIssuer?: string;
     /** Must be https:// (http:// only for localhost). */
     authUrl?: string;
@@ -63,7 +91,10 @@ export interface DaywalkerConfig {
     /** Short cache for failed validations (not 429/network errors). Default 3000ms; 0 disables. */
     negativeCacheTtlMs?: number;
     maxRetries?: number;
+    /** Defaults for `fetch()` retries; per-request `init.retry` overrides individual fields. */
     retry?: RetryOptions;
+    /** Per-attempt timeout for requests to Daywalker Auth. Default 5000ms; 0 disables. */
+    timeoutMs?: number;
     fetch?: typeof fetch;
     env?: Record<string, string | undefined>;
 }
@@ -85,6 +116,7 @@ export interface SignedHeaders {
 }
 export interface SignRequestParams {
     method: string;
+    /** Request target path; a query string (`/a?b=1`) is split off and covered as "@query". */
     path: string;
     authority: string;
     body?: string | Uint8Array | null;
@@ -92,19 +124,39 @@ export interface SignRequestParams {
     created?: number;
     keyid?: string;
     alg?: string;
+    /** Sets `Authorization: Bearer <apiKey>` on the returned headers (not covered by the signature). */
     apiKey?: string;
+    /** Must be 1-128 of `[A-Za-z0-9_.-]` so it can't inject Signature-Input parameters. */
     nonce?: string;
 }
+/**
+ * Remembers verified request signatures until they expire. The default in-memory store is per process:
+ * deployments with several instances must pass a shared store (e.g. Redis `SET key 1 NX PX ttl`), or a
+ * signature replayed against another instance is accepted there.
+ */
+export interface ReplayStore {
+    /** True when `key` was recorded and has not expired yet. */
+    has(key: string): boolean | Promise<boolean>;
+    /**
+     * Atomically records `key` for `ttlMs` if it is absent. Returns false when the key is already present or
+     * the store can't take it (e.g. full); the signature is then rejected.
+     */
+    record(key: string, ttlMs: number): boolean | Promise<boolean>;
+}
 export interface VerifySignatureParams {
     method: string;
+    /** Request target path, including any query string (covered as "@query"). */
     path: string;
     authority: string;
     headers: Record<string, string | undefined> | Headers;
     body?: string | Uint8Array | null;
-    publicKey: PublicJwk | CryptoKey | string;
+    /** A JWK, a JWKS (selected by the signature's `keyid`), a CryptoKey, PEM or Base64 key. */
+    publicKey: PublicJwk | PublicJwks | CryptoKey | string;
     currentTime?: number;
     maxClockSkewSeconds?: number;
     replayCheck?: boolean;
+    /** Where verified signatures are remembered; defaults to a per-process in-memory cache. */
+    replayStore?: ReplayStore;
 }
 export interface VerifySignatureResult {
     valid: boolean;

package/dist/types.js

@@ -1,4 +1,10 @@
 import { redactSecrets } from "./crypto/encoding.js";
+/**
+ * Failures that say nothing about the token: Daywalker Auth was unreachable, timed out, answered 5xx
+ * or answered with something that isn't a validation result. Both carry status 503 and are never cached;
+ * adapters should answer 503 rather than 401 for them.
+ */
+export const UNAVAILABLE_ERROR_CODES = Object.freeze(["SERVICE_UNAVAILABLE", "NETWORK_ERROR"]);
 export class DaywalkerError extends Error {
     status;
     code;

package/docs/analytics.md

@@ -27,6 +27,6 @@ await analytics.shutdown();
 
 Add each flag's value to events (for breakdowns by variation) with `flags: client` where `client` is a `@shelbyb/daywalker-sdk/flags` instance (anything with `allFlags()`).
 
-Options: `autocapturePageviews` (default true), `flushAt` (20), `flushInterval` (2s browser / 10s Node), `maxQueueSize` (1000), `persistence` (`localStorage` | `memory`), `sessionTimeoutMinutes` (30), `respectDoNotTrack`, `optedOut` (consent), `captureFullUrls` (default false: URLs drop the fragment and all query parameters except `utm_*`, `gclid`, `fbclid`, `ref`), `onError`. `host` must be `https://` except on localhost.
+Options: `autocapturePageviews` (default true), `flushAt` (20), `flushInterval` (2s browser / 10s Node), `maxQueueSize` (1000), `persistence` (`localStorage` | `memory`), `sessionTimeoutMinutes` (30), `respectDoNotTrack`, `optedOut` (consent; opting out also drops events already queued), `captureFullUrls` (default false: URLs drop the fragment and all query parameters except `utm_*`, `gclid`, `fbclid`, `ref`), `sanitizePath` (rewrite paths that carry secrets, e.g. `(p) => p.replace(/^\/reset\/[^/]+/, "/reset/:token")`), `onError`. `host` must be `https://` except on localhost.
 
 Events are sent to `POST {host}/a/batch`, which also accepts PostHog's capture format.

package/docs/flags-node.md

@@ -46,4 +46,4 @@ See `@shelbyb/daywalker-sdk/flags/react` for the `Providers` component.
 
 ## API
 
-`variation` / `variationDetail` (async) and `variationSync` / `variationDetailSync`, typed helpers (`boolVariation`, …), `allFlagsState(context, { clientSideOnly, withReasons })`, `secureModeHash(context)`, `track`, `identify`, `on("ready" | "failed" | "update" | "update:<key>")`, `flush()`, `close()`.
+`variation` / `variationDetail` (async) and `variationSync` / `variationDetailSync`, typed helpers (`boolVariation`, …), `allFlagsState(context, { clientSideOnly, withReasons })` (`clientSideOnly` defaults to `true`, so server-only flags never reach a browser bootstrap), `secureModeHash(context)`, `track`, `identify`, `on("ready" | "failed" | "update" | "update:<key>" | "stale" | "recovered")`, `flush()`, `close()`.

package/docs/flags.md

@@ -43,6 +43,7 @@ Only flags marked **Available to client-side SDKs** are visible.
 | `sendEvents` | `true` | Analytics for insights and experiments |
 | `privateAttributes` / `allAttributesPrivate` | — | Attributes never sent to DevPulse |
 | `cache` | `false` | Persist the last flags in `localStorage` and use them while loading |
+| `offline` | `false` | Serve only `bootstrap`/cached values and open no connection (tests, server rendering) |
 
 ## Contexts
 
@@ -50,4 +51,4 @@ Single kind: `{ kind: "user", key: "u1", plan: "pro" }`. Multi-kind: `{ kind: "m
 
 ## API
 
-`variation(key, default)`, `variationDetail(key, default)`, `boolVariation` / `stringVariation` / `numberVariation` / `jsonVariation`, `allFlags()`, `identify(context)`, `track(key, data?, metricValue?)`, `on("ready" | "failed" | "change" | "change:<key>", fn)`, `flush()`, `close()`.
+`variation(key, default)`, `variationDetail(key, default)`, `boolVariation` / `stringVariation` / `numberVariation` / `jsonVariation`, `allFlags()`, `identify(context)`, `track(key, data?, metricValue?)`, `on("ready" | "failed" | "change" | "change:<key>" | "stale" | "recovered", fn)` (`stale`: the stream dropped and the last flags keep serving; `recovered`: it reconnected), `flush()`, `close()`.