@vivero/stoma 0.1.0-rc.10

package/dist/policies/traffic/geo-ip-filter.js

@@ -0,0 +1,74 @@
+import { GatewayError } from "../../core/errors";
+import { Priority, policyDebug, resolveConfig, withSkip } from "../sdk";
+function geoIpFilter(config) {
+  const resolved = resolveConfig(
+    { mode: "deny", countryHeader: "cf-ipcountry" },
+    config
+  );
+  const allowSet = new Set(
+    (resolved.allow ?? []).map((code) => code.toUpperCase())
+  );
+  const denySet = new Set(
+    (resolved.deny ?? []).map((code) => code.toUpperCase())
+  );
+  const handler = async (c, next) => {
+    const debug = policyDebug(c, "geo-ip-filter");
+    const country = c.req.header(resolved.countryHeader)?.toUpperCase();
+    const mode = resolved.mode;
+    debug(`country=${country ?? "unknown"} mode=${mode}`);
+    if (mode === "allow") {
+      if (!country || !allowSet.has(country)) {
+        throw new GatewayError(
+          403,
+          "geo_denied",
+          "Access denied from this region"
+        );
+      }
+    } else {
+      if (country && denySet.has(country)) {
+        throw new GatewayError(
+          403,
+          "geo_denied",
+          "Access denied from this region"
+        );
+      }
+    }
+    await next();
+  };
+  return {
+    name: "geo-ip-filter",
+    priority: Priority.IP_FILTER,
+    handler: withSkip(config?.skip, handler),
+    phases: ["request-headers"],
+    evaluate: {
+      onRequest: async (input) => {
+        const country = input.headers.get(resolved.countryHeader)?.toUpperCase();
+        const mode = resolved.mode;
+        if (mode === "allow") {
+          if (!country || !allowSet.has(country)) {
+            return {
+              action: "reject",
+              status: 403,
+              code: "geo_denied",
+              message: "Access denied from this region"
+            };
+          }
+        } else {
+          if (country && denySet.has(country)) {
+            return {
+              action: "reject",
+              status: 403,
+              code: "geo_denied",
+              message: "Access denied from this region"
+            };
+          }
+        }
+        return { action: "continue" };
+      }
+    }
+  };
+}
+export {
+  geoIpFilter
+};
+//# sourceMappingURL=geo-ip-filter.js.map

