@vivero/stoma 0.1.0-rc.10

package/dist/policies/sdk/testing.d.ts

@@ -0,0 +1,53 @@
+import * as hono_types from 'hono/types';
+import { MiddlewareHandler, Hono } from 'hono';
+import { TestAdapter } from '../../adapters/testing.js';
+import { P as Policy } from '../../protocol-2fD3DJrL.js';
+import './trace.js';
+import '@vivero/stoma-core';
+
+interface PolicyTestHarnessOptions {
+    /**
+     * Custom upstream handler. Receives the Hono context after the policy
+     * runs. Default: returns `{ ok: true }` with status 200.
+     */
+    upstream?: MiddlewareHandler;
+    /** Route path pattern for the test app. Default: `"/*"`. */
+    path?: string;
+    /** Gateway name injected into context. Default: `"test-gateway"`. */
+    gatewayName?: string;
+    /** Custom adapter to use. If not provided, a {@link TestAdapter} is created. */
+    adapter?: TestAdapter;
+}
+/**
+ * Create a minimal test app with a single policy, error handling,
+ * gateway context injection, and a configurable upstream.
+ *
+ * @example
+ * ```ts
+ * import { createPolicyTestHarness } from "@vivero/stoma/policies";
+ * import { myPolicy } from "./my-policy";
+ *
+ * const { request, adapter } = createPolicyTestHarness(myPolicy({ max: 10 }));
+ *
+ * it("should allow valid requests", async () => {
+ *   const res = await request("/test");
+ *   expect(res.status).toBe(200);
+ *   // Await any background work (e.g. waitUntil)
+ *   await adapter.waitAll();
+ * });
+ * ```
+ *
+ * @param policy - The policy instance to test.
+ * @param options - Optional upstream, path, and gateway name.
+ * @returns An object with `request()`, `app`, and the `adapter` used.
+ */
+declare function createPolicyTestHarness(policy: Policy, options?: PolicyTestHarnessOptions): {
+    /** The underlying Hono app for advanced test scenarios. */
+    app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+    /** The adapter used by the harness. Call `adapter.waitAll()` to await background tasks. */
+    adapter: TestAdapter;
+    /** Make a test request through the policy pipeline. */
+    request: (reqPath: string, init?: RequestInit) => Response | Promise<Response>;
+};
+
+export { type PolicyTestHarnessOptions, createPolicyTestHarness };

package/dist/policies/sdk/testing.js

@@ -0,0 +1,41 @@
+import { Hono } from "hono";
+import { TestAdapter } from "../../adapters/testing";
+import { errorToResponse, GatewayError } from "../../core/errors";
+import { createContextInjector } from "../../core/pipeline";
+function createPolicyTestHarness(policy, options) {
+  const path = options?.path ?? "/*";
+  const gatewayName = options?.gatewayName ?? "test-gateway";
+  const adapter = options?.adapter ?? new TestAdapter();
+  const app = new Hono();
+  app.use(
+    path,
+    createContextInjector(gatewayName, path, void 0, void 0, adapter)
+  );
+  app.use(path, async (c, next) => {
+    try {
+      await policy.handler(c, next);
+    } catch (err) {
+      if (err instanceof GatewayError) {
+        return errorToResponse(err);
+      }
+      throw err;
+    }
+  });
+  if (options?.upstream) {
+    app.all(path, options.upstream);
+  } else {
+    app.all(path, (c) => c.json({ ok: true }));
+  }
+  return {
+    /** The underlying Hono app for advanced test scenarios. */
+    app,
+    /** The adapter used by the harness. Call `adapter.waitAll()` to await background tasks. */
+    adapter,
+    /** Make a test request through the policy pipeline. */
+    request: (reqPath, init) => app.request(reqPath, init)
+  };
+}
+export {
+  createPolicyTestHarness
+};
+//# sourceMappingURL=testing.js.map

