@shelbyb/daywalker-sdk 0.2.0 → 0.4.0

package/dist/flags/react.js

@@ -1,26 +1,47 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { createClient } from "./client.js";
 const ClientContext = createContext(null);
 const isBrowser = typeof window !== "undefined";
 /**
- * Provides a DevPulse client to the tree. On the server (SSR/RSC streaming)
- * no network connection is opened; flags come from `options.bootstrap`, so the
- * first client render matches the server HTML. Changing `context` calls identify().
+ * Provides a DevPulse client to the tree. On the server (SSR/RSC streaming) and during the
+ * first client render, an offline client serves `options.bootstrap` and makes no requests, so
+ * hydration matches the server HTML. The live client is created (and closed) in an effect,
+ * which keeps StrictMode's simulated unmount from leaving a closed client behind. Changing
+ * `context` calls identify().
  */
 export function DevPulseProvider({ clientSideId, context, options, client: external, children }) {
-    const [client] = useState(() => external ?? createClient(clientSideId, context, isBrowser ? options : { ...options, streaming: false, sendEvents: false, bootstrap: options.bootstrap ?? {} }));
     const contextJson = JSON.stringify(context);
-    const first = useRef(true);
+    // Render-time stand-in: no network, timers or listeners, so creating it during render is safe.
+    // No localStorage cache either, so the first client render matches the server HTML.
+    const [placeholder] = useState(() => createClient(clientSideId, context, { ...options, offline: true, sendEvents: false, cache: false }));
+    const [owned, setOwned] = useState(null);
+    const latest = useRef({ contextJson, options });
+    latest.current = { contextJson, options };
     useEffect(() => {
-        if (first.current) {
-            first.current = false;
+        if (external || !isBrowser)
             return;
-        }
-        void client.identify(JSON.parse(contextJson));
-    }, [client, contextJson]);
-    useEffect(() => () => void (!external && client.close()), [client, external]);
-    return _jsx(ClientContext.Provider, { value: client, children: children });
+        const c = createClient(clientSideId, JSON.parse(latest.current.contextJson), latest.current.options);
+        setOwned(c);
+        return () => {
+            void c.close();
+            setOwned((cur) => (cur === c ? null : cur));
+        };
+    }, [external, clientSideId]);
+    const live = external ?? owned;
+    const seen = useRef({ client: null, contextJson });
+    useEffect(() => {
+        if (!live || live.isClosed)
+            return;
+        const prev = seen.current;
+        seen.current = { client: live, contextJson };
+        // A client we just created already has the current context; an injected one is taken as is.
+        const changed = prev.client === live ? prev.contextJson !== contextJson : live === owned && JSON.stringify(live.getContext()) !== contextJson;
+        if (changed)
+            void live.identify(JSON.parse(contextJson)).catch(() => undefined);
+    }, [live, owned, contextJson]);
+    return _jsx(ClientContext.Provider, { value: live ?? placeholder, children: children });
 }
 export function useDevPulseClient() {
     const client = useContext(ClientContext);
@@ -39,8 +60,17 @@ export function useFlagDetail(key, defaultValue) {
     // Snapshot is the serialized value so useSyncExternalStore sees stable identities.
     const snapshot = () => JSON.stringify(client.allFlags()[key] ?? null);
     const serialized = useSyncExternalStore(subscribe, snapshot, snapshot);
-    // Record the evaluation (analytics) once per distinct value.
-    return useMemo(() => client.variationDetail(key, JSON.parse(defaultJson)), [client, key, defaultJson, serialized]); // eslint-disable-line react-hooks/exhaustive-deps
+    const detail = useMemo(() => client.peekVariationDetail(key, JSON.parse(defaultJson)), [client, key, defaultJson, serialized]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Record the evaluation (analytics) after commit, once per distinct result: renders can be
+    // repeated or thrown away (StrictMode, concurrent rendering), effects re-run in StrictMode.
+    const recorded = useRef(null);
+    useEffect(() => {
+        if (recorded.current === detail)
+            return;
+        recorded.current = detail;
+        client.recordEvaluation(key, JSON.parse(defaultJson), detail);
+    }, [client, key, defaultJson, detail]);
+    return detail;
 }
 /** All flag values; re-renders when any flag changes. */
 export function useFlags() {
@@ -55,8 +85,8 @@ export function useFlagsReady() {
     const subscribe = useMemo(() => (cb) => client.on("ready", cb), [client]);
     return useSyncExternalStore(subscribe, () => client.isInitialized, () => client.isInitialized);
 }
-/** Track a custom event for metrics and experiments. */
+/** Track a custom event for metrics and experiments. Stable across renders (safe in effect deps). */
 export function useTrack() {
     const client = useDevPulseClient();
-    return (key, data, metricValue) => client.track(key, data, metricValue);
+    return useCallback((key, data, metricValue) => client.track(key, data, metricValue), [client]);
 }

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { Daywalker, createDaywalker, daywalker, } from "./client.js";
-export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, } from "./types.js";
-export type { DaywalkerConfig, RateLimitWindow, TokenPayload, ValidateErrorCode, ValidateResult, RetryOptions, SelfCheckResult, PublicJwk, SigningKey, } from "./types.js";
-export { resolveConfig, publicHostname, } from "./config.js";
+export { Daywalker, createDaywalker, daywalker, MAX_RETRY_AFTER_MS, MAX_VALIDATION_CACHE_ENTRIES, } from "./client.js";
+export type { DaywalkerFetchInit, } from "./client.js";
+export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, UNAVAILABLE_ERROR_CODES, } from "./types.js";
+export type { DaywalkerConfig, RateLimitWindow, TokenPayload, ValidateErrorCode, ValidateResult, RetryOptions, SelfCheckResult, PublicJwk, PublicJwks, SigningKey, } from "./types.js";
+export { resolveConfig, publicHostname, assertSecureUrl, DEFAULT_TIMEOUT_MS, } from "./config.js";
 export type { ResolvedConfig, } from "./config.js";
-export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";
-export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, } from "./crypto/index.js";
+export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";
+export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, ReplayStore, } from "./crypto/index.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Daywalker, createDaywalker, daywalker, } from "./client.js";
-export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, } from "./types.js";
-export { resolveConfig, publicHostname, } from "./config.js";
-export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";
+export { Daywalker, createDaywalker, daywalker, MAX_RETRY_AFTER_MS, MAX_VALIDATION_CACHE_ENTRIES, } from "./client.js";
+export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, UNAVAILABLE_ERROR_CODES, } from "./types.js";
+export { resolveConfig, publicHostname, assertSecureUrl, DEFAULT_TIMEOUT_MS, } from "./config.js";
+export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";

