@daloyjs/core 0.36.0 → 0.37.0

package/dist/fetch-resilience.js

@@ -0,0 +1,485 @@
+/**
+ * `resilientFetch()` — circuit breaker, retry-with-backoff, and per-call
+ * timeout for outbound `fetch`, designed to layer **on top of**
+ * {@link fetchGuard} (which only covers SSRF on egress).
+ *
+ * `fetchGuard()` answers "is this outbound address safe?". This module
+ * answers "is this upstream healthy, and how do we behave when it is
+ * not?" — the operational half of a mature outbound HTTP client
+ * (timeouts that prevent a hung upstream from exhausting your event
+ * loop, bounded retries that ride out a blip without amplifying an
+ * outage, and a circuit breaker that fails fast when an upstream is
+ * clearly down). The two compose: wrap an SSRF-guarded fetch in a
+ * resilient one and you get both safety and resilience with zero runtime
+ * dependencies.
+ *
+ * ```ts
+ * import { fetchGuard, resilientFetch } from "@daloyjs/core";
+ *
+ * const safeFetch = resilientFetch({
+ *   fetch: fetchGuard(),       // SSRF floor underneath
+ *   timeoutMs: 2_000,          // abort any call that stalls past 2s
+ *   retries: 2,                // up to 2 retries on transient failures
+ *   circuitBreaker: { failureThreshold: 5, resetTimeoutMs: 30_000 },
+ * });
+ *
+ * const res = await safeFetch("https://api.example.com/things");
+ * ```
+ *
+ * ## Design notes
+ *
+ * - **Per-call timeout** is enforced with an `AbortController` that is
+ *   combined with any caller-supplied `signal`, so cancellation works in
+ *   both directions. A timeout surfaces as {@link FetchTimeoutError}; a
+ *   caller-initiated abort surfaces as the caller's own `AbortError` and
+ *   is **never** retried or counted as an upstream failure.
+ * - **Retry-with-backoff** only retries idempotent methods
+ *   (`GET`/`HEAD`/`OPTIONS`/`PUT`/`DELETE`) and a conservative set of
+ *   transient statuses (`408`, `429`, `500`, `502`, `503`, `504`) plus
+ *   network errors and timeouts. Backoff is exponential with full
+ *   jitter and honours a `Retry-After` header when present. A
+ *   {@link SsrfBlockedError} is treated as a hard refusal — never
+ *   retried, never trips the breaker.
+ * - **Circuit breaker** is a classic three-state machine
+ *   (`closed → open → half-open`). Consecutive failures past the
+ *   threshold open the circuit; while open every call fails fast with
+ *   {@link CircuitOpenError} until `resetTimeoutMs` elapses, after which
+ *   a limited number of trial requests probe the upstream. The breaker
+ *   is shared across every call made through the returned function, so a
+ *   single hot upstream is protected process-wide.
+ *
+ * @module
+ * @since 0.37.0
+ */
+/**
+ * Thrown by {@link resilientFetch} (and {@link CircuitBreaker.execute})
+ * when the circuit is open and the call is refused without hitting the
+ * network. Distinct from a network failure so callers can render a
+ * dedicated "service temporarily unavailable" path.
+ *
+ * @since 0.37.0
+ */
+export class CircuitOpenError extends Error {
+    /** Milliseconds until the breaker will next allow a trial request. */
+    retryAfterMs;
+    constructor(retryAfterMs) {
+        super(`circuit breaker is open; retry in ~${Math.max(0, Math.round(retryAfterMs))}ms`);
+        this.name = "CircuitOpenError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * Thrown by {@link resilientFetch} when a single attempt exceeds the
+ * configured `timeoutMs`. A caller-initiated abort (via a `signal`
+ * passed in the request init) surfaces as the caller's own `AbortError`
+ * instead and is never retried.
+ *
+ * @since 0.37.0
+ */
+export class FetchTimeoutError extends Error {
+    /** The timeout that was exceeded, in milliseconds. */
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`outbound fetch timed out after ${timeoutMs}ms`);
+        this.name = "FetchTimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * A standalone three-state circuit breaker. {@link resilientFetch}
+ * builds on this, but it is exported for callers who want to protect a
+ * non-`fetch` dependency (a database driver, a gRPC client, …) with the
+ * same semantics.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker({ failureThreshold: 3 });
+ * const rows = await breaker.execute(() => db.query("SELECT 1"));
+ * ```
+ *
+ * @since 0.37.0
+ */
+export class CircuitBreaker {
+    #failureThreshold;
+    #resetTimeoutMs;
+    #halfOpenMaxAttempts;
+    #successThreshold;
+    #onStateChange;
+    #now;
+    #state = "closed";
+    #failureCount = 0;
+    #successCount = 0;
+    #openedAt = 0;
+    #halfOpenInFlight = 0;
+    constructor(options = {}) {
+        const failureThreshold = options.failureThreshold ?? 5;
+        const resetTimeoutMs = options.resetTimeoutMs ?? 30_000;
+        const halfOpenMaxAttempts = options.halfOpenMaxAttempts ?? 1;
+        const successThreshold = options.successThreshold ?? 1;
+        if (!Number.isInteger(failureThreshold) || failureThreshold < 1) {
+            throw new RangeError("CircuitBreaker: failureThreshold must be a positive integer");
+        }
+        if (!Number.isFinite(resetTimeoutMs) || resetTimeoutMs < 0) {
+            throw new RangeError("CircuitBreaker: resetTimeoutMs must be a non-negative number");
+        }
+        if (!Number.isInteger(halfOpenMaxAttempts) || halfOpenMaxAttempts < 1) {
+            throw new RangeError("CircuitBreaker: halfOpenMaxAttempts must be a positive integer");
+        }
+        if (!Number.isInteger(successThreshold) || successThreshold < 1) {
+            throw new RangeError("CircuitBreaker: successThreshold must be a positive integer");
+        }
+        this.#failureThreshold = failureThreshold;
+        this.#resetTimeoutMs = resetTimeoutMs;
+        this.#halfOpenMaxAttempts = halfOpenMaxAttempts;
+        this.#successThreshold = successThreshold;
+        if (options.onStateChange)
+            this.#onStateChange = options.onStateChange;
+        this.#now = options.now ?? Date.now;
+    }
+    /** The breaker's current state, after applying any pending timeout. */
+    get state() {
+        if (this.#state === "open" && this.#now() - this.#openedAt >= this.#resetTimeoutMs) {
+            return "half-open";
+        }
+        return this.#state;
+    }
+    /** Milliseconds until the breaker will next admit a trial request. */
+    get retryAfterMs() {
+        if (this.#state !== "open")
+            return 0;
+        return Math.max(0, this.#resetTimeoutMs - (this.#now() - this.#openedAt));
+    }
+    #transition(next) {
+        const previous = this.#state;
+        if (previous === next)
+            return;
+        this.#state = next;
+        if (next === "open")
+            this.#openedAt = this.#now();
+        if (next === "closed") {
+            this.#failureCount = 0;
+            this.#successCount = 0;
+            this.#halfOpenInFlight = 0;
+        }
+        if (next === "half-open") {
+            this.#successCount = 0;
+            this.#halfOpenInFlight = 0;
+        }
+        this.#onStateChange?.(next, previous);
+    }
+    /** Reserve a slot, throwing {@link CircuitOpenError} if none is free. */
+    #admit() {
+        if (this.#state === "open") {
+            if (this.#now() - this.#openedAt >= this.#resetTimeoutMs) {
+                this.#transition("half-open");
+            }
+            else {
+                throw new CircuitOpenError(this.retryAfterMs);
+            }
+        }
+        if (this.#state === "half-open") {
+            if (this.#halfOpenInFlight >= this.#halfOpenMaxAttempts) {
+                throw new CircuitOpenError(this.retryAfterMs);
+            }
+            this.#halfOpenInFlight++;
+        }
+    }
+    #onSuccess() {
+        if (this.#state === "half-open") {
+            this.#halfOpenInFlight = Math.max(0, this.#halfOpenInFlight - 1);
+            this.#successCount++;
+            if (this.#successCount >= this.#successThreshold) {
+                this.#transition("closed");
+            }
+            return;
+        }
+        this.#failureCount = 0;
+    }
+    #onFailure() {
+        if (this.#state === "half-open") {
+            this.#halfOpenInFlight = Math.max(0, this.#halfOpenInFlight - 1);
+            this.#transition("open");
+            return;
+        }
+        this.#failureCount++;
+        if (this.#failureCount >= this.#failureThreshold) {
+            this.#transition("open");
+        }
+    }
+    /**
+     * Run `fn` under breaker supervision. Throws {@link CircuitOpenError}
+     * immediately when the circuit is open. A thrown error (other than
+     * `CircuitOpenError`) counts as a failure; a returned value counts as
+     * a success. Use {@link recordOutcome} from {@link resilientFetch}
+     * when an HTTP *response* (not a thrown error) should count as a
+     * failure.
+     */
+    async execute(fn) {
+        this.#admit();
+        try {
+            const result = await fn();
+            this.#onSuccess();
+            return result;
+        }
+        catch (err) {
+            if (err instanceof CircuitOpenError)
+                throw err;
+            this.#onFailure();
+            throw err;
+        }
+    }
+    /**
+     * Record an externally-determined outcome. Lets a caller treat a
+     * non-throwing result (e.g. an HTTP 503 response) as a failure while
+     * still flowing the value back. Returns nothing; pair with an explicit
+     * {@link admit}/{@link release} when you need full manual control.
+     */
+    recordOutcome(success) {
+        if (success)
+            this.#onSuccess();
+        else
+            this.#onFailure();
+    }
+    /**
+     * Reserve a breaker slot for a manually-supervised call. Throws
+     * {@link CircuitOpenError} if the circuit will not admit the call.
+     * Must be paired with exactly one {@link recordOutcome} or
+     * {@link release}.
+     */
+    admit() {
+        this.#admit();
+    }
+    /**
+     * Release a slot reserved by {@link admit} without recording a success
+     * or failure. Use for outcomes that are not an upstream health signal
+     * (a caller-initiated abort, an SSRF refusal). Counts and state are
+     * left untouched aside from freeing a half-open probe slot.
+     */
+    release() {
+        if (this.#state === "half-open") {
+            this.#halfOpenInFlight = Math.max(0, this.#halfOpenInFlight - 1);
+        }
+    }
+}
+const DEFAULT_RETRYABLE_METHODS = ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"];
+const DEFAULT_RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504];
+const DEFAULT_BREAKER_FAILURE_STATUSES = [500, 502, 503, 504];
+/** Abortable sleep that resolves early (without throwing) if cancelled. */
+function defaultSleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        if (signal) {
+            if (signal.aborted) {
+                clearTimeout(timer);
+                resolve();
+                return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        // Do not keep the event loop alive solely for a backoff timer.
+        timer.unref?.();
+    });
+}
+/** Parse a `Retry-After` header (delta-seconds or HTTP-date) to ms. */
+function parseRetryAfter(value, now) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - now);
+    }
+    return undefined;
+}
+/**
+ * Combine a caller-supplied signal with a fresh timeout signal. Returns
+ * the merged signal plus a `cleanup` to clear the timer / listeners and
+ * a `timedOut` flag so the caller can distinguish our timeout from the
+ * caller's own abort.
+ */
+function withTimeout(timeoutMs, external) {
+    const controller = new AbortController();
+    let timedOut = false;
+    let timer;
+    const onExternalAbort = () => {
+        controller.abort(external.reason);
+    };
+    if (external) {
+        if (external.aborted) {
+            controller.abort(external.reason);
+        }
+        else {
+            external.addEventListener("abort", onExternalAbort, { once: true });
+        }
+    }
+    if (timeoutMs > 0 && !controller.signal.aborted) {
+        timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        timer.unref?.();
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            if (timer)
+                clearTimeout(timer);
+            external?.removeEventListener("abort", onExternalAbort);
+        },
+        timedOut: () => timedOut,
+    };
+}
+function isAbortError(err) {
+    return err instanceof Error && err.name === "AbortError";
+}
+/**
+ * Wrap a `fetch` with per-call timeout, retry-with-backoff, and a shared
+ * circuit breaker. The returned function has the same call signature as
+ * the global `fetch`.
+ *
+ * Layer it over {@link fetchGuard} to keep SSRF protection underneath:
+ *
+ * ```ts
+ * const safeFetch = resilientFetch({ fetch: fetchGuard(), timeoutMs: 2_000 });
+ * ```
+ *
+ * @since 0.37.0
+ */
+export function resilientFetch(options = {}) {
+    const baseFetch = options.fetch ?? globalThis.fetch;
+    if (typeof baseFetch !== "function") {
+        throw new Error("resilientFetch(): no global fetch available; pass options.fetch.");
+    }
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const retries = options.retries ?? 2;
+    const retryDelayMs = options.retryDelayMs ?? 100;
+    const maxRetryDelayMs = options.maxRetryDelayMs ?? 2_000;
+    const backoffFactor = options.backoffFactor ?? 2;
+    const jitter = options.jitter ?? true;
+    const respectRetryAfter = options.respectRetryAfter ?? true;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new RangeError("resilientFetch(): timeoutMs must be a non-negative number");
+    }
+    if (!Number.isInteger(retries) || retries < 0) {
+        throw new RangeError("resilientFetch(): retries must be a non-negative integer");
+    }
+    const retryMethods = new Set((options.retryableMethods ?? DEFAULT_RETRYABLE_METHODS).map((m) => m.toUpperCase()));
+    const retryStatuses = new Set(options.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES);
+    const breakerFailureStatuses = new Set(options.circuitBreakerFailureStatuses ?? DEFAULT_BREAKER_FAILURE_STATUSES);
+    const sleep = options.sleep ?? defaultSleep;
+    let breaker;
+    if (options.circuitBreaker !== false) {
+        breaker =
+            options.circuitBreaker instanceof CircuitBreaker
+                ? options.circuitBreaker
+                : new CircuitBreaker(options.circuitBreaker ?? {});
+    }
+    function backoffFor(attempt, response) {
+        if (respectRetryAfter && response) {
+            const fromHeader = parseRetryAfter(response.headers.get("retry-after"), Date.now());
+            if (fromHeader !== undefined)
+                return Math.min(maxRetryDelayMs, fromHeader);
+        }
+        const exp = retryDelayMs * backoffFactor ** (attempt - 1);
+        const capped = Math.min(maxRetryDelayMs, exp);
+        // Backoff jitter is a load-spreading heuristic, not a security primitive;
+        // a non-cryptographic PRNG is the correct, conventional choice here.
+        return jitter ? Math.random() * capped : capped; // daloy-allow-weak-random: backoff jitter is not a security primitive
+    }
+    function shouldRetry(ctx) {
+        if (options.isRetryable)
+            return options.isRetryable(ctx);
+        if (!retryMethods.has(ctx.request.method.toUpperCase()))
+            return false;
+        if (ctx.response)
+            return retryStatuses.has(ctx.response.status);
+        return true; // network error / timeout on an idempotent method
+    }
+    const resilient = async (input, init) => {
+        // Materialise once so method/headers are stable across retries and
+        // the caller's signal can be combined per attempt.
+        const request = new Request(input, init);
+        const callerSignal = init?.signal ?? request.signal;
+        const run = async () => {
+            let lastError;
+            for (let attempt = 1; attempt <= retries + 1; attempt++) {
+                const { signal, cleanup, timedOut } = withTimeout(timeoutMs, callerSignal);
+                let response;
+                try {
+                    // Clone the request per attempt so a consumed body can be re-sent.
+                    response = await baseFetch(request.clone(), { signal });
+                }
+                catch (err) {
+                    cleanup();
+                    // Caller cancelled: never retry, never count as upstream failure.
+                    if (isAbortError(err) && callerSignal?.aborted)
+                        throw err;
+                    // An SSRF refusal from an underlying fetchGuard is a hard, terminal
+                    // decision about the request itself — never retried.
+                    if (err instanceof Error && err.name === "SsrfBlockedError")
+                        throw err;
+                    // Our timeout fired.
+                    lastError = timedOut() && isAbortError(err) ? new FetchTimeoutError(timeoutMs) : err;
+                    const ctx = { attempt, request, error: lastError };
+                    if (attempt <= retries && shouldRetry(ctx)) {
+                        const delay = backoffFor(attempt);
+                        options.onRetry?.(ctx, delay);
+                        await sleep(delay, callerSignal ?? undefined);
+                        if (callerSignal?.aborted)
+                            throw lastError;
+                        continue;
+                    }
+                    throw lastError;
+                }
+                cleanup();
+                const ctx = { attempt, request, response };
+                if (attempt <= retries && shouldRetry(ctx)) {
+                    const delay = backoffFor(attempt, response);
+                    options.onRetry?.(ctx, delay);
+                    await sleep(delay, callerSignal ?? undefined);
+                    if (callerSignal?.aborted)
+                        return response;
+                    continue;
+                }
+                return response;
+            }
+            // Unreachable: the loop always returns or throws.
+            throw lastError;
+        };
+        if (!breaker)
+            return run();
+        // Supervise with the breaker. A retryable-but-exhausted server-error
+        // response must count as a failure, so we admit/record manually.
+        breaker.admit();
+        try {
+            const response = await run();
+            breaker.recordOutcome(!breakerFailureStatuses.has(response.status));
+            return response;
+        }
+        catch (err) {
+            // SSRF refusals and caller aborts are not upstream health signals.
+            if (err instanceof CircuitOpenError)
+                throw err;
+            const isCallerAbort = isAbortError(err) && callerSignal?.aborted;
+            const isSsrf = err instanceof Error && err.name === "SsrfBlockedError";
+            if (isCallerAbort || isSsrf)
+                breaker.release();
+            else
+                breaker.recordOutcome(false);
+            throw err;
+        }
+    };
+    return resilient;
+}

package/dist/geo-block.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Country-level access control for {@link Hooks}. The {@link geoBlock}
+ * middleware enforces ISO 3166-1 alpha-2 country allow- and deny-lists by
+ * mapping the client IP to a country **using an operator-supplied lookup** —
+ * Daloy bundles no GeoIP database and adds no runtime dependency, keeping the
+ * `@daloyjs/core` zero-dependency floor intact.
+ *
+ * Two resolution strategies are supported, exactly one of which must be wired:
+ *
+ * - `lookupCountry(ip)` — you own the IP → country mapping (e.g. a MaxMind
+ *   GeoLite2 reader, an `ip2location` reader, or your own table). Daloy
+ *   resolves the client IP (reusing the same `X-Forwarded-For` / `X-Real-IP`
+ *   handling as {@link "./ip-restriction.js".ipRestriction}) and hands you the
+ *   string.
+ * - `resolveCountry(ctx)` — the country is already attached to the request by
+ *   an upstream edge (e.g. Cloudflare's `CF-IPCountry`, AWS CloudFront's
+ *   `CloudFront-Viewer-Country`, Vercel's `x-vercel-ip-country`); you read it
+ *   straight off the context.
+ *
+ * Like the other network guards this fails **closed for allow-lists** (an
+ * unknown country is rejected when an allow-list is configured) and **open for
+ * deny-only** configurations, so a missing lookup cannot silently widen access.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/**
+ * Why a request was (or would have been) blocked by {@link geoBlock}.
+ *
+ * - `"denied_country"` — the resolved country is on the `deny` list.
+ * - `"not_in_allowlist"` — an `allow` list is configured and the resolved
+ *   country is not on it.
+ * - `"unknown_country"` — the country could not be resolved and
+ *   `allowUnknownCountry` was `false`.
+ *
+ * @since 0.37.0
+ */
+export type GeoBlockReason = "denied_country" | "not_in_allowlist" | "unknown_country";
+/**
+ * The decision {@link geoBlock} reached for a request, passed to `onBlock` and
+ * stamped (for allowed requests) on `ctx.state[stateKey]`.
+ *
+ * @since 0.37.0
+ */
+export interface GeoBlockDecision {
+    /** Resolved client IP, when the `lookupCountry` strategy was used. */
+    readonly ip?: string;
+    /** Resolved ISO 3166-1 alpha-2 country code (upper-cased), if known. */
+    readonly country?: string;
+    /** Why the request was blocked. */
+    readonly reason: GeoBlockReason;
+}
+/**
+ * Country code resolved from the client context (e.g. an edge-injected
+ * header). Return `undefined`/`null`/`""` when the country is unknown.
+ *
+ * @since 0.37.0
+ */
+export type CountryFromContext = (ctx: BaseContext<any, any>) => string | undefined | null | Promise<string | undefined | null>;
+/**
+ * Operator-supplied IP → country lookup (e.g. a MaxMind reader). Return
+ * `undefined`/`null`/`""` when the IP cannot be mapped to a country.
+ *
+ * @since 0.37.0
+ */
+export type CountryFromIp = (ip: string) => string | undefined | null | Promise<string | undefined | null>;
+/**
+ * What to record on `ctx.state[stateKey]` for an allowed request.
+ *
+ * @since 0.37.0
+ */
+export interface GeoState {
+    /** Resolved ISO 3166-1 alpha-2 country code (upper-cased), if known. */
+    readonly country?: string;
+}
+/**
+ * Options for {@link geoBlock}. At least one of `allow` or `deny` must be a
+ * non-empty list, and exactly one of `lookupCountry` or `resolveCountry` must
+ * be provided.
+ *
+ * @since 0.37.0
+ */
+export interface GeoBlockOptions {
+    /**
+     * ISO 3166-1 alpha-2 country codes (case-insensitive) that are allowed.
+     * When non-empty, any request whose resolved country is not on this list is
+     * rejected. An unknown country is rejected too unless
+     * `allowUnknownCountry` is set.
+     */
+    allow?: readonly string[];
+    /**
+     * ISO 3166-1 alpha-2 country codes (case-insensitive) that are always
+     * rejected. A `deny` match wins over an `allow` match (least privilege).
+     */
+    deny?: readonly string[];
+    /**
+     * Operator-supplied IP → country mapping. Mutually exclusive with
+     * `resolveCountry`. Daloy resolves the client IP first (see `resolveIp` /
+     * `trustProxyHeaders`) and passes it to this function.
+     */
+    lookupCountry?: CountryFromIp;
+    /**
+     * Read the country straight off the request context (e.g. an edge header
+     * such as `CF-IPCountry`). Mutually exclusive with `lookupCountry`.
+     */
+    resolveCountry?: CountryFromContext;
+    /**
+     * Override the source of the client IP for the `lookupCountry` strategy. By
+     * default Daloy fails closed because Web-standard `Request` objects do not
+     * expose the peer address. Ignored when `resolveCountry` is used.
+     */
+    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    /**
+     * Read `X-Forwarded-For` / `X-Real-IP` in the default IP resolver. Defaults
+     * to `false` because those headers are client-spoofable unless every
+     * request reaches Daloy through a proxy chain you control. Ignored when
+     * `resolveCountry` is used or a custom `resolveIp` is supplied.
+     */
+    trustProxyHeaders?: boolean;
+    /**
+     * What to do when the country cannot be resolved. Defaults to `false` when
+     * an `allow` list is configured (fail closed — an unknown country is not on
+     * the allow-list) and `true` for deny-only configurations (fail open). Set
+     * explicitly to override.
+     */
+    allowUnknownCountry?: boolean;
+    /**
+     * `"block"` (default) rejects with HTTP `403`; `"log"` lets the request
+     * through after invoking `onBlock`, for safe rollout / monitoring.
+     */
+    mode?: "block" | "log";
+    /**
+     * Response message when a request is rejected. Defaults to
+     * `"Access from your region is not permitted"`. Avoid echoing the country
+     * or IP — doing so can leak topology to attackers.
+     */
+    message?: string;
+    /**
+     * Observability hook invoked for every blocked (or, in `"log"` mode,
+     * would-be-blocked) request. Never receives allowed requests.
+     */
+    onBlock?: (decision: GeoBlockDecision) => void;
+    /**
+     * `ctx.state` key under which the resolved {@link GeoState} is stamped for
+     * allowed requests. Defaults to `"geo"`.
+     */
+    stateKey?: string;
+}
+/**
+ * Block or allow requests by client country. Daloy ships no GeoIP database;
+ * supply either an IP → country `lookupCountry` (e.g. a MaxMind reader) or a
+ * `resolveCountry` that reads an edge-injected country header.
+ *
+ * @example MaxMind-style IP lookup behind a trusted proxy
+ * ```ts
+ * import maxmind from "maxmind"; // operator dependency, not a Daloy one
+ * const reader = await maxmind.open<{ country?: { iso_code?: string } }>("GeoLite2-Country.mmdb");
+ * app.use(geoBlock({
+ *   deny: ["KP", "IR"],
+ *   trustProxyHeaders: true,
+ *   lookupCountry: (ip) => reader.get(ip)?.country?.iso_code,
+ * }));
+ * ```
+ *
+ * @example Cloudflare edge header (no IP lookup needed)
+ * ```ts
+ * app.use(geoBlock({
+ *   allow: ["US", "CA", "GB"],
+ *   resolveCountry: (ctx) => ctx.request.headers.get("cf-ipcountry"),
+ * }));
+ * ```
+ *
+ * On reject the middleware throws a {@link ForbiddenError}, which Daloy renders
+ * as RFC 9457 `application/problem+json` with `Cache-Control: no-store`.
+ *
+ * @param opts - Geo-blocking configuration.
+ * @returns {@link Hooks} to register via `app.use(...)`.
+ * @throws Error when neither `allow` nor `deny` is provided, when both or
+ *   neither of `lookupCountry` / `resolveCountry` are provided, when a country
+ *   code is malformed, or when `mode` is invalid.
+ * @since 0.37.0
+ */
+export declare function geoBlock(opts: GeoBlockOptions): Hooks;