package/dist/policies/sdk/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/sdk/testing.ts"],"sourcesContent":["/**\n * Test harness for policy authors.\n *\n * Eliminates the repeated 15-line `makeApp()` boilerplate from policy\n * test files. Creates a minimal Hono app with the policy under test,\n * a GatewayError handler, gateway context injection, and a configurable\n * upstream.\n *\n * @module testing\n */\n\nimport type { MiddlewareHandler } from \"hono\";\nimport { Hono } from \"hono\";\nimport { TestAdapter } from \"../../adapters/testing\";\nimport { errorToResponse, GatewayError } from \"../../core/errors\";\nimport { createContextInjector } from \"../../core/pipeline\";\nimport type { Policy } from \"../types\";\n\nexport interface PolicyTestHarnessOptions {\n  /**\n   * Custom upstream handler. Receives the Hono context after the policy\n   * runs. Default: returns `{ ok: true }` with status 200.\n   */\n  upstream?: MiddlewareHandler;\n  /** Route path pattern for the test app. Default: `\"/*\"`. */\n  path?: string;\n  /** Gateway name injected into context. Default: `\"test-gateway\"`. */\n  gatewayName?: string;\n  /** Custom adapter to use. If not provided, a {@link TestAdapter} is created. */\n  adapter?: TestAdapter;\n}\n\n/**\n * Create a minimal test app with a single policy, error handling,\n * gateway context injection, and a configurable upstream.\n *\n * @example\n * ```ts\n * import { createPolicyTestHarness } from \"@vivero/stoma/policies\";\n * import { myPolicy } from \"./my-policy\";\n *\n * const { request, adapter } = createPolicyTestHarness(myPolicy({ max: 10 }));\n *\n * it(\"should allow valid requests\", async () => {\n *   const res = await request(\"/test\");\n *   expect(res.status).toBe(200);\n *   // Await any background work (e.g. waitUntil)\n *   await adapter.waitAll();\n * });\n * ```\n *\n * @param policy - The policy instance to test.\n * @param options - Optional upstream, path, and gateway name.\n * @returns An object with `request()`, `app`, and the `adapter` used.\n */\nexport function createPolicyTestHarness(\n  policy: Policy,\n  options?: PolicyTestHarnessOptions\n) {\n  const path = options?.path ?? \"/*\";\n  const gatewayName = options?.gatewayName ?? \"test-gateway\";\n  const adapter = options?.adapter ?? new TestAdapter();\n\n  const app = new Hono();\n\n  // 1. Inject gateway context (requestId, debug factory, etc.)\n  app.use(\n    path,\n    createContextInjector(gatewayName, path, undefined, undefined, adapter)\n  );\n\n  // 2. Run the policy with GatewayError → structured JSON handling\n  app.use(path, async (c, next) => {\n    try {\n      await policy.handler(c, next);\n    } catch (err) {\n      if (err instanceof GatewayError) {\n        return errorToResponse(err);\n      }\n      throw err;\n    }\n  });\n\n  // 3. Upstream handler\n  if (options?.upstream) {\n    app.all(path, options.upstream);\n  } else {\n    app.all(path, (c) => c.json({ ok: true }));\n  }\n\n  return {\n    /** The underlying Hono app for advanced test scenarios. */\n    app,\n    /** The adapter used by the harness. Call `adapter.waitAll()` to await background tasks. */\n    adapter,\n    /** Make a test request through the policy pipeline. */\n    request: (reqPath: string, init?: RequestInit) =>\n      app.request(reqPath, init),\n  };\n}\n"],"mappings":"AAYA,SAAS,YAAY;AACrB,SAAS,mBAAmB;AAC5B,SAAS,iBAAiB,oBAAoB;AAC9C,SAAS,6BAA6B;AAwC/B,SAAS,wBACd,QACA,SACA;AACA,QAAM,OAAO,SAAS,QAAQ;AAC9B,QAAM,cAAc,SAAS,eAAe;AAC5C,QAAM,UAAU,SAAS,WAAW,IAAI,YAAY;AAEpD,QAAM,MAAM,IAAI,KAAK;AAGrB,MAAI;AAAA,IACF;AAAA,IACA,sBAAsB,aAAa,MAAM,QAAW,QAAW,OAAO;AAAA,EACxE;AAGA,MAAI,IAAI,MAAM,OAAO,GAAG,SAAS;AAC/B,QAAI;AACF,YAAM,OAAO,QAAQ,GAAG,IAAI;AAAA,IAC9B,SAAS,KAAK;AACZ,UAAI,eAAe,cAAc;AAC/B,eAAO,gBAAgB,GAAG;AAAA,MAC5B;AACA,YAAM;AAAA,IACR;AAAA,EACF,CAAC;AAGD,MAAI,SAAS,UAAU;AACrB,QAAI,IAAI,MAAM,QAAQ,QAAQ;AAAA,EAChC,OAAO;AACL,QAAI,IAAI,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,CAAC;AAAA,EAC3C;AAEA,SAAO;AAAA;AAAA,IAEL;AAAA;AAAA,IAEA;AAAA;AAAA,IAEA,SAAS,CAAC,SAAiB,SACzB,IAAI,QAAQ,SAAS,IAAI;AAAA,EAC7B;AACF;","names":[]}

package/dist/policies/sdk/trace.d.ts

@@ -0,0 +1,73 @@
+import { Context } from 'hono';
+
+/**
+ * Policy trace - structured per-policy trace entries for deep debugging.
+ *
+ * Provides a zero-overhead reporter API (`TraceReporter`) that policies
+ * call to record what they did. When tracing is not active, the reporter
+ * is a no-op constant - no allocations, no Map lookups.
+ *
+ * @module trace
+ */
+
+/** Set by `parseDebugRequest()` when the client requests tracing. */
+declare const TRACE_REQUESTED_KEY = "_stomaTraceRequested";
+/** Array of `PolicyTraceBaseline` entries pushed by `policiesToMiddleware()`. */
+declare const TRACE_ENTRIES_KEY = "_stomaTraceEntries";
+/** Map of policy name → `PolicyTraceDetail` set by `policyTrace()`. */
+declare const TRACE_DETAILS_KEY = "_stomaTraceDetails";
+/** Auto-captured by the pipeline for every policy when tracing is active. */
+interface PolicyTraceBaseline {
+    name: string;
+    priority: number;
+    durationMs: number;
+    calledNext: boolean;
+    error: string | null;
+}
+/** Policy-reported detail (cooperative opt-in via `trace()`). */
+interface PolicyTraceDetail {
+    action: string;
+    data?: Record<string, unknown>;
+}
+/** Combined baseline + optional detail for a single policy. */
+interface PolicyTraceEntry extends PolicyTraceBaseline {
+    detail?: PolicyTraceDetail;
+}
+/** Full trace payload emitted as the `x-stoma-trace` response header. */
+interface PolicyTrace {
+    requestId: string;
+    traceId: string;
+    route: string;
+    totalMs: number;
+    entries: PolicyTraceEntry[];
+}
+/**
+ * A trace reporter function. Always callable - no-op when tracing is inactive.
+ *
+ * @param action - Human-readable action string (e.g. `"HIT"`, `"allowed"`).
+ * @param data   - Optional structured context data.
+ */
+type TraceReporter = (action: string, data?: Record<string, unknown>) => void;
+/** Shared no-op reporter instance - zero overhead when tracing is off. */
+declare const noopTraceReporter: TraceReporter;
+/**
+ * Get a trace reporter for a specific policy.
+ *
+ * When tracing is active (`_stomaTraceRequested` is truthy), returns a
+ * function that stores the detail on the context. When inactive, returns
+ * {@link noopTraceReporter} - a no-op with zero overhead.
+ *
+ * @param c          - Hono request context.
+ * @param policyName - Policy name used as the Map key.
+ * @returns A {@link TraceReporter} - always callable.
+ */
+declare function policyTrace(c: Context, policyName: string): TraceReporter;
+/**
+ * Fast-path check: is tracing requested for this request?
+ *
+ * @param c - Hono request context.
+ * @returns `true` when the client requested tracing via `x-stoma-debug: trace`.
+ */
+declare function isTraceRequested(c: Context): boolean;
+
+export { type PolicyTrace, type PolicyTraceBaseline, type PolicyTraceDetail, type PolicyTraceEntry, TRACE_DETAILS_KEY, TRACE_ENTRIES_KEY, TRACE_REQUESTED_KEY, type TraceReporter, isTraceRequested, noopTraceReporter, policyTrace };

package/dist/policies/sdk/trace.js

