rcf-lite 0.24.0 → 0.25.0

package/blueprints/deploy-hetzner-server/contributions/probes/probe-utils.mjs

@@ -0,0 +1,106 @@
+// Shared helpers for deploy-hetzner-server probes.
+//
+// Runtime-dependency posture:
+// - cloud-init-render-lint, manifest-schema-validate and
+//   hcloud-dry-run-mock run in-process against the shared throwaway-
+//   server fixture at packages/rcf-lite/test/fixtures/hetzner-throwaway-
+//   server/. No real API call fires; hcloud is mocked via
+//   src/hcloud-mock.mjs so the shim never crosses the process boundary.
+// - real-account-* probes call the fixture's provision.mjs / destroy.mjs
+//   / snapshot verbs. Without CI_HAS_HETZNER_ACCOUNT they record
+//   accountBoundSkipped: true and the aggregate flips to pass per
+//   hetzner-round-7-spec-2026-09-07.md section 3.5.
+
+import { mkdir, writeFile, readFile, readdir } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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 MANIFEST_DIR = resolve(FIXTURE_DIR, 'hetzner/servers');
+export const SCHEMA_PATH = resolve(HERE, '..', 'schemas', 'hetzner-server.schema.json');
+export const REPORT_DIR = resolve(
+  PROJECT_ROOT,
+  '.rcf/reports/blueprints/deploy-hetzner-server',
+);
+
+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: 'deploy-hetzner-server',
+    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 async function readManifestFiles(dir = MANIFEST_DIR) {
+  let entries;
+  try {
+    entries = (await readdir(dir))
+      .filter((f) => f.endsWith('.json'))
+      .sort();
+  } catch (err) {
+    return { present: false, entries: [], files: [], error: err.message };
+  }
+  const files = [];
+  for (const name of entries) {
+    const p = join(dir, name);
+    const text = await readFile(p, 'utf8');
+    files.push({ name, path: p, text });
+  }
+  return { present: entries.length > 0, entries, files };
+}
+
+export function accountBoundSkippedResult(anchorAcId, note) {
+  return {
+    anchorAcId,
+    verdict: 'skipped',
+    accountBoundSkipped: true,
+    detail: `accountBound: CI_HAS_HETZNER_ACCOUNT unset; ${note}`,
+  };
+}

package/blueprints/deploy-hetzner-server/contributions/probes/real-account-cloud-init-hardened.mjs

@@ -0,0 +1,63 @@
+// Probe: real-account cloud-init hardened.
+//
+// anchorAcId: AC-37105-1. accountBound: true.
+//
+// Without CI_HAS_HETZNER_ACCOUNT the probe records
+// accountBoundSkipped: true and the aggregate flips to pass.
+//
+// With the env var set the probe:
+//   - provisions the throwaway server via the fixture provision.mjs;
+//   - shells cloud-init status --wait over ssh to the throwaway server;
+//   - runs the six baseline checks over ssh (grep for the marker per
+//     baseline block); FAILS naming the first missing block on any
+//     defect.
+//   - always() calls destroy.mjs regardless of verdict.
+
+import { accountBoundSkippedResult, FIXTURE_DIR } from './probe-utils.mjs';
+import { resolve } from 'node:path';
+
+export const anchorAcId = 'AC-37105-1';
+export const accountBound = true;
+
+export default async function runProbe() {
+  if (process.env.CI_HAS_HETZNER_ACCOUNT !== 'true') {
+    return {
+      results: [accountBoundSkippedResult(anchorAcId, 'real-account cloud-init hardened check skipped; run with CI_HAS_HETZNER_ACCOUNT=true to exercise the six ssh baseline checks against a throwaway cx23.')],
+    };
+  }
+  const provisionPath = resolve(FIXTURE_DIR, 'provision.mjs');
+  const destroyPath = resolve(FIXTURE_DIR, 'destroy.mjs');
+  const sshCheckPath = resolve(FIXTURE_DIR, 'src/ssh-baseline-check.mjs');
+  const { provisionThrowawayServer } = await import(provisionPath);
+  const { destroyThrowawayServer } = await import(destroyPath);
+  const { runSshBaselineChecks } = await import(sshCheckPath);
+  let provisioned;
+  try {
+    provisioned = await provisionThrowawayServer({ runId: process.env.GITHUB_RUN_ID ?? 'local' });
+    const report = await runSshBaselineChecks(provisioned);
+    const failed = report.checks.filter((c) => c.verdict === 'fail');
+    if (failed.length > 0) {
+      return {
+        results: failed.map((c) => ({
+          anchorAcId,
+          verdict: 'fail',
+          detail: `cloud-init baseline block "${c.label}" failed on server ${provisioned.id}: ${c.detail}`,
+        })),
+      };
+    }
+    return {
+      results: [{
+        anchorAcId,
+        verdict: 'pass',
+        detail: `cloud-init status --wait completed on server ${provisioned.id}; all six ssh baseline checks passed.`,
+      }],
+      extra: report,
+    };
+  } catch (err) {
+    return { results: [{ anchorAcId, verdict: 'fail', detail: `check failed: ${err.message}` }] };
+  } finally {
+    if (provisioned && provisioned.id) {
+      try { await destroyThrowawayServer(provisioned); } catch (_) { /* swept by orphan cron */ }
+    }
+  }
+}

