@starci/hfs 4.12.2 → 4.13.2

package/stack/release-store.mjs

@@ -8,7 +8,38 @@ import path from 'node:path';
 import { firstLine, lines as splitLines } from './context.mjs';
 import { isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
-import { releaseListScript, releasePointerScript } from './remote.mjs';
+import { gatedCommand, inlineCommand } from './ssh-gate.mjs';
+/** A lock nobody refreshed for this long (its holder died without releasing it) is taken over by the next try. Phases refresh it. */
+export const LOCK_TTL_SECONDS = 3600;
+const TOKEN = /^[0-9a-f]{32}$/u;
+const TRIGGERS = ['ci', 'dispatch', 'urgent'];
+/** An attempt id: UTC compact time and 8 random hex. */
+export const ATTEMPT_ID = /^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$/u;
+const checkedToken = (token) => {
+    if (typeof token !== 'string' || !TOKEN.test(token))
+        throw refusal('STACK_LOCK_TOKEN', 'a lock token is exactly 32 lowercase hex characters');
+    return token;
+};
+const checkedTrigger = (trigger) => {
+    if (typeof trigger !== 'string' || !TRIGGERS.includes(trigger))
+        throw refusal('STACK_LOCK_TRIGGER', 'a deploy trigger is ci, dispatch or urgent');
+    return trigger; // TRIGGERS holds exactly the LockTrigger members
+};
+const checkedAttempt = (attempt) => {
+    if (typeof attempt !== 'string' || !ATTEMPT_ID.test(attempt))
+        throw refusal('STACK_ATTEMPT_ID', 'an attempt id is a UTC compact time and 8 lowercase hex characters');
+    return attempt;
+};
+/**
+ * The remote command of one try at the deploy lock (ssh-gate.mts holds the body): `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is
+ * replaced by rename, a lock unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`.
+ * Composed only from a validated base, token and trigger.
+ */
+export const lockAcquireScript = (base, token, trigger, ttl = LOCK_TTL_SECONDS) => inlineCommand('lock-acquire', [base, checkedToken(token), checkedTrigger(trigger), String(Math.trunc(ttl))]);
+/** The remote command that marks the lock alive when `token` owns it: prints `held` or `lost`. */
+export const lockRefreshScript = (base, token) => inlineCommand('lock-refresh', [base, checkedToken(token)]);
+/** The remote command that removes the lock when `token` owns it: prints `released` or `lost`. */
+export const lockReleaseScript = (base, token) => inlineCommand('lock-release', [base, checkedToken(token)]);
 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. */
@@ -20,7 +51,7 @@ const checkedId = (id) => {
 };
 const checkedBase = (config) => {
     const base = config.remote?.releasesBase ?? `/srv/${config.stack}`;
-    if (!BASE.test(base) || base.split('/').includes('..'))
+    if (!BASE.test(base) || base.includes('..'))
         throw refusal('STACK_RELEASE_BASE', `the releases base ${base} must be an absolute path without ..`);
     return base;
 };
@@ -28,10 +59,11 @@ const checkedBase = (config) => {
  * 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) {
+export function createReleaseStore(config, ssh, options = {}) {
     const base = checkedBase(config);
-    const dirOf = (id) => `${base}/releases/${checkedId(id)}`;
-    async function run(command, input) {
+    /** Runs the named operation: through the forced-command gate (`starci-op <name> <args>`) when the key has one, else as the same body under `sh -c`. */
+    async function run(name, args, input) {
+        const command = options.gated === true ? gatedCommand(name, args) : inlineCommand(name, args);
         const answer = await ssh(lfOnly(command), { input });
         if (answer.status !== 0)
             throw failure('STACK_RELEASE_SSH', `remote command failed: ${firstLine(answer.stderr)}`);
@@ -46,22 +78,30 @@ export function createReleaseStore(config, ssh) {
         }
     }
     async function pointer(name) {
-        const out = await run(releasePointerScript(`"${base}"`, name));
+        const out = await run('pointer', [base, name]);
         const id = out.trim();
         return isReleaseId(id) ? id : '';
     }
+    /** Both files of a stored release as [name, text] pairs, framed as base64 lines. */
+    async function readFiles(id) {
+        const out = await run('read', [base, checkedId(id)]);
+        const frames = out.split('\n');
+        if (frames.length !== 3 || frames[2] !== '' || frames.slice(0, 2).some((frame) => !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(frame)))
+            throw failure('STACK_RELEASE_SSH', 'invalid release response framing');
+        return FILES.map((name, index) => [name, Buffer.from(frames[index], 'base64').toString('utf8')]);
+    }
     return {
         /** Uploads stack.yaml and release.json of a rendered release as text; read-only afterwards. */
         async store(dir, id) {
-            const target = dirOf(id);
+            checkedId(id);
             const contents = FILES.map((name) => [name, readLocal(dir, name)]);
             const input = contents.map(([, text]) => Buffer.from(text, 'utf8').toString('base64')).join('\n') + '\n';
-            await run(`set -e; d="${target}"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf '%s' "$stack" | base64 -d > "$d/stack.yaml"; printf '%s' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"`, input);
+            await run('store', [base, checkedId(id)], input);
         },
         /** 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`);
+            await run('accept', [base, id]);
         },
         /** The accepted release id, '' when none. */
         current: () => pointer('current'),
@@ -69,20 +109,66 @@ export function createReleaseStore(config, ssh) {
         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 out = await run(`set -e; for f in stack.yaml release.json; do test -r "${source}/$f"; base64 < "${source}/$f" | tr -d '\\n'; printf '\\n'; done`);
-            const frames = out.split('\n');
-            if (frames.length !== 3 || frames[2] !== '' || frames.slice(0, 2).some((frame) => !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(frame)))
-                throw failure('STACK_RELEASE_SSH', 'invalid release response framing');
-            const files = FILES.map((name, index) => [name, Buffer.from(frames[index], 'base64').toString('utf8')]);
+            const files = await readFiles(id);
             fs.mkdirSync(targetDir, { recursive: true });
             for (const [name, text] of files)
                 fs.writeFileSync(path.join(targetDir, name), text);
             return targetDir;
         },
+        /** A stored release in memory: the stack bytes and the parsed release record. */
+        async read(id) {
+            const [stack, release] = await readFiles(id);
+            let record;
+            try {
+                record = JSON.parse(release[1]);
+            }
+            catch {
+                throw failure('STACK_RELEASE_STORE', `release ${id} has a release.json that is not JSON`);
+            }
+            return { stackYaml: stack[1], release: record !== null && typeof record === 'object' && !Array.isArray(record) ? record : {} };
+        },
+        async tryLock(token, trigger) {
+            const answer = (await run('lock-acquire', [base, checkedToken(token), checkedTrigger(trigger), String(LOCK_TTL_SECONDS)])).trim();
+            if (answer === 'acquired')
+                return { acquired: true };
+            const busy = /^busy ([a-z]+) (-?[0-9]+)$/u.exec(answer);
+            if (!busy)
+                throw failure('STACK_RELEASE_SSH', 'the deploy lock script answered something else than acquired or busy');
+            return { acquired: false, holder: busy[1], ageSeconds: Number(busy[2]) };
+        },
+        async refreshLock(token) { return (await run('lock-refresh', [base, checkedToken(token)])).trim() === 'held'; },
+        async unlock(token) { return (await run('lock-release', [base, checkedToken(token)])).trim() === 'released'; },
+        journal(attempt) {
+            const id = checkedAttempt(attempt);
+            const encoded = (value) => `${Buffer.from(JSON.stringify(value), 'utf8').toString('base64')}
+`;
+            return {
+                async write(document) {
+                    await run('journal-write', [base, id], encoded(document));
+                },
+                async index(entry) {
+                    await run('journal-index', [base], encoded(entry));
+                },
+            };
+        },
+        /** The attempt documents the journal keeps, oldest first. */
+        async journals() {
+            const documents = [];
+            for (const frame of (await run('journal-read', [base])).split('\n')) {
+                if (frame === '')
+                    continue;
+                try {
+                    const parsed = JSON.parse(Buffer.from(frame, 'base64').toString('utf8'));
+                    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+                        documents.push(parsed);
+                }
+                catch { /* a document that cannot be read is no evidence either way */ }
+            }
+            return documents;
+        },
         /** The stored releases, newest first: [{ id, current, previous }]. */
         async list() {
-            const response = await run(`${releasePointerScript(`"${base}"`, 'current')}; ${releasePointerScript(`"${base}"`, 'previous')}; ${releaseListScript(`"${base}"`)}`);
+            const response = await run('list', [base]);
             const [current, previous, ...entries] = response.split('\n');
             const now = isReleaseId(current) ? current : '';
             const before = isReleaseId(previous) ? previous : '';

package/stack/remote.d.mts

@@ -73,6 +73,8 @@ export declare function openSealedSession(ctx: StackContext, config: DeployConfi
 export declare const ownerSshRunner: (ctx: StackContext, config: DeployConfig, options?: SshOptions) => Runner;
 /** Opens the runner (`deps.ssh` wins in specs), calls `body(run, notes)` and always cleans the session up. */
 export declare function withRunner<T>(ctx: StackContext, config: DeployConfig, options: SshOptions, deps: RunnerDeps, body: (run: Runner, notes: string[]) => T | Promise<T>): Promise<T>;
+/** The sealed member that holds the CI transport of an environment: VPS_SSH_KEY (the CI-only deploy key), VPS_KNOWN_HOSTS, VPS_HOST and VPS_USER. */
+export declare const CI_MEMBER = "vps-ci";
 /** CI transport: pinned key, known_hosts, ssh config block and DOCKER_HOST=ssh://<alias> in $GITHUB_ENV. */
 export declare function connectCi(ctx: StackContext, config: DeployConfig, { execute }?: {
     execute?: boolean;

package/stack/remote.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 import { tool } from './context.mjs';
 import { restrictToUser, writePrivate } from './private-file.mjs';
 import { refusal } from './errors.mjs';
+import { openMember as openSealedMember } from './sealed.mjs';
 import { createSshSession, sessionDirectory } from './ssh-session.mjs';
 import { assertStackAccount } from './target-binding.mjs';
 const ACCOUNT = /^[A-Za-z0-9._@-]+$/u;
@@ -215,22 +216,36 @@ function ciHome(ctx) {
         throw refusal('STACK_CONNECT_NO_HOME', 'HOME is not set');
     return path.join(ctx.env.HOME, '.ssh');
 }
-function ciInputs(ctx) {
+/** The sealed member that holds the CI transport of an environment: VPS_SSH_KEY (the CI-only deploy key), VPS_KNOWN_HOSTS, VPS_HOST and VPS_USER. */
+export const CI_MEMBER = 'vps-ci';
+/**
+ * The CI transport values: the sealed member `vps-ci` of the environment (opened with the server identity the job holds) when it exists, else the
+ * variables of the job (the transition, and the owner's own runs). The member keeps the host, the account, the key and the pinned host keys out of
+ * GitHub and of a public log; the pinned host keys are reviewed in git as ciphertext.
+ */
+function ciValues(ctx, config) {
+    const present = typeof config.secretsDir === 'string' && fs.existsSync(memberFile(config.secretsDir, CI_MEMBER));
+    if (!present)
+        return { values: ctx.env, sealed: false };
+    const map = openSealedMember(ctx, config, CI_MEMBER);
+    return { values: Object.fromEntries([...CI_VARIABLES, 'VPS_GATE'].map((name) => [name, typeof map[name] === 'string' ? map[name] : undefined])), sealed: true };
+}
+function ciInputs(ctx, values, sealed) {
     for (const name of CI_VARIABLES)
-        if (!ctx.env[name])
-            throw refusal('STACK_CONNECT_MISSING', `${name} is not set`);
+        if (!values[name])
+            throw refusal('STACK_CONNECT_MISSING', sealed ? `the sealed member ${CI_MEMBER} holds no ${name}` : `${name} is not set and the environment has no sealed member ${CI_MEMBER}`);
     const [host, user] = ['VPS_HOST', 'VPS_USER'].map((name) => {
-        const value = ctx.env[name]; // set: every CI variable was checked above
+        const value = values[name]; // set: every CI variable was checked above
         if (!ACCOUNT.test(value) || value.startsWith('-'))
             throw refusal('STACK_CONNECT_INVALID', `${name} must match ${ACCOUNT}`);
         return value;
     });
-    const key = lfOnly(ctx.env.VPS_SSH_KEY);
+    const key = lfOnly(values.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, user };
+    return { key: withNewline(key), known: withNewline(lfOnly(values.VPS_KNOWN_HOSTS)), host, user };
 }
 const sshBlock = (alias, inputs) => [
     '', `Host ${alias}`, `  HostName ${inputs.host}`, `  User ${inputs.user}`, '  IdentityFile ~/.ssh/deploy_key',
@@ -240,18 +255,24 @@ const sshBlock = (alias, inputs) => [
 /** 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 { values, sealed } = ciValues(ctx, config);
+    const inputs = ciInputs(ctx, values, sealed);
     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'] };
+    const gated = values.VPS_GATE === '1';
+    const origin = sealed ? `the sealed member ${CI_MEMBER}` : 'VPS_SSH_KEY';
+    const plan = [...(gated ? ['STARCI_SSH_GATE=1 in GITHUB_ENV (the key is forced through starci-ssh-gate)'] : []), `${dir}/deploy_key (0600) from ${origin}`, `${dir}/known_hosts (0644) from ${sealed ? CI_MEMBER : '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'], sealed, gated };
     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 };
+    fs.appendFileSync(ctx.env.GITHUB_ENV, `DOCKER_HOST=ssh://${alias}
+${gated ? 'STARCI_SSH_GATE=1' + String.fromCharCode(10) : ''}`);
+    // The log of a public repository is public: mask the host, the account and the releases root before any later line can carry them.
+    const masks = sealed ? [inputs.host, inputs.user, config.remote.releasesBase].filter((value) => typeof value === 'string' && value.length >= 4).map((value) => `::add-mask::${value}`) : [];
+    return { ok: true, lines: [...masks, ...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 } = {}) {

package/stack/rollback-guard.d.mts

@@ -0,0 +1,10 @@
+/** What the guard found. */
+export interface ContractFinding {
+    blocked: boolean;
+    migrations: string[];
+    reason: string;
+}
+/** Judges a rollback to `target` against the attempt documents of the journal (oldest first). */
+export declare function contractFinding(documents: readonly Record<string, unknown>[], target: string): ContractFinding;
+/** Refuses `STACK_ROLLBACK_CONTRACT` when the finding blocks and the owner did not acknowledge the data effect; returns the notice line when it did. */
+export declare function enforceContractGuard(finding: ContractFinding, acknowledged: boolean): string[];

package/stack/rollback-guard.mjs

@@ -0,0 +1,41 @@
+// rollback-guard.mjs - the guard of a manual rollback to an older release.
+// A rollback restores service specs, never data (PROJECT-STACKS-6). A contract migration destroys what the code of the releases before the previous
+// one still uses, so rolling back to such a release after a contract migration ran leaves it on a schema it cannot read. The journal knows both: each
+// attempt that accepted a release carries an `accept` phase, and each attempt that applied contract migrations carries them in `contract`.
+//   chain      the accepted releases in the order the journal accepted them (a rollback is one more entry)
+//   a contract migration applied by the attempt that accepted chain[i] is safe for chain[i] and chain[i-1] (the deploy only runs it once the previous
+//   release no longer uses what it drops), and unsafe for every release accepted for the last time before chain[i-1].
+// A target the journal cannot place is refused as soon as any contract migration is recorded; `--data-acknowledged` is the owner's yes to the loss window.
+import { refusal } from './errors.mjs';
+const accepted = (document) => Array.isArray(document.phases) && document.phases.some((phase) => phase !== null && typeof phase === 'object' && phase.phase === 'accept' && phase.verdict === 'ok');
+const contractOf = (document) => (Array.isArray(document.contract) ? document.contract.filter((name) => typeof name === 'string') : []);
+/** Judges a rollback to `target` against the attempt documents of the journal (oldest first). */
+export function contractFinding(documents, target) {
+    const chain = [];
+    const marks = [];
+    for (const document of documents) {
+        if (typeof document.releaseId !== 'string' || !accepted(document))
+            continue;
+        chain.push(document.releaseId);
+        const migrations = contractOf(document);
+        if (migrations.length > 0)
+            marks.push({ index: chain.length - 1, migrations });
+    }
+    if (marks.length === 0)
+        return { blocked: false, migrations: [], reason: '' };
+    const at = chain.lastIndexOf(target);
+    const unsafe = marks.filter((mark) => at === -1 || at < mark.index - 1);
+    if (unsafe.length === 0)
+        return { blocked: false, migrations: [], reason: '' };
+    const migrations = unsafe.flatMap((mark) => mark.migrations);
+    const where = at === -1 ? `the journal has no record of release ${target} being accepted, and` : `release ${target} was accepted before the release that ran them, and`;
+    return { blocked: true, migrations, reason: `${where} contract migration(s) ${migrations.join(', ')} ran since: the schema no longer fits that release` };
+}
+/** Refuses `STACK_ROLLBACK_CONTRACT` when the finding blocks and the owner did not acknowledge the data effect; returns the notice line when it did. */
+export function enforceContractGuard(finding, acknowledged) {
+    if (!finding.blocked)
+        return [];
+    if (!acknowledged)
+        throw refusal('STACK_ROLLBACK_CONTRACT', `${finding.reason}. A rollback restores services, never data: restore the backup first, or pass --data-acknowledged to roll back anyway; nothing was changed`);
+    return [`--data-acknowledged: rolling back past ${finding.migrations.join(', ')}; the schema may not fit this release`];
+}

package/stack/server-key.d.mts

@@ -28,6 +28,8 @@ export interface ServerKeyOptions {
 export declare const SERVER_AGE_IDENTITY = "/root/.config/sops/age/keys.txt";
 /** The managed workflow `--restore github` dispatches (templates/app/ci-workflows*). */
 export declare const RESTORE_WORKFLOW = "stack-key-restore.yml";
+/** A command run as root: directly when the deploy user is root, else over passwordless sudo, the script read from stdin. */
+export declare const AS_ROOT = "if [ \"$(id -u)\" -eq 0 ]; then sh -s; else sudo -n sh -s; fi";
 /**
  * The directories, after root's PATH, where age-keygen is looked for: sudo's secure_path (AlmaLinux 10, RHEL) leaves out
  * /usr/local/bin, where the static installer puts it, so the presence check and every call resolve it the same way, as root.

package/stack/server-key.mjs

@@ -37,7 +37,7 @@ export const SERVER_AGE_IDENTITY = '/root/.config/sops/age/keys.txt';
 export const RESTORE_WORKFLOW = 'stack-key-restore.yml';
 const RECIPIENT = /^age1[a-z0-9]+$/u;
 /** A command run as root: directly when the deploy user is root, else over passwordless sudo, the script read from stdin. */
-const AS_ROOT = 'if [ "$(id -u)" -eq 0 ]; then sh -s; else sudo -n sh -s; fi';
+export const AS_ROOT = 'if [ "$(id -u)" -eq 0 ]; then sh -s; else sudo -n sh -s; fi';
 /**
  * The directories, after root's PATH, where age-keygen is looked for: sudo's secure_path (AlmaLinux 10, RHEL) leaves out
  * /usr/local/bin, where the static installer puts it, so the presence check and every call resolve it the same way, as root.

package/stack/ssh-gate.d.mts

@@ -0,0 +1,35 @@
+/** What an argument is: each kind is a closed alphabet, checked by the client (TypeScript) and by the gate (POSIX sh) alike. */
+export type ArgKind = 'base' | 'release' | 'pointer' | 'token' | 'trigger' | 'attempt' | 'seconds';
+/** One named operation: its arguments by kind, whether it reads stdin, and the sh body that runs with the arguments as $1.... */
+export interface GateOp {
+    readonly name: string;
+    readonly args: readonly ArgKind[];
+    readonly stdin: boolean;
+    readonly body: string;
+}
+/** The closed alphabet of each argument kind. */
+export declare const ARG_TESTS: Readonly<Record<ArgKind, (value: string) => boolean>>;
+/**
+ * The named operations of the release store. `lock-acquire`: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by
+ * rename, a lock unrefreshed for $4 seconds is moved aside (one rename wins) and claimed anew; prints `acquired` or `busy <trigger> <age>`.
+ */
+export declare const GATE_OPS: readonly GateOp[];
+/** The operation called `name`; an unknown name is a defect of the caller. */
+export declare function gateOp(name: string): GateOp;
+/** The command the CI transport sends: `starci-op <name> <argument>...` (every argument is plain characters, so nothing needs quoting). */
+export declare function gatedCommand(name: string, args: readonly string[]): string;
+/** The same operation as one command for a key without the gate: the body under `sh -c` with the arguments as positional parameters. */
+export declare function inlineCommand(name: string, args: readonly string[]): string;
+/** The POSIX sh text of `starci-ssh-gate`, to install executable at /usr/local/bin/starci-ssh-gate on the manager. */
+export declare function gateScript(): string;
+/** True when the CI transport was set up for a key that has the gate (`connect` exports STARCI_SSH_GATE=1 for a sealed `vps-ci` member that says `VPS_GATE: "1"`). */
+export declare const gateIsOn: (env: NodeJS.ProcessEnv | undefined) => boolean;
+/** Where the gate is installed on the manager, and the forced-command word of the authorized_keys line. */
+export declare const GATE_PATH = "/usr/local/bin/starci-ssh-gate";
+/** The options of the CI key's line: `restrict` already denies everything optional; the explicit denials keep the line readable and survive a reader who forgets what `restrict` covers. */
+export declare const AUTHORIZED_OPTIONS: readonly string[];
+/**
+ * The authorized_keys line of the CI key from its PUBLIC key text. Only a one-line public key is accepted (a private key, a line that already carries options
+ * or a second line is refused); the key keeps the comment it was generated with, which names it for revocation.
+ */
+export declare function authorizedKeysLine(publicKey: string): string;

package/stack/ssh-gate.mjs

@@ -0,0 +1,145 @@
+// ssh-gate.mjs - the forced command of the CI SSH key on the manager (`starci-ssh-gate`) and the named operations it admits.
+// The CI key reaches the manager's Docker socket, which is root on that host; its line in authorized_keys is therefore
+//   restrict,command="starci-ssh-gate" ssh-ed25519 AAAA... <comment>
+// and the gate admits exactly two kinds of request:
+//   `docker system dial-stdio`                   the transport of DOCKER_HOST=ssh://<alias> (the docker CLI starts it itself)
+//   `starci-op <name> <argument>...`             one of the named operations below, each argument validated by its kind
+// Everything else - a shell, an unknown name, a wrong argument count, an argument outside its closed alphabet - is refused with exit 126 and no echo of
+// the request. The operations are the release store's remote protocol (release-store.mts): the same script bodies run for the owner's key (through
+// `sh -c`, without the gate) and for the CI key (through the gate), so the gate admits no script the store does not itself run.
+// A body reads its arguments as $1... ($0 is `starci-op`) and its stdin; it holds no free text.
+import { refusal } from './errors.mjs';
+import { shellQuote } from './remote.mjs';
+const RELEASE_ID = /^[0-9a-f]{16}$/u;
+const TOKEN = /^[0-9a-f]{32}$/u;
+const ATTEMPT = /^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$/u;
+const BASE = /^\/[A-Za-z0-9._/-]+$/u;
+/** The closed alphabet of each argument kind. */
+export const ARG_TESTS = Object.freeze({
+    base: (value) => BASE.test(value) && !value.includes('..'),
+    release: (value) => RELEASE_ID.test(value),
+    pointer: (value) => value === 'current' || value === 'previous',
+    token: (value) => TOKEN.test(value),
+    trigger: (value) => value === 'ci' || value === 'dispatch' || value === 'urgent',
+    attempt: (value) => ATTEMPT.test(value),
+    seconds: (value) => /^[0-9]{1,6}$/u.test(value),
+});
+const OWNER_READ = 'if [ -r "$l/owner" ]; then read -r held_token held_trigger held_stamp < "$l/owner"; else held_token=none; held_trigger=unknown; held_stamp=$(stat -c %Y "$l" 2>/dev/null) || held_stamp=0; fi; case "$held_stamp" in \'\'|*[!0-9]*) held_stamp=0;; esac';
+/** Prints the release the pointer `$2` under `$1` names, or an empty line for an absent link; a failing readlink fails the script. */
+const POINTER = 'if [ -L "$1/$2" ]; then basename "$(readlink "$1/$2")"; else printf \'\\n\'; fi';
+/**
+ * The named operations of the release store. `lock-acquire`: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by
+ * rename, a lock unrefreshed for $4 seconds is moved aside (one rename wins) and claimed anew; prints `acquired` or `busy <trigger> <age>`.
+ */
+export const GATE_OPS = Object.freeze([
+    { name: 'pointer', args: ['base', 'pointer'], stdin: false, body: POINTER },
+    { name: 'list', args: ['base'], stdin: false, body: `for n in current previous; do if [ -L "$1/$n" ]; then basename "$(readlink "$1/$n")"; else printf '\\n'; fi; done; if [ -d "$1/releases" ]; then ls -1t "$1/releases"; fi` },
+    { name: 'read', args: ['base', 'release'], stdin: false, body: `set -e; s="$1/releases/$2"; for f in stack.yaml release.json; do test -r "$s/$f"; base64 < "$s/$f" | tr -d '\\n'; printf '\\n'; done` },
+    { name: 'store', args: ['base', 'release'], stdin: true, body: 'set -e; d="$1/releases/$2"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf \'%s\' "$stack" | base64 -d > "$d/stack.yaml"; printf \'%s\' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"' },
+    { name: 'accept', args: ['base', 'release'], stdin: false, body: 'set -e; cd "$1"; id="$2"; 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' },
+    {
+        name: 'lock-acquire', args: ['base', 'token', 'trigger', 'seconds'], stdin: false,
+        body: [
+            'b="$1"; tok="$2"; trg="$3"; ttl="$4"; l="$b/deploy.lock"; now=$(date +%s); mkdir -p "$b" || exit 1',
+            'claim() { printf \'%s %s %s\\n\' "$tok" "$trg" "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo acquired && exit 0; exit 1; }',
+            'if mkdir "$l" 2>/dev/null; then claim; fi',
+            OWNER_READ,
+            'age=$((now - held_stamp)); if [ "$age" -gt "$ttl" ]; then if mv "$l" "$l.stale.$tok" 2>/dev/null; then rm -rf "$l.stale.$tok"; if mkdir "$l" 2>/dev/null; then claim; fi; fi; fi',
+            'case "$held_trigger" in ci|dispatch|urgent) ;; *) held_trigger=unknown;; esac; echo "busy $held_trigger $age"',
+        ].join('; '),
+    },
+    { name: 'lock-refresh', args: ['base', 'token'], stdin: false, body: 'l="$1/deploy.lock"; now=$(date +%s); if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = "$2" ]; then printf \'%s %s %s\\n\' "$t" "$g" "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo held; else echo lost; fi; else echo lost; fi' },
+    { name: 'lock-release', args: ['base', 'token'], stdin: false, body: 'l="$1/deploy.lock"; if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = "$2" ]; then rm -rf "$l" && echo released; else echo lost; fi; else echo lost; fi' },
+    { name: 'journal-write', args: ['base', 'attempt'], stdin: true, body: 'set -e; d="$1/deploys"; mkdir -p "$d"; IFS= read -r doc; printf \'%s\' "$doc" | base64 -d > "$d/.$2.tmp"; mv -f "$d/.$2.tmp" "$d/$2.json"' },
+    { name: 'journal-index', args: ['base'], stdin: true, body: 'set -e; mkdir -p "$1/deploys"; IFS= read -r line; printf \'%s\\n\' "$(printf \'%s\' "$line" | base64 -d)" >> "$1/deploys.jsonl"' },
+    // The newest 500 attempt documents, one base64 line each, oldest first (attempt ids sort by their UTC time).
+    { name: 'journal-read', args: ['base'], stdin: false, body: 'd="$1/deploys"; [ -d "$d" ] || exit 0; names=$(ls -1 "$d") || exit 1; printf \'%s\\n\' "$names" | tail -n 500 | while IFS= read -r f; do case "$f" in ' + `${'[0-9]'.repeat(8)}T${'[0-9]'.repeat(6)}Z-${'[0-9a-f]'.repeat(8)}.json` + ') base64 < "$d/$f" | tr -d \'\\n\'; printf \'\\n\';; esac; done' },
+]);
+const BY_NAME = new Map(GATE_OPS.map((op) => [op.name, op]));
+/** The operation called `name`; an unknown name is a defect of the caller. */
+export function gateOp(name) {
+    const op = BY_NAME.get(name);
+    if (!op)
+        throw refusal('STACK_GATE_OP', `${name} is not an operation of the ssh gate`);
+    return op;
+}
+function checkedArguments(op, args) {
+    if (args.length !== op.args.length)
+        throw refusal('STACK_GATE_ARGUMENT', `${op.name} takes ${op.args.length} argument(s)`);
+    op.args.forEach((kind, index) => {
+        if (!ARG_TESTS[kind](args[index]))
+            throw refusal('STACK_GATE_ARGUMENT', `argument ${index + 1} of ${op.name} is not a plain ${kind}`);
+    });
+    return args;
+}
+/** The command the CI transport sends: `starci-op <name> <argument>...` (every argument is plain characters, so nothing needs quoting). */
+export function gatedCommand(name, args) {
+    const op = gateOp(name);
+    return ['starci-op', op.name, ...checkedArguments(op, args)].join(' ');
+}
+/** The same operation as one command for a key without the gate: the body under `sh -c` with the arguments as positional parameters. */
+export function inlineCommand(name, args) {
+    const op = gateOp(name);
+    return `sh -c ${shellQuote(op.body)} starci-op ${checkedArguments(op, args).map(shellQuote).join(' ')}`;
+}
+const VALIDATOR = Object.freeze({
+    base: 'v_base', release: 'v_release', pointer: 'v_pointer', token: 'v_token', trigger: 'v_trigger', attempt: 'v_attempt', seconds: 'v_seconds',
+});
+/** The sh variable that holds the body of an operation. */
+const bodyVariable = (name) => `OP_${name.replaceAll('-', '_')}`;
+/** The POSIX sh text of `starci-ssh-gate`, to install executable at /usr/local/bin/starci-ssh-gate on the manager. */
+export function gateScript() {
+    const digits = (count, set = '[0-9]') => set.repeat(count);
+    const bodies = GATE_OPS.map((op) => `${bodyVariable(op.name)}=${shellQuote(op.body)}`);
+    const cases = GATE_OPS.map((op) => {
+        const checks = op.args.map((kind, index) => `${VALIDATOR[kind]} "$${index + 1}"`).join(' && ');
+        return `  ${op.name}) [ $# -eq ${op.args.length} ]${checks ? ` && ${checks}` : ''} || refuse; exec sh -c "$${bodyVariable(op.name)}" starci-op "$@";;`;
+    });
+    return [
+        '#!/bin/sh',
+        '# starci-ssh-gate: the forced command of the CI key (generated by `starci app stack ci-key --print-gate`; do not edit, regenerate).',
+        '# Admits `docker system dial-stdio` and the named operations of the release store, nothing else. A refusal says nothing about the request.',
+        'PATH="$PATH:/usr/local/bin:/usr/bin:/bin"',
+        "refuse() { echo 'starci-ssh-gate: command refused' >&2; exit 126; }",
+        'v_base() { case "$1" in /*) ;; *) return 1;; esac; case "$1" in *[!A-Za-z0-9._/-]*|*..*) return 1;; esac; }',
+        'v_hex() { case "$2" in \'\'|*[!0-9a-f]*) return 1;; esac; [ "${#2}" -eq "$1" ]; }',
+        'v_release() { v_hex 16 "$1"; }',
+        'v_token() { v_hex 32 "$1"; }',
+        'v_pointer() { case "$1" in current|previous) ;; *) return 1;; esac; }',
+        'v_trigger() { case "$1" in ci|dispatch|urgent) ;; *) return 1;; esac; }',
+        `v_attempt() { case "$1" in ${digits(8)}T${digits(6)}Z-${digits(8, '[0-9a-f]')}) ;; *) return 1;; esac; v_hex 8 "\${1#*Z-}"; }`,
+        'v_seconds() { case "$1" in \'\'|*[!0-9]*) return 1;; esac; [ "${#1}" -le 6 ]; }',
+        ...bodies,
+        'cmd=${SSH_ORIGINAL_COMMAND-}',
+        '[ -n "$cmd" ] || refuse',
+        'if [ "$cmd" = \'docker system dial-stdio\' ]; then exec docker system dial-stdio; fi',
+        "IFS=' '; set -f",
+        'set -- $cmd',
+        '[ $# -ge 2 ] && [ "$1" = starci-op ] || refuse',
+        'op=$2; shift 2',
+        'case "$op" in',
+        ...cases,
+        '  *) refuse;;',
+        'esac',
+        '',
+    ].join('\n');
+}
+/** True when the CI transport was set up for a key that has the gate (`connect` exports STARCI_SSH_GATE=1 for a sealed `vps-ci` member that says `VPS_GATE: "1"`). */
+export const gateIsOn = (env) => env?.STARCI_SSH_GATE === '1';
+/** Where the gate is installed on the manager, and the forced-command word of the authorized_keys line. */
+export const GATE_PATH = '/usr/local/bin/starci-ssh-gate';
+/** The options of the CI key's line: `restrict` already denies everything optional; the explicit denials keep the line readable and survive a reader who forgets what `restrict` covers. */
+export const AUTHORIZED_OPTIONS = Object.freeze(['restrict', 'command="starci-ssh-gate"', 'no-pty', 'no-port-forwarding', 'no-agent-forwarding', 'no-X11-forwarding', 'no-user-rc']);
+const KEY_LINE = /^(ssh-ed25519|ecdsa-sha2-nistp(?:256|384|521)|ssh-rsa|sk-ssh-ed25519@openssh\.com) [A-Za-z0-9+/]+={0,3}(?: [A-Za-z0-9._@:+=-]+)?$/u;
+/**
+ * The authorized_keys line of the CI key from its PUBLIC key text. Only a one-line public key is accepted (a private key, a line that already carries options
+ * or a second line is refused); the key keeps the comment it was generated with, which names it for revocation.
+ */
+export function authorizedKeysLine(publicKey) {
+    const text = publicKey.trim();
+    if (text.includes('PRIVATE KEY'))
+        throw refusal('STACK_CI_KEY_PRIVATE', 'that is a private key: give the public half (.pub) of the CI key');
+    if (!KEY_LINE.test(text))
+        throw refusal('STACK_CI_KEY_PUBLIC', 'the CI public key must be one line: <type> <base64> [comment], with no options in front');
+    return `${AUTHORIZED_OPTIONS.join(',')} ${text}`;
+}

package/stack/status.d.mts

@@ -0,0 +1,51 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ReleaseStore } from './release-store.mjs';
+import type { ActionResult, Runner, SshOptions } from './remote.mjs';
+/** One live service of the stack as `docker service inspect` reports it (names, digests and states only; no environment, no secret). */
+export interface ObservedService {
+    /** The service name without the stack prefix (`api` for `shop_api`). */
+    service: string;
+    /** The image reference of the service spec, or null when it has none. */
+    image: string | null;
+    /** The `sha256:...` digest the image reference pins, or null when it is a tag only. */
+    digest: string | null;
+    /** The update state of the service (`completed`, `rollback_completed`, ...), null when it was never updated. */
+    updateState: string | null;
+    /** The first 16 hex of the sha256 of the canonical task template: it changes when anything a task runs with changes. */
+    taskTemplateHash: string | null;
+}
+/** The kinds of drift a status reports. */
+export type DriftKind = 'rolled back by swarm' | 'updated outside a release' | 'missing' | 'not in the release';
+/** One service that does not run what the accepted release says. */
+export interface ServiceDrift {
+    service: string;
+    kind: DriftKind;
+    detail: string;
+}
+/** The `sha256:...` digest an image reference pins, or null. */
+export declare const digestOf: (image: string | null | undefined) => string | null;
+/** The image of each service of a stack file, by service name (the pinned references of a rendered release). */
+export declare function stackImages(stackYaml: string): Record<string, string>;
+/** The live services of the stack, sorted by name. Throws when docker cannot be asked. */
+export declare function observedServices(ctx: Pick<StackContext, 'spawn'>, config: Pick<DeployConfig, 'stack'>): ObservedService[];
+/** What a release says its services run: the stack's images and, when it was accepted by this version, the services observed at the accept. */
+export interface ExpectedRelease {
+    stackYaml: string;
+    release: Record<string, unknown>;
+}
+/** Compares the live services with a release; an empty list means they run the release. */
+export declare function compareWithRelease(expected: ExpectedRelease, live: readonly ObservedService[]): ServiceDrift[];
+/** The collaborators of a status (the specs inject stubs). */
+export interface StatusDeps {
+    ssh: (ctx: StackContext, config: DeployConfig, options: SshOptions) => Runner | Promise<Runner>;
+    releaseStore: (config: DeployConfig, ssh: Runner, options?: {
+        gated?: boolean | undefined;
+    }) => ReleaseStore;
+    observedServices: (ctx: StackContext, config: DeployConfig) => ObservedService[];
+}
+/**
+ * `stack status`: the accepted release against the live services. Returns { ok, lines, data: { release, sourceSha, drift, services } }; ok is false exactly
+ * when a service drifted. An environment with no accepted release reports that and is not a drift.
+ */
+export declare function statusStack(ctx: StackContext, config: DeployConfig, options?: SshOptions, deps?: Partial<StatusDeps>): Promise<ActionResult>;