rcf-lite 0.23.0 → 0.25.0

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

@@ -0,0 +1,231 @@
+// Shared helpers for edge-cloudflare-tunnel probes (round-7 T-3).
+//
+// Runtime-dependency posture:
+// - manifest-schema-validate is dependency-free: it reads yaml text and
+//   walks the parsed document. The tunnel manifest schema ships at
+//   ./tunnel-manifest.schema.json.
+// - cloudflared-config-lint shells to cloudflared tunnel ingress validate.
+//   When a local cloudflared binary is on PATH the probe uses it; when it
+//   is not, the probe runs the vendor container image
+//   cloudflare/cloudflared:2026.8.3 via docker run --rm -v <dir>:/etc/cloudflared:ro
+//   per the vendor downloads page. When neither is available the probe
+//   records warn (source-tree assertions still run).
+// - aud-presence-check reads a sidecar JSON and the paired tunnel yaml;
+//   dependency-free.
+// - real-account-* probes shell to cloudflared tunnel info / undici curl
+//   against a scratch subdomain on a real Cloudflare account; without
+//   CI_HAS_CLOUDFLARE_ACCOUNT AND CI_HAS_HETZNER_ACCOUNT they record
+//   accountBoundSkipped: true and the aggregate flips to pass per
+//   hetzner-round-7-spec section 3.5.
+//
+// FIXTURE_ROOT posture:
+// - The fixture-side delegate shims under
+//   packages/rcf-lite/test/fixtures/hetzner-throwaway-server/run-<probe>.mjs
+//   set RCF_LITE_T3_FIXTURE_ROOT to a scratch directory when a mutation
+//   switch is on. The probe modules NEVER read a fixture-side mutation env var and
+//   NEVER branch on being under mutation; their verdict is a pure
+//   function of the files at FIXTURE_ROOT.
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+
+// Fixture root defaults to the shared throwaway-server fixture cloudflared/
+// sub-directory. A fixture-side delegate that needs to inject a mutation
+// copies the sub-tree to a scratch dir and points FIXTURE_ROOT at it.
+export const CANONICAL_FIXTURE_ROOT = resolve(
+  PROJECT_ROOT,
+  'packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared',
+);
+export function fixtureRoot() {
+  return process.env.RCF_LITE_T3_FIXTURE_ROOT
+    ? resolve(process.env.RCF_LITE_T3_FIXTURE_ROOT)
+    : CANONICAL_FIXTURE_ROOT;
+}
+export const REPORT_DIR = resolve(
+  PROJECT_ROOT,
+  '.rcf/reports/blueprints/edge-cloudflare-tunnel',
+);
+
+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 function isSkipped(results) {
+  return results.length > 0 && results.every((r) => r.accountBoundSkipped === true);
+}
+
+export async function writeReport({ probeName, engine, results, extra }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const rawVerdict = aggregate(results);
+  const aggregateVerdict = isSkipped(results) ? 'pass' : rawVerdict;
+  const report = {
+    slug: 'edge-cloudflare-tunnel',
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict,
+    ...(extra ?? {}),
+  };
+  // Strip absolute builder scratchpad paths from persisted reports so
+  // the committed envelopes stay repo-relative and diff cleanly. Walks
+  // every string in the report and rewrites PROJECT_ROOT-prefixed paths
+  // to their repo-relative form (covers report.fixtureRoot, results[].detail,
+  // extra.* and any nested string value future probes surface).
+  const prefix = PROJECT_ROOT + '/';
+  function stripPaths(node) {
+    if (typeof node === 'string') {
+      if (node === PROJECT_ROOT) return '.';
+      return node.split(prefix).join('');
+    }
+    if (Array.isArray(node)) return node.map(stripPaths);
+    if (node && typeof node === 'object') {
+      const out = {};
+      for (const [k, v] of Object.entries(node)) out[k] = stripPaths(v);
+      return out;
+    }
+    return node;
+  }
+  Object.assign(report, stripPaths(report));
+  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 outcome = (await mainFn()) ?? { results: [] };
+    const { results, extra } = outcome;
+    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 function accountBoundSkippedResult(anchorAcId, envList, note) {
+  return {
+    anchorAcId,
+    verdict: 'skipped',
+    accountBoundSkipped: true,
+    detail: `accountBound: ${envList.join(' or ')} unset; ${note}`,
+  };
+}
+
+// Minimal yaml subset parser tuned for the tunnel manifest shape.
+// The fixture manifests are intentionally simple: no anchors, no flow-style
+// scalars, two-space indent. The parser produces a shape sufficient for
+// the ACs (tunnel id string, credentialsFile.secretRef, ingress array of
+// {hostname?, service, originRequest?.access.aud?}).
+export function parseTunnelYaml(text) {
+  const doc = {};
+  const lines = text.split(/\r?\n/);
+  const stack = [{ indent: -1, node: doc }];
+  const kvRe = /^([A-Za-z0-9_.-]+):\s*(.*)$/;
+  function decode(raw) {
+    if (raw === '' || raw === undefined) return null;
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+    if (raw === 'null' || raw === '~') return null;
+    return raw.replace(/^"([^"\\]*)"$/, '$1').replace(/^'([^'\\]*)'$/, '$1');
+  }
+  for (let idx = 0; idx < lines.length; idx += 1) {
+    const raw = lines[idx];
+    if (raw.trim() === '' || raw.trim().startsWith('#')) continue;
+    const indentM = raw.match(/^(\s*)/);
+    const indent = indentM ? indentM[1].length : 0;
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+    const parent = stack[stack.length - 1].node;
+    const body = raw.slice(indent);
+    if (body.startsWith('- ')) {
+      const rest = body.slice(2);
+      const kv = rest.match(kvRe);
+      if (kv) {
+        const [, key, val] = kv;
+        const obj = {};
+        if (val === '') {
+          const child = {};
+          obj[key] = child;
+          parent.push(obj);
+          stack.push({ indent, node: obj });
+          stack.push({ indent: indent + 2, node: child });
+        } else {
+          obj[key] = decode(val.trim());
+          parent.push(obj);
+          stack.push({ indent, node: obj });
+        }
+      } else {
+        parent.push(decode(rest.trim()));
+      }
+      continue;
+    }
+    const kv = body.match(kvRe);
+    if (!kv) continue;
+    const [, key, val] = kv;
+    if (val === '') {
+      let peekIsList = false;
+      for (let j = idx + 1; j < lines.length; j += 1) {
+        const nxt = lines[j];
+        if (!nxt || nxt.trim() === '' || nxt.trim().startsWith('#')) continue;
+        const nxtIndentM = nxt.match(/^(\s*)/);
+        const nxtIndent = nxtIndentM ? nxtIndentM[1].length : 0;
+        if (nxtIndent <= indent) break;
+        peekIsList = nxt.slice(nxtIndent).startsWith('- ');
+        break;
+      }
+      const child = peekIsList ? [] : {};
+      parent[key] = child;
+      stack.push({ indent, node: child });
+    } else {
+      parent[key] = decode(val.trim());
+    }
+  }
+  return doc;
+}
+
+export function whichDocker() {
+  const r = spawnSync('docker', ['version', '--format', '{{.Client.Version}}'], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+}
+
+export function whichCloudflared() {
+  const r = spawnSync('cloudflared', ['--version'], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+}
+
+export const CLOUDFLARED_IMAGE = 'cloudflare/cloudflared:2026.8.3';
+
+// Two dimensions: connector runtime (compose-service or systemd-unit) and
+// hostname mode (public-hostname or access-gated). Every combination
+// ships one manifest under cloudflared/<runtime>/cloudflare/tunnels/<mode>.yaml.
+export const RUNTIMES = ['compose-service', 'systemd-unit'];
+export const HOSTNAME_MODES = ['public-hostname', 'access-gated'];
+export function pairs() {
+  const list = [];
+  for (const runtime of RUNTIMES) {
+    for (const mode of HOSTNAME_MODES) list.push({ runtime, mode });
+  }
+  return list;
+}
+
+// Backwards compat name used by the manifest-schema-validate probe: iterate over
+// runtime variants for schema-shape checks (both modes are shape-checked).
+export const VARIANTS = RUNTIMES;

package/blueprints/edge-cloudflare-tunnel/contributions/probes/real-account-connector-healthy.mjs

@@ -0,0 +1,54 @@
+// Probe: real-account-connector-healthy.
+//
+// anchorAcId: AC-tunnel-connectorHealthy.
+// accountBound: true (gates on CI_HAS_CLOUDFLARE_ACCOUNT AND CI_HAS_HETZNER_ACCOUNT).
+//
+// Without both env vars the probe records accountBoundSkipped: true and
+// the aggregate flips to pass per hetzner-round-7-spec section 3.5.
+//
+// With both env vars the probe (not exercised in this dispatch; the
+// blueprint author has no account tokens per the dispatch envelope):
+// - Provisions a throwaway Hetzner server via the shared fixture
+//   provision.mjs (T-1 verb).
+// - Stands up cloudflared against a scratch Cloudflare subdomain and asks
+//   the api for `cloudflared tunnel info <name>`; asserts at least one
+//   healthy connector.
+// - Captures a tunnelConnectorUp event with connector id, region and
+//   version metadata (metadata only).
+// - Tears down via destroy.mjs in an always() block.
+
+import { runShim, accountBoundSkippedResult } from './probe-utils.mjs';
+
+export const anchorAcIds = ['AC-tunnel-connectorHealthy'];
+export const accountBound = true;
+
+export default async function runProbe() {
+  const results = [];
+  const extra = {
+    envRequired: ['CI_HAS_CLOUDFLARE_ACCOUNT', 'CI_HAS_HETZNER_ACCOUNT'],
+    envPresent: {
+      CI_HAS_CLOUDFLARE_ACCOUNT: process.env.CI_HAS_CLOUDFLARE_ACCOUNT === 'true',
+      CI_HAS_HETZNER_ACCOUNT: process.env.CI_HAS_HETZNER_ACCOUNT === 'true',
+    },
+  };
+  const hasAll = extra.envPresent.CI_HAS_CLOUDFLARE_ACCOUNT && extra.envPresent.CI_HAS_HETZNER_ACCOUNT;
+  if (!hasAll) {
+    results.push(accountBoundSkippedResult(
+      'AC-tunnel-connectorHealthy',
+      ['CI_HAS_CLOUDFLARE_ACCOUNT', 'CI_HAS_HETZNER_ACCOUNT'],
+      'real-account cloudflared tunnel info + tunnelConnectorUp capture not exercised. Set CI_HAS_CLOUDFLARE_ACCOUNT=true AND CI_HAS_HETZNER_ACCOUNT=true (with HCLOUD_TOKEN and CLOUDFLARE_API_TOKEN in the environment via security-secrets-management) to run the real-account path.',
+    ));
+    return { results, extra };
+  }
+  results.push({
+    anchorAcId: 'AC-tunnel-connectorHealthy',
+    verdict: 'warn',
+    detail: 'account-bound path present in this dispatch environment but not exercised by the blueprint-author role; run under the delivery-ci-workflows lane with the account tokens loaded.',
+  });
+  return { results, extra };
+}
+
+const engine = { kind: 'real-account-cloudflared-info', image: 'cloudflared + hcloud (throwaway server)', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('real-account-connector-healthy', engine, runProbe);
+}

package/blueprints/edge-cloudflare-tunnel/contributions/probes/real-account-tunnel-hostname-routes.mjs

@@ -0,0 +1,73 @@
+// Probe: real-account-tunnel-hostname-routes.
+//
+// anchorAcId list:
+// - AC-tunnel-hostnameRoutes (public-hostname sub-case)
+// - AC-tunnel-accessGated (access-gated sub-case, gated on CI_HAS_CLOUDFLARE_ACCESS)
+// accountBound: true (CI_HAS_CLOUDFLARE_ACCOUNT AND CI_HAS_HETZNER_ACCOUNT for
+// the public-hostname sub-case; add CI_HAS_CLOUDFLARE_ACCESS for the
+// access-gated sub-case per Q4 ratification).
+//
+// Without the env vars the sub-cases skip independently and each records
+// accountBoundSkipped: true. The aggregate flips to pass per hetzner-
+// round-7-spec section 3.5.
+//
+// With the env vars (not exercised in this dispatch; the blueprint
+// author has no account tokens per the dispatch envelope):
+// - Public-hostname sub-case: undici curl against the scratch subdomain,
+//   asserts 200 and the internal service payload.
+// - Access-gated sub-case: two fixture identities; the JWT-less request
+//   is refused at the edge; the JWT-carrying request proceeds.
+
+import { runShim, accountBoundSkippedResult } from './probe-utils.mjs';
+
+export const anchorAcIds = ['AC-tunnel-hostnameRoutes', 'AC-tunnel-accessGated'];
+export const accountBound = true;
+
+export default async function runProbe() {
+  const results = [];
+  const extra = {
+    envRequired: {
+      publicHostname: ['CI_HAS_CLOUDFLARE_ACCOUNT', 'CI_HAS_HETZNER_ACCOUNT'],
+      accessGated: ['CI_HAS_CLOUDFLARE_ACCOUNT', 'CI_HAS_HETZNER_ACCOUNT', 'CI_HAS_CLOUDFLARE_ACCESS'],
+    },
+    envPresent: {
+      CI_HAS_CLOUDFLARE_ACCOUNT: process.env.CI_HAS_CLOUDFLARE_ACCOUNT === 'true',
+      CI_HAS_HETZNER_ACCOUNT: process.env.CI_HAS_HETZNER_ACCOUNT === 'true',
+      CI_HAS_CLOUDFLARE_ACCESS: process.env.CI_HAS_CLOUDFLARE_ACCESS === 'true',
+    },
+  };
+  const hasPublic = extra.envPresent.CI_HAS_CLOUDFLARE_ACCOUNT && extra.envPresent.CI_HAS_HETZNER_ACCOUNT;
+  const hasGated = hasPublic && extra.envPresent.CI_HAS_CLOUDFLARE_ACCESS;
+  if (!hasPublic) {
+    results.push(accountBoundSkippedResult(
+      'AC-tunnel-hostnameRoutes',
+      ['CI_HAS_CLOUDFLARE_ACCOUNT', 'CI_HAS_HETZNER_ACCOUNT'],
+      'public-hostname sub-case: undici curl against the scratch subdomain not exercised. Set CI_HAS_CLOUDFLARE_ACCOUNT=true AND CI_HAS_HETZNER_ACCOUNT=true to run this path.',
+    ));
+  } else {
+    results.push({
+      anchorAcId: 'AC-tunnel-hostnameRoutes',
+      verdict: 'warn',
+      detail: 'public-hostname sub-case: account-bound path present but not exercised by the blueprint-author role; run under the delivery-ci-workflows lane.',
+    });
+  }
+  if (!hasGated) {
+    results.push(accountBoundSkippedResult(
+      'AC-tunnel-accessGated',
+      ['CI_HAS_CLOUDFLARE_ACCOUNT', 'CI_HAS_HETZNER_ACCOUNT', 'CI_HAS_CLOUDFLARE_ACCESS'],
+      'access-gated sub-case: two-identity JWT check against the scratch subdomain not exercised. Requires all three env vars (CI_HAS_CLOUDFLARE_ACCESS added per Q4 ratification).',
+    ));
+  } else {
+    results.push({
+      anchorAcId: 'AC-tunnel-accessGated',
+      verdict: 'warn',
+      detail: 'access-gated sub-case: account-bound path present but not exercised by the blueprint-author role; run under the delivery-ci-workflows lane.',
+    });
+  }
+  return { results, extra };
+}
+
+const engine = { kind: 'real-account-tunnel-curl', image: 'undici + cloudflared (scratch subdomain)', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('real-account-tunnel-hostname-routes', engine, runProbe);
+}

package/blueprints/edge-cloudflare-tunnel/contributions/probes/run-aud-presence-check.mjs

@@ -0,0 +1,4 @@
+import runProbe from './aud-presence-check.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'sidecar-read', image: 'edge-cloudflare-tunnel aud-presence facade', healthy: true };
+runShim('aud-presence-check', engine, runProbe);

package/blueprints/edge-cloudflare-tunnel/contributions/probes/run-cloudflared-config-lint.mjs

@@ -0,0 +1,4 @@
+import runProbe from './cloudflared-config-lint.mjs';
+import { runShim, CLOUDFLARED_IMAGE } from './probe-utils.mjs';
+const engine = { kind: 'cloudflared-ingress-validate', image: CLOUDFLARED_IMAGE, healthy: true };
+runShim('cloudflared-config-lint', engine, runProbe);

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

@@ -0,0 +1,4 @@
+import runProbe from './manifest-schema-validate.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'schema-validate', image: 'edge-cloudflare-tunnel manifest schema (Ajv-free walker)', healthy: true };
+runShim('manifest-schema-validate', engine, runProbe);

package/blueprints/edge-cloudflare-tunnel/contributions/probes/run-real-account-connector-healthy.mjs

@@ -0,0 +1,4 @@
+import runProbe from './real-account-connector-healthy.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'real-account-connector-healthy', image: 'account-bound', healthy: true };
+runShim('real-account-connector-healthy', engine, runProbe);

package/blueprints/edge-cloudflare-tunnel/contributions/probes/run-real-account-tunnel-hostname-routes.mjs

@@ -0,0 +1,4 @@
+import runProbe from './real-account-tunnel-hostname-routes.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'real-account-tunnel-hostname-routes', image: 'account-bound', healthy: true };
+runShim('real-account-tunnel-hostname-routes', engine, runProbe);

package/blueprints/edge-cloudflare-tunnel/contributions/probes/tunnel-manifest.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stravica.ai/schemas/edge-cloudflare-tunnel/tunnel-manifest.v1.json",
+  "title": "edge-cloudflare-tunnel tunnel manifest v1.0.0",
+  "type": "object",
+  "required": ["tunnel", "credentialsFile", "ingress"],
+  "additionalProperties": false,
+  "properties": {
+    "tunnel": {
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+      "description": "uuid-shaped Cloudflare Tunnel id per the vendor tunnel primitive"
+    },
+    "credentialsFile": {
+      "type": "object",
+      "required": ["secretRef"],
+      "additionalProperties": false,
+      "properties": {
+        "secretRef": {
+          "type": "string",
+          "minLength": 1,
+          "description": "security-secrets-management reference to the credentials JSON; never a literal path or JSON body"
+        }
+      }
+    },
+    "ingress": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "hostname": { "type": "string", "minLength": 1 },
+          "service": { "type": "string", "minLength": 1 },
+          "originRequest": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "access": {
+                "type": "object",
+                "required": ["aud"],
+                "properties": {
+                  "aud": { "type": "string", "minLength": 1 },
+                  "teamName": { "type": "string" },
+                  "required": { "type": "boolean" }
+                }
+              }
+            }
+          }
+        },
+        "required": ["service"]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "edge-cloudflare-tunnel-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Connector install shape switches on applied containerHost (compose-service default; systemd-unit for bare cloudHost); cloudflaredReady fires on boot",
+  "description": "The blueprint contributes a cloudflared connector whose runtime shape is elicited via ADR-4002 with enum {compose-service, systemd-unit} and recommendedDefault compose-service. When containerHost is applied (T-2 platform-docker-compose-host on top of T-1 deploy-hetzner-server) the connector ships as a compose service alongside the applying project services on the same web-net network. When the host runs bare (only T-1 applied) the connector ships as a systemd unit per the vendor local-configuration-file docs. Either shape emits cloudflaredReady on boot with connector id, region and version metadata (metadata only; no token or credentials in the payload).",
+  "category": "functional",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.3 edge-cloudflare-tunnel-REQ-001). Ships as v1.0.0 of edge-cloudflare-tunnel.",
+  "tags": [
+    "blueprint:edge-cloudflare-tunnel",
+    "capability:tunnelBridge"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "edge-cloudflare-tunnel-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Tunnel manifest schema at cloudflare/tunnels/<name>.yaml under the applying project (uuid tunnel id, secretRef credentials, ingress rules with catch-all 404)",
+  "description": "The applying project ships one tunnel manifest per named tunnel at cloudflare/tunnels/<name>.yaml. The shipped JSON schema requires a uuid-shaped tunnel id, a credentials-file reference into security-secrets-management (secretRef, never a literal path or JSON body inline), and an ingress rules array whose last entry is a mandatory catch-all rule returning http_status 404. cloudflared refuses to boot when the manifest fails validation.",
+  "category": "functional",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.3 edge-cloudflare-tunnel-REQ-002). Ships as v1.0.0 of edge-cloudflare-tunnel.",
+  "tags": [
+    "blueprint:edge-cloudflare-tunnel",
+    "capability:tunnelBridge"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "edge-cloudflare-tunnel-REQ-003",
+  "prdId": "PRD-001",
+  "title": "No public origin ports on the host (T-1 firewall stays 22 open plus 80/443 only when a reverse proxy is applied; manifest refuses an origin-port request)",
+  "description": "The applying project MUST NOT open a public port on the host firewall for the origin path when only edge-cloudflare-tunnel provides ingress. T-1 deploy-hetzner-server firewall 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 manifest schema refuses ingress rules whose service URL binds to a host public interface.",
+  "category": "functional",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.3 edge-cloudflare-tunnel-REQ-003). Ships as v1.0.0 of edge-cloudflare-tunnel.",
+  "tags": [
+    "blueprint:edge-cloudflare-tunnel",
+    "capability:tunnelBridge"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "edge-cloudflare-tunnel-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Access-gated composition: when zeroTrustGate is applied, ingress rules attach originRequest.access.aud; when absent, block omitted and tunnel serves in public-hostname mode",
+  "description": "The blueprint reads the applying project sidecar rcf/blueprints/edge-cloudflare-tunnel.applied.json at apply time and inspects appliedCapabilities. When zeroTrustGate is present every ingress rule attaches an originRequest.access block naming the Access AUD; 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. The aud-presence-check probe refuses if the shape drifts to open ingress on a project that intended the gated shape.",
+  "category": "functional",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.3 edge-cloudflare-tunnel-REQ-004). Ships as v1.0.0 of edge-cloudflare-tunnel.",
+  "tags": [
+    "blueprint:edge-cloudflare-tunnel",
+    "capability:tunnelBridge"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "edge-cloudflare-tunnel-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Credentials-file discipline: JSON at mode 0o400, referenced via secretRef, not committed, grep-refuse on the literal, no leak in event bodies",
+  "description": "The tunnel credentials JSON file lands on the host at mode 0o400 (owner read only), is referenced from the manifest as a secretRef (never a literal committed file body), MUST NOT be committed to the applying project tree (grep-refuse on the tunnel id and account tag literals across the working tree), and MUST NOT appear in any cloudflaredReady, tunnelConnectorUp or ingressRuleReloaded event body.",
+  "category": "functional",
+  "domain": "edge",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.3 edge-cloudflare-tunnel-REQ-005). Ships as v1.0.0 of edge-cloudflare-tunnel.",
+  "tags": [
+    "blueprint:edge-cloudflare-tunnel",
+    "capability:tunnelBridge"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/tacs/tac-4001-edge-cloudflare-tunnel-connector-shape.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-4001-edge-cloudflare-tunnel-connector-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Edge-cloudflare-tunnel connector install shape",
+  "purpose": "The cloudflared connector installs in one of two runtime shapes as selected by ADR-4002 from the applied capability set. When containerHost is applied (T-2 platform-docker-compose-host on top of T-1 deploy-hetzner-server) the connector ships as a compose service alongside the applying project services on the same web-net network with no host ports and a healthcheck. When the host runs bare (only T-1 applied) the connector ships as a systemd unit per the vendor local-configuration-file docs. Either shape emits cloudflaredReady on boot with connector id, region and version metadata (metadata only).",
+  "responsibilities": [
+    "Ship the compose-service variant under packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/compose-service/ (AC-tunnel-connectorShape).",
+    "Ship the systemd-unit variant under packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/systemd-unit/ (AC-tunnel-connectorShape).",
+    "Emit cloudflaredReady on boot with connector id, region and version metadata (AC-tunnel-connectorHealthy).",
+    "Never expose an origin port on the host firewall (AC-tunnel-noPublicOrigin)."
+  ],
+  "internalStructure": "One module discovering the applied fixture root and returning both variant paths; consumers walk the compose fragment or the systemd unit file per the applied capability set.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "facade",
+      "summary": "Connector shape discovery facade exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/tacs/tac-4002-edge-cloudflare-tunnel-manifest-schema.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-4002-edge-cloudflare-tunnel-manifest-schema",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Edge-cloudflare-tunnel manifest schema",
+  "purpose": "The tunnel manifest at cloudflare/tunnels/<name>.yaml under the applying project is the sole runtime source of truth for what the cloudflared connector serves. The shipped JSON schema requires a uuid-shaped tunnel id, a secretRef credentials reference (never a literal path or JSON body inline), and an ingress rules array whose last entry is a catch-all rule returning http_status 404. The schema refuses ingress rules whose service URL binds to a host public interface.",
+  "responsibilities": [
+    "Ship the JSON schema at contributions/probes/tunnel-manifest.schema.json (AC-tunnel-manifestSchema).",
+    "Validate the fixture manifests at cloudflared/*/cloudflare/tunnels/*.yaml on every reviewer boot (AC-tunnel-manifestSchema, AC-tunnel-hostnameRoutes).",
+    "Refuse ingress rules that bind to a host public port (AC-tunnel-noPublicOrigin).",
+    "Refuse a manifest whose credentials reference is not a secretRef (AC-tunnel-manifestSchema, AC-tunnel-credentialsDiscipline)."
+  ],
+  "internalStructure": "One JSON schema plus one probe module; the probe reads the resolved fixture root from env (defaulted to the canonical fixture path) and validates every tunnel yaml against the schema.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "facade",
+      "summary": "Manifest schema-validate facade exported from the blueprint probe module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/edge-cloudflare-tunnel/contributions/tacs/tac-4003-edge-cloudflare-tunnel-access-binding.json

@@ -0,0 +1,25 @@
+{
+  "tacId": "TAC-4003-edge-cloudflare-tunnel-access-binding",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Edge-cloudflare-tunnel Access AUD binding",
+  "purpose": "The blueprint reads the applying project sidecar rcf/blueprints/edge-cloudflare-tunnel.applied.json at apply time and inspects appliedCapabilities. When zeroTrustGate is present every ingress rule attaches an originRequest.access.aud block naming the Access AUD; when absent the block is omitted and the tunnel serves in public-hostname mode. The shape is a pure function of the sidecar and never silently degrades to open ingress.",
+  "responsibilities": [
+    "Ship the aud-presence-check probe module (AC-tunnel-accessGated, AC-tunnel-accessGatedRefuse).",
+    "Ship both fixture variants (access-gated and public-hostname) under cloudflared/sidecars/*.applied.json (AC-tunnel-accessGated).",
+    "Refuse when the gated variant drifts to open ingress (AC-tunnel-accessGatedRefuse)."
+  ],
+  "internalStructure": "One probe module reading the sidecar file resolved from the fixture root and validating the ingress shape flips correctly.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "facade",
+      "summary": "AUD-presence-check facade exported from the blueprint probe module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}