@hyperfixation/cli 0.1.0 → 0.1.1

package/dist/restore-check.js

@@ -0,0 +1,257 @@
+import { quoteIdent } from "@hyperfixation/db";
+import { createLocalDirectoryBackupSource, createS3BackupSource, } from "./backup-source.js";
+import { loadOperatorConfig, requireOperatorConfig } from "./config.js";
+import { openDatabase, openDatabaseUrl, redactPasswords, DEFAULT_POSTGRES_PORT, } from "./database.js";
+import { deriveNames } from "./names.js";
+import { REQUIRED_EXTENSIONS } from "./provision-database.js";
+import { createSshRunner } from "./runner.js";
+import { openAppState } from "./state.js";
+/** Appended to `hf_<app>` for the database the dump is restored into and then dropped. */
+export const SCRATCH_SUFFIX = "_restore_check";
+/** Postgres truncates an identifier past this, which would collide with the live database. */
+const MAX_IDENTIFIER_BYTES = 63;
+/** Older than this and the dump gets a warning line; it never changes the exit code. */
+export const STALE_DUMP_HOURS = 36;
+/** The box's Coolify Postgres superuser — the role the whole check runs as. */
+const CLUSTER_ADMIN_USER = "postgres";
+const CLUSTER_ADMIN_DATABASE = "postgres";
+export class RestoreCheckError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RestoreCheckError";
+    }
+}
+/**
+ * Restores the newest dump of `hf_<app>` beside the live database and compares row counts.
+ *
+ * The scratch database is dropped in a `finally`: it holds a full copy of the app's data, so
+ * leaving one behind on a failure would double the disk the app uses until someone noticed.
+ *
+ * `lastRestoreCheckAt` is written only by a run that counted both sides and found them equal.
+ * `hf doctor` warns on a stale timestamp, so a check that died halfway — or one that found a
+ * mismatch — has to leave the warning standing until a check actually passes.
+ */
+export async function restoreCheck(options) {
+    // Refuses a name carrying a quote, a semicolon or a glob before it reaches SQL, `find` or
+    // `pg_restore`'s argv.
+    const names = deriveNames(options.app);
+    const scratchDatabase = `${names.databaseName}${SCRATCH_SUFFIX}`;
+    if (Buffer.byteLength(scratchDatabase) > MAX_IDENTIFIER_BYTES) {
+        throw new RestoreCheckError(`${scratchDatabase} is longer than Postgres's ${String(MAX_IDENTIFIER_BYTES)}-byte ` +
+            `identifier limit, and a truncated name would collide with another database`);
+    }
+    const dump = await options.source.newest(names.databaseName);
+    if (dump === undefined) {
+        throw new RestoreCheckError(`no ${names.databaseName} dump in the ${options.source.kind} backup source: nothing to check`);
+    }
+    const db = typeof options.database === "string" ? openDatabaseUrl(options.database) : options.database;
+    const clusterUrl = db.adminUrl();
+    if (clusterUrl === undefined) {
+        throw new RestoreCheckError(`a restore cannot be run over the ${db.kind} transport: pg_restore needs an address. ` +
+            "Publish the Coolify Postgres port on the box's loopback so the tunnel works.");
+    }
+    const restoreTarget = urlOnto(options.restoreAdminUrl ?? clusterUrl, scratchDatabase);
+    const now = options.now ?? new Date();
+    const dumpAgeHours = (now.getTime() - dump.takenAt.getTime()) / 3_600_000;
+    try {
+        // A scratch database left by a killed run is the one thing in the way of this one.
+        await db.query(`DROP DATABASE IF EXISTS ${quoteIdent(scratchDatabase)} WITH (FORCE)`);
+        await db.query(`CREATE DATABASE ${quoteIdent(scratchDatabase)}`);
+        try {
+            // Its own connection, so that it can be closed before the drop: `WITH (FORCE)` terminates
+            // the backends it finds, and a `pg` client whose backend was killed under it raises an
+            // error event nothing is listening for.
+            const scratch = openDatabaseUrl(urlOnto(clusterUrl, scratchDatabase));
+            let rows;
+            try {
+                for (const extension of REQUIRED_EXTENSIONS) {
+                    await scratch.query(`CREATE EXTENSION IF NOT EXISTS ${quoteIdent(extension)}`);
+                }
+                // What `provisionRoles` grants the migrator in the live database. Without them the
+                // restore runs as a role that may not create anything: the extensions have to be created
+                // by the admin (pgvector needs a superuser) but everything the dump carries is the
+                // migrator's, which is the ownership the live database has.
+                await db.query(`GRANT CONNECT, CREATE ON DATABASE ${quoteIdent(scratchDatabase)} ` +
+                    `TO ${quoteIdent(names.migratorRole)}`);
+                await scratch.query(`GRANT CREATE, USAGE ON SCHEMA public TO ${quoteIdent(names.migratorRole)}`);
+                await runRestore(options, restoreTarget, names.migratorRole, dump.path);
+                rows = compare(await countTables(db, names.databaseName), await countTables(scratch));
+            }
+            finally {
+                await scratch.close();
+            }
+            const ok = rows.every((row) => row.verdict === "ok");
+            if (ok)
+                await options.state.patch({ lastRestoreCheckAt: now.toISOString() });
+            return {
+                databaseName: names.databaseName,
+                scratchDatabase,
+                dump,
+                dumpAgeHours,
+                dumpStale: dumpAgeHours > STALE_DUMP_HOURS,
+                rows,
+                ok,
+            };
+        }
+        finally {
+            await db.query(`DROP DATABASE IF EXISTS ${quoteIdent(scratchDatabase)} WITH (FORCE)`);
+        }
+    }
+    finally {
+        if (typeof options.database === "string")
+            await db.close();
+    }
+}
+/** The argv `restoreCheck` runs — the array the test asserts against. */
+export function pgRestoreArgv(options) {
+    return [
+        options.pgRestorePath ?? "pg_restore",
+        "--no-owner",
+        // Every object comes out owned by the migrator, as in the live database. `--no-comments`
+        // because a dump's `COMMENT ON EXTENSION` belongs to the admin that created the extension,
+        // and a comment nobody may set is not a restore failure.
+        "--no-comments",
+        `--role=${options.role}`,
+        "--dbname",
+        options.url,
+        options.file,
+    ];
+}
+async function runRestore(options, url, role, file) {
+    const argv = pgRestoreArgv({ url, role, file, pgRestorePath: options.pgRestorePath });
+    const result = await options.runner.exec(argv);
+    if (result.code !== 0) {
+        // `url` carries the cluster's admin password, and so does anything pg_restore echoed of it.
+        throw new RestoreCheckError(`pg_restore exited ${String(result.code)} restoring ${file}: ` +
+            redactPasswords(result.stderr.trim()));
+    }
+}
+/**
+ * Row counts for every table the app's data lives in: `hf_*`, plus every table carrying
+ * `normalized_name`, which is how `@hyperfixation/db` spells a record table the app declared.
+ */
+async function countTables(db, database) {
+    const { rows: tables } = await db.query(`SELECT c.relname
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = 'public'
+        AND c.relkind IN ('r', 'p')
+        AND (c.relname LIKE 'hf\\_%'
+             OR EXISTS (SELECT 1
+                          FROM pg_attribute a
+                         WHERE a.attrelid = c.oid
+                           AND a.attname = 'normalized_name'
+                           AND a.attnum > 0
+                           AND NOT a.attisdropped))
+      ORDER BY c.relname`, { database });
+    const names = tables.map((row) => row[0]).filter((name) => name !== undefined);
+    const counts = new Map();
+    if (names.length === 0)
+        return counts;
+    const { rows } = await db.query(names
+        .map((name) => `SELECT ${quoteLiteral(name)} AS relname, count(*) AS rows FROM public.${quoteIdent(name)}`)
+        .join(" UNION ALL "), { database });
+    for (const [name, count] of rows) {
+        if (name !== undefined && count !== undefined)
+            counts.set(name, Number(count));
+    }
+    return counts;
+}
+/**
+ * One row per table either side has.
+ *
+ * A table on one side only is its own verdict rather than a crash or a zero: an app migration
+ * between the backup and the check is the ordinary reason for it, and reading it as a count of
+ * zero would make an added table look like lost data.
+ */
+function compare(live, restored) {
+    const tables = [...new Set([...live.keys(), ...restored.keys()])].sort();
+    return tables.map((table) => {
+        const liveCount = live.get(table);
+        const restoredCount = restored.get(table);
+        const verdict = liveCount === undefined
+            ? "restored only"
+            : restoredCount === undefined
+                ? "live only"
+                : liveCount === restoredCount
+                    ? "ok"
+                    : "mismatch";
+        return {
+            table,
+            ...(liveCount === undefined ? {} : { live: liveCount }),
+            ...(restoredCount === undefined ? {} : { restored: restoredCount }),
+            verdict,
+        };
+    });
+}
+/** The table `hf restore-check` prints, and the two lines around it. */
+export function formatRestoreCheck(result) {
+    const age = `${result.dumpAgeHours.toFixed(1)} h old`;
+    const lines = [`${result.databaseName}: ${result.dump.path}, ${age}`];
+    if (result.dumpStale) {
+        lines.push(`WARNING: the dump is ${age} — over ${String(STALE_DUMP_HOURS)} h`);
+    }
+    const header = ["table", "live", "restored", "verdict"];
+    const cells = result.rows.map((row) => [
+        row.table,
+        row.live === undefined ? "—" : String(row.live),
+        row.restored === undefined ? "—" : String(row.restored),
+        row.verdict,
+    ]);
+    const widths = header.map((name, column) => Math.max(name.length, ...cells.map((row) => row[column]?.length ?? 0)));
+    const line = (row) => row.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd();
+    lines.push(line(header), ...cells.map(line));
+    const mismatched = result.rows.filter((row) => row.verdict !== "ok").length;
+    lines.push(result.ok
+        ? `${String(result.rows.length)} table(s) matched`
+        : `${String(mismatched)} of ${String(result.rows.length)} table(s) did not match`);
+    return lines;
+}
+/**
+ * `hf restore-check <name>`: the operator config, an `ssh` runner onto the box, and the check.
+ *
+ * The cluster admin password comes from libpq's own `PGPASSWORD` until E3 records Coolify's — the
+ * operator config has no key for it, and inventing one before the box has been looked at is
+ * exactly what risk 3 warns against.
+ */
+export async function restoreCheckApp(options) {
+    const env = options.env ?? process.env;
+    const config = await loadOperatorConfig({ env });
+    const { HF_SSH_HOST } = requireOperatorConfig(config, ["HF_SSH_HOST"], { env });
+    const runner = createSshRunner({ host: HF_SSH_HOST });
+    const admin = { user: CLUSTER_ADMIN_USER, password: env.PGPASSWORD };
+    const db = await openDatabase(runner, { admin });
+    try {
+        return await restoreCheck({
+            app: options.app,
+            state: await openAppState(options.app, { env }),
+            source: options.fromS3 === true
+                ? createS3BackupSource()
+                : createLocalDirectoryBackupSource({ runner, directory: options.backupDir }),
+            runner,
+            database: db,
+            restoreAdminUrl: boxAdminUrl(admin),
+        });
+    }
+    finally {
+        await db.close();
+    }
+}
+/** The cluster as the box itself sees it, where `pg_restore` runs. */
+function boxAdminUrl(admin) {
+    const url = new URL("postgresql://127.0.0.1");
+    url.port = String(DEFAULT_POSTGRES_PORT);
+    url.username = encodeURIComponent(admin.user);
+    if (admin.password !== undefined)
+        url.password = encodeURIComponent(admin.password);
+    url.pathname = `/${CLUSTER_ADMIN_DATABASE}`;
+    return url.toString();
+}
+function urlOnto(connectionString, database) {
+    const url = new URL(connectionString);
+    url.pathname = `/${encodeURIComponent(database)}`;
+    return url.toString();
+}
+function quoteLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}