package/blueprints/deploy-hetzner-server/contributions/probes/real-account-snapshot-on-demand.mjs

@@ -0,0 +1,60 @@
+// Probe: real-account snapshot on demand.
+//
+// anchorAcId: AC-37108-1. accountBound: true.
+//
+// Without CI_HAS_HETZNER_ACCOUNT the probe records
+// accountBoundSkipped: true and the aggregate flips to pass.
+//
+// With the env var set the probe:
+//   - provisions the throwaway server via provision.mjs;
+//   - fires the snapshot verb on the provisioner facade;
+//   - asserts hcloud image list --type=snapshot --output json shows a
+//     snapshot with the server name and current wall-clock time in the
+//     labels;
+//   - always() calls destroy.mjs regardless of verdict; the snapshot is
+//     deleted as part of destroy.mjs so the run leaves no orphaned
+//     image behind.
+
+import { accountBoundSkippedResult, FIXTURE_DIR } from './probe-utils.mjs';
+import { resolve } from 'node:path';
+
+export const anchorAcId = 'AC-37108-1';
+export const accountBound = true;
+
+export default async function runProbe() {
+  if (process.env.CI_HAS_HETZNER_ACCOUNT !== 'true') {
+    return {
+      results: [accountBoundSkippedResult(anchorAcId, 'real-account snapshot on-demand skipped; run with CI_HAS_HETZNER_ACCOUNT=true to exercise the hcloud image create-image path.')],
+    };
+  }
+  const provisionPath = resolve(FIXTURE_DIR, 'provision.mjs');
+  const destroyPath = resolve(FIXTURE_DIR, 'destroy.mjs');
+  const snapshotPath = resolve(FIXTURE_DIR, 'src/snapshot-verb.mjs');
+  const { provisionThrowawayServer } = await import(provisionPath);
+  const { destroyThrowawayServer } = await import(destroyPath);
+  const { takeAndVerifySnapshot } = await import(snapshotPath);
+  let provisioned;
+  try {
+    provisioned = await provisionThrowawayServer({ runId: process.env.GITHUB_RUN_ID ?? 'local' });
+    const outcome = await takeAndVerifySnapshot(provisioned);
+    if (!outcome.snapshotId) {
+      return {
+        results: [{ anchorAcId, verdict: 'fail', detail: `snapshot verb ran but no matching snapshot appeared in hcloud image list.` }],
+      };
+    }
+    return {
+      results: [{
+        anchorAcId,
+        verdict: 'pass',
+        detail: `snapshot ${outcome.snapshotId} tagged with server name ${provisioned.name} and time ${outcome.wallClockTime} on server ${provisioned.id}.`,
+      }],
+      extra: outcome,
+    };
+  } catch (err) {
+    return { results: [{ anchorAcId, verdict: 'fail', detail: `snapshot verb threw: ${err.message}` }] };
+  } finally {
+    if (provisioned && provisioned.id) {
+      try { await destroyThrowawayServer(provisioned); } catch (_) { /* swept by orphan cron */ }
+    }
+  }
+}

