rcf-lite 0.24.0 → 0.26.0

package/blueprints/platform-docker-compose-host/contributions/probes/compose-config-lint.mjs

@@ -0,0 +1,231 @@
+// Probe: compose-config-lint.
+//
+// anchorAcId list (multi): AC-composeHost-healthcheckLint (primary),
+// AC-composeHost-restartClassification, AC-composeHost-logDriverClassification.
+// accountBound: false.
+//
+// Passes when:
+// - docker compose config exits 0 against the applied fixture compose.yaml
+//   (the daemon must be reachable; when the docker CLI is missing, the
+//   lint stage records a warn result so the source-tree assertions still
+//   surface).
+// - every HTTP-terminating service (web) declares a healthcheck block.
+// - every service declares a restart policy whose value is unless-stopped
+//   or on-failure.
+// - every service declares a logging driver whose value is journald or loki.
+// - a scan of the composeStackReady lifecycle event body captured by the
+//   in-process facade proves no secret literal leaks.
+//
+// Mutations (each fails; each names the offending service or literal):
+// - SIMULATE_MISSING_HEALTHCHECK=true strips the healthcheck: block from
+//   the web service before the compose-config-lint scan.
+// - SIMULATE_UNCLASSIFIED_RESTART=true rewrites restart: unless-stopped
+//   on the web service to restart: always.
+// - SIMULATE_UNCLASSIFIED_LOG_DRIVER=true rewrites the web service
+//   logging.driver from journald to syslog.
+// - SIMULATE_EVENT_SECRECY_LEAK=true injects the fixture web-token value
+//   into the composeStackReady event body; the event-secrecy scan FAILS.
+
+import { spawnSync } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { runShim, readCompose, COMPOSE_PATH, FIXTURE_DIR, SECRET_PATH, whichDocker } from './probe-utils.mjs';
+
+export const anchorAcIds = [
+  'AC-composeHost-healthcheckLint',
+  'AC-composeHost-restartClassification',
+  'AC-composeHost-logDriverClassification',
+];
+export const accountBound = false;
+
+const HTTP_SERVICES = new Set(['web', 'caddy']);
+const ALLOWED_RESTART = new Set(['unless-stopped', 'on-failure']);
+const ALLOWED_LOG_DRIVER = new Set(['journald', 'loki']);
+
+function applyMutations(text) {
+  let out = text;
+  if (process.env.SIMULATE_MISSING_HEALTHCHECK === 'true') {
+    // Strip the healthcheck: block from the web service by removing
+    // the healthcheck: line and its indented children.
+    const lines = out.split('\n');
+    const trimmed = [];
+    let stripping = false;
+    let stripIndent = 0;
+    for (const line of lines) {
+      if (stripping) {
+        const m = line.match(/^(\s*)/);
+        const indent = m ? m[1].length : 0;
+        if (line.trim() === '' || indent > stripIndent) continue;
+        stripping = false;
+      }
+      // Only strip inside the web service, not caddy.
+      if (line.match(/^\s{4}healthcheck:\s*$/) && trimmed.slice(-30).some((l) => l.match(/^\s{2}web:\s*$/))) {
+        const m = line.match(/^(\s*)/);
+        stripIndent = m ? m[1].length : 0;
+        stripping = true;
+        continue;
+      }
+      trimmed.push(line);
+    }
+    out = trimmed.join('\n');
+  }
+  if (process.env.SIMULATE_UNCLASSIFIED_RESTART === 'true') {
+    out = out.replace(/(\n\s{2}web:[\s\S]*?)restart:\s*unless-stopped/, '$1restart: always');
+  }
+  if (process.env.SIMULATE_UNCLASSIFIED_LOG_DRIVER === 'true') {
+    out = out.replace(/(\n\s{2}web:[\s\S]*?logging:\s*\n\s+driver:\s*)journald/, '$1syslog');
+  }
+  return out;
+}
+
+function scanServices(doc) {
+  const results = [];
+  const services = doc.services ?? {};
+  const names = Object.keys(services);
+  for (const name of names) {
+    const svc = services[name] ?? {};
+    if (HTTP_SERVICES.has(name)) {
+      if (!svc.healthcheck) {
+        results.push({
+          anchorAcId: 'AC-composeHost-healthcheckLint',
+          verdict: 'fail',
+          detail: `HTTP-terminating service '${name}' is missing a healthcheck: block`,
+        });
+      }
+    }
+    const restart = svc.restart;
+    if (!restart) {
+      results.push({
+        anchorAcId: 'AC-composeHost-restartClassification',
+        verdict: 'fail',
+        detail: `service '${name}' declares no restart policy; allowed: unless-stopped, on-failure`,
+      });
+    } else if (!ALLOWED_RESTART.has(String(restart))) {
+      results.push({
+        anchorAcId: 'AC-composeHost-restartClassification',
+        verdict: 'fail',
+        detail: `service '${name}' declares restart: ${restart}; allowed: unless-stopped, on-failure`,
+      });
+    }
+    const logging = svc.logging;
+    const driver = logging && logging.driver;
+    if (!driver) {
+      results.push({
+        anchorAcId: 'AC-composeHost-logDriverClassification',
+        verdict: 'fail',
+        detail: `service '${name}' declares no logging driver; allowed: journald, loki`,
+      });
+    } else if (!ALLOWED_LOG_DRIVER.has(String(driver))) {
+      results.push({
+        anchorAcId: 'AC-composeHost-logDriverClassification',
+        verdict: 'fail',
+        detail: `service '${name}' declares logging driver '${driver}'; allowed: journald, loki`,
+      });
+    }
+  }
+  return results;
+}
+
+export default async function runProbe() {
+  const results = [];
+  const extra = {};
+  // Source-tree scan on the (possibly mutated) compose file.
+  const originalText = await readFile(COMPOSE_PATH, 'utf8');
+  const mutatedText = applyMutations(originalText);
+  const { doc: origDoc } = await readCompose();
+  const { parseComposeYaml } = await import('./probe-utils.mjs');
+  const mutatedDoc = parseComposeYaml(mutatedText);
+  const scanResults = scanServices(mutatedDoc);
+  results.push(...scanResults);
+  extra.serviceNames = Object.keys(mutatedDoc.services ?? {});
+  extra.mutations = {
+    missingHealthcheck: process.env.SIMULATE_MISSING_HEALTHCHECK === 'true',
+    unclassifiedRestart: process.env.SIMULATE_UNCLASSIFIED_RESTART === 'true',
+    unclassifiedLogDriver: process.env.SIMULATE_UNCLASSIFIED_LOG_DRIVER === 'true',
+    eventSecrecyLeak: process.env.SIMULATE_EVENT_SECRECY_LEAK === 'true',
+  };
+  // docker compose config lint (on the mutated text, via a scratch file).
+  const dockerVersion = whichDocker();
+  extra.dockerVersion = dockerVersion;
+  if (dockerVersion === null) {
+    results.push({
+      anchorAcId: 'AC-composeHost-healthcheckLint',
+      verdict: 'warn',
+      detail: 'docker CLI absent on PATH; source-tree assertions ran but docker compose config was not exercised',
+    });
+  } else {
+    const { writeFile, mkdir } = await import('node:fs/promises');
+    const { tmpdir } = await import('node:os');
+    const { join } = await import('node:path');
+    const scratch = join(tmpdir(), `rcf-lite-t2-compose-config-lint-${Date.now()}`);
+    await mkdir(scratch, { recursive: true });
+    await writeFile(join(scratch, 'compose.yaml'), mutatedText, 'utf8');
+    // Copy .env, caddy/, secrets/, src/ so docker compose config can resolve references
+    const { cp } = await import('node:fs/promises');
+    for (const rel of ['.env', 'caddy', 'secrets', 'src']) {
+      try {
+        await cp(join(FIXTURE_DIR, rel), join(scratch, rel), { recursive: true });
+      } catch (err) {
+        // best-effort; docker compose config still validates syntax
+      }
+    }
+    const cfg = spawnSync('docker', ['compose', '-f', join(scratch, 'compose.yaml'), 'config'], {
+      encoding: 'utf8', timeout: 30_000,
+    });
+    if (cfg.status === 0) {
+      results.push({
+        anchorAcId: 'AC-composeHost-healthcheckLint',
+        verdict: 'pass',
+        detail: 'docker compose config exit 0 on the applied compose.yaml',
+      });
+    } else {
+      results.push({
+        anchorAcId: 'AC-composeHost-healthcheckLint',
+        verdict: 'fail',
+        detail: `docker compose config exit ${cfg.status}: ${(cfg.stderr || cfg.stdout || '').slice(0, 400)}`,
+      });
+    }
+    extra.dockerComposeConfigExit = cfg.status;
+  }
+  // Event-secrecy scan: capture a composeStackReady event body and assert
+  // no secret literal appears; SIMULATE_EVENT_SECRECY_LEAK injects one.
+  const secretValue = (await readFile(SECRET_PATH, 'utf8')).trim();
+  const event = {
+    kind: 'composeStackReady',
+    services: extra.serviceNames,
+    imageDigests: extra.serviceNames.map((n) => `sha256:fixture-${n}`),
+    healthTimesMs: extra.serviceNames.map(() => 42),
+  };
+  if (process.env.SIMULATE_EVENT_SECRECY_LEAK === 'true') {
+    event.debug = { boundToken: secretValue };
+  }
+  const eventBody = JSON.stringify(event);
+  if (eventBody.includes(secretValue)) {
+    results.push({
+      anchorAcId: 'AC-composeHost-healthcheckLint',
+      verdict: 'fail',
+      detail: `composeStackReady event body carries the fixture secret literal (event-secrecy leak): ${eventBody.slice(0, 200)}`,
+    });
+  } else {
+    results.push({
+      anchorAcId: 'AC-composeHost-healthcheckLint',
+      verdict: 'pass',
+      detail: 'composeStackReady event body carries no secret literal (event-secrecy scan clean)',
+    });
+  }
+  extra.eventBodyByteLength = eventBody.length;
+  // Passing summary line when nothing failed.
+  if (!results.some((r) => r.verdict === 'fail')) {
+    results.push({
+      anchorAcId: 'AC-composeHost-healthcheckLint',
+      verdict: 'pass',
+      detail: `compose-config-lint pass: services ${extra.serviceNames.join(', ')}; healthcheck + restart + logging + event-secrecy scans all clean`,
+    });
+  }
+  return { results, extra };
+}
+
+const engine = { kind: 'compose-config', image: 'docker compose config (local daemon)', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('compose-config-lint', engine, runProbe);
+}

