@nymbalhq/security-cloudflare 0.0.0-stage → 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+import { AdapterError, SecurityAdapter, SecurityConfigLike, DriftReport, SecurityState, Logger, AdapterContext } from '@nymbalhq/types';
+
+/** The entrypoint phases Nymbal writes, in the order `apply` writes them. */
+declare const PHASES: readonly ["http_ratelimit", "http_request_firewall_custom", "http_request_firewall_managed", "http_request_cache_settings"];
+type Phase = (typeof PHASES)[number];
+/** A ruleset rule as the Cloudflare v4 API reads and writes it. */
+interface Rule {
+    id?: string;
+    ref?: string;
+    description?: string;
+    expression: string;
+    action: string;
+    action_parameters?: Record<string, unknown>;
+    ratelimit?: {
+        characteristics: string[];
+        period: number;
+        requests_per_period: number;
+        mitigation_timeout: number;
+    };
+    enabled?: boolean;
+    [key: string]: unknown;
+}
+declare const isNymbalRule: (rule: {
+    ref?: unknown;
+}) => boolean;
+/** Each `rateLimit` window Cloudflare has a period for, in seconds. */
+declare const WINDOW_PERIODS: Readonly<Record<string, number>>;
+/** Cloudflare's own managed rulesets, by the name `managedRulesets` uses. */
+declare const MANAGED_RULESET_IDS: {
+    readonly cloudflare: "efb7b8c949ac4650a09736fc376e9aee";
+    readonly owasp: "4814384a9e5d4991b9815dcfc25d2f1f";
+};
+interface RateLimitEntry {
+    requests: number;
+    window: string;
+    action: 'block' | 'challenge' | 'throttle';
+}
+interface CustomRule {
+    name: string;
+    expression: string;
+    action: 'block' | 'managed_challenge' | 'js_challenge' | 'log';
+}
+/** The parts of the `security` block the edge rules come from; every one may be absent. */
+interface EdgeRulesConfig {
+    rateLimit?: Record<string, RateLimitEntry>;
+    geo?: {
+        block?: string[];
+    };
+    customRules?: CustomRule[];
+    managedRulesets?: string[];
+}
+/** A key with a `*` that is not part of `**`: one segment at the origin, any number at the edge. */
+declare const hasSingleStar: (key: string) => boolean;
+/**
+ * The rules the config puts on the zone, by phase, every one carrying a `nymbal:` ref. Rate limits follow their keys'
+ * sorted order and custom rules their config order, so the same config always gives the same rules. A key that is not
+ * a path, or a window with no Cloudflare period, gives no rule: `validate` reports both.
+ */
+declare function desiredRules(config: EdgeRulesConfig): Record<Phase, Rule[]>;
+
+declare const DEFAULT_API_BASE = "https://api.cloudflare.com/client/v4";
+declare const REQUEST_TIMEOUT_MS = 5000;
+/** The `security.cloudflare` block: the adapter's `ctx.config`. */
+interface CloudflareConnection {
+    zoneId?: string;
+    apiToken?: string;
+    apiBase?: string;
+}
+/** The token or zone was refused (401 or 403), or the config has none. */
+declare class CloudflareCredentialsError extends AdapterError {
+    constructor(detail: string, context?: Record<string, unknown>);
+}
+
+type Plan = 'free' | 'pro' | 'business' | 'enterprise';
+/** What each plan allows; every limit counts every rule in the phase, the zone owner's included. */
+declare const PLAN_LIMITS: Readonly<Record<Plan, {
+    rateLimitRules: number;
+    periods: readonly number[];
+    customRules: number;
+    managedRulesets: boolean;
+    cacheRules: number;
+}>>;
+interface PhasePlan {
+    phase: Phase;
+    add: Rule[];
+    /** `position` is set when the rule is out of place: its index on the zone, and the one `apply` writes it at. */
+    change: Array<{
+        ref: string;
+        from: Rule;
+        to: Rule;
+        position?: {
+            from: number;
+            to: number;
+        };
+    }>;
+    remove: Rule[];
+}
+/** What `apply` would change (from `plan`) or changed (from `apply`), phase by phase. */
+interface SecurityPlan {
+    phases: PhasePlan[];
+}
+declare const isEmptyPlan: (plan: SecurityPlan) => boolean;
+interface CloudflareSecurityAdapter extends SecurityAdapter {
+    drift(config: SecurityConfigLike): Promise<DriftReport>;
+    inspect(): Promise<SecurityState>;
+    plan(config: SecurityConfigLike): Promise<SecurityPlan>;
+    /** Writes each phase whose Nymbal rules differ, one by one; it rejects at the first refused write. */
+    apply(config: SecurityConfigLike): Promise<SecurityPlan>;
+}
+declare function createCloudflareSecurityAdapter(deps: {
+    connection: CloudflareConnection;
+    logger: Logger;
+}): CloudflareSecurityAdapter;
+
+/** The kernel's entry: `security: { adapter: 'cloudflare', cloudflare: CloudflareConnection }`. */
+declare function createAdapter(ctx: AdapterContext): CloudflareSecurityAdapter;
+
+export { CloudflareCredentialsError, DEFAULT_API_BASE, MANAGED_RULESET_IDS, PHASES, PLAN_LIMITS, REQUEST_TIMEOUT_MS, WINDOW_PERIODS, createAdapter, createCloudflareSecurityAdapter, desiredRules, hasSingleStar, isEmptyPlan, isNymbalRule };
+export type { CloudflareConnection, CloudflareSecurityAdapter, EdgeRulesConfig, Phase, PhasePlan, Plan, Rule, SecurityPlan };

package/dist/index.js

