rcf-lite 0.22.0 → 0.24.0

package/blueprints/edge-cloudflare-rate-limiting/contributions/probes/probe-utils.mjs

@@ -0,0 +1,111 @@
+// Shared helpers for edge-cloudflare-rate-limiting probes.
+//
+// Runtime-dependency posture: three probes read the cf-edge fixture
+// manifest directory in-process (no network); one probe fires an
+// undici burst against a scheduled real-account URL when
+// CI_HAS_CLOUDFLARE_ACCOUNT and CF_RATE_LIMIT_URL are set, and
+// records accountBoundSkipped: true otherwise per spec section 3.5
+// and ruling 6. The drift-audit runner realisation lives in the
+// fixture at src/drift-audit-runner.mjs.
+
+import { mkdir, writeFile, readFile, readdir, rename, stat } from 'node:fs/promises';
+import { dirname, resolve, join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/cf-edge');
+export const MANIFEST_DIR = resolve(FIXTURE_DIR, 'cloudflare/rate-limits');
+export const SCHEMA_PATH = resolve(HERE, '..', 'schemas', 'rate-limit-rule.schema.json');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/edge-cloudflare-rate-limiting');
+
+export const REQUIRED_FIELDS = Object.freeze([
+  'id',
+  'expression',
+  'threshold',
+  'period',
+  'characteristics',
+  'action',
+  'duration',
+]);
+
+export const ACTION_ENUM = Object.freeze(['block', 'challenge', 'log', 'managed_challenge']);
+
+export function aggregate(results) {
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+
+export async function writeReport({ probeName, engine, results, extra }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const report = {
+    slug: 'edge-cloudflare-rate-limiting',
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict: aggregate(results),
+    ...(extra ?? {}),
+  };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2) + '\n', 'utf8');
+  return { report, path };
+}
+
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const { results, extra } = await mainFn();
+    const { report, path } = await writeReport({ probeName, engine, results, extra });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stdout.write(`report written to ${path}\n`);
+    if (report.aggregateVerdict === 'fail') process.exitCode = 1;
+  } catch (err) {
+    const results = [{
+      anchorAcId: 'unknown',
+      verdict: 'fail',
+      detail: `probe threw: ${err && err.message ? err.message : String(err)}`,
+    }];
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${err && err.stack ? err.stack : String(err)}\n`);
+    process.stderr.write(`report written to ${path}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export async function readManifestFiles(dir = MANIFEST_DIR) {
+  const missing = process.env.SIMULATE_MANIFEST_MISSING === 'true';
+  let entries;
+  try {
+    entries = (await readdir(dir)).filter((f) => f.endsWith('.json')).sort();
+  } catch (err) {
+    return { present: false, missing: [], entries: [], error: err.message };
+  }
+  const hidden = new Set();
+  if (missing && entries.length > 0) {
+    hidden.add(entries[0]);
+  }
+  const files = [];
+  for (const name of entries) {
+    if (hidden.has(name)) continue;
+    const p = join(dir, name);
+    const text = await readFile(p, 'utf8');
+    files.push({ name, path: p, text });
+  }
+  return { present: entries.length > 0, entries, files, hiddenBySimulate: [...hidden] };
+}
+
+export function scanForPlaintextSecrets(text) {
+  const hits = [];
+  if (/[Bb]earer\s+[A-Za-z0-9._-]{20,}/.test(text)) hits.push('bearer-token-like');
+  if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(text)) hits.push('pem-private-key');
+  if (/"?CF_API_TOKEN"?\s*:\s*"[^"]{5,}"/.test(text)) hits.push('inline-cf-api-token');
+  return hits;
+}
+
+export async function loadSchema() {
+  const raw = await readFile(SCHEMA_PATH, 'utf8');
+  return JSON.parse(raw);
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/probes/real-account-burst-and-429.mjs

@@ -0,0 +1,104 @@
+// Probe: real-account burst-and-429 against a scheduled URL.
+//
+// anchorAcId: AC-36103-1. accountBound: true.
+//
+// When CI_HAS_CLOUDFLARE_ACCOUNT=true AND CF_RATE_LIMIT_URL is set,
+// the probe fires an in-process burst against the scheduled URL and
+// asserts:
+//   - the (N+1)th and subsequent requests within the elicited
+//     duration return HTTP 429.
+//   - the 429 responses carry a Retry-After header consistent with
+//     the elicited duration.
+//   - the 429 responses carry a Cf-Ray header naming the CF edge.
+//
+// Without either env var the probe records accountBoundSkipped: true
+// and aggregates to pass per spec section 3.5 and ruling 6.
+// N (the elicited threshold) is read from CF_RATE_LIMIT_THRESHOLD
+// (default 60); the burst count is N+3.
+
+export const anchorAcId = 'AC-36103-1';
+export const accountBound = true;
+
+const BURST_TIMEOUT_MS = 10000;
+
+async function fireOne(url) {
+  const ctrl = new AbortController();
+  const to = setTimeout(() => ctrl.abort(), BURST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { method: 'GET', redirect: 'manual', signal: ctrl.signal });
+    return { status: res.status, retryAfter: res.headers.get('retry-after'), cfRay: res.headers.get('cf-ray') };
+  } finally {
+    clearTimeout(to);
+  }
+}
+
+export default async function runProbe() {
+  const has = process.env.CI_HAS_CLOUDFLARE_ACCOUNT === 'true';
+  const url = process.env.CF_RATE_LIMIT_URL || '';
+  if (!has || !url) {
+    return {
+      results: [{
+        anchorAcId: 'AC-36103-1',
+        verdict: 'pass',
+        accountBoundSkipped: true,
+        detail: `accountBoundSkipped: CI_HAS_CLOUDFLARE_ACCOUNT=${has} CF_RATE_LIMIT_URL=${url ? 'set' : 'unset'}; per spec section 3.5 and ruling 6 pass-with-skip.`,
+      }],
+      extra: { accountBoundSkipped: true },
+    };
+  }
+  const threshold = Number.parseInt(process.env.CF_RATE_LIMIT_THRESHOLD || '60', 10);
+  const burstCount = threshold + 3;
+  const results429 = [];
+  const responses = [];
+  try {
+    for (let i = 0; i < burstCount; i += 1) {
+      const r = await fireOne(url);
+      responses.push(r);
+      if (r.status === 429) results429.push(r);
+    }
+  } catch (err) {
+    return {
+      results: [{
+        anchorAcId: 'AC-36103-1',
+        verdict: 'fail',
+        detail: `real-account burst threw before completion: ${err && err.message ? err.message : String(err)}`,
+      }],
+      extra: { accountBound: true, responsesFired: responses.length },
+    };
+  }
+  const results = [];
+  if (results429.length < 2) {
+    results.push({
+      anchorAcId: 'AC-36103-1',
+      verdict: 'fail',
+      detail: `burst of ${burstCount} produced ${results429.length} 429 response(s); expected at least the ${burstCount - threshold} requests above the elicited threshold to return 429.`,
+    });
+  }
+  const missingRetryAfter = results429.filter((r) => !r.retryAfter);
+  if (missingRetryAfter.length > 0) {
+    results.push({
+      anchorAcId: 'AC-36103-1',
+      verdict: 'fail',
+      detail: `${missingRetryAfter.length} of the 429 response(s) missing a Retry-After header; the Cloudflare WAF rate-limiting rules documented shape names Retry-After as the value the client honours.`,
+    });
+  }
+  const missingCfRay = results429.filter((r) => !r.cfRay);
+  if (missingCfRay.length > 0) {
+    results.push({
+      anchorAcId: 'AC-36103-1',
+      verdict: 'fail',
+      detail: `${missingCfRay.length} of the 429 response(s) missing a Cf-Ray header; the header identifies the CF edge that served the refusal.`,
+    });
+  }
+  if (results.length === 0) {
+    results.push({
+      anchorAcId: 'AC-36103-1',
+      verdict: 'pass',
+      detail: `burst of ${burstCount} produced ${results429.length} 429 response(s), every 429 carries Retry-After and Cf-Ray; over-threshold behaviour confirmed against the scheduled URL.`,
+    });
+  }
+  return {
+    results,
+    extra: { accountBound: true, responsesFired: responses.length, count429: results429.length, threshold },
+  };
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/probes/run-event-secrecy.mjs

@@ -0,0 +1,5 @@
+import runProbe from './event-secrecy.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'event-sink-accumulation', image: 'cf-edge fixture drift-audit runner driven with synthetic manifest and fake fetch (in-process)', healthy: true };
+runShim('event-secrecy', engine, runProbe);

package/blueprints/edge-cloudflare-rate-limiting/contributions/probes/run-manifest-presence.mjs

@@ -0,0 +1,5 @@
+import runProbe from './manifest-presence.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'source-scan', image: 'cf-edge fixture manifest directory (in-process JSON read)', healthy: true };
+runShim('manifest-presence', engine, runProbe);

package/blueprints/edge-cloudflare-rate-limiting/contributions/probes/run-manifest-schema-validate.mjs

@@ -0,0 +1,5 @@
+import runProbe from './manifest-schema-validate.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'source-scan', image: 'cf-edge fixture manifest directory validated against draft-07 JSON Schema (in-process)', healthy: true };
+runShim('manifest-schema-validate', engine, runProbe);

package/blueprints/edge-cloudflare-rate-limiting/contributions/probes/run-real-account-burst-and-429.mjs

@@ -0,0 +1,5 @@
+import runProbe from './real-account-burst-and-429.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'real-account', image: 'undici burst against scheduled Cloudflare-fronted URL', healthy: true };
+runShim('real-account-burst-and-429', engine, runProbe);

package/blueprints/edge-cloudflare-rate-limiting/contributions/requirements/edge-cloudflare-rate-limiting-req-001.json

@@ -0,0 +1,17 @@
+{
+  "reqId": "edge-cloudflare-rate-limiting-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The rate-limit rule set is committed to the applying project as a local manifest under cloudflare/rate-limits/, one JSON file per rule",
+  "description": "The applying project holds its rate-limit rule set as a set of JSON documents under the elicited rate-limit-rules-dir (default cloudflare/rate-limits/), one file per rule per ADR-3703. Every manifest file declares the seven documented fields the Cloudflare WAF rate-limiting rules contract names per https://developers.cloudflare.com/waf/rate-limiting-rules/: id (a stable operator-facing string), expression (the WAF rules-language expression string), threshold (positive integer), period (seconds), characteristics (non-empty array of stable characteristic strings), action (block or challenge or log or managed_challenge), duration (seconds, the length of the block window). No rule references a secret in plaintext; the zone id is elicited and stored via the applied secretsManagement companion. The manifest is the source of truth an operator applies via the wrangler or dashboard flow named in the guide; no committed script writes the rules to the live zone.",
+  "category": "functional",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (cloudflare-round-6-spec-2026-09-06.md section 5.6). Ships as v1.0.0 of edge-cloudflare-rate-limiting.",
+  "tags": [
+    "blueprint:edge-cloudflare-rate-limiting"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/requirements/edge-cloudflare-rate-limiting-req-002.json

@@ -0,0 +1,17 @@
+{
+  "reqId": "edge-cloudflare-rate-limiting-REQ-002",
+  "prdId": "PRD-001",
+  "title": "The operator-facing management surface is a documented wrangler or Cloudflare-dashboard flow that applies the local manifest to the live zone",
+  "description": "The blueprint ships no committed script that writes rules to the live Cloudflare zone. The applying project's operator applies the manifest to the elicited zone through one of two documented flows per TAC-3702 and the guide: a wrangler-based flow (the guide names the exact wrangler subcommands the operator runs; commits an audit trail through the wrangler history) or a Cloudflare-dashboard flow (the guide walks the dashboard screens the operator clicks per https://developers.cloudflare.com/waf/rate-limiting-rules/). The elicited rate-limit-management-surface value records the flow the operator chose; the guide's copy-paste walkthrough covers both. The intent is a management surface an operator can hand-run at a known cadence and reproduce from the manifest without inventing a bespoke deploy tool.",
+  "category": "operational",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (cloudflare-round-6-spec-2026-09-06.md section 5.6). Ships as v1.0.0 of edge-cloudflare-rate-limiting.",
+  "tags": [
+    "blueprint:edge-cloudflare-rate-limiting"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/requirements/edge-cloudflare-rate-limiting-req-003.json

@@ -0,0 +1,17 @@
+{
+  "reqId": "edge-cloudflare-rate-limiting-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Over-threshold behaviour: the (N+1)th and subsequent requests within the elicited duration return 429 with Retry-After and Cf-Ray, and the origin never sees them",
+  "description": "Given a rule that permits N requests per period on a characteristic set, when a client sends the (N+1)th request within that period, Cloudflare's zone-level rate limiter refuses the request at the edge for the elicited duration. The refusal response is HTTP 429 with a Retry-After header naming a value consistent with the elicited duration and a Cf-Ray header identifying the CF edge that served the refusal per the Cloudflare WAF rate-limiting rules documented shape at https://developers.cloudflare.com/waf/rate-limiting-rules/. The origin Worker never sees the refused requests. This is the runtime observable AC-rateLimiting-overThresholdBlocks binds; the runtime verification is the real-account burst probe per REQ-004's account-bound category, and per ruling 6 the local CI records accountBound: skipped without CI_HAS_CLOUDFLARE_ACCOUNT.",
+  "category": "functional",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (cloudflare-round-6-spec-2026-09-06.md section 5.6). Ships as v1.0.0 of edge-cloudflare-rate-limiting.",
+  "tags": [
+    "blueprint:edge-cloudflare-rate-limiting"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/requirements/edge-cloudflare-rate-limiting-req-004.json

@@ -0,0 +1,17 @@
+{
+  "reqId": "edge-cloudflare-rate-limiting-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Drift audit: an opt-in scheduled runner reads live zone rules via the Cloudflare API and diffs against the local manifest, reporting mismatches metadata-only",
+  "description": "The blueprint ships a scheduled drift-audit runner (TAC-3703) the applying project can wire behind the elicited rate-limit-drift-audit-cadence per ADR-3704. When enabled (daily or hourly), the runner fetches the live rate-limiting rules on the elicited zone via the Cloudflare API, diffs the returned rule set against the local manifest field-by-field, and constructs one drift-audit record per mismatched rule. Each record is written through the applied logger's audit sink with the metadata-only shape {ruleId, clientIpHash, outcome, timestamp} plus the diff fields; a record never carries a full client IP, a request body or a user agent per REQ-005's event-secrecy discipline. The runner's report artefact writes to the standard blueprint-report location under .rcf/reports/blueprints/edge-cloudflare-rate-limiting/. When the elicited cadence is off, the runner is not wired.",
+  "category": "operational",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (cloudflare-round-6-spec-2026-09-06.md section 5.6). Ships as v1.0.0 of edge-cloudflare-rate-limiting.",
+  "tags": [
+    "blueprint:edge-cloudflare-rate-limiting"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/requirements/edge-cloudflare-rate-limiting-req-005.json

@@ -0,0 +1,17 @@
+{
+  "reqId": "edge-cloudflare-rate-limiting-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Composition with security-auth-magic-link: the zone-level rate rule layers over the per-email application rule",
+  "description": "When both edge-cloudflare-rate-limiting and security-auth-magic-link are applied on the same project, the composition follows ADR-3702: the zone-level rate rule sits at the CF edge and refuses the (N+1)th request for the elicited duration before it reaches the origin Worker; the per-email application rate limiter that security-auth-magic-link ships continues to run on requests that pass the edge gate, applying per-email per-minute limits at the mint-surface. Zone rule layers OVER the application rule; the two operate on different characteristic sets (IP-per-URL at the zone, email at the application) and never overlap on the same characteristic. The guide names the composition explicitly with a copy-paste example. Applying both blueprints without the ADR-3702 layering understanding would leave two rate rules operating on the same characteristic and shadowing each other; ADR-3702 states the layering explicitly and the applied recorder records both blueprints so the operator sees the two-rule shape at apply time.",
+  "category": "functional",
+  "domain": "edge",
+  "priority": "should",
+  "rationale": "Ratified in the Cloudflare round 6 spec (cloudflare-round-6-spec-2026-09-06.md section 5.6). Ships as v1.0.0 of edge-cloudflare-rate-limiting.",
+  "tags": [
+    "blueprint:edge-cloudflare-rate-limiting"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/schemas/rate-limit-rule.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://stravica.ai/rcf-lite/schemas/rate-limit-rule.schema.json",
+  "title": "Cloudflare rate-limit rule manifest file",
+  "description": "One rule per file under the elicited rate-limit-rules-dir. Fields track the Cloudflare WAF rate-limiting rules documented shape at https://developers.cloudflare.com/waf/rate-limiting-rules/.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "expression",
+    "threshold",
+    "period",
+    "characteristics",
+    "action",
+    "duration"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Operator-facing stable rule id (kebab-case; used in drift-audit records as ruleId)."
+    },
+    "expression": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Cloudflare WAF rules-language expression string; scopes the rule to a request set."
+    },
+    "threshold": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Requests permitted per period on the characteristic set."
+    },
+    "period": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Window in seconds the threshold applies over."
+    },
+    "characteristics": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Non-empty list of characteristic strings the rule keys on (e.g. cf.colo.id, ip.src, http.host + http.request.uri.path)."
+    },
+    "action": {
+      "type": "string",
+      "enum": [
+        "block",
+        "challenge",
+        "log",
+        "managed_challenge"
+      ],
+      "description": "Cloudflare-documented action verb the rule applies over-threshold."
+    },
+    "duration": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Block window in seconds the (N+1)th and subsequent requests are refused for."
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional operator-facing description of the rule intent."
+    }
+  }
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/tacs/tac-3701-edge-cloudflare-rate-limiting-manifest-schema.json

@@ -0,0 +1,31 @@
+{
+  "tacId": "TAC-3701-edge-cloudflare-rate-limiting-manifest-schema",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Rate-limit rule manifest schema and manifest layout",
+  "purpose": "The shipped JSON Schema (draft-07) at blueprints/edge-cloudflare-rate-limiting/contributions/schemas/rate-limit-rule.schema.json is the single source of truth for the shape of one manifest file under the elicited rate-limit-rules-dir. The schema names the seven Cloudflare WAF rate-limiting rules fields per https://developers.cloudflare.com/waf/rate-limiting-rules/ (id, expression, threshold, period, characteristics, action, duration), their types (string, string, positive integer, positive integer, non-empty string array, enum of block/challenge/log/managed_challenge, positive integer), and the additionalProperties: false stance. The manifest-schema-validate probe reads every file in the fixture manifest directory and validates against this schema; the manifest-presence probe asserts the seven required fields are all present. This TAC anchors AC-36101-1, AC-36106-1 and AC-36108-1.",
+  "responsibilities": [
+    "Ship a JSON Schema (draft-07) at contributions/schemas/rate-limit-rule.schema.json naming the seven required fields, their types and additionalProperties: false (AC-36101-1, AC-36106-1).",
+    "Ship the shape used by the manifest-presence probe to assert every manifest file carries the seven required fields (AC-36101-1).",
+    "Ship the shape used by the manifest-schema-validate probe to refuse a manifest file with a missing threshold under SIMULATE_SCHEMA_INVALID=true (AC-36106-1).",
+    "Ship the layout used by the manifest-presence probe under SIMULATE_MANIFEST_MISSING=true to name the missing file's basename in the detail (AC-36108-1)."
+  ],
+  "internalStructure": "One JSON Schema file (contributions/schemas/rate-limit-rule.schema.json). One shipped example manifest directory in the cf-edge fixture with two files (cloudflare/rate-limits/example.json, cloudflare/rate-limits/api-writes.json). Two induced-failure switches in the fixture: SIMULATE_MANIFEST_MISSING=true moves one manifest file to a scratch location so manifest-presence fails; SIMULATE_SCHEMA_INVALID=true writes a manifest file with a missing threshold so manifest-schema-validate fails. Both switches restore before commit; the anatomy test verifies the negative path.",
+  "interfaces": [
+    {
+      "name": "rate-limit-rule.schema.json",
+      "kind": "schema",
+      "summary": "JSON Schema (draft-07) for one rate-limit rule manifest file."
+    },
+    {
+      "name": "cloudflare/rate-limits/",
+      "kind": "layout",
+      "summary": "Elicited manifest directory, one JSON file per rule."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/tacs/tac-3702-edge-cloudflare-rate-limiting-management-surface-doc.json

@@ -0,0 +1,25 @@
+{
+  "tacId": "TAC-3702-edge-cloudflare-rate-limiting-management-surface-doc",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Operator-facing management surface documentation (wrangler and Cloudflare dashboard flows)",
+  "purpose": "The shipped guide at blueprints/edge-cloudflare-rate-limiting/guide/edge-cloudflare-rate-limiting.md documents both a wrangler command flow and a Cloudflare dashboard flow for applying one rule from a manifest file to the elicited zone. The guide is the sole management-surface artefact the blueprint ships; no committed script writes rules to the live zone. The elicited rate-limit-management-surface value records the flow the operator chose. The guide also names the composition with security-auth-magic-link per ADR-3702 and shows a copy-paste example. This TAC anchors AC-36102-1 and AC-36105-1.",
+  "responsibilities": [
+    "Ship a guide with a wrangler command flow and a Cloudflare dashboard flow, both walking through the apply of one rule from a manifest file (AC-36102-1).",
+    "Reference https://developers.cloudflare.com/waf/rate-limiting-rules/ as the vendor doc for the rule shape (AC-36102-1).",
+    "Ship a Composition with security-auth-magic-link section naming ADR-3702 explicitly, stating the zone rule characteristic (IP-per-URL) and the application rule characteristic (per-email per-minute) with a copy-paste example (AC-36105-1)."
+  ],
+  "internalStructure": "One guide file (guide/edge-cloudflare-rate-limiting.md) with three named sections: Manifest, Management surface (wrangler and dashboard subsections) and Composition with security-auth-magic-link. Every section links back to the corresponding REQ and ADR.",
+  "interfaces": [
+    {
+      "name": "guide/edge-cloudflare-rate-limiting.md",
+      "kind": "documentation",
+      "summary": "Operator-facing management surface guide with both wrangler and dashboard flows plus the composition example."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/tacs/tac-3703-edge-cloudflare-rate-limiting-drift-audit-runner.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-3703-edge-cloudflare-rate-limiting-drift-audit-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Drift-audit runner: read live zone rules via the Cloudflare API and diff against the local manifest",
+  "purpose": "The single project-side module realising the scheduled drift-audit runner. It fetches the live rate-limiting rules on the elicited zone via the Cloudflare API (GET /client/v4/zones/{zone_id}/rulesets), diffs the returned rule set against the local manifest file-by-file, and constructs one drift-audit record per mismatched rule. Records write through the applied logger's audit sink with the metadata-only shape {ruleId, clientIpHash, outcome, timestamp, diff}; no record carries a full IP, a request body or a user agent (event-secrecy discipline per REQ-004 and AC-36107-1). The runner is factory-driven for testability: probes and the anatomy test inject a fake fetch that returns a synthetic live-zone response. This TAC anchors AC-36104-1 and AC-36107-1.",
+  "responsibilities": [
+    "Export createDriftAuditRunner({env, eventSink, fetch, clock, cadence}) returning {runOnce, schedule, stop} matching the drift-audit shape (AC-36104-1).",
+    "Diff every manifest rule against every live rule and construct one drift record per mismatched rule, with the metadata-only shape {ruleId, outcome, timestamp, diff} (AC-36104-1, AC-36107-1).",
+    "Emit exactly one audit event per drift record on the injected sink, Object.frozen at the boundary (AC-36107-1).",
+    "Refuse to run when the elicited cadence is off (AC-36104-1)."
+  ],
+  "internalStructure": "One shipped runner module the blueprint contributes at guide-installation time (the runner code is copy-paste from the guide into the applying project; the shipped fixture at packages/rcf-lite/test/fixtures/cf-edge/src/drift-audit-runner.mjs realises the shape the guide names). The runner constructs one drift record per mismatched rule; the record is Object.frozen at the boundary so a downstream handler cannot enrich it with a leaked field.",
+  "interfaces": [
+    {
+      "name": "createDriftAuditRunner",
+      "kind": "factory",
+      "summary": "Drift-audit runner factory over env, eventSink, fetch, clock and the elicited cadence."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/user-stories/edge-cloudflare-rate-limiting-us-36101.json

@@ -0,0 +1,27 @@
+{
+  "usId": "edge-cloudflare-rate-limiting-US-36101",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-rate-limiting-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Rules manifest present in the applying project as one JSON file per rule under the elicited manifest directory",
+  "asA": "shelf consumer applying the edge-cloudflare-rate-limiting v1.0.0 blueprint on a Workers project using the cf-edge fixture",
+  "iWant": "the elicited rate-limit-rules-dir to contain at least one committed JSON file per rate-limit rule the applying project intends to run, each file matching the elicited rule shape and none referencing a secret in plaintext",
+  "soThat": "the applying project's rate-limit rules are source-controlled and reviewable, and the operator has a stable source of truth to apply to the live zone through the wrangler or dashboard flow",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-36101-1",
+      "description": "The rate-limit manifest directory (default cloudflare/rate-limits/) exists in the applied project and holds at least one JSON file per rule; every file parses as JSON and carries the seven documented Cloudflare WAF rate-limiting rules fields (id, expression, threshold, period, characteristics, action, duration); no file body contains a plaintext Cloudflare API token or the elicited zone id (the zone id is elicited and stored via the applied secretsManagement companion).",
+      "given": "the cf-edge fixture with the two committed manifest files under cloudflare/rate-limits/",
+      "when": "the manifest-presence probe scans the fixture directory",
+      "then": "every manifest file parses, every file carries the seven required fields, and no file references a secret in plaintext",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3701-edge-cloudflare-rate-limiting-manifest-schema"
+  ],
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/user-stories/edge-cloudflare-rate-limiting-us-36102.json

@@ -0,0 +1,27 @@
+{
+  "usId": "edge-cloudflare-rate-limiting-US-36102",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-rate-limiting-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Guide documents the operator-facing management surface with both wrangler and dashboard flows",
+  "asA": "operator on the applying project preparing to push rate-limit rules from the local manifest to the live Cloudflare zone",
+  "iWant": "a documented step-by-step flow that walks me through both a wrangler command sequence and a Cloudflare dashboard sequence for applying each manifest rule",
+  "soThat": "I can pick the flow that suits the project's operating discipline and reproduce the apply from the manifest at any cadence without inventing a bespoke tool",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-36102-1",
+      "description": "The blueprint guide at blueprints/edge-cloudflare-rate-limiting/guide/edge-cloudflare-rate-limiting.md documents an operator-facing management surface with both a wrangler command flow and a Cloudflare dashboard flow; each flow names the exact steps to apply one rule from a manifest file to the elicited zone; the guide references https://developers.cloudflare.com/waf/rate-limiting-rules/ as the vendor doc for the rule shape.",
+      "given": "the shipped guide file in the blueprint tree",
+      "when": "the anatomy test scans the guide for the wrangler headings, the dashboard headings and the vendor URL",
+      "then": "both flow headings are present and the vendor URL appears",
+      "testable": true,
+      "scope": "documentation"
+    }
+  ],
+  "tacIds": [
+    "TAC-3702-edge-cloudflare-rate-limiting-management-surface-doc"
+  ],
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/user-stories/edge-cloudflare-rate-limiting-us-36103.json

@@ -0,0 +1,27 @@
+{
+  "usId": "edge-cloudflare-rate-limiting-US-36103",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-rate-limiting-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Over-threshold burst returns 429 with Retry-After and Cf-Ray on the (N+1)th request within the elicited duration",
+  "asA": "operator running the real-account burst probe against a scheduled HQ-owned URL configured with the manifest rule",
+  "iWant": "the probe to fire an undici burst above the rule threshold and observe the (N+1)th and subsequent requests return HTTP 429 with a Retry-After header consistent with the elicited duration and a Cf-Ray header for the CF edge that served the refusal",
+  "soThat": "the shipped over-threshold behaviour is verified against a real Cloudflare account and, in CI without CI_HAS_CLOUDFLARE_ACCOUNT, the probe records accountBound: skipped per ruling 6",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-36103-1",
+      "description": "When CI_HAS_CLOUDFLARE_ACCOUNT is true and CF_RATE_LIMIT_URL is set to a scheduled HQ-owned URL configured with the manifest rule, the real-account-burst-and-429 probe fires the elicited threshold plus one requests within the rule period and observes the (N+1)th and subsequent requests within the elicited duration return HTTP 429 with a Retry-After header value consistent with the elicited duration and a Cf-Ray header naming the CF edge; when either env var is absent the probe records accountBoundSkipped: true and the aggregate verdict is pass per spec section 3.5 and ruling 6.",
+      "given": "a scheduled HQ-owned URL configured with the manifest rule (or the accountBound: skipped fallback in CI)",
+      "when": "the real-account-burst-and-429 probe fires the burst (or records the skip)",
+      "then": "the probe returns 429 with the two required headers on the over-threshold requests, or records accountBoundSkipped: true and aggregates to pass",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3701-edge-cloudflare-rate-limiting-manifest-schema"
+  ],
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}

package/blueprints/edge-cloudflare-rate-limiting/contributions/user-stories/edge-cloudflare-rate-limiting-us-36104.json

@@ -0,0 +1,27 @@
+{
+  "usId": "edge-cloudflare-rate-limiting-US-36104",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-rate-limiting-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Drift-audit runner reads live zone rules via the Cloudflare API and diffs against the local manifest, constructing metadata-only records",
+  "asA": "operator on the applying project running the scheduled drift-audit runner behind the elicited cadence (daily or hourly)",
+  "iWant": "the runner to fetch the live rule set from the Cloudflare API for the elicited zone and diff every rule against the local manifest, constructing one drift-audit record per mismatched rule with the metadata-only shape and writing a report to .rcf/reports/blueprints/edge-cloudflare-rate-limiting/",
+  "soThat": "manifest drift (a rule changed on the dashboard without a manifest update, or vice versa) is surfaced through the logging companion at the elicited cadence rather than lingering unnoticed",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-36104-1",
+      "description": "Given a synthetic drift scenario (a fixture manifest file that names threshold 10 and a fake live-zone response that reports threshold 20 on the same rule id), the drift-audit runner's diff step constructs one drift record per mismatched rule; the record carries {ruleId, outcome: driftDetected, timestamp, diff: [field: threshold, manifestValue: 10, liveValue: 20]} and NO full IP, NO request body, NO user agent; when the cadence elicit is off the runner is not wired and no report is written.",
+      "given": "the cf-edge fixture with the committed manifest and a synthetic Cloudflare API response with one mismatched rule",
+      "when": "the drift-audit runner's diff step runs against the pair",
+      "then": "one drift record is constructed per mismatched rule with the metadata-only shape and the report writes to .rcf/reports/blueprints/edge-cloudflare-rate-limiting/",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3703-edge-cloudflare-rate-limiting-drift-audit-runner"
+  ],
+  "createdAt": "2026-09-07T22:00:00.000Z",
+  "updatedAt": "2026-09-07T22:00:00.000Z"
+}