@intentius/chant 0.124.30 → 0.124.32

package/dist/workspace/ci-runner-key.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The runner key on a `chant ci serve` or `chant ci run` host (#4099, epic
+ * #4101).
+ *
+ * The host keeps its runner key in the serve's state directory, by default
+ * `<git common dir>/chant/ci-serve/runner-key.pem`: an Ed25519 private key in
+ * PEM, mode 0600, made by `--setup-key` when there is none. Its public half
+ * is the `ssh-ed25519` line `.chant/trust.json` lists under `runners`, and
+ * `--setup-key --trust` proposes that entry through `chant workspace trust
+ * runner add` (#3510) on a branch of its own, pushed for review. It never
+ * commits to the target branch: changing the trust config is a protected
+ * write, and the change is reviewed and merged like any other.
+ *
+ * `ci serve` refuses to start when its key is not listed, with the runner
+ * role, in `.chant/trust.json` at the target branch's head, since every run
+ * it signed would then be ignored by `ci tick --source runs`. `--unsigned`
+ * starts it without a key.
+ */
+/** The runner key's file in the state directory. */
+export declare const RUNNER_KEY_FILE = "runner-key.pem";
+/** The principal `--setup-key --trust` lists the key for when `--principal` names none. */
+export declare function defaultRunnerPrincipal(): string;
+export interface HostRunnerKey {
+    path: string;
+    pem: string;
+    /** `ssh-ed25519 <base64>`. */
+    publicKey: string;
+    /** Whether this call made it. */
+    created: boolean;
+}
+/** The host's runner key in `stateDir`, or undefined when there is none. */
+export declare function hostRunnerKey(stateDir: string): HostRunnerKey | undefined;
+/** The host's runner key in `stateDir`, made when there is none: Ed25519, PEM, mode 0600 in a directory of mode 0700. */
+export declare function ensureHostRunnerKey(stateDir: string): HostRunnerKey;
+/**
+ * The target branch's head, as the readers of runners take it: the remote's
+ * branch after a fetch (best effort), else the local branch. Undefined when
+ * neither exists.
+ */
+export declare function targetHead(top: string, branch: string, remote?: string): {
+    commit: string;
+    ref: string;
+} | undefined;
+/** The exact command that lists `publicKey` for `principal`. */
+export declare function trustCommand(principal: string, publicKey: string): string;
+/** Whether `.chant/trust.json` at `commit` lists the key as a runner holding the runner role: its principal, or why not. */
+export declare function runnerKeyListed(top: string, commit: string, pem: string): {
+    ok: true;
+    principal: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface RunnerTrustProposal {
+    /** The branch holding the commit, or null when the key was already listed at the target's head. */
+    branch: string | null;
+    commit: string | null;
+    /** Whether the branch was pushed to the remote. */
+    pushed: boolean;
+    /** The trust config's digest on the branch. */
+    digest: string | null;
+}
+/**
+ * Propose the runner entry for review (#4099): in a temporary worktree at
+ * the target's head, run `trust runner add` (#3510), commit the change on
+ * `chant/trust-runner/<principal>`, and push that branch to `remote` when
+ * the clone has it. The target branch is never written. The commit is made
+ * with the host's git identity and signing settings; when the policy at base
+ * has signers, the change needs a signature by a policy writer before it
+ * merges.
+ */
+export declare function proposeRunnerTrust(req: {
+    top: string;
+    branch: string;
+    principal: string;
+    publicKey: string;
+    by?: string;
+    remote?: string;
+}): RunnerTrustProposal;
+export interface RunnerKeySetup {
+    key: HostRunnerKey;
+    /** The target's head the trust config was read at, or null when there is no such branch. */
+    head: string | null;
+    /** The principal the key is listed for at the head, or null. */
+    listedAs: string | null;
+    principal: string;
+    command: string;
+    proposal?: RunnerTrustProposal;
+}
+/** `--setup-key [--trust]`: make or read the key, see whether the target's head lists it, and with `trust` propose the entry. */
+export declare function setupRunnerKey(req: {
+    top: string;
+    stateDir: string;
+    branch: string;
+    principal?: string;
+    trust?: boolean;
+    by?: string;
+}): RunnerKeySetup;
+/** What `--setup-key` prints on stderr; the public key alone goes to stdout. */
+export declare function formatRunnerKeySetup(s: RunnerKeySetup, branch: string): string;
+/**
+ * The key `ci serve` signs with, checked before its first poll (#4099): the
+ * `--key` file, else `CHANT_RUNNER_KEY`, else the host's key in the state
+ * directory. Signing is opt-in (#4156):
+ *
+ * - With no key, `ci serve` serves unsigned and says so only in `note`.
+ * - A key `.chant/trust.json` at the target's head does not list with the
+ *   runner role, or a target branch it can't find to check against, leaves
+ *   it serving unsigned, with one `warning`.
+ * - With `required` (the declaration's `ci.green.signedSince`) each of
+ *   those refuses to start, as before #4156.
+ *
+ * A key that is not an Ed25519 private key in PEM, or a `--key` file that
+ * can't be read, refuses either way. `unsigned` (`--unsigned`) skips the
+ * key without `required` and is ignored with it.
+ */
+export declare function ciServeRunnerKey(req: {
+    top: string;
+    stateDir: string;
+    branch: string;
+    keyFile?: string;
+    envKey?: string;
+    unsigned?: boolean;
+    /** The declaration's `ci.green.signedSince`, when it sets one: every run must then be signed. */
+    required?: string | null;
+}): {
+    pem?: string;
+    fromFlag: boolean;
+    source: string;
+    warning?: string;
+    note?: string;
+};
+//# sourceMappingURL=ci-runner-key.d.ts.map

package/dist/workspace/ci-runner-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-runner-key.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-runner-key.ts"],"names":[],"mappings":"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"}

package/dist/workspace/ci-runner-key.js

@@ -0,0 +1,237 @@
+/**
+ * The runner key on a `chant ci serve` or `chant ci run` host (#4099, epic
+ * #4101).
+ *
+ * The host keeps its runner key in the serve's state directory, by default
+ * `<git common dir>/chant/ci-serve/runner-key.pem`: an Ed25519 private key in
+ * PEM, mode 0600, made by `--setup-key` when there is none. Its public half
+ * is the `ssh-ed25519` line `.chant/trust.json` lists under `runners`, and
+ * `--setup-key --trust` proposes that entry through `chant workspace trust
+ * runner add` (#3510) on a branch of its own, pushed for review. It never
+ * commits to the target branch: changing the trust config is a protected
+ * write, and the change is reviewed and merged like any other.
+ *
+ * `ci serve` refuses to start when its key is not listed, with the runner
+ * role, in `.chant/trust.json` at the target branch's head, since every run
+ * it signed would then be ignored by `ci tick --source runs`. `--unsigned`
+ * starts it without a key.
+ */
+import { execFileSync } from "node:child_process";
+import { generateKeyPairSync } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { hostname, tmpdir } from "node:os";
+import { join } from "node:path";
+import { ciTagSigner } from "./ci-green.js";
+import { CiRunError } from "./ci-run.js";
+import { loadRunnerKey } from "./trust/dsse.js";
+import { trustWrite } from "./trust/trust-write.js";
+/** The runner key's file in the state directory. */
+export const RUNNER_KEY_FILE = "runner-key.pem";
+/** The principal `--setup-key --trust` lists the key for when `--principal` names none. */
+export function defaultRunnerPrincipal() {
+    return `chant-runner:${hostname().split(".")[0].toLowerCase().replace(/[^a-z0-9-]/g, "-") || "host"}`;
+}
+const message = (err) => (err instanceof Error ? err.message : String(err));
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function tryGit(cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the key at `path`, refusing one others can read or one that is not an Ed25519 private key in PEM. */
+function readHostKey(path) {
+    const mode = statSync(path).mode & 0o777;
+    if (mode & 0o077)
+        throw new CiRunError(`${path} can be read by other users (mode ${mode.toString(8)}); chmod 600 it, since it signs for this runner`);
+    const pem = readFileSync(path, "utf-8");
+    try {
+        return { path, pem, publicKey: loadRunnerKey(pem).publicKey, created: false };
+    }
+    catch (err) {
+        throw new CiRunError(`${path} is not an Ed25519 private key in PEM: ${message(err)}`);
+    }
+}
+/** The host's runner key in `stateDir`, or undefined when there is none. */
+export function hostRunnerKey(stateDir) {
+    const path = join(stateDir, RUNNER_KEY_FILE);
+    return existsSync(path) ? readHostKey(path) : undefined;
+}
+/** The host's runner key in `stateDir`, made when there is none: Ed25519, PEM, mode 0600 in a directory of mode 0700. */
+export function ensureHostRunnerKey(stateDir) {
+    const found = hostRunnerKey(stateDir);
+    if (found)
+        return found;
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const path = join(stateDir, RUNNER_KEY_FILE);
+    const { privateKey } = generateKeyPairSync("ed25519");
+    const pem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    // wx: never replace a key another process made in the meantime.
+    writeFileSync(path, pem, { mode: 0o600, flag: "wx" });
+    chmodSync(path, 0o600);
+    return { path, pem, publicKey: loadRunnerKey(pem).publicKey, created: true };
+}
+/**
+ * The target branch's head, as the readers of runners take it: the remote's
+ * branch after a fetch (best effort), else the local branch. Undefined when
+ * neither exists.
+ */
+export function targetHead(top, branch, remote = "origin") {
+    if (tryGit(top, ["remote", "get-url", remote]) !== undefined)
+        tryGit(top, ["fetch", "-q", remote, `+refs/heads/${branch}:refs/remotes/${remote}/${branch}`]);
+    for (const ref of [`refs/remotes/${remote}/${branch}`, `refs/heads/${branch}`]) {
+        const commit = tryGit(top, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]);
+        if (commit)
+            return { commit, ref };
+    }
+    return undefined;
+}
+/** The exact command that lists `publicKey` for `principal`. */
+export function trustCommand(principal, publicKey) {
+    return `chant workspace trust runner add ${principal} --key "${publicKey}"`;
+}
+/** Whether `.chant/trust.json` at `commit` lists the key as a runner holding the runner role: its principal, or why not. */
+export function runnerKeyListed(top, commit, pem) {
+    try {
+        return { ok: true, principal: ciTagSigner(top, commit, pem, "the runs it signs").principal };
+    }
+    catch (err) {
+        return { ok: false, reason: message(err) };
+    }
+}
+/**
+ * Propose the runner entry for review (#4099): in a temporary worktree at
+ * the target's head, run `trust runner add` (#3510), commit the change on
+ * `chant/trust-runner/<principal>`, and push that branch to `remote` when
+ * the clone has it. The target branch is never written. The commit is made
+ * with the host's git identity and signing settings; when the policy at base
+ * has signers, the change needs a signature by a policy writer before it
+ * merges.
+ */
+export function proposeRunnerTrust(req) {
+    const remote = req.remote ?? "origin";
+    const head = targetHead(req.top, req.branch, remote);
+    if (!head)
+        throw new CiRunError(`there is no branch ${req.branch} here or on ${remote}, so there is no trust config to add the runner to`);
+    const branch = `chant/trust-runner/${req.principal.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "")}`;
+    if (tryGit(req.top, ["rev-parse", "--verify", "-q", `refs/heads/${branch}`])) {
+        throw new CiRunError(`the branch ${branch} exists already; review or delete it, then run --setup-key --trust again`);
+    }
+    const dir = mkdtempSync(join(tmpdir(), "chant-trust-runner-"));
+    try {
+        git(req.top, ["worktree", "add", "-q", "-b", branch, dir, head.commit]);
+        const doc = trustWrite({ cwd: dir, action: "runner add", name: req.principal, key: req.publicKey, ...(req.by ? { by: req.by } : {}) });
+        if ("error" in doc)
+            throw new CiRunError(`trust runner add refused (${doc.error.code}): ${doc.error.message}`);
+        if (!doc.changed) {
+            git(req.top, ["worktree", "remove", "--force", dir]);
+            git(req.top, ["branch", "-q", "-D", branch]);
+            return { branch: null, commit: null, pushed: false, digest: doc.digest };
+        }
+        git(dir, ["add", "--", ".chant/trust.json"]);
+        git(dir, ["commit", "-q", "-m", `trust the ${req.principal} runner key\n\nchant ci --setup-key --trust: list this host's runner key in .chant/trust.json (#4099).`]);
+        const commit = git(dir, ["rev-parse", "HEAD"]);
+        let pushed = false;
+        if (tryGit(req.top, ["remote", "get-url", remote]) !== undefined) {
+            try {
+                git(dir, ["push", "-q", remote, `refs/heads/${branch}:refs/heads/${branch}`]);
+                pushed = true;
+            }
+            catch (err) {
+                throw new CiRunError(`committed ${branch} here, and pushing it to ${remote} failed: ${message(err).split("\n")[0]}`);
+            }
+        }
+        return { branch, commit, pushed, digest: doc.digest };
+    }
+    finally {
+        tryGit(req.top, ["worktree", "remove", "--force", dir]);
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** `--setup-key [--trust]`: make or read the key, see whether the target's head lists it, and with `trust` propose the entry. */
+export function setupRunnerKey(req) {
+    const key = ensureHostRunnerKey(req.stateDir);
+    const head = targetHead(req.top, req.branch);
+    const listed = head ? runnerKeyListed(req.top, head.commit, key.pem) : undefined;
+    const principal = req.principal ?? defaultRunnerPrincipal();
+    const out = { key, head: head?.commit ?? null, listedAs: listed?.ok ? listed.principal : null, principal, command: trustCommand(principal, key.publicKey) };
+    if (req.trust && !out.listedAs)
+        out.proposal = proposeRunnerTrust({ top: req.top, branch: req.branch, principal, publicKey: key.publicKey, ...(req.by ? { by: req.by } : {}) });
+    return out;
+}
+/** What `--setup-key` prints on stderr; the public key alone goes to stdout. */
+export function formatRunnerKeySetup(s, branch) {
+    const lines = [`runner key ${s.key.path} (${s.key.created ? "made now, mode 0600" : "already here"})`];
+    if (s.listedAs) {
+        lines.push(`.chant/trust.json at ${branch} ${s.head.slice(0, 12)} lists it for ${s.listedAs}, with the runner role`);
+    }
+    else if (s.proposal?.branch) {
+        lines.push(`committed the runner entry for ${s.principal} on ${s.proposal.branch} (${s.proposal.commit.slice(0, 12)})${s.proposal.pushed ? " and pushed it" : ""}; open a pull request into ${branch}, and the key counts once it merges`);
+        lines.push("changing .chant/trust.json is a protected write: when the trust policy has signers, an admin signs the commit before it merges");
+    }
+    else if (s.proposal) {
+        lines.push(`the runner entry for ${s.principal} is already at ${branch}'s head`);
+    }
+    else {
+        lines.push(`.chant/trust.json at ${branch}${s.head ? ` ${s.head.slice(0, 12)}` : ""} does not list it yet. In a checkout of ${branch}, run`, `  ${s.command}`, "commit the change through review, or run this again with --trust to push it on a branch");
+    }
+    return lines.join("\n");
+}
+/**
+ * The key `ci serve` signs with, checked before its first poll (#4099): the
+ * `--key` file, else `CHANT_RUNNER_KEY`, else the host's key in the state
+ * directory. Signing is opt-in (#4156):
+ *
+ * - With no key, `ci serve` serves unsigned and says so only in `note`.
+ * - A key `.chant/trust.json` at the target's head does not list with the
+ *   runner role, or a target branch it can't find to check against, leaves
+ *   it serving unsigned, with one `warning`.
+ * - With `required` (the declaration's `ci.green.signedSince`) each of
+ *   those refuses to start, as before #4156.
+ *
+ * A key that is not an Ed25519 private key in PEM, or a `--key` file that
+ * can't be read, refuses either way. `unsigned` (`--unsigned`) skips the
+ * key without `required` and is ignored with it.
+ */
+export function ciServeRunnerKey(req) {
+    const required = req.required ?? null;
+    const optIn = `ci.green.signedSince is ${required}, so every run must be signed`;
+    if (req.unsigned && !required)
+        return { fromFlag: false, source: "none (--unsigned)", note: "runs are not signed (--unsigned)" };
+    const host = req.keyFile === undefined && !req.envKey ? hostRunnerKey(req.stateDir) : undefined;
+    const pem = req.keyFile !== undefined ? readFileSync(req.keyFile, "utf-8") : req.envKey || host?.pem;
+    const source = req.keyFile !== undefined ? req.keyFile : req.envKey ? "CHANT_RUNNER_KEY" : (host?.path ?? join(req.stateDir, RUNNER_KEY_FILE));
+    if (pem === undefined) {
+        if (!required)
+            return { fromFlag: false, source: "none", note: "runs are not signed: there is no runner key. To verify who ran a job, add one with chant ci serve --setup-key --trust" };
+        throw new CiRunError(`${optIn}, and there is no runner key: no --key, no CHANT_RUNNER_KEY and no ${source}. Make one with chant ci serve --setup-key and list it with --trust`);
+    }
+    let publicKey;
+    try {
+        publicKey = loadRunnerKey(pem).publicKey;
+    }
+    catch (err) {
+        throw new CiRunError(`the runner key from ${source} is not an Ed25519 private key in PEM: ${message(err)}`);
+    }
+    const head = targetHead(req.top, req.branch);
+    if (!head) {
+        const why = `there is no branch ${req.branch} here or on origin, so the runner key can't be checked against its .chant/trust.json`;
+        if (required)
+            throw new CiRunError(`${optIn}, and ${why}; fetch it`);
+        return { fromFlag: false, source, warning: `${why}, so runs are not signed; fetch it to sign them` };
+    }
+    const listed = runnerKeyListed(req.top, head.commit, pem);
+    if (!listed.ok) {
+        const why = `the runner key from ${source} is not trusted at ${branchAt(req.branch, head.commit)}: ${listed.reason}`;
+        const fix = `List it on a branch for review with chant ci serve --setup-key --trust, or run ${trustCommand(defaultRunnerPrincipal(), publicKey)} in a checkout of ${req.branch} and merge the change.`;
+        if (required)
+            throw new CiRunError(`${optIn}, and ${why}\n  ${fix}`);
+        return { fromFlag: false, source, warning: `${why}. Runs are not signed until it is. ${fix}` };
+    }
+    return { pem, fromFlag: req.keyFile !== undefined, source };
+}
+const branchAt = (branch, commit) => `${branch} ${commit.slice(0, 12)}`;

package/dist/workspace/ci-secrets.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The chant runner's secrets file (#4096, epic #4101): the values a job gets
+ * from the host, such as cloud credentials and the endpoint, which a forge
+ * job would get from the forge's secrets.
+ *
+ * `chant ci run` and `chant ci serve` read it from `--secrets <file>`, or
+ * the file `CHANT_CI_SECRETS` names. It is a dotenv file of `NAME=value`
+ * lines, or a JSON object:
+ *
+ * - a map of name to value, `{ "AWS_SECRET_ACCESS_KEY": "..." }`;
+ * - or `{ "secrets": { ... }, "jobs": { "plan": [...], "apply": [...] } }`,
+ *   where `jobs` lists, for a job, the names it gets. A job `jobs` doesn't
+ *   name gets every secret.
+ *
+ * The allowlist lives in this file on the host, not in the repository, so a
+ * pull request can't widen what its plan gets.
+ *
+ * The file must belong to the user reading it and give group and others no
+ * permission at all, as ssh asks of a private key (`chmod 600`). A file
+ * that does is refused before any job runs.
+ *
+ * Every value in the file, and every value of the job's environment whose
+ * name looks secret ({@link SECRET_NAME}), is redacted from what the run
+ * writes about itself (../op/redact.ts).
+ */
+import { type Redact } from "../op/redact.js";
+import type { CiJobName } from "./ci-run.js";
+/** The variable that names the secrets file when `--secrets` is not given. */
+export declare const CI_SECRETS_ENV = "CHANT_CI_SECRETS";
+/** A variable whose name matches this is taken as secret, and its value redacted. */
+export declare const SECRET_NAME: RegExp;
+/** The secrets file, read. */
+export interface CiSecrets {
+    /** Where it was read from. */
+    file: string;
+    /** Every secret, by name. */
+    values: Record<string, string>;
+    /** For a job the file names, the secrets it gets. A job missing here gets every one. */
+    jobs: Partial<Record<CiJobName, string[]>>;
+}
+export declare class CiSecretsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Refuse a secrets file anyone but its owner can read or write, or that
+ * belongs to another user, as ssh refuses a loose key. Not checked on
+ * Windows, whose files carry no such mode.
+ */
+export declare function checkCiSecretsMode(file: string): void;
+/** A dotenv text's `NAME=value` pairs. Errors name the line, never a value. */
+export declare function parseDotenv(text: string, file: string): Record<string, string>;
+/** The secrets in a file's text: JSON when it starts with `{`, else dotenv. */
+export declare function parseCiSecrets(text: string, file: string): Omit<CiSecrets, "file">;
+/** Read the secrets file, refusing one others can read. */
+export declare function readCiSecrets(file: string): CiSecrets;
+/** The secrets `job` gets: those `jobs` lists for it, else every one. */
+export declare function ciSecretsFor(secrets: CiSecrets | undefined, job: CiJobName): Record<string, string>;
+/**
+ * The redactor for a job: every value in the secrets file, whether the job
+ * gets it or not, and the value of each variable in the job's environment
+ * whose name looks secret, such as `GITHUB_TOKEN` or a `--pass-env
+ * AWS_SECRET_ACCESS_KEY`. Undefined when there is nothing to redact.
+ */
+export declare function ciRedactor(jobEnv: Record<string, string>, secrets?: CiSecrets): Redact | undefined;
+//# sourceMappingURL=ci-secrets.d.ts.map

package/dist/workspace/ci-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-secrets.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,8EAA8E;AAC9E,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAEjD,qFAAqF;AACrF,eAAO,MAAM,WAAW,QAA+B,CAAC;AAMxD,8BAA8B;AAC9B,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,wFAAwF;IACxF,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;CAC5C;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAoBrD;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0D9E;AAOD,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAmClF;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAGrD;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAInG;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAIlG"}

package/dist/workspace/ci-secrets.js

@@ -0,0 +1,211 @@
+/**
+ * The chant runner's secrets file (#4096, epic #4101): the values a job gets
+ * from the host, such as cloud credentials and the endpoint, which a forge
+ * job would get from the forge's secrets.
+ *
+ * `chant ci run` and `chant ci serve` read it from `--secrets <file>`, or
+ * the file `CHANT_CI_SECRETS` names. It is a dotenv file of `NAME=value`
+ * lines, or a JSON object:
+ *
+ * - a map of name to value, `{ "AWS_SECRET_ACCESS_KEY": "..." }`;
+ * - or `{ "secrets": { ... }, "jobs": { "plan": [...], "apply": [...] } }`,
+ *   where `jobs` lists, for a job, the names it gets. A job `jobs` doesn't
+ *   name gets every secret.
+ *
+ * The allowlist lives in this file on the host, not in the repository, so a
+ * pull request can't widen what its plan gets.
+ *
+ * The file must belong to the user reading it and give group and others no
+ * permission at all, as ssh asks of a private key (`chmod 600`). A file
+ * that does is refused before any job runs.
+ *
+ * Every value in the file, and every value of the job's environment whose
+ * name looks secret ({@link SECRET_NAME}), is redacted from what the run
+ * writes about itself (../op/redact.ts).
+ */
+import { readFileSync, statSync } from "node:fs";
+import { redactorOf } from "../op/redact.js";
+import { RUNNER_KEY_ENV } from "./ci-green.js";
+/** The variable that names the secrets file when `--secrets` is not given. */
+export const CI_SECRETS_ENV = "CHANT_CI_SECRETS";
+/** A variable whose name matches this is taken as secret, and its value redacted. */
+export const SECRET_NAME = /TOKEN|SECRET|KEY|PASSWORD/i;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const JOBS = ["plan", "apply"];
+export class CiSecretsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CiSecretsError";
+    }
+}
+/**
+ * Refuse a secrets file anyone but its owner can read or write, or that
+ * belongs to another user, as ssh refuses a loose key. Not checked on
+ * Windows, whose files carry no such mode.
+ */
+export function checkCiSecretsMode(file) {
+    let st;
+    try {
+        st = statSync(file);
+    }
+    catch (err) {
+        throw new CiSecretsError(`the secrets file ${file} can't be read: ${err.code ?? String(err)}`);
+    }
+    if (!st.isFile())
+        throw new CiSecretsError(`the secrets file ${file} is not a file`);
+    if (process.platform === "win32")
+        return;
+    const loose = Number(st.mode) & 0o077;
+    if (loose !== 0) {
+        const mode = (Number(st.mode) & 0o777).toString(8).padStart(4, "0");
+        throw new CiSecretsError(`the secrets file ${file} has mode ${mode}, so its group or other users can ${loose & 0o044 ? "read" : "change"} it; a secrets file must be readable only by its owner, as ssh asks of a key: chmod 600 ${file}`);
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (uid !== undefined && Number(st.uid) !== uid) {
+        throw new CiSecretsError(`the secrets file ${file} belongs to uid ${st.uid}, not to this user (uid ${uid}); a secrets file must be its reader's own`);
+    }
+}
+/** A dotenv text's `NAME=value` pairs. Errors name the line, never a value. */
+export function parseDotenv(text, file) {
+    const out = {};
+    let i = 0;
+    let line = 1;
+    const fail = (why) => {
+        throw new CiSecretsError(`${file}:${line}: ${why}`);
+    };
+    while (i < text.length) {
+        // One line: blank, a comment, or NAME=value.
+        const eol = text.indexOf("\n", i);
+        const rest = text.slice(i, eol === -1 ? text.length : eol);
+        const trimmed = rest.trim();
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            i = eol === -1 ? text.length : eol + 1;
+            line++;
+            continue;
+        }
+        const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*/.exec(rest);
+        if (!m)
+            fail("expected NAME=value");
+        const name = m[1];
+        let j = i + m[0].length;
+        const startLine = line;
+        let value = "";
+        const q = text[j];
+        if (q === '"' || q === "'") {
+            j++;
+            for (;;) {
+                if (j >= text.length) {
+                    line = startLine;
+                    fail(`the value of ${name} has no closing ${q}`);
+                }
+                const c = text[j];
+                if (c === q)
+                    break;
+                if (c === "\n")
+                    line++;
+                if (q === '"' && c === "\\" && j + 1 < text.length) {
+                    const n = text[j + 1];
+                    value += n === "n" ? "\n" : n === "r" ? "\r" : n === "t" ? "\t" : n;
+                    j += 2;
+                    continue;
+                }
+                value += c;
+                j++;
+            }
+            j++;
+            const end = text.indexOf("\n", j);
+            const after = text.slice(j, end === -1 ? text.length : end).trim();
+            if (after !== "" && !after.startsWith("#"))
+                fail(`unexpected text after the quoted value of ${name}`);
+            i = end === -1 ? text.length : end + 1;
+        }
+        else {
+            const end = text.indexOf("\n", j);
+            value = text.slice(j, end === -1 ? text.length : end).replace(/\s+#.*$/, "").trim();
+            i = end === -1 ? text.length : end + 1;
+        }
+        if (Object.prototype.hasOwnProperty.call(out, name))
+            fail(`${name} is set twice`);
+        out[name] = value;
+        line++;
+    }
+    return out;
+}
+function checkName(name, file) {
+    if (!ENV_NAME.test(name))
+        throw new CiSecretsError(`${file} names a secret ${JSON.stringify(name)}, which is not a variable name`);
+    if (name === RUNNER_KEY_ENV)
+        throw new CiSecretsError(`${file} sets ${RUNNER_KEY_ENV}, and the runner key is never passed to a job; give it to ci run or ci serve with --key or ${RUNNER_KEY_ENV}`);
+}
+/** The secrets in a file's text: JSON when it starts with `{`, else dotenv. */
+export function parseCiSecrets(text, file) {
+    if (!text.trimStart().startsWith("{")) {
+        const values = parseDotenv(text, file);
+        for (const name of Object.keys(values))
+            checkName(name, file);
+        return { values, jobs: {} };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        // The parser's message quotes the text near the error, which may be a secret.
+        throw new CiSecretsError(`${file} starts with {, and is not valid JSON`);
+    }
+    const doc = raw;
+    const structured = doc.secrets !== null && typeof doc.secrets === "object" && !Array.isArray(doc.secrets);
+    const map = (structured ? doc.secrets : doc);
+    const values = {};
+    for (const [name, value] of Object.entries(map)) {
+        checkName(name, file);
+        if (typeof value !== "string")
+            throw new CiSecretsError(`${file}: the secret ${name} must be a string`);
+        values[name] = value;
+    }
+    const jobs = {};
+    if (structured) {
+        for (const key of Object.keys(doc))
+            if (key !== "secrets" && key !== "jobs")
+                throw new CiSecretsError(`${file} has ${JSON.stringify(key)} beside secrets and jobs`);
+        const given = doc.jobs ?? {};
+        if (given === null || typeof given !== "object" || Array.isArray(given))
+            throw new CiSecretsError(`${file}: jobs must map plan and apply to lists of secret names`);
+        for (const [job, names] of Object.entries(given)) {
+            if (!JOBS.includes(job))
+                throw new CiSecretsError(`${file}: jobs names ${JSON.stringify(job)}, and the jobs are plan and apply`);
+            if (!Array.isArray(names) || names.some((n) => typeof n !== "string"))
+                throw new CiSecretsError(`${file}: jobs.${job} must be a list of secret names`);
+            for (const n of names)
+                if (!Object.prototype.hasOwnProperty.call(values, n))
+                    throw new CiSecretsError(`${file}: jobs.${job} names ${n}, which the file does not set`);
+            jobs[job] = [...names];
+        }
+    }
+    return { values, jobs };
+}
+/** Read the secrets file, refusing one others can read. */
+export function readCiSecrets(file) {
+    checkCiSecretsMode(file);
+    return { file, ...parseCiSecrets(readFileSync(file, "utf-8"), file) };
+}
+/** The secrets `job` gets: those `jobs` lists for it, else every one. */
+export function ciSecretsFor(secrets, job) {
+    if (!secrets)
+        return {};
+    const names = secrets.jobs[job] ?? Object.keys(secrets.values);
+    return Object.fromEntries(names.map((n) => [n, secrets.values[n]]));
+}
+/**
+ * The redactor for a job: every value in the secrets file, whether the job
+ * gets it or not, and the value of each variable in the job's environment
+ * whose name looks secret, such as `GITHUB_TOKEN` or a `--pass-env
+ * AWS_SECRET_ACCESS_KEY`. Undefined when there is nothing to redact.
+ */
+export function ciRedactor(jobEnv, secrets) {
+    const values = Object.values(secrets?.values ?? {});
+    for (const [name, value] of Object.entries(jobEnv))
+        if (SECRET_NAME.test(name))
+            values.push(value);
+    return redactorOf(values);
+}