@@ -0,0 +1,547 @@
+// src/index.ts
+import { ConfigError } from "@nymbalhq/types";
+
+// src/adapter.ts
+import {
+  AdapterError as AdapterError2,
+  boundedHealthCheck,
+  buildSecurityHeaders,
+  errorText as errorText2
+} from "@nymbalhq/types";
+
+// src/client.ts
+import { AdapterError, errorText } from "@nymbalhq/types";
+var DEFAULT_API_BASE = "https://api.cloudflare.com/client/v4";
+var REQUEST_TIMEOUT_MS = 5e3;
+var CREDENTIALS_HINT = "check security.cloudflare.zoneId and apiToken (CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_TOKEN): the token needs Zone \u203A Zone \u203A Read, Zone \u203A Zone WAF \u203A Edit and Zone \u203A Cache Rules \u203A Edit on the zone";
+var CloudflareCredentialsError = class extends AdapterError {
+  constructor(detail, context = {}) {
+    super("cloudflare_credentials", `Cloudflare: ${detail}; ${CREDENTIALS_HINT}`, { context });
+  }
+};
+function hasCredentials(connection) {
+  return Boolean(connection.zoneId) && Boolean(connection.apiToken);
+}
+function apiErrors(body) {
+  const errors = body?.errors ?? [];
+  const messages = errors.map((e) => e.message).filter((m) => typeof m === "string");
+  return messages.length > 0 ? messages.join("; ") : "no error message";
+}
+function createClient(connection) {
+  const base = (connection.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  const zonePath = `/zones/${encodeURIComponent(connection.zoneId ?? "")}`;
+  async function request(method, path, body) {
+    if (!hasCredentials(connection)) {
+      throw new CloudflareCredentialsError("no zone ID or API token is configured");
+    }
+    let response;
+    let text;
+    try {
+      response = await fetch(`${base}${path}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${connection.apiToken}`,
+          ...body !== void 0 && { "content-type": "application/json" }
+        },
+        ...body !== void 0 && { body: JSON.stringify(body) },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+      });
+      text = await response.text();
+    } catch (error) {
+      throw new AdapterError(
+        "cloudflare_unreachable",
+        `Cloudflare API at ${base} did not answer ${method} ${path}: ${errorText(error)}`,
+        { cause: error, context: { method, path } }
+      );
+    }
+    let parsed;
+    try {
+      parsed = text === "" ? void 0 : JSON.parse(text);
+    } catch {
+      parsed = void 0;
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new CloudflareCredentialsError(
+        `${method} ${path} was refused (${response.status}: ${apiErrors(parsed)})`,
+        { status: response.status }
+      );
+    }
+    if (response.ok && (typeof parsed !== "object" || parsed === null)) {
+      throw new AdapterError(
+        "cloudflare_api",
+        `Cloudflare answered ${method} ${path} with ${response.status} and no JSON body`,
+        { context: { method, path, status: response.status } }
+      );
+    }
+    return { status: response.status, body: parsed };
+  }
+  const failed = (method, path, status, body) => new AdapterError(
+    "cloudflare_api",
+    `Cloudflare answered ${method} ${path} with ${status}: ${apiErrors(body)}`,
+    { context: { method, path, status } }
+  );
+  return {
+    async zone() {
+      const { status, body } = await request("GET", zonePath);
+      if (status === 404) {
+        throw new CloudflareCredentialsError(`zone ${connection.zoneId} was not found`, { status });
+      }
+      if (status !== 200) throw failed("GET", zonePath, status, body);
+      return body.result;
+    },
+    async entrypoint(phase) {
+      const path = `${zonePath}/rulesets/phases/${phase}/entrypoint`;
+      const { status, body } = await request("GET", path);
+      if (status === 404) return void 0;
+      if (status !== 200) throw failed("GET", path, status, body);
+      return body.result?.rules ?? [];
+    },
+    async putEntrypoint(phase, rules) {
+      const path = `${zonePath}/rulesets/phases/${phase}/entrypoint`;
+      const { status, body } = await request("PUT", path, { rules });
+      if (status !== 200) throw failed("PUT", path, status, body);
+    }
+  };
+}
+
+// src/rules.ts
+var PHASES = [
+  "http_ratelimit",
+  "http_request_firewall_custom",
+  "http_request_firewall_managed",
+  "http_request_cache_settings"
+];
+var NYMBAL_REF_PREFIX = "nymbal:";
+var isNymbalRule = (rule) => typeof rule.ref === "string" && rule.ref.startsWith(NYMBAL_REF_PREFIX);
+var WINDOW_PERIODS = {
+  "10s": 10,
+  "1m": 60,
+  "2m": 120,
+  "5m": 300,
+  "10m": 600,
+  "1h": 3600
+};
+var MANAGED_RULESET_IDS = {
+  cloudflare: "efb7b8c949ac4650a09736fc376e9aee",
+  owasp: "4814384a9e5d4991b9815dcfc25d2f1f"
+};
+var MANAGED_NAMES = {
+  cloudflare: "Cloudflare Managed Ruleset",
+  owasp: "Cloudflare OWASP Core Ruleset"
+};
+var quoted = (text) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+function pathExpression(key) {
+  return key.includes("*") ? `http.request.uri.path wildcard ${quoted(key.replace(/\*+/g, "*"))}` : `http.request.uri.path eq ${quoted(key)}`;
+}
+var hasSingleStar = (key) => /(^|[^*])\*([^*]|$)/.test(key);
+var isEdgePath = (key) => key.startsWith("/");
+function rateLimitRule(key, entry) {
+  const period = WINDOW_PERIODS[entry.window];
+  if (!isEdgePath(key) || period === void 0) return void 0;
+  const [action, mitigationTimeout] = entry.action === "challenge" ? ["managed_challenge", 0] : entry.action === "throttle" ? ["block", 0] : ["block", period];
+  return {
+    ref: `${NYMBAL_REF_PREFIX}ratelimit:${key}`,
+    description: `${NYMBAL_REF_PREFIX} rate limit ${key}`,
+    expression: pathExpression(key),
+    action,
+    ratelimit: {
+      characteristics: ["cf.colo.id", "ip.src"],
+      period,
+      requests_per_period: entry.requests,
+      mitigation_timeout: mitigationTimeout
+    },
+    enabled: true
+  };
+}
+var fragmentCacheRule = () => ({
+  ref: `${NYMBAL_REF_PREFIX}cache:fragments`,
+  description: `${NYMBAL_REF_PREFIX} cache the fragment routes`,
+  expression: 'starts_with(http.request.uri.path, "/fragments/")',
+  action: "set_cache_settings",
+  action_parameters: {
+    cache: true,
+    edge_ttl: { mode: "respect_origin" },
+    browser_ttl: { mode: "respect_origin" }
+  },
+  enabled: true
+});
+function desiredRules(config) {
+  const rateLimits = Object.entries(config.rateLimit ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).flatMap(([key, entry]) => rateLimitRule(key, entry) ?? []);
+  const custom = [];
+  const blocked = config.geo?.block ?? [];
+  if (blocked.length > 0) {
+    custom.push({
+      ref: `${NYMBAL_REF_PREFIX}geo:block`,
+      description: `${NYMBAL_REF_PREFIX} geo block ${blocked.join(" ")}`,
+      expression: `ip.src.country in {${blocked.map(quoted).join(" ")}}`,
+      action: "block",
+      enabled: true
+    });
+  }
+  for (const rule of config.customRules ?? []) {
+    custom.push({
+      ref: `${NYMBAL_REF_PREFIX}custom:${rule.name}`,
+      description: `${NYMBAL_REF_PREFIX} ${rule.name}`,
+      expression: rule.expression,
+      action: rule.action,
+      enabled: true
+    });
+  }
+  const managed = [...new Set(config.managedRulesets ?? [])].filter((name) => Object.hasOwn(MANAGED_RULESET_IDS, name)).map(
+    (name) => ({
+      ref: `${NYMBAL_REF_PREFIX}managed:${name}`,
+      description: `${NYMBAL_REF_PREFIX} ${MANAGED_NAMES[name]}`,
+      expression: "true",
+      action: "execute",
+      action_parameters: { id: MANAGED_RULESET_IDS[name] },
+      enabled: true
+    })
+  );
+  return {
+    http_ratelimit: rateLimits,
+    http_request_firewall_custom: custom,
+    http_request_firewall_managed: managed,
+    http_request_cache_settings: [fragmentCacheRule()]
+  };
+}
+
+// src/adapter.ts
+var PLAN_LIMITS = {
+  free: {
+    rateLimitRules: 1,
+    periods: [10],
+    customRules: 5,
+    managedRulesets: false,
+    cacheRules: 10
+  },
+  pro: {
+    rateLimitRules: 2,
+    periods: [10, 60],
+    customRules: 20,
+    managedRulesets: true,
+    cacheRules: 25
+  },
+  business: {
+    rateLimitRules: 5,
+    periods: [10, 60, 120, 300, 600],
+    customRules: 100,
+    managedRulesets: true,
+    cacheRules: 50
+  },
+  enterprise: {
+    rateLimitRules: 100,
+    periods: [10, 60, 120, 300, 600, 3600],
+    customRules: 1e3,
+    managedRulesets: true,
+    cacheRules: 300
+  }
+};
+var isPlan = (value) => typeof value === "string" && Object.hasOwn(PLAN_LIMITS, value);
+var isEmptyPlan = (plan) => plan.phases.every((p) => p.add.length + p.change.length + p.remove.length === 0);
+function holds(desired, live) {
+  if (Array.isArray(desired)) {
+    return Array.isArray(live) && live.length === desired.length && desired.every((d, i) => holds(d, live[i]));
+  }
+  if (typeof desired === "object" && desired !== null) {
+    if (typeof live !== "object" || live === null) return false;
+    return Object.entries(desired).every(([k, v]) => holds(v, live[k]));
+  }
+  return desired === live;
+}
+var changedFields = (desired, live) => Object.keys(desired).filter((field) => !holds(desired[field], live[field]));
+function byRef(rules) {
+  return new Map(rules.filter(isNymbalRule).map((r) => [r.ref, r]));
+}
+var keyOf = (rule) => isNymbalRule(rule) ? `ref:${String(rule.ref)}` : `id:${String(rule.id)}`;
+function misplaced(live, desired) {
+  const wanted = byRef(desired);
+  const kept = live.filter((r) => !isNymbalRule(r) || wanted.has(r.ref));
+  const ours = kept.flatMap((r, i) => isNymbalRule(r) ? [i] : []);
+  const liveRefs = ours.map((i) => kept[i].ref);
+  const present = new Set(liveRefs);
+  const inOrder = desired.filter((r) => present.has(r.ref)).map((r) => r.ref);
+  const oneRun = ours.length === 0 || ours[ours.length - 1] - ours[0] === ours.length - 1;
+  const out = /* @__PURE__ */ new Map();
+  if (oneRun && liveRefs.every((ref, i) => ref === inOrder[i])) return out;
+  const written = nextRules(kept, desired).filter(
+    (r) => !isNymbalRule(r) || present.has(r.ref)
+  );
+  const target = new Map(written.map((r, i) => [keyOf(r), i]));
+  for (const i of ours) {
+    const ref = kept[i].ref;
+    const to = target.get(keyOf(kept[i]));
+    if (to !== i) out.set(ref, { from: i, to });
+  }
+  return out;
+}
+function diffPhase(phase, live, desired) {
+  const current = byRef(live);
+  const wanted = byRef(desired);
+  const moved = misplaced(live, desired);
+  const plan = { phase, add: [], change: [], remove: [] };
+  for (const [ref, to] of wanted) {
+    const from = current.get(ref);
+    const position = moved.get(ref);
+    if (from === void 0) plan.add.push(to);
+    else if (changedFields(to, from).length > 0 || position !== void 0) {
+      plan.change.push({ ref, from, to, ...position !== void 0 && { position } });
+    }
+  }
+  for (const [ref, rule] of current) if (!wanted.has(ref)) plan.remove.push(rule);
+  return plan;
+}
+function nextRules(live, desired) {
+  const ids = new Map(live.filter(isNymbalRule).map((r) => [r.ref, r.id]));
+  const own = live.filter((r) => !isNymbalRule(r)).map(({ version: _version, last_updated: _updated, ...rule }) => rule);
+  const ours = desired.map((rule) => {
+    const id = ids.get(rule.ref);
+    return id === void 0 ? rule : { ...rule, id };
+  });
+  return [...own, ...ours];
+}
+function createCloudflareSecurityAdapter(deps) {
+  const { connection, logger } = deps;
+  const client = createClient(connection);
+  let lastValidatedAt = "";
+  const livePhases = async () => {
+    const read = await Promise.all(PHASES.map((phase) => client.entrypoint(phase)));
+    return Object.fromEntries(PHASES.map((phase, i) => [phase, read[i] ?? []]));
+  };
+  const desiredOf = (config) => desiredRules(config);
+  function configErrors(config) {
+    const errors = [];
+    for (const [key, entry] of Object.entries(config.rateLimit ?? {})) {
+      if (!isEdgePath(key)) {
+        errors.push({
+          code: "cloudflare.path",
+          path: `rateLimit.${key}`,
+          message: `rate limit key '${key}' is not a path (it must start with /), so it has no edge rule`
+        });
+      }
+      if (WINDOW_PERIODS[entry.window] === void 0) {
+        errors.push({
+          code: "cloudflare.period",
+          path: `rateLimit.${key}.window`,
+          message: `window '${entry.window}' has no Cloudflare period; use one of ${Object.keys(WINDOW_PERIODS).join(", ")}`
+        });
+      }
+    }
+    for (const code of config.geo?.block ?? []) {
+      if (!/^[A-Z]{2}$/.test(code)) {
+        errors.push({
+          code: "cloudflare.geo",
+          path: "geo.block",
+          message: `'${code}' is not an ISO 3166 alpha-2 country code (two capital letters)`
+        });
+      }
+    }
+    return errors;
+  }
+  function planErrors(plan2, config, live) {
+    const limits = PLAN_LIMITS[plan2];
+    const errors = [];
+    for (const [key, entry] of Object.entries(config.rateLimit ?? {})) {
+      const period = WINDOW_PERIODS[entry.window];
+      if (period !== void 0 && !limits.periods.includes(period)) {
+        errors.push({
+          code: "cloudflare.period",
+          path: `rateLimit.${key}.window`,
+          message: `window '${entry.window}' is not allowed on the ${plan2} plan; it allows periods of ${limits.periods.join(", ")} s`
+        });
+      }
+      if (entry.action === "throttle" && plan2 !== "enterprise") {
+        errors.push({
+          code: "cloudflare.action",
+          path: `rateLimit.${key}.action`,
+          message: `throttle needs the enterprise plan; the zone is on the ${plan2} plan (use block or challenge)`
+        });
+      }
+    }
+    const desired = desiredRules(config);
+    const counted = [
+      ["http_ratelimit", limits.rateLimitRules, "rate limiting rules"],
+      ["http_request_firewall_custom", limits.customRules, "custom rules"],
+      ["http_request_cache_settings", limits.cacheRules, "cache rules"]
+    ];
+    for (const [phase, limit, what] of counted) {
+      const own = live[phase].filter((r) => !isNymbalRule(r)).length;
+      const total = own + desired[phase].length;
+      if (total > limit) {
+        errors.push({
+          code: "cloudflare.plan-limit",
+          path: phase,
+          message: `${phase} would hold ${total} ${what} (${own} of the zone's own, ${desired[phase].length} of Nymbal's); the ${plan2} plan allows ${limit}`
+        });
+      }
+    }
+    if (!limits.managedRulesets && desired.http_request_firewall_managed.length > 0) {
+      errors.push({
+        code: "cloudflare.plan-limit",
+        path: "managedRulesets",
+        message: `managed rulesets need the pro plan or above; the zone is on the ${plan2} plan`
+      });
+    }
+    return errors;
+  }
+  async function plan(config) {
+    const live = await livePhases();
+    const desired = desiredOf(config);
+    return { phases: PHASES.map((phase) => diffPhase(phase, live[phase], desired[phase])) };
+  }
+  return {
+    capabilities: () => ["headers", "edge-rules"],
+    producesEvents: [],
+    consumesEvents: [],
+    // Boot makes no request: the zone changes only by `nymbal security:apply`.
+    initialize: () => Promise.resolve(),
+    healthCheck() {
+      return boundedHealthCheck(async () => {
+        const zone = await client.zone();
+        const plan2 = zone.plan?.legacy_id ?? "unknown";
+        return { status: "healthy", detail: `zone ${zone.name ?? zone.id} on the ${plan2} plan` };
+      });
+    },
+    async applyMiddleware(app, config) {
+      app.setDefaultHeaders(buildSecurityHeaders(config));
+      logger.debug({}, "security headers attached");
+    },
+    async validate(config) {
+      const edge = config;
+      if (!hasCredentials(connection)) {
+        const missing = [
+          ...connection.zoneId ? [] : ["zoneId"],
+          ...connection.apiToken ? [] : ["apiToken"]
+        ];
+        return {
+          valid: false,
+          errors: [
+            {
+              code: "cloudflare.credentials",
+              path: "cloudflare",
+              message: `security.cloudflare has no ${missing.join(" or ")} (CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_TOKEN)`
+            }
+          ]
+        };
+      }
+      const errors = configErrors(edge);
+      try {
+        const zone = await client.zone();
+        const plan2 = zone.plan?.legacy_id;
+        if (!isPlan(plan2)) {
+          errors.push({
+            code: "cloudflare.plan-limit",
+            message: `the zone's plan '${String(plan2)}' is not one Nymbal knows the limits of (free, pro, business, enterprise)`
+          });
+        } else {
+          errors.push(...planErrors(plan2, edge, await livePhases()));
+        }
+      } catch (error) {
+        if (!(error instanceof CloudflareCredentialsError)) throw error;
+        errors.push({ code: "cloudflare.credentials", message: error.message });
+      }
+      lastValidatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      return { valid: errors.length === 0, errors };
+    },
+    plan,
+    async apply(config) {
+      const desired = desiredOf(config);
+      const written = [];
+      for (const phase of PHASES) {
+        const live = await client.entrypoint(phase);
+        const change = diffPhase(phase, live ?? [], desired[phase]);
+        if (change.add.length + change.change.length + change.remove.length === 0) continue;
+        try {
+          await client.putEntrypoint(phase, nextRules(live ?? [], desired[phase]));
+        } catch (error) {
+          const done = written.map((p) => p.phase);
+          throw new AdapterError2(
+            "cloudflare_apply",
+            `writing ${phase} failed after ${done.length === 0 ? "no phase" : done.join(", ")} was written: ${errorText2(error)}`,
+            { cause: error, context: { failed: phase, written: done } }
+          );
+        }
+        logger.info(
+          {
+            phase,
+            added: change.add.length,
+            changed: change.change.length,
+            removed: change.remove.length
+          },
+          `wrote ${phase}`
+        );
+        written.push(change);
+      }
+      return { phases: written };
+    },
+    async drift(config) {
+      const live = await livePhases();
+      const desired = desiredOf(config);
+      const differences = [];
+      for (const phase of PHASES) {
+        const { add, change, remove } = diffPhase(phase, live[phase], desired[phase]);
+        for (const rule of add) {
+          differences.push({ path: `${phase}/${rule.ref}`, configured: rule, actual: void 0 });
+        }
+        for (const { ref, from, to, position } of change) {
+          for (const field of changedFields(to, from)) {
+            differences.push({
+              path: `${phase}/${ref}/${field}`,
+              configured: to[field],
+              actual: from[field]
+            });
+          }
+          if (position !== void 0) {
+            differences.push({
+              path: `${phase}/${ref}/position`,
+              configured: position.to,
+              actual: position.from
+            });
+          }
+        }
+        for (const rule of remove) {
+          differences.push({ path: `${phase}/${rule.ref}`, configured: void 0, actual: rule });
+        }
+      }
+      return { drift: differences.length > 0, differences };
+    },
+    async inspect() {
+      const live = await livePhases();
+      return {
+        rulesApplied: PHASES.flatMap(
+          (phase) => live[phase].filter(isNymbalRule).map((r) => r.ref)
+        ),
+        lastValidatedAt
+      };
+    }
+  };
+}
+
+// src/index.ts
+function createAdapter(ctx) {
+  if (ctx.slot !== "security") {
+    throw new ConfigError(`@nymbalhq/security-cloudflare serves security, not ${ctx.slot}`, {
+      code: "adapter.wrong_slot",
+      context: { slot: ctx.slot }
+    });
+  }
+  return createCloudflareSecurityAdapter({
+    connection: ctx.config,
+    logger: ctx.logger
+  });
+}
+export {
+  CloudflareCredentialsError,
+  DEFAULT_API_BASE,
+  MANAGED_RULESET_IDS,
+  PHASES,
+  PLAN_LIMITS,
+  REQUEST_TIMEOUT_MS,
+  WINDOW_PERIODS,
+  createAdapter,
+  createCloudflareSecurityAdapter,
+  desiredRules,
+  hasSingleStar,
+  isEmptyPlan,
+  isNymbalRule
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/adapter.ts","../src/client.ts","../src/rules.ts"],"sourcesContent":["import { ConfigError, type AdapterContext } from '@nymbalhq/types'\nimport { createCloudflareSecurityAdapter, type CloudflareSecurityAdapter } from './adapter.js'\nimport type { CloudflareConnection } from './client.js'\n\nexport {\n  createCloudflareSecurityAdapter,\n  isEmptyPlan,\n  PLAN_LIMITS,\n  type CloudflareSecurityAdapter,\n  type PhasePlan,\n  type Plan,\n  type SecurityPlan,\n} from './adapter.js'\nexport {\n  CloudflareCredentialsError,\n  DEFAULT_API_BASE,\n  REQUEST_TIMEOUT_MS,\n  type CloudflareConnection,\n} from './client.js'\nexport {\n  desiredRules,\n  hasSingleStar,\n  isNymbalRule,\n  MANAGED_RULESET_IDS,\n  PHASES,\n  WINDOW_PERIODS,\n  type EdgeRulesConfig,\n  type Phase,\n  type Rule,\n} from './rules.js'\n\n/** The kernel's entry: `security: { adapter: 'cloudflare', cloudflare: CloudflareConnection }`. */\nexport function createAdapter(ctx: AdapterContext): CloudflareSecurityAdapter {\n  if (ctx.slot !== 'security') {\n    throw new ConfigError(`@nymbalhq/security-cloudflare serves security, not ${ctx.slot}`, {\n      code: 'adapter.wrong_slot',\n      context: { slot: ctx.slot },\n    })\n  }\n  return createCloudflareSecurityAdapter({\n    connection: ctx.config as CloudflareConnection,\n    logger: ctx.logger,\n  })\n}\n","import {\n  AdapterError,\n  boundedHealthCheck,\n  buildSecurityHeaders,\n  errorText,\n  type DriftReport,\n  type HttpAdapter,\n  type Logger,\n  type SecurityAdapter,\n  type SecurityConfigLike,\n  type SecurityState,\n  type ValidationResult,\n} from '@nymbalhq/types'\nimport {\n  CloudflareCredentialsError,\n  createClient,\n  hasCredentials,\n  type CloudflareClient,\n  type CloudflareConnection,\n} from './client.js'\nimport {\n  PHASES,\n  WINDOW_PERIODS,\n  desiredRules,\n  isEdgePath,\n  isNymbalRule,\n  type EdgeRulesConfig,\n  type Phase,\n  type Rule,\n} from './rules.js'\n\nexport type Plan = 'free' | 'pro' | 'business' | 'enterprise'\n\n/** What each plan allows; every limit counts every rule in the phase, the zone owner's included. */\nexport const PLAN_LIMITS: Readonly<\n  Record<\n    Plan,\n    {\n      rateLimitRules: number\n      periods: readonly number[]\n      customRules: number\n      managedRulesets: boolean\n      cacheRules: number\n    }\n  >\n> = {\n  free: {\n    rateLimitRules: 1,\n    periods: [10],\n    customRules: 5,\n    managedRulesets: false,\n    cacheRules: 10,\n  },\n  pro: {\n    rateLimitRules: 2,\n    periods: [10, 60],\n    customRules: 20,\n    managedRulesets: true,\n    cacheRules: 25,\n  },\n  business: {\n    rateLimitRules: 5,\n    periods: [10, 60, 120, 300, 600],\n    customRules: 100,\n    managedRulesets: true,\n    cacheRules: 50,\n  },\n  enterprise: {\n    rateLimitRules: 100,\n    periods: [10, 60, 120, 300, 600, 3600],\n    customRules: 1000,\n    managedRulesets: true,\n    cacheRules: 300,\n  },\n}\n\nconst isPlan = (value: unknown): value is Plan =>\n  typeof value === 'string' && Object.hasOwn(PLAN_LIMITS, value)\n\nexport interface PhasePlan {\n  phase: Phase\n  add: Rule[]\n  /** `position` is set when the rule is out of place: its index on the zone, and the one `apply` writes it at. */\n  change: Array<{ ref: string; from: Rule; to: Rule; position?: { from: number; to: number } }>\n  remove: Rule[]\n}\n\n/** What `apply` would change (from `plan`) or changed (from `apply`), phase by phase. */\nexport interface SecurityPlan {\n  phases: PhasePlan[]\n}\n\nexport const isEmptyPlan = (plan: SecurityPlan): boolean =>\n  plan.phases.every((p) => p.add.length + p.change.length + p.remove.length === 0)\n\nexport interface CloudflareSecurityAdapter extends SecurityAdapter {\n  drift(config: SecurityConfigLike): Promise<DriftReport>\n  inspect(): Promise<SecurityState>\n  plan(config: SecurityConfigLike): Promise<SecurityPlan>\n  /** Writes each phase whose Nymbal rules differ, one by one; it rejects at the first refused write. */\n  apply(config: SecurityConfigLike): Promise<SecurityPlan>\n}\n\n/** `desired` holds in `live`: every field `desired` sets, at any depth, has the same value there. */\nfunction holds(desired: unknown, live: unknown): boolean {\n  if (Array.isArray(desired)) {\n    return (\n      Array.isArray(live) &&\n      live.length === desired.length &&\n      desired.every((d, i) => holds(d, live[i]))\n    )\n  }\n  if (typeof desired === 'object' && desired !== null) {\n    if (typeof live !== 'object' || live === null) return false\n    return Object.entries(desired).every(([k, v]) => holds(v, (live as Record<string, unknown>)[k]))\n  }\n  return desired === live\n}\n\n/** The fields of `desired` that `live` does not hold. */\nconst changedFields = (desired: Rule, live: Rule): string[] =>\n  Object.keys(desired).filter((field) => !holds(desired[field], live[field]))\n\nfunction byRef(rules: readonly Rule[]): Map<string, Rule> {\n  return new Map(rules.filter(isNymbalRule).map((r) => [r.ref as string, r]))\n}\n\n/** A rule's identity within a phase: its ref when Nymbal's, its id when the owner's. */\nconst keyOf = (rule: Rule): string =>\n  isNymbalRule(rule) ? `ref:${String(rule.ref)}` : `id:${String(rule.id)}`\n\n/**\n * The Nymbal rules a dashboard reorder put out of place, by ref, with their index on the zone and the one `apply`\n * writes them at. The kept rules are in place when they are one run, in the config's order; owner rules after that run\n * are the dashboard's default place for a new rule, so they move nothing. Indexes count only the rules both sides keep.\n */\nfunction misplaced(\n  live: readonly Rule[],\n  desired: readonly Rule[],\n): Map<string, { from: number; to: number }> {\n  const wanted = byRef(desired)\n  const kept = live.filter((r) => !isNymbalRule(r) || wanted.has(r.ref as string))\n  const ours = kept.flatMap((r, i) => (isNymbalRule(r) ? [i] : []))\n  const liveRefs = ours.map((i) => kept[i]!.ref as string)\n  const present = new Set(liveRefs)\n  const inOrder = desired.filter((r) => present.has(r.ref as string)).map((r) => r.ref as string)\n  const oneRun = ours.length === 0 || ours[ours.length - 1]! - ours[0]! === ours.length - 1\n  const out = new Map<string, { from: number; to: number }>()\n  if (oneRun && liveRefs.every((ref, i) => ref === inOrder[i])) return out\n  const written = nextRules(kept, desired).filter(\n    (r) => !isNymbalRule(r) || present.has(r.ref as string),\n  )\n  const target = new Map(written.map((r, i) => [keyOf(r), i]))\n  for (const i of ours) {\n    const ref = kept[i]!.ref as string\n    const to = target.get(keyOf(kept[i]!))!\n    if (to !== i) out.set(ref, { from: i, to })\n  }\n  return out\n}\n\nfunction diffPhase(phase: Phase, live: readonly Rule[], desired: readonly Rule[]): PhasePlan {\n  const current = byRef(live)\n  const wanted = byRef(desired)\n  const moved = misplaced(live, desired)\n  const plan: PhasePlan = { phase, add: [], change: [], remove: [] }\n  for (const [ref, to] of wanted) {\n    const from = current.get(ref)\n    const position = moved.get(ref)\n    if (from === undefined) plan.add.push(to)\n    else if (changedFields(to, from).length > 0 || position !== undefined) {\n      plan.change.push({ ref, from, to, ...(position !== undefined && { position }) })\n    }\n  }\n  for (const [ref, rule] of current) if (!wanted.has(ref)) plan.remove.push(rule)\n  return plan\n}\n\n/** The rules to PUT: the zone's own, in their order, then Nymbal's, each keeping the id Cloudflare gave it. */\nfunction nextRules(live: readonly Rule[], desired: readonly Rule[]): Rule[] {\n  const ids = new Map(live.filter(isNymbalRule).map((r) => [r.ref as string, r.id] as const))\n  const own = live\n    .filter((r) => !isNymbalRule(r))\n    .map(({ version: _version, last_updated: _updated, ...rule }) => rule as Rule)\n  const ours = desired.map((rule) => {\n    const id = ids.get(rule.ref as string)\n    return id === undefined ? rule : { ...rule, id }\n  })\n  return [...own, ...ours]\n}\n\nexport function createCloudflareSecurityAdapter(deps: {\n  connection: CloudflareConnection\n  logger: Logger\n}): CloudflareSecurityAdapter {\n  const { connection, logger } = deps\n  const client: CloudflareClient = createClient(connection)\n  let lastValidatedAt = ''\n\n  const livePhases = async (): Promise<Record<Phase, Rule[]>> => {\n    const read = await Promise.all(PHASES.map((phase) => client.entrypoint(phase)))\n    return Object.fromEntries(PHASES.map((phase, i) => [phase, read[i] ?? []])) as Record<\n      Phase,\n      Rule[]\n    >\n  }\n\n  const desiredOf = (config: SecurityConfigLike) => desiredRules(config as EdgeRulesConfig)\n\n  /** Errors a config has whatever the zone: keys, windows and geo codes. */\n  function configErrors(config: EdgeRulesConfig): ValidationResult['errors'] {\n    const errors: ValidationResult['errors'] = []\n    for (const [key, entry] of Object.entries(config.rateLimit ?? {})) {\n      if (!isEdgePath(key)) {\n        errors.push({\n          code: 'cloudflare.path',\n          path: `rateLimit.${key}`,\n          message: `rate limit key '${key}' is not a path (it must start with /), so it has no edge rule`,\n        })\n      }\n      if (WINDOW_PERIODS[entry.window] === undefined) {\n        errors.push({\n          code: 'cloudflare.period',\n          path: `rateLimit.${key}.window`,\n          message: `window '${entry.window}' has no Cloudflare period; use one of ${Object.keys(WINDOW_PERIODS).join(', ')}`,\n        })\n      }\n    }\n    for (const code of config.geo?.block ?? []) {\n      if (!/^[A-Z]{2}$/.test(code)) {\n        errors.push({\n          code: 'cloudflare.geo',\n          path: 'geo.block',\n          message: `'${code}' is not an ISO 3166 alpha-2 country code (two capital letters)`,\n        })\n      }\n    }\n    return errors\n  }\n\n  /** Errors the zone's plan and its own rules give the config. */\n  function planErrors(\n    plan: Plan,\n    config: EdgeRulesConfig,\n    live: Record<Phase, Rule[]>,\n  ): ValidationResult['errors'] {\n    const limits = PLAN_LIMITS[plan]\n    const errors: ValidationResult['errors'] = []\n    for (const [key, entry] of Object.entries(config.rateLimit ?? {})) {\n      const period = WINDOW_PERIODS[entry.window]\n      if (period !== undefined && !limits.periods.includes(period)) {\n        errors.push({\n          code: 'cloudflare.period',\n          path: `rateLimit.${key}.window`,\n          message: `window '${entry.window}' is not allowed on the ${plan} plan; it allows periods of ${limits.periods.join(', ')} s`,\n        })\n      }\n      if (entry.action === 'throttle' && plan !== 'enterprise') {\n        errors.push({\n          code: 'cloudflare.action',\n          path: `rateLimit.${key}.action`,\n          message: `throttle needs the enterprise plan; the zone is on the ${plan} plan (use block or challenge)`,\n        })\n      }\n    }\n    const desired = desiredRules(config)\n    const counted: Array<[Phase, number, string]> = [\n      ['http_ratelimit', limits.rateLimitRules, 'rate limiting rules'],\n      ['http_request_firewall_custom', limits.customRules, 'custom rules'],\n      ['http_request_cache_settings', limits.cacheRules, 'cache rules'],\n    ]\n    for (const [phase, limit, what] of counted) {\n      const own = live[phase].filter((r) => !isNymbalRule(r)).length\n      const total = own + desired[phase].length\n      if (total > limit) {\n        errors.push({\n          code: 'cloudflare.plan-limit',\n          path: phase,\n          message: `${phase} would hold ${total} ${what} (${own} of the zone's own, ${desired[phase].length} of Nymbal's); the ${plan} plan allows ${limit}`,\n        })\n      }\n    }\n    if (!limits.managedRulesets && desired.http_request_firewall_managed.length > 0) {\n      errors.push({\n        code: 'cloudflare.plan-limit',\n        path: 'managedRulesets',\n        message: `managed rulesets need the pro plan or above; the zone is on the ${plan} plan`,\n      })\n    }\n    return errors\n  }\n\n  async function plan(config: SecurityConfigLike): Promise<SecurityPlan> {\n    const live = await livePhases()\n    const desired = desiredOf(config)\n    return { phases: PHASES.map((phase) => diffPhase(phase, live[phase], desired[phase])) }\n  }\n\n  return {\n    capabilities: () => ['headers', 'edge-rules'],\n    producesEvents: [],\n    consumesEvents: [],\n\n    // Boot makes no request: the zone changes only by `nymbal security:apply`.\n    initialize: () => Promise.resolve(),\n\n    healthCheck() {\n      return boundedHealthCheck(async () => {\n        const zone = await client.zone()\n        const plan = zone.plan?.legacy_id ?? 'unknown'\n        return { status: 'healthy', detail: `zone ${zone.name ?? zone.id} on the ${plan} plan` }\n      })\n    },\n\n    async applyMiddleware(app: HttpAdapter, config: SecurityConfigLike): Promise<void> {\n      app.setDefaultHeaders(buildSecurityHeaders(config))\n      logger.debug({}, 'security headers attached')\n    },\n\n    async validate(config: SecurityConfigLike): Promise<ValidationResult> {\n      const edge = config as EdgeRulesConfig\n      if (!hasCredentials(connection)) {\n        const missing = [\n          ...(connection.zoneId ? [] : ['zoneId']),\n          ...(connection.apiToken ? [] : ['apiToken']),\n        ]\n        return {\n          valid: false,\n          errors: [\n            {\n              code: 'cloudflare.credentials',\n              path: 'cloudflare',\n              message: `security.cloudflare has no ${missing.join(' or ')} (CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_TOKEN)`,\n            },\n          ],\n        }\n      }\n      const errors = configErrors(edge)\n      try {\n        const zone = await client.zone()\n        const plan = zone.plan?.legacy_id\n        if (!isPlan(plan)) {\n          errors.push({\n            code: 'cloudflare.plan-limit',\n            message: `the zone's plan '${String(plan)}' is not one Nymbal knows the limits of (free, pro, business, enterprise)`,\n          })\n        } else {\n          errors.push(...planErrors(plan, edge, await livePhases()))\n        }\n      } catch (error) {\n        if (!(error instanceof CloudflareCredentialsError)) throw error\n        errors.push({ code: 'cloudflare.credentials', message: error.message })\n      }\n      lastValidatedAt = new Date().toISOString()\n      return { valid: errors.length === 0, errors }\n    },\n\n    plan,\n\n    async apply(config: SecurityConfigLike): Promise<SecurityPlan> {\n      const desired = desiredOf(config)\n      const written: PhasePlan[] = []\n      for (const phase of PHASES) {\n        const live = await client.entrypoint(phase)\n        const change = diffPhase(phase, live ?? [], desired[phase])\n        if (change.add.length + change.change.length + change.remove.length === 0) continue\n        try {\n          await client.putEntrypoint(phase, nextRules(live ?? [], desired[phase]))\n        } catch (error) {\n          const done = written.map((p) => p.phase)\n          throw new AdapterError(\n            'cloudflare_apply',\n            `writing ${phase} failed after ${done.length === 0 ? 'no phase' : done.join(', ')} was written: ${errorText(error)}`,\n            { cause: error, context: { failed: phase, written: done } },\n          )\n        }\n        logger.info(\n          {\n            phase,\n            added: change.add.length,\n            changed: change.change.length,\n            removed: change.remove.length,\n          },\n          `wrote ${phase}`,\n        )\n        written.push(change)\n      }\n      return { phases: written }\n    },\n\n    async drift(config: SecurityConfigLike): Promise<DriftReport> {\n      const live = await livePhases()\n      const desired = desiredOf(config)\n      const differences: DriftReport['differences'] = []\n      for (const phase of PHASES) {\n        const { add, change, remove } = diffPhase(phase, live[phase], desired[phase])\n        for (const rule of add) {\n          differences.push({ path: `${phase}/${rule.ref}`, configured: rule, actual: undefined })\n        }\n        for (const { ref, from, to, position } of change) {\n          for (const field of changedFields(to, from)) {\n            differences.push({\n              path: `${phase}/${ref}/${field}`,\n              configured: to[field],\n              actual: from[field],\n            })\n          }\n          if (position !== undefined) {\n            differences.push({\n              path: `${phase}/${ref}/position`,\n              configured: position.to,\n              actual: position.from,\n            })\n          }\n        }\n        for (const rule of remove) {\n          differences.push({ path: `${phase}/${rule.ref}`, configured: undefined, actual: rule })\n        }\n      }\n      return { drift: differences.length > 0, differences }\n    },\n\n    async inspect(): Promise<SecurityState> {\n      const live = await livePhases()\n      return {\n        rulesApplied: PHASES.flatMap((phase) =>\n          live[phase].filter(isNymbalRule).map((r) => r.ref as string),\n        ),\n        lastValidatedAt,\n      }\n    },\n  }\n}\n","import { AdapterError, errorText } from '@nymbalhq/types'\nimport type { Phase, Rule } from './rules.js'\n\nexport const DEFAULT_API_BASE = 'https://api.cloudflare.com/client/v4'\nexport const REQUEST_TIMEOUT_MS = 5000\n\n/** The `security.cloudflare` block: the adapter's `ctx.config`. */\nexport interface CloudflareConnection {\n  zoneId?: string\n  apiToken?: string\n  apiBase?: string\n}\n\nexport const CREDENTIALS_HINT =\n  'check security.cloudflare.zoneId and apiToken (CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_TOKEN): the token needs ' +\n  'Zone › Zone › Read, Zone › Zone WAF › Edit and Zone › Cache Rules › Edit on the zone'\n\n/** The token or zone was refused (401 or 403), or the config has none. */\nexport class CloudflareCredentialsError extends AdapterError {\n  constructor(detail: string, context: Record<string, unknown> = {}) {\n    super('cloudflare_credentials', `Cloudflare: ${detail}; ${CREDENTIALS_HINT}`, { context })\n  }\n}\n\ninterface Envelope<T> {\n  success?: boolean\n  errors?: Array<{ code?: number; message?: string }>\n  result?: T\n}\n\nexport interface Zone {\n  id: string\n  name?: string\n  plan?: { legacy_id?: string; name?: string }\n}\n\n/** The Cloudflare v4 API as the adapter uses it: the zone, and one phase's entrypoint ruleset. */\nexport interface CloudflareClient {\n  zone(): Promise<Zone>\n  /** The phase's rules, or undefined when the phase was never written (404). */\n  entrypoint(phase: Phase): Promise<Rule[] | undefined>\n  /** Replaces the phase's rules whole, creating the entrypoint when it is absent. */\n  putEntrypoint(phase: Phase, rules: Rule[]): Promise<void>\n}\n\nexport function hasCredentials(\n  connection: CloudflareConnection,\n): connection is Required<Pick<CloudflareConnection, 'zoneId' | 'apiToken'>> &\n  CloudflareConnection {\n  return Boolean(connection.zoneId) && Boolean(connection.apiToken)\n}\n\nfunction apiErrors(body: unknown): string {\n  const errors = (body as Envelope<unknown> | null)?.errors ?? []\n  const messages = errors.map((e) => e.message).filter((m): m is string => typeof m === 'string')\n  return messages.length > 0 ? messages.join('; ') : 'no error message'\n}\n\nexport function createClient(connection: CloudflareConnection): CloudflareClient {\n  const base = (connection.apiBase ?? DEFAULT_API_BASE).replace(/\\/+$/, '')\n  const zonePath = `/zones/${encodeURIComponent(connection.zoneId ?? '')}`\n\n  async function request(\n    method: 'GET' | 'PUT',\n    path: string,\n    body?: unknown,\n  ): Promise<{ status: number; body: unknown }> {\n    if (!hasCredentials(connection)) {\n      throw new CloudflareCredentialsError('no zone ID or API token is configured')\n    }\n    let response: Response\n    let text: string\n    try {\n      response = await fetch(`${base}${path}`, {\n        method,\n        headers: {\n          authorization: `Bearer ${connection.apiToken}`,\n          ...(body !== undefined && { 'content-type': 'application/json' }),\n        },\n        ...(body !== undefined && { body: JSON.stringify(body) }),\n        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),\n      })\n      text = await response.text()\n    } catch (error) {\n      throw new AdapterError(\n        'cloudflare_unreachable',\n        `Cloudflare API at ${base} did not answer ${method} ${path}: ${errorText(error)}`,\n        { cause: error, context: { method, path } },\n      )\n    }\n    let parsed: unknown\n    try {\n      parsed = text === '' ? undefined : (JSON.parse(text) as unknown)\n    } catch {\n      // A proxy's error page is not JSON: a failure still goes by its status, and a success is refused below.\n      parsed = undefined\n    }\n    if (response.status === 401 || response.status === 403) {\n      throw new CloudflareCredentialsError(\n        `${method} ${path} was refused (${response.status}: ${apiErrors(parsed)})`,\n        { status: response.status },\n      )\n    }\n    if (response.ok && (typeof parsed !== 'object' || parsed === null)) {\n      throw new AdapterError(\n        'cloudflare_api',\n        `Cloudflare answered ${method} ${path} with ${response.status} and no JSON body`,\n        { context: { method, path, status: response.status } },\n      )\n    }\n    return { status: response.status, body: parsed }\n  }\n\n  const failed = (method: string, path: string, status: number, body: unknown): AdapterError =>\n    new AdapterError(\n      'cloudflare_api',\n      `Cloudflare answered ${method} ${path} with ${status}: ${apiErrors(body)}`,\n      { context: { method, path, status } },\n    )\n\n  return {\n    async zone() {\n      const { status, body } = await request('GET', zonePath)\n      if (status === 404) {\n        throw new CloudflareCredentialsError(`zone ${connection.zoneId} was not found`, { status })\n      }\n      if (status !== 200) throw failed('GET', zonePath, status, body)\n      return (body as Envelope<Zone>).result as Zone\n    },\n    async entrypoint(phase) {\n      const path = `${zonePath}/rulesets/phases/${phase}/entrypoint`\n      const { status, body } = await request('GET', path)\n      if (status === 404) return undefined\n      if (status !== 200) throw failed('GET', path, status, body)\n      return (body as Envelope<{ rules?: Rule[] }>).result?.rules ?? []\n    },\n    async putEntrypoint(phase, rules) {\n      const path = `${zonePath}/rulesets/phases/${phase}/entrypoint`\n      const { status, body } = await request('PUT', path, { rules })\n      if (status !== 200) throw failed('PUT', path, status, body)\n    },\n  }\n}\n","/** The entrypoint phases Nymbal writes, in the order `apply` writes them. */\nexport const PHASES = [\n  'http_ratelimit',\n  'http_request_firewall_custom',\n  'http_request_firewall_managed',\n  'http_request_cache_settings',\n] as const\nexport type Phase = (typeof PHASES)[number]\n\n/** A ruleset rule as the Cloudflare v4 API reads and writes it. */\nexport interface Rule {\n  id?: string\n  ref?: string\n  description?: string\n  expression: string\n  action: string\n  action_parameters?: Record<string, unknown>\n  ratelimit?: {\n    characteristics: string[]\n    period: number\n    requests_per_period: number\n    mitigation_timeout: number\n  }\n  enabled?: boolean\n  [key: string]: unknown\n}\n\nexport const NYMBAL_REF_PREFIX = 'nymbal:'\n\nexport const isNymbalRule = (rule: { ref?: unknown }): boolean =>\n  typeof rule.ref === 'string' && rule.ref.startsWith(NYMBAL_REF_PREFIX)\n\n/** Each `rateLimit` window Cloudflare has a period for, in seconds. */\nexport const WINDOW_PERIODS: Readonly<Record<string, number>> = {\n  '10s': 10,\n  '1m': 60,\n  '2m': 120,\n  '5m': 300,\n  '10m': 600,\n  '1h': 3600,\n}\n\n/** Cloudflare's own managed rulesets, by the name `managedRulesets` uses. */\nexport const MANAGED_RULESET_IDS = {\n  cloudflare: 'efb7b8c949ac4650a09736fc376e9aee',\n  owasp: '4814384a9e5d4991b9815dcfc25d2f1f',\n} as const\nexport type ManagedRuleset = keyof typeof MANAGED_RULESET_IDS\n\nconst MANAGED_NAMES: Readonly<Record<ManagedRuleset, string>> = {\n  cloudflare: 'Cloudflare Managed Ruleset',\n  owasp: 'Cloudflare OWASP Core Ruleset',\n}\n\nexport interface RateLimitEntry {\n  requests: number\n  window: string\n  action: 'block' | 'challenge' | 'throttle'\n}\n\nexport interface CustomRule {\n  name: string\n  expression: string\n  action: 'block' | 'managed_challenge' | 'js_challenge' | 'log'\n}\n\n/** The parts of the `security` block the edge rules come from; every one may be absent. */\nexport interface EdgeRulesConfig {\n  rateLimit?: Record<string, RateLimitEntry>\n  geo?: { block?: string[] }\n  customRules?: CustomRule[]\n  managedRulesets?: string[]\n}\n\nconst quoted = (text: string): string => `\"${text.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"')}\"`\n\n/**\n * The edge match for an in-process limiter key: exact without `*`, else a wildcard with `**` as `*`. Cloudflare's `*`\n * crosses `/`, so a single `*` matches more at the edge than at the origin (`hasSingleStar`).\n */\nexport function pathExpression(key: string): string {\n  return key.includes('*')\n    ? `http.request.uri.path wildcard ${quoted(key.replace(/\\*+/g, '*'))}`\n    : `http.request.uri.path eq ${quoted(key)}`\n}\n\n/** A key with a `*` that is not part of `**`: one segment at the origin, any number at the edge. */\nexport const hasSingleStar = (key: string): boolean => /(^|[^*])\\*([^*]|$)/.test(key)\n\n/** A rate limit key the edge can express: a path. */\nexport const isEdgePath = (key: string): boolean => key.startsWith('/')\n\nfunction rateLimitRule(key: string, entry: RateLimitEntry): Rule | undefined {\n  const period = WINDOW_PERIODS[entry.window]\n  if (!isEdgePath(key) || period === undefined) return undefined\n  const [action, mitigationTimeout] =\n    entry.action === 'challenge'\n      ? ['managed_challenge', 0]\n      : entry.action === 'throttle'\n        ? ['block', 0]\n        : ['block', period]\n  return {\n    ref: `${NYMBAL_REF_PREFIX}ratelimit:${key}`,\n    description: `${NYMBAL_REF_PREFIX} rate limit ${key}`,\n    expression: pathExpression(key),\n    action,\n    ratelimit: {\n      characteristics: ['cf.colo.id', 'ip.src'],\n      period,\n      requests_per_period: entry.requests,\n      mitigation_timeout: mitigationTimeout,\n    },\n    enabled: true,\n  }\n}\n\n/**\n * The fragment routes' HTML is the same for every shopper and carries its own `s-maxage`, so the edge caches it for\n * the origin's TTLs; Cloudflare caches no HTML without a rule.\n */\nconst fragmentCacheRule = (): Rule => ({\n  ref: `${NYMBAL_REF_PREFIX}cache:fragments`,\n  description: `${NYMBAL_REF_PREFIX} cache the fragment routes`,\n  expression: 'starts_with(http.request.uri.path, \"/fragments/\")',\n  action: 'set_cache_settings',\n  action_parameters: {\n    cache: true,\n    edge_ttl: { mode: 'respect_origin' },\n    browser_ttl: { mode: 'respect_origin' },\n  },\n  enabled: true,\n})\n\n/**\n * The rules the config puts on the zone, by phase, every one carrying a `nymbal:` ref. Rate limits follow their keys'\n * sorted order and custom rules their config order, so the same config always gives the same rules. A key that is not\n * a path, or a window with no Cloudflare period, gives no rule: `validate` reports both.\n */\nexport function desiredRules(config: EdgeRulesConfig): Record<Phase, Rule[]> {\n  const rateLimits = Object.entries(config.rateLimit ?? {})\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n    .flatMap(([key, entry]) => rateLimitRule(key, entry) ?? [])\n\n  const custom: Rule[] = []\n  const blocked = config.geo?.block ?? []\n  if (blocked.length > 0) {\n    custom.push({\n      ref: `${NYMBAL_REF_PREFIX}geo:block`,\n      description: `${NYMBAL_REF_PREFIX} geo block ${blocked.join(' ')}`,\n      expression: `ip.src.country in {${blocked.map(quoted).join(' ')}}`,\n      action: 'block',\n      enabled: true,\n    })\n  }\n  for (const rule of config.customRules ?? []) {\n    custom.push({\n      ref: `${NYMBAL_REF_PREFIX}custom:${rule.name}`,\n      description: `${NYMBAL_REF_PREFIX} ${rule.name}`,\n      expression: rule.expression,\n      action: rule.action,\n      enabled: true,\n    })\n  }\n\n  const managed = [...new Set(config.managedRulesets ?? [])]\n    .filter((name): name is ManagedRuleset => Object.hasOwn(MANAGED_RULESET_IDS, name))\n    .map(\n      (name): Rule => ({\n        ref: `${NYMBAL_REF_PREFIX}managed:${name}`,\n        description: `${NYMBAL_REF_PREFIX} ${MANAGED_NAMES[name]}`,\n        expression: 'true',\n        action: 'execute',\n        action_parameters: { id: MANAGED_RULESET_IDS[name] },\n        enabled: true,\n      }),\n    )\n\n  return {\n    http_ratelimit: rateLimits,\n    http_request_firewall_custom: custom,\n    http_request_firewall_managed: managed,\n    http_request_cache_settings: [fragmentCacheRule()],\n  }\n}\n"],"mappings":"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","names":["AdapterError","errorText","plan","AdapterError","errorText"]}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@nymbalhq/security-cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "description": "Cloudflare WAF for Nymbal: the `cloudflare` security adapter, with rules applied by command",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nymbalhq/nymbal.git",
+    "directory": "packages/security-cloudflare"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./recipes/*": "./recipes/*"
+  },
+  "files": [
+    "dist",
+    "recipes"
+  ],
+  "dependencies": {
+    "@nymbalhq/types": "1.2.0"
+  },
+  "devDependencies": {
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "fast-check": "^4.10.2",
+    "tsup": "^9.0.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit --rootDir ../.."
+  }
 }

package/recipes/cloudflare.json

@@ -0,0 +1,35 @@
+{
+  "name": "cloudflare",
+  "summary": "Put the store's rate limits, geo blocks, custom rules and managed rulesets on its Cloudflare zone.",
+  "install": ["@nymbalhq/security-cloudflare"],
+  "set": [
+    { "path": "security.adapter", "value": "cloudflare" },
+    {
+      "path": "security.cloudflare",
+      "value": {
+        "zoneId": { "env": "CLOUDFLARE_ZONE_ID" },
+        "apiToken": { "env": "CLOUDFLARE_API_TOKEN" }
+      }
+    }
+  ],
+  "env": [
+    {
+      "name": "CLOUDFLARE_ZONE_ID",
+      "example": "",
+      "required": true,
+      "comment": "The zone's ID (Cloudflare dashboard, the domain's Overview page, API section)"
+    },
+    {
+      "name": "CLOUDFLARE_API_TOKEN",
+      "example": "",
+      "required": true,
+      "comment": "An API token scoped to that zone only, with Zone › Zone › Read, Zone › Zone WAF › Edit and Zone › Cache Rules › Edit"
+    }
+  ],
+  "next": [
+    "Create the API token in the Cloudflare dashboard (My Profile, API Tokens) with three permissions on this zone only: Zone › Zone › Read, Zone › Zone WAF › Edit and Zone › Cache Rules › Edit.",
+    "Behind Cloudflare every request reaches the API from an edge address: set http.trustProxy: true so the in-process rate limiter keys on the client, not on the edge.",
+    "The zone's plan limits security.rateLimit: the Free plan allows one rate limit with a 10s window, Pro two with 10s or 1m (the scaffold's four fit Business and up). A throttle action needs the Enterprise plan: on Free, Pro or Business change the scaffold's two throttle entries (/api/*, /webhooks/*) to block or challenge. nymbal security:plan names each limit the plan refuses.",
+    "Run nymbal security:plan to see the rules, then nymbal security:apply to put them on the zone; nymbal security:drift reports a dashboard edit."
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.