@@ -0,0 +1,25 @@
+const TRACE_REQUESTED_KEY = "_stomaTraceRequested";
+const TRACE_ENTRIES_KEY = "_stomaTraceEntries";
+const TRACE_DETAILS_KEY = "_stomaTraceDetails";
+const noopTraceReporter = () => {
+};
+function policyTrace(c, policyName) {
+  if (!c.get(TRACE_REQUESTED_KEY)) return noopTraceReporter;
+  return (action, data) => {
+    const details = c.get(TRACE_DETAILS_KEY) ?? /* @__PURE__ */ new Map();
+    details.set(policyName, { action, data });
+    c.set(TRACE_DETAILS_KEY, details);
+  };
+}
+function isTraceRequested(c) {
+  return c.get(TRACE_REQUESTED_KEY) === true;
+}
+export {
+  TRACE_DETAILS_KEY,
+  TRACE_ENTRIES_KEY,
+  TRACE_REQUESTED_KEY,
+  isTraceRequested,
+  noopTraceReporter,
+  policyTrace
+};
+//# sourceMappingURL=trace.js.map

package/dist/policies/sdk/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/sdk/trace.ts"],"sourcesContent":["/**\n * Policy trace - structured per-policy trace entries for deep debugging.\n *\n * Provides a zero-overhead reporter API (`TraceReporter`) that policies\n * call to record what they did. When tracing is not active, the reporter\n * is a no-op constant - no allocations, no Map lookups.\n *\n * @module trace\n */\nimport type { Context } from \"hono\";\n\n// ---------------------------------------------------------------------------\n// Context key constants\n// ---------------------------------------------------------------------------\n\n/** Set by `parseDebugRequest()` when the client requests tracing. */\nexport const TRACE_REQUESTED_KEY = \"_stomaTraceRequested\";\n\n/** Array of `PolicyTraceBaseline` entries pushed by `policiesToMiddleware()`. */\nexport const TRACE_ENTRIES_KEY = \"_stomaTraceEntries\";\n\n/** Map of policy name → `PolicyTraceDetail` set by `policyTrace()`. */\nexport const TRACE_DETAILS_KEY = \"_stomaTraceDetails\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Auto-captured by the pipeline for every policy when tracing is active. */\nexport interface PolicyTraceBaseline {\n  name: string;\n  priority: number;\n  durationMs: number;\n  calledNext: boolean;\n  error: string | null;\n}\n\n/** Policy-reported detail (cooperative opt-in via `trace()`). */\nexport interface PolicyTraceDetail {\n  action: string;\n  data?: Record<string, unknown>;\n}\n\n/** Combined baseline + optional detail for a single policy. */\nexport interface PolicyTraceEntry extends PolicyTraceBaseline {\n  detail?: PolicyTraceDetail;\n}\n\n/** Full trace payload emitted as the `x-stoma-trace` response header. */\nexport interface PolicyTrace {\n  requestId: string;\n  traceId: string;\n  route: string;\n  totalMs: number;\n  entries: PolicyTraceEntry[];\n}\n\n// ---------------------------------------------------------------------------\n// Reporter API\n// ---------------------------------------------------------------------------\n\n/**\n * A trace reporter function. Always callable - no-op when tracing is inactive.\n *\n * @param action - Human-readable action string (e.g. `\"HIT\"`, `\"allowed\"`).\n * @param data   - Optional structured context data.\n */\nexport type TraceReporter = (\n  action: string,\n  data?: Record<string, unknown>\n) => void;\n\n/** Shared no-op reporter instance - zero overhead when tracing is off. */\nexport const noopTraceReporter: TraceReporter = () => {};\n\n/**\n * Get a trace reporter for a specific policy.\n *\n * When tracing is active (`_stomaTraceRequested` is truthy), returns a\n * function that stores the detail on the context. When inactive, returns\n * {@link noopTraceReporter} - a no-op with zero overhead.\n *\n * @param c          - Hono request context.\n * @param policyName - Policy name used as the Map key.\n * @returns A {@link TraceReporter} - always callable.\n */\nexport function policyTrace(c: Context, policyName: string): TraceReporter {\n  if (!c.get(TRACE_REQUESTED_KEY)) return noopTraceReporter;\n\n  return (action: string, data?: Record<string, unknown>) => {\n    const details = (c.get(TRACE_DETAILS_KEY) ??\n      new Map<string, PolicyTraceDetail>()) as Map<string, PolicyTraceDetail>;\n    details.set(policyName, { action, data });\n    c.set(TRACE_DETAILS_KEY, details);\n  };\n}\n\n/**\n * Fast-path check: is tracing requested for this request?\n *\n * @param c - Hono request context.\n * @returns `true` when the client requested tracing via `x-stoma-debug: trace`.\n */\nexport function isTraceRequested(c: Context): boolean {\n  return c.get(TRACE_REQUESTED_KEY) === true;\n}\n"],"mappings":"AAgBO,MAAM,sBAAsB;AAG5B,MAAM,oBAAoB;AAG1B,MAAM,oBAAoB;AAmD1B,MAAM,oBAAmC,MAAM;AAAC;AAahD,SAAS,YAAY,GAAY,YAAmC;AACzE,MAAI,CAAC,EAAE,IAAI,mBAAmB,EAAG,QAAO;AAExC,SAAO,CAAC,QAAgB,SAAmC;AACzD,UAAM,UAAW,EAAE,IAAI,iBAAiB,KACtC,oBAAI,IAA+B;AACrC,YAAQ,IAAI,YAAY,EAAE,QAAQ,KAAK,CAAC;AACxC,MAAE,IAAI,mBAAmB,OAAO;AAAA,EAClC;AACF;AAQO,SAAS,iBAAiB,GAAqB;AACpD,SAAO,EAAE,IAAI,mBAAmB,MAAM;AACxC;","names":[]}

package/dist/policies/traffic/cache.d.ts

@@ -0,0 +1,4 @@
+import 'hono';
+export { u as CacheConfig, C as CacheStore, I as InMemoryCacheStore, d as InMemoryCacheStoreOptions, r as cache } from '../../protocol-2fD3DJrL.js';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';

package/dist/policies/traffic/cache.js