package/blueprints/deploy-hetzner-server/contributions/probes/real-account-throwaway-server-provision.mjs

@@ -0,0 +1,58 @@
+// Probe: real-account throwaway-server provision.
+//
+// anchorAcId: AC-37103-1. accountBound: true.
+//
+// Without CI_HAS_HETZNER_ACCOUNT the probe records
+// accountBoundSkipped: true and the aggregate flips to pass per
+// hetzner-round-7-spec-2026-09-07.md section 3.5.
+//
+// With the env var set the probe:
+//   - runs the fixture's provision.mjs against the ci-throwaway manifest;
+//   - asserts a new server appears in `hcloud server list --output json`
+//     whose id matches the scratch-file-written id;
+//   - asserts the fixture's captured hetznerServerProvisioned event
+//     carries id, primaryIpv4, location=fsn1, serverType=cx23;
+//   - always() calls destroy.mjs so the throwaway server is torn down
+//     regardless of verdict.
+
+import { accountBoundSkippedResult, FIXTURE_DIR } from './probe-utils.mjs';
+import { resolve } from 'node:path';
+
+export const anchorAcId = 'AC-37103-1';
+export const accountBound = true;
+
+export default async function runProbe() {
+  if (process.env.CI_HAS_HETZNER_ACCOUNT !== 'true') {
+    return {
+      results: [accountBoundSkippedResult(anchorAcId, 'real-account throwaway-server provision skipped; run with CI_HAS_HETZNER_ACCOUNT=true to exercise.')],
+    };
+  }
+  const provisionPath = resolve(FIXTURE_DIR, 'provision.mjs');
+  const destroyPath = resolve(FIXTURE_DIR, 'destroy.mjs');
+  const { provisionThrowawayServer } = await import(provisionPath);
+  const { destroyThrowawayServer } = await import(destroyPath);
+  let provisioned;
+  try {
+    provisioned = await provisionThrowawayServer({ runId: process.env.GITHUB_RUN_ID ?? 'local' });
+    return {
+      results: [{
+        anchorAcId,
+        verdict: 'pass',
+        detail: `throwaway server ${provisioned.id} provisioned; hetznerServerProvisioned event captured; primaryIpv4=${provisioned.primaryIpv4} location=${provisioned.location} serverType=${provisioned.serverType}.`,
+      }],
+      extra: { serverId: provisioned.id, primaryIpv4: provisioned.primaryIpv4 },
+    };
+  } catch (err) {
+    return {
+      results: [{
+        anchorAcId,
+        verdict: 'fail',
+        detail: `provision failed: ${err.message}`,
+      }],
+    };
+  } finally {
+    if (provisioned && provisioned.id) {
+      try { await destroyThrowawayServer(provisioned); } catch (_) { /* swept by orphan cron */ }
+    }
+  }
+}

package/blueprints/deploy-hetzner-server/contributions/probes/run-cloud-init-render-lint.mjs

@@ -0,0 +1,9 @@
+import runProbe from './cloud-init-render-lint.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = {
+  kind: 'template-render',
+  image: 'hetzner-throwaway-server fixture (in-process template render)',
+  healthy: true,
+};
+runShim('cloud-init-render-lint', engine, runProbe);

package/blueprints/deploy-hetzner-server/contributions/probes/run-hcloud-dry-run-mock.mjs

@@ -0,0 +1,9 @@
+import runProbe from './hcloud-dry-run-mock.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = {
+  kind: 'facade-round-trip',
+  image: 'hetzner-throwaway-server fixture provisioner facade against a mocked hcloud shim',
+  healthy: true,
+};
+runShim('hcloud-dry-run-mock', engine, runProbe);

package/blueprints/deploy-hetzner-server/contributions/probes/run-manifest-schema-validate.mjs

@@ -0,0 +1,9 @@
+import runProbe from './manifest-schema-validate.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = {
+  kind: 'schema-validate',
+  image: 'hetzner-throwaway-server fixture manifest directory (draft-07 subset in-process)',
+  healthy: true,
+};
+runShim('manifest-schema-validate', engine, runProbe);

