@daloyjs/core 0.36.0 → 0.37.0

package/dist/index.js

@@ -6,8 +6,9 @@ export { _resetInsecureDefaultsLogForTests } from "./app.js";
 export { getConnInfo, setConnInfo, assertBehindProxy, resolveClientIp, readRemoteAddress, readRemotePort, pickForwardedForByHops, } from "./conn-info.js";
 export { subdomains, PSL_SNAPSHOT_DATE, PSL_PUBLIC_SUFFIXES, MAX_SNAPSHOT_AGE_DAYS, } from "./subdomains.js";
 export { defineDependency, DEPENDENCY_MARKER } from "./dependency.js";
-export { HttpError, BadRequestError, ValidationError, NotFoundError, UnauthorizedError, ForbiddenError, MethodNotAllowedError, PayloadTooLargeError, UnsupportedMediaTypeError, TooManyRequestsError, RequestTimeoutError, InternalError, MessageLeakError, httpError, SAFE_CUSTOM_ERROR_RESPONSE_HEADERS, checkCustomErrorResponseHeaders, } from "./errors.js";
+export { HttpError, BadRequestError, ValidationError, NotFoundError, ConflictError, UnauthorizedError, ForbiddenError, MethodNotAllowedError, PayloadTooLargeError, UnsupportedMediaTypeError, TooManyRequestsError, RequestTimeoutError, InternalError, MessageLeakError, httpError, SAFE_CUSTOM_ERROR_RESPONSE_HEADERS, checkCustomErrorResponseHeaders, } from "./errors.js";
 export { validate, isStandardSchema } from "./schema.js";
