@intentius/chant 0.124.40 → 0.124.42

package/dist/__fixtures__/oidc-emulator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A local emulator of every service the OIDC trade (#4296, ../ci-identity.ts)
+ * talks to, for tests: the forge's token request URL, AWS STS, Google's STS
+ * and IAM credentials, and Entra's token endpoint. It answers with test
+ * values only and keeps every request, so a test can say which identity
+ * was asked for and how many tokens were minted.
+ */
+import type { CloudTradeSpec } from "../ci-identity.js";
+/** What the emulator was asked. */
+export interface EmulatorLog {
+    /** Each OIDC token minted: its audience. */
+    minted: string[];
+    /** Each AWS role assumed, with the token it was assumed with. */
+    assumed: Array<{
+        role: string;
+        token: string;
+    }>;
+    /** Each GCP service account impersonated. */
+    impersonated: string[];
+    /** Each Azure client a token was traded for, with the token. */
+    clients: Array<{
+        clientId: string;
+        token: string;
+    }>;
+}
+export interface OidcEmulator {
+    url: string;
+    log: EmulatorLog;
+    /** The forge's token request variables, as a GitHub or Forgejo job with `id-token: write` has them. */
+    requestEnv: {
+        ACTIONS_ID_TOKEN_REQUEST_URL: string;
+        ACTIONS_ID_TOKEN_REQUEST_TOKEN: string;
+    };
+    /** `spec` with each cloud pointed at the emulator. */
+    pointAt(spec: CloudTradeSpec): CloudTradeSpec;
+    close(): Promise<void>;
+}
+/** The request token the emulator accepts, and the prefix of every token it mints. */
+export declare const EMULATED_REQUEST_TOKEN = "emulated-oidc-request-token-4296";
+export declare const EMULATED_JWT_PREFIX = "eyJemulated4296";
+/** The test credentials the emulator hands out for an identity: they name it, so a test can tell which was traded. */
+export declare function emulatedCredentials(identity: string): {
+    accessKeyId: string;
+    secret: string;
+    token: string;
+};
+/** Start the emulator on a free local port. */
+export declare function startOidcEmulator(): Promise<OidcEmulator>;
+//# sourceMappingURL=oidc-emulator.d.ts.map

package/dist/__fixtures__/oidc-emulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc-emulator.d.ts","sourceRoot":"","sources":["../../src/__fixtures__/oidc-emulator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iEAAiE;IACjE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,6CAA6C;IAC7C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,gEAAgE;IAChE,OAAO,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,WAAW,CAAC;IACjB,uGAAuG;IACvG,UAAU,EAAE;QAAE,4BAA4B,EAAE,MAAM,CAAC;QAAC,8BAA8B,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7F,sDAAsD;IACtD,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAAC;IAC9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AACzE,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD,sHAAsH;AACtH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAG5G;AASD,+CAA+C;AAC/C,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,YAAY,CAAC,CAiE/D"}

package/dist/__fixtures__/oidc-emulator.js

@@ -0,0 +1,89 @@
+/**
+ * A local emulator of every service the OIDC trade (#4296, ../ci-identity.ts)
+ * talks to, for tests: the forge's token request URL, AWS STS, Google's STS
+ * and IAM credentials, and Entra's token endpoint. It answers with test
+ * values only and keeps every request, so a test can say which identity
+ * was asked for and how many tokens were minted.
+ */
+import { createServer } from "node:http";
+/** The request token the emulator accepts, and the prefix of every token it mints. */
+export const EMULATED_REQUEST_TOKEN = "emulated-oidc-request-token-4296";
+export const EMULATED_JWT_PREFIX = "eyJemulated4296";
+/** The test credentials the emulator hands out for an identity: they name it, so a test can tell which was traded. */
+export function emulatedCredentials(identity) {
+    const tag = identity.replace(/[^A-Za-z0-9]/g, "").slice(-24);
+    return { accessKeyId: `ASIATEST${tag}`, secret: `secret-${tag}`, token: `session-${tag}` };
+}
+const body = (req) => new Promise((ok) => {
+    let b = "";
+    req.on("data", (c) => (b += c));
+    req.on("end", () => ok(b));
+});
+/** Start the emulator on a free local port. */
+export async function startOidcEmulator() {
+    const log = { minted: [], assumed: [], impersonated: [], clients: [] };
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        const text = await body(req);
+        const send = (status, payload, type = "application/json") => {
+            res.writeHead(status, { "content-type": type });
+            res.end(typeof payload === "string" ? payload : JSON.stringify(payload));
+        };
+        if (url.pathname === "/oidc") {
+            if (req.headers.authorization !== `bearer ${EMULATED_REQUEST_TOKEN}`)
+                return send(401, { message: "bad request token" });
+            const aud = url.searchParams.get("audience") ?? "";
+            log.minted.push(aud);
+            return send(200, { value: `${EMULATED_JWT_PREFIX}.${Buffer.from(aud).toString("base64url")}.${log.minted.length}` });
+        }
+        if (url.pathname === "/aws/") {
+            const form = new URLSearchParams(text);
+            const role = form.get("RoleArn") ?? "";
+            const token = form.get("WebIdentityToken") ?? "";
+            if (form.get("Action") !== "AssumeRoleWithWebIdentity" || !token.startsWith("eyJ"))
+                return send(400, "<Error>bad request</Error>", "text/xml");
+            log.assumed.push({ role, token });
+            const c = emulatedCredentials(role);
+            return send(200, `<AssumeRoleWithWebIdentityResponse><AssumeRoleWithWebIdentityResult><Credentials><AccessKeyId>${c.accessKeyId}</AccessKeyId><SecretAccessKey>${c.secret}</SecretAccessKey><SessionToken>${c.token}</SessionToken><Expiration>2026-10-22T23:00:00Z</Expiration></Credentials></AssumeRoleWithWebIdentityResult></AssumeRoleWithWebIdentityResponse>`, "text/xml");
+        }
+        if (url.pathname === "/gcp-sts/v1/token") {
+            const j = JSON.parse(text);
+            if (!j.subjectToken?.startsWith("eyJ"))
+                return send(400, { error: "bad subject token" });
+            return send(200, { access_token: "federated-test-token", token_type: "Bearer" });
+        }
+        const sa = /^\/gcp-iam\/v1\/projects\/-\/serviceAccounts\/([^/:]+):generateAccessToken$/.exec(url.pathname);
+        if (sa) {
+            if (req.headers.authorization !== "Bearer federated-test-token")
+                return send(401, { error: "bad federated token" });
+            const name = decodeURIComponent(sa[1]);
+            log.impersonated.push(name);
+            return send(200, { accessToken: `ya29.${emulatedCredentials(name).token}`, expireTime: "2026-10-22T23:00:00Z" });
+        }
+        if (/^\/azure\/[^/]+\/oauth2\/v2\.0\/token$/.test(url.pathname)) {
+            const form = new URLSearchParams(text);
+            const clientId = form.get("client_id") ?? "";
+            const token = form.get("client_assertion") ?? "";
+            if (form.get("grant_type") !== "client_credentials" || !token.startsWith("eyJ"))
+                return send(400, { error: "bad grant" });
+            log.clients.push({ clientId, token });
+            return send(200, { access_token: `azure.${emulatedCredentials(clientId).token}`, token_type: "Bearer" });
+        }
+        send(404, { message: `no route ${url.pathname}` });
+    });
+    await new Promise((ok) => server.listen(0, "127.0.0.1", ok));
+    const url = `http://127.0.0.1:${server.address().port}`;
+    return {
+        url,
+        log,
+        requestEnv: { ACTIONS_ID_TOKEN_REQUEST_URL: `${url}/oidc?api-version=2.0`, ACTIONS_ID_TOKEN_REQUEST_TOKEN: EMULATED_REQUEST_TOKEN },
+        pointAt(spec) {
+            return {
+                ...(spec.aws ? { aws: { ...spec.aws, endpoint: `${url}/aws` } } : {}),
+                ...(spec.gcp ? { gcp: { ...spec.gcp, stsEndpoint: `${url}/gcp-sts`, iamEndpoint: `${url}/gcp-iam` } } : {}),
+                ...(spec.azure ? { azure: { ...spec.azure, authority: `${url}/azure` } } : {}),
+            };
+        },
+        close: () => new Promise((ok) => server.close(() => ok())),
+    };
+}