package/dist/middleware.d.ts

@@ -1,4 +1,22 @@
 import { Daywalker } from "./client.js";
+import type { ValidateResult } from "./types.js";
+type ValidateFailure = Extract<ValidateResult, {
+    ok: false;
+}>;
+export interface AuthFailureResponse {
+    /** 401 bad/expired/missing token, 429 rate limited, 500 server misconfiguration, 503 auth service unavailable. */
+    status: 401 | 429 | 500 | 503;
+    error: string;
+    message: string;
+    retryAfter?: number;
+}
+/**
+ * Maps a failed validation to the HTTP status an adapter should answer with. Outages (5xx,
+ * network errors, SERVICE_UNAVAILABLE) become 503 rather than 401 so clients retry instead of
+ * discarding a valid token; configuration errors become a 500 without their (internal) details.
+ * Shared by the Next, Web/Hono and Express adapters.
+ */
+export declare function toAuthFailureResponse(result: ValidateFailure): AuthFailureResponse;
 export interface DaywalkerMiddlewareOptions {
     client?: Daywalker;
     serviceSlug?: string;

package/dist/middleware.js

@@ -1,4 +1,30 @@
 import { daywalker } from "./client.js";
+/** Error codes that mean Daywalker Auth itself could not be reached or is degraded. */
+const UNAVAILABLE_ERROR_CODES = new Set(["NETWORK_ERROR", "SERVICE_UNAVAILABLE"]);
+/**
+ * Maps a failed validation to the HTTP status an adapter should answer with. Outages (5xx,
+ * network errors, SERVICE_UNAVAILABLE) become 503 rather than 401 so clients retry instead of
+ * discarding a valid token; configuration errors become a 500 without their (internal) details.
+ * Shared by the Next, Web/Hono and Express adapters.
+ */
+export function toAuthFailureResponse(result) {
+    const retryAfter = result.retryAfter && result.retryAfter > 0 ? result.retryAfter : undefined;
+    if (result.error === "CONFIGURATION_ERROR") {
+        return { status: 500, error: "CONFIGURATION_ERROR", message: "Authentication is not configured correctly on this server." };
+    }
+    if (result.status === 429 || result.error === "RATE_LIMITED") {
+        return { status: 429, error: "RATE_LIMITED", message: result.message || "Rate limit exceeded", retryAfter };
+    }
+    if (result.status >= 500 || result.status === 0 || UNAVAILABLE_ERROR_CODES.has(result.error)) {
+        return {
+            status: 503,
+            error: UNAVAILABLE_ERROR_CODES.has(result.error) ? result.error : "SERVICE_UNAVAILABLE",
+            message: "Daywalker Auth is temporarily unavailable. Please retry.",
+            retryAfter,
+        };
+    }
+    return { status: 401, error: result.error || "INVALID_TOKEN", message: result.message || "Unauthorized" };
+}
 /**
  * Standard Web / Hono compatible middleware.
  * Works with Hono, standard Web Request/Response routers, and middleware pipelines.
@@ -46,13 +72,8 @@ export function daywalkerAuth(options = {}) {
         }
         const result = await client.validateToken(token, { serviceSlug });
         if (!result.ok) {
-            const status = result.status === 429 ? 429 : 401;
-            const body = {
-                error: result.error,
-                message: result.message,
-                retryAfter: result.retryAfter,
-            };
-            const headers = result.retryAfter ? { "Retry-After": String(result.retryAfter) } : undefined;
+            const { status, ...body } = toAuthFailureResponse(result);
+            const headers = body.retryAfter ? { "Retry-After": String(body.retryAfter) } : undefined;
             if (typeof c?.json === "function") {
                 return c.json(body, status, headers);
             }

package/dist/next.d.ts

@@ -7,19 +7,55 @@ import type { TokenPayload } from "./types.js";
  */
 export declare const SERVER_ACTION_ID_PATTERN: RegExp;
 export declare const DEFAULT_BYPASS_PATHS: string[];
+/**
+ * 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 declare const STATIC_FILE_EXTENSIONS: RegExp;
+/**
+ * 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 declare function normalizePathname(pathname: string): string | null;
+/**
+ * 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 declare function isStaticAssetPath(pathname: string, staticFileExtensions?: RegExp | readonly string[]): boolean;
 export interface NextMiddlewareOptions {
     client?: Daywalker;
     serviceSlug?: string;
+    /**
+     * Public paths that skip auth (exact match or `path/` prefix, compared against the decoded,
+     * normalized pathname). Defaults to `DEFAULT_BYPASS_PATHS`. Prefer Next's `matcher` config to keep
+     * public routes from reaching the middleware at all.
+     */
     bypassPaths?: string[];
+    /**
+     * Opt-in: also skip auth for (non-`/api`, non-`/_next/`) paths ending in one of these extensions,
+     * e.g. `STATIC_FILE_EXTENSIONS` or `["png", "css"]`. Off by default, because a dynamic route such
+     * as `/users/[id]` also answers `/users/123.js`. Prefer a `matcher` that excludes `public/` files.
+     */
+    staticFileExtensions?: RegExp | readonly string[];
     errorPath?: string;
     homePath?: string;
+    /** Only enforce auth on `/api` and `/api/*`; other routes pass through. */
     protectApiOnly?: boolean;
     validateServerActions?: boolean;
+    /** When set, requests whose Host header is missing or not listed get a 403. */
     allowedHosts?: string[];
 }
