rcf-lite 0.23.0 → 0.25.0

package/blueprints/edge-cloudflare-tunnel/contributions/user-stories/edge-cloudflare-tunnel-us-39101.json

@@ -0,0 +1,24 @@
+{
+  "usId": "edge-cloudflare-tunnel-US-39101",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-tunnel-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Connector install shape switches on applied containerHost (compose-service default; systemd-unit fallback for bare cloudHost)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 alongside deploy-hetzner-server (and optionally platform-docker-compose-host)",
+  "iWant": "the cloudflared connector to install as a compose service when the containerHost capability is applied and as a systemd unit when the host runs bare",
+  "soThat": "the runtime shape matches the applied platform rather than forcing a container onto a bare host or a bare service into a compose-managed stack",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-tunnel-connectorShape",
+      "description": "The applied fixture ships both variants under packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/{compose-service,systemd-unit}/; the compose-service variant defines a cloudflared service on the same web-net network as the T-2 web and caddy services with no host ports, restart unless-stopped and a healthcheck; the systemd-unit variant ships a cloudflared.service unit file per the vendor local-configuration-file docs.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4001-edge-cloudflare-tunnel-connector-shape"
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/user-stories/edge-cloudflare-tunnel-us-39102.json

@@ -0,0 +1,24 @@
+{
+  "usId": "edge-cloudflare-tunnel-US-39102",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-tunnel-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Cloudflared connector reports healthy on boot (tunnelConnectorUp fires with connector id, region, version)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 on a cloudHost",
+  "iWant": "the connector to emit a tunnelConnectorUp event on boot with connector id, region and version metadata (metadata only)",
+  "soThat": "the observability sink proves the tunnel is up without a shell into the host",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-tunnel-connectorHealthy",
+      "description": "real-account-connector-healthy probe declares accountBound true (on CI_HAS_CLOUDFLARE_ACCOUNT AND CI_HAS_HETZNER_ACCOUNT) and records accountBoundSkipped when either is unset. When both are set the probe drives cloudflared tunnel info against the fixture tunnel and asserts at least one healthy connector plus a tunnelConnectorUp event with connector id, region and version.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4001-edge-cloudflare-tunnel-connector-shape"
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/user-stories/edge-cloudflare-tunnel-us-39103.json

@@ -0,0 +1,24 @@
+{
+  "usId": "edge-cloudflare-tunnel-US-39103",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-tunnel-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Tunnel manifest at cloudflare/tunnels/<name>.yaml validates on shape (uuid tunnel id, secretRef credentials, ingress with catch-all 404)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0",
+  "iWant": "the tunnel manifest to validate against a shipped JSON schema requiring a uuid-shaped tunnel id, a secretRef credentials reference, and an ingress rules array whose last entry is a mandatory catch-all http_status 404",
+  "soThat": "a mis-shaped manifest is caught at apply-time rather than at first inbound request",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-tunnel-manifestSchema",
+      "description": "manifest-schema-validate probe passes on the canonical fixture and fails when the fixture is mutated (SIMULATE_MANIFEST_INVALID_TUNNEL_ID, SIMULATE_MANIFEST_CREDENTIALS_INLINE, SIMULATE_MANIFEST_MISSING_CATCHALL) naming the offending field.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4002-edge-cloudflare-tunnel-manifest-schema"
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/user-stories/edge-cloudflare-tunnel-us-39104.json

@@ -0,0 +1,24 @@
+{
+  "usId": "edge-cloudflare-tunnel-US-39104",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-tunnel-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Cloudflared tunnel ingress validate exits 0 on the fixture manifest (routes public hostname to internal service URL)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 with a compose service listening on an internal port",
+  "iWant": "the ingress rule mapping the public hostname to the internal service URL (http://web:8080 in the compose-service variant, http://127.0.0.1:8080 in the systemd-unit variant) to pass cloudflared tunnel ingress validate cleanly",
+  "soThat": "a rule that would fail at boot fails at gate instead",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-tunnel-hostnameRoutes",
+      "description": "cloudflared-config-lint probe runs cloudflared tunnel ingress validate against the fixture manifest (through the cloudflare/cloudflared:2026.8.3 container image when the binary is not on PATH) and exits 0 on the canonical fixture; SIMULATE_INGRESS_INVALID rewrites the service URL to an unresolvable scheme and the probe FAILS.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4002-edge-cloudflare-tunnel-manifest-schema"
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/user-stories/edge-cloudflare-tunnel-us-39105.json

@@ -0,0 +1,24 @@
+{
+  "usId": "edge-cloudflare-tunnel-US-39105",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-tunnel-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "No public origin ports on the host (firewall stays 22 open plus 80/443 only when a reverse proxy is applied; manifest refuses origin-port request)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 without a reverse proxy",
+  "iWant": "the host firewall to stay closed on 80/443 and the manifest schema to refuse any ingress rule whose service URL binds to a host public interface",
+  "soThat": "the tunnel remains the only path from the edge to the origin",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-tunnel-noPublicOrigin",
+      "description": "manifest-schema-validate refuses under SIMULATE_ORIGIN_PORT_OPEN when an ingress rule service URL binds to 0.0.0.0 or a host public interface; the T-1 firewall on the ci-throwaway manifest stays 22 open plus 80/443 open only when a reverse proxy is applied.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4002-edge-cloudflare-tunnel-manifest-schema"
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/user-stories/edge-cloudflare-tunnel-us-39106.json

@@ -0,0 +1,24 @@
+{
+  "usId": "edge-cloudflare-tunnel-US-39106",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-tunnel-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Access-gated composition: zeroTrustGate applied attaches originRequest.access.aud; absent omits the block",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 alongside edge-cloudflare-access v1.0.0",
+  "iWant": "every ingress rule to attach an originRequest.access block naming the Access AUD when zeroTrustGate is applied and to omit the block when it is not",
+  "soThat": "the shape switches purely on the applied capability set and never silently degrades",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-tunnel-accessGated",
+      "description": "aud-presence-check probe reads each variant sidecar and asserts the ingress rules attach originRequest.access.aud on the access-gated variant and omit the block on the public-hostname variant. The shape flip is a pure function of the sidecar contents.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4003-edge-cloudflare-tunnel-access-binding"
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/user-stories/edge-cloudflare-tunnel-us-39107.json

@@ -0,0 +1,24 @@
+{
+  "usId": "edge-cloudflare-tunnel-US-39107",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-tunnel-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Access-gated shape does not silently degrade to open ingress when the AUD block drifts absent (aud-presence-check refuses)",
+  "asA": "shelf consumer who applied edge-cloudflare-tunnel v1.0.0 with zeroTrustGate on",
+  "iWant": "a probe that asserts the ingress rule keeps its originRequest.access.aud block on every reapply and refuses if the block drifts absent",
+  "soThat": "a silent config drift to open ingress is caught at gate rather than at first probing",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-tunnel-accessGatedRefuse",
+      "description": "aud-presence-check FAILS under SIMULATE_AUD_DROP when the gated fixture ingress drifts to omit the originRequest.access block. The finding names the affected rule and the missing AUD value.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4003-edge-cloudflare-tunnel-access-binding"
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/user-stories/edge-cloudflare-tunnel-us-39108.json

@@ -0,0 +1,24 @@
+{
+  "usId": "edge-cloudflare-tunnel-US-39108",
+  "prdId": "PRD-001",
+  "reqId": "edge-cloudflare-tunnel-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Credentials-file discipline (0o400 host mode, secretRef, not committed, grep-refuse, no leak in event bodies)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 on a cloudHost",
+  "iWant": "the tunnel credentials file to land at mode 0o400 on the host, be referenced from the manifest as a secretRef, never be committed to the applying tree (grep-refuse on the tunnel id and account tag literals), and never appear in any lifecycle event body",
+  "soThat": "a leaked credentials file cannot happen through a review-time miss",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-tunnel-credentialsDiscipline",
+      "description": "The fixture credentials placeholder documents the 0o400 host mode and secretRef pattern; the manifest references the credentials via a secretRef; the grep-refuse pattern is documented in the guide; every cloudflaredReady, tunnelConnectorUp and ingressRuleReloaded event body captured by the in-process facade carries metadata only, and SIMULATE_EVENT_SECRECY_LEAK inserts the credentials literal into a lifecycle event body and the scan FAILS naming the leaked field.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-4002-edge-cloudflare-tunnel-manifest-schema"
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/docs/topics.md

@@ -0,0 +1,72 @@
+# edge-cloudflare-tunnel blueprint coordination vocabulary
+
+This file is the edge-cloudflare-tunnel 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-tunnel contribution | Origin | Composition note |
+|---|---|---|---|
+| `edgeIngressBridge` | ADR-4001-edge-cloudflare-tunnel-ingress-bridge-contract | Minted by this blueprint. Names the wire-shape contract for the project-wide ingress-bridge from a `cloudHost` service to the CF edge; the shipped answer is a Cloudflare Tunnel connector (as a compose service by default when `containerHost` is applied; as a systemd unit for a bare `cloudHost` per the vendor cloudflared as-a-service local-configuration-file docs). | The one project-wide decision on how a service on a `cloudHost` reaches the public internet without opening origin ports. A future non-Cloudflare sibling (Tailscale Funnel, Fly.io proxy) would contribute the same topic string with a different mechanism, forcing a DELIBERATE conflict the operator resolves with a project-level ADR. |
+
+The edge-cloudflare-tunnel blueprint claims one global topic (minted here, shipped as the Cloudflare Tunnel connector bridge on a `cloudHost` or `containerHost`). ADR-4002 connector-runtime elicit and ADR-4003 hostname-mode discovered decision 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` |
+| 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` |
+
+US 39101-39108 sit at the LOW end of the 39101-39899 band on purpose (watchpost run-4 lesson). A project-side story mechanically derived from an edge-cloudflare-tunnel REQ id into the number 39108 would collide against the shipped US-39108; band headroom (39109-39899) leaves that space.
+
+Edge-cloudflare-tunnel suffixes for this blueprint use the 4001-4003 block, continuing the widening pattern (deploy-hetzner-server 3801-3804 for the T-1 sibling, platform-docker-compose-host 3901-3904 for the T-2 sibling).
+
+## Cross-references
+
+- `deploy-hetzner-server` (v1.0.0): consumed via `capabilities: [cloudHost]` for the bare systemd-unit connector runtime path.
+- `platform-docker-compose-host` (v1.0.0): consumed via `capabilities: [containerHost]` for the shipped default compose-service connector runtime path.
+- `security-secrets-management` (v1.0.1): the tunnel credentials file source resolves through the applied secrets facade when the secrets blueprint is applied; the guide names the `secretRef` shape.
+- `edge-cloudflare-access` (v1.0.0): optional composition on `capabilities: [zeroTrustGate]`; when applied, ingress rules attach originRequest.access.aud per ADR-4003.
+- `observability-logging`: the applied logging companion consumes every `cloudflaredReady`, `tunnelConnectorUp`, `tunnelConnectorDown`, `ingressRuleReloaded` and `accessGateRefused` event.

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

@@ -0,0 +1,204 @@
+# Guide: edge-cloudflare-tunnel
+
+The edge-cloudflare-tunnel blueprint bridges a service on a `cloudHost`
+or a `containerHost` to the Cloudflare edge through a Cloudflare Tunnel,
+with no public origin ports. This guide walks the shape end to end:
+what the connector looks like, what the manifest looks like, how the
+Access-gated shape composes on top of the public-hostname shape, and
+how the credentials-file discipline stays honest on every reapply.
+
+Ratifying spec: `projects/blueprint-library/specs/hetzner-round-7-spec-2026-09-07.md` section 5.3.
+
+## When to reach for this blueprint
+
+Reach when the applying project needs to expose a service on the public
+internet without opening origin ports on the host and without standing
+up a bespoke reverse proxy in front of the CDN. The tunnel connector
+dials out to the Cloudflare edge and terminates ingress there; the host
+firewall (T-1 deploy-hetzner-server) can stay closed on 80/443 unless a
+reverse proxy is also applied.
+
+Do not reach for this blueprint when the applying project runs on
+Cloudflare Workers (`deploy-cloudflare-workers` handles ingress
+directly), when the applying project runs behind a corporate VPN
+(private connectivity has different tools), or when the ingress path
+needs a non-Cloudflare bridge shape (Tailscale Funnel, Fly.io proxy;
+those will mint on operator demand into their own reserved slots).
+
+## Connector runtime: when to reach for compose-service vs systemd-unit
+
+The connector runtime is elicited via `connector-runtime` per ADR-4002
+with `recommendedDefault: compose-service`.
+
+Reach for **compose-service** (the shipped default when `containerHost`
+is applied) when the applying project already runs docker compose on
+the host. The connector ships as another service in the same stack,
+sharing the compose network, the log driver and the restart discipline.
+The T-2 platform-docker-compose-host contract makes this the natural
+home; the connector composes on `containerHost` from T-2.
+
+Reach for **systemd-unit** when the host runs bare (only T-1 applied)
+and there is no compose stack to add a service to. The connector runs
+as a systemd unit per the vendor cloudflared as-a-service documented
+systemd unit; the unit file lives at `/etc/systemd/system/cloudflared.service`
+on the host and reads the local configuration file at
+`/etc/cloudflared/<name>.yaml`. Boot ordering plays nicely with journald.
+
+The fixture ships both variants under
+`packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/{compose-service,systemd-unit}/`
+and both pass `manifest-schema-validate`, `cloudflared-config-lint` and
+`aud-presence-check` on every reviewer boot.
+
+## Hostname mode: when to reach for Access-gated vs public-hostname
+
+The hostname mode is not elicited. It is DISCOVERED from the applied
+capability set (ADR-4003). When `zeroTrustGate` is applied (i.e.
+edge-cloudflare-access v1.0.0 is applied on the same project), every
+ingress rule attaches `originRequest.access.aud` with the AUD from the
+sidecar. When `zeroTrustGate` is not applied, the block is omitted and
+the tunnel serves in public-hostname mode.
+
+Reach for **access-gated** when the service behind the tunnel needs an
+authentication gate at the edge (any request without a valid Access
+JWT is refused before it hits the origin). The Access side of the
+composition is owned by edge-cloudflare-access; edge-cloudflare-tunnel
+only reads the sidecar and attaches the AUD block. See the vendor
+self-hosted-public-app documentation for the full AUD binding shape.
+
+Reach for **public-hostname** when the service is deliberately public
+(a marketing page, a documentation site, or a public API where
+authorisation lives at the origin). The tunnel still terminates
+ingress at the CF edge; no origin port is opened; the difference is
+that cloudflared does not check for a JWT before forwarding.
+
+Graceful degrade: when Access is not applied, the blueprint still ships
+in public-hostname mode. The `aud-presence-check` probe runs on both
+fixture variants and asserts the shape flips correctly.
+
+## Tunnel manifest walkthrough
+
+The applying project ships one tunnel manifest per named tunnel at
+`cloudflare/tunnels/<name>.yaml`. A minimal public-hostname manifest:
+
+```yaml
+tunnel: 12345678-90ab-4cde-8f12-3456789abcde
+credentialsFile:
+  secretRef: hq-estate/CLOUDFLARE_TUNNEL_CREDENTIALS_MY_PROJECT
+ingress:
+  - hostname: my-app.example.com
+    service: http://web:8080
+  - service: http_status:404
+```
+
+An access-gated manifest adds one `originRequest.access` block per
+non-catch-all rule:
+
+```yaml
+tunnel: 12345678-90ab-4cde-8f12-3456789abcde
+credentialsFile:
+  secretRef: hq-estate/CLOUDFLARE_TUNNEL_CREDENTIALS_MY_PROJECT
+ingress:
+  - hostname: my-app.example.com
+    service: http://web:8080
+    originRequest:
+      access:
+        aud: AUD-example-team
+        teamName: my-team
+        required: true
+  - service: http_status:404
+```
+
+The shipped JSON schema at
+`blueprints/edge-cloudflare-tunnel/contributions/probes/tunnel-manifest.schema.json`
+requires: a uuid-shaped `tunnel` id, a `credentialsFile.secretRef`
+reference (never a literal path or inline JSON body), and an ingress
+rules array whose last entry is a catch-all `service: http_status:404`.
+Every ingress service URL must bind to an internal address (a compose
+service name or a loopback interface); binding to `0.0.0.0` or a
+non-loopback numeric IP refuses at apply time.
+
+## Credentials rotation pattern
+
+The tunnel credentials JSON file lands on the host at mode 0o400 (owner
+read only) and is referenced from the manifest as a
+`credentialsFile.secretRef`. To rotate:
+
+1. Regenerate the credentials via `cloudflared tunnel token <name>` or
+   the Cloudflare API against the tunnel id.
+2. Update the secret named by the manifest's `secretRef` via
+   `security-secrets-management`.
+3. Trigger a reapply on the applying project; the connector picks up
+   the new credentials on its next boot cycle.
+
+The credentials file MUST NOT be committed to the applying 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.
+
+## Composition on the shelf
+
+Consumes: `platform-docker-compose-host` (compose-service runtime),
+`deploy-hetzner-server` (bare cloudHost systemd runtime),
+`security-secrets-management` (credentials secretRef). Optionally
+consumes `edge-cloudflare-access` (the Access-gated shape).
+
+Provides: `tunnelBridge` capability; new global topic
+`edgeIngressBridge` (ADR-4001 scope global).
+
+The `deliver-ci-workflows` shelf blueprint invokes the two account-bound
+probes on a scratch subdomain when the account tokens are present;
+without them the probes record `accountBoundSkipped: true` and the
+aggregate flips to pass per hetzner-round-7-spec section 3.5.
+
+## Running the probes
+
+Every reviewer boot exercises the three local probes on the fixture:
+
+```
+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
+```
+
+Every probe writes its report envelope to
+`.rcf/reports/blueprints/edge-cloudflare-tunnel/<probe-name>.json`
+under the repo root.
+
+Mutations (fixture-side, one per switch; the probe modules never read
+`SIMULATE_` env vars):
+
+- `SIMULATE_MANIFEST_INVALID_TUNNEL_ID=true` on `run-tunnel-manifest-schema-validate.mjs`
+- `SIMULATE_MANIFEST_CREDENTIALS_INLINE=true` on `run-tunnel-manifest-schema-validate.mjs`
+- `SIMULATE_MANIFEST_MISSING_CATCHALL=true` on `run-tunnel-manifest-schema-validate.mjs`
+- `SIMULATE_ORIGIN_PORT_OPEN=true` on `run-tunnel-manifest-schema-validate.mjs`
+- `SIMULATE_EVENT_SECRECY_LEAK=true` on `run-tunnel-manifest-schema-validate.mjs`
+- `SIMULATE_INGRESS_INVALID=true` on `run-cloudflared-config-lint.mjs`
+- `SIMULATE_AUD_DROP=true` on `run-aud-presence-check.mjs`
+
+Real-account probes need `CI_HAS_CLOUDFLARE_ACCOUNT=true` and
+`CI_HAS_HETZNER_ACCOUNT=true` (plus `CI_HAS_CLOUDFLARE_ACCESS=true` for
+the gated sub-case per the round-7 Q4 ratification):
+
+```
+CI_HAS_CLOUDFLARE_ACCOUNT=true CI_HAS_HETZNER_ACCOUNT=true \
+  node ./run-real-account-connector-healthy.mjs
+CI_HAS_CLOUDFLARE_ACCOUNT=true CI_HAS_HETZNER_ACCOUNT=true CI_HAS_CLOUDFLARE_ACCESS=true \
+  node ./run-real-account-tunnel-hostname-routes.mjs
+```
+
+Without the env vars the probes record `accountBoundSkipped: true` and
+the aggregate flips to pass.
+
+## Standards trace
+
+- Cloudflare Tunnel overview: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
+- Get-started with Tunnel: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/
+- cloudflared downloads: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
+- Routing to a tunnel: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/routing-to-tunnel/
+- Local configuration file: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/local-management/configuration-file/
+- cloudflared as-a-service: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/install-and-setup/tunnel-guide/local/as-a-service/
+- Self-hosted app in front of a tunnel (Access): https://developers.cloudflare.com/cloudflare-one/applications/configure-apps/self-hosted-public-app/
+- Cloudflare Access policies: https://developers.cloudflare.com/cloudflare-one/policies/access/

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

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `edge-cloudflare-turnstile` are recorded here. The shape follows Keep a Changelog and Semantic Versioning per the blueprint authoring standard.
+
+## 1.0.0 (2026-09-07)
+
+### Added
+
+- v1.0.0 mint of the `edge-cloudflare-turnstile` blueprint, category `edge`, capabilities `["humanCheck"]`. Ships a client widget mount, a server-side siteverify verifier that POSTs to `https://challenges.cloudflare.com/turnstile/v0/siteverify` with the elicited secret, a refuse-if-token-missing guard on every elicited surface, and a composition hook into `security-auth-magic-link` mint surface.
+- 5 REQs (`edge-cloudflare-turnstile-REQ-001..005`), 8 USs (`edge-cloudflare-turnstile-US-35101..35108`), 3 TACs (`TAC-3601` widget mount, `TAC-3602` server verifier plus token-required guard, `TAC-3603` magic-link hook), 3 ADRs (`ADR-3601` scope-global on new topic `humanVerificationGate` with `standardsTraceClause: Cloudflare Turnstile siteverify endpoint documented shape`; `ADR-3602` widget mode enum elicit with `recommendedDefault: managed`; `ADR-3603` refuse shape 400 with error-code body and no sitekey leak).
+- 4 Node-only probes under `contributions/probes/`: `secret-shape-scan` (source-tree AST scan asserts `TURNSTILE_SECRET` is only read through the env facade and refuses non-test secret literals), `siteverify-fixture` (drives the LIVE `challenges.cloudflare.com/turnstile/v0/siteverify` endpoint with the pinned always-pass and always-fail Cloudflare test secrets and asserts `success:true` and `success:false` respectively), `guard-shape-scan` (source scan plus live missing-token POST against every guarded surface), `event-secrecy` (asserts every event record carries `{sitekeyHash, outcome, timestamp}` keys only; no token, no secret leak).
+- 1 Playwright probe pack (`probe-packs/edge-cloudflare-turnstile.pack.mjs`) with 4 surface-observable checks per spec section 3.2: `AC-turnstile-widgetRendered` (widget mounts, iframe/script from the Cloudflare Turnstile origin only, `cf-turnstile-response` token populated, no third-party script), `AC-turnstile-serverVerified-pass` (`/api/submit` 200 on always-pass secret), `AC-turnstile-serverVerified-fail` (`/api/submit` 400 on always-fail secret with `errorCodes` and no sitekey leak), `AC-turnstile-magicLinkGuard` (mint refuses missing-token and always-fail-secret with 400 and no mint side-effect).
+- 4 elicited parameters on `blueprint.json`: `turnstile-sitekey`, `turnstile-secret` (routed through `security-secrets-management` when applied), `turnstile-widget-mode` (enum default `managed`), `turnstile-guarded-surfaces`.
+- `suggestedCompanions`: `logging` (for the metadata-only event sink retention), `errorHandling` (for the verifier failure boundary), `secretsManagement` (for the paired sitekey and secret).
+- Ships the dedicated pack fixture at `packages/rcf-lite/test/fixtures/probe-pack-edge-cloudflare-turnstile/` per spec section 3.3. The fixture pins the Cloudflare public test keys documented at `https://developers.cloudflare.com/turnstile/troubleshooting/testing/` as environment defaults so the pack runs without real Turnstile credentials.
+- Anatomy test at `packages/rcf-lite/test/blueprint/edge-cloudflare-turnstile-anatomy.test.js` covers TS-120..127 on the T-5 repo-chain slice.
+
+### Known limitations
+
+- No account-bound probe. Cloudflare Turnstile documents its endpoint and test keys as public; the live siteverify calls in the shipped probes route through Cloudflare with no operator account required. A real-account variant would gate on a specific applying-project sitekey and secret pair; the shipped test-key runs cover the wire-shape contract.

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

@@ -0,0 +1,95 @@
+# edge-cloudflare-turnstile
+
+Cloudflare Turnstile as a CAPTCHA-alternative on public-facing forms. Ships the client widget mount, the server-side siteverify verifier (POST to `https://challenges.cloudflare.com/turnstile/v0/siteverify` with the elicited secret), a refuse-if-token-missing guard on every elicited surface, and a composition hook into the `security-auth-magic-link` mint surface.
+
+- Slug: `edge-cloudflare-turnstile`
+- Category: `edge`
+- Version: `1.0.0`
+- Capabilities: `["humanCheck"]`
+- Standards: Cloudflare Turnstile (`https://developers.cloudflare.com/turnstile/`), Cloudflare Turnstile testing (`https://developers.cloudflare.com/turnstile/troubleshooting/testing/`)
+
+## What this blueprint commits
+
+| REQ | Commits |
+|---|---|
+| `edge-cloudflare-turnstile-REQ-001` | Client widget mount: the elicited sitekey renders the Turnstile widget; the mount injects no third-party script beyond the Cloudflare Turnstile JS host. |
+| `edge-cloudflare-turnstile-REQ-002` | Server-side siteverify: POST to `https://challenges.cloudflare.com/turnstile/v0/siteverify` with the elicited secret; on `success:true` the handler proceeds; on `success:false` the handler rejects with 400. |
+| `edge-cloudflare-turnstile-REQ-003` | Refuse-if-token-missing guard on elicited surfaces: a submit without a token rejects with 400 before hitting downstream logic. |
+| `edge-cloudflare-turnstile-REQ-004` | Composition with `security-auth-magic-link`: when both are applied, the magic-link mint surface refuses a submit without a valid Turnstile token. |
+| `edge-cloudflare-turnstile-REQ-005` | Widget mode is an elicited enum: `managed`, `non-interactive`, `invisible` per Cloudflare's documented modes. `recommendedDefault: managed`. |
+
+## Contract at a glance
+
+- **Client widget mount** (TAC-3601) injects Cloudflare Turnstile JS from `https://challenges.cloudflare.com` and no other origin; renders the widget for the elicited sitekey; populates the hidden `Cf-Turnstile-Response` token field on submit.
+- **Server-side siteverify verifier** (TAC-3602) POSTs `{secret, response}` to `https://challenges.cloudflare.com/turnstile/v0/siteverify`. On `success:true` the handler proceeds. On `success:false` the handler rejects with 400 and the refusal body carries the documented `error-codes` value; the sitekey is never in the refusal body.
+- **Refuse-if-token-missing guard** (TAC-3602) is the sole reader of the `Cf-Turnstile-Response` payload field; a submit without a token rejects with `400 {"errorCode":"turnstile.token-missing"}` before any downstream handler runs.
+- **Composition with security-auth-magic-link** (TAC-3603) registers the magic-link mint route under the Turnstile guard so a mint submit reads through the same token check.
+- **Widget mode** (ADR-3602) is an elicited enum: `managed`, `non-interactive`, `invisible`. Default: `managed`.
+
+## Elicited parameters
+
+| Id | Purpose |
+|---|---|
+| `turnstile-sitekey` | Cloudflare Turnstile sitekey the widget renders with. Public per Cloudflare's testing docs when a test sitekey is applied. |
+| `turnstile-secret` | Cloudflare Turnstile secret the server-side verifier POSTs with. Delegated to `security-secrets-management` when applied. |
+| `turnstile-widget-mode` | Enum `managed` \| `non-interactive` \| `invisible`. `recommendedDefault: managed`. |
+| `turnstile-guarded-surfaces` | List of applied route ids the token-required guard registers on. |
+
+## Companions
+
+- **`suggestedCompanions[logging]`**: every siteverify call and every refuse-if-token-missing rejection writes through the applied logger.
+- **`suggestedCompanions[errorHandling]`**: siteverify network failure, malformed token, missing sitekey/secret build an internal error record.
+- **`suggestedCompanions[secretsManagement]`**: the paired sitekey and secret are stored in the operator's applied `secretsManagement` companion.
+
+## Composition
+
+- Consumes `security-secrets-management` for the sitekey/secret pair when applied.
+- Composes with `security-auth-magic-link` at the mint surface via `TAC-3603`.
+- Provides capability `humanCheck` per section 6a of `blueprint-authoring.md`.
+- One scope-global ADR (`ADR-3601`) on new topic `humanVerificationGate`. A future hCaptcha or reCAPTCHA sibling contributes the same topic string with a different answer and forces a deliberate operator-resolved conflict.
+
+## Probes and pack
+
+Four Node-only probes under `contributions/probes/`:
+
+| Probe | Anchors | Engine |
+|---|---|---|
+| `secret-shape-scan` | `AC-35107-1` | Source-tree AST scan over the pack fixture. |
+| `siteverify-fixture` | `AC-35102-1` | Live POST to `https://challenges.cloudflare.com/turnstile/v0/siteverify` with pinned Cloudflare public test secrets. |
+| `guard-shape-scan` | `AC-35104-1` | Source-tree scan plus a live missing-token POST against every guarded surface. |
+| `event-secrecy` | `AC-35108-1` | Live pass + fail runs through the verifier; asserts every event carries `sitekeyHash`, `outcome`, `timestamp` and no token or secret substring. |
+
+One Playwright pack at `probe-packs/edge-cloudflare-turnstile.pack.mjs` with four surface-observable checks: `AC-turnstile-widgetRendered`, `AC-turnstile-serverVerified-pass`, `AC-turnstile-serverVerified-fail`, `AC-turnstile-magicLinkGuard`. The pack ships no `appliesTo` gate; every fixture that applies the blueprint fires every check.
+
+The dedicated pack fixture at `packages/rcf-lite/test/fixtures/probe-pack-edge-cloudflare-turnstile/` pins the Cloudflare public test keys (documented at `https://developers.cloudflare.com/turnstile/troubleshooting/testing/`) as environment defaults so the pack runs without real Turnstile credentials.
+
+## Pinned Cloudflare public test keys
+
+Per Cloudflare's testing page (`https://developers.cloudflare.com/turnstile/troubleshooting/testing/`):
+
+| Sitekey | Behaviour |
+|---|---|
+| `1x00000000000000000000AA` | Always passes |
+| `2x00000000000000000000AB` | Always blocks |
+| `3x00000000000000000000FF` | Forces an interactive challenge |
+| `1x00000000000000000000BB` | Invisible widget, always passes |
+| `2x00000000000000000000BB` | Invisible widget, always blocks |
+
+| Secret | Behaviour |
+|---|---|
+| `1x0000000000000000000000000000000AA` | Always passes on siteverify |
+| `2x0000000000000000000000000000000AA` | Always fails on siteverify |
+| `3x0000000000000000000000000000000AA` | Token already spent |
+
+These keys are public per Cloudflare's documentation; they are safe to pin as fixture defaults and are not operational secrets.
+
+## Risks
+
+1. Client-side widget mounts a third-party script. The `AC-turnstile-widgetRendered` pack check pins the mount to `https://challenges.cloudflare.com` only and fails if any other origin is contacted (see the `?break=other-origin` negative proof in the fixture `proof/` directory).
+2. Test sitekeys are the only always-green option for CI. The guide names the pass, block and forced-interactive modes per Cloudflare's testing page so an operator can pick a mode for staging.
+
+## Standards trace
+
+- Cloudflare Turnstile: `https://developers.cloudflare.com/turnstile/`
+- Cloudflare Turnstile testing: `https://developers.cloudflare.com/turnstile/troubleshooting/testing/`
+- Cloudflare Turnstile siteverify endpoint: `https://challenges.cloudflare.com/turnstile/v0/siteverify`