@starci/hfs 4.2.17 → 4.4.0

package/stack/release-store.mjs

@@ -0,0 +1,87 @@
+// release-store.mjs - the release record protocol on the manager: /srv/<stack>/releases/<digest16>/{stack.yaml,release.json} behind the
+// stable `current` and `previous` pointers, which move only after verification. A JavaScript object over an injected ssh runner:
+//   ssh(command, { input }) -> { status, stdout, stderr }     runs a shell command on the manager (remote.mjs provides the real one)
+// Every remote command is composed ONLY from a validated release id (16 lowercase hex) and a validated base path, so no free text reaches
+// the remote shell. The record holds names and digests, never a secret value. Files travel as text on stdin / stdout.
+import fs from 'node:fs';
+import path from 'node:path';
+import { eachInOrder, mapInOrder } from '../runtime/scripts/lib/in-order.mjs';
+import { firstLine, lines as splitLines } from './context.mjs';
+import { isReleaseId } from './digest.mjs';
+import { failure, refusal } from './errors.mjs';
+
+const BASE = /^\/[A-Za-z0-9._/-]+$/u;
+const FILES = ['stack.yaml', 'release.json'];
+
+/** Removes every carriage return: a snippet from a Windows checkout must never reach a remote shell with CRLF. */
+export const lfOnly = (text) => String(text).replaceAll('\r', '');
+
+const checkedId = (id) => {
+  if (!isReleaseId(id)) throw refusal('STACK_RELEASE_ID', 'a release id is exactly 16 lowercase hex characters');
+  return id;
+};
+
+const checkedBase = (config) => {
+  const base = config.remote?.releasesBase ?? `/srv/${config.stack}`;
+  if (!BASE.test(base) || base.split('/').includes('..')) throw refusal('STACK_RELEASE_BASE', `the releases base ${base} must be an absolute path without ..`);
+  return base;
+};
+
+/**
+ * The release store of one stack. `ssh` is the runner; the returned API is async:
+ *   store(dir, id) accept(id) current() previous() fetch(id, targetDir) list()
+ */
+export function createReleaseStore(config, ssh) {
+  const base = checkedBase(config);
+  const dirOf = (id) => `${base}/releases/${checkedId(id)}`;
+
+  async function run(command, input) {
+    const answer = await ssh(lfOnly(command), { input });
+    if (answer.status !== 0) throw failure('STACK_RELEASE_SSH', `remote command failed: ${firstLine(answer.stderr)}`);
+    return answer.stdout;
+  }
+
+  function readLocal(dir, name) {
+    try { return fs.readFileSync(path.join(dir, name), 'utf8'); } catch { throw failure('STACK_RELEASE_STORE', `cannot read ${name} in ${dir}`); }
+  }
+
+  async function pointer(name) {
+    const out = await run(`cd "${base}" 2>/dev/null && [ -L ${name} ] && basename "$(readlink ${name})" || true`);
+    const id = out.trim();
+    return isReleaseId(id) ? id : '';
+  }
+
+  return {
+    /** Uploads stack.yaml and release.json of a rendered release as text; read-only afterwards. */
+    async store(dir, id) {
+      const target = dirOf(id);
+      const contents = FILES.map((name) => [name, readLocal(dir, name)]);
+      await run(`set -e; d="${target}"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi`);
+      await eachInOrder(contents, ([name, text]) => run(`set -e; d="${target}"; cat > "$d/${name}"`, text));
+      await run(`set -e; d="${target}"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"`);
+    },
+    /** The release was verified: previous := current, current := id. */
+    async accept(id) {
+      checkedId(id);
+      await run(`set -e; cd "${base}"; test -d "releases/${id}"; if [ -L current ] && [ "$(basename "$(readlink current)")" != "${id}" ]; then ln -sfn "$(readlink current)" previous; fi; ln -sfn "releases/${id}" current.new; mv -Tf current.new current`);
+    },
+    /** The accepted release id, '' when none. */
+    current: () => pointer('current'),
+    /** The release accepted before the current one, '' when none. */
+    previous: () => pointer('previous'),
+    /** Downloads a stored release (both files) into `targetDir` for a rollback or an audit. */
+    async fetch(id, targetDir) {
+      const source = dirOf(id);
+      const files = await mapInOrder(FILES, async (name) => [name, await run(`cat "${source}/${name}"`)]);
+      fs.mkdirSync(targetDir, { recursive: true });
+      for (const [name, text] of files) fs.writeFileSync(path.join(targetDir, name), text);
+      return targetDir;
+    },
+    /** The stored releases, newest first: [{ id, current, previous }]. */
+    async list() {
+      const [now, before] = [await pointer('current'), await pointer('previous')];
+      const out = await run(`cd "${base}/releases" 2>/dev/null && ls -1t || true`);
+      return splitLines(out).filter(isReleaseId).map((id) => ({ id, current: id === now, previous: id === before }));
+    },
+  };
+}