package/dist/runner.d.ts

@@ -0,0 +1,65 @@
+export interface ExecOptions {
+    /** Written to the command's stdin and then closed. SQL goes here, never into argv. */
+    input?: string;
+}
+export interface ExecResult {
+    /** `null` when the command was killed by a signal or by `timeoutMs`. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface Tunnel {
+    /** On 127.0.0.1, already accepting connections. */
+    localPort: number;
+    close(): Promise<void>;
+}
+/**
+ * Somewhere commands run: the Coolify box over `ssh`, or this machine in a test.
+ *
+ * `exec` takes an argument array, never a string. Everything it is asked to run carries an app
+ * name, a container name or a role name that came from a flag or an API, and the one shape that
+ * cannot be talked into a second command is a vector the shell never sees as one token.
+ */
+export interface Runner {
+    exec(command: readonly string[], options?: ExecOptions): Promise<ExecResult>;
+    /** Forwards a local port to `127.0.0.1:<remotePort>` on the far side. */
+    tunnel(remotePort: number): Promise<Tunnel>;
+}
+export declare class RunnerError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The argv `exec` runs, `ssh` excluded — the array the test asserts against. */
+export declare function sshExecArgv(host: string, command: readonly string[]): string[];
+export declare function sshTunnelArgv(host: string, localPort: number, remotePort: number): string[];
+/** Single-quotes one word for a POSIX remote shell. */
+export declare function shellQuote(command: readonly string[]): string;
+export interface SshRunnerOptions {
+    /** `HF_SSH_HOST`. */
+    host: string;
+    /** The `ssh` binary; overridden only by tests that assert the argv. */
+    sshPath?: string;
+    /** How long to wait for a forwarded port to accept a connection. */
+    tunnelReadyTimeoutMs?: number;
+}
+export declare const DEFAULT_TUNNEL_READY_TIMEOUT_MS = 10000;
+/** A `Runner` that reaches the box over `ssh`. */
+export declare function createSshRunner(options: SshRunnerOptions): Runner;
+export interface LocalRunnerOptions {
+    /** What `tunnel()` reports; the local Postgres a test already has. */
+    tunnelPort?: number;
+}
+export interface LocalRunner extends Runner {
+    /** Every argv `exec` was asked for, in order. */
+    readonly commands: readonly (readonly string[])[];
+    /** Every remote port `tunnel` was asked for, in order. */
+    readonly tunnels: readonly number[];
+}
+/**
+ * A `Runner` that runs on this machine and records what it was asked to run.
+ *
+ * `tunnel()` forwards nothing — it names a port the test already has — so provisioning can be
+ * exercised end to end against the test cluster without an `ssh` anywhere in the suite.
+ */
+export declare function createLocalRunner(options?: LocalRunnerOptions): LocalRunner;

