@rubytech/create-maxy-code 0.1.24 → 0.1.27

package/payload/platform/plugins/cloudflare/scripts/__tests__/tunnel-ingress.test.ts

@@ -0,0 +1,241 @@
+// Task 009 — acceptance grid for tunnel-ingress.ts pure layer.
+//
+// Runs under `node --test --experimental-strip-types` (no compile step). No
+// filesystem reads except via temp files written by the test itself; no
+// network; no shell-outs. Mirrors apt-resolve / samba-provision style.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  renderConfigYml,
+  renderTunnelState,
+  readPersistedHostnames,
+  probeSambaStanza,
+  renderAccessPolicyActionRequired,
+  type IngressSpec,
+  type TunnelState,
+} from "../tunnel-ingress.ts";
+
+// ---------------------------------------------------------------------------
+// renderConfigYml
+// ---------------------------------------------------------------------------
+
+test("renderConfigYml: HTTPS-only matches pre-Task-009 shape byte-for-byte", () => {
+  const spec: IngressSpec = {
+    tunnelId: "abc-123",
+    credentialsPath: "/home/admin/.maxy/cloudflared/abc-123.json",
+    httpPort: 19200,
+    httpHostnames: ["admin.maxy.bot", "public.maxy.bot"],
+  };
+  assert.equal(
+    renderConfigYml(spec),
+    [
+      "tunnel: abc-123",
+      "credentials-file: /home/admin/.maxy/cloudflared/abc-123.json",
+      "ingress:",
+      "  - hostname: admin.maxy.bot",
+      "    service: http://localhost:19200",
+      "  - hostname: public.maxy.bot",
+      "    service: http://localhost:19200",
+      "  - service: http_status:404",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("renderConfigYml: SSH+SMB appear AFTER http hostnames and BEFORE catch-all", () => {
+  const spec: IngressSpec = {
+    tunnelId: "t-id",
+    credentialsPath: "/creds.json",
+    httpPort: 19200,
+    httpHostnames: ["admin.maxy.bot"],
+    sshHostname: "ssh.maxy.bot",
+    smbHostname: "smb.maxy.bot",
+  };
+  const out = renderConfigYml(spec);
+  const idxHttp = out.indexOf("admin.maxy.bot");
+  const idxSsh = out.indexOf("ssh.maxy.bot");
+  const idxSmb = out.indexOf("smb.maxy.bot");
+  const idx404 = out.indexOf("http_status:404");
+  assert.ok(idxHttp < idxSsh, "HTTP before SSH");
+  assert.ok(idxSsh < idxSmb, "SSH before SMB");
+  assert.ok(idxSmb < idx404, "SMB before catch-all 404");
+  assert.match(out, /\s+service: ssh:\/\/localhost:22$/m);
+  assert.match(out, /\s+service: tcp:\/\/localhost:445$/m);
+});
+
+test("renderConfigYml: SSH only — no SMB block when smbHostname is null", () => {
+  const spec: IngressSpec = {
+    tunnelId: "t-id",
+    credentialsPath: "/creds.json",
+    httpPort: 19200,
+    httpHostnames: ["admin.maxy.bot"],
+    sshHostname: "ssh.maxy.bot",
+    smbHostname: null,
+  };
+  const out = renderConfigYml(spec);
+  assert.ok(out.includes("ssh.maxy.bot"));
+  assert.ok(!out.includes("tcp://localhost:445"));
+});
+
+test("renderConfigYml: empty string hostnames are treated as absent", () => {
+  const spec: IngressSpec = {
+    tunnelId: "t-id",
+    credentialsPath: "/creds.json",
+    httpPort: 19200,
+    httpHostnames: ["admin.maxy.bot"],
+    sshHostname: "",
+    smbHostname: "",
+  };
+  const out = renderConfigYml(spec);
+  assert.ok(!out.includes("ssh://localhost:22"));
+  assert.ok(!out.includes("tcp://localhost:445"));
+});
+
+// ---------------------------------------------------------------------------
+// renderTunnelState
+// ---------------------------------------------------------------------------
+
+test("renderTunnelState: pre-Task-009 fields preserved when ssh/smb absent", () => {
+  const state: TunnelState = {
+    tunnelId: "abc",
+    tunnelName: "maxy",
+    domain: "admin.maxy.bot",
+    configPath: "/home/admin/.maxy/cloudflared/config.yml",
+    credentialsPath: "/home/admin/.maxy/cloudflared/abc.json",
+  };
+  const parsed = JSON.parse(renderTunnelState(state));
+  assert.deepEqual(parsed, {
+    tunnelId: "abc",
+    tunnelName: "maxy",
+    domain: "admin.maxy.bot",
+    configPath: "/home/admin/.maxy/cloudflared/config.yml",
+    credentialsPath: "/home/admin/.maxy/cloudflared/abc.json",
+  });
+});
+
+test("renderTunnelState: ssh/smb hostnames persist when present", () => {
+  const state: TunnelState = {
+    tunnelId: "abc",
+    tunnelName: "maxy",
+    domain: "admin.maxy.bot",
+    configPath: "/cfg.yml",
+    credentialsPath: "/creds.json",
+    sshHostname: "ssh.maxy.bot",
+    smbHostname: "smb.maxy.bot",
+  };
+  const parsed = JSON.parse(renderTunnelState(state));
+  assert.equal(parsed.sshHostname, "ssh.maxy.bot");
+  assert.equal(parsed.smbHostname, "smb.maxy.bot");
+});
+
+// ---------------------------------------------------------------------------
+// readPersistedHostnames
+// ---------------------------------------------------------------------------
+
+test("readPersistedHostnames: returns nulls when file missing", () => {
+  const got = readPersistedHostnames("/nope/does/not/exist.json");
+  assert.deepEqual(got, { sshHostname: null, smbHostname: null });
+});
+
+test("readPersistedHostnames: round-trips ssh/smb hostnames from disk", () => {
+  const dir = mkdtempSync(join(tmpdir(), "tunnel-state-"));
+  const path = join(dir, "tunnel.state");
+  try {
+    writeFileSync(
+      path,
+      JSON.stringify({
+        tunnelId: "abc",
+        tunnelName: "maxy",
+        domain: "admin.maxy.bot",
+        configPath: "/cfg.yml",
+        credentialsPath: "/creds.json",
+        sshHostname: "ssh.maxy.bot",
+        smbHostname: "smb.maxy.bot",
+      }),
+    );
+    const got = readPersistedHostnames(path);
+    assert.deepEqual(got, { sshHostname: "ssh.maxy.bot", smbHostname: "smb.maxy.bot" });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("readPersistedHostnames: malformed JSON returns nulls (no throw)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "tunnel-state-bad-"));
+  const path = join(dir, "tunnel.state");
+  try {
+    writeFileSync(path, "not json");
+    assert.deepEqual(readPersistedHostnames(path), { sshHostname: null, smbHostname: null });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// probeSambaStanza
+// ---------------------------------------------------------------------------
+
+test("probeSambaStanza: true when [<brand>] header present", () => {
+  const dir = mkdtempSync(join(tmpdir(), "smb-probe-"));
+  const path = join(dir, "smb.conf");
+  try {
+    writeFileSync(path, "[global]\nworkgroup = WORKGROUP\n\n[maxy]\n   path = /home/admin\n");
+    assert.equal(probeSambaStanza("maxy", path), true);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("probeSambaStanza: false when only peer brand present (isolation)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "smb-probe-peer-"));
+  const path = join(dir, "smb.conf");
+  try {
+    writeFileSync(path, "[global]\n\n[realagent]\n   path = /home/admin\n");
+    assert.equal(probeSambaStanza("maxy", path), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("probeSambaStanza: false when smb.conf missing", () => {
+  assert.equal(probeSambaStanza("maxy", "/nope/smb.conf"), false);
+});
+
+test("probeSambaStanza: brand names with regex meta characters are escaped", () => {
+  const dir = mkdtempSync(join(tmpdir(), "smb-probe-regex-"));
+  const path = join(dir, "smb.conf");
+  try {
+    writeFileSync(path, "[some.brand]\n   path = /x\n");
+    assert.equal(probeSambaStanza("some.brand", path), true);
+    assert.equal(probeSambaStanza("someXbrand", path), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// renderAccessPolicyActionRequired
+// ---------------------------------------------------------------------------
+
+test("renderAccessPolicyActionRequired: empty string when neither hostname set", () => {
+  assert.equal(
+    renderAccessPolicyActionRequired({ operatorEmail: "x@y.com" }),
+    "",
+  );
+});
+
+test("renderAccessPolicyActionRequired: lists each hostname with operator email", () => {
+  const out = renderAccessPolicyActionRequired({
+    sshHostname: "ssh.maxy.bot",
+    smbHostname: "smb.maxy.bot",
+    operatorEmail: "joel@example.com",
+  });
+  assert.match(out, /SSH: ssh\.maxy\.bot/);
+  assert.match(out, /SMB: smb\.maxy\.bot/);
+  assert.match(out, /Emails: joel@example\.com/);
+  assert.match(out, /Zero Trust → Access → Applications/);
+});

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -27,15 +27,20 @@
 
 set -euo pipefail
 
+# Resolve symlinks before dirname — ~/setup-tunnel.sh is installed as a symlink
+# (see packages/create-maxy-code/src/index.ts:installTunnelScripts), so the raw
+# BASH_SOURCE[0] points at $HOME, not the scripts directory where the sibling
+# helpers (_stream-log.sh, tunnel-ingress.ts) live. Factored to SCRIPT_DIR so
+# Task 600's stream-log-contract scanner can statically resolve the
+# tunnel-ingress.ts target (Task 054).
+SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
+
 # --------------------------------------------------------------------------
 # Shared stream-log helpers (require STREAM_LOG_PATH, phase_line, …).
 # --------------------------------------------------------------------------
 
 # shellcheck source=_stream-log.sh
-# Resolve symlinks before dirname — ~/setup-tunnel.sh is installed as a symlink
-# (see packages/create-maxy-code/src/index.ts:installTunnelScripts), so the raw
-# BASH_SOURCE[0] points at $HOME, not the scripts directory where _stream-log.sh lives.
-source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
+source "${SCRIPT_DIR}/_stream-log.sh"
 require_stream_log_path setup-tunnel
 
 # --------------------------------------------------------------------------
@@ -53,7 +58,39 @@ PORT="$2"
 shift 2
 HOSTNAMES=("$@")
 
-phase_line setup-tunnel step=start brand="${BRAND}" port="${PORT}" hostnames="${HOSTNAMES[*]}"
+# --------------------------------------------------------------------------
+# Task 009 — SSH/SMB ingress env vars.
+#
+# SSH and SMB hostnames arrive via environment, NOT positional argv, so the
+# existing form/endpoint contract (which passes admin/public/apex as
+# positionals) keeps working unchanged. The action-runner sets these env
+# vars when the operator submits the cloudflare-setup form with the SSH
+# and SMB fields populated; absent env vars mean "no SSH/SMB ingress this
+# run" — except when tunnel.state already persists them, in which case
+# rehydrate from there.
+#
+#   SSH_HOSTNAME      e.g. ssh.maxy.bot   → ingress service: ssh://localhost:22
+#   SMB_HOSTNAME      e.g. smb.maxy.bot   → ingress service: tcp://localhost:445
+#   OPERATOR_EMAIL    e.g. joel@x.com     → printed in the ACTION REQUIRED
+#                                            dashboard click-path for the
+#                                            Access policy (operator-authored;
+#                                            CF API is banned per
+#                                            feedback_cf_api_total_eradication)
+#
+# Re-run idempotency: if env vars are unset, the script reads sshHostname /
+# smbHostname from the existing tunnel.state (if present) so a re-run
+# without env vars doesn't silently drop the SSH/SMB ingress. tunnel.state
+# is rewritten with the resolved hostnames at the end of Step 5b.
+# --------------------------------------------------------------------------
+
+SSH_HOSTNAME="${SSH_HOSTNAME:-}"
+SMB_HOSTNAME="${SMB_HOSTNAME:-}"
+OPERATOR_EMAIL="${OPERATOR_EMAIL:-}"
+SETUP_TUNNEL_DRY_RUN="${SETUP_TUNNEL_DRY_RUN:-0}"
+
+phase_line setup-tunnel step=start brand="${BRAND}" port="${PORT}" hostnames="${HOSTNAMES[*]}" \
+  ssh_hostname="${SSH_HOSTNAME:-none}" smb_hostname="${SMB_HOSTNAME:-none}" \
+  dry_run="${SETUP_TUNNEL_DRY_RUN}"
 
 # --------------------------------------------------------------------------
 # Step 0: Set brand context (paths + dirs). Corresponds to runbook Step 0.
@@ -636,39 +673,241 @@ for H in "${HOSTNAMES[@]}"; do
 done
 
 # --------------------------------------------------------------------------
-# Step 5: Write config.yml. Every hostname (apex + subdomain) gets an
-# ingress rule — apex still needs the rule for the connector to serve
-# traffic once DNS is manually pointed.
+# Task 009 — Rehydrate SSH/SMB hostnames from tunnel.state when env unset.
+#
+# A re-run without SSH_HOSTNAME / SMB_HOSTNAME should keep the previously
+# configured ingress rather than silently dropping them. The Node helper
+# reads tunnel.state (if present) and prints a JSON {sshHostname, smbHostname}.
 # --------------------------------------------------------------------------
 
+TUNNEL_INGRESS_TS="${SCRIPT_DIR}/tunnel-ingress.ts"
+if [ ! -f "${TUNNEL_INGRESS_TS}" ]; then
+  phase_line setup-tunnel step=ingress-renderer-resolve result=error \
+    reason=helper-missing path="${TUNNEL_INGRESS_TS}"
+  echo "ERROR: tunnel-ingress.ts is missing at ${TUNNEL_INGRESS_TS}" >&2
+  exit 1
+fi
+
+if [ -z "${SSH_HOSTNAME}${SMB_HOSTNAME}" ] && [ -f "${CFG_DIR}/tunnel.state" ]; then
+  PERSISTED_JSON="$(node --experimental-strip-types --no-warnings "${TUNNEL_INGRESS_TS}" read-state "${CFG_DIR}/tunnel.state" 2>/dev/null || echo '{}')"
+  PERSISTED_SSH="$(printf '%s' "${PERSISTED_JSON}" | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{const o=JSON.parse(d);process.stdout.write(o.sshHostname||"")}catch{}})')"
+  PERSISTED_SMB="$(printf '%s' "${PERSISTED_JSON}" | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{const o=JSON.parse(d);process.stdout.write(o.smbHostname||"")}catch{}})')"
+  if [ -n "${PERSISTED_SSH}" ]; then
+    SSH_HOSTNAME="${PERSISTED_SSH}"
+    phase_line setup-tunnel step=ssh-hostname-rehydrated hostname="${SSH_HOSTNAME}"
+  fi
+  if [ -n "${PERSISTED_SMB}" ]; then
+    SMB_HOSTNAME="${PERSISTED_SMB}"
+    phase_line setup-tunnel step=smb-hostname-rehydrated hostname="${SMB_HOSTNAME}"
+  fi
+fi
+
+# --------------------------------------------------------------------------
+# Task 009 — Samba presence probe (gates SMB ingress on Task 034 stanza).
+#
+# Per Task 034, the brand's Samba stanza `[<brand>]` is written to
+# /etc/samba/smb.conf at install time. If the stanza is absent, this Pi
+# has no SMB share to expose and the SMB ingress is skipped loudly.
+# Probe via grep on the Pi filesystem (NOT brand.json — Samba is a
+# post-install side effect, not a declared field).
+# --------------------------------------------------------------------------
+
+if [ -n "${SMB_HOSTNAME}" ]; then
+  if ! node --experimental-strip-types --no-warnings "${TUNNEL_INGRESS_TS}" probe-samba "${BRAND}" /etc/samba/smb.conf >/dev/null 2>&1; then
+    phase_line setup-tunnel step=smb-ingress-skipped reason=samba-not-provisioned \
+      hostname="${SMB_HOSTNAME}" brand="${BRAND}"
+    echo "[tunnel-install] smb-ingress-skipped reason=samba-not-provisioned brand=${BRAND}"
+    echo "  Skipping SMB ingress: /etc/samba/smb.conf has no [${BRAND}] stanza."
+    echo "  Provision Samba first (the installer's post-install step does this); then re-run."
+    SMB_HOSTNAME=""
+  fi
+fi
+
+# --------------------------------------------------------------------------
+# Task 009 — Step 4b: Route DNS for SSH/SMB hostnames (after HTTPS pass).
+#
+# Two-phase ordering: HTTPS hostnames are routed first (loop above). If a
+# subsequent SSH or SMB route DNS fails, emit `*-ingress-deferred` and
+# continue WITHOUT exit 1, so the HTTPS ingress remains durable. Apex
+# hostnames are not valid for SSH/SMB (the hostnames are subdomains by
+# definition); no apex carve-out is needed.
+# --------------------------------------------------------------------------
+
+route_extra_hostname() {
+  local kind="$1"  # "ssh" or "smb"
+  local hostname="$2"
+  [ -z "${hostname}" ] && return 0
+
+  if [ "${SETUP_TUNNEL_DRY_RUN}" = "1" ]; then
+    phase_line setup-tunnel step="${kind}-route-dns" hostname="${hostname}" result=dry-run-skip
+    return 0
+  fi
+
+  phase_line setup-tunnel step="${kind}-route-dns" hostname="${hostname}" tunnel_id="${TUNNEL_ID}"
+  local ROUTE_LOG
+  ROUTE_LOG="$(mktemp -t "maxy-${kind}-route-dns.XXXXXX")"
+  if tee_subprocess_capture "setup-tunnel:cloudflared" -- \
+      cloudflared --origincert "${CFG_DIR}/cert.pem" \
+      tunnel route dns --overwrite-dns "${TUNNEL_ID}" "${hostname}" \
+      > "${ROUTE_LOG}"; then
+    phase_line setup-tunnel step="${kind}-route-dns" hostname="${hostname}" result=ok
+    rm -f "${ROUTE_LOG}"
+    return 0
+  fi
+  local ROUTE_RC=$?
+  local STDERR_BOUNDED
+  STDERR_BOUNDED="$(tr '\n' ' ' < "${ROUTE_LOG}" | head -c 400)"
+  phase_line setup-tunnel step="${kind}-ingress-deferred" hostname="${hostname}" \
+    reason=route-dns-failed exit="${ROUTE_RC}" stderr="${STDERR_BOUNDED}"
+  echo "WARNING: cloudflared tunnel route dns failed for ${hostname} (exit=${ROUTE_RC})." >&2
+  echo "         HTTPS ingress remains durable; the ${kind} ingress is deferred." >&2
+  rm -f "${ROUTE_LOG}"
+  # Clear the hostname so the config.yml render below skips this entry.
+  if [ "${kind}" = "ssh" ]; then SSH_HOSTNAME=""; else SMB_HOSTNAME=""; fi
+  return 0
+}
+
+route_extra_hostname ssh "${SSH_HOSTNAME}"
+route_extra_hostname smb "${SMB_HOSTNAME}"
+
+# --------------------------------------------------------------------------
+# Step 5: Write config.yml via the unit-tested Node renderer. Every HTTPS
+# hostname (apex + subdomain) gets an ingress rule — apex still needs the
+# rule for the connector to serve traffic once DNS is manually pointed.
+# SSH and SMB rules are inserted between the HTTPS rules and the catch-all
+# http_status:404 (renderer enforces ordering).
+# --------------------------------------------------------------------------
+
+INGRESS_SPEC_FILE="$(mktemp -t maxy-ingress-spec.XXXXXX.json)"
 {
-  echo "tunnel: ${TUNNEL_ID}"
-  echo "credentials-file: ${CFG_DIR}/${TUNNEL_ID}.json"
-  echo "ingress:"
+  printf '{'
+  printf '"tunnelId":"%s",' "${TUNNEL_ID}"
+  printf '"credentialsPath":"%s",' "${CFG_DIR}/${TUNNEL_ID}.json"
+  printf '"httpPort":%s,' "${PORT}"
+  printf '"httpHostnames":['
+  FIRST=1
   for H in "${HOSTNAMES[@]}"; do
-    echo "  - hostname: ${H}"
-    echo "    service: http://localhost:${PORT}"
+    if [ ${FIRST} -eq 1 ]; then FIRST=0; else printf ','; fi
+    printf '"%s"' "${H}"
   done
-  echo "  - service: http_status:404"
-} > "${CFG_DIR}/config.yml"
-echo "wrote ${CFG_DIR}/config.yml"
+  printf '],'
+  printf '"sshHostname":"%s",' "${SSH_HOSTNAME}"
+  printf '"smbHostname":"%s"' "${SMB_HOSTNAME}"
+  printf '}'
+} > "${INGRESS_SPEC_FILE}"
+
+if [ "${SETUP_TUNNEL_DRY_RUN}" = "1" ]; then
+  echo "--- DRY RUN: rendered config.yml ---"
+  node --experimental-strip-types --no-warnings "${TUNNEL_INGRESS_TS}" render-config "${INGRESS_SPEC_FILE}"
+  echo "--- DRY RUN: end ---"
+  phase_line setup-tunnel step=config-yml-write result=dry-run-skip
+else
+  if ! node --experimental-strip-types --no-warnings "${TUNNEL_INGRESS_TS}" render-config "${INGRESS_SPEC_FILE}" > "${CFG_DIR}/config.yml"; then
+    phase_line setup-tunnel step=config-yml-write result=error reason=renderer-failed
+    echo "ERROR: tunnel-ingress render-config failed" >&2
+    rm -f "${INGRESS_SPEC_FILE}"
+    exit 1
+  fi
+  echo "wrote ${CFG_DIR}/config.yml"
+fi
+rm -f "${INGRESS_SPEC_FILE}"
+
+if [ -n "${SSH_HOSTNAME}" ]; then
+  phase_line setup-tunnel step=ssh-ingress-added hostname="${SSH_HOSTNAME}" service=ssh://localhost:22
+  echo "[tunnel-install] ssh-ingress-added hostname=${SSH_HOSTNAME} service=ssh://localhost:22"
+fi
+if [ -n "${SMB_HOSTNAME}" ]; then
+  phase_line setup-tunnel step=smb-ingress-added hostname="${SMB_HOSTNAME}" service=tcp://localhost:445
+  echo "[tunnel-install] smb-ingress-added hostname=${SMB_HOSTNAME} service=tcp://localhost:445"
+fi
 
 # --------------------------------------------------------------------------
-# Step 5b: Write tunnel.state. Required by resume-tunnel.sh — without it
-# the brand.service's ExecStartPre exits silently without spawning a
-# connector.
+# Step 5b: Write tunnel.state via the same renderer. Additive sshHostname /
+# smbHostname fields let the next re-run rehydrate them. Required by
+# resume-tunnel.sh — without it the brand.service's ExecStartPre exits
+# silently without spawning a connector.
 # --------------------------------------------------------------------------
 
-cat > "${CFG_DIR}/tunnel.state" <<EOF
+STATE_SPEC_FILE="$(mktemp -t maxy-tunnel-state.XXXXXX.json)"
 {
-  "tunnelId": "${TUNNEL_ID}",
-  "tunnelName": "${TUNNEL_NAME}",
-  "domain": "${HOSTNAMES[0]}",
-  "configPath": "${CFG_DIR}/config.yml",
-  "credentialsPath": "${CFG_DIR}/${TUNNEL_ID}.json"
-}
-EOF
-echo "wrote ${CFG_DIR}/tunnel.state"
+  printf '{'
+  printf '"tunnelId":"%s",' "${TUNNEL_ID}"
+  printf '"tunnelName":"%s",' "${TUNNEL_NAME}"
+  printf '"domain":"%s",' "${HOSTNAMES[0]}"
+  printf '"configPath":"%s",' "${CFG_DIR}/config.yml"
+  printf '"credentialsPath":"%s",' "${CFG_DIR}/${TUNNEL_ID}.json"
+  printf '"sshHostname":"%s",' "${SSH_HOSTNAME}"
+  printf '"smbHostname":"%s"' "${SMB_HOSTNAME}"
+  printf '}'
+} > "${STATE_SPEC_FILE}"
+
+if [ "${SETUP_TUNNEL_DRY_RUN}" = "1" ]; then
+  echo "--- DRY RUN: rendered tunnel.state ---"
+  node --experimental-strip-types --no-warnings "${TUNNEL_INGRESS_TS}" render-state "${STATE_SPEC_FILE}"
+  echo "--- DRY RUN: end ---"
+  phase_line setup-tunnel step=tunnel-state-write result=dry-run-skip
+else
+  if ! node --experimental-strip-types --no-warnings "${TUNNEL_INGRESS_TS}" render-state "${STATE_SPEC_FILE}" > "${CFG_DIR}/tunnel.state"; then
+    phase_line setup-tunnel step=tunnel-state-write result=error reason=renderer-failed
+    echo "ERROR: tunnel-ingress render-state failed" >&2
+    rm -f "${STATE_SPEC_FILE}"
+    exit 1
+  fi
+  echo "wrote ${CFG_DIR}/tunnel.state"
+fi
+rm -f "${STATE_SPEC_FILE}"
+
+# --------------------------------------------------------------------------
+# Task 009 — Access policy ACTION REQUIRED.
+#
+# The Cloudflare Access policy that gates these new SSH/SMB hostnames must
+# be authored in the dashboard by the operator: CF API/SDK is banned
+# (feedback_cf_api_total_eradication) and `cloudflared` CLI has no
+# Access-application create subcommand. Print the click-path with the
+# resolved hostnames + operator email substituted in. operatorEmail comes
+# from OPERATOR_EMAIL env, falling back to brand.json `.operatorEmail`.
+# --------------------------------------------------------------------------
+
+if [ -n "${SSH_HOSTNAME}${SMB_HOSTNAME}" ]; then
+  RESOLVED_EMAIL="${OPERATOR_EMAIL}"
+  if [ -z "${RESOLVED_EMAIL}" ] && [ -n "${SETUP_TUNNEL_BRAND_JSON}" ] && command -v jq >/dev/null 2>&1; then
+    RESOLVED_EMAIL="$(jq -r '.operatorEmail // empty' "${SETUP_TUNNEL_BRAND_JSON}" 2>/dev/null || true)"
+  fi
+  if [ -z "${RESOLVED_EMAIL}" ]; then
+    RESOLVED_EMAIL="<operator email — set OPERATOR_EMAIL or brand.json .operatorEmail>"
+    phase_line setup-tunnel step=operator-email-unresolved reason=env-and-brand-json-missing
+  fi
+
+  if [ -n "${SSH_HOSTNAME}" ]; then
+    phase_line setup-tunnel step=ssh-access-policy-required hostname="${SSH_HOSTNAME}" allow_emails="${RESOLVED_EMAIL}"
+    echo "[tunnel-install] ssh-access-policy-required hostname=${SSH_HOSTNAME} allow-emails=${RESOLVED_EMAIL}"
+  fi
+  if [ -n "${SMB_HOSTNAME}" ]; then
+    phase_line setup-tunnel step=smb-access-policy-required hostname="${SMB_HOSTNAME}" allow_emails="${RESOLVED_EMAIL}"
+    echo "[tunnel-install] smb-access-policy-required hostname=${SMB_HOSTNAME} allow-emails=${RESOLVED_EMAIL}"
+  fi
+
+  AR_INPUT_FILE="$(mktemp -t maxy-access-req.XXXXXX.json)"
+  {
+    printf '{'
+    printf '"sshHostname":"%s",' "${SSH_HOSTNAME}"
+    printf '"smbHostname":"%s",' "${SMB_HOSTNAME}"
+    printf '"operatorEmail":"%s"' "${RESOLVED_EMAIL}"
+    printf '}'
+  } > "${AR_INPUT_FILE}"
+  node --experimental-strip-types --no-warnings "${TUNNEL_INGRESS_TS}" action-req "${AR_INPUT_FILE}" || true
+  rm -f "${AR_INPUT_FILE}"
+fi
+
+# --------------------------------------------------------------------------
+# Dry-run short-circuit: exit before onboarding / service restart.
+# --------------------------------------------------------------------------
+if [ "${SETUP_TUNNEL_DRY_RUN}" = "1" ]; then
+  phase_line setup-tunnel step=done dry_run=1
+  echo ""
+  echo "DRY RUN complete. No cloudflared mutations made; no service restart."
+  exit 0
+fi
 
 # --------------------------------------------------------------------------
 # Step 6: Persist onboarding step-7 completion BEFORE arming the restart.