@@ -0,0 +1,224 @@
+import {
+  Priority,
+  policyDebug,
+  policyTrace,
+  resolveConfig,
+  safeCall,
+  setDebugHeader,
+  withSkip
+} from "../sdk";
+const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([204, 304]);
+function safeBody(body, status) {
+  return NULL_BODY_STATUSES.has(status) ? null : body ?? null;
+}
+class InMemoryCacheStore {
+  entries = /* @__PURE__ */ new Map();
+  maxEntries;
+  constructor(options) {
+    this.maxEntries = options?.maxEntries;
+  }
+  async get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.entries.delete(key);
+      return null;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return new Response(safeBody(entry.body, entry.status), {
+      status: entry.status,
+      headers: entry.headers
+    });
+  }
+  async put(key, response, ttlSeconds) {
+    const body = await response.arrayBuffer();
+    const headers = [];
+    response.headers.forEach((value, name) => {
+      headers.push([name, value]);
+    });
+    if (this.maxEntries && !this.entries.has(key) && this.entries.size >= this.maxEntries) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.entries.delete(oldestKey);
+      }
+    }
+    this.entries.set(key, {
+      body,
+      status: response.status,
+      headers,
+      expiresAt: Date.now() + ttlSeconds * 1e3
+    });
+  }
+  async delete(key) {
+    return this.entries.delete(key);
+  }
+  /** Remove all entries (for testing) */
+  clear() {
+    this.entries.clear();
+  }
+  /** Current number of entries (for testing/inspection) */
+  get size() {
+    return this.entries.size;
+  }
+  /** Release all cached entries. */
+  destroy() {
+    this.entries.clear();
+  }
+}
+const INTERNAL_EXPIRES_HEADER = "x-stoma-internal-expires-at";
+const BODY_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+function parseCacheControlDirectives(header) {
+  if (!header) return [];
+  return header.split(",").map((part) => part.trim().split("=")[0].trim().toLowerCase());
+}
+function cache(config) {
+  const resolved = resolveConfig(
+    {
+      ttlSeconds: 300,
+      methods: ["GET"],
+      respectCacheControl: true,
+      cacheStatusHeader: "x-cache",
+      bypassDirectives: ["no-store", "no-cache"]
+    },
+    config
+  );
+  const normalizedMethods = resolved.methods.map((m) => m.toUpperCase());
+  let store = config?.store;
+  if (!store) {
+    store = new InMemoryCacheStore();
+  }
+  const resolvedStore = store;
+  const statusHeader = resolved.cacheStatusHeader;
+  async function buildKey(c) {
+    if (config?.cacheKeyFn) return await config.cacheKeyFn(c);
+    let key = `${c.req.method}:${c.req.url}`;
+    if (BODY_METHODS.has(c.req.method.toUpperCase())) {
+      try {
+        const bodyText = await c.req.raw.clone().text();
+        if (bodyText) {
+          const hashBuffer = await crypto.subtle.digest(
+            "SHA-256",
+            new TextEncoder().encode(bodyText)
+          );
+          const hashArray = new Uint8Array(hashBuffer);
+          let hashHex = "";
+          for (const b of hashArray) {
+            hashHex += b.toString(16).padStart(2, "0");
+          }
+          key += `|body:${hashHex}`;
+        }
+      } catch {
+      }
+    }
+    if (config?.varyHeaders) {
+      const vary = config.varyHeaders.map((h) => c.req.header(h) ?? "").join("|");
+      key += `|vary:${vary}`;
+    }
+    return key;
+  }
+  const handler = async (c, next) => {
+    const debug = policyDebug(c, "cache");
+    const trace = policyTrace(c, "cache");
+    if (!normalizedMethods.includes(c.req.method.toUpperCase())) {
+      trace("SKIP", { method: c.req.method });
+      await next();
+      c.res.headers.set(statusHeader, "SKIP");
+      return;
+    }
+    const key = await buildKey(c);
+    setDebugHeader(c, "x-stoma-cache-key", key);
+    setDebugHeader(c, "x-stoma-cache-ttl", resolved.ttlSeconds);
+    const cached = await safeCall(
+      () => resolvedStore.get(key),
+      null,
+      debug,
+      "store.get()"
+    );
+    if (cached) {
+      debug(`HIT ${key}`);
+      setDebugHeader(c, "x-stoma-cache-status", "HIT");
+      trace("HIT", { key });
+      const expiresAtStr = cached.headers.get(INTERNAL_EXPIRES_HEADER);
+      if (expiresAtStr) {
+        const remaining = Math.max(
+          0,
+          Math.ceil((Number(expiresAtStr) - Date.now()) / 1e3)
+        );
+        setDebugHeader(c, "x-stoma-cache-expires-in", remaining);
+      }
+      const body = await cached.arrayBuffer();
+      const res = new Response(safeBody(body, cached.status), {
+        status: cached.status,
+        headers: cached.headers
+      });
+      res.headers.delete(INTERNAL_EXPIRES_HEADER);
+      res.headers.set(statusHeader, "HIT");
+      c.res = res;
+      return;
+    }
+    await next();
+    if (c.res.status >= 500) {
+      debug(`SKIP ${key} (status=${c.res.status})`);
+      setDebugHeader(c, "x-stoma-cache-status", "SKIP");
+      c.res.headers.set(statusHeader, "SKIP");
+      return;
+    }
+    if (resolved.cacheableStatuses && !resolved.cacheableStatuses.includes(c.res.status)) {
+      debug(`SKIP ${key} (status=${c.res.status} not in cacheableStatuses)`);
+      setDebugHeader(c, "x-stoma-cache-status", "SKIP");
+      c.res.headers.set(statusHeader, "SKIP");
+      return;
+    }
+    if (resolved.respectCacheControl) {
+      const cc = c.res.headers.get("cache-control") ?? "";
+      const directives = parseCacheControlDirectives(cc);
+      if (resolved.bypassDirectives.some(
+        (d) => directives.includes(d.toLowerCase())
+      )) {
+        debug(`BYPASS ${key} (cache-control: ${cc})`);
+        setDebugHeader(c, "x-stoma-cache-status", "BYPASS");
+        trace("BYPASS", { key, directive: cc });
+        c.res.headers.set(statusHeader, "BYPASS");
+        return;
+      }
+    }
+    debug(`MISS ${key} (ttl=${resolved.ttlSeconds}s)`);
+    setDebugHeader(c, "x-stoma-cache-status", "MISS");
+    trace("MISS", { key, ttl: resolved.ttlSeconds });
+    const storeClone = c.res.clone();
+    const storeBody = safeBody(
+      await storeClone.arrayBuffer(),
+      storeClone.status
+    );
+    const storeHeaders = new Headers(storeClone.headers);
+    storeHeaders.set(
+      INTERNAL_EXPIRES_HEADER,
+      String(Date.now() + resolved.ttlSeconds * 1e3)
+    );
+    await safeCall(
+      () => resolvedStore.put(
+        key,
+        new Response(storeBody, {
+          status: storeClone.status,
+          headers: storeHeaders
+        }),
+        resolved.ttlSeconds
+      ),
+      void 0,
+      debug,
+      "store.put()"
+    );
+    c.res.headers.set(statusHeader, "MISS");
+  };
+  return {
+    name: "cache",
+    priority: Priority.CACHE,
+    handler: withSkip(config?.skip, handler)
+  };
+}
+export {
+  InMemoryCacheStore,
+  cache
+};
+//# sourceMappingURL=cache.js.map