package/blueprints/deploy-hetzner-server/contributions/probes/run-real-account-cloud-init-hardened.mjs

@@ -0,0 +1,9 @@
+import runProbe from './real-account-cloud-init-hardened.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = {
+  kind: 'real-account-ssh',
+  image: 'Hetzner Cloud throwaway cx23 with cloud-init user-data (ssh baseline checks)',
+  healthy: true,
+};
+runShim('real-account-cloud-init-hardened', engine, runProbe);

package/blueprints/deploy-hetzner-server/contributions/probes/run-real-account-snapshot-on-demand.mjs

@@ -0,0 +1,9 @@
+import runProbe from './real-account-snapshot-on-demand.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = {
+  kind: 'real-account-snapshot',
+  image: 'Hetzner Cloud throwaway cx23 with snapshot verb via hcloud image create-image',
+  healthy: true,
+};
+runShim('real-account-snapshot-on-demand', engine, runProbe);

package/blueprints/deploy-hetzner-server/contributions/probes/run-real-account-throwaway-server-provision.mjs

@@ -0,0 +1,9 @@
+import runProbe from './real-account-throwaway-server-provision.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = {
+  kind: 'real-account-throwaway-server',
+  image: 'Hetzner Cloud API via hcloud CLI (provision + list + destroy)',
+  healthy: true,
+};
+runShim('real-account-throwaway-server-provision', engine, runProbe);