package/dist/ci-handover.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The forge token handover (#4295): no step that runs a pull request's code
+ * holds a forge token.
+ *
+ * A pull request's plan runs its code: the synth of its components, the
+ * plans their capabilities run, its build and lint, and its hooks. A token
+ * that can post a note or set a status can also push, so the generated plan
+ * job uses the job's token for the checkout's fetches alone and drops it
+ * before anything else runs. The ordering is terragucci's `handover.ts`
+ * (INTENTIUS/terragucci e6cb431, packages/terragucci/src/handover.ts):
+ *
+ * 1. The checkout is a script ({@link checkoutScript}), not actions/checkout,
+ *    whose post step runs at the job's end with the token as its input. The
+ *    token reaches its fetches through the environment, never the git config.
+ * 2. Every later step starts again without the token variables
+ *    ({@link dropForgeTokens}).
+ * 3. The plan step is the job's last. A step after it would start beside
+ *    whatever the change's code left running, with what it wrote to
+ *    GITHUB_ENV and GITHUB_PATH. So the plan step hands its report directory
+ *    on as the job's outputs ({@link handoverTrap}) in place of an artifact
+ *    upload.
+ * 4. A fresh job, `plan-note`, checks out the target branch's commit, takes
+ *    the report back ({@link takeOverScript}), keeps it as the artifact, and
+ *    posts the note and the status with the token (`chant components
+ *    pr-post`, ./pr-post.ts). It reads the report as data.
+ *
+ * `chant ci run plan` keeps the same rule: no step of the plan job gets a
+ * forge token, and the runner posts from the report once the steps settle
+ * (../workspace/ci-run.ts).
+ */
+import type { ForgeKind } from "./pr-forge.js";
+/**
+ * The variables a runner, a job or a secret may hold a forge token in.
+ * A step that runs the change's code starts without them. The list is
+ * terragucci's `STEP_TOKEN_VARS` (render.ts:1787) with chant's own names
+ * (`FORGE_TOKEN_ENV` in ./pr-forge.ts) and GitLab's added.
+ */
+export declare const FORGE_TOKEN_VARS: readonly ["CHANT_FORGE_TOKEN", "CHANT_GITHUB_TOKEN", "CHANT_FORGEJO_TOKEN", "CHANT_GITLAB_TOKEN", "CHANT_CHECKOUT_TOKEN", "GITHUB_TOKEN", "GH_TOKEN", "FORGEJO_TOKEN", "GITEA_TOKEN", "GITLAB_TOKEN", "CI_JOB_TOKEN", "ACTIONS_RUNTIME_TOKEN"];
+/** `env` without {@link FORGE_TOKEN_VARS}. */
+export declare function withoutForgeTokens<T extends Record<string, string | undefined>>(env: T): T;
+/** Whether `env` holds a forge token under one of {@link FORGE_TOKEN_VARS}. */
+export declare function holdsForgeToken(env: Record<string, string | undefined>): boolean;
+/** The marker a step {@link dropForgeTokens} restarted carries. */
+export declare const NO_FORGE_TOKEN_MARKER = "CHANT_NO_FORGE_TOKEN";
+/**
+ * The first line of a step that runs the change's code: restart the step's
+ * shell once without the token variables in its process environment, or,
+ * when it cannot restart, unset them. Unsetting alone leaves the values in
+ * the shell's own initial environment, which a child reads on Linux from
+ * `/proc/<pid>/environ`; the restart replaces it. A forge runs a step's
+ * script as a file (`sh -e {0}` in a GitHub or Forgejo container job), so
+ * `$0` is that file. terragucci's `restartWithout` (render.ts:1826).
+ */
+export declare function dropForgeTokens(shell?: "sh" | "bash", extra?: readonly string[]): string;
+/** The line a GitLab plan job starts its script with: GitLab runs the script in one shell, so the unset holds for every line after it. */
+export declare const GITLAB_DROP_FORGE_TOKENS: string;
+/** The forges whose plan job hands its report on through job outputs. GitLab passes the artifact to the next job itself. */
+export type HandoverForge = Exclude<ForgeKind, "gitlab">;
+/**
+ * How many outputs the plan job hands its report on in, and the most
+ * characters each holds. Forgejo keeps each output's value to 1 MiB. GitHub
+ * keeps a job's outputs to 1 MB together, sized as UTF-16. terragucci's
+ * `HANDOVER_LIMITS` (handover.ts).
+ */
+export declare const HANDOVER_LIMITS: Record<HandoverForge, {
+    chunk: number;
+    parts: number;
+}>;
+/** The outputs' names on a forge: report_0, report_1, ... */
+export declare function handoverKeys(forge: HandoverForge): string[];
+/** The files the note job reads, which a report too large to hand on whole is cut to. */
+export declare const HANDOVER_NOTE_FILES: readonly ["pr-plan.json", "pr-note.md"];
+/**
+ * Packs the report directory (argv 1) into the step's output file (argv 2):
+ * every regular file, found without following a link, as gzipped JSON in
+ * base64, cut into the forge's chunks. A report too large is cut to
+ * {@link HANDOVER_NOTE_FILES}, and to none when even those are too large.
+ */
+export declare function packJs(forge: HandoverForge): string;
+/**
+ * Writes back, under the directory argv 1 names, the files the plan job
+ * handed on: stdin holds its outputs, one JSON string a line. A path is kept
+ * only when it is plain segments (no empty one, no `.` or `..`, no backslash
+ * or control character), so nothing lands outside the directory.
+ */
+export declare const UNPACK_JS: string;
+/**
+ * The lines of the plan step, after {@link dropForgeTokens}: when the step
+ * ends, however it ends, its report directory (`dir`, from the directory the
+ * step starts in) goes into the step's outputs.
+ */
+export declare function handoverTrap(dir: string, forge: HandoverForge): string[];
+/** A job's outputs that carry the report its step `step` handed on. */
+export declare function handoverOutputs(step: string, forge: HandoverForge): Record<string, string>;
+/**
+ * The script of the step that takes the report job `job` handed on into
+ * `dir`. Each output comes in as toJSON's string, one line of a quoted
+ * heredoc whose end no JSON string can be, so the change's outputs stay data.
+ */
+export declare function takeOverScript(job: string, dir: string, forge: HandoverForge): string;
+/** The variable the checkout script reads the job's token from. */
+export declare const CHECKOUT_TOKEN_ENV = "CHANT_CHECKOUT_TOKEN";
+/**
+ * Checks the run's commit out with git, as actions/checkout does without
+ * credentials kept: `GITHUB_SHA` under `GITHUB_REF`. With `history`, every
+ * branch and tag too, since the plan measures the change with git. The job's
+ * token ({@link CHECKOUT_TOKEN_ENV}) reaches the fetches alone, through the
+ * environment, never the git config. A workspace already checked out is
+ * cleaned first, as actions/checkout does. terragucci's `checkoutScript`
+ * (handover.ts). With `ledger`, the `chant/lifecycle` branch is fetched
+ * into a local branch too, while the token is there: the plan reads the
+ * gate ledger from it, and a later fetch without the token cannot reach a
+ * private repository (`requireLifecycleLedger` in ./lifecycle/git.ts reads
+ * the local branch when the fetch fails).
+ */
+export declare function checkoutScript(history: boolean, ledger?: boolean): string;
+//# sourceMappingURL=ci-handover.d.ts.map

package/dist/ci-handover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-handover.d.ts","sourceRoot":"","sources":["../src/ci-handover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,YAC3B,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,UAAU,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,uBAAuB,CACf,CAAC;AAEX,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAI1F;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAEhF;AAED,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,yBAAyB,CAAC;AAE5D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAE,IAAI,GAAG,MAAa,EAAE,KAAK,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAOlG;AAED,0IAA0I;AAC1I,eAAO,MAAM,wBAAwB,QAAwC,CAAC;AAE9E,4HAA4H;AAC5H,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,aAAa,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAGnF,CAAC;AAEF,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CAE3D;AAED,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,YAAI,cAAc,EAAE,YAAY,CAAU,CAAC;AAE3E;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAiBnD;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,QAaZ,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CAMxE;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE1F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAOrF;AAED,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAQ,GAAG,MAAM,CA8BvE"}

package/dist/ci-handover.js

@@ -0,0 +1,217 @@
+/**
+ * The forge token handover (#4295): no step that runs a pull request's code
+ * holds a forge token.
+ *
+ * A pull request's plan runs its code: the synth of its components, the
+ * plans their capabilities run, its build and lint, and its hooks. A token
+ * that can post a note or set a status can also push, so the generated plan
+ * job uses the job's token for the checkout's fetches alone and drops it
+ * before anything else runs. The ordering is terragucci's `handover.ts`
+ * (INTENTIUS/terragucci e6cb431, packages/terragucci/src/handover.ts):
+ *
+ * 1. The checkout is a script ({@link checkoutScript}), not actions/checkout,
+ *    whose post step runs at the job's end with the token as its input. The
+ *    token reaches its fetches through the environment, never the git config.
+ * 2. Every later step starts again without the token variables
+ *    ({@link dropForgeTokens}).
+ * 3. The plan step is the job's last. A step after it would start beside
+ *    whatever the change's code left running, with what it wrote to
+ *    GITHUB_ENV and GITHUB_PATH. So the plan step hands its report directory
+ *    on as the job's outputs ({@link handoverTrap}) in place of an artifact
+ *    upload.
+ * 4. A fresh job, `plan-note`, checks out the target branch's commit, takes
+ *    the report back ({@link takeOverScript}), keeps it as the artifact, and
+ *    posts the note and the status with the token (`chant components
+ *    pr-post`, ./pr-post.ts). It reads the report as data.
+ *
+ * `chant ci run plan` keeps the same rule: no step of the plan job gets a
+ * forge token, and the runner posts from the report once the steps settle
+ * (../workspace/ci-run.ts).
+ */
+/**
+ * The variables a runner, a job or a secret may hold a forge token in.
+ * A step that runs the change's code starts without them. The list is
+ * terragucci's `STEP_TOKEN_VARS` (render.ts:1787) with chant's own names
+ * (`FORGE_TOKEN_ENV` in ./pr-forge.ts) and GitLab's added.
+ */
+export const FORGE_TOKEN_VARS = [
+    "CHANT_FORGE_TOKEN",
+    "CHANT_GITHUB_TOKEN",
+    "CHANT_FORGEJO_TOKEN",
+    "CHANT_GITLAB_TOKEN",
+    "CHANT_CHECKOUT_TOKEN",
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+    "FORGEJO_TOKEN",
+    "GITEA_TOKEN",
+    "GITLAB_TOKEN",
+    "CI_JOB_TOKEN",
+    "ACTIONS_RUNTIME_TOKEN",
+];
+/** `env` without {@link FORGE_TOKEN_VARS}. */
+export function withoutForgeTokens(env) {
+    const out = { ...env };
+    for (const name of FORGE_TOKEN_VARS)
+        delete out[name];
+    return out;
+}
+/** Whether `env` holds a forge token under one of {@link FORGE_TOKEN_VARS}. */
+export function holdsForgeToken(env) {
+    return FORGE_TOKEN_VARS.some((name) => (env[name] ?? "") !== "");
+}
+/** The marker a step {@link dropForgeTokens} restarted carries. */
+export const NO_FORGE_TOKEN_MARKER = "CHANT_NO_FORGE_TOKEN";
+/**
+ * The first line of a step that runs the change's code: restart the step's
+ * shell once without the token variables in its process environment, or,
+ * when it cannot restart, unset them. Unsetting alone leaves the values in
+ * the shell's own initial environment, which a child reads on Linux from
+ * `/proc/<pid>/environ`; the restart replaces it. A forge runs a step's
+ * script as a file (`sh -e {0}` in a GitHub or Forgejo container job), so
+ * `$0` is that file. terragucci's `restartWithout` (render.ts:1826).
+ */
+export function dropForgeTokens(shell = "sh", extra = []) {
+    const again = shell === "bash" ? 'bash --noprofile --norc -e -o pipefail "$0"' : 'sh -e "$0"';
+    const marker = NO_FORGE_TOKEN_MARKER;
+    // #4296: a plan job that traded its OIDC token drops the variables a token is requested with too.
+    const vars = [...FORGE_TOKEN_VARS, ...extra];
+    const can = `[ -z "\${${marker}:-}" ] && [ "\${0#*/}" != "$0" ] && [ -f "$0" ] && ! { [ "\${0##*/}" = sh ] || [ "\${0##*/}" = bash ] || [ "\${0##*/}" = dash ]; } && command -v env >/dev/null 2>&1 && command -v ${shell} >/dev/null 2>&1`;
+    return `if ${can}; then exec env ${vars.map((v) => `-u ${v}`).join(" ")} ${marker}=1 ${again}; fi; unset ${vars.join(" ")}`;
+}
+/** The line a GitLab plan job starts its script with: GitLab runs the script in one shell, so the unset holds for every line after it. */
+export const GITLAB_DROP_FORGE_TOKENS = `unset ${FORGE_TOKEN_VARS.join(" ")}`;
+/**
+ * How many outputs the plan job hands its report on in, and the most
+ * characters each holds. Forgejo keeps each output's value to 1 MiB. GitHub
+ * keeps a job's outputs to 1 MB together, sized as UTF-16. terragucci's
+ * `HANDOVER_LIMITS` (handover.ts).
+ */
+export const HANDOVER_LIMITS = {
+    forgejo: { chunk: 1000000, parts: 4 },
+    github: { chunk: 450000, parts: 1 },
+};
+/** The outputs' names on a forge: report_0, report_1, ... */
+export function handoverKeys(forge) {
+    return Array.from({ length: HANDOVER_LIMITS[forge].parts }, (_, i) => `report_${i}`);
+}
+/** The files the note job reads, which a report too large to hand on whole is cut to. */
+export const HANDOVER_NOTE_FILES = ["pr-plan.json", "pr-note.md"];
+/**
+ * Packs the report directory (argv 1) into the step's output file (argv 2):
+ * every regular file, found without following a link, as gzipped JSON in
+ * base64, cut into the forge's chunks. A report too large is cut to
+ * {@link HANDOVER_NOTE_FILES}, and to none when even those are too large.
+ */
+export function packJs(forge) {
+    const { chunk, parts } = HANDOVER_LIMITS[forge];
+    return [
+        'const fs=require("fs"),p=require("path"),z=require("zlib");',
+        "const [dir,out]=process.argv.slice(1);",
+        `const CHUNK=${chunk},PARTS=${parts},NOTE=${JSON.stringify(HANDOVER_NOTE_FILES)};`,
+        "const all={};",
+        'const walk=(d,r)=>{let n=[];try{n=fs.readdirSync(d).sort()}catch{return}for(const x of n){const f=p.join(d,x),k=r?r+"/"+x:x;let s;try{s=fs.lstatSync(f)}catch{continue}if(s.isDirectory())walk(f,k);else if(s.isFile())all[k]=fs.readFileSync(f).toString("base64")}};',
+        'walk(dir,"");',
+        'const pack=(o)=>z.gzipSync(JSON.stringify(o)).toString("base64");',
+        "let b=pack(all);",
+        "if(b.length>CHUNK*PARTS){b=pack(Object.fromEntries(Object.entries(all).filter(([k])=>NOTE.includes(k))));",
+        'if(b.length>CHUNK*PARTS){b=pack({});console.error("chant: the plan report is too large to hand to the note job, even cut to the report and the note; it hands on none of it")}',
+        'else console.error("chant: the plan report is too large to hand to the note job whole; it hands on pr-plan.json and pr-note.md")}',
+        'let o="";for(let i=0;i*CHUNK<b.length;i++)o+="report_"+i+"="+b.slice(i*CHUNK,(i+1)*CHUNK)+"\\n";',
+        "fs.appendFileSync(out,o);",
+    ].join("");
+}
+/**
+ * Writes back, under the directory argv 1 names, the files the plan job
+ * handed on: stdin holds its outputs, one JSON string a line. A path is kept
+ * only when it is plain segments (no empty one, no `.` or `..`, no backslash
+ * or control character), so nothing lands outside the directory.
+ */
+export const UNPACK_JS = [
+    'const fs=require("fs"),p=require("path"),z=require("zlib");',
+    "const dir=process.argv[1];",
+    'let b="";',
+    'for(const l of fs.readFileSync(0,"utf8").split("\\n")){if(!l.trim())continue;let s="";try{s=JSON.parse(l)}catch{}if(typeof s==="string")b+=s}',
+    'if(!b){console.log("chant: the plan job handed on no report");process.exit(0)}',
+    'let files;try{files=JSON.parse(z.gunzipSync(Buffer.from(b,"base64"),{maxOutputLength:268435456}).toString("utf8"))}catch(e){console.log("chant: the report the plan job handed on does not read: "+e.message);process.exit(0)}',
+    'if(!files||typeof files!=="object"||Array.isArray(files)){console.log("chant: the report the plan job handed on is not a set of files");process.exit(0)}',
+    "let n=0;",
+    'for(const [k,v] of Object.entries(files)){const parts=k.split("/");',
+    'if(typeof v!=="string"||k.length>1024||parts.some((x)=>!x||x==="."||x===".."||/[\\\\\\x00-\\x1f]/.test(x))){console.log("chant: left out "+JSON.stringify(k));continue}',
+    'try{const f=p.join(dir,...parts);fs.mkdirSync(p.dirname(f),{recursive:true});fs.writeFileSync(f,Buffer.from(v,"base64"));n++}catch(e){console.log("chant: could not write "+JSON.stringify(k)+": "+e.message)}}',
+    'console.log("chant: took "+n+" report files from the plan job")',
+].join("");
+/**
+ * The lines of the plan step, after {@link dropForgeTokens}: when the step
+ * ends, however it ends, its report directory (`dir`, from the directory the
+ * step starts in) goes into the step's outputs.
+ */
+export function handoverTrap(dir, forge) {
+    return [
+        `chant_report="$PWD/${dir}"`,
+        `chant_handover() { node -e '${packJs(forge)}' "$chant_report" "\${GITHUB_OUTPUT:-/dev/null}" || echo "chant: the plan report could not be handed to the note job" >&2; }`,
+        "trap chant_handover EXIT",
+    ];
+}
+/** A job's outputs that carry the report its step `step` handed on. */
+export function handoverOutputs(step, forge) {
+    return Object.fromEntries(handoverKeys(forge).map((k) => [k, `\${{ steps.${step}.outputs.${k} }}`]));
+}
+/**
+ * The script of the step that takes the report job `job` handed on into
+ * `dir`. Each output comes in as toJSON's string, one line of a quoted
+ * heredoc whose end no JSON string can be, so the change's outputs stay data.
+ */
+export function takeOverScript(job, dir, forge) {
+    return [
+        "set -u",
+        `node -e '${UNPACK_JS}' ${dir} <<'END_OF_REPORT'`,
+        ...handoverKeys(forge).map((k) => `\${{ toJSON(needs.${job}.outputs.${k}) }}`),
+        "END_OF_REPORT",
+    ].join("\n");
+}
+/** The variable the checkout script reads the job's token from. */
+export const CHECKOUT_TOKEN_ENV = "CHANT_CHECKOUT_TOKEN";
+/**
+ * Checks the run's commit out with git, as actions/checkout does without
+ * credentials kept: `GITHUB_SHA` under `GITHUB_REF`. With `history`, every
+ * branch and tag too, since the plan measures the change with git. The job's
+ * token ({@link CHECKOUT_TOKEN_ENV}) reaches the fetches alone, through the
+ * environment, never the git config. A workspace already checked out is
+ * cleaned first, as actions/checkout does. terragucci's `checkoutScript`
+ * (handover.ts). With `ledger`, the `chant/lifecycle` branch is fetched
+ * into a local branch too, while the token is there: the plan reads the
+ * gate ledger from it, and a later fetch without the token cannot reach a
+ * private repository (`requireLifecycleLedger` in ./lifecycle/git.ts reads
+ * the local branch when the fetch fails).
+ */
+export function checkoutScript(history, ledger = false) {
+    const fetchLine = history
+        ? `git -c protocol.version=2 fetch -q --prune --no-recurse-submodules origin '+refs/heads/*:refs/remotes/origin/*' '+refs/tags/*:refs/tags/*' "+$want:$target"`
+        : 'git -c protocol.version=2 fetch -q --no-tags --prune --no-recurse-submodules --depth=1 origin "+$want:$target"';
+    return [
+        "set -eu",
+        'git config --global --add safe.directory "$PWD" 2>/dev/null || true',
+        "[ -d .git ] || git init -q .",
+        'git remote get-url origin >/dev/null 2>&1 || git remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY"',
+        `if [ -n "\${${CHECKOUT_TOKEN_ENV}:-}" ]; then`,
+        `  chant_auth="$(printf 'x-access-token:%s' "$${CHECKOUT_TOKEN_ENV}" | base64 | tr -d '\\n')"`,
+        '  export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraheader GIT_CONFIG_VALUE_0="AUTHORIZATION: basic $chant_auth"',
+        "  unset chant_auth",
+        "fi",
+        'ref="$GITHUB_REF"',
+        'want="$GITHUB_SHA"',
+        'case "$ref" in',
+        '  refs/heads/*) target="refs/remotes/origin/${ref#refs/heads/}" ;;',
+        '  refs/tags/*) target="$ref" ;;',
+        '  refs/*) target="refs/remotes/${ref#refs/}" ;;',
+        '  *) target="refs/remotes/origin/chant-head" ;;',
+        "esac",
+        "if git rev-parse -q --verify HEAD >/dev/null; then git clean -ffdxq; fi",
+        fetchLine,
+        ...(ledger ? ["git -c protocol.version=2 fetch -q --no-tags origin '+refs/heads/chant/lifecycle:refs/heads/chant/lifecycle' 2>/dev/null || true"] : []),
+        'case "$ref" in',
+        '  refs/heads/*) git checkout -q --force -B "${ref#refs/heads/}" "$target" ;;',
+        '  *) git checkout -q --force --detach "$target" ;;',
+        "esac",
+    ].join("\n");
+}