package/dist/policies/traffic/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/traffic/cache.ts"],"sourcesContent":["/**\n * Response caching policy with pluggable storage backends.\n *\n * @module cache\n */\nimport type { Context } from \"hono\";\nimport {\n  Priority,\n  policyDebug,\n  policyTrace,\n  resolveConfig,\n  safeCall,\n  setDebugHeader,\n  withSkip,\n} from \"../sdk\";\nimport type { Policy, PolicyConfig } from \"../types\";\n\n// Per HTTP spec, 204 and 304 responses must not carry a body.\n// Node.js enforces this strictly; workerd is lenient. Guard all\n// Response reconstruction so we don't silently break on Node/Bun/Deno.\nconst NULL_BODY_STATUSES = new Set([204, 304]);\nfunction safeBody(\n  body: BodyInit | null | undefined,\n  status: number\n): BodyInit | null {\n  return NULL_BODY_STATUSES.has(status) ? null : (body ?? null);\n}\n\n// --- Store interface ---\n\n/** Pluggable cache storage backend */\nexport interface CacheStore {\n  /** Retrieve a cached response by key. Returns null on miss. */\n  get(key: string): Promise<Response | null>;\n  /** Store a response under key with a TTL in seconds. */\n  put(key: string, response: Response, ttlSeconds: number): Promise<void>;\n  /** Delete a cached entry. Returns true if something was removed. */\n  delete(key: string): Promise<boolean>;\n  /** Optional cleanup - clear expired entries, release resources. */\n  destroy?(): void;\n}\n\n// --- In-memory default ---\n\ninterface CacheEntry {\n  body: ArrayBuffer;\n  status: number;\n  headers: [string, string][];\n  expiresAt: number;\n}\n\n/** Options for the in-memory cache store. */\nexport interface InMemoryCacheStoreOptions {\n  /** Maximum number of cached entries. When exceeded, the oldest entry is evicted (LRU). */\n  maxEntries?: number;\n}\n\nexport class InMemoryCacheStore implements CacheStore {\n  private entries = new Map<string, CacheEntry>();\n  private maxEntries: number | undefined;\n\n  constructor(options?: InMemoryCacheStoreOptions) {\n    this.maxEntries = options?.maxEntries;\n  }\n\n  async get(key: string): Promise<Response | null> {\n    const entry = this.entries.get(key);\n    if (!entry) return null;\n    if (Date.now() > entry.expiresAt) {\n      this.entries.delete(key);\n      return null;\n    }\n    // Move to end for LRU ordering (most recently accessed = last)\n    this.entries.delete(key);\n    this.entries.set(key, entry);\n    return new Response(safeBody(entry.body, entry.status), {\n      status: entry.status,\n      headers: entry.headers,\n    });\n  }\n\n  async put(\n    key: string,\n    response: Response,\n    ttlSeconds: number\n  ): Promise<void> {\n    const body = await response.arrayBuffer();\n    const headers: [string, string][] = [];\n    response.headers.forEach((value, name) => {\n      headers.push([name, value]);\n    });\n\n    // Evict oldest entry (first key in Map iteration order) when at capacity\n    if (\n      this.maxEntries &&\n      !this.entries.has(key) &&\n      this.entries.size >= this.maxEntries\n    ) {\n      const oldestKey = this.entries.keys().next().value;\n      if (oldestKey !== undefined) {\n        this.entries.delete(oldestKey);\n      }\n    }\n\n    this.entries.set(key, {\n      body,\n      status: response.status,\n      headers,\n      expiresAt: Date.now() + ttlSeconds * 1000,\n    });\n  }\n\n  async delete(key: string): Promise<boolean> {\n    return this.entries.delete(key);\n  }\n\n  /** Remove all entries (for testing) */\n  clear(): void {\n    this.entries.clear();\n  }\n\n  /** Current number of entries (for testing/inspection) */\n  get size(): number {\n    return this.entries.size;\n  }\n\n  /** Release all cached entries. */\n  destroy(): void {\n    this.entries.clear();\n  }\n}\n\n// --- Helpers ---\n\n/** Internal header embedded in cached responses to track expiry time. Stripped before serving. */\nconst INTERNAL_EXPIRES_HEADER = \"x-stoma-internal-expires-at\";\n\n/** Methods that typically carry a request body. */\nconst BODY_METHODS = new Set([\"POST\", \"PUT\", \"PATCH\"]);\n\n/**\n * Parse Cache-Control into individual directive names (lowercase, no values).\n *\n * `\"public, max-age=3600, no-store\"` → `[\"public\", \"max-age\", \"no-store\"]`\n */\nfunction parseCacheControlDirectives(header: string): string[] {\n  if (!header) return [];\n  return header\n    .split(\",\")\n    .map((part) => part.trim().split(\"=\")[0].trim().toLowerCase());\n}\n\n// --- Policy ---\n\nexport interface CacheConfig extends PolicyConfig {\n  /** Cache TTL in seconds. Default: 300. */\n  ttlSeconds?: number;\n  /** HTTP methods to cache. Default: [\"GET\"]. Case-insensitive. */\n  methods?: string[];\n  /** Custom cache key builder. Supports async for body-based keys. Default: method + url (+ body hash for POST/PUT/PATCH). */\n  cacheKeyFn?: (c: Context) => string | Promise<string>;\n  /** Only cache responses with these status codes. When set, responses with other statuses are not cached (5xx is always excluded regardless). */\n  cacheableStatuses?: number[];\n  /** Vary cache key on these request headers. */\n  varyHeaders?: string[];\n  /** Storage backend. Default: InMemoryCacheStore. */\n  store?: CacheStore;\n  /** Respect upstream Cache-Control directives. Default: true. */\n  respectCacheControl?: boolean;\n  /** Response header name for cache status (HIT/MISS/BYPASS/SKIP). Default: `\"x-cache\"`. */\n  cacheStatusHeader?: string;\n  /** Cache-Control directives that trigger a bypass. Matched at the directive level, not substring. Default: `[\"no-store\", \"no-cache\"]`. */\n  bypassDirectives?: string[];\n}\n\n/**\n * Cache upstream responses to reduce latency and load.\n *\n * Sets a cache status header on **every** response:\n * - `HIT` - served from cache\n * - `MISS` - fetched from upstream, now cached\n * - `BYPASS` - upstream Cache-Control directive prevented caching\n * - `SKIP` - not eligible for caching (wrong method or server error status)\n *\n * Server error responses (5xx) are never cached. Store failures degrade\n * gracefully via {@link safeCall} - a broken cache store never crashes the\n * request.\n *\n * For methods with a request body (POST, PUT, PATCH), the default cache key\n * includes a SHA-256 hash of the body to prevent key collisions across\n * different payloads.\n *\n * @param config - Cache TTL, storage backend, and key strategy. All fields optional.\n * @returns A {@link Policy} at priority 40.\n *\n * @example\n * ```ts\n * // Simple 5-minute in-memory cache for GET requests\n * cache({ ttlSeconds: 300 });\n *\n * // Cache with Vary on Accept-Language and custom store\n * cache({\n *   ttlSeconds: 600,\n *   varyHeaders: [\"accept-language\"],\n *   store: new CacheApiCacheStore(caches.default),\n * });\n * ```\n */\nexport function cache(config?: CacheConfig): Policy {\n  const resolved = resolveConfig<CacheConfig>(\n    {\n      ttlSeconds: 300,\n      methods: [\"GET\"],\n      respectCacheControl: true,\n      cacheStatusHeader: \"x-cache\",\n      bypassDirectives: [\"no-store\", \"no-cache\"],\n    },\n    config\n  );\n\n  // Normalize methods to uppercase for case-insensitive matching\n  const normalizedMethods = resolved.methods!.map((m) => m.toUpperCase());\n\n  let store = config?.store;\n  if (!store) {\n    store = new InMemoryCacheStore();\n  }\n  const resolvedStore = store;\n\n  const statusHeader = resolved.cacheStatusHeader!;\n\n  async function buildKey(c: Context): Promise<string> {\n    if (config?.cacheKeyFn) return await config.cacheKeyFn(c);\n\n    let key = `${c.req.method}:${c.req.url}`;\n\n    // Include body hash for methods that carry a body\n    if (BODY_METHODS.has(c.req.method.toUpperCase())) {\n      try {\n        const bodyText = await c.req.raw.clone().text();\n        if (bodyText) {\n          const hashBuffer = await crypto.subtle.digest(\n            \"SHA-256\",\n            new TextEncoder().encode(bodyText)\n          );\n          const hashArray = new Uint8Array(hashBuffer);\n          let hashHex = \"\";\n          for (const b of hashArray) {\n            hashHex += b.toString(16).padStart(2, \"0\");\n          }\n          key += `|body:${hashHex}`;\n        }\n      } catch {\n        // Body already consumed or unreadable - use URL-only key\n      }\n    }\n\n    if (config?.varyHeaders) {\n      const vary = config.varyHeaders\n        .map((h) => c.req.header(h) ?? \"\")\n        .join(\"|\");\n      key += `|vary:${vary}`;\n    }\n    return key;\n  }\n\n  const handler: import(\"hono\").MiddlewareHandler = async (c, next) => {\n    const debug = policyDebug(c, \"cache\");\n    const trace = policyTrace(c, \"cache\");\n\n    // Non-cacheable method - pass through with SKIP status\n    if (!normalizedMethods.includes(c.req.method.toUpperCase())) {\n      trace(\"SKIP\", { method: c.req.method });\n      await next();\n      c.res.headers.set(statusHeader, \"SKIP\");\n      return;\n    }\n\n    const key = await buildKey(c);\n    setDebugHeader(c, \"x-stoma-cache-key\", key);\n    setDebugHeader(c, \"x-stoma-cache-ttl\", resolved.ttlSeconds!);\n\n    // Check cache (resilient to store failures)\n    const cached = await safeCall(\n      () => resolvedStore.get(key),\n      null,\n      debug,\n      \"store.get()\"\n    );\n    if (cached) {\n      debug(`HIT ${key}`);\n      setDebugHeader(c, \"x-stoma-cache-status\", \"HIT\");\n      trace(\"HIT\", { key });\n      // Compute remaining TTL from the internal expiry header (if present)\n      const expiresAtStr = cached.headers.get(INTERNAL_EXPIRES_HEADER);\n      if (expiresAtStr) {\n        const remaining = Math.max(\n          0,\n          Math.ceil((Number(expiresAtStr) - Date.now()) / 1000)\n        );\n        setDebugHeader(c, \"x-stoma-cache-expires-in\", remaining);\n      }\n      // Return cached response, re-creating so headers can be modified\n      const body = await cached.arrayBuffer();\n      const res = new Response(safeBody(body, cached.status), {\n        status: cached.status,\n        headers: cached.headers,\n      });\n      res.headers.delete(INTERNAL_EXPIRES_HEADER);\n      res.headers.set(statusHeader, \"HIT\");\n      c.res = res;\n      return;\n    }\n\n    await next();\n\n    // Never cache server error responses (5xx)\n    if (c.res.status >= 500) {\n      debug(`SKIP ${key} (status=${c.res.status})`);\n      setDebugHeader(c, \"x-stoma-cache-status\", \"SKIP\");\n      c.res.headers.set(statusHeader, \"SKIP\");\n      return;\n    }\n\n    // Only cache responses matching cacheableStatuses (when configured)\n    if (\n      resolved.cacheableStatuses &&\n      !resolved.cacheableStatuses.includes(c.res.status)\n    ) {\n      debug(`SKIP ${key} (status=${c.res.status} not in cacheableStatuses)`);\n      setDebugHeader(c, \"x-stoma-cache-status\", \"SKIP\");\n      c.res.headers.set(statusHeader, \"SKIP\");\n      return;\n    }\n\n    // Check upstream Cache-Control (directive-level matching, not substring)\n    if (resolved.respectCacheControl) {\n      const cc = c.res.headers.get(\"cache-control\") ?? \"\";\n      const directives = parseCacheControlDirectives(cc);\n      if (\n        resolved.bypassDirectives!.some((d) =>\n          directives.includes(d.toLowerCase())\n        )\n      ) {\n        debug(`BYPASS ${key} (cache-control: ${cc})`);\n        setDebugHeader(c, \"x-stoma-cache-status\", \"BYPASS\");\n        trace(\"BYPASS\", { key, directive: cc });\n        c.res.headers.set(statusHeader, \"BYPASS\");\n        return;\n      }\n    }\n\n    // Store a clone (with internal expiry header) and mark as MISS\n    debug(`MISS ${key} (ttl=${resolved.ttlSeconds}s)`);\n    setDebugHeader(c, \"x-stoma-cache-status\", \"MISS\");\n    trace(\"MISS\", { key, ttl: resolved.ttlSeconds! });\n    const storeClone = c.res.clone();\n    const storeBody = safeBody(\n      await storeClone.arrayBuffer(),\n      storeClone.status\n    );\n    const storeHeaders = new Headers(storeClone.headers);\n    storeHeaders.set(\n      INTERNAL_EXPIRES_HEADER,\n      String(Date.now() + resolved.ttlSeconds! * 1000)\n    );\n    await safeCall(\n      () =>\n        resolvedStore.put(\n          key,\n          new Response(storeBody, {\n            status: storeClone.status,\n            headers: storeHeaders,\n          }),\n          resolved.ttlSeconds!\n        ),\n      undefined,\n      debug,\n      \"store.put()\"\n    );\n    c.res.headers.set(statusHeader, \"MISS\");\n  };\n\n  return {\n    name: \"cache\",\n    priority: Priority.CACHE,\n    handler: withSkip(config?.skip, handler),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/policies/traffic/dynamic-routing.d.ts