package/dist/policies/traffic/geo-ip-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/traffic/geo-ip-filter.ts"],"sourcesContent":["/**\n * Geographic IP filtering policy.\n *\n * Allows or denies requests based on the country code derived from\n * a configurable header (defaults to Cloudflare's `cf-ipcountry`).\n *\n * @module geo-ip-filter\n */\nimport { GatewayError } from \"../../core/errors\";\nimport type { PolicyInput } from \"../../core/protocol\";\nimport { Priority, policyDebug, resolveConfig, withSkip } from \"../sdk\";\nimport type { Policy, PolicyConfig } from \"../types\";\n\nexport interface GeoIpFilterConfig extends PolicyConfig {\n  /** Country codes to allow (e.g. `[\"US\", \"CA\", \"GB\"]`). Used in \"allow\" mode. */\n  allow?: string[];\n  /** Country codes to deny. Used in \"deny\" mode. */\n  deny?: string[];\n  /** Filter mode. Default: `\"deny\"`. */\n  mode?: \"allow\" | \"deny\";\n  /** Header name to read the country code from. Default: `\"cf-ipcountry\"`. */\n  countryHeader?: string;\n}\n\n/**\n * Block or allow requests based on geographic country code.\n *\n * Reads the country from the configured header (default `cf-ipcountry`,\n * set by Cloudflare). Supports allowlist and denylist modes. Country\n * sets are pre-computed once at construction time for efficiency.\n *\n * @param config - Country filter rules and mode selection.\n * @returns A policy at priority 1 (IP_FILTER).\n *\n * @example\n * ```ts\n * // Allow only US, Canada, and UK\n * geoIpFilter({ mode: \"allow\", allow: [\"US\", \"CA\", \"GB\"] });\n *\n * // Block specific countries\n * geoIpFilter({ deny: [\"CN\", \"RU\"] });\n * ```\n */\nexport function geoIpFilter(config?: GeoIpFilterConfig): Policy {\n  const resolved = resolveConfig<GeoIpFilterConfig>(\n    { mode: \"deny\", countryHeader: \"cf-ipcountry\" },\n    config\n  );\n\n  // Pre-compute country sets once at construction time instead of per-request\n  const allowSet = new Set(\n    (resolved.allow ?? []).map((code) => code.toUpperCase())\n  );\n  const denySet = new Set(\n    (resolved.deny ?? []).map((code) => code.toUpperCase())\n  );\n\n  const handler: import(\"hono\").MiddlewareHandler = async (c, next) => {\n    const debug = policyDebug(c, \"geo-ip-filter\");\n    const country = c.req.header(resolved.countryHeader!)?.toUpperCase();\n    const mode = resolved.mode!;\n\n    debug(`country=${country ?? \"unknown\"} mode=${mode}`);\n\n    if (mode === \"allow\") {\n      // Unknown country (missing header) is denied in allow mode\n      if (!country || !allowSet.has(country)) {\n        throw new GatewayError(\n          403,\n          \"geo_denied\",\n          \"Access denied from this region\"\n        );\n      }\n    } else {\n      // Unknown country (missing header) is allowed in deny mode\n      if (country && denySet.has(country)) {\n        throw new GatewayError(\n          403,\n          \"geo_denied\",\n          \"Access denied from this region\"\n        );\n      }\n    }\n\n    await next();\n  };\n\n  return {\n    name: \"geo-ip-filter\",\n    priority: Priority.IP_FILTER,\n    handler: withSkip(config?.skip, handler),\n    phases: [\"request-headers\"],\n    evaluate: {\n      onRequest: async (input: PolicyInput) => {\n        const country = input.headers\n          .get(resolved.countryHeader!)\n          ?.toUpperCase();\n        const mode = resolved.mode!;\n\n        if (mode === \"allow\") {\n          if (!country || !allowSet.has(country)) {\n            return {\n              action: \"reject\",\n              status: 403,\n              code: \"geo_denied\",\n              message: \"Access denied from this region\",\n            };\n          }\n        } else {\n          if (country && denySet.has(country)) {\n            return {\n              action: \"reject\",\n              status: 403,\n              code: \"geo_denied\",\n              message: \"Access denied from this region\",\n            };\n          }\n        }\n\n        return { action: \"continue\" };\n      },\n    },\n  };\n}\n"],"mappings":"AAQA,SAAS,oBAAoB;AAE7B,SAAS,UAAU,aAAa,eAAe,gBAAgB;AAiCxD,SAAS,YAAY,QAAoC;AAC9D,QAAM,WAAW;AAAA,IACf,EAAE,MAAM,QAAQ,eAAe,eAAe;AAAA,IAC9C;AAAA,EACF;AAGA,QAAM,WAAW,IAAI;AAAA,KAClB,SAAS,SAAS,CAAC,GAAG,IAAI,CAAC,SAAS,KAAK,YAAY,CAAC;AAAA,EACzD;AACA,QAAM,UAAU,IAAI;AAAA,KACjB,SAAS,QAAQ,CAAC,GAAG,IAAI,CAAC,SAAS,KAAK,YAAY,CAAC;AAAA,EACxD;AAEA,QAAM,UAA4C,OAAO,GAAG,SAAS;AACnE,UAAM,QAAQ,YAAY,GAAG,eAAe;AAC5C,UAAM,UAAU,EAAE,IAAI,OAAO,SAAS,aAAc,GAAG,YAAY;AACnE,UAAM,OAAO,SAAS;AAEtB,UAAM,WAAW,WAAW,SAAS,SAAS,IAAI,EAAE;AAEpD,QAAI,SAAS,SAAS;AAEpB,UAAI,CAAC,WAAW,CAAC,SAAS,IAAI,OAAO,GAAG;AACtC,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAAA,IACF,OAAO;AAEL,UAAI,WAAW,QAAQ,IAAI,OAAO,GAAG;AACnC,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAEA,UAAM,KAAK;AAAA,EACb;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU,SAAS;AAAA,IACnB,SAAS,SAAS,QAAQ,MAAM,OAAO;AAAA,IACvC,QAAQ,CAAC,iBAAiB;AAAA,IAC1B,UAAU;AAAA,MACR,WAAW,OAAO,UAAuB;AACvC,cAAM,UAAU,MAAM,QACnB,IAAI,SAAS,aAAc,GAC1B,YAAY;AAChB,cAAM,OAAO,SAAS;AAEtB,YAAI,SAAS,SAAS;AACpB,cAAI,CAAC,WAAW,CAAC,SAAS,IAAI,OAAO,GAAG;AACtC,mBAAO;AAAA,cACL,QAAQ;AAAA,cACR,QAAQ;AAAA,cACR,MAAM;AAAA,cACN,SAAS;AAAA,YACX;AAAA,UACF;AAAA,QACF,OAAO;AACL,cAAI,WAAW,QAAQ,IAAI,OAAO,GAAG;AACnC,mBAAO;AAAA,cACL,QAAQ;AAAA,cACR,QAAQ;AAAA,cACR,MAAM;AAAA,cACN,SAAS;AAAA,YACX;AAAA,UACF;AAAA,QACF;AAEA,eAAO,EAAE,QAAQ,WAAW;AAAA,MAC9B;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/policies/traffic/http-callout.d.ts

@@ -0,0 +1,59 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import { Context } from 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface HttpCalloutConfig extends PolicyConfig {
+    /** Target URL - static string or dynamic function. Required. */
+    url: string | ((c: Context) => string | Promise<string>);
+    /** HTTP method. Default: "GET". */
+    method?: string;
+    /** Request headers - static values or dynamic functions. */
+    headers?: Record<string, string | ((c: Context) => string | Promise<string>)>;
+    /** Request body - static or dynamic. JSON-serialized if object. */
+    body?: unknown | ((c: Context) => unknown | Promise<unknown>);
+    /** Timeout in ms. Default: 5000. */
+    timeout?: number;
+    /** Callback to process the callout response. Required. */
+    onResponse: (response: Response, c: Context) => void | Promise<void>;
+    /** Error handler. Default: throw GatewayError 502. */
+    onError?: (error: unknown, c: Context) => void | Promise<void>;
+    /** If true, throw on non-2xx response. Default: true. */
+    abortOnFailure?: boolean;
+}
+/**
+ * Make an external HTTP call mid-pipeline.
+ *
+ * Resolves URL, headers, and body (static or dynamic), makes the fetch,
+ * and calls the `onResponse` callback to process the result. Errors are
+ * handled via `onError` or default to a 502 GatewayError.
+ *
+ * @security When the `url` parameter is a dynamic function that derives
+ * the callout target from request data (headers, path, query, or body),
+ * this policy is vulnerable to Server-Side Request Forgery (SSRF). An
+ * attacker could manipulate request data to make the worker issue requests
+ * to internal services, metadata endpoints (e.g. cloud provider instance
+ * metadata), or other unintended targets. Hardcode callout URLs whenever
+ * possible. If dynamic URLs are required, validate them against an
+ * explicit allowlist of permitted hosts and schemes.
+ *
+ * @param config - Callout target, method, headers, body, and response handler.
+ * @returns A {@link Policy} at priority 50 (REQUEST_TRANSFORM).
+ *
+ * @example
+ * ```ts
+ * httpCallout({
+ *   url: "https://auth.example.com/validate",
+ *   method: "POST",
+ *   headers: { authorization: (c) => c.req.header("authorization") ?? "" },
+ *   body: (c) => ({ path: c.req.path }),
+ *   onResponse: async (res, c) => {
+ *     const data = await res.json();
+ *     c.set("userId", data.userId);
+ *   },
+ * });
+ * ```
+ */
+declare const httpCallout: (config: HttpCalloutConfig) => Policy;
+
+export { type HttpCalloutConfig, httpCallout };