+/** Options for the Next.js 16+ `proxy.ts` aliases (identical to `NextMiddlewareOptions`). */
+export type NextProxyOptions = NextMiddlewareOptions;
 /**
  * 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 declare function sanitizeRedirectPath(path: string): string | null;
 /**
@@ -28,24 +64,34 @@ export declare function sanitizeRedirectPath(path: string): string | null;
  * Implements:
  * 1. Server Action probe defense (CVE-2025-55182 scanner mitigation)
  * 2. Static asset and health check bypass
- * 3. Self-healing service error page routing with `from` back-redirect
- * 4. Distinct handling for API routes (JSON + CORS) vs UI pages (redirect)
+ * 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 declare function createDaywalkerMiddleware(options?: NextMiddlewareOptions): (request: Request) => Promise<Response>;
+/**
+ * Service health gate: checks this service's own DAYWALKER_API_KEY (not the caller's token) and
+ * routes every request to `errorPath` while it is invalid, redirecting back once it heals.
+ * It does NOT authenticate callers; use `createDaywalkerMiddleware` or `withDaywalkerAuth` for that.
+ */
+export declare function createDaywalkerServiceHealthMiddleware(options?: NextMiddlewareOptions): (request: Request) => Promise<Response>;
 /**
  * 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
@@ -61,3 +107,14 @@ export declare function withDaywalkerAuth<Context extends Record<string, unknown
     client?: Daywalker;
     serviceSlug?: string;
 }): (req: Request, context?: Context) => Promise<Response>;
+/**
+ * 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 declare const createDaywalkerProxy: typeof createDaywalkerMiddleware;
+export declare const createDaywalkerServiceHealthProxy: typeof createDaywalkerServiceHealthMiddleware;

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,19 +13,123 @@ export const DEFAULT_BYPASS_PATHS = [
     "/robots.txt",
     "/sitemap.xml",
 ];
+/**
+ * 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;
+/**
+ * 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 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 (isBuiltInStaticPath(pathname))
+        return true;
+    if (pathname.startsWith("/_next/"))
+        return false;
+    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);
+    }
+    catch {
+        return null;
+    }
+    if (resolved.origin !== REDIRECT_ORIGIN || !resolved.pathname.startsWith("/") || resolved.pathname.startsWith("//")) {
         return null;
     }
-    return clean;
+    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 ")) {
@@ -42,33 +147,61 @@ function extractToken(req) {
  * Implements:
  * 1. Server Action probe defense (CVE-2025-55182 scanner mitigation)
  * 2. Static asset and health check bypass
- * 3. Self-healing service error page routing with `from` back-redirect
- * 4. Distinct handling for API routes (JSON + CORS) vs UI pages (redirect)
+ * 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 = {}) {
     const client = options.client ?? daywalker;
+    return buildMiddleware(options, async (request) => {
+        const token = extractToken(request);
+        if (!token) {
+            return { ok: false, error: "INVALID_TOKEN", status: 401, message: "Missing Authorization header or x-api-token" };
+        }
+        return client.validateToken(token, { serviceSlug: options.serviceSlug });
+    });
+}
+/**
+ * Service health gate: checks this service's own DAYWALKER_API_KEY (not the caller's token) and
+ * routes every request to `errorPath` while it is invalid, redirecting back once it heals.
+ * It does NOT authenticate callers; use `createDaywalkerMiddleware` or `withDaywalkerAuth` for that.
+ */
+export function createDaywalkerServiceHealthMiddleware(options = {}) {
+    const client = options.client ?? daywalker;
+    return buildMiddleware(options, () => client.validateServiceKey({ serviceSlug: options.serviceSlug }));
+}
+function buildMiddleware(options, authenticate) {
     const bypassPaths = options.bypassPaths ?? DEFAULT_BYPASS_PATHS;
     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 });
             }
         }