package/stack/remote.mjs

@@ -0,0 +1,205 @@
+// remote.mjs - how the stack verbs reach the Swarm manager: the ssh runner, remote command quoting, the CI transport setup.
+//   sshRunner(ctx, config, { sshCmd })  -> run(command, { input }) -> { status, stdout, stderr }   (`.cleanup()`, `.notes`)
+//   transports, in this order: --ssh-cmd "ssh vps" (no shell) -> the owner-machine session opened from the sealed members
+//   (only when config.remote.sealed is declared and STARCI_STACK_SEALED_SSH=1) -> the ssh alias config.remote.host (CI after `connect`,
+//   or the operator's own ssh config).
+//   connectCi / disconnectCi            GitHub Actions: write and remove the pinned key, known_hosts, ssh config and DOCKER_HOST.
+// A remote command is ONE ssh argument with every carriage return removed (lfOnly: a script that reached a Windows checkout with CRLF made
+// `bash -s` fail with `set: pipefail`). Key material lives in memory and in a private temp directory only; it is never in argv (only the key
+// FILE path is), in a line, in a result or in an error message.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { tool } from './context.mjs';
+import { restrictToUser, writePrivate } from './private-file.mjs';
+import { refusal } from './errors.mjs';
+
+const ACCOUNT = /^[A-Za-z0-9._@-]+$/u;
+const CI_VARIABLES = ['VPS_SSH_KEY', 'VPS_KNOWN_HOSTS', 'VPS_HOST', 'VPS_USER'];
+const SSH_OPTIONS = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20'];
+
+/** Removes every carriage return. */
+export const lfOnly = (text) => String(text).replaceAll('\r', '');
+
+/** POSIX single-quote quoting; NUL and line breaks cannot be quoted safely and are refused. */
+export function shellQuote(value) {
+  const text = String(value);
+  if (text.includes('\0') || /[\r\n]/u.test(text)) throw refusal('STACK_REMOTE_ARGUMENT', 'a remote argument must not contain NUL or a line break');
+  return ["'", text.replaceAll("'", String.raw`'\''`), "'"].join('');
+}
+
+/** Runs `docker <args>` on the manager through `run` (every argument quoted). */
+export const remoteDocker = (run, args) => run(['docker', ...args.map(shellQuote)].join(' '));
+
+const noop = () => {};
+
+function makeRunner(ctx, argv, { cleanup = noop, notes = [] } = {}) {
+  const [command, ...head] = argv;
+  const run = (remote, { input } = {}) => {
+    const options = input === undefined ? {} : { input: lfOnly(input) };
+    const result = tool(ctx, command, [...head, lfOnly(remote)], options);
+    if (result.error) return { status: 127, stdout: '', stderr: `cannot run ${command}: ${result.error.message}` };
+    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+  };
+  return Object.assign(run, { cleanup, notes });
+}
+
+function sshCommandArgv(sshCmd) {
+  const parts = String(sshCmd).split(/\s+/u).filter(Boolean);
+  if (parts.length === 0) throw refusal('STACK_REMOTE_SSH_CMD', '--ssh-cmd is empty');
+  return parts;
+}
+
+/** A sealed binary member is the file itself; a JSON object around it ({ data | <names> }, the re-sealed shape of `starci app secret rename`) is unwrapped. */
+function unwrap(text, names) {
+  const body = lfOnly(text);
+  const trimmed = body.trim();
+  if (!trimmed.startsWith('{')) return body;
+  let parsed;
+  try { parsed = JSON.parse(trimmed); } catch { return body; }
+  for (const name of ['data', ...names]) if (typeof parsed[name] === 'string') return lfOnly(parsed[name]);
+  return body;
+}
+
+function openMember(slug, read) {
+  try { return read(); } catch (error) { throw refusal('STACK_REMOTE_SEALED', `cannot open the sealed member ${slug}: ${error.message}`); }
+}
+
+function opsAccount(ctx, config) {
+  const slug = config.remote.sealed.ops;
+  const map = openMember(slug, () => ctx.sops.decrypt(path.join(config.secretsDir, `${slug}.enc`), 'dotenv'));
+  for (const name of ['VPS_HOST', 'VPS_USER']) {
+    const value = map[name];
+    if (typeof value !== 'string' || !ACCOUNT.test(value) || value.startsWith('-')) throw refusal('STACK_REMOTE_OPS', `${slug} must hold ${name} (letters, digits, . _ @ -)`);
+  }
+  return `${map.VPS_USER}@${map.VPS_HOST}`;
+}
+
+function binaryMember(ctx, config, slug, names) {
+  return unwrap(openMember(slug, () => ctx.sops.decryptBinary(path.join(config.secretsDir, `${slug}.enc`))), names);
+}
+
+const withNewline = (text) => `${text.trim()}\n`;
+
+/** CI (a Linux runner): the file with exactly this mode. */
+function writeWithMode(file, text, mode) {
+  fs.writeFileSync(file, text, { mode });
+  fs.chmodSync(file, mode);
+}
+
+/** The owner-machine session files: key and known_hosts in a private temp directory, removed (key overwritten) by cleanup(). */
+export function openSealedSession(ctx, config) {
+  const { sealed } = config.remote;
+  const account = opsAccount(ctx, config);
+  const key = binaryMember(ctx, config, sealed.sshKey, ['privateKey', 'key']);
+  if (!key.includes('PRIVATE KEY')) throw refusal('STACK_REMOTE_KEY', `${sealed.sshKey} does not hold a PEM private key`);
+  const known = binaryMember(ctx, config, sealed.knownHosts, ['knownHosts', 'known_hosts']).trim();
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-ssh-'));
+  const keyFile = path.join(dir, 'id');
+  const knownFile = path.join(dir, 'known_hosts');
+  const cleanup = () => {
+    if (fs.existsSync(keyFile)) {
+      restrictToUser(ctx, keyFile, 'F');
+      fs.writeFileSync(keyFile, '0'.repeat(key.length));
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+  };
+  try {
+    writePrivate(ctx, keyFile, withNewline(key));
+    writePrivate(ctx, knownFile, known ? withNewline(known) : '');
+  } catch (error) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    throw error;
+  }
+  const notes = known ? [] : ['owner-machine session without known_hosts: the host key is accepted on first contact (accept-new); verify it, CI never does this'];
+  return { account, dir, keyFile, knownFile, strict: known ? 'yes' : 'accept-new', notes, cleanup };
+}
+
+/** The owner-machine runner over that session. */
+function sealedRunner(ctx, config) {
+  const session = openSealedSession(ctx, config);
+  const argv = ['ssh', '-T', '-i', session.keyFile, '-o', 'IdentitiesOnly=yes', '-o', `UserKnownHostsFile=${session.knownFile}`, '-o', `StrictHostKeyChecking=${session.strict}`, '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20', session.account];
+  return makeRunner(ctx, argv, { cleanup: session.cleanup, notes: session.notes });
+}
+
+/** The ssh runner of one invocation (see the top of the file). */
+export function sshRunner(ctx, config, { sshCmd = null } = {}) {
+  if (sshCmd) return makeRunner(ctx, sshCommandArgv(sshCmd));
+  if (config.remote.sealed && ctx.env.STARCI_STACK_SEALED_SSH === '1') return sealedRunner(ctx, config);
+  return makeRunner(ctx, ['ssh', ...SSH_OPTIONS, config.remote.host]);
+}
+
+/**
+ * The context to open the runner with. On an operator machine (not CI, no --ssh-cmd, the sealed members exist, no explicit
+ * STARCI_STACK_SEALED_SSH) the sealed session is selected; otherwise the context is returned unchanged.
+ */
+export function withOwnerTransport(ctx, config, { sshCmd = null } = {}) {
+  const { sealed } = config.remote;
+  if (sshCmd || !sealed || ctx.env.GITHUB_ACTIONS === 'true' || ctx.env.STARCI_STACK_SEALED_SSH !== undefined) return ctx;
+  const present = [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(path.join(config.secretsDir, `${slug}.enc`)));
+  if (!present) return ctx;
+  return Object.create(ctx, { env: { value: { ...ctx.env, STARCI_STACK_SEALED_SSH: '1' }, enumerable: true } });
+}
+
+/** The runner of a verb that opens it itself (deploy, rollback, accept): the owner-machine session is selected exactly as `withRunner` does. */
+export const ownerSshRunner = (ctx, config, options = {}) => sshRunner(withOwnerTransport(ctx, config, options), config, options);
+
+/** Opens the runner (`deps.ssh` wins in specs), calls `body(run, notes)` and always cleans the session up. */
+export async function withRunner(ctx, config, options, deps, body) {
+  const run = deps.ssh ?? sshRunner(withOwnerTransport(ctx, config, options), config, options);
+  try {
+    return await body(run, run.notes ?? []);
+  } finally {
+    run.cleanup?.();
+  }
+}
+
+function ciHome(ctx) {
+  if (ctx.env.GITHUB_ACTIONS !== 'true') throw refusal('STACK_CONNECT_CI_ONLY', 'connect and disconnect run only in GitHub Actions (GITHUB_ACTIONS=true)');
+  if (!ctx.env.HOME) throw refusal('STACK_CONNECT_NO_HOME', 'HOME is not set');
+  return path.join(ctx.env.HOME, '.ssh');
+}
+
+function ciInputs(ctx) {
+  for (const name of CI_VARIABLES) if (!ctx.env[name]) throw refusal('STACK_CONNECT_MISSING', `${name} is not set`);
+  for (const name of ['VPS_HOST', 'VPS_USER']) {
+    if (!ACCOUNT.test(ctx.env[name]) || ctx.env[name].startsWith('-')) throw refusal('STACK_CONNECT_INVALID', `${name} must match ${ACCOUNT}`);
+  }
+  const key = lfOnly(ctx.env.VPS_SSH_KEY);
+  if (!key.includes('PRIVATE KEY')) throw refusal('STACK_CONNECT_INVALID', 'VPS_SSH_KEY is not a PEM private key');
+  if (!ctx.env.GITHUB_ENV) throw refusal('STACK_CONNECT_NO_GITHUB_ENV', 'GITHUB_ENV is not set');
+  return { key: withNewline(key), known: withNewline(lfOnly(ctx.env.VPS_KNOWN_HOSTS)), host: ctx.env.VPS_HOST, user: ctx.env.VPS_USER };
+}
+
+const sshBlock = (alias, inputs) => [
+  '', `Host ${alias}`, `  HostName ${inputs.host}`, `  User ${inputs.user}`, '  IdentityFile ~/.ssh/deploy_key',
+  '  StrictHostKeyChecking yes', '  BatchMode yes', '  ConnectTimeout 20', '  ServerAliveInterval 30',
+  '  ControlMaster auto', '  ControlPath ~/.ssh/cm-%C', '  ControlPersist 15m', '',
+].join('\n');
+
+/** CI transport: pinned key, known_hosts, ssh config block and DOCKER_HOST=ssh://<alias> in $GITHUB_ENV. */
+export async function connectCi(ctx, config, { execute = false } = {}) {
+  const dir = ciHome(ctx);
+  const inputs = ciInputs(ctx);
+  const alias = config.remote.host;
+  const plan = [`${dir}/deploy_key (0600) from VPS_SSH_KEY`, `${dir}/known_hosts (0644) from VPS_KNOWN_HOSTS`, `a Host ${alias} block in ${dir}/config`, `DOCKER_HOST=ssh://${alias} in GITHUB_ENV`];
+  const data = { host: alias, files: ['deploy_key', 'known_hosts', 'config'] };
+  if (!execute) return { ok: true, lines: plan.map((item) => `dry run: would write ${item}`), data };
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeWithMode(path.join(dir, 'deploy_key'), inputs.key, 0o600);
+  writeWithMode(path.join(dir, 'known_hosts'), inputs.known, 0o644);
+  fs.appendFileSync(path.join(dir, 'config'), sshBlock(alias, inputs), { mode: 0o600 });
+  fs.appendFileSync(ctx.env.GITHUB_ENV, `DOCKER_HOST=ssh://${alias}\n`);
+  return { ok: true, lines: plan.map((item) => `wrote ${item}`), data };
+}
+
+/** CI cleanup: closes the ssh control master (failure ignored) and removes the deploy key. */
+export async function disconnectCi(ctx, config, { execute = false } = {}) {
+  const dir = ciHome(ctx);
+  const alias = config.remote.host;
+  const data = { host: alias };
+  if (!execute) return { ok: true, lines: [`dry run: would run ssh -O exit ${alias} and remove ${dir}/deploy_key`], data };
+  tool(ctx, 'ssh', ['-O', 'exit', alias]);
+  fs.rmSync(path.join(dir, 'deploy_key'), { force: true });
+  return { ok: true, lines: [`closed the ssh session to ${alias} and removed ${dir}/deploy_key`], data };
+}