@@ -0,0 +1,54 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import { Context } from 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface RoutingRule {
+    /** Human-readable rule name for debugging. */
+    name?: string;
+    /** Condition that determines if this rule applies. */
+    condition: (c: Context) => boolean | Promise<boolean>;
+    /** Target upstream URL to route to. */
+    target: string;
+    /** Optional path rewrite function. */
+    rewritePath?: (path: string) => string;
+    /** Optional headers to add to the upstream request. */
+    headers?: Record<string, string>;
+}
+interface DynamicRoutingConfig extends PolicyConfig {
+    /** Ordered list of routing rules. First match wins. Required. */
+    rules: Array<RoutingRule>;
+    /** If true and no rule matches, call next() normally. If false, throw 404. Default: true. */
+    fallthrough?: boolean;
+}
+/**
+ * Evaluate routing rules and expose the first match on request context.
+ *
+ * Evaluates rules in order. The first matching rule's target, rewritePath,
+ * and headers are set as context variables for downstream consumption.
+ *
+ * @param config - Routing rules and fallthrough behavior.
+ * @returns A {@link Policy} at priority 50 (REQUEST_TRANSFORM).
+ *
+ * @example
+ * ```ts
+ * dynamicRouting({
+ *   rules: [
+ *     {
+ *       name: "v2-api",
+ *       condition: (c) => c.req.header("x-api-version") === "2",
+ *       target: "https://api-v2.internal",
+ *       rewritePath: (path) => path.replace("/api/", "/v2/"),
+ *     },
+ *     {
+ *       name: "default",
+ *       condition: () => true,
+ *       target: "https://api-v1.internal",
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare const dynamicRouting: (config: DynamicRoutingConfig) => Policy;
+
+export { type DynamicRoutingConfig, type RoutingRule, dynamicRouting };

package/dist/policies/traffic/dynamic-routing.js

@@ -0,0 +1,36 @@
+import { GatewayError } from "../../core/errors";
+import { definePolicy, Priority } from "../sdk";
+const dynamicRouting = /* @__PURE__ */ definePolicy({
+  name: "dynamic-routing",
+  priority: Priority.REQUEST_TRANSFORM,
+  httpOnly: true,
+  defaults: { fallthrough: true },
+  handler: async (c, next, { config, debug }) => {
+    for (const rule of config.rules) {
+      const matched = await rule.condition(c);
+      if (matched) {
+        debug(
+          `matched rule ${rule.name ? `"${rule.name}"` : "(unnamed)"} \u2192 target=${rule.target}`
+        );
+        c.set("_dynamicTarget", rule.target);
+        if (rule.rewritePath) {
+          c.set("_dynamicRewrite", rule.rewritePath);
+        }
+        if (rule.headers) {
+          c.set("_dynamicHeaders", rule.headers);
+        }
+        await next();
+        return;
+      }
+    }
+    if (!config.fallthrough) {
+      throw new GatewayError(404, "no_route", "No routing rule matched");
+    }
+    debug("no rule matched, falling through");
+    await next();
+  }
+});
+export {
+  dynamicRouting
+};
+//# sourceMappingURL=dynamic-routing.js.map

