rcf-lite 0.24.0 → 0.26.0

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

@@ -0,0 +1,237 @@
+// Probe: manifest-schema-validate.
+//
+// anchorAcId list (multi):
+// - AC-tunnel-manifestSchema (primary)
+// - AC-tunnel-noPublicOrigin (refuses ingress rules whose service URL
+//   binds to a host public interface)
+// - AC-tunnel-credentialsDiscipline (refuses when credentials are inlined
+//   instead of via secretRef; runs an event-secrecy scan on the
+//   fixture credentials placeholder body)
+// accountBound: false.
+//
+// Verdict is a pure function of the files at fixtureRoot() (default: the
+// canonical fixture; a fixture-side delegate points FIXTURE_ROOT at a
+// scratch dir with a mutation applied). The probe module reads no
+// fixture-side mutation env var and does not branch on being under mutation.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runShim, fixtureRoot, parseTunnelYaml, pairs } from './probe-utils.mjs';
+
+export const anchorAcIds = [
+  'AC-tunnel-manifestSchema',
+  'AC-tunnel-noPublicOrigin',
+  'AC-tunnel-credentialsDiscipline',
+];
+export const accountBound = false;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = resolve(HERE, 'tunnel-manifest.schema.json');
+
+function validateAgainstSchema(doc, schema) {
+  // Minimal Ajv-free walker sufficient for this schema. Returns an array
+  // of violation strings.
+  const errors = [];
+  function walk(node, sub, pathHint) {
+    if (sub.type === 'object' && sub.properties) {
+      if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+        errors.push(`${pathHint}: expected object, got ${node === null ? 'null' : Array.isArray(node) ? 'array' : typeof node}`);
+        return;
+      }
+      for (const key of sub.required ?? []) {
+        if (!(key in node)) errors.push(`${pathHint}: missing required field '${key}'`);
+      }
+      if (sub.additionalProperties === false) {
+        for (const key of Object.keys(node)) {
+          if (!(key in (sub.properties ?? {}))) errors.push(`${pathHint}: unknown field '${key}'`);
+        }
+      }
+      for (const [key, subsub] of Object.entries(sub.properties)) {
+        if (key in node) walk(node[key], subsub, `${pathHint}.${key}`);
+      }
+    } else if (sub.type === 'array') {
+      if (!Array.isArray(node)) {
+        errors.push(`${pathHint}: expected array, got ${typeof node}`);
+        return;
+      }
+      if (typeof sub.minItems === 'number' && node.length < sub.minItems) {
+        errors.push(`${pathHint}: expected at least ${sub.minItems} item(s), got ${node.length}`);
+      }
+      if (sub.items) {
+        node.forEach((item, i) => walk(item, sub.items, `${pathHint}[${i}]`));
+      }
+    } else if (sub.type === 'string') {
+      if (typeof node !== 'string') {
+        errors.push(`${pathHint}: expected string, got ${typeof node}`);
+        return;
+      }
+      if (typeof sub.minLength === 'number' && node.length < sub.minLength) {
+        errors.push(`${pathHint}: expected minLength ${sub.minLength}, got ${node.length}`);
+      }
+      if (sub.pattern && !(new RegExp(sub.pattern).test(node))) {
+        errors.push(`${pathHint}: value '${node}' does not match pattern ${sub.pattern}`);
+      }
+    } else if (sub.type === 'boolean') {
+      if (typeof node !== 'boolean') errors.push(`${pathHint}: expected boolean`);
+    }
+  }
+  walk(doc, schema, 'manifest');
+  return errors;
+}
+
+function refuseOriginPortRules(doc) {
+  // A service URL that binds to a host public interface is a policy
+  // violation for a T-3 apply (no reverse proxy). The catch-all
+  // http_status:N is exempt.
+  const violations = [];
+  const rules = Array.isArray(doc.ingress) ? doc.ingress : [];
+  for (let i = 0; i < rules.length; i += 1) {
+    const rule = rules[i] ?? {};
+    const svc = String(rule.service ?? '');
+    if (svc.startsWith('http_status:')) continue;
+    const m = svc.match(/^https?:\/\/([^\/:]+)(:\d+)?(\/.*)?$/);
+    if (!m) {
+      violations.push(`ingress[${i}] service '${svc}' does not match the internal-address shape (expected http(s)://<internal-name>[:port]/...)`);
+      continue;
+    }
+    const host = m[1];
+    if (host === '0.0.0.0' || host === '') {
+      violations.push(`ingress[${i}] service '${svc}' binds to a host public interface (${host || 'empty'}); T-3 requires internal addresses only`);
+      continue;
+    }
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(host) && host !== '127.0.0.1') {
+      violations.push(`ingress[${i}] service '${svc}' binds to a numeric IP that is not loopback; T-3 requires internal names or loopback`);
+    }
+  }
+  return violations;
+}
+
+async function eventSecrecyScan(credentialsPath) {
+  let creds;
+  try {
+    creds = JSON.parse(await readFile(credentialsPath, 'utf8'));
+  } catch (err) {
+    return {
+      verdict: 'fail',
+      detail: `credentials placeholder read failed at ${credentialsPath}: ${err.message}. Fix the fixture setup step (packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/*/credentials/probe.json.example must exist and parse as JSON) before re-running the probe. A missing placeholder is a fixture-setup defect, not an event-secrecy warning.`,
+    };
+  }
+  const eventBody = {
+    kind: 'cloudflaredReady',
+    connectorId: 'sha256:fixture-connector',
+    region: 'fixture-region',
+    version: '2026.8.3',
+    // A fixture-side mutation may seed a _leakedEvent object which the
+    // probe surfaces by including it in the synthetic event body.
+    ...(creds._leakedEvent ?? {}),
+  };
+  const body = JSON.stringify(eventBody);
+  const leaks = [];
+  for (const [k, v] of Object.entries(creds)) {
+    if (k === '_comment' || k === '_leakedEvent') continue;
+    if (typeof v !== 'string' || v.length < 8) continue;
+    if (body.includes(v)) leaks.push(`event body carries credentials.${k} literal`);
+  }
+  if (leaks.length) {
+    return { verdict: 'fail', detail: `event-secrecy scan FAILED: ${leaks.join('; ')}` };
+  }
+  return { verdict: 'pass', detail: 'event-secrecy scan clean; cloudflaredReady body carries metadata only' };
+}
+
+export default async function runProbe() {
+  const results = [];
+  const extra = {};
+  const root = fixtureRoot();
+  extra.fixtureRoot = root;
+  const schema = JSON.parse(await readFile(SCHEMA_PATH, 'utf8'));
+  extra.schemaId = schema.$id;
+  for (const { runtime, mode } of pairs()) {
+    const manifestPath = resolve(root, runtime, 'cloudflare/tunnels', `${mode}.yaml`);
+    let text;
+    try {
+      text = await readFile(manifestPath, 'utf8');
+    } catch (err) {
+      results.push({
+        anchorAcId: 'AC-tunnel-manifestSchema',
+        verdict: 'fail',
+        detail: `${runtime}/${mode}: manifest read failed at ${manifestPath}: ${err.message}`,
+      });
+      continue;
+    }
+    const doc = parseTunnelYaml(text);
+    const schemaErrors = validateAgainstSchema(doc, schema);
+    if (schemaErrors.length) {
+      results.push({
+        anchorAcId: 'AC-tunnel-manifestSchema',
+        verdict: 'fail',
+        detail: `${runtime}/${mode}: schema violation(s): ${schemaErrors.slice(0, 5).join('; ')}${schemaErrors.length > 5 ? ` (+${schemaErrors.length - 5} more)` : ''}`,
+      });
+    } else {
+      results.push({
+        anchorAcId: 'AC-tunnel-manifestSchema',
+        verdict: 'pass',
+        detail: `${runtime}/${mode}: manifest at ${manifestPath} validates against tunnel-manifest.schema.json`,
+      });
+    }
+    const rulesForCatchall = Array.isArray(doc.ingress) ? doc.ingress : [];
+    const lastRule = rulesForCatchall[rulesForCatchall.length - 1];
+    if (!lastRule || typeof lastRule.service !== 'string' || !lastRule.service.startsWith('http_status:')) {
+      results.push({
+        anchorAcId: 'AC-tunnel-manifestSchema',
+        verdict: 'fail',
+        detail: `${runtime}/${mode}: last ingress rule must be a catch-all http_status:N (found: ${lastRule ? JSON.stringify(lastRule).slice(0, 120) : '(no ingress rules)'})`,
+      });
+    }
+    const originViolations = refuseOriginPortRules(doc);
+    if (originViolations.length) {
+      results.push({
+        anchorAcId: 'AC-tunnel-noPublicOrigin',
+        verdict: 'fail',
+        detail: `${runtime}/${mode}: ${originViolations.join('; ')}`,
+      });
+    } else {
+      results.push({
+        anchorAcId: 'AC-tunnel-noPublicOrigin',
+        verdict: 'pass',
+        detail: `${runtime}/${mode}: every ingress service URL binds to an internal address; no host public port exposed`,
+      });
+    }
+    const cred = doc.credentialsFile;
+    if (!cred || typeof cred !== 'object' || Array.isArray(cred)) {
+      results.push({
+        anchorAcId: 'AC-tunnel-credentialsDiscipline',
+        verdict: 'fail',
+        detail: `${runtime}/${mode}: credentialsFile must be an object with a secretRef`,
+      });
+    } else if (!('secretRef' in cred) || typeof cred.secretRef !== 'string' || !cred.secretRef.length) {
+      results.push({
+        anchorAcId: 'AC-tunnel-credentialsDiscipline',
+        verdict: 'fail',
+        detail: `${runtime}/${mode}: credentialsFile.secretRef is required (found keys: ${Object.keys(cred).join(', ') || '(none)'})`,
+      });
+    } else if ('AccountTag' in cred || 'TunnelSecret' in cred || 'TunnelID' in cred) {
+      results.push({
+        anchorAcId: 'AC-tunnel-credentialsDiscipline',
+        verdict: 'fail',
+        detail: `${runtime}/${mode}: credentialsFile carries an inline JSON body (bypasses secretRef)`,
+      });
+    } else {
+      results.push({
+        anchorAcId: 'AC-tunnel-credentialsDiscipline',
+        verdict: 'pass',
+        detail: `${runtime}/${mode}: credentialsFile.secretRef = ${cred.secretRef}`,
+      });
+    }
+    const credPath = resolve(root, runtime, 'credentials/probe.json.example');
+    const scan = await eventSecrecyScan(credPath);
+    results.push({ anchorAcId: 'AC-tunnel-credentialsDiscipline', ...scan });
+    extra[`${runtime}/${mode}`] = { tunnel: doc.tunnel, ingressCount: Array.isArray(doc.ingress) ? doc.ingress.length : 0 };
+  }
+  return { results, extra };
+}
+
+const engine = { kind: 'schema-validate', image: 'edge-cloudflare-tunnel manifest schema (Ajv-free walker)', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('manifest-schema-validate', engine, runProbe);
+}

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,143 @@
+// Probe: real-account-connector-healthy.
+//
+// anchorAcId: AC-tunnel-connectorHealthy (US-39102 contribution;
+// real-account-connector-healthy declared with tunnelConnectorUp).
+// C4 ruling: the AC-tunnel-* symbolic anchors on the tunnel blueprint
+// ARE the AC ids in the shipped US-39101..US-39108 contribution band
+// (see blueprints/edge-cloudflare-tunnel/contributions/user-stories/
+// edge-cloudflare-tunnel-us-3910N.json); the anchors already resolve
+// to the shipped band, so no re-anchor is performed by H-2. The kv
+// treatment differed because those probes anchored AC-5xxx ids that
+// existed nowhere on the shelf; here the ids exist and match by
+// design.
+//
+// accountBound: true (gates on CI_HAS_CLOUDFLARE_ACCOUNT AND
+// CI_HAS_HETZNER_ACCOUNT; the connector runs on a throwaway Hetzner
+// server).
+//
+// Env-absent branch: pass-with-skip (spec section 3.5).
+// Env-present branch: provisions a throwaway Hetzner server through
+// the shared T-1 fixture provisionThrowawayServer, drives the
+// cloudflared control surface through the cf-edge shim's
+// cloudflaredTunnelInfo({ tunnelName }) call, asserts at least one
+// HEALTHY connector, and captures a tunnelConnectorUp event
+// (metadata-only: connector id, region, version). If the fixture
+// provisioning throws (missing HCLOUD_TOKEN, quota, etc.), the
+// probe FAILS with a pointer naming the fixture step: the tunnel
+// connector cannot report healthy on a server that never provisioned.
+//
+// The shim seams (cloudflaredTunnelInfo, event capture) allow the
+// driver path and mutation switches to be exercised locally without
+// a real Cloudflare account; the real-account run happens at HQ
+// gate time.
+
+import { runShim, accountBoundSkippedResult } from './probe-utils.mjs';
+
+export const anchorAcIds = ['AC-tunnel-connectorHealthy'];
+export const accountBound = true;
+
+const TUNNEL_NAME_ENV = 'CF_TUNNEL_NAME';
+const DEFAULT_TUNNEL_NAME = 'h2-cf-probe-integrity-scratch';
+
+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',
+    },
+    events: [],
+  };
+  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 };
+  }
+
+  // Env-present path: real driver. All account-bound work runs through
+  // the cf-edge shim, which itself delegates to the hetzner fixture in
+  // production and returns synthetic responses under the fixture-side
+  // H2_CF_TUNNEL_SHIM_MODE token. Probe body reads no mutation-switch
+  // env var and imports no fixture module directly.
+  const {
+    provisionScratchServer, destroyScratchServer, cloudflaredTunnelInfo,
+  } = await import(
+    '../../../../packages/rcf-lite/test/fixtures/cf-edge/h2-cf-tunnel-shim.mjs'
+  );
+
+  const runId = process.env.GITHUB_RUN_ID || `local-${Date.now()}`;
+  let provisioned = null;
+  try {
+    provisioned = await provisionScratchServer({ runId });
+    extra.provisioned = {
+      id: provisioned.id, name: provisioned.name, location: provisioned.location, shimMode: provisioned.shimMode,
+    };
+  } catch (err) {
+    results.push({
+      anchorAcId: 'AC-tunnel-connectorHealthy',
+      verdict: 'fail',
+      detail: `fixture provisionScratchServer failed: ${err.message}. The tunnel connector cannot report healthy on a server that never provisioned. Fix the fixture step (packages/rcf-lite/test/fixtures/hetzner-throwaway-server/provision.mjs) or the account tokens (HCLOUD_TOKEN) before re-running.`,
+    });
+    return { results, extra };
+  }
+
+  try {
+    const tunnelName = process.env[TUNNEL_NAME_ENV] || DEFAULT_TUNNEL_NAME;
+    extra.tunnelName = tunnelName;
+    let info;
+    try {
+      info = await cloudflaredTunnelInfo({ tunnelName });
+    } catch (err) {
+      results.push({
+        anchorAcId: 'AC-tunnel-connectorHealthy',
+        verdict: 'fail',
+        detail: `cloudflared tunnel info shim call failed: ${err.message}. Fix the cf-edge shim (packages/rcf-lite/test/fixtures/cf-edge/h2-cf-tunnel-shim.mjs) or the cloudflared control surface before re-running.`,
+      });
+      return { results, extra };
+    }
+    extra.shimMode = info.shimMode;
+    extra.connectorCount = info.connectors.length;
+    const healthy = info.connectors.filter((c) => String(c.status || '').toUpperCase() === 'HEALTHY');
+    if (healthy.length === 0) {
+      results.push({
+        anchorAcId: 'AC-tunnel-connectorHealthy',
+        verdict: 'fail',
+        detail: `cloudflared tunnel info returned ${info.connectors.length} connector(s), none HEALTHY. Statuses observed: ${info.connectors.map((c) => String(c.status || 'MISSING')).join(', ') || '(no connectors)'}.`,
+      });
+      return { results, extra };
+    }
+    // Capture tunnelConnectorUp event, metadata only (id, region, version).
+    for (const c of healthy) {
+      extra.events.push({
+        kind: 'tunnelConnectorUp',
+        connectorId: String(c.id ?? ''),
+        region: String(c.region ?? ''),
+        version: String(c.version ?? ''),
+      });
+    }
+    results.push({
+      anchorAcId: 'AC-tunnel-connectorHealthy',
+      verdict: 'pass',
+      detail: `cloudflared tunnel info returned ${info.connectors.length} connector(s), ${healthy.length} HEALTHY (shim mode ${info.shimMode}); tunnelConnectorUp event captured for each healthy connector with metadata-only payload (connectorId, region, version).`,
+    });
+    return { results, extra };
+  } finally {
+    // Always attempt teardown; a failed teardown is a fixture concern
+    // and rides sweep-orphans, not this probe.
+    try {
+      await destroyScratchServer(provisioned);
+    } catch (_err) {
+      // Best-effort; the nightly sweep-orphans job collects any leak.
+    }
+  }
+}
+
+const engine = { kind: 'real-account-cloudflared-info', image: 'cloudflared + hcloud (throwaway server) via cf-edge shim', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('real-account-connector-healthy', engine, runProbe);
+}