package/blueprints/deploy-hetzner-server/contributions/requirements/deploy-hetzner-server-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-hetzner-server-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The provisioner facade is the sole reader of the Hetzner API token and opens on boot with provisionerReady",
+  "description": "The applying project reaches the Hetzner Cloud API through a single provisioner facade module that is the ONLY module holding a reference to the HETZNER_ACCOUNT_API_KEY secret (or the elicited project-scoped alternative). The facade wraps typed verbs (createServer, applyFirewall, takeSnapshot, listSnapshots, destroyServer) and, when provisioningTool=hcloud (default), shells to the hcloud CLI with `--output json`; when provisioningTool=raw-api it fetches the equivalent Hetzner Cloud REST endpoints per https://docs.hetzner.cloud/. On process boot the facade opens against the token via a bounded ready-check and emits a provisionerReady lifecycle event on the injected event sink with a metadata-only payload {tool, apiHost}. No other module reads the token; the injected event sink never carries the token or user-data bodies.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.1 REQ-001). Ships as v1.0.0 of deploy-hetzner-server.",
+  "tags": [
+    "blueprint:deploy-hetzner-server",
+    "capability:cloudHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/deploy-hetzner-server/contributions/requirements/deploy-hetzner-server-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-hetzner-server-REQ-002",
+  "prdId": "PRD-001",
+  "title": "The applying project holds server declarations at hetzner/servers/name.json against a shipped JSON Schema",
+  "description": "The applying project holds every server declaration as one JSON document under hetzner/servers/<name>.json, matching a shipped draft-07 JSON Schema at blueprints/deploy-hetzner-server/contributions/schemas/hetzner-server.schema.json. Required fields: name, serverType (cx23, cx33, and other Hetzner shared-cpu shapes), location (fsn1 default per Baz ruling 2026-09-07 09:50Z; also nbg1, hel1, ash, hil), image (ubuntu-24.04 default), sshKeyIds (nonempty array of Hetzner ssh-key references delegated to security-secrets-management), firewallId (an existing firewall or auto-create), networkId (optional private network), cloudInitPath (relative path to the rendered cloud-init user-data), labels (Hetzner tag map that must include role and blueprint), firewallRules (see REQ-004), snapshotCadence (see REQ-005). The schema refuses on missing required fields and on rule-shape violations (see REQ-004).",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.1 REQ-002).",
+  "tags": [
+    "blueprint:deploy-hetzner-server",
+    "capability:cloudHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/deploy-hetzner-server/contributions/requirements/deploy-hetzner-server-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-hetzner-server-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Cloud-init template renders YAML that lands the six hardening baseline blocks on every provisioned server",
+  "description": "The blueprint ships a cloud-init user-data template at blueprints/deploy-hetzner-server/contributions/templates/cloud-init.yaml.tmpl. Rendering the template against a manifest lands the six baseline blocks named by the estate baseline at operator/knowledge/systems/environments/hetzner-cloud/overview.md Security posture baseline and by the Debian unattended-upgrades wiki: (1) SSH key-only (PasswordAuthentication no via write_files on /etc/ssh/sshd_config.d/hardening.conf), (2) root disabled (PermitRootLogin no via the same file), (3) UFW default-deny incoming with 22, 80, 443 allowed per the manifest firewall shape, (4) DOCKER-USER iptables chain wired to drop non-conforming egress, (5) fail2ban SSH jail, (6) unattended-upgrades on for security updates. A render-lint asserts every block appears in the rendered YAML; a mutation SIMULATE_HARDENING_DRIFT=true removes the unattended-upgrades block and the lint FAILS naming the missing line.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.1 REQ-003).",
+  "tags": [
+    "blueprint:deploy-hetzner-server",
+    "capability:cloudHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/deploy-hetzner-server/contributions/requirements/deploy-hetzner-server-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-hetzner-server-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Firewall shape: 22 from operator-nominated prefixes, 80/443 open, all other inbound denied, applied at provision time",
+  "description": "Every hetzner/servers/name.json manifest carries a firewallRules array with the three-rule minimum shape: (a) an ssh rule permitting inbound TCP on 22 from a nonempty list of source-prefix ranges (the operator-nominated set; the schema refuses on 0.0.0.0/0 in this list), (b) an http rule permitting inbound TCP on 80 from any source, (c) an https rule permitting inbound TCP on 443 from any source, (d) an implicit deny for every other inbound rule. The provisioner applies the rule set to the server at provision time via hcloud firewall create (or reuse) plus hcloud firewall apply-to-resource. A raw-api provisioner posts the equivalent create-firewall and apply-to-resources bodies per https://docs.hetzner.cloud/#firewalls. Manifest schema validation refuses on any rule-set shape that violates (a) through (c).",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.1 REQ-004).",
+  "tags": [
+    "blueprint:deploy-hetzner-server",
+    "capability:cloudHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/deploy-hetzner-server/contributions/requirements/deploy-hetzner-server-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-hetzner-server-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Snapshot cadence elicited (weekly default, daily and off alternatives), snapshot-on-demand fires a tagged snapshot",
+  "description": "The applying project elicits a snapshot cadence per ADR-3802 with an enum of weekly (recommended default), daily and off. The value lives on hetzner/servers/name.json as snapshotCadence. When the cadence is non-off, a scheduled snapshot runner in the applying project fires the snapshot verb on the provisioner facade against every server whose cadence matches, and tags each snapshot with the server name and wall-clock time. A snapshot-on-demand verb on the provisioner fires the same shape without a schedule. Under provisioningTool=hcloud the facade shells to hcloud image create-image and tags via hcloud image update; under raw-api it posts to POST /servers/{id}/actions/create_image and PATCH /images/{id}. The hetznerSnapshotTaken lifecycle event carries snapshot id and wall-clock time. Hetzner-managed backups are a separately elicited paid opt-in (approximately 20 percent of monthly server price per https://docs.hetzner.com/cloud/servers/backups-snapshots/overview) and compose with the scheduled snapshot runner.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.1 REQ-005).",
+  "tags": [
+    "blueprint:deploy-hetzner-server",
+    "capability:cloudHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/deploy-hetzner-server/contributions/requirements/deploy-hetzner-server-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-hetzner-server-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Four lifecycle events fire with metadata-only payloads and no secret ever crosses the sink boundary",
+  "description": "The provisioner facade emits four lifecycle events on the injected event sink: provisionerReady (tool, apiHost), hetznerServerProvisioned (id, primaryIpv4, location, serverType, labels), hetznerSnapshotTaken (serverId, snapshotId, wallClockTime), hetznerServerDestroyed (id, wallClockTime). Every payload carries only metadata; no event body carries the HETZNER_ACCOUNT_API_KEY value, an ssh private key, or a rendered user-data body. The event-secrecy check inside the hcloud-dry-run-mock probe accumulates every emitted event body across a full lifecycle run and asserts the token, an ssh private-key marker (BEGIN OPENSSH PRIVATE KEY), and the elicited user-data bytes appear in NO event body; a mutation SIMULATE_EVENT_SECRECY_LEAK=true injects the token into the hetznerServerProvisioned payload and the probe FAILS with a defensive-fake finding naming the leaked field.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Hetzner round 7 spec (2026-09-07 section 5.1 REQ-006).",
+  "tags": [
+    "blueprint:deploy-hetzner-server",
+    "capability:cloudHost"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/deploy-hetzner-server/contributions/schemas/hetzner-server.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://stravica.ai/rcf-lite/schemas/hetzner-server.schema.json",
+  "title": "Hetzner Cloud server manifest file",
+  "description": "One server per file under the applying project's hetzner/servers/ directory. Fields track the Hetzner Cloud API server resource shape at https://docs.hetzner.cloud/.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "name",
+    "serverType",
+    "location",
+    "image",
+    "sshKeyIds",
+    "firewallId",
+    "cloudInitPath",
+    "labels",
+    "firewallRules",
+    "snapshotCadence"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Operator-facing stable server name (kebab-case). Used as the Hetzner server name and prefixed onto snapshot names."
+    },
+    "serverType": {
+      "type": "string",
+      "enum": ["cx23", "cx33", "cx43", "cpx11", "cpx21", "cpx31", "cpx41", "cax11", "cax21", "cax31"],
+      "description": "Hetzner Cloud shared-vCPU server type. cx23 is the shipped default per the round-7 spec section 5.1."
+    },
+    "location": {
+      "type": "string",
+      "enum": ["fsn1", "nbg1", "hel1", "ash", "hil"],
+      "description": "Hetzner data centre location. fsn1 is the shipped default per Baz ruling 2026-09-07 09:50Z on the Q2 ratification."
+    },
+    "image": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Hetzner Cloud base image identifier. ubuntu-24.04 is the shipped default."
+    },
+    "sshKeyIds": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Nonempty array of Hetzner ssh-key references. Delegated to security-secrets-management for the actual key material."
+    },
+    "networkId": {
+      "type": ["string", "null"],
+      "description": "Optional Hetzner Cloud private network id. null for no attached private network."
+    },
+    "firewallId": {
+      "type": ["string", "null"],
+      "description": "Existing Hetzner Cloud firewall id to reuse; when null the provisioner creates one from firewallRules."
+    },
+    "cloudInitPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Relative path to the rendered cloud-init user-data file. The renderer at src/cloud-init-renderer.mjs consumes contributions/templates/cloud-init.yaml.tmpl and writes the output here."
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "required": [
+        "role",
+        "blueprint"
+      ],
+      "description": "Hetzner tag map. Must include role and blueprint. Under the shared throwaway-server fixture role=rcf-lite-ci-throwaway is required per section 3.3 of the round-7 spec."
+    },
+    "firewallRules": {
+      "type": "array",
+      "minItems": 3,
+      "description": "The rule shape from TAC-3804. Must include an ssh rule (protocol tcp, port 22, direction in, sourceIps nonempty and NOT containing 0.0.0.0/0), an http rule (protocol tcp, port 80, direction in, sourceIps [\"0.0.0.0/0\", \"::/0\"]) and an https rule (protocol tcp, port 443, direction in, sourceIps [\"0.0.0.0/0\", \"::/0\"]).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "protocol", "port", "direction", "sourceIps"],
+        "properties": {
+          "name": { "type": "string", "enum": ["ssh", "http", "https"] },
+          "protocol": { "type": "string", "enum": ["tcp", "udp", "icmp"] },
+          "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
+          "direction": { "type": "string", "enum": ["in", "out"] },
+          "sourceIps": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
+    "snapshotCadence": {
+      "type": "string",
+      "enum": ["weekly", "daily", "off"],
+      "description": "Snapshot cadence per ADR-3802. weekly is the recommended default."
+    },
+    "hetznerManagedBackups": {
+      "type": "boolean",
+      "description": "Optional paid opt-in for Hetzner-managed backups per ADR-3802 (approximately 20 percent of monthly server price)."
+    }
+  }
+}