package/dist/policies/traffic/dynamic-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/traffic/dynamic-routing.ts"],"sourcesContent":["/**\n * Dynamic routing policy - evaluate routing rules and expose match data on context.\n *\n * Evaluates an ordered list of routing rules against the request context.\n * The first matching rule sets context variables that downstream handlers\n * can consume (`_dynamicTarget`, `_dynamicRewrite`, `_dynamicHeaders`).\n *\n * @module dynamic-routing\n */\nimport type { Context } from \"hono\";\nimport { GatewayError } from \"../../core/errors\";\nimport { definePolicy, Priority } from \"../sdk\";\nimport type { PolicyConfig } from \"../types\";\n\nexport interface RoutingRule {\n  /** Human-readable rule name for debugging. */\n  name?: string;\n  /** Condition that determines if this rule applies. */\n  condition: (c: Context) => boolean | Promise<boolean>;\n  /** Target upstream URL to route to. */\n  target: string;\n  /** Optional path rewrite function. */\n  rewritePath?: (path: string) => string;\n  /** Optional headers to add to the upstream request. */\n  headers?: Record<string, string>;\n}\n\nexport interface DynamicRoutingConfig extends PolicyConfig {\n  /** Ordered list of routing rules. First match wins. Required. */\n  rules: Array<RoutingRule>;\n  /** If true and no rule matches, call next() normally. If false, throw 404. Default: true. */\n  fallthrough?: boolean;\n}\n\n/**\n * Evaluate routing rules and expose the first match on request context.\n *\n * Evaluates rules in order. The first matching rule's target, rewritePath,\n * and headers are set as context variables for downstream consumption.\n *\n * @param config - Routing rules and fallthrough behavior.\n * @returns A {@link Policy} at priority 50 (REQUEST_TRANSFORM).\n *\n * @example\n * ```ts\n * dynamicRouting({\n *   rules: [\n *     {\n *       name: \"v2-api\",\n *       condition: (c) => c.req.header(\"x-api-version\") === \"2\",\n *       target: \"https://api-v2.internal\",\n *       rewritePath: (path) => path.replace(\"/api/\", \"/v2/\"),\n *     },\n *     {\n *       name: \"default\",\n *       condition: () => true,\n *       target: \"https://api-v1.internal\",\n *     },\n *   ],\n * });\n * ```\n */\nexport const dynamicRouting = /*#__PURE__*/ definePolicy<DynamicRoutingConfig>({\n  name: \"dynamic-routing\",\n  priority: Priority.REQUEST_TRANSFORM,\n  httpOnly: true,\n  defaults: { fallthrough: true },\n  handler: async (c, next, { config, debug }) => {\n    for (const rule of config.rules) {\n      const matched = await rule.condition(c);\n      if (matched) {\n        debug(\n          `matched rule ${rule.name ? `\"${rule.name}\"` : \"(unnamed)\"}` +\n            ` → target=${rule.target}`\n        );\n        c.set(\"_dynamicTarget\", rule.target);\n        if (rule.rewritePath) {\n          c.set(\"_dynamicRewrite\", rule.rewritePath);\n        }\n        if (rule.headers) {\n          c.set(\"_dynamicHeaders\", rule.headers);\n        }\n        await next();\n        return;\n      }\n    }\n\n    // No rule matched\n    if (!config.fallthrough) {\n      throw new GatewayError(404, \"no_route\", \"No routing rule matched\");\n    }\n\n    debug(\"no rule matched, falling through\");\n    await next();\n  },\n});\n"],"mappings":"AAUA,SAAS,oBAAoB;AAC7B,SAAS,cAAc,gBAAgB;AAmDhC,MAAM,iBAA+B,6BAAmC;AAAA,EAC7E,MAAM;AAAA,EACN,UAAU,SAAS;AAAA,EACnB,UAAU;AAAA,EACV,UAAU,EAAE,aAAa,KAAK;AAAA,EAC9B,SAAS,OAAO,GAAG,MAAM,EAAE,QAAQ,MAAM,MAAM;AAC7C,eAAW,QAAQ,OAAO,OAAO;AAC/B,YAAM,UAAU,MAAM,KAAK,UAAU,CAAC;AACtC,UAAI,SAAS;AACX;AAAA,UACE,gBAAgB,KAAK,OAAO,IAAI,KAAK,IAAI,MAAM,WAAW,kBAC3C,KAAK,MAAM;AAAA,QAC5B;AACA,UAAE,IAAI,kBAAkB,KAAK,MAAM;AACnC,YAAI,KAAK,aAAa;AACpB,YAAE,IAAI,mBAAmB,KAAK,WAAW;AAAA,QAC3C;AACA,YAAI,KAAK,SAAS;AAChB,YAAE,IAAI,mBAAmB,KAAK,OAAO;AAAA,QACvC;AACA,cAAM,KAAK;AACX;AAAA,MACF;AAAA,IACF;AAGA,QAAI,CAAC,OAAO,aAAa;AACvB,YAAM,IAAI,aAAa,KAAK,YAAY,yBAAyB;AAAA,IACnE;AAEA,UAAM,kCAAkC;AACxC,UAAM,KAAK;AAAA,EACb;AACF,CAAC;","names":[]}