+export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
 export { readBodyLimited, safeJsonParse, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
 export { requestId, secureHeaders, SECURE_HEADERS_MARKER, cors, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, rateLimit, loginThrottle, timing, bearerAuth, basicAuth, csrf, CSRF_HOOK_MARKER, fetchMetadata, requireScopes, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, _resetSharedRateLimitStoresForTests, } from "./middleware.js";
 export { etag } from "./etag.js";
@@ -19,6 +20,18 @@ export { assertTemporalClaims, TemporalClaimError, } from "./time-claims.js";
 export { every, some, except } from "./combine.js";
 export { ipRestriction } from "./ip-restriction.js";
 export { fetchGuard, SsrfBlockedError } from "./fetch-guard.js";
+export { resilientFetch, CircuitBreaker, CircuitOpenError, FetchTimeoutError, } from "./fetch-resilience.js";
+export { createWebhookSender, MemoryWebhookDeadLetterSink, } from "./webhook-delivery.js";
+export { Scheduler, CronParseError, parseCron, nextCronRun, } from "./scheduler.js";
+export { clientCertAuth, setClientCertificate, getClientCertificate, normalizePeerCertificate, parseForwardedClientCert, } from "./mtls.js";
+export { signMessage, signRequest, verifyMessage, verifyRequest, httpSignatureAuth, contentDigest, verifyContentDigest, DEFAULT_SIGNATURE_LABEL, DEFAULT_MAX_SIGNATURE_AGE_SECONDS, DEFAULT_SIGNATURE_CLOCK_SKEW_SECONDS, } from "./http-signatures.js";
+export { autoBan, MemoryAutoBanStore, _resetAutoBanStoresForTests, } from "./auto-ban.js";
+export { botGuard, GOOGLEBOT, BINGBOT, WELL_KNOWN_BOTS } from "./bot-guard.js";
+export { ipReputation, urlFeed } from "./ip-reputation.js";
+export { geoBlock } from "./geo-block.js";
+export { concurrencyLimit } from "./concurrency-limit.js";
+export { requestDecompression, decompressRequestBody, DecompressionBombError, UnsupportedContentEncodingError, MalformedCompressedBodyError, _resetRequestDecompressionProbeForTests, } from "./request-decompression.js";
+export { waf } from "./waf.js";
 export { safeRedirect, OpenRedirectBlockedError } from "./safe-redirect.js";
 export { loadShedding, LOAD_SHEDDING_MARKER } from "./load-shedding.js";
 export { defineConfig, ConfigValidationError } from "./config.js";
@@ -28,6 +41,10 @@ export { sseStream, sseResponse, ndjsonStream, ndjsonResponse, } from "./streami
 export { httpBearerScheme, httpBasicScheme, apiKeyScheme, oauth2Scheme, openIdConnectScheme, REQUIRE_PAYLOAD_AUTH_EXTENSION, securitySchemeRequiresPayloadAuth, toOpenAPISecurityScheme, } from "./security-schemes.js";
 export { discriminator, discriminatedUnion } from "./discriminator.js";
 export { session, rotateSession, signValue, verifySignedValue, MemorySessionStore, SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
+export { idempotency, MemoryIdempotencyStore, _resetSharedIdempotencyStoresForTests, } from "./idempotency.js";
+export { responseCache, MemoryResponseCacheStore, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
+export { encodeCursor, decodeCursor, buildLinkHeader, buildPageLinks, paginationQuery, MAX_CURSOR_LENGTH, } from "./pagination.js";
+export { MetricsRegistry, Counter, Gauge, Histogram, httpMetrics, DEFAULT_DURATION_BUCKETS, PROMETHEUS_CONTENT_TYPE, } from "./metrics.js";
 export { fileField, multipartObject, isFileFieldSchema, isMultipartObjectSchema, } from "./multipart.js";
 export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACING_SPAN_STATUS_OK, TRACING_SPAN_STATUS_ERROR, } from "./tracing.js";
 export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";

package/dist/ip-reputation.d.ts

@@ -0,0 +1,198 @@
+/**
+ * IP reputation / dynamic denylist feed for {@link Hooks}. Where
+ * {@link "./ip-restriction.js".ipRestriction} enforces a *static* allow/deny
+ * list compiled once at construction, {@link ipReputation} wires **pluggable,
+ * periodically-refreshed abuse feeds** (Tor exit lists, Spamhaus DROP,
+ * cloud-abuse ranges, your own threat intel) into the request path without
+ * rebuilding the matcher.
+ *
+ * Design goals:
+ *
+ * 1. **Pluggable feeds** — any {@link IpReputationFeed} that yields IP / CIDR
+ *    strings. {@link urlFeed} ships for the common case (fetch a newline /
+ *    Spamhaus-DROP-style list over HTTP), but a feed can be backed by anything.
+ * 2. **Periodic refresh** — the denylist is reloaded on an `unref`'d timer so a
+ *    long-lived abuse range eventually expires and new ranges are picked up,
+ *    without a redeploy.
+ * 3. **Fail-open** — a denylist is *additive* defense-in-depth, never the only
+ *    gate. If a feed fails to load (initial or refresh), traffic is **not**
+ *    blocked: the last-known-good list is kept (or an empty list if nothing has
+ *    loaded yet). A feed outage must never take the whole app down.
+ *
+ * The middleware is dependency-free and runtime-portable; it reuses the
+ * SSRF-grade CIDR matcher from `ipRestriction()`. {@link urlFeed}'s default
+ * transport is the platform `fetch`; pass your own for non-standard runtimes or
+ * to layer SSRF protection.
+ *
+ * @example
+ * ```ts
+ * import { ipReputation, urlFeed } from "@daloyjs/core";
+ *
+ * const reputation = ipReputation({
+ *   trustProxyHeaders: true,
+ *   feeds: [
+ *     urlFeed("https://www.spamhaus.org/drop/drop.txt", { name: "spamhaus-drop" }),
+ *     urlFeed("https://check.torproject.org/torbulkexitlist", { name: "tor-exit" }),
+ *   ],
+ *   refreshIntervalMs: 60 * 60_000, // hourly
+ * });
+ *
+ * app.use(reputation.hooks);
+ * // On shutdown: reputation.stop();
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/**
+ * A pluggable source of abusive IP / CIDR entries. Implementations return the
+ * raw list each refresh; parsing, validation, and de-duplication are handled by
+ * {@link ipReputation}.
+ *
+ * @since 0.37.0
+ */
+export interface IpReputationFeed {
+    /** Human-readable feed name, surfaced in {@link IpReputationMatch.feed}. */
+    name: string;
+    /**
+     * Fetch the current entries. May return IP addresses or CIDR ranges as
+     * strings; invalid entries are skipped (never throw for junk lines). Honour
+     * the {@link AbortSignal} when provided.
+     *
+     * @param signal - Abort signal tied to the refresh timeout.
+     * @returns The current IP / CIDR entries.
+     */
+    fetch(signal?: AbortSignal): Promise<readonly string[]>;
+}
+/**
+ * Details of a request that matched the reputation denylist. Passed to
+ * {@link IpReputationOptions.onMatch}.
+ *
+ * @since 0.37.0
+ */
+export interface IpReputationMatch {
+    /** The resolved client IP. */
+    ip: string;
+    /** Names of the feeds whose entries matched. */
+    feeds: readonly string[];
+}
+/**
+ * Options for {@link ipReputation}.
+ *
+ * @since 0.37.0
+ */
+export interface IpReputationOptions {
+    /** One or more abuse feeds to merge into the denylist. Required, non-empty. */
+    feeds: readonly IpReputationFeed[];
+    /**
+     * How often to reload every feed, in ms. Default 1 hour. Set `0` to disable
+     * the timer and refresh only manually via {@link IpReputationController.refresh}.
+     */
+    refreshIntervalMs?: number;
+    /**
+     * Per-refresh timeout for each feed `fetch`, in ms. Default 30 s. A feed that
+     * exceeds it is aborted and treated as a (fail-open) refresh failure.
+     */
+    fetchTimeoutMs?: number;
+    /**
+     * Load the feeds immediately at construction. Default `true`. When `false`,
+     * the first load happens on the first timer tick (or manual `refresh()`), so
+     * early requests see an empty denylist (fail-open).
+     */
+    loadOnStart?: boolean;
+    /**
+     * Custom client-IP resolver. Overrides {@link IpReputationOptions.trustProxyHeaders}.
+     * Defaults to failing open (no IP → not blocked).
+     */
+    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    /**
+     * Trust `X-Forwarded-For` / `X-Real-IP` in the default IP resolver. Only
+     * enable behind a trusted proxy that overwrites these headers.
+     */
+    trustProxyHeaders?: boolean;
+    /**
+     * `"block"` (default) throws a {@link ForbiddenError} on a match; `"log"`
+     * only invokes {@link IpReputationOptions.onMatch} and lets the request
+     * continue (monitor mode).
+     */
+    mode?: "block" | "log";
+    /** Detail string for the `403` problem+json. Default `"IP address not permitted"`. */
+    message?: string;
+    /** Called whenever a request IP is on the denylist (in both modes). */
+    onMatch?: (match: IpReputationMatch) => void;
+    /**
+     * Called when a feed fails to load or refresh. The denylist keeps its
+     * last-known-good entries (fail-open). Use it to surface feed-health metrics.
+     */
+    onError?: (error: unknown, feedName: string) => void;
+}
+/**
+ * A running IP-reputation guard. Pass {@link IpReputationController.hooks} to
+ * `app.use()`, drive refreshes manually with {@link IpReputationController.refresh},
+ * and release the timer on shutdown with {@link IpReputationController.stop}.
+ *
+ * @since 0.37.0
+ */
+export interface IpReputationController {
+    /** The middleware hooks to register via `app.use(...)`. */
+    hooks: Hooks;
+    /**
+     * Force an immediate reload of every feed. Resolves once all feeds have
+     * settled (failures are swallowed per the fail-open contract).
+     */
+    refresh(): Promise<void>;
+    /** Stop the periodic-refresh timer. Idempotent. */
+    stop(): void;
+    /** Resolves after the first load attempt completes (success or fail-open). */
+    readonly ready: Promise<void>;
+    /** Current number of compiled denylist entries across all feeds. */
+    readonly size: number;
+    /** Test whether an IP is currently on the denylist (no side effects). */
+    has(ip: string): boolean;
+}
+/**
+ * Options for {@link urlFeed}.
+ *
+ * @since 0.37.0
+ */
+export interface UrlFeedOptions {
+    /** Feed name. Defaults to the URL. */
+    name?: string;
+    /**
+     * Custom `fetch` implementation. Defaults to the platform `fetch`. Provide an
+     * SSRF-guarded fetch or a non-standard-runtime client here.
+     */
+    fetchImpl?: typeof fetch;
+    /** Extra request headers (e.g. an API token for a commercial feed). */
+    headers?: Record<string, string>;
+}
+/**
+ * Build an {@link IpReputationFeed} that fetches a newline-delimited IP / CIDR
+ * list over HTTP. Handles the Spamhaus-DROP-style `<cidr> ; <annotation>`
+ * format and `#` / `;` / `//` comment lines. Lines that aren't valid IPs/CIDRs
+ * are skipped by {@link ipReputation}, so a partially-malformed feed still loads
+ * its good entries.
+ *
+ * @param url - The feed URL.
+ * @param opts - Optional feed name, custom `fetch`, and request headers.
+ * @returns A feed ready to pass to {@link IpReputationOptions.feeds}.
+ * @since 0.37.0
+ */
+export declare function urlFeed(url: string, opts?: UrlFeedOptions): IpReputationFeed;
+/**
+ * IP reputation / dynamic denylist middleware. Merges one or more pluggable
+ * abuse feeds into a periodically-refreshed denylist and rejects (or logs)
+ * requests from listed IPs, reusing the `ipRestriction()` CIDR matcher.
+ *
+ * Fail-open by design: a feed that cannot be loaded never blocks traffic — the
+ * last-known-good list is retained (empty until the first successful load). An
+ * unresolvable client IP is also treated as not-listed.
+ *
+ * @param opts - Reputation configuration; `feeds` must be non-empty.
+ * @returns An {@link IpReputationController} whose `hooks` go to `app.use(...)`.
+ * @throws Error when `feeds` is empty, `mode` is invalid, or a numeric option
+ *   is out of range.
+ * @since 0.37.0
+ */
+export declare function ipReputation(opts: IpReputationOptions): IpReputationController;

package/dist/ip-reputation.js

@@ -0,0 +1,253 @@
+/**
+ * IP reputation / dynamic denylist feed for {@link Hooks}. Where
+ * {@link "./ip-restriction.js".ipRestriction} enforces a *static* allow/deny
+ * list compiled once at construction, {@link ipReputation} wires **pluggable,
+ * periodically-refreshed abuse feeds** (Tor exit lists, Spamhaus DROP,
+ * cloud-abuse ranges, your own threat intel) into the request path without
+ * rebuilding the matcher.
+ *
+ * Design goals:
+ *
+ * 1. **Pluggable feeds** — any {@link IpReputationFeed} that yields IP / CIDR
+ *    strings. {@link urlFeed} ships for the common case (fetch a newline /
+ *    Spamhaus-DROP-style list over HTTP), but a feed can be backed by anything.
+ * 2. **Periodic refresh** — the denylist is reloaded on an `unref`'d timer so a
+ *    long-lived abuse range eventually expires and new ranges are picked up,
+ *    without a redeploy.
+ * 3. **Fail-open** — a denylist is *additive* defense-in-depth, never the only
+ *    gate. If a feed fails to load (initial or refresh), traffic is **not**
+ *    blocked: the last-known-good list is kept (or an empty list if nothing has
+ *    loaded yet). A feed outage must never take the whole app down.
+ *
+ * The middleware is dependency-free and runtime-portable; it reuses the
+ * SSRF-grade CIDR matcher from `ipRestriction()`. {@link urlFeed}'s default
+ * transport is the platform `fetch`; pass your own for non-standard runtimes or
+ * to layer SSRF protection.
+ *
+ * @example
+ * ```ts
+ * import { ipReputation, urlFeed } from "@daloyjs/core";
+ *
+ * const reputation = ipReputation({
+ *   trustProxyHeaders: true,
+ *   feeds: [
+ *     urlFeed("https://www.spamhaus.org/drop/drop.txt", { name: "spamhaus-drop" }),
+ *     urlFeed("https://check.torproject.org/torbulkexitlist", { name: "tor-exit" }),
+ *   ],
+ *   refreshIntervalMs: 60 * 60_000, // hourly
+ * });
+ *
+ * app.use(reputation.hooks);
+ * // On shutdown: reputation.stop();
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { ForbiddenError } from "./errors.js";
+import { compileCidrMatcher, matchesMatcher, parseIp, } from "./ip-restriction.js";
+const DEFAULT_REFRESH_MS = 60 * 60_000;
+const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
+const DEFAULT_MESSAGE = "IP address not permitted";
+/**
+ * Split a single feed line into its IP / CIDR token, stripping comments and the
+ * trailing annotations common to abuse feeds (e.g. Spamhaus DROP's
+ * `1.2.3.0/24 ; SBL123`). Returns `undefined` for comment-only / blank lines.
+ *
+ * @internal
+ */
+function parseFeedLine(line) {
+    let s = line.trim();
+    if (!s || s.startsWith("#") || s.startsWith(";") || s.startsWith("//")) {
+        return undefined;
+    }
+    // Cut inline comments / annotations after the address token.
+    const cut = s.search(/[\s;#]/);
+    if (cut !== -1)
+        s = s.slice(0, cut);
+    return s || undefined;
+}
+/**
+ * Build an {@link IpReputationFeed} that fetches a newline-delimited IP / CIDR
+ * list over HTTP. Handles the Spamhaus-DROP-style `<cidr> ; <annotation>`
+ * format and `#` / `;` / `//` comment lines. Lines that aren't valid IPs/CIDRs
+ * are skipped by {@link ipReputation}, so a partially-malformed feed still loads
+ * its good entries.
+ *
+ * @param url - The feed URL.
+ * @param opts - Optional feed name, custom `fetch`, and request headers.
+ * @returns A feed ready to pass to {@link IpReputationOptions.feeds}.
+ * @since 0.37.0
+ */
+export function urlFeed(url, opts = {}) {
+    const name = opts.name ?? url;
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    return {
+        name,
+        async fetch(signal) {
+            if (typeof doFetch !== "function") {
+                throw new Error("urlFeed: no fetch implementation available on this runtime. Pass options.fetchImpl.");
+            }
+            const res = await doFetch(url, {
+                signal,
+                headers: opts.headers,
+                redirect: "follow",
+            });
+            if (!res.ok) {
+                throw new Error(`urlFeed: ${name} responded ${res.status}.`);
+            }
+            const text = await res.text();
+            const out = [];
+            for (const line of text.split("\n")) {
+                const token = parseFeedLine(line);
+                if (token !== undefined)
+                    out.push(token);
+            }
+            return out;
+        },
+    };
+}
+function forwardedIpResolver(ctx) {
+    const headers = ctx.request.headers;
+    const forwarded = headers.get("x-forwarded-for");
+    if (forwarded) {
+        const first = forwarded.split(",")[0]?.trim();
+        if (first)
+            return first;
+    }
+    return ctx.request.headers.get("x-real-ip") ?? undefined;
+}
+function noIpResolver(_ctx) {
+    return undefined;
+}
+/**
+ * IP reputation / dynamic denylist middleware. Merges one or more pluggable
+ * abuse feeds into a periodically-refreshed denylist and rejects (or logs)
+ * requests from listed IPs, reusing the `ipRestriction()` CIDR matcher.
+ *
+ * Fail-open by design: a feed that cannot be loaded never blocks traffic — the
+ * last-known-good list is retained (empty until the first successful load). An
+ * unresolvable client IP is also treated as not-listed.
+ *
+ * @param opts - Reputation configuration; `feeds` must be non-empty.
+ * @returns An {@link IpReputationController} whose `hooks` go to `app.use(...)`.
+ * @throws Error when `feeds` is empty, `mode` is invalid, or a numeric option
+ *   is out of range.
+ * @since 0.37.0
+ */
+export function ipReputation(opts) {
+    if (!opts.feeds || opts.feeds.length === 0) {
+        throw new Error("ipReputation(): at least one feed must be provided.");
+    }
+    const mode = opts.mode ?? "block";
+    if (mode !== "block" && mode !== "log") {
+        throw new Error('ipReputation(): mode must be "block" or "log".');
+    }
+    const refreshIntervalMs = opts.refreshIntervalMs ?? DEFAULT_REFRESH_MS;
+    if (!Number.isInteger(refreshIntervalMs) || refreshIntervalMs < 0) {
+        throw new Error("ipReputation(): refreshIntervalMs must be a non-negative integer.");
+    }
+    const fetchTimeoutMs = opts.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    if (!Number.isInteger(fetchTimeoutMs) || fetchTimeoutMs <= 0) {
+        throw new Error("ipReputation(): fetchTimeoutMs must be a positive integer.");
+    }
+    const message = opts.message ?? DEFAULT_MESSAGE;
+    const resolveIp = opts.resolveIp ?? (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
+    // Last-known-good compiled denylist, one entry per feed so a single feed's
+    // failed refresh doesn't drop the others.
+    let compiled = opts.feeds.map((f) => ({ name: f.name, v4: [], v6: [] }));
+    const compileFeed = (name, entries) => {
+        const v4 = [];
+        const v6 = [];
+        for (const entry of entries) {
+            let matcher;
+            try {
+                matcher = compileCidrMatcher(entry);
+            }
+            catch {
+                continue; // skip junk lines; a malformed feed still loads its good rows
+            }
+            (matcher.family === 4 ? v4 : v6).push(matcher);
+        }
+        return { name, v4, v6 };
+    };
+    const refreshOne = async (feed, index) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), fetchTimeoutMs);
+        if (typeof timer === "object" && typeof timer.unref === "function")
+            timer.unref();
+        try {
+            const entries = await feed.fetch(controller.signal);
+            compiled[index] = compileFeed(feed.name, entries);
+        }
+        catch (err) {
+            // Fail-open: keep the previous compiled entries for this feed.
+            opts.onError?.(err, feed.name);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const refresh = async () => {
+        await Promise.all(opts.feeds.map((feed, i) => refreshOne(feed, i)));
+    };
+    const matchingFeeds = (ip) => {
+        const parsed = parseIp(ip);
+        if (!parsed)
+            return [];
+        const hits = [];
+        for (const feed of compiled) {
+            const list = parsed.family === 4 ? feed.v4 : feed.v6;
+            if (list.some((m) => matchesMatcher(parsed, m)))
+                hits.push(feed.name);
+        }
+        return hits;
+    };
+    let stopped = false;
+    let interval;
+    if (refreshIntervalMs > 0) {
+        interval = setInterval(() => {
+            void refresh();
+        }, refreshIntervalMs);
+        if (typeof interval === "object" && typeof interval.unref === "function") {
+            interval.unref();
+        }
+    }
+    const ready = opts.loadOnStart === false ? Promise.resolve() : refresh();
+    return {
+        hooks: {
+            beforeHandle(ctx) {
+                const ip = resolveIp(ctx);
+                if (!ip)
+                    return undefined; // fail-open on unresolved IP
+                const feeds = matchingFeeds(ip);
+                if (feeds.length === 0)
+                    return undefined;
+                opts.onMatch?.({ ip, feeds });
+                if (mode === "block")
+                    throw new ForbiddenError(message);
+                return undefined;
+            },
+        },
+        refresh,
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (interval !== undefined)
+                clearInterval(interval);
+        },
+        get ready() {
+            return ready;
+        },
+        get size() {
+            let total = 0;
+            for (const feed of compiled)
+                total += feed.v4.length + feed.v6.length;
+            return total;
+        },
+        has(ip) {
+            return matchingFeeds(ip).length > 0;
+        },
+    };
+}

package/dist/jwk.d.ts

@@ -35,6 +35,21 @@ export interface JwkOptions {
      * when `jwks` is not a URL.
      */
     fetchTtlSeconds?: number;
+    /**
+     * Grace window (seconds) during which a *previously fetched* JWKS keeps
+     * being served if a TTL-expiry refresh fails (network error, non-2xx,
+     * or malformed body). Measured from the last successful fetch, on top of
+     * {@link fetchTtlSeconds}; a transient IdP blip therefore does not fail
+     * every request while a perfectly valid cached key set is in hand. The
+     * first fetch is never eligible (there is no last-good set to fall back
+     * to), so an unreachable IdP at boot still rejects. Tokens are always
+     * cryptographically verified and `exp`-checked regardless. Set to `0` to
+     * disable and fail closed the moment the TTL lapses. Default `3600` (1h).
+     * Ignored when `jwks` is not a URL.
+     *
+     * @since 0.41.0
+     */
+    maxStaleSeconds?: number;
     /**
      * Optional `fetch` implementation override (mainly for tests). Defaults
      * to global `fetch`.

package/dist/jwk.js

@@ -71,7 +71,7 @@ function findJwkByKid(jwks, kid) {
     }
     return undefined;
 }
-function makeJwksLoader(source, fetchImpl, ttlSeconds) {
+function makeJwksLoader(source, fetchImpl, ttlSeconds, maxStaleSeconds) {
     if (typeof source === "string") {
         if (!source.startsWith("https://")) {
             throw new Error("jwk(): jwks URL must be https:// — refusing plaintext JWKS source.");
@@ -100,6 +100,20 @@ function makeJwksLoader(source, fetchImpl, ttlSeconds) {
                     cache = { jwks: body, fetchedAt: Date.now() };
                     return body;
                 }
+                catch (err) {
+                    // Stale-while-error: a TTL-expiry refresh that fails must not take
+                    // down all auth when a last-good JWKS is still within the grace
+                    // window. Public verification keys rotate slowly; tokens remain
+                    // cryptographically verified and exp-checked either way. The first
+                    // fetch (no cache) always rethrows, so an unreachable IdP at boot
+                    // still fails closed.
+                    if (cache &&
+                        maxStaleSeconds > 0 &&
+                        Date.now() - cache.fetchedAt < (ttlSeconds + maxStaleSeconds) * 1000) {
+                        return cache.jwks;
+                    }
+                    throw err;
+                }
                 finally {
                     inflight = undefined;
                 }
@@ -168,12 +182,20 @@ export function jwk(opts) {
             throw new Error("jwk(): fetchTtlSeconds must be a non-negative finite number.");
         }
     }
+    if (opts.maxStaleSeconds !== undefined) {
+        if (typeof opts.maxStaleSeconds !== "number" ||
+            !Number.isFinite(opts.maxStaleSeconds) ||
+            opts.maxStaleSeconds < 0) {
+            throw new Error("jwk(): maxStaleSeconds must be a non-negative finite number.");
+        }
+    }
     const realm = opts.realm ?? "api";
     if (/["\r\n\0]/.test(realm)) {
         throw new Error("jwk(): realm must not contain quotes, CR, LF, or NUL bytes.");
     }
     const ttl = opts.fetchTtlSeconds ?? 300;
-    const loader = makeJwksLoader(opts.jwks, opts.fetch ?? globalThis.fetch, ttl);
+    const maxStale = opts.maxStaleSeconds ?? 3600;
+    const loader = makeJwksLoader(opts.jwks, opts.fetch ?? globalThis.fetch, ttl, maxStale);
     const algorithms = [...opts.algorithms];
     let cachedVerifier;
     let cachedJwksRef;

package/dist/load-shedding.d.ts

@@ -39,10 +39,15 @@ export interface LoadSheddingOptions {
  * @internal
  */
 export interface LoadSheddingSnapshot {
+    /** Sampled event-loop delay in milliseconds. */
     eventLoopDelayMs: number;
+    /** Sampled `heapUsed` in bytes. */
     heapUsedBytes: number;
+    /** Sampled resident set size (`rss`) in bytes. */
     rssBytes: number;
+    /** Sampled event-loop utilization in the range `[0, 1]`. */
     eventLoopUtilization: number;
+    /** Reason the request was shed, when a threshold is exceeded. */
     reason?: string;
 }
 /**

package/dist/logger.js

@@ -72,7 +72,11 @@ const JWT_LIKE_RE = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
  * conservatively to avoid false positives on ordinary identifiers.
  *
  * Sources (token formats published by each provider as of 2026):
- * - GitHub: `gh[opsur]_` 36–251 alphanumerics; `github_pat_` 40+ alnum/_
+ * - GitHub: `gh[opru]_` 36–251 alphanumerics (opaque); `ghs_` 36+ of
+ *   alnum/`.`/`-`/`_` to also cover the 2026 stateless installation-token
+ *   format (a ~520-char `ghs_`-prefixed JWT with two dots — see
+ *   <https://github.blog/changelog/2026-05-15-github-app-installation-tokens-per-request-override-header/>);
+ *   `github_pat_` 40+ alnum/_
  * - Slack:  `xox[abprs]-` legacy/bot/user/refresh tokens
  * - AWS:    `AKIA`/`ASIA` + 16 uppercase alphanumerics
  * - Stripe: `sk|rk|pk` + `_live_|_test_` + 20+ alphanumerics
@@ -82,7 +86,7 @@ const JWT_LIKE_RE = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
  * - Anthropic: `sk-ant-` + 20+ alnum/_/-
  * - OpenAI: `sk-` + 20+ alnum/_/- (matched after the `sk-ant-` form)
  */
-const CREDENTIAL_LIKE_RE = /(?:gh[opsur]_[A-Za-z0-9]{36,251}|github_pat_[A-Za-z0-9_]{40,255}|xox[abprs]-[A-Za-z0-9-]{10,}|(?:AKIA|ASIA)[A-Z0-9]{16}|(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{20,}|npm_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9_-]{20,}|AIza[A-Za-z0-9_-]{35}|sk-ant-[A-Za-z0-9_-]{20,}|sk-[A-Za-z0-9_-]{20,})/g;
+const CREDENTIAL_LIKE_RE = /(?:ghs_[A-Za-z0-9._-]{36,1024}|gh[opru]_[A-Za-z0-9]{36,251}|github_pat_[A-Za-z0-9_]{40,255}|xox[abprs]-[A-Za-z0-9-]{10,}|(?:AKIA|ASIA)[A-Z0-9]{16}|(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{20,}|npm_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9_-]{20,}|AIza[A-Za-z0-9_-]{35}|sk-ant-[A-Za-z0-9_-]{20,}|sk-[A-Za-z0-9_-]{20,})/g;
 function resolveRedaction(opt) {
     if (opt === false)
         return null;