package/dist/runner.js

@@ -0,0 +1,199 @@
+import { spawn } from "node:child_process";
+import { createServer, connect as connectTcp } from "node:net";
+export class RunnerError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RunnerError";
+    }
+}
+/**
+ * What `HF_SSH_HOST` may be: `[user@]host`, and nothing that `ssh` would read as an option.
+ *
+ * A destination beginning `-o` is `ssh`'s own `-oProxyCommand=…`, which runs whatever it says
+ * on *this* machine. The config file is the operator's, but it is also the one place an env
+ * override reaches, so the destination is checked rather than trusted.
+ */
+const SSH_HOST = /^[A-Za-z0-9._-]+(@[A-Za-z0-9._-]+)?$/;
+/**
+ * Options every `ssh` invocation carries.
+ *
+ * `BatchMode=yes` so a missing key fails instead of prompting a non-interactive run for a
+ * password; `ControlMaster=no` with `ControlPath=none` so a multiplexed session left over from
+ * the operator's own `ssh` cannot silently carry a tunnel that outlives this process, and so a
+ * broken master socket cannot wedge provisioning.
+ */
+const SSH_OPTIONS = [
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "ControlMaster=no",
+    "-o",
+    "ControlPath=none",
+];
+/** The argv `exec` runs, `ssh` excluded — the array the test asserts against. */
+export function sshExecArgv(host, command) {
+    assertHost(host);
+    // `ssh` hands the remote end one string and the login shell splits it, so the array has to be
+    // re-quoted for that shell; nothing else in this file ever builds a shell word.
+    return ["-T", ...SSH_OPTIONS, host, shellQuote(command)];
+}
+export function sshTunnelArgv(host, localPort, remotePort) {
+    assertHost(host);
+    return [
+        "-N",
+        "-T",
+        ...SSH_OPTIONS,
+        "-L",
+        `${String(localPort)}:127.0.0.1:${String(remotePort)}`,
+        host,
+    ];
+}
+/** Single-quotes one word for a POSIX remote shell. */
+export function shellQuote(command) {
+    return command.map((word) => `'${word.replaceAll("'", `'\\''`)}'`).join(" ");
+}
+export const DEFAULT_TUNNEL_READY_TIMEOUT_MS = 10_000;
+/** A `Runner` that reaches the box over `ssh`. */
+export function createSshRunner(options) {
+    const ssh = options.sshPath ?? "ssh";
+    assertHost(options.host);
+    return {
+        exec: async (command, execOptions) => await spawnCollecting(ssh, sshExecArgv(options.host, command), execOptions),
+        tunnel: async (remotePort) => {
+            const localPort = await freeLocalPort();
+            const child = spawn(ssh, sshTunnelArgv(options.host, localPort, remotePort), {
+                stdio: ["ignore", "ignore", "pipe"],
+            });
+            let stderr = "";
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString("utf8");
+            });
+            const exited = new Promise((resolve) => child.once("exit", () => resolve()));
+            try {
+                await waitForPort(localPort, options.tunnelReadyTimeoutMs ?? DEFAULT_TUNNEL_READY_TIMEOUT_MS, child);
+            }
+            catch (cause) {
+                child.kill("SIGTERM");
+                await exited;
+                throw new RunnerError(`ssh -L ${String(localPort)}:127.0.0.1:${String(remotePort)} never became ready` +
+                    (stderr === "" ? "" : `: ${stderr.trim()}`), { cause });
+            }
+            return {
+                localPort,
+                close: async () => {
+                    child.kill("SIGTERM");
+                    await exited;
+                },
+            };
+        },
+    };
+}
+/**
+ * A `Runner` that runs on this machine and records what it was asked to run.
+ *
+ * `tunnel()` forwards nothing — it names a port the test already has — so provisioning can be
+ * exercised end to end against the test cluster without an `ssh` anywhere in the suite.
+ */
+export function createLocalRunner(options = {}) {
+    const commands = [];
+    const tunnels = [];
+    return {
+        get commands() {
+            return commands;
+        },
+        get tunnels() {
+            return tunnels;
+        },
+        exec: async (command, execOptions) => {
+            commands.push([...command]);
+            const [bin, ...args] = command;
+            if (bin === undefined)
+                throw new RunnerError("exec was given an empty command");
+            return await spawnCollecting(bin, args, execOptions);
+        },
+        tunnel: async (remotePort) => {
+            tunnels.push(remotePort);
+            const localPort = options.tunnelPort;
+            if (localPort === undefined) {
+                throw new RunnerError("this local Runner was not given a tunnelPort");
+            }
+            return { localPort, close: async () => undefined };
+        },
+    };
+}
+async function spawnCollecting(bin, args, options = {}) {
+    const child = spawn(bin, [...args], { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+    });
+    // A child that exits before reading its stdin (`true`, a refused ssh) makes the write fail with
+    // EPIPE; the exit code already says what happened, so it must not surface as an unhandled error.
+    child.stdin?.on("error", () => { });
+    child.stdin?.end(options.input ?? "");
+    const code = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (exitCode) => resolve(exitCode));
+    });
+    return { code, stdout, stderr };
+}
+/**
+ * A port nothing is listening on, by binding one and letting go.
+ *
+ * Inherently a race — something else on the machine may take it in between — so the ready check
+ * below is what actually decides whether the forward came up.
+ */
+async function freeLocalPort() {
+    return await new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address === null || typeof address === "string") {
+                server.close();
+                reject(new RunnerError("could not take a local port for the tunnel"));
+                return;
+            }
+            const { port } = address;
+            server.close(() => resolve(port));
+        });
+    });
+}
+async function waitForPort(port, timeoutMs, child) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            throw new RunnerError(`ssh exited before the forward on ${String(port)} was ready`);
+        }
+        if (await canConnect(port))
+            return;
+        if (Date.now() >= deadline) {
+            throw new RunnerError(`nothing accepted on 127.0.0.1:${String(port)} within ${String(timeoutMs)}ms`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+async function canConnect(port) {
+    return await new Promise((resolve) => {
+        let socket;
+        const done = (ok) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(ok);
+        };
+        socket = connectTcp({ port, host: "127.0.0.1" });
+        socket.setTimeout(1_000);
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+        socket.once("timeout", () => done(false));
+    });
+}
+function assertHost(host) {
+    if (!SSH_HOST.test(host)) {
+        throw new RunnerError(`HF_SSH_HOST must match ${SSH_HOST.source}, got ${JSON.stringify(host)}`);
+    }
+}

package/dist/secret-file.d.ts

@@ -0,0 +1,30 @@
+/** Owner read/write and nothing else — the only mode the operator's files are read at. */
+export declare const SECRET_MODE = 384;
+/**
+ * A file that holds secrets was readable or writable by someone other than its owner.
+ *
+ * Thrown *after* the file has been tightened to 0600: the operator's next run works, and this
+ * run stops loudly enough that they can decide whether anything in it needs rotating. Nothing
+ * of the file's contents reaches the message.
+ */
+export declare class InsecureFileMode extends Error {
+    readonly file: string;
+    /** The permission bits found, before they were tightened. */
+    readonly found: number;
+    constructor(file: string, found: number);
+}
+/**
+ * Reads a file that holds secrets, or `undefined` when it does not exist.
+ *
+ * Refuses a file any other user can reach, having first tightened it — see `InsecureFileMode`.
+ */
+export declare function readSecretFile(file: string): Promise<string | undefined>;
+/**
+ * Writes a file that holds secrets, at 0600, atomically.
+ *
+ * Temp file then `rename`, because the state cache is written between provisioning steps: a
+ * crash partway through a write would otherwise leave a half-written JSON file that the next
+ * run refuses, and the passwords and tokens it held are not recoverable from anywhere else.
+ * The temp file is created 0600 too, so the secrets are never briefly world-readable.
+ */
+export declare function writeSecretFile(file: string, contents: string): Promise<void>;

package/dist/secret-file.js

@@ -0,0 +1,69 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+/** Owner read/write and nothing else — the only mode the operator's files are read at. */
+export const SECRET_MODE = 0o600;
+/** The mode a secret directory is created at, so a new file cannot be listed by anyone else. */
+const SECRET_DIR_MODE = 0o700;
+/**
+ * A file that holds secrets was readable or writable by someone other than its owner.
+ *
+ * Thrown *after* the file has been tightened to 0600: the operator's next run works, and this
+ * run stops loudly enough that they can decide whether anything in it needs rotating. Nothing
+ * of the file's contents reaches the message.
+ */
+export class InsecureFileMode extends Error {
+    file;
+    /** The permission bits found, before they were tightened. */
+    found;
+    constructor(file, found) {
+        super(`${file} was mode ${found.toString(8).padStart(4, "0")}, not 0600: other users on this ` +
+            `machine could read it. It has been tightened to 0600 — rerun, and rotate anything it ` +
+            `holds that may have been read.`);
+        this.name = "InsecureFileMode";
+        this.file = file;
+        this.found = found;
+    }
+}
+/**
+ * Reads a file that holds secrets, or `undefined` when it does not exist.
+ *
+ * Refuses a file any other user can reach, having first tightened it — see `InsecureFileMode`.
+ */
+export async function readSecretFile(file) {
+    let mode;
+    try {
+        mode = (await stat(file)).mode & 0o777;
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+    if ((mode & 0o077) !== 0) {
+        await chmod(file, SECRET_MODE);
+        throw new InsecureFileMode(file, mode);
+    }
+    return await readFile(file, "utf8");
+}
+/**
+ * Writes a file that holds secrets, at 0600, atomically.
+ *
+ * Temp file then `rename`, because the state cache is written between provisioning steps: a
+ * crash partway through a write would otherwise leave a half-written JSON file that the next
+ * run refuses, and the passwords and tokens it held are not recoverable from anywhere else.
+ * The temp file is created 0600 too, so the secrets are never briefly world-readable.
+ */
+export async function writeSecretFile(file, contents) {
+    await mkdir(path.dirname(file), { recursive: true, mode: SECRET_DIR_MODE });
+    const temp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        await writeFile(temp, contents, { mode: SECRET_MODE });
+        await chmod(temp, SECRET_MODE);
+        await rename(temp, file);
+    }
+    catch (cause) {
+        await rm(temp, { force: true });
+        throw cause;
+    }
+}