rcf-lite 0.23.0 → 0.25.0

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

@@ -0,0 +1,27 @@
+{
+  "usId": "edge-cloudflare-rate-limiting-US-36105",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-rate-limiting-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Composition with security-auth-magic-link: zone rate rule layers over the per-email application rule",
+  "asA": "operator applying both edge-cloudflare-rate-limiting and security-auth-magic-link on the same project",
+  "iWant": "the guide to name the ADR-3702 layering explicitly, showing that the zone rule refuses IP-per-URL bursts at the CF edge before they reach the origin and the security-auth-magic-link per-email application rule continues to run on requests that pass the edge gate",
+  "soThat": "I understand the composition at apply time rather than discovering that both blueprints operate on separate characteristic sets by trial and error",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-36105-1",
+      "description": "The guide contains a section titled Composition with security-auth-magic-link that names ADR-3702 explicitly, states the zone rule characteristic (IP-per-URL) and the application rule characteristic (per-email per-minute) verbatim, and shows a copy-paste example of both blueprints applied on the same project.",
+      "given": "the shipped guide at blueprints/edge-cloudflare-rate-limiting/guide/edge-cloudflare-rate-limiting.md",
+      "when": "the anatomy test scans the guide for the composition section and ADR-3702 reference",
+      "then": "the section heading, ADR-3702 reference, both characteristic strings and the copy-paste example are present",
+      "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-36106.json

@@ -0,0 +1,27 @@
+{
+  "usId": "edge-cloudflare-rate-limiting-US-36106",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-rate-limiting-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Manifest schema validates every rule file against the shipped JSON Schema and refuses invalid shapes",
+  "asA": "operator on the applying project committing new rate-limit rule files under the elicited manifest directory",
+  "iWant": "the shipped JSON Schema to validate every rule file's shape (the seven required fields with the correct types) and the manifest-schema-validate probe to surface any file that violates the shape",
+  "soThat": "invalid manifest changes are caught in the fixture probe rather than at operator apply time against a live zone",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-36106-1",
+      "description": "Given the shipped rate-limit-rule JSON Schema (blueprints/edge-cloudflare-rate-limiting/contributions/schemas/rate-limit-rule.schema.json, draft-07), the manifest-schema-validate probe reads every manifest file in the fixture manifest directory and validates each against the schema; every valid file passes; a manifest file with a missing threshold field (simulated via SIMULATE_SCHEMA_INVALID=true) fails validation and the probe returns aggregateVerdict: fail with the offending field named in the detail.",
+      "given": "the cf-edge fixture with the two committed manifest files and the shipped JSON Schema",
+      "when": "the manifest-schema-validate probe validates every manifest file",
+      "then": "every valid file passes; the SIMULATE_SCHEMA_INVALID=true switch surfaces the missing threshold field and the aggregate verdict is fail",
+      "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-36107.json

@@ -0,0 +1,27 @@
+{
+  "usId": "edge-cloudflare-rate-limiting-US-36107",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-rate-limiting-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Drift-audit records carry metadata-only fields (ruleId, clientIpHash, outcome, timestamp) with no full IP, no body, no user agent",
+  "asA": "operator on the applying project reading drift-audit reports and rate-limit event records through the applied logging companion",
+  "iWant": "every drift-audit record and every rate-limit event record to carry only metadata-safe fields (ruleId, clientIpHash, outcome, timestamp, plus the drift diff fields where applicable), never a full client IP, never a request body, never a user agent string",
+  "soThat": "the audit trail is safe to store, forward and read without additional PII scrubbing at the audit sink",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-36107-1",
+      "description": "The event-secrecy probe drives a synthetic drift-audit payload constructed from a fixture rule and a fake live-zone response; every record on the sink carries only {ruleId, clientIpHash, outcome, timestamp} plus (for drift records) a diff array with the schema-safe fields; the probe asserts NO full IP (regex 4-octet dotted quad or v6 group), NO request body key, NO user-agent key; the SIMULATE_EVENT_LEAK_IP=true switch injects a full IP into the drift record and the probe returns aggregateVerdict: fail with the leaked key named in the detail.",
+      "given": "the shipped drift-audit runner and a synthetic input pair",
+      "when": "the event-secrecy probe drives the runner and inspects the resulting records",
+      "then": "every record carries only the metadata-safe fields; SIMULATE_EVENT_LEAK_IP=true surfaces a leaked key and the aggregate verdict is fail",
+      "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"
+}

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

@@ -0,0 +1,27 @@
+{
+  "usId": "edge-cloudflare-rate-limiting-US-36108",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-rate-limiting-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Manifest-presence probe refuses a missing manifest file and names the missing file in the detail",
+  "asA": "operator on the applying project accidentally deleting or moving a manifest file under the elicited manifest directory",
+  "iWant": "the manifest-presence probe to surface the missing file at fixture probe time rather than at operator apply time against a live zone",
+  "soThat": "a manifest under-population defect is caught in the CI probe rather than lingering until an operator notices a missing rule at the dashboard",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-36108-1",
+      "description": "Given the cf-edge fixture with the SIMULATE_MANIFEST_MISSING=true switch, one committed manifest file is treated as absent by the probe; the manifest-presence probe returns aggregateVerdict: fail with the missing file's basename named in the detail; without the switch the probe passes and both manifest files are inspected.",
+      "given": "the cf-edge fixture with two committed manifest files and the SIMULATE_MANIFEST_MISSING=true switch",
+      "when": "the manifest-presence probe scans the fixture manifest directory",
+      "then": "the probe returns aggregateVerdict: fail and the missing file basename is present in the detail",
+      "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/docs/topics.md

@@ -0,0 +1,71 @@
+# edge-cloudflare-rate-limiting blueprint coordination vocabulary
+
+This file is the edge-cloudflare-rate-limiting half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | edge-cloudflare-rate-limiting contribution | Origin | Composition note |
+| deploy-hetzner-server | 37101-37899 | 38xx | shipped v1.0.0 | `linuxCloudHostContract`, `snapshotAndBackupCadence` |
+| platform-docker-compose-host | 38101-38899 | 39xx | shipped v1.0.0 | `containerHostContract` |
+| edge-cloudflare-tunnel | 39101-39899 | 40xx | shipped v1.0.0 | `edgeIngressBridge` |
+|---|---|---|---|
+| `edgeThrottleContract` | ADR-3701-edge-cloudflare-rate-limiting-throttle-contract | Minted by this blueprint. Names the wire-shape contract for the project-wide edge throttle; the shipped answer is Cloudflare WAF rate-limiting rules per `https://developers.cloudflare.com/waf/rate-limiting-rules/`. | The one project-wide decision on the edge throttle at the shipped-shape boundary. A future non-Cloudflare sibling (Fastly rate-limits, Vercel Edge Config throttles) would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR. |
+
+The edge-cloudflare-rate-limiting blueprint claims one global topic (minted here, shipped as the Cloudflare WAF rate-limiting rules manifest and drift-audit). ADR-3702 layering, ADR-3703 manifest shape and ADR-3704 drift-audit cadence do not contribute global topics; a composing blueprint that holds an opinion on either authors its own project-level ADR.
+
+Rules for new topics: lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer.
+
+## Id number bands (registry bootstrap)
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.2.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.2.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
+| application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.1.0 | `adminConsoleSignInSurface` |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+| messaging-queue-cloudflare | 29101-29899 | 30xx | shipped v1.0.0 | `deliverySemantics` |
+| jobs-background | 30101-30899 | 31xx | shipped v1.0.0 | `backgroundJobModel` |
+| platform-cloudflare-kv | 31101-31899 | 32xx | shipped v1.0.0 | `keyValueStoreContract` |
+| platform-cloudflare-cron-triggers | 32101-32899 | 33xx | shipped v1.0.0 | `scheduledTriggerContract` |
+| platform-cloudflare-durable-objects | 33101-33899 | 34xx | shipped v1.0.0 | `strongConsistencyCellContract`, `websocketHubContract` |
+| edge-cloudflare-access | 34101-34899 | 35xx | shipped v1.0.0 | `edgeAuthenticationGate` |
+| edge-cloudflare-turnstile | 35101-35899 | 36xx | shipped v1.0.0 | `humanVerificationGate` |
+| edge-cloudflare-rate-limiting | 36101-36899 | 37xx | shipped v1.0.0 | `edgeThrottleContract` |
+
+US 36101-36108 sit at the LOW end of the 36101-36899 band on purpose (watchpost run-4 lesson). ADR/TAC suffixes for this blueprint use the 3701-3799 block, continuing the shelf pattern.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `edgeThrottleContract` exactly as spelled here when your blueprint holds an opinion on the edge throttle contract; contribute your own scope:global ADR on that string and let composition surface the pairing.
+- Consumer blueprints reading the `edgeRateLimit` capability declared on `blueprint.json` per section 6a of `blueprint-authoring.md` obtain the shipped rate-limit surface at apply time via the capability-declaration mechanism.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-3701 on `edgeThrottleContract` is the first shipped answer to a topic that will conflict, by design, with future non-Cloudflare siblings. Applying `edge-cloudflare-rate-limiting` alongside such a sibling would raise a `globalAdrTopic` conflict the operator resolves via one of the four documented resolutions (adopt one, keep the existing one, author a project-level supersede ADR, or `--resolve <topic>=project:<ADR-id>` on the add).

package/blueprints/edge-cloudflare-rate-limiting/guide/edge-cloudflare-rate-limiting.md

@@ -0,0 +1,88 @@
+# edge-cloudflare-rate-limiting guide
+
+Round 6 T-6 of the Cloudflare-first blueprint line. Ships zone-level rate limiting as an edge gate in front of Worker handlers. The rule set is a local manifest the applying project commits, and an operator applies it to the live Cloudflare zone through either a wrangler command flow or the Cloudflare dashboard flow, both walked below.
+
+## Manifest
+
+The applying project holds its rate-limit rule set as one JSON file per rule under the elicited `rate-limit-rules-dir` (default `cloudflare/rate-limits/`) per ADR-3703. Every file matches the shipped JSON Schema (`contributions/schemas/rate-limit-rule.schema.json`, draft-07) and carries the seven Cloudflare WAF rate-limiting rules documented fields per `https://developers.cloudflare.com/waf/rate-limiting-rules/`.
+
+Example (`cloudflare/rate-limits/public-api-per-ip.json`):
+
+```
+{
+  "id": "public-api-per-ip",
+  "expression": "(http.request.uri.path matches \"^/api/\")",
+  "threshold": 60,
+  "period": 60,
+  "characteristics": ["ip.src", "cf.colo.id"],
+  "action": "block",
+  "duration": 60,
+  "description": "Per-IP-per-colo throttle on /api/*; the (N+1)th request in 60s is blocked for 60s."
+}
+```
+
+The zone id is elicited (`rate-limit-zone-id`) and stored through the applied `secretsManagement` companion; a manifest file never inlines a zone id or an API token.
+
+## Management surface
+
+The blueprint ships no committed script that writes rules to the live zone. The operator applies each rule through one of two documented flows, or both. The elicited `rate-limit-management-surface` value records the choice.
+
+### wrangler flow
+
+The wrangler flow uses the Cloudflare API through a hand-run command sequence. The steps for one rule are:
+
+1. Set `CLOUDFLARE_API_TOKEN` (and `CLOUDFLARE_ACCOUNT_ID` for the account scope) in the operator's environment. Store both through the applied `secretsManagement` companion; never commit them to the git tree.
+2. Load the elicited zone id: `export CF_ZONE_ID=$(cat rcf/blueprints/edge-cloudflare-rate-limiting.applied.json | jq -r .elicits.rateLimitZoneId)` or read it from the applied vault seam.
+3. Fetch the existing rate-limiting ruleset id for the zone via the wrangler-installed API-fetch helper: `wrangler api curl "/zones/${CF_ZONE_ID}/rulesets?phase=http_ratelimit" --method GET` and note the `id` on the returned ruleset (create one if none exists per the vendor doc).
+4. For each rule file, `POST` the rule shape to the ruleset's `/rules` endpoint. The rule body is built from the manifest file by mapping each field one-to-one: `expression`, `action`, and a `ratelimit` object carrying `characteristics`, `period`, `requests_per_period` (from `threshold`), and `mitigation_timeout` (from `duration`).
+5. Verify by listing the ruleset again and confirming every manifest rule appears with the expected fields.
+
+The vendor doc `https://developers.cloudflare.com/waf/rate-limiting-rules/` names the endpoint shape verbatim; the wrangler flow is a hand-run reproduction of that shape.
+
+### Cloudflare dashboard flow
+
+The dashboard flow applies each rule through the Cloudflare zone dashboard. The steps for one rule are:
+
+1. Open the target zone in the Cloudflare dashboard.
+2. Navigate to Security -> WAF -> Rate limiting rules.
+3. Click Create rule; give the rule the manifest file's `id` as the operator-facing name.
+4. In When incoming requests match, set the Custom filter expression to the manifest `expression` (Edit expression toggle to paste raw).
+5. In Then take action, set the action to the manifest `action` (Block, Managed challenge, JS challenge or Log). Set the Duration to the manifest `duration` in seconds.
+6. In With the following properties, set the counting period to the manifest `period` seconds, the requests per period to the manifest `threshold`, and the characteristics to the manifest `characteristics` array (each string mapped to the dashboard's Same request property selectors).
+7. Save the rule. Repeat for every file in the manifest directory.
+
+Both flows produce the same shape on the live zone; the operator picks the flow that fits the project's operating discipline. The elicited `rate-limit-management-surface` records which flow the operator committed to at apply time.
+
+## Composition with security-auth-magic-link
+
+Per ADR-3702, when both `edge-cloudflare-rate-limiting` and `security-auth-magic-link` apply on the same project, the zone-level rate rule layers OVER the per-email application rule. The two rules operate on different characteristic sets and are additive:
+
+| Rule | Characteristic set | Where it runs |
+| --- | --- | --- |
+| Zone rule (this blueprint) | IP-per-URL (e.g. `ip.src` + `http.request.uri.path`) | Cloudflare edge, before any origin Worker code |
+| Application rule (magic-link) | per-email per-minute | Origin Worker mint-surface handler |
+
+Copy-paste example (applying both blueprints in the same project):
+
+```
+rcf define blueprint add ./blueprints/edge-cloudflare-rate-limiting \
+  --answer rate-limit-rules-dir=cloudflare/rate-limits \
+  --answer rate-limit-zone-id=<vault-ref> \
+  --answer rate-limit-management-surface=both \
+  --answer rate-limit-drift-audit-cadence=daily
+
+rcf define blueprint add ./blueprints/security-auth-magic-link \
+  --answer magic-link-mint-rate-limit=5perMinute
+```
+
+The applied recorder records both blueprints so the operator sees the two-rule shape at apply time.
+
+## Drift audit
+
+The blueprint ships a scheduled drift-audit runner realisation in the `cf-edge` fixture at `packages/rcf-lite/test/fixtures/cf-edge/src/drift-audit-runner.mjs`. The runner exports `createDriftAuditRunner({env, eventSink, fetch, clock, cadence, manifestLoader})` per TAC-3703 and fetches the live rules on the elicited zone via `https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets`, diffs field-by-field against the local manifest, and constructs one drift-audit record per mismatched rule with the metadata-only shape `{ruleId, clientIpHash, outcome, timestamp, diff}`. No record carries a full client IP, a request body or a user agent (event-secrecy discipline per REQ-005 and AC-36107-1).
+
+The elicited `rate-limit-drift-audit-cadence` per ADR-3704 picks `off` (runner not wired), `daily` (24-hour cadence, `recommendedDefault`), or `hourly`.
+
+## Runtime observable and CI
+
+Per spec section 3.1 and ruling 6, the runtime observable for `AC-rateLimiting-overThresholdBlocks` (US-36103/AC-36103-1) is the real-account burst probe. In CI without `CI_HAS_CLOUDFLARE_ACCOUNT` and `CF_RATE_LIMIT_URL`, the probe records `accountBoundSkipped: true` and aggregates to `pass`; this IS the accepted CI verdict. The three local probes (manifest presence, manifest schema validate, event secrecy) always run and always gate the ship.

package/blueprints/edge-cloudflare-tunnel/CHANGELOG.md

@@ -0,0 +1,13 @@
+# edge-cloudflare-tunnel CHANGELOG
+
+## 1.0.0 - 2026-09-08
+
+Initial release. Round-7 T-3 of the Hetzner spec at `projects/blueprint-library/specs/hetzner-round-7-spec-2026-09-07.md`.
+
+- Mints capability `tunnelBridge` and global topic `edgeIngressBridge`.
+- Five REQs, eight USs, three TACs, three ADRs; five Node-only probes.
+- Extends the shared throwaway-Hetzner-server fixture with a cloudflared connector in both runtime shapes (compose-service alongside the T-2 web and caddy services when `containerHost` is applied; systemd-unit for a bare `cloudHost`) and both hostname modes (access-gated when `zeroTrustGate` is applied; public-hostname when absent) plus five `run-<probe>.mjs` delegate shims.
+- manifest-schema-validate carries five fixture-side mutation switches (`SIMULATE_MANIFEST_INVALID_TUNNEL_ID`, `SIMULATE_MANIFEST_CREDENTIALS_INLINE`, `SIMULATE_MANIFEST_MISSING_CATCHALL`, `SIMULATE_ORIGIN_PORT_OPEN`, `SIMULATE_EVENT_SECRECY_LEAK`); cloudflared-config-lint carries `SIMULATE_INGRESS_INVALID` and runs `cloudflared tunnel ingress validate` via the `cloudflare/cloudflared:2026.8.3` container when a local binary is not on PATH; aud-presence-check carries `SIMULATE_AUD_DROP`.
+- Mutation-discipline (T-2 gate ruling carried forward): every `SIMULATE_*` switch lives in the fixture-side delegate shim; the probe modules read only `RCF_LITE_T3_FIXTURE_ROOT` and never branch on being under mutation.
+- Connector-runtime choice elicited via `connector-runtime` (compose-service default when `containerHost` applied; systemd-unit alternative for bare `cloudHost`, per the vendor cloudflared as-a-service local-configuration-file docs); hostname-mode discovered (not elicited) from `appliedCapabilities` via the sidecar per ADR-4003.
+- Consumers: `w-2026-09-06-dave-010` follow-on (make the librarian API and workspace viewer reachable without Mullvad) is the estate consumer; blueprint acceptance never depends on that consumer, and the ops-01 migration mints as its own work item.

package/blueprints/edge-cloudflare-tunnel/README.md

@@ -0,0 +1,257 @@
+# edge-cloudflare-tunnel
+
+Round-7 T-3 core blueprint on the rcf-lite shelf. Bridges a service on a
+`cloudHost` (bare, systemd shape) or a `containerHost` (compose-service
+shape) to the Cloudflare edge through a Cloudflare Tunnel, with no
+public origin ports. When applied alongside `edge-cloudflare-access`
+(via the `zeroTrustGate` capability) the tunnel binds an Access AUD;
+when applied without it the tunnel serves in public-hostname mode.
+
+- Slug: `edge-cloudflare-tunnel`
+- Version: `1.0.0`
+- Category: `edge`
+- Capabilities: `["tunnelBridge"]`
+- Mints global topic: `edgeIngressBridge`
+- Contribution count: 5 REQs, 8 USs, 3 TACs, 3 ADRs, 5 probes
+- Consumers: ops-01 has no consumer today (SSH is the only inbound path). Estate consumer is the follow-on make-the-librarian-API-and-workspace-viewer-reachable-without-Mullvad work that `w-2026-09-06-dave-010` is expected to green-light. Blueprint acceptance never depends on that consumer; the ops-01 migration mints as a separate work item at that point (`w-2026-09-07-dave-004`).
+
+## Five REQs
+
+| Id | Contract |
+|---|---|
+| edge-cloudflare-tunnel-REQ-001 | Connector install shape switches on applied `containerHost` (compose-service default; systemd-unit for bare `cloudHost`); `cloudflaredReady` fires on boot with connector id, region and version metadata. |
+| edge-cloudflare-tunnel-REQ-002 | Tunnel manifest schema at `cloudflare/tunnels/<name>.yaml` (uuid tunnel id, `credentialsFile.secretRef` reference, ingress rules with catch-all `http_status:404`). |
+| edge-cloudflare-tunnel-REQ-003 | No public origin ports on the host; T-1 firewall stays closed on 80/443 unless a reverse proxy is applied; manifest refuses ingress rules whose service URL binds to a host public interface. |
+| edge-cloudflare-tunnel-REQ-004 | Access-gated composition: `zeroTrustGate` applied attaches `originRequest.access.aud`; absent omits the block and serves in public-hostname mode. |
+| edge-cloudflare-tunnel-REQ-005 | Credentials-file discipline (host mode 0o400, referenced via `secretRef`, not committed, grep-refuse, no leak in event bodies). |
+
+## Connector runtime shapes
+
+The connector runtime is elicited via `connector-runtime` (ADR-4002) with
+`recommendedDefault: compose-service`.
+
+- **compose-service** (default when `containerHost` is applied). The
+  cloudflared container ships alongside the applying project services on
+  the same web-net network. No host ports; restart `unless-stopped`;
+  logging driver aligned with the T-2 compose-host log-driver elicit.
+  Fixture: `packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/compose-service/`.
+- **systemd-unit** (alternative for a bare `cloudHost`). The cloudflared
+  binary is installed via the vendor package per the cloudflared
+  as-a-service documented systemd unit and runs as a systemd service
+  reading the local configuration file. Fixture:
+  `packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/systemd-unit/`.
+
+When to reach for which: pick compose-service when the project already
+runs docker compose on the host (natural home, same log driver, same
+restart discipline); pick systemd-unit when the host runs bare and there
+is no compose stack to add a service to (or when the project deliberately
+keeps cloudflared outside the compose lifecycle for boot ordering).
+
+## Tunnel manifest shape
+
+The manifest lives at `cloudflare/tunnels/<name>.yaml` under the
+applying project. The shipped JSON schema
+(`contributions/probes/tunnel-manifest.schema.json`) requires:
+
+- `tunnel`: uuid-shaped Cloudflare Tunnel id.
+- `credentialsFile.secretRef`: reference into `security-secrets-management`
+  (never a literal path or JSON body inline).
+- `ingress`: array of `{ hostname?, service, originRequest? }`. The last
+  entry MUST be a catch-all `service: http_status:404`. When the
+  Access-gated shape is applied every non-catch-all rule attaches
+  `originRequest.access.aud` with the AUD from the sidecar.
+
+Example (compose-service, public-hostname mode):
+
+```yaml
+tunnel: 00000000-0000-4000-8000-0000000012ab
+credentialsFile:
+  secretRef: hq-estate/CLOUDFLARE_TUNNEL_CREDENTIALS_MY_PROJECT
+ingress:
+  - hostname: my-app.example.com
+    service: http://web:8080
+  - service: http_status:404
+```
+
+Example (Access-gated shape adds one block per non-catch-all rule):
+
+```yaml
+ingress:
+  - hostname: my-app.example.com
+    service: http://web:8080
+    originRequest:
+      access:
+        aud: AUD-example-cloudflare-team
+        teamName: my-team
+        required: true
+  - service: http_status:404
+```
+
+## Credentials-file discipline
+
+The tunnel credentials JSON file lands on the host at mode 0o400 (owner
+read only). The manifest references it as a `credentialsFile.secretRef`;
+the fixture placeholder at
+`packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/*/credentials/probe.json.example`
+documents the pattern. The credentials file MUST NOT be committed to
+the applying project tree; a grep across the working tree for the
+tunnel id and account tag literals refuses on any tracked file. Every
+`cloudflaredReady`, `tunnelConnectorUp` and `ingressRuleReloaded` event
+body carries metadata only; the event-secrecy scan refuses on a body
+that mentions the credentials literal.
+
+Rotate credentials by rewriting the secret pointed to by `secretRef`
+and re-applying; the connector reloads on the next boot cycle.
+
+## Composition point (Access-gated vs public-hostname)
+
+The hostname mode is discovered from the applied capability set (not
+elicited; see ADR-4003). The blueprint reads the sidecar at
+`rcf/blueprints/edge-cloudflare-tunnel.applied.json` and inspects
+`appliedCapabilities`.
+
+- When `zeroTrustGate` is present (i.e. `edge-cloudflare-access` v1.0.0
+  is applied on the same project), every ingress rule attaches
+  `originRequest.access.aud` and cloudflared refuses at the edge any
+  request without a valid Access JWT for that AUD.
+- When `zeroTrustGate` is absent, the block is omitted and the tunnel
+  serves in public-hostname mode (open ingress on the public hostname;
+  authorization is whatever the origin service itself carries).
+
+The `aud-presence-check` probe refuses when the gated variant drifts to
+omit the AUD block (defensive against silent degradation).
+
+Graceful degrade: when Access is not applied (T-4 absent from
+`origin/main` or the applying project simply does not want the gate),
+the blueprint still ships in public-hostname mode. The probe assertion
+runs on both fixture variants so the shape flip is proven on every
+reviewer boot.
+
+## No-public-ports rule
+
+The T-1 firewall on a `cloudHost` allows 22 unconditionally and 80/443
+only when a reverse proxy is applied. A project applying only T-1 plus
+T-3 (no reverse proxy) declares zero 80/443 rules; the tunnel is the
+sole path from the edge to the origin. The manifest schema refuses
+ingress rules whose service URL binds to `0.0.0.0`, a non-loopback
+numeric IP, or an unresolvable shape.
+
+## Elicited parameters
+
+- `tunnel-name` (string; default `probe`): the Cloudflare Tunnel name
+  and the manifest filename under `cloudflare/tunnels/<name>.yaml`.
+- `cloudflare-zone-secret` (string; default `hq-estate/CLOUDFLARE_ZONE_ID`):
+  `security-secrets-management` reference to the Cloudflare zone the
+  tunnel serves under.
+- `public-hostname-template` (string; default `<service>.<zone>`):
+  template for the public hostname, expanded per ingress rule.
+- `ingress-rules` (string; default `[]`): ingress rules array (hostname
+  + service URL pairs).
+- `access-aud` (string; default empty): Access AUD tag for the gated
+  shape. Presence toggles the gated shape when `zeroTrustGate` is
+  applied.
+- `connector-runtime` (enum: `compose-service`, `systemd-unit`; default
+  `compose-service`): the connector runtime per ADR-4002.
+
+## Companions
+
+- `suggestedCompanions[logging]`: every `cloudflaredReady`,
+  `tunnelConnectorUp`, `tunnelConnectorDown`, `ingressRuleReloaded` and
+  `accessGateRefused` event writes through the applied logger.
+- `suggestedCompanions[errorHandling]`: a cloudflared exit, a JWT-check
+  failure, an ingress-rule schema violation, a hostname-DNS-route API
+  refusal constructs an internal error record.
+
+`providesRoles: []`.
+
+## Five probes
+
+Every probe writes its report envelope to
+`.rcf/reports/blueprints/edge-cloudflare-tunnel/<probe-name>.json`
+under the repo root.
+
+- **manifest-schema-validate** (local). Anchors AC-tunnel-manifestSchema,
+  AC-tunnel-noPublicOrigin, AC-tunnel-credentialsDiscipline. `accountBound: false`.
+  Ajv-free walker over the shipped JSON schema; runs on all four
+  variants; refuses on `SIMULATE_MANIFEST_INVALID_TUNNEL_ID`,
+  `SIMULATE_MANIFEST_CREDENTIALS_INLINE`, `SIMULATE_MANIFEST_MISSING_CATCHALL`,
+  `SIMULATE_ORIGIN_PORT_OPEN`, `SIMULATE_EVENT_SECRECY_LEAK`.
+- **cloudflared-config-lint** (local). Anchors AC-tunnel-hostnameRoutes.
+  `accountBound: false`. Runs `cloudflared tunnel --config <path> ingress validate`
+  via a local binary or the vendor container image
+  `cloudflare/cloudflared:2026.8.3`; refuses on `SIMULATE_INGRESS_INVALID`.
+- **aud-presence-check** (local). Anchors AC-tunnel-accessGated,
+  AC-tunnel-accessGatedRefuse. `accountBound: false`. Reads the sidecar
+  and the paired manifests; asserts the shape flips correctly; refuses
+  on `SIMULATE_AUD_DROP` when the gated fixture drifts to open ingress.
+- **real-account-connector-healthy** (account-bound). Anchors
+  AC-tunnel-connectorHealthy. `accountBound: true` on
+  `CI_HAS_CLOUDFLARE_ACCOUNT` AND `CI_HAS_HETZNER_ACCOUNT`. Without
+  both, records `accountBoundSkipped: true` and the aggregate flips to
+  `pass`.
+- **real-account-tunnel-hostname-routes** (account-bound). Anchors
+  AC-tunnel-hostnameRoutes (public sub-case) and AC-tunnel-accessGated
+  (gated sub-case). `accountBound: true`. The public-hostname sub-case
+  runs on `CI_HAS_CLOUDFLARE_ACCOUNT` + `CI_HAS_HETZNER_ACCOUNT`; the
+  access-gated sub-case adds `CI_HAS_CLOUDFLARE_ACCESS` per the round-7
+  Q4 ratification. Sub-cases skip independently.
+
+The delegate shims at
+`packages/rcf-lite/test/fixtures/hetzner-throwaway-server/run-<probe>.mjs`
+read the `SIMULATE_*` env vars and prepare mutated inputs in a scratch
+dir; the probe modules never read a `SIMULATE_` env var and never
+branch on being under mutation.
+
+## Two fixture variants times two hostname modes
+
+The fixture lives under
+`packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/`:
+
+- `compose-service/compose-fragment.yaml`: the cloudflared compose
+  service alongside the T-2 web and caddy services.
+- `systemd-unit/cloudflared.service`: the systemd unit per the vendor
+  as-a-service docs.
+- `<runtime>/cloudflare/tunnels/public-hostname.yaml`: manifest without
+  the AUD block.
+- `<runtime>/cloudflare/tunnels/access-gated.yaml`: manifest with the
+  AUD block on every non-catch-all rule.
+- `<runtime>/credentials/probe.json.example`: placeholder credentials
+  documenting the 0o400 mode discipline.
+- `sidecars/access-gated.applied.json`: `appliedCapabilities` includes
+  `zeroTrustGate`.
+- `sidecars/public-hostname.applied.json`: `appliedCapabilities`
+  excludes `zeroTrustGate`.
+
+Reviewer boot (mocked, no account) from the fixture directory:
+
+```
+cd packages/rcf-lite/test/fixtures/hetzner-throwaway-server
+node ./run-tunnel-manifest-schema-validate.mjs && node ./run-cloudflared-config-lint.mjs && node ./run-aud-presence-check.mjs
+```
+
+Reviewer boot (real account, throwaway server): set
+`CI_HAS_CLOUDFLARE_ACCOUNT=true` and `CI_HAS_HETZNER_ACCOUNT=true`
+(and `CI_HAS_CLOUDFLARE_ACCESS=true` for the gated sub-case) with the
+account tokens loaded via `security-secrets-management`, then invoke the
+two `run-real-account-*.mjs` scripts.
+
+## Composition on the shelf
+
+Consumes:
+- `platform-docker-compose-host` v1.0.0 (`containerHost` capability) for
+  the compose-service runtime path.
+- `deploy-hetzner-server` v1.0.0 (`cloudHost` capability) for the bare
+  systemd-unit runtime path.
+- `security-secrets-management` v1.0.1 (`secretsProvider` capability) for
+  the tunnel credentials `secretRef`.
+- Optionally `edge-cloudflare-access` v1.0.0 (`zeroTrustGate` capability)
+  for the Access-gated shape.
+
+Provides:
+- `tunnelBridge` (declared under `capabilities` on `blueprint.json`).
+- New global topic `edgeIngressBridge` on ADR-4001 (scope global).
+
+Conflict-by-design with future non-Cloudflare siblings on the
+`edgeIngressBridge` topic: Tailscale Funnel, Fly.io proxy, etc.
+would contribute the same topic string with a different mechanism.
+Round 7 ships only the Cloudflare Tunnel provider.