package/dist/policies/traffic/geo-ip-filter.d.ts

@@ -0,0 +1,37 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface GeoIpFilterConfig extends PolicyConfig {
+    /** Country codes to allow (e.g. `["US", "CA", "GB"]`). Used in "allow" mode. */
+    allow?: string[];
+    /** Country codes to deny. Used in "deny" mode. */
+    deny?: string[];
+    /** Filter mode. Default: `"deny"`. */
+    mode?: "allow" | "deny";
+    /** Header name to read the country code from. Default: `"cf-ipcountry"`. */
+    countryHeader?: string;
+}
+/**
+ * Block or allow requests based on geographic country code.
+ *
+ * Reads the country from the configured header (default `cf-ipcountry`,
+ * set by Cloudflare). Supports allowlist and denylist modes. Country
+ * sets are pre-computed once at construction time for efficiency.
+ *
+ * @param config - Country filter rules and mode selection.
+ * @returns A policy at priority 1 (IP_FILTER).
+ *
+ * @example
+ * ```ts
+ * // Allow only US, Canada, and UK
+ * geoIpFilter({ mode: "allow", allow: ["US", "CA", "GB"] });
+ *
+ * // Block specific countries
+ * geoIpFilter({ deny: ["CN", "RU"] });
+ * ```
+ */
+declare function geoIpFilter(config?: GeoIpFilterConfig): Policy;
+
+export { type GeoIpFilterConfig, geoIpFilter };