@@ -80,20 +213,18 @@ export function createDaywalkerMiddleware(options = {}) {
             }
         }
         // 1. Bypass static files and health check probes
-        if (bypassPaths.some((path) => pathname === path || pathname.startsWith(`${path}/`)) ||
-            pathname.startsWith("/_next") ||
-            (pathname.includes(".") && !pathname.endsWith(".json"))) {
+        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" } });
         }
-        // 2. Validate token (from request header, or service's configured DAYWALKER_API_KEY)
-        const incomingToken = extractToken(request);
-        const authResult = await client.validateToken(incomingToken ? { token: incomingToken, serviceSlug: options.serviceSlug } : { serviceSlug: options.serviceSlug });
+        // 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) {
-                // If the service token is now valid, heal/redirect back to home or referer
+                // Authorized again: heal/redirect back to home
                 const redirectUrl = new URL(homePath, request.url);
                 return globalThis.NextResponse?.redirect
                     ? globalThis.NextResponse.redirect(redirectUrl)
@@ -106,20 +237,21 @@ export function createDaywalkerMiddleware(options = {}) {
         }
         // 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) } : {}),
                     },
                 });
             }
@@ -129,13 +261,14 @@ export function createDaywalkerMiddleware(options = {}) {
                     ? 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);
@@ -153,7 +286,8 @@ export function createDaywalkerMiddleware(options = {}) {
 /**
  * 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
@@ -175,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 = {
@@ -187,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>;