package/stack/render.mjs

@@ -0,0 +1,149 @@
+// render.mjs - renders a release: the committed stack source plus a generated override (image references, plain environment, the
+// `<KEY>_FILE` pointers and the versioned secret grants) resolved by `docker stack config`. Writes `stack.generated.yaml`, `stack.yaml`
+// and `release.json` under the output directory, and nothing at all when a guard refuses. Output carries names and counts only; the
+// docker child gets a minimal environment, never the age identity or DOCKER_HOST.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { tool } from './context.mjs';
+import { hasPlaceholderDigest, isImageReference, isReleaseId } from './digest.mjs';
+import { failure, refusal } from './errors.mjs';
+import { configObjects, loadSealed, sha } from './sealed.mjs';
+
+const SOURCE_SHA = /^[0-9a-f]{7,64}$/u;
+const ENV_LINE = /^([A-Z][A-Z0-9_]*)=(.*)$/u;
+const BASE_ENV = ['PATH', 'HOME', 'USERPROFILE', 'SystemRoot', 'TEMP', 'TMP', 'DOCKER_CONFIG'];
+const SECRET_MODE = 0o444;
+
+function checkImages(config, options) {
+  const wanted = Object.keys(config.images);
+  const given = Object.keys(options.images ?? {});
+  const missing = wanted.filter((service) => !given.includes(service));
+  if (missing.length > 0) throw refusal('STACK_IMAGE_MISSING', `no image given for ${missing.join(', ')}`);
+  const unknown = given.filter((service) => !wanted.includes(service));
+  if (unknown.length > 0) throw refusal('STACK_IMAGE_UNKNOWN', `${unknown.join(', ')} is not an image of the deploy block`);
+  for (const service of wanted) {
+    const reference = options.images[service];
+    if (hasPlaceholderDigest(reference)) throw refusal('STACK_PLACEHOLDER_DIGEST', `the image of ${service} carries the all-zero placeholder digest`);
+    if (!isImageReference(reference, options.allowUnpinned === true)) throw refusal('STACK_IMAGE_UNPINNED', `the image of ${service} must be a registry reference pinned by @sha256 digest`);
+  }
+}
+
+function checkInputs(config, options) {
+  checkImages(config, options);
+  if (!SOURCE_SHA.test(String(options.sourceSha))) throw refusal('STACK_SOURCE_SHA_INVALID', 'sourceSha must be 7 to 64 lowercase hex characters');
+  if (options.previous !== null && options.previous !== undefined && !isReleaseId(options.previous)) throw refusal('STACK_PREVIOUS_INVALID', 'previous must be 16 lowercase hex characters');
+}
+
+/** Compose interpolation treats `$` specially; the override doubles it so a value reaches the service unchanged. */
+const escapeDollar = (value) => value.replaceAll('$', '$$$$');
+
+function envFile(config, rel) {
+  const out = {};
+  for (const line of fs.readFileSync(path.join(config.envDir, rel), 'utf8').split(/\r?\n/u)) {
+    const match = ENV_LINE.exec(line);
+    if (match) out[match[1]] = match[2];
+  }
+  return out;
+}
+
+function plainEnvironment(config, settings, entry) {
+  const out = {};
+  for (const rel of entry.files) Object.assign(out, envFile(config, rel));
+  Object.assign(out, entry.values);
+  for (const [name, setting] of Object.entries(entry.settings)) {
+    const value = settings[setting.key] ?? setting.default;
+    if (value !== null) out[name] = value;
+  }
+  return out;
+}
+
+function serviceOverride(config, sealed, images, service) {
+  const grant = config.secrets.grants.find((item) => item.service === service);
+  const environment = plainEnvironment(config, sealed.settings, config.environment[service] ?? { files: [], values: {}, settings: {} });
+  const keys = sealed.grants[service] ?? [];
+  if (grant?.filePointers) for (const key of keys) environment[`${key}_FILE`] = `/run/secrets/${key}`;
+  const out = {};
+  if (images[service] !== undefined) out.image = images[service];
+  if (Object.keys(environment).length > 0) out.environment = Object.fromEntries(Object.entries(environment).map(([name, value]) => [name, escapeDollar(String(value))]));
+  if (keys.length > 0) out.secrets = keys.map((key) => ({ source: key, target: key, mode: SECRET_MODE }));
+  return out;
+}
+
+function buildOverride(config, sealed, images) {
+  const services = new Set([...Object.keys(config.images), ...Object.keys(config.environment), ...Object.keys(sealed.grants)]);
+  return {
+    services: Object.fromEntries([...services].sort((a, b) => a.localeCompare(b)).map((service) => [service, serviceOverride(config, sealed, images, service)])),
+    secrets: Object.fromEntries(Object.entries(sealed.secrets).map(([key, entry]) => [key, { external: true, name: entry.runtimeName }])),
+  };
+}
+
+function minimalEnv(ctx, config, configs) {
+  const env = {};
+  for (const name of BASE_ENV) if (ctx.env[name] !== undefined) env[name] = ctx.env[name];
+  for (const name of config.passEnv) env[name] = ctx.env[name] ?? '';
+  for (const object of configs) env[object.env] = object.name;
+  return env;
+}
+
+function dockerRender(ctx, config, overrideFile, options, env) {
+  const files = [config.stackFile, overrideFile, ...(options.extraCompose ?? [])].flatMap((file) => ['-c', file]);
+  const run = tool(ctx, 'docker', ['stack', 'config', ...files], { env });
+  if (run.error) throw failure('STACK_RENDER_FAILED', `cannot run docker (${run.error.message})`);
+  if (run.status !== 0) throw failure('STACK_RENDER_FAILED', run.stderr.trim().split('\n').slice(0, 6).join(' | '));
+  if (hasPlaceholderDigest(run.stdout)) throw refusal('STACK_PLACEHOLDER_DIGEST', 'rendered stack still carries a placeholder digest');
+  return run.stdout;
+}
+
+function releaseRecord(ctx, config, parts) {
+  const { sealed, configs, options, stackBytes, env } = parts;
+  const passed = Object.fromEntries(config.passEnv.map((name) => [name, env[name]]));
+  const digestInput = { environment: config.environment, settings: Object.entries(sealed.settings).sort(([a], [b]) => a.localeCompare(b)), configs: configs.map((item) => item.name), passed };
+  return {
+    schema: 'starci/stack-release@1',
+    stack: config.stack,
+    releaseDigest: sha(stackBytes),
+    sourceSha: options.sourceSha,
+    images: options.images,
+    configDigest: sha(JSON.stringify(digestInput)),
+    configs: configs.map((item) => ({ logical: item.logical, name: item.name })),
+    secrets: Object.entries(sealed.secrets).map(([key, entry]) => ({ key, runtimeName: entry.runtimeName })).sort((a, b) => a.key.localeCompare(b.key)),
+    healthAssertions: [...config.verify.http, ...config.verify.exec].map((check) => check.name),
+    previousAccepted: options.previous ?? null,
+    renderedAt: new Date(ctx.now()).toISOString(),
+  };
+}
+
+function writeOutput(out, override, stackBytes, release) {
+  fs.mkdirSync(out, { recursive: true });
+  fs.writeFileSync(path.join(out, 'stack.generated.yaml'), `${JSON.stringify(override, null, 2)}\n`);
+  fs.writeFileSync(path.join(out, 'stack.yaml'), stackBytes);
+  fs.writeFileSync(path.join(out, 'release.json'), `${JSON.stringify(release, null, 2)}\n`);
+}
+
+/** Renders a release into `options.out` (a fresh temp directory when null). Effects stay local; nothing leaves the machine. */
+export async function renderRelease(ctx, config, options) {
+  checkInputs(config, options);
+  const sealed = loadSealed(ctx, config);
+  const configs = configObjects(config);
+  const override = buildOverride(config, sealed, options.images);
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-override-'));
+  try {
+    const overrideFile = path.join(scratch, 'stack.generated.yaml');
+    fs.writeFileSync(overrideFile, `${JSON.stringify(override, null, 2)}\n`);
+    const env = minimalEnv(ctx, config, configs);
+    const stackBytes = dockerRender(ctx, config, overrideFile, options, env);
+    const release = releaseRecord(ctx, config, { sealed, configs, options, stackBytes, env });
+    const out = options.out ?? fs.mkdtempSync(path.join(os.tmpdir(), 'stack-render-'));
+    writeOutput(out, override, stackBytes, release);
+    const releaseId = release.releaseDigest.slice(0, 16);
+    const counts = { secrets: release.secrets.length, configs: configs.length };
+    return {
+      ok: true,
+      lines: [`render: release ${releaseId}: ${counts.secrets} secrets, ${counts.configs} configs; images pinned`, `out: ${out}`],
+      data: { releaseDigest: release.releaseDigest, releaseId, out, ...counts },
+    };
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}

package/stack/retire.mjs

@@ -0,0 +1,47 @@
+// retire.mjs - `starci app stack retire --project <compose project>... [--execute]`: stops the containers of the OLD docker compose projects once the swarm
+// stack has taken over, WITHOUT removing anything. Each container gets `--restart=no` first (a restart policy or a reboot would otherwise start the old
+// model again beside the new one), then `docker stop`; applications first, data stores last (the reverse of the recovery order). Containers, volumes,
+// images and networks stay, so the old model can be started again for a rollback. The legacy edge container is never touched here (it is kept stopped
+// by the takeover for its own retention), and a project that holds it is refused.
+import { refusal } from './errors.mjs';
+import { remoteDocker, withRunner } from './remote.mjs';
+import { snapshotContainers, startOrder } from './live-restore.mjs';
+
+const PROJECT = /^[a-z0-9][a-z0-9_-]*$/u;
+const STOP_GRACE_SECONDS = 45;
+
+function checkProjects(config, projects) {
+  if (projects.length === 0) throw refusal('STACK_RETIRE_NO_PROJECT', 'name the compose projects to retire with --project <name> (repeatable)');
+  for (const project of projects) {
+    if (!PROJECT.test(project)) throw refusal('STACK_RETIRE_PROJECT', `${project} is not a compose project name`);
+    if (project === config.stack) throw refusal('STACK_RETIRE_PROJECT', `${project} is the swarm stack, not an old compose project`);
+  }
+}
+
+/** The running containers of the selected projects, applications first and data stores last. */
+function selected(run, projects) {
+  const all = snapshotContainers(run);
+  const chosen = all.filter((entry) => projects.includes(entry.project));
+  return startOrder(chosen).reverse();
+}
+
+/** `retire`: dry run unless execute. */
+export async function retireCompose(ctx, config, { projects = [], execute = false, sshCmd = null } = {}, deps = {}) {
+  checkProjects(config, projects);
+  return withRunner(ctx, config, { sshCmd }, deps, (run, notes) => {
+    const containers = selected(run, projects);
+    const edge = config.ingress?.legacy?.container;
+    if (edge && containers.some((entry) => entry.name === edge)) throw refusal('STACK_RETIRE_EDGE', `the project of ${edge} (the legacy edge) is not retired here: the takeover keeps that container stopped for its own retention`);
+    const lines = [...notes, `${containers.length} running container(s) in ${projects.join(', ')}: ${containers.map((entry) => entry.name).join(', ') || 'none'}`];
+    if (containers.length === 0) return { ok: true, lines: [...lines, 'nothing to retire'], data: { stopped: [], failed: [] } };
+    if (!execute) return { ok: true, lines: [...lines, 'dry run: each would get --restart=no and then be stopped (nothing is removed)'], data: { stopped: [], failed: [] } };
+    const stopped = [];
+    const failed = [];
+    for (const entry of containers) {
+      const done = remoteDocker(run, ['update', '--restart=no', entry.name]).status === 0 && remoteDocker(run, ['stop', '-t', String(STOP_GRACE_SECONDS), entry.name]).status === 0;
+      (done ? stopped : failed).push(entry.name);
+    }
+    const outcome = failed.length === 0 ? `retired ${stopped.length} container(s); nothing was removed, start them again with docker start for a rollback` : `FAILED to retire: ${failed.join(', ')}`;
+    return { ok: failed.length === 0, lines: [...lines, outcome], data: { stopped, failed } };
+  });
+}

package/stack/sealed.mjs

@@ -0,0 +1,149 @@
+// sealed.mjs - opens the sealed custody members in memory and derives, from names and keyed hashes only, which Swarm secret each
+// service is granted (the shared half of the release tools). No value is ever written to disk, printed or put in an argument list:
+// callers receive `value` and must keep it in memory. Config objects (non-secret files mounted into services) are versioned by content.
+import { createHash, createHmac } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { secretRoots } from '../runtime/scripts/hfs/secret-files.mjs';
+import { readMap } from '../runtime/scripts/hfs/secret-store.mjs';
+import { refusal } from './errors.mjs';
+
+const KEY_NAME = /^[A-Z][A-Z0-9_]*$/u;
+const UNSAFE_SETTING = /[\r\n"'\\]/u;
+const MAX_NAME = 64;
+
+/** sha256 of the bytes, as lowercase hex. */
+export const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+const CR = String.fromCodePoint(13);
+const LF = String.fromCodePoint(10);
+
+/** True for content that is not text: a NUL byte in the first 8 KiB. Binary files are never rewritten. */
+export const isBinary = (bytes) => bytes.subarray(0, 8192).includes(0);
+
+/** Every CRLF of a string becomes LF. */
+export const lfText = (text) => text.replaceAll(CR + LF, LF);
+
+/**
+ * Line endings of a text file as the services need them: every CRLF becomes LF (a script rendered from a Windows checkout failed with
+ * `set: Illegal option -`). Binary content is returned untouched. Takes and returns a Buffer.
+ */
+export function lfBytes(bytes) {
+  if (isBinary(bytes) || !bytes.includes(13)) return bytes;
+  return Buffer.from(lfText(bytes.toString('latin1')), 'latin1');
+}
+
+/** The bytes of a config file as they are hashed and created: LF-normalised text, untouched binary. */
+export const configBytes = (file) => lfBytes(fs.readFileSync(file));
+
+/** The key that makes the version suffix of a secret name unguessable from the name alone: a local fixture key or the age identity. */
+export function versionKeyOf(ctx) {
+  const key = ctx.env.STARCI_SECRET_VERSION_KEY || ctx.env.SOPS_AGE_KEY;
+  if (!key) throw refusal('STACK_VERSION_KEY_MISSING', 'STARCI_SECRET_VERSION_KEY (a local fixture) or SOPS_AGE_KEY is needed to version the secret names');
+  return key;
+}
+
+/** `<stack>-<key>-v<10 hex of HMAC(versionKey, key NUL value)>`: a changed value is a new name, an unchanged one keeps its name. */
+export function secretRuntimeName(stack, key, value, versionKey) {
+  const version = createHmac('sha256', versionKey).update(`${key}\0${value}`).digest('hex').slice(0, 10);
+  const name = `${stack}-${key.toLowerCase().replaceAll('_', '-')}-v${version}`;
+  if (name.length > MAX_NAME) throw refusal('STACK_SECRET_NAME_TOO_LONG', `the Swarm secret name for ${key} would exceed ${MAX_NAME} characters`);
+  return name;
+}
+
+const AGE_IDENTITY_ENV = /^SOPS_AGE_KEY(?:_FILE)?$/iu;
+const AGE_HINT = 'load the age identity into SOPS_AGE_KEY (the secret.env of the owner machine, or the CI secret) and retry';
+
+/** True when an age identity is reachable: SOPS_AGE_KEY or SOPS_AGE_KEY_FILE in the environment, the repository's .claude/secret.env or the per-user keys.txt. */
+export function hasAgeIdentity(ctx, config) {
+  const named = Object.entries(ctx.env).some(([name, value]) => AGE_IDENTITY_ENV.test(name) && value);
+  return named || fs.existsSync(path.join(config.repoRoot, '.claude', 'secret.env')) || fs.existsSync(secretRoots(ctx.env).identity);
+}
+
+/** Refuses up front, before any work, when sealed custody must be opened and no age identity is reachable. */
+export function requireAgeIdentity(ctx, config, purpose) {
+  if (!hasAgeIdentity(ctx, config)) throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available: ${AGE_HINT}`);
+}
+
+/** Opens one sealed member (`<secretsDir>/<member>.enc`) into a { KEY: value } map. Names the member only on failure. */
+export function openMember(ctx, config, member) {
+  try {
+    const map = readMap(path.join(config.secretsDir, `${member}.enc`), ctx.sops);
+    return Object.fromEntries(Object.entries(map).map(([key, value]) => [key, typeof value === 'string' && !value.includes(String.fromCodePoint(0)) ? lfText(value) : value]));
+  } catch {
+    throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened${hasAgeIdentity(ctx, config) ? ' (is the age identity a recipient of this member?)' : `: no age identity is available, ${AGE_HINT}`}`);
+  }
+}
+
+const present = (map, key) => typeof map[key] === 'string' && map[key] !== '';
+
+function sourceKeys(map, source) {
+  if (source.keys !== null) return source.keys;
+  return Object.keys(map).filter((key) => KEY_NAME.test(key) && !key.endsWith('_FILE'));
+}
+
+/** The KEY -> value pairs one grant source contributes, given what the same service already holds. */
+function takeFromSource(map, source, held) {
+  const taken = {};
+  for (const key of sourceKeys(map, source)) {
+    if (!present(map, key)) {
+      if (source.required) throw refusal('STACK_SECRET_MISSING', `the sealed member ${source.member} has no value for ${key}`);
+    } else if (!(source.fill && Object.hasOwn(held, key))) taken[key] = map[key];
+  }
+  return taken;
+}
+
+function serviceValues(grant, memberOf) {
+  const held = {};
+  for (const source of grant.from) Object.assign(held, takeFromSource(memberOf(source.member), source, held));
+  return held;
+}
+
+function sealGrants(config, memberOf, versionKey) {
+  const grants = {};
+  const secrets = {};
+  const owner = {};
+  for (const grant of config.secrets.grants) {
+    const values = { ...grants[grant.service]?.values, ...serviceValues(grant, memberOf) };
+    grants[grant.service] = { values };
+    for (const [key, value] of Object.entries(values)) {
+      if (Object.hasOwn(secrets, key) && secrets[key].value !== value) throw refusal('STACK_SECRET_CONFLICT', `${key} has different values for ${owner[key]} and ${grant.service}`);
+      owner[key] ??= grant.service;
+      secrets[key] ??= { runtimeName: secretRuntimeName(config.stack, key, value, versionKey), value };
+    }
+  }
+  return { secrets, grants: Object.fromEntries(Object.entries(grants).map(([service, entry]) => [service, Object.keys(entry.values).sort()])) };
+}
+
+function sealSettings(config, memberOf) {
+  const block = config.secrets.settings;
+  if (block === null) return {};
+  const map = memberOf(block.member);
+  const settings = {};
+  for (const key of block.keys.filter((name) => present(map, name))) {
+    if (UNSAFE_SETTING.test(map[key])) throw refusal('STACK_SETTING_INVALID', `${key} must be a plain one-line value`);
+    settings[key] = map[key];
+  }
+  return settings;
+}
+
+/**
+ * Opens the sealed members once each and returns what every service is granted:
+ * { secrets: { KEY: { runtimeName, value } }, grants: { service: [KEY...] }, settings: { KEY: value } }. The caller must not log a value.
+ */
+export function loadSealed(ctx, config) {
+  const versionKey = versionKeyOf(ctx);
+  const opened = new Map();
+  const memberOf = (member) => {
+    if (!opened.has(member)) opened.set(member, openMember(ctx, config, member));
+    return opened.get(member);
+  };
+  const { secrets, grants } = sealGrants(config, memberOf, versionKey);
+  return { secrets, grants, settings: sealSettings(config, memberOf) };
+}
+
+/** The config objects: non-secret files mounted into services, named by the digest of their content. */
+export const configObjects = (config) => config.configs.map((entry) => {
+  const file = path.join(config.envDir, entry.file);
+  return { logical: entry.name, env: entry.env, file, name: `${config.stack}-${entry.name}-c${sha(configBytes(file)).slice(0, 10)}` };
+});