package/dist/policies/traffic/http-callout.js

@@ -0,0 +1,69 @@
+import { GatewayError } from "../../core/errors";
+import { definePolicy, Priority } from "../sdk";
+const httpCallout = /* @__PURE__ */ definePolicy({
+  name: "http-callout",
+  priority: Priority.REQUEST_TRANSFORM,
+  httpOnly: true,
+  defaults: { method: "GET", timeout: 5e3, abortOnFailure: true },
+  handler: async (c, next, { config, debug }) => {
+    const url = typeof config.url === "function" ? await config.url(c) : config.url;
+    const resolvedHeaders = {};
+    if (config.headers) {
+      for (const [key, value] of Object.entries(config.headers)) {
+        resolvedHeaders[key] = typeof value === "function" ? await value(c) : value;
+      }
+    }
+    let resolvedBody;
+    if (config.body !== void 0) {
+      const raw = typeof config.body === "function" ? await config.body(c) : config.body;
+      if (raw !== void 0 && raw !== null) {
+        resolvedBody = typeof raw === "string" ? raw : JSON.stringify(raw);
+        if (typeof raw !== "string" && !resolvedHeaders["content-type"]) {
+          resolvedHeaders["content-type"] = "application/json";
+        }
+      }
+    }
+    debug(`${config.method} ${url}`);
+    let response;
+    try {
+      response = await fetch(url, {
+        method: config.method,
+        headers: resolvedHeaders,
+        body: resolvedBody,
+        signal: AbortSignal.timeout(config.timeout)
+      });
+    } catch (error) {
+      if (config.onError) {
+        await config.onError(error, c);
+        await next();
+        return;
+      }
+      throw new GatewayError(
+        502,
+        "callout_failed",
+        `External callout failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    if (!response.ok && config.abortOnFailure) {
+      if (config.onError) {
+        await config.onError(
+          new Error(`External callout returned ${response.status}`),
+          c
+        );
+        await next();
+        return;
+      }
+      throw new GatewayError(
+        502,
+        "callout_failed",
+        `External callout returned ${response.status}`
+      );
+    }
+    await config.onResponse(response, c);
+    await next();
+  }
+});
+export {
+  httpCallout
+};
+//# sourceMappingURL=http-callout.js.map

package/dist/policies/traffic/http-callout.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/traffic/http-callout.ts"],"sourcesContent":["/**\n * HTTP callout policy - make an external HTTP call mid-pipeline.\n *\n * Use cases include external authorization, token exchange, data enrichment,\n * and webhook notification before proxying to the upstream service.\n *\n * @module http-callout\n */\nimport type { Context } from \"hono\";\nimport { GatewayError } from \"../../core/errors\";\nimport { definePolicy, Priority } from \"../sdk\";\nimport type { PolicyConfig } from \"../types\";\n\nexport interface HttpCalloutConfig extends PolicyConfig {\n  /** Target URL - static string or dynamic function. Required. */\n  url: string | ((c: Context) => string | Promise<string>);\n  /** HTTP method. Default: \"GET\". */\n  method?: string;\n  /** Request headers - static values or dynamic functions. */\n  headers?: Record<string, string | ((c: Context) => string | Promise<string>)>;\n  /** Request body - static or dynamic. JSON-serialized if object. */\n  body?: unknown | ((c: Context) => unknown | Promise<unknown>);\n  /** Timeout in ms. Default: 5000. */\n  timeout?: number;\n  /** Callback to process the callout response. Required. */\n  onResponse: (response: Response, c: Context) => void | Promise<void>;\n  /** Error handler. Default: throw GatewayError 502. */\n  onError?: (error: unknown, c: Context) => void | Promise<void>;\n  /** If true, throw on non-2xx response. Default: true. */\n  abortOnFailure?: boolean;\n}\n\n/**\n * Make an external HTTP call mid-pipeline.\n *\n * Resolves URL, headers, and body (static or dynamic), makes the fetch,\n * and calls the `onResponse` callback to process the result. Errors are\n * handled via `onError` or default to a 502 GatewayError.\n *\n * @security When the `url` parameter is a dynamic function that derives\n * the callout target from request data (headers, path, query, or body),\n * this policy is vulnerable to Server-Side Request Forgery (SSRF). An\n * attacker could manipulate request data to make the worker issue requests\n * to internal services, metadata endpoints (e.g. cloud provider instance\n * metadata), or other unintended targets. Hardcode callout URLs whenever\n * possible. If dynamic URLs are required, validate them against an\n * explicit allowlist of permitted hosts and schemes.\n *\n * @param config - Callout target, method, headers, body, and response handler.\n * @returns A {@link Policy} at priority 50 (REQUEST_TRANSFORM).\n *\n * @example\n * ```ts\n * httpCallout({\n *   url: \"https://auth.example.com/validate\",\n *   method: \"POST\",\n *   headers: { authorization: (c) => c.req.header(\"authorization\") ?? \"\" },\n *   body: (c) => ({ path: c.req.path }),\n *   onResponse: async (res, c) => {\n *     const data = await res.json();\n *     c.set(\"userId\", data.userId);\n *   },\n * });\n * ```\n */\nexport const httpCallout = /*#__PURE__*/ definePolicy<HttpCalloutConfig>({\n  name: \"http-callout\",\n  priority: Priority.REQUEST_TRANSFORM,\n  httpOnly: true,\n  defaults: { method: \"GET\", timeout: 5000, abortOnFailure: true },\n  handler: async (c, next, { config, debug }) => {\n    // Resolve URL\n    const url =\n      typeof config.url === \"function\" ? await config.url(c) : config.url;\n\n    // Resolve headers\n    const resolvedHeaders: Record<string, string> = {};\n    if (config.headers) {\n      for (const [key, value] of Object.entries(config.headers)) {\n        resolvedHeaders[key] =\n          typeof value === \"function\" ? await value(c) : value;\n      }\n    }\n\n    // Resolve body\n    let resolvedBody: string | undefined;\n    if (config.body !== undefined) {\n      const raw =\n        typeof config.body === \"function\"\n          ? await (config.body as (c: Context) => unknown | Promise<unknown>)(c)\n          : config.body;\n      if (raw !== undefined && raw !== null) {\n        resolvedBody = typeof raw === \"string\" ? raw : JSON.stringify(raw);\n        if (typeof raw !== \"string\" && !resolvedHeaders[\"content-type\"]) {\n          resolvedHeaders[\"content-type\"] = \"application/json\";\n        }\n      }\n    }\n\n    debug(`${config.method} ${url}`);\n\n    let response: Response;\n    try {\n      response = await fetch(url, {\n        method: config.method,\n        headers: resolvedHeaders,\n        body: resolvedBody,\n        signal: AbortSignal.timeout(config.timeout!),\n      });\n    } catch (error) {\n      if (config.onError) {\n        await config.onError(error, c);\n        await next();\n        return;\n      }\n      throw new GatewayError(\n        502,\n        \"callout_failed\",\n        `External callout failed: ${error instanceof Error ? error.message : String(error)}`\n      );\n    }\n\n    // Check for non-2xx\n    if (!response.ok && config.abortOnFailure) {\n      if (config.onError) {\n        await config.onError(\n          new Error(`External callout returned ${response.status}`),\n          c\n        );\n        await next();\n        return;\n      }\n      throw new GatewayError(\n        502,\n        \"callout_failed\",\n        `External callout returned ${response.status}`\n      );\n    }\n\n    await config.onResponse(response, c);\n    await next();\n  },\n});\n"],"mappings":"AASA,SAAS,oBAAoB;AAC7B,SAAS,cAAc,gBAAgB;AAuDhC,MAAM,cAA4B,6BAAgC;AAAA,EACvE,MAAM;AAAA,EACN,UAAU,SAAS;AAAA,EACnB,UAAU;AAAA,EACV,UAAU,EAAE,QAAQ,OAAO,SAAS,KAAM,gBAAgB,KAAK;AAAA,EAC/D,SAAS,OAAO,GAAG,MAAM,EAAE,QAAQ,MAAM,MAAM;AAE7C,UAAM,MACJ,OAAO,OAAO,QAAQ,aAAa,MAAM,OAAO,IAAI,CAAC,IAAI,OAAO;AAGlE,UAAM,kBAA0C,CAAC;AACjD,QAAI,OAAO,SAAS;AAClB,iBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,OAAO,GAAG;AACzD,wBAAgB,GAAG,IACjB,OAAO,UAAU,aAAa,MAAM,MAAM,CAAC,IAAI;AAAA,MACnD;AAAA,IACF;AAGA,QAAI;AACJ,QAAI,OAAO,SAAS,QAAW;AAC7B,YAAM,MACJ,OAAO,OAAO,SAAS,aACnB,MAAO,OAAO,KAAoD,CAAC,IACnE,OAAO;AACb,UAAI,QAAQ,UAAa,QAAQ,MAAM;AACrC,uBAAe,OAAO,QAAQ,WAAW,MAAM,KAAK,UAAU,GAAG;AACjE,YAAI,OAAO,QAAQ,YAAY,CAAC,gBAAgB,cAAc,GAAG;AAC/D,0BAAgB,cAAc,IAAI;AAAA,QACpC;AAAA,MACF;AAAA,IACF;AAEA,UAAM,GAAG,OAAO,MAAM,IAAI,GAAG,EAAE;AAE/B,QAAI;AACJ,QAAI;AACF,iBAAW,MAAM,MAAM,KAAK;AAAA,QAC1B,QAAQ,OAAO;AAAA,QACf,SAAS;AAAA,QACT,MAAM;AAAA,QACN,QAAQ,YAAY,QAAQ,OAAO,OAAQ;AAAA,MAC7C,CAAC;AAAA,IACH,SAAS,OAAO;AACd,UAAI,OAAO,SAAS;AAClB,cAAM,OAAO,QAAQ,OAAO,CAAC;AAC7B,cAAM,KAAK;AACX;AAAA,MACF;AACA,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA,4BAA4B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAAA,MACpF;AAAA,IACF;AAGA,QAAI,CAAC,SAAS,MAAM,OAAO,gBAAgB;AACzC,UAAI,OAAO,SAAS;AAClB,cAAM,OAAO;AAAA,UACX,IAAI,MAAM,6BAA6B,SAAS,MAAM,EAAE;AAAA,UACxD;AAAA,QACF;AACA,cAAM,KAAK;AACX;AAAA,MACF;AACA,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA,6BAA6B,SAAS,MAAM;AAAA,MAC9C;AAAA,IACF;AAEA,UAAM,OAAO,WAAW,UAAU,CAAC;AACnC,UAAM,KAAK;AAAA,EACb;AACF,CAAC;","names":[]}

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

@@ -0,0 +1,46 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import { Context } from 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface InterruptConfig extends PolicyConfig {
+    /** Predicate that determines whether to short-circuit. Required. */
+    condition: (c: Context) => boolean | Promise<boolean>;
+    /** HTTP status code for the interrupt response. Default: 200. */
+    statusCode?: number;
+    /** Response body. String → text/plain, object → application/json, undefined → empty. */
+    body?: unknown;
+    /** Additional response headers. */
+    headers?: Record<string, string>;
+}
+/**
+ * Conditionally short-circuit the pipeline and return a static response.
+ *
+ * Evaluates a predicate against the incoming request context. When the
+ * condition returns `true`, the pipeline is interrupted - a response is
+ * returned immediately and `next()` is never called (upstream is skipped).
+ * When the condition returns `false`, the pipeline continues normally.
+ *
+ * @param config - Condition predicate, status code, body, and headers.
+ * @returns A {@link Policy} at priority 100 (default - users typically set a custom priority).
+ *
+ * @example
+ * ```ts
+ * // Maintenance mode
+ * interrupt({
+ *   condition: (c) => c.req.header("x-maintenance") === "true",
+ *   statusCode: 503,
+ *   body: { maintenance: true, message: "Back soon" },
+ *   headers: { "retry-after": "300" },
+ * });
+ *
+ * // Health check short-circuit
+ * interrupt({
+ *   condition: (c) => c.req.path === "/healthz",
+ *   body: "ok",
+ * });
+ * ```
+ */
+declare const interrupt: (config: InterruptConfig) => Policy;
+
+export { type InterruptConfig, interrupt };

package/dist/policies/traffic/interrupt.js

@@ -0,0 +1,38 @@
+import { definePolicy, Priority } from "../sdk";
+const interrupt = /* @__PURE__ */ definePolicy({
+  name: "interrupt",
+  priority: Priority.DEFAULT,
+  httpOnly: true,
+  defaults: { statusCode: 200, headers: {} },
+  handler: async (c, next, { config, debug }) => {
+    const shouldInterrupt = await config.condition(c);
+    if (!shouldInterrupt) {
+      debug("condition false, continuing pipeline");
+      await next();
+      return;
+    }
+    debug("condition true, short-circuiting");
+    const responseHeaders = new Headers(config.headers);
+    let body = null;
+    if (config.body === void 0 || config.body === null) {
+    } else if (typeof config.body === "string") {
+      body = config.body;
+      if (!responseHeaders.has("content-type")) {
+        responseHeaders.set("content-type", "text/plain");
+      }
+    } else {
+      body = JSON.stringify(config.body);
+      if (!responseHeaders.has("content-type")) {
+        responseHeaders.set("content-type", "application/json");
+      }
+    }
+    c.res = new Response(body, {
+      status: config.statusCode,
+      headers: responseHeaders
+    });
+  }
+});
+export {
+  interrupt
+};
+//# sourceMappingURL=interrupt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/traffic/interrupt.ts"],"sourcesContent":["/**\n * Interrupt policy - conditionally short-circuit the pipeline with a static response.\n *\n * @module interrupt\n */\nimport type { Context } from \"hono\";\nimport { definePolicy, Priority } from \"../sdk\";\nimport type { PolicyConfig } from \"../types\";\n\nexport interface InterruptConfig extends PolicyConfig {\n  /** Predicate that determines whether to short-circuit. Required. */\n  condition: (c: Context) => boolean | Promise<boolean>;\n  /** HTTP status code for the interrupt response. Default: 200. */\n  statusCode?: number;\n  /** Response body. String → text/plain, object → application/json, undefined → empty. */\n  body?: unknown;\n  /** Additional response headers. */\n  headers?: Record<string, string>;\n}\n\n/**\n * Conditionally short-circuit the pipeline and return a static response.\n *\n * Evaluates a predicate against the incoming request context. When the\n * condition returns `true`, the pipeline is interrupted - a response is\n * returned immediately and `next()` is never called (upstream is skipped).\n * When the condition returns `false`, the pipeline continues normally.\n *\n * @param config - Condition predicate, status code, body, and headers.\n * @returns A {@link Policy} at priority 100 (default - users typically set a custom priority).\n *\n * @example\n * ```ts\n * // Maintenance mode\n * interrupt({\n *   condition: (c) => c.req.header(\"x-maintenance\") === \"true\",\n *   statusCode: 503,\n *   body: { maintenance: true, message: \"Back soon\" },\n *   headers: { \"retry-after\": \"300\" },\n * });\n *\n * // Health check short-circuit\n * interrupt({\n *   condition: (c) => c.req.path === \"/healthz\",\n *   body: \"ok\",\n * });\n * ```\n */\nexport const interrupt = /*#__PURE__*/ definePolicy<InterruptConfig>({\n  name: \"interrupt\",\n  priority: Priority.DEFAULT,\n  httpOnly: true,\n  defaults: { statusCode: 200, headers: {} },\n  handler: async (c, next, { config, debug }) => {\n    const shouldInterrupt = await config.condition(c);\n\n    if (!shouldInterrupt) {\n      debug(\"condition false, continuing pipeline\");\n      await next();\n      return;\n    }\n\n    debug(\"condition true, short-circuiting\");\n\n    const responseHeaders = new Headers(config.headers);\n\n    let body: string | null = null;\n    if (config.body === undefined || config.body === null) {\n      // empty body\n    } else if (typeof config.body === \"string\") {\n      body = config.body;\n      if (!responseHeaders.has(\"content-type\")) {\n        responseHeaders.set(\"content-type\", \"text/plain\");\n      }\n    } else {\n      body = JSON.stringify(config.body);\n      if (!responseHeaders.has(\"content-type\")) {\n        responseHeaders.set(\"content-type\", \"application/json\");\n      }\n    }\n\n    c.res = new Response(body, {\n      status: config.statusCode!,\n      headers: responseHeaders,\n    });\n  },\n});\n"],"mappings":"AAMA,SAAS,cAAc,gBAAgB;AA0ChC,MAAM,YAA0B,6BAA8B;AAAA,EACnE,MAAM;AAAA,EACN,UAAU,SAAS;AAAA,EACnB,UAAU;AAAA,EACV,UAAU,EAAE,YAAY,KAAK,SAAS,CAAC,EAAE;AAAA,EACzC,SAAS,OAAO,GAAG,MAAM,EAAE,QAAQ,MAAM,MAAM;AAC7C,UAAM,kBAAkB,MAAM,OAAO,UAAU,CAAC;AAEhD,QAAI,CAAC,iBAAiB;AACpB,YAAM,sCAAsC;AAC5C,YAAM,KAAK;AACX;AAAA,IACF;AAEA,UAAM,kCAAkC;AAExC,UAAM,kBAAkB,IAAI,QAAQ,OAAO,OAAO;AAElD,QAAI,OAAsB;AAC1B,QAAI,OAAO,SAAS,UAAa,OAAO,SAAS,MAAM;AAAA,IAEvD,WAAW,OAAO,OAAO,SAAS,UAAU;AAC1C,aAAO,OAAO;AACd,UAAI,CAAC,gBAAgB,IAAI,cAAc,GAAG;AACxC,wBAAgB,IAAI,gBAAgB,YAAY;AAAA,MAClD;AAAA,IACF,OAAO;AACL,aAAO,KAAK,UAAU,OAAO,IAAI;AACjC,UAAI,CAAC,gBAAgB,IAAI,cAAc,GAAG;AACxC,wBAAgB,IAAI,gBAAgB,kBAAkB;AAAA,MACxD;AAAA,IACF;AAEA,MAAE,MAAM,IAAI,SAAS,MAAM;AAAA,MACzB,QAAQ,OAAO;AAAA,MACf,SAAS;AAAA,IACX,CAAC;AAAA,EACH;AACF,CAAC;","names":[]}

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

@@ -0,0 +1,47 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+/**
+ * IP allowlist/denylist filtering policy.
+ *
+ * Supports both HTTP (`handler`) and protocol-agnostic (`evaluate`) entry
+ * points. The evaluate path uses {@link PolicyInput.clientIp} when available
+ * (set by the runtime), falling back to header extraction.
+ *
+ * @module ip-filter
+ */
+
+interface IpFilterConfig extends PolicyConfig {
+    /** IPs or CIDR ranges to allow (allowlist mode). */
+    allow?: string[];
+    /** IPs or CIDR ranges to deny (denylist mode). */
+    deny?: string[];
+    /** Filter mode. Default: "deny". */
+    mode?: "allow" | "deny";
+    /** Ordered list of headers to inspect for the client IP. Default: `["cf-connecting-ip", "x-forwarded-for"]`. */
+    ipHeaders?: string[];
+}
+/**
+ * Block or allow requests based on client IP address or CIDR range.
+ *
+ * Supports both allowlist and denylist modes. Client IP is extracted from
+ * `CF-Connecting-IP` (Cloudflare) or `X-Forwarded-For`. Accepts individual
+ * IPs (`192.168.1.1`) and CIDR notation (`10.0.0.0/8`).
+ *
+ * @param config - IP filter rules and mode selection.
+ * @returns A {@link Policy} at priority 1 (runs before everything else).
+ *
+ * @example
+ * ```ts
+ * // Allow only internal IPs
+ * ipFilter({ mode: "allow", allow: ["10.0.0.0/8", "172.16.0.0/12"] });
+ *
+ * // Block known bad actors
+ * ipFilter({ deny: ["203.0.113.0/24", "198.51.100.42"] });
+ * ```
+ */
+declare function ipFilter(config: IpFilterConfig): Policy;
+
+export { type IpFilterConfig, ipFilter };

package/dist/policies/traffic/ip-filter.js

@@ -0,0 +1,57 @@
+import { GatewayError } from "../../core/errors";
+import { isInRange, parseCIDR } from "../../utils/cidr";
+import { extractClientIp } from "../../utils/ip";
+import { Priority, withSkip } from "../sdk";
+function ipFilter(config) {
+  const mode = config.mode ?? "deny";
+  const ipHeaderOptions = config.ipHeaders ? { ipHeaders: config.ipHeaders } : {};
+  const allowRanges = (config.allow ?? []).map(parseCIDR).filter((r) => r !== null);
+  const denyRanges = (config.deny ?? []).map(parseCIDR).filter((r) => r !== null);
+  function checkIp(ip) {
+    if (mode === "allow") {
+      if (!isInRange(ip, allowRanges)) {
+        return {
+          action: "reject",
+          status: 403,
+          code: "ip_denied",
+          message: "Access denied"
+        };
+      }
+    } else {
+      if (isInRange(ip, denyRanges)) {
+        return {
+          action: "reject",
+          status: 403,
+          code: "ip_denied",
+          message: "Access denied"
+        };
+      }
+    }
+    return { action: "continue" };
+  }
+  const handler = async (c, next) => {
+    const ip = extractClientIp(c.req.raw.headers, ipHeaderOptions);
+    const result = checkIp(ip);
+    if (result.action === "reject") {
+      throw new GatewayError(result.status, result.code, result.message);
+    }
+    await next();
+  };
+  return {
+    name: "ip-filter",
+    priority: Priority.IP_FILTER,
+    handler: withSkip(config.skip, handler),
+    phases: ["request-headers"],
+    // ── Protocol-agnostic evaluator ────────────────────────────────
+    evaluate: {
+      onRequest: async (input) => {
+        const ip = input.clientIp ?? extractClientIp(input.headers, ipHeaderOptions);
+        return checkIp(ip);
+      }
+    }
+  };
+}
+export {
+  ipFilter
+};
+//# sourceMappingURL=ip-filter.js.map

package/dist/policies/traffic/ip-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/traffic/ip-filter.ts"],"sourcesContent":["/**\n * IP allowlist/denylist filtering policy.\n *\n * Supports both HTTP (`handler`) and protocol-agnostic (`evaluate`) entry\n * points. The evaluate path uses {@link PolicyInput.clientIp} when available\n * (set by the runtime), falling back to header extraction.\n *\n * @module ip-filter\n */\n\nimport { GatewayError } from \"../../core/errors\";\nimport type { PolicyInput, PolicyResult } from \"../../core/protocol\";\nimport { isInRange, type ParsedCIDR, parseCIDR } from \"../../utils/cidr\";\nimport { type ExtractClientIpOptions, extractClientIp } from \"../../utils/ip\";\nimport { Priority, withSkip } from \"../sdk\";\nimport type { Policy, PolicyConfig } from \"../types\";\n\nexport interface IpFilterConfig extends PolicyConfig {\n  /** IPs or CIDR ranges to allow (allowlist mode). */\n  allow?: string[];\n  /** IPs or CIDR ranges to deny (denylist mode). */\n  deny?: string[];\n  /** Filter mode. Default: \"deny\". */\n  mode?: \"allow\" | \"deny\";\n  /** Ordered list of headers to inspect for the client IP. Default: `[\"cf-connecting-ip\", \"x-forwarded-for\"]`. */\n  ipHeaders?: string[];\n}\n\n/**\n * Block or allow requests based on client IP address or CIDR range.\n *\n * Supports both allowlist and denylist modes. Client IP is extracted from\n * `CF-Connecting-IP` (Cloudflare) or `X-Forwarded-For`. Accepts individual\n * IPs (`192.168.1.1`) and CIDR notation (`10.0.0.0/8`).\n *\n * @param config - IP filter rules and mode selection.\n * @returns A {@link Policy} at priority 1 (runs before everything else).\n *\n * @example\n * ```ts\n * // Allow only internal IPs\n * ipFilter({ mode: \"allow\", allow: [\"10.0.0.0/8\", \"172.16.0.0/12\"] });\n *\n * // Block known bad actors\n * ipFilter({ deny: [\"203.0.113.0/24\", \"198.51.100.42\"] });\n * ```\n */\nexport function ipFilter(config: IpFilterConfig): Policy {\n  const mode = config.mode ?? \"deny\";\n  const ipHeaderOptions: ExtractClientIpOptions = config.ipHeaders\n    ? { ipHeaders: config.ipHeaders }\n    : {};\n  const allowRanges: ParsedCIDR[] = (config.allow ?? [])\n    .map(parseCIDR)\n    .filter((r): r is ParsedCIDR => r !== null);\n  const denyRanges: ParsedCIDR[] = (config.deny ?? [])\n    .map(parseCIDR)\n    .filter((r): r is ParsedCIDR => r !== null);\n\n  // ── Shared logic - used by both handler and evaluate ────────────\n  function checkIp(ip: string): PolicyResult {\n    if (mode === \"allow\") {\n      if (!isInRange(ip, allowRanges)) {\n        return {\n          action: \"reject\",\n          status: 403,\n          code: \"ip_denied\",\n          message: \"Access denied\",\n        };\n      }\n    } else {\n      if (isInRange(ip, denyRanges)) {\n        return {\n          action: \"reject\",\n          status: 403,\n          code: \"ip_denied\",\n          message: \"Access denied\",\n        };\n      }\n    }\n    return { action: \"continue\" };\n  }\n\n  // ── HTTP handler (Hono middleware) ──────────────────────────────\n  const handler: import(\"hono\").MiddlewareHandler = async (c, next) => {\n    const ip = extractClientIp(c.req.raw.headers, ipHeaderOptions);\n    const result = checkIp(ip);\n    if (result.action === \"reject\") {\n      throw new GatewayError(result.status, result.code, result.message);\n    }\n    await next();\n  };\n\n  return {\n    name: \"ip-filter\",\n    priority: Priority.IP_FILTER,\n    handler: withSkip(config.skip, handler),\n    phases: [\"request-headers\"],\n    // ── Protocol-agnostic evaluator ────────────────────────────────\n    evaluate: {\n      onRequest: async (input: PolicyInput) => {\n        const ip =\n          input.clientIp ?? extractClientIp(input.headers, ipHeaderOptions);\n        return checkIp(ip);\n      },\n    },\n  };\n}\n"],"mappings":"AAUA,SAAS,oBAAoB;AAE7B,SAAS,WAA4B,iBAAiB;AACtD,SAAsC,uBAAuB;AAC7D,SAAS,UAAU,gBAAgB;AAiC5B,SAAS,SAAS,QAAgC;AACvD,QAAM,OAAO,OAAO,QAAQ;AAC5B,QAAM,kBAA0C,OAAO,YACnD,EAAE,WAAW,OAAO,UAAU,IAC9B,CAAC;AACL,QAAM,eAA6B,OAAO,SAAS,CAAC,GACjD,IAAI,SAAS,EACb,OAAO,CAAC,MAAuB,MAAM,IAAI;AAC5C,QAAM,cAA4B,OAAO,QAAQ,CAAC,GAC/C,IAAI,SAAS,EACb,OAAO,CAAC,MAAuB,MAAM,IAAI;AAG5C,WAAS,QAAQ,IAA0B;AACzC,QAAI,SAAS,SAAS;AACpB,UAAI,CAAC,UAAU,IAAI,WAAW,GAAG;AAC/B,eAAO;AAAA,UACL,QAAQ;AAAA,UACR,QAAQ;AAAA,UACR,MAAM;AAAA,UACN,SAAS;AAAA,QACX;AAAA,MACF;AAAA,IACF,OAAO;AACL,UAAI,UAAU,IAAI,UAAU,GAAG;AAC7B,eAAO;AAAA,UACL,QAAQ;AAAA,UACR,QAAQ;AAAA,UACR,MAAM;AAAA,UACN,SAAS;AAAA,QACX;AAAA,MACF;AAAA,IACF;AACA,WAAO,EAAE,QAAQ,WAAW;AAAA,EAC9B;AAGA,QAAM,UAA4C,OAAO,GAAG,SAAS;AACnE,UAAM,KAAK,gBAAgB,EAAE,IAAI,IAAI,SAAS,eAAe;AAC7D,UAAM,SAAS,QAAQ,EAAE;AACzB,QAAI,OAAO,WAAW,UAAU;AAC9B,YAAM,IAAI,aAAa,OAAO,QAAQ,OAAO,MAAM,OAAO,OAAO;AAAA,IACnE;AACA,UAAM,KAAK;AAAA,EACb;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU,SAAS;AAAA,IACnB,SAAS,SAAS,OAAO,MAAM,OAAO;AAAA,IACtC,QAAQ,CAAC,iBAAiB;AAAA;AAAA,IAE1B,UAAU;AAAA,MACR,WAAW,OAAO,UAAuB;AACvC,cAAM,KACJ,MAAM,YAAY,gBAAgB,MAAM,SAAS,eAAe;AAClE,eAAO,QAAQ,EAAE;AAAA,MACnB;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/policies/traffic/json-threat-protection.d.ts

@@ -0,0 +1,51 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface JsonThreatProtectionConfig extends PolicyConfig {
+    /** Maximum nesting depth. Default: `20`. */
+    maxDepth?: number;
+    /** Maximum number of keys per object. Default: `100`. */
+    maxKeys?: number;
+    /** Maximum string value length (also applies to object keys). Default: `10000`. */
+    maxStringLength?: number;
+    /** Maximum array length. Default: `100`. */
+    maxArraySize?: number;
+    /** Maximum raw body size in bytes. Checked BEFORE parsing. Default: `1048576` (1 MB). */
+    maxBodySize?: number;
+    /**
+     * Content types to inspect.
+     * Requests with other content types pass through without inspection.
+     * Default: `["application/json"]`.
+     */
+    contentTypes?: string[];
+}
+/**
+ * JSON threat protection policy.
+ *
+ * Enforces structural limits on JSON request bodies to prevent abuse
+ * from deeply nested objects, excessively large arrays, long strings,
+ * or oversized payloads. Runs at EARLY priority to reject malicious
+ * payloads before they reach business logic.
+ *
+ * @example
+ * ```ts
+ * import { jsonThreatProtection } from "@vivero/stoma";
+ *
+ * // Default limits (20 depth, 100 keys, 10K string, 100 array, 1MB body)
+ * jsonThreatProtection();
+ *
+ * // Strict limits for a public API
+ * jsonThreatProtection({
+ *   maxDepth: 5,
+ *   maxKeys: 20,
+ *   maxStringLength: 1000,
+ *   maxArraySize: 50,
+ *   maxBodySize: 102400, // 100KB
+ * });
+ * ```
+ */
+declare const jsonThreatProtection: (config?: JsonThreatProtectionConfig | undefined) => Policy;
+
+export { type JsonThreatProtectionConfig, jsonThreatProtection };