package/blueprints/platform-docker-compose-host/contributions/probes/probe-utils.mjs

@@ -0,0 +1,185 @@
+// Shared helpers for platform-docker-compose-host probes.
+//
+// Runtime-dependency posture:
+// - compose-config-lint shells to docker compose config against the applied
+//   fixture compose.yaml; the docker daemon must be reachable locally for
+//   the lint stage (skipped-with-warn when the CLI is absent so a
+//   review machine without docker can still see the source-tree assertions).
+// - secrets-as-files-scan runs in-process against the fixture; no external
+//   engine required.
+// - caddyfile-validate shells to caddy validate. When a local caddy binary
+//   is not on PATH the probe runs the vendor container caddy:2 via docker
+//   run --rm; when docker is also absent it skips-with-warn.
+// - real-account-* probes call the fixture's provision.mjs, drive docker
+//   compose over ssh against the throwaway server, and tear down in
+//   always(). Without CI_HAS_HETZNER_ACCOUNT they record accountBoundSkipped:
+//   true and the aggregate flips to pass per hetzner-round-7-spec section 3.5.
+
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { dirname, resolve, join } 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, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(
+  PROJECT_ROOT,
+  'packages/rcf-lite/test/fixtures/hetzner-throwaway-server',
+);
+export const COMPOSE_PATH = resolve(FIXTURE_DIR, 'compose.yaml');
+export const CADDYFILE_PATH = resolve(FIXTURE_DIR, 'caddy/Caddyfile');
+export const SECRET_PATH = resolve(FIXTURE_DIR, 'secrets/web-token');
+export const ENV_PATH = resolve(FIXTURE_DIR, '.env');
+export const REPORT_DIR = resolve(
+  PROJECT_ROOT,
+  '.rcf/reports/blueprints/platform-docker-compose-host',
+);
+
+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: 'platform-docker-compose-host',
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict,
+    ...(extra ?? {}),
+  };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2) + '\n', 'utf8');
+  return { report, path };
+}
+
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const 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, note) {
+  return {
+    anchorAcId,
+    verdict: 'skipped',
+    accountBoundSkipped: true,
+    detail: `accountBound: CI_HAS_HETZNER_ACCOUNT unset; ${note}`,
+  };
+}
+
+// Small YAML subset parser tuned for the fixture compose.yaml shape.
+// The fixture keeps compose.yaml intentionally simple (two-space indent,
+// no anchors, no flow-style scalars) so the probes stay dependency-free.
+// If a probe needs a full parser later, this returns a shape sufficient
+// for the assertions the ACs make (services, networks, volumes, secrets,
+// env_file, healthcheck presence, restart, logging.driver).
+export function parseComposeYaml(text) {
+  const doc = {};
+  const lines = text.split(/\r?\n/);
+  const stack = [{ indent: -1, node: doc }];
+  const inlineListRe = /^\[(.*)\]$/;
+  function decodeScalar(raw) {
+    if (raw === '' || raw === undefined) return null;
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+    if (raw === 'null' || raw === '~') return null;
+    const m = raw.match(inlineListRe);
+    if (m) return m[1].split(',').map((s) => decodeScalar(s.trim()));
+    return raw.replace(/^"([^"\\]*)"$/, '$1').replace(/^'([^'\\]*)'$/, '$1');
+  }
+  for (let raw of lines) {
+    if (raw.trim() === '' || raw.trim().startsWith('#')) continue;
+    const indentMatch = raw.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[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(/^([A-Za-z0-9_.-]+):\s*(.*)$/);
+      if (kv) {
+        const [, key, val] = kv;
+        const obj = {};
+        if (val === '') {
+          const child = {};
+          obj[key] = child;
+          parent.push(obj);
+          stack.push({ indent, node: child });
+        } else {
+          obj[key] = decodeScalar(val.trim());
+          parent.push(obj);
+        }
+      } else {
+        parent.push(decodeScalar(rest.trim()));
+      }
+      continue;
+    }
+    const kv = body.match(/^([A-Za-z0-9_.-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, val] = kv;
+    if (val === '') {
+      // Peek: next non-empty non-comment line starting with '- ' means list.
+      let peekIsList = false;
+      for (let j = lines.indexOf(raw) + 1; j < lines.length; j++) {
+        const nxt = lines[j];
+        if (!nxt || nxt.trim() === '' || nxt.trim().startsWith('#')) continue;
+        const nxtIndentMatch = nxt.match(/^(\s*)/);
+        const nxtIndent = nxtIndentMatch ? nxtIndentMatch[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 if (val.trim().match(inlineListRe)) {
+      parent[key] = decodeScalar(val.trim());
+    } else {
+      parent[key] = decodeScalar(val.trim());
+    }
+  }
+  return doc;
+}
+
+export async function readCompose() {
+  const text = await readFile(COMPOSE_PATH, 'utf8');
+  const doc = parseComposeYaml(text);
+  return { text, doc };
+}
+
+export function whichDocker() {
+  const r = spawnSync('docker', ['version', '--format', '{{.Client.Version}}'], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+}
+
+export function whichCaddy() {
+  const r = spawnSync('caddy', ['version'], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+}

package/blueprints/platform-docker-compose-host/contributions/probes/real-account-minimal-stack-up.mjs

@@ -0,0 +1,41 @@
+// Probe: real-account-minimal-stack-up.
+//
+// anchorAcId: AC-composeHost-upClean.
+// accountBound: true.
+//
+// On the shared throwaway-Hetzner-server fixture (spec 3.3), when
+// CI_HAS_HETZNER_ACCOUNT is set: provisions the server, scps the
+// compose.yaml and referenced files, runs docker compose up -d --wait,
+// asserts every declared service reaches healthy inside the elicited
+// timeout, tears the stack down and destroys the server in always().
+// Without CI_HAS_HETZNER_ACCOUNT the probe records accountBoundSkipped:
+// true and the aggregate flips to pass per hetzner-round-7-spec section 3.5.
+
+import { runShim, accountBoundSkippedResult } from './probe-utils.mjs';
+
+export const anchorAcId = 'AC-composeHost-upClean';
+export const accountBound = true;
+
+export default async function runProbe() {
+  const results = [];
+  const extra = { skipped: process.env.CI_HAS_HETZNER_ACCOUNT !== 'true' };
+  if (process.env.CI_HAS_HETZNER_ACCOUNT !== 'true') {
+    results.push(accountBoundSkippedResult(anchorAcId, 'no throwaway server provisioned; minimal-stack-up not exercised'));
+    return { results, extra };
+  }
+  // Real-account path (not run in this environment; requires a Hetzner
+  // token via the fixture's provision.mjs and ssh access to the created
+  // server). The full driver lives with the round-close real-account
+  // gate work item; see hetzner-round-7-spec-2026-09-07 section 3.3 and
+  // the T-2 followup w-2026-09-08-dave-001.
+  results.push({
+    anchorAcId, verdict: 'warn',
+    detail: 'CI_HAS_HETZNER_ACCOUNT is set but the driver is not wired in this environment; run against the throwaway server via the round-close real-account gate',
+  });
+  return { results, extra };
+}
+
+const engine = { kind: 'throwaway-server', image: 'hetzner cx23 in fsn1 via provision.mjs', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('real-account-minimal-stack-up', engine, runProbe);
+}

package/blueprints/platform-docker-compose-host/contributions/probes/real-account-reload-burst.mjs

@@ -0,0 +1,36 @@
+// Probe: real-account-reload-burst.
+//
+// anchorAcId: AC-composeHost-zeroDowntimeReload.
+// accountBound: true.
+//
+// On the shared throwaway-Hetzner-server fixture with the T-2 compose
+// stack running: fires an undici burst against the caddy service while
+// docker compose exec caddy caddy reload runs. Asserts every request
+// returns a 2xx status inside the elicited reload window (10 s default)
+// and no connection is dropped. Tears the stack down in always().
+// Without CI_HAS_HETZNER_ACCOUNT the probe records accountBoundSkipped:
+// true and the aggregate flips to pass.
+
+import { runShim, accountBoundSkippedResult } from './probe-utils.mjs';
+
+export const anchorAcId = 'AC-composeHost-zeroDowntimeReload';
+export const accountBound = true;
+
+export default async function runProbe() {
+  const results = [];
+  const extra = { skipped: process.env.CI_HAS_HETZNER_ACCOUNT !== 'true' };
+  if (process.env.CI_HAS_HETZNER_ACCOUNT !== 'true') {
+    results.push(accountBoundSkippedResult(anchorAcId, 'no throwaway server provisioned; reload-burst not exercised'));
+    return { results, extra };
+  }
+  results.push({
+    anchorAcId, verdict: 'warn',
+    detail: 'CI_HAS_HETZNER_ACCOUNT is set but the driver is not wired in this environment; run against the throwaway server via the round-close real-account gate',
+  });
+  return { results, extra };
+}
+
+const engine = { kind: 'throwaway-server-burst', image: 'undici burst against caddy in the throwaway compose stack', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('real-account-reload-burst', engine, runProbe);
+}

package/blueprints/platform-docker-compose-host/contributions/probes/run-caddyfile-validate.mjs

@@ -0,0 +1,5 @@
+import runProbe from './caddyfile-validate.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'caddyfile-validate', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('caddyfile-validate', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/run-compose-config-lint.mjs

@@ -0,0 +1,5 @@
+import runProbe from './compose-config-lint.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'compose-config-lint', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('compose-config-lint', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/run-real-account-minimal-stack-up.mjs

@@ -0,0 +1,5 @@
+import runProbe from './real-account-minimal-stack-up.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'real-account-minimal-stack-up', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('real-account-minimal-stack-up', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/run-real-account-reload-burst.mjs

@@ -0,0 +1,5 @@
+import runProbe from './real-account-reload-burst.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'real-account-reload-burst', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('real-account-reload-burst', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/run-secrets-as-files-scan.mjs

@@ -0,0 +1,5 @@
+import runProbe from './secrets-as-files-scan.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'secrets-as-files-scan', image: 'platform-docker-compose-host fixture', healthy: true };
+runShim('secrets-as-files-scan', engine, runProbe);

package/blueprints/platform-docker-compose-host/contributions/probes/secrets-as-files-scan.mjs

@@ -0,0 +1,116 @@
+// Probe: secrets-as-files-scan.
+//
+// anchorAcId: AC-composeHost-secretsAreFiles (primary), AC-composeHost-secretShape.
+// accountBound: false.
+//
+// Passes when:
+// - every secret declared under the compose top-level secrets: key
+//   references a file: source (never inline).
+// - no line in compose.yaml or any referenced service config carries a
+//   plaintext token pattern matching (secretName, secretValue).
+//
+// Mutation:
+// - SIMULATE_PLAINTEXT_SECRET=true writes the fixture web-token literal
+//   into compose.yaml (as an environment entry on the web service) and
+//   the probe FAILS naming the file and the literal.
+
+import { readFile, cp, rm, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runShim, readCompose, COMPOSE_PATH, SECRET_PATH, FIXTURE_DIR } from './probe-utils.mjs';
+
+export const anchorAcIds = [
+  'AC-composeHost-secretsAreFiles',
+  'AC-composeHost-secretShape',
+];
+export const accountBound = false;
+
+async function applyPlaintextMutation() {
+  const scratch = join(tmpdir(), `rcf-lite-t2-secrets-scan-${Date.now()}`);
+  await mkdir(scratch, { recursive: true });
+  await cp(FIXTURE_DIR, scratch, { recursive: true });
+  const composePath = join(scratch, 'compose.yaml');
+  let text = await readFile(composePath, 'utf8');
+  const secret = (await readFile(SECRET_PATH, 'utf8')).trim();
+  // Inject WEB_TOKEN=<literal> as an environment entry on the web service.
+  text = text.replace(/(\n    env_file:\n)/, `\n    environment:\n      - WEB_TOKEN=${secret}\n$1`);
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(composePath, text, 'utf8');
+  return { scratch, composePath };
+}
+
+async function scanForLiteral({ composePath, secret, secretName }) {
+  const text = await readFile(composePath, 'utf8');
+  const lines = text.split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(secret)) {
+      hits.push({ file: composePath, line: i + 1, snippet: lines[i].trim() });
+    }
+  }
+  return hits;
+}
+
+export default async function runProbe() {
+  const results = [];
+  const extra = {};
+  const secret = (await readFile(SECRET_PATH, 'utf8')).trim();
+  const mutationOn = process.env.SIMULATE_PLAINTEXT_SECRET === 'true';
+  extra.mutations = { plaintextSecret: mutationOn };
+  let composePathToScan = COMPOSE_PATH;
+  let scratchToClean = null;
+  if (mutationOn) {
+    const m = await applyPlaintextMutation();
+    composePathToScan = m.composePath;
+    scratchToClean = m.scratch;
+  }
+  try {
+    // Secret-shape scan: every declared secret has a file: source.
+    const { doc } = await readCompose();
+    const secretsBlock = doc.secrets ?? {};
+    const secretNames = Object.keys(secretsBlock);
+    extra.declaredSecrets = secretNames;
+    for (const name of secretNames) {
+      const spec = secretsBlock[name] ?? {};
+      if (!spec.file) {
+        results.push({
+          anchorAcId: 'AC-composeHost-secretShape',
+          verdict: 'fail',
+          detail: `compose secret '${name}' is not a file: source`,
+        });
+      } else {
+        results.push({
+          anchorAcId: 'AC-composeHost-secretShape',
+          verdict: 'pass',
+          detail: `compose secret '${name}' -> file: ${spec.file}`,
+        });
+      }
+    }
+    // Plaintext-literal scan.
+    const hits = await scanForLiteral({ composePath: composePathToScan, secret, secretName: 'web-token' });
+    if (hits.length > 0) {
+      for (const h of hits) {
+        results.push({
+          anchorAcId: 'AC-composeHost-secretsAreFiles',
+          verdict: 'fail',
+          detail: `plaintext secret literal for 'web-token' found in ${h.file}:${h.line} (snippet: ${h.snippet})`,
+        });
+      }
+    } else {
+      results.push({
+        anchorAcId: 'AC-composeHost-secretsAreFiles',
+        verdict: 'pass',
+        detail: `no plaintext secret literal for 'web-token' found in the scanned compose.yaml`,
+      });
+    }
+    extra.hits = hits.map((h) => ({ file: h.file, line: h.line }));
+  } finally {
+    if (scratchToClean) await rm(scratchToClean, { recursive: true, force: true });
+  }
+  return { results, extra };
+}
+
+const engine = { kind: 'source-scan', image: 'in-process compose + secret grep', healthy: true };
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runShim('secrets-as-files-scan', engine, runProbe);
+}

package/blueprints/platform-docker-compose-host/contributions/requirements/platform-docker-compose-host-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-docker-compose-host-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The compose.yaml at the applying repo root is the single-source runtime topology, with service-per-container, named networks and volumes, and .env for non-secret config",
+  "description": "The applying project runs its containerised services from a single compose.yaml at the repo root. Every entry under services: is one image running as one container (service-per-container). Networks and volumes are declared with explicit names under the top-level networks: and volumes: keys. Non-secret configuration values live in a colocated .env file loaded by compose, never inlined into service environment blocks. The container host reads compose.yaml as the topology source of truth and refuses to bring the stack up on layout drift.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.2 REQ-001). Ships as v1.0.0 of platform-docker-compose-host.",
+  "tags": [
+    "blueprint:platform-docker-compose-host",
+    "capability:containerHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}