package/blueprints/deploy-hetzner-server/contributions/tacs/tac-3801-deploy-hetzner-server-provisioner.json

@@ -0,0 +1,27 @@
+{
+  "tacId": "TAC-3801-deploy-hetzner-server-provisioner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Deploy-hetzner-server provisioner facade",
+  "purpose": "The single project-side module that dereferences HETZNER_ACCOUNT_API_KEY, wraps typed Hetzner Cloud verbs (createServer, applyFirewall, takeSnapshot, listSnapshots, destroyServer), and emits four lifecycle events to the injected event sink. Under provisioningTool=hcloud the module shells to hcloud CLI with --output json; under raw-api it fetches the equivalent Hetzner Cloud REST endpoints. Consumers never dereference the token; the facade is the one place vendor credentials live.",
+  "responsibilities": [
+    "Open the facade on boot via a bounded ready-check; be the ONLY module that reads the HETZNER_ACCOUNT_API_KEY value, and export no symbol that leaks it (AC-37101-1).",
+    "Expose typed verbs createServer, applyFirewall, takeSnapshot, listSnapshots and destroyServer as returned methods on the factory result; refuse a raw-token passthrough on the public surface (AC-37101-1, AC-37103-1, AC-37108-1).",
+    "Emit provisionerReady, hetznerServerProvisioned, hetznerSnapshotTaken and hetznerServerDestroyed on the injected event sink; every payload is metadata-only per REQ-006 (AC-37101-1, AC-37103-1, AC-37108-1, AC-37109-1).",
+    "Shell path (hcloud): call hcloud <verb> --output json, JSON.parse the stdout, project the documented fields (id, primaryIpv4, location, serverType, snapshotId) into the returned record (AC-37103-1, AC-37108-1).",
+    "Raw-api path: fetch the documented REST endpoints (POST /servers, POST /firewalls, POST /servers/{id}/actions/create_image, DELETE /servers/{id}) with the token in Authorization: Bearer and project the same records (AC-37103-1)."
+  ],
+  "internalStructure": "One module exporting createProvisionerFacade({ token, tool, apiHost, eventSink, hcloudPath?, fetch? }) returning a ProvisionerFacade whose methods are the typed verbs. The token capture lives at the top of the factory; the shell path passes the token via HCLOUD_TOKEN in the child environment (never on the argv); the raw-api path passes it in the Authorization header. Consumers call the returned methods for the process lifetime; the raw token never crosses the module boundary again.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "factory",
+      "summary": "Provisioner facade factory exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/deploy-hetzner-server/contributions/tacs/tac-3802-deploy-hetzner-server-manifest-schema.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-3802-deploy-hetzner-server-manifest-schema",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Hetzner server manifest schema",
+  "purpose": "One draft-07 JSON Schema declaring the shape of hetzner/servers/name.json in the applying project. Names required fields (name, serverType, location, image, sshKeyIds, firewallId, cloudInitPath, labels, firewallRules, snapshotCadence) and enforces enums (location, serverType, snapshotCadence) and rule-shape invariants (see TAC-3804). Manifest-schema-validate.mjs uses the schema to accept or refuse every fixture manifest.",
+  "responsibilities": [
+    "Ship a draft-07 JSON Schema for the hetzner-server manifest at contributions/schemas/hetzner-server.schema.json (AC-37102-1).",
+    "Refuse on missing required fields with an error message that names the offending field (AC-37102-1).",
+    "Refuse on firewall-rule-shape violations (22 opened to 0.0.0.0/0, or 80/443 missing) with an error message that names the offending rule (AC-37106-1).",
+    "Enforce snapshotCadence enum {weekly, daily, off} and refuse otherwise (AC-37107-1)."
+  ],
+  "internalStructure": "One JSON Schema file at blueprints/deploy-hetzner-server/contributions/schemas/hetzner-server.schema.json; one shipped example manifest under the shared throwaway-server fixture at packages/rcf-lite/test/fixtures/hetzner-throwaway-server/hetzner/servers/ci-throwaway.json.",
+  "interfaces": [
+    {
+      "name": "hetzner-server.schema.json",
+      "kind": "jsonSchema",
+      "summary": "draft-07 JSON Schema for the Hetzner server manifest."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}