@intentius/chant-lexicon-github 0.124.40 → 0.124.41

package/src/components/generate-pr-env-pipeline.test.ts

@@ -0,0 +1,206 @@
+/**
+ * A pull request's environment in the generated GitHub workflow (#4298):
+ * `env-up` on an opened, updated or reopened pull request, `env-post` after
+ * it, `env-down` when it closes, `env-sweep` on the schedule, and a plan job
+ * that skips the close.
+ *
+ * `env-up` runs the pull request's code, so it follows the handover (#4295):
+ * only its checkout sees the job's token, every later step starts without
+ * the token variables, and the `pr-env up` step is last and hands its report
+ * and record on. The behaviour test runs the generated steps with `sh`, as a
+ * forge runs them, with every token variable set.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { dropForgeTokens, FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import { PR_ENV_SWEEP_CRON } from "@intentius/chant/components/pr-pipeline";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "kubectl-apply", manifest: "app.yaml" } as never] }] }];
+
+interface Step {
+  name?: string;
+  id?: string;
+  if?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  with?: Record<string, unknown>;
+}
+interface Job {
+  if: string;
+  needs?: string[];
+  permissions: Record<string, string>;
+  outputs?: Record<string, string>;
+  concurrency: { group: string; "cancel-in-progress": boolean };
+  steps: Step[];
+}
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const SECRET = "ghs_generated_env_secret_4298";
+const TOKENS = Object.fromEntries(FORGE_TOKEN_VARS.map((v) => [v, `${SECRET}_${v}`]));
+const BASE = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp" };
+const UP_LINE = /^chant components pr-env up .*$/m;
+
+function hasActionlint(): boolean {
+  try {
+    execFileSync("actionlint", ["-version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function workflow(): { yaml: string; jobs: string[]; doc: { on: Record<string, unknown>; jobs: Record<string, Job> } } {
+  const result = generateGithubPipeline(ESTATE, { env: "staging", image: "example/ci:1", beforeScript: ["npm ci"], extraScript: ["echo after"], prLoop: { prEnvironment: true, build: true } });
+  return { yaml: result.yaml, jobs: result.jobs.map((j) => j.jobName), doc: parseYAML(result.yaml) as { on: Record<string, unknown>; jobs: Record<string, Job> } };
+}
+
+describe("the GitHub pull-request workflow with a pull request environment", () => {
+  const { yaml, jobs, doc } = workflow();
+
+  test("the pull_request trigger fires on close too, and a schedule starts the sweep", () => {
+    expect(doc.on.pull_request).toEqual({ branches: ["main"], types: ["opened", "synchronize", "reopened", "closed"] });
+    expect(doc.on.schedule).toEqual([{ cron: PR_ENV_SWEEP_CRON }]);
+    expect(doc.jobs.plan!.if).toBe("github.event_name == 'pull_request' && github.event.action != 'closed'");
+    expect(jobs).toEqual(expect.arrayContaining(["env-up", "env-post", "env-down", "env-sweep"]));
+  });
+
+  test("env-up plans pr-<n> with no forge and no push; env-down tears it down from the base branch", () => {
+    const up = doc.jobs["env-up"]!;
+    const down = doc.jobs["env-down"]!;
+    expect(up.if).toBe("github.event_name == 'pull_request' && github.event.action != 'closed'");
+    expect(down.if).toBe("github.event_name == 'pull_request' && github.event.action == 'closed'");
+    const last = up.steps.at(-1)!;
+    expect(last.run).toMatch(UP_LINE);
+    expect(last.run!.match(UP_LINE)![0]).toBe('chant components pr-env up --base "$BASE_SHA" --pr "$PR_NUMBER" --output .chant/pr-env --no-push');
+    expect(last.env?.CHANT_ENV).toBe("pr-${{ github.event.pull_request.number }}");
+    const downRun = down.steps.find((s) => s.run?.startsWith("chant components pr-env"))!;
+    expect(downRun.run).toBe('chant components pr-env down --pr "$PR_NUMBER" --reason closed --forge github --output .chant/pr-env');
+    expect(down.steps[0]!.with?.ref).toBe("${{ github.event.pull_request.base.ref }}");
+    expect(up.concurrency).toEqual({ group: "chant-pr-env-${{ github.event.pull_request.number }}", "cancel-in-progress": false });
+    expect(down.concurrency).toEqual(up.concurrency);
+    expect(doc.jobs["env-sweep"]!.if).toBe("github.event_name == 'schedule'");
+  });
+
+  test("without the option nothing changes", () => {
+    const plain = parseYAML(generateGithubPipeline(ESTATE, { env: "staging", prLoop: {} }).yaml) as { on: Record<string, unknown>; jobs: Record<string, Job> };
+    expect(plain.on.pull_request).toEqual({ branches: ["main"] });
+    expect(plain.jobs["env-up"]).toBeUndefined();
+  });
+
+  test.skipIf(!hasActionlint())("passes actionlint", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-actionlint-"));
+    dirs.push(dir);
+    mkdirSync(join(dir, ".github", "workflows"), { recursive: true });
+    writeFileSync(join(dir, ".github", "workflows", "chant-pr.yml"), yaml);
+    expect(() => execFileSync("actionlint", [".github/workflows/chant-pr.yml"], { cwd: dir, encoding: "utf8" })).not.toThrow();
+  });
+});
+
+describe("env-up holds no forge token while the pull request's code runs (#4295)", () => {
+  const { doc } = workflow();
+  const up = doc.jobs["env-up"]!;
+  const post = doc.jobs["env-post"]!;
+
+  test("only the checkout step is given the job's token, and only for its fetches", () => {
+    const [checkout, ...rest] = up.steps;
+    expect(checkout!.uses).toBeUndefined();
+    expect(checkout!.env).toEqual({ CHANT_CHECKOUT_TOKEN: "${{ github.token }}" });
+    for (const step of rest) {
+      expect(JSON.stringify(step)).not.toContain("github.token");
+      for (const name of FORGE_TOKEN_VARS) expect(step.env ?? {}).not.toHaveProperty(name);
+    }
+    expect(up.permissions).toEqual({ contents: "read" });
+  });
+
+  test("every step after the checkout starts by dropping the token variables, and none is an action", () => {
+    for (const step of up.steps.slice(1)) {
+      expect(step.uses).toBeUndefined();
+      expect(step.run!.split("\n")[0]).toBe(dropForgeTokens("sh"));
+    }
+  });
+
+  test("the pr-env up step is the job's last and hands its report on as the job's outputs", () => {
+    const last = up.steps.at(-1)!;
+    expect(last.id).toBe("env-up");
+    expect(last.run!.trimEnd().split("\n").at(-1)).toBe("echo after");
+    expect(up.outputs).toEqual({ report_0: "${{ steps.env-up.outputs.report_0 }}" });
+  });
+
+  test("env-post checks out the target branch's commit, and only it can write the record, the note and the status", () => {
+    expect(post.needs).toEqual(["env-up"]);
+    expect(post.if).toContain("needs.env-up.result == 'failure'");
+    expect(post.steps[0]).toMatchObject({ uses: expect.stringMatching(/^actions\/checkout@/), with: { ref: "${{ github.event.pull_request.base.sha }}" } });
+    expect(post.permissions).toEqual({ contents: "write", "pull-requests": "write", statuses: "write" });
+    const last = post.steps.at(-1)!;
+    expect(last.env).toMatchObject({ GITHUB_TOKEN: "${{ github.token }}", HEAD_SHA: "${{ github.sha }}", UP_RESULT: "${{ needs.env-up.result }}" });
+    expect(last.run).toBe('chant components pr-env post --pr "$PR_NUMBER" --head "$HEAD_SHA" --forge github --output .chant/pr-env --result "$UP_RESULT"');
+    // The post job runs no build, no lint and no pr-env up: none of the change's code.
+    expect(JSON.stringify(post)).not.toMatch(/chant (build|lint)|pr-env up/);
+  });
+});
+
+/** Run one generated step as a forge does: its script as a file, `sh -e`, with the job's tokens in the environment. */
+function runStep(step: Step, cwd: string, env: Record<string, string>): number | null {
+  const file = join(cwd, "..", `step-${Math.random().toString(36).slice(2)}.sh`);
+  writeFileSync(file, step.run!);
+  return spawnSync("sh", ["-e", file], { cwd, env: { ...BASE, ...TOKENS, ...env }, encoding: "utf-8" }).status;
+}
+
+describe("env-up's steps, run, see no forge token and hand the report and record on (#4295)", () => {
+  const { doc } = workflow();
+
+  test("each step after the checkout, and every process it starts, sees none of the token variables", () => {
+    const top = mkdtempSync(join(tmpdir(), "chant-generated-env-step-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(work);
+    const seen = join(top, "seen");
+    mkdirSync(seen);
+    const output = join(top, "github-output");
+    const steps = doc.jobs["env-up"]!.steps.slice(1);
+    steps.forEach((step, i) => {
+      const probe = `env > "${seen}/${i}.env"; sh -c 'env' >> "${seen}/${i}.env"`;
+      const report = "mkdir -p .chant/pr-env && echo '{\"stage\":\"up\"}' > .chant/pr-env/pr-env-up.json && echo '{\"kind\":\"up\"}' > .chant/pr-env/pr-env-record.json";
+      const lines = step.run!.split("\n");
+      const handover = lines.filter((l) => l.startsWith("chant_report=") || l.startsWith("chant_handover") || l.startsWith("trap "));
+      const body = [lines[0], ...handover, probe, ...(UP_LINE.test(step.run!) ? [report] : [])].join("\n");
+      expect(runStep({ run: body }, work, { GITHUB_OUTPUT: output, BASE_SHA: "b".repeat(40), PR_NUMBER: "7" }), step.name ?? lines[1]).toBe(0);
+    });
+    for (let i = 0; i < steps.length; i++) expect(readFileSync(join(seen, `${i}.env`), "utf-8")).not.toContain(SECRET);
+    expect(readFileSync(output, "utf-8")).toMatch(/^report_0=\S+$/m);
+  });
+
+  test("env-post's take-over step writes the report and the record back from that output", () => {
+    const top = mkdtempSync(join(tmpdir(), "chant-generated-env-post-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(join(work, ".chant", "pr-env"), { recursive: true });
+    writeFileSync(join(work, ".chant", "pr-env", "pr-env-up.json"), '{"stage":"up"}\n');
+    writeFileSync(join(work, ".chant", "pr-env", "pr-env-record.json"), '{"kind":"up"}\n');
+    const output = join(top, "github-output");
+    const upStep = doc.jobs["env-up"]!.steps.at(-1)!;
+    const handOn = upStep.run!.split("\n").filter((l, n) => n === 0 || l.startsWith("chant_report=") || l.startsWith("chant_handover") || l.startsWith("trap ")).join("\n");
+    expect(runStep({ run: handOn }, work, { GITHUB_OUTPUT: output })).toBe(0);
+    const value = readFileSync(output, "utf-8").trim().slice("report_0=".length);
+
+    const postWork = join(top, "post");
+    mkdirSync(postWork);
+    const take = doc.jobs["env-post"]!.steps.find((s) => s.name === "Take the environment's report from the env-up job")!;
+    const filled = take.run!.replace("${{ toJSON(needs.env-up.outputs.report_0) }}", JSON.stringify(value));
+    expect(runStep({ run: filled }, postWork, {})).toBe(0);
+    expect(existsSync(join(postWork, ".chant", "pr-env", "pr-env-record.json"))).toBe(true);
+    expect(readFileSync(join(postWork, ".chant", "pr-env", "pr-env-up.json"), "utf-8")).toBe('{"stage":"up"}\n');
+  });
+});

package/src/components/generate-pr-pipeline.handover.test.ts

@@ -0,0 +1,167 @@
+/**
+ * #4295: in the generated pull-request workflow, no step that runs the pull
+ * request's code holds a forge token. The plan job uses the job's token for
+ * its checkout's fetches alone, every later step starts without the token
+ * variables, and the plan step is the job's last and hands its report on as
+ * the job's outputs. The plan-note job, which runs none of the change's
+ * code, posts.
+ *
+ * The behaviour tests run the generated steps with `sh`, as a forge runs
+ * them, with every token variable set, and `chant ci run plan` replaced by a
+ * line that prints what the step can see.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { dropForgeTokens, FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+  { name: "app", dependsOn: ["net"], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "app" }] }] },
+];
+
+interface Step {
+  name?: string;
+  id?: string;
+  if?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  with?: Record<string, unknown>;
+}
+interface Job {
+  needs?: string[];
+  if?: string;
+  permissions?: Record<string, string>;
+  outputs?: Record<string, string>;
+  steps: Step[];
+}
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const SECRET = "ghs_generated_job_secret_4295";
+const TOKENS = Object.fromEntries(FORGE_TOKEN_VARS.map((v) => [v, `${SECRET}_${v}`]));
+const BASE = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp" };
+const PLAN_LINE = /^chant ci run plan .*$/m;
+
+/** The pipeline with a build, a before-script line and an after-script line, so every kind of step is there. */
+function workflow(extra: Record<string, unknown> = {}): { jobs: Record<string, Job> } {
+  const { yaml } = generateGithubPipeline(ESTATE, { env: "prod", image: "example/ci:1", beforeScript: ["npm ci"], extraScript: ["echo after"], prLoop: { build: true, ...extra } });
+  return parseYAML(yaml) as { jobs: Record<string, Job> };
+}
+
+describe("the generated plan job holds no forge token while the change's code runs (#4295)", () => {
+  const doc = workflow();
+  const plan = doc.jobs.plan!;
+  const note = doc.jobs["plan-note"]!;
+
+  test("only the checkout step is given the job's token, and only for its fetches", () => {
+    const [checkout, ...rest] = plan.steps;
+    expect(checkout!.uses).toBeUndefined();
+    expect(checkout!.env).toEqual({ CHANT_CHECKOUT_TOKEN: "${{ github.token }}" });
+    for (const step of rest) {
+      expect(JSON.stringify(step)).not.toContain("github.token");
+      for (const name of FORGE_TOKEN_VARS) expect(step.env ?? {}).not.toHaveProperty(name);
+    }
+    // The token itself can read the repository and nothing else.
+    expect(plan.permissions).toEqual({ contents: "read" });
+  });
+
+  test("every step after the checkout starts by dropping the token variables, and none is an action", () => {
+    for (const step of plan.steps.slice(1)) {
+      expect(step.uses).toBeUndefined();
+      expect(step.run!.split("\n")[0]).toBe(dropForgeTokens("sh"));
+    }
+  });
+
+  test("the plan step is the job's last: no upload, cache or checkout post step runs after the change's code", () => {
+    const last = plan.steps.at(-1)!;
+    expect(last.id).toBe("plan");
+    expect(last.run).toMatch(PLAN_LINE);
+    // The after-script lines run inside it, not as steps of their own.
+    expect(last.run!.trimEnd().split("\n").at(-1)).toBe("echo after");
+    expect(plan.outputs).toEqual({ report_0: "${{ steps.plan.outputs.report_0 }}" });
+  });
+
+  test("the plan-note job checks out the target branch's commit, and only it can write the note and the status", () => {
+    expect(note.needs).toEqual(["plan"]);
+    expect(note.if).toContain("needs.plan.result == 'failure'");
+    expect(note.steps[0]).toMatchObject({ uses: expect.stringMatching(/^actions\/checkout@/), with: { ref: "${{ github.event.pull_request.base.sha }}" } });
+    expect(note.permissions).toEqual({ actions: "read", contents: "read", "pull-requests": "write", statuses: "write" });
+    const post = note.steps.at(-1)!;
+    expect(post.env).toMatchObject({ GITHUB_TOKEN: "${{ github.token }}", HEAD_SHA: "${{ github.sha }}", PLAN_RESULT: "${{ needs.plan.result }}" });
+    expect(post.run).toBe('chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge github --result "$PLAN_RESULT"');
+    // The note job runs no build, no lint and no plan: none of the change's code.
+    expect(JSON.stringify(note)).not.toMatch(/chant (build|lint|ci run)/);
+  });
+});
+
+/** Run one generated step as a forge does: its script as a file, `sh -e`, with the job's tokens in the environment. */
+function runStep(step: Step, cwd: string, env: Record<string, string>): number | null {
+  const file = join(cwd, "..", `step-${Math.random().toString(36).slice(2)}.sh`);
+  writeFileSync(file, step.run!);
+  return spawnSync("sh", ["-e", file], { cwd, env: { ...BASE, ...TOKENS, ...env }, encoding: "utf-8" }).status;
+}
+
+describe("the generated steps, run, see no forge token and hand the report on (#4295)", () => {
+  const doc = workflow();
+
+  test("each step after the checkout, and every process it starts, sees none of the token variables", () => {
+    const top = mkdtempSync(join(tmpdir(), "chant-generated-step-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(work);
+    const seen = join(top, "seen");
+    mkdirSync(seen);
+    const output = join(top, "github-output");
+    const steps = doc.jobs.plan!.steps.slice(1);
+    steps.forEach((step, i) => {
+      // The step's own lines become a probe; the plan line also writes a report, as pr-plan would.
+      const probe = `env > "${seen}/${i}.env"; sh -c 'env' >> "${seen}/${i}.env"`;
+      const report = 'mkdir -p .chant/pr && echo \'{"stage":"plan"}\' > .chant/pr/pr-plan.json && echo note > .chant/pr/pr-note.md';
+      // The generated drop line and hand-on lines run as they are; the step's own commands become the probe.
+      const lines = step.run!.split("\n");
+      const handover = lines.filter((l) => l.startsWith("chant_report=") || l.startsWith("chant_handover") || l.startsWith("trap "));
+      const body = [lines[0], ...handover, probe, ...(PLAN_LINE.test(step.run!) ? [report] : [])].join("\n");
+      const status = runStep({ run: body }, work, { GITHUB_OUTPUT: output, BASE_SHA: "b".repeat(40), PR_NUMBER: "7" });
+      expect(status, step.name ?? step.run!.split("\n")[1]).toBe(0);
+    });
+    for (let i = 0; i < steps.length; i++) {
+      const env = readFileSync(join(seen, `${i}.env`), "utf-8");
+      expect(env).not.toContain(SECRET);
+    }
+    // The plan step handed its report on as the job's output.
+    expect(readFileSync(output, "utf-8")).toMatch(/^report_0=\S+$/m);
+  });
+
+  test("the note job's take-over step writes the plan step's report back from that output", () => {
+    const top = mkdtempSync(join(tmpdir(), "chant-generated-note-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(join(work, ".chant", "pr"), { recursive: true });
+    writeFileSync(join(work, ".chant", "pr", "pr-plan.json"), '{"stage":"plan"}\n');
+    const output = join(top, "github-output");
+    const planStep = doc.jobs.plan!.steps.at(-1)!;
+    const handOn = planStep.run!.split("\n").filter((l, n) => n === 0 || l.startsWith("chant_report=") || l.startsWith("chant_handover") || l.startsWith("trap ")).join("\n");
+    expect(runStep({ run: handOn }, work, { GITHUB_OUTPUT: output })).toBe(0);
+    const value = readFileSync(output, "utf-8").trim().slice("report_0=".length);
+
+    const noteWork = join(top, "note");
+    mkdirSync(noteWork);
+    const take = doc.jobs["plan-note"]!.steps.find((s) => s.name === "Take the plan report from the plan job")!;
+    // The forge fills the expression with toJSON of the output: a JSON string on one line.
+    const filled = take.run!.replace("${{ toJSON(needs.plan.outputs.report_0) }}", JSON.stringify(value));
+    expect(runStep({ run: filled }, noteWork, {})).toBe(0);
+    expect(existsSync(join(noteWork, ".chant", "pr", "pr-plan.json"))).toBe(true);
+    expect(readFileSync(join(noteWork, ".chant", "pr", "pr-plan.json"), "utf-8")).toBe('{"stage":"plan"}\n');
+  });
+});

package/src/components/generate-pr-pipeline.identity.test.ts

@@ -0,0 +1,219 @@
+/**
+ * #4296: the pull-request workflow's plan job trades its OIDC token for the
+ * plan identity before the change is checked out, and the change's code
+ * never holds a token, a way to request one, or the apply identity.
+ *
+ * The behaviour tests run the generated steps with `sh`, as a forge runner
+ * does: the trade step against a local emulator of the token URL and the
+ * clouds (@intentius/chant/__fixtures__/oidc-emulator), then each later
+ * step with the runner's token request variables still set and what the
+ * trade left in GITHUB_ENV, its own commands replaced by a probe that
+ * prints what it sees and tries to request a token. Test values only.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { dropForgeTokens, FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import { OIDC_REQUEST_VARS, resolveCloudIdentity, TRADE_SPEC_ENV, tradeIdentities, type PipelineCloudIdentity } from "@intentius/chant/ci-identity";
+import { emulatedCredentials, EMULATED_JWT_PREFIX, EMULATED_REQUEST_TOKEN, startOidcEmulator, type OidcEmulator } from "@intentius/chant/__fixtures__/oidc-emulator";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const run = promisify(execFile);
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+  { name: "app", dependsOn: ["net"], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "app" }] }] },
+];
+
+const PLAN_ROLE = "arn:aws:iam::111111111111:role/prod-plan";
+const APPLY_ROLE = "arn:aws:iam::111111111111:role/prod-apply";
+const IDENTITY = resolveCloudIdentity(
+  {
+    aws: { rules: [{ environments: ["prod"], plan: PLAN_ROLE, apply: APPLY_ROLE }] },
+    gcp: { provider: "projects/123/locations/global/workloadIdentityPools/ci/providers/forge", rules: [{ plan: "plan@test.iam.gserviceaccount.com", apply: "apply@test.iam.gserviceaccount.com" }] },
+    azure: { tenantId: "test-tenant", rules: [{ plan: "plan-client", apply: "apply-client" }] },
+  },
+  "prod",
+)!;
+const APPLY_IDENTITIES = tradeIdentities(IDENTITY.apply);
+
+interface Step {
+  name?: string;
+  id?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  "working-directory"?: string;
+}
+interface Job {
+  permissions?: Record<string, string>;
+  steps: Step[];
+}
+
+function workflow(identity: PipelineCloudIdentity | undefined, extra: Record<string, unknown> = {}): { jobs: Record<string, Job> } {
+  const { yaml } = generateGithubPipeline(ESTATE, {
+    env: "prod",
+    image: "example/ci:1",
+    beforeScript: ["npm ci"],
+    extraScript: ["echo after"],
+    prLoop: { build: true, applyOnMerge: true, ...(identity ? { identity } : {}), ...extra },
+  });
+  return parseYAML(yaml) as { jobs: Record<string, Job> };
+}
+
+const TRADE_NAME = /^Trade the job's OIDC token for the (plan|apply) identity$/;
+const tradeOf = (job: Job): Record<string, unknown> => JSON.parse(job.steps[0]!.env![TRADE_SPEC_ENV]!) as Record<string, unknown>;
+
+describe("the generated jobs' cloud identities (#4296)", () => {
+  const doc = workflow(IDENTITY);
+  const plan = doc.jobs.plan!;
+
+  test("the plan job's first step trades for the plan identity, before the checkout", () => {
+    expect(plan.steps[0]!.name).toMatch(TRADE_NAME);
+    expect(plan.steps[0]!.name).toContain("plan identity");
+    expect(plan.steps[0]!.uses).toBeUndefined();
+    expect(plan.steps[0]!.run).toMatch(/^\(cd \/ && node -e '/);
+    expect(plan.steps[1]!.name).toBe("Check out the change");
+    expect(tradeOf(plan)).toEqual(IDENTITY.plan);
+    expect(plan.permissions).toEqual({ contents: "read", "id-token": "write" });
+  });
+
+  test("the plan job names no apply identity anywhere", () => {
+    const text = JSON.stringify(plan);
+    for (const id of APPLY_IDENTITIES) expect(text).not.toContain(id);
+  });
+
+  test("every step after the checkout starts by dropping the forge tokens and the OIDC request variables", () => {
+    for (const step of plan.steps.slice(2)) expect(step.run!.split("\n")[0]).toBe(dropForgeTokens("sh", OIDC_REQUEST_VARS));
+  });
+
+  test("the record job trades for the plan identity and the apply job for the apply identity, each before its checkout", () => {
+    const record = doc.jobs.record!;
+    const apply = doc.jobs.apply!;
+    expect(record.steps[0]!.name).toContain("plan identity");
+    expect(tradeOf(record)).toEqual(IDENTITY.plan);
+    expect(apply.steps[0]!.name).toContain("apply identity");
+    expect(tradeOf(apply)).toEqual(IDENTITY.apply);
+    for (const job of [record, apply]) {
+      expect(job.steps[1]!.uses).toMatch(/^actions\/checkout@/);
+      expect(job.permissions!["id-token"]).toBe("write");
+    }
+    expect(JSON.stringify(record)).not.toContain(APPLY_ROLE);
+  });
+
+  test("with a gate per wave, every wave's apply job trades for the apply identity", () => {
+    const waves = workflow(IDENTITY, { waveGate: "prod" }).jobs;
+    const names = Object.keys(waves).filter((n) => n.startsWith("apply-wave-"));
+    expect(names.length).toBe(2);
+    for (const n of names) expect(tradeOf(waves[n]!)).toEqual(IDENTITY.apply);
+  });
+
+  test("the plan-note job requests no token and trades nothing", () => {
+    const note = doc.jobs["plan-note"]!;
+    expect(note.permissions!["id-token"]).toBeUndefined();
+    expect(JSON.stringify(note)).not.toContain(TRADE_SPEC_ENV);
+  });
+
+  test("without identity no job requests a token, and the plan job is as #4295 left it", () => {
+    const plain = workflow(undefined);
+    for (const job of Object.values(plain.jobs)) {
+      expect(job.permissions?.["id-token"]).toBeUndefined();
+      expect(job.steps.some((s) => TRADE_NAME.test(s.name ?? ""))).toBe(false);
+    }
+    expect(plain.jobs.plan!.steps[1]!.run!.split("\n")[0]).toBe(dropForgeTokens("sh"));
+  });
+});
+
+const dirs: string[] = [];
+let emu: OidcEmulator;
+beforeAll(async () => {
+  emu = await startOidcEmulator();
+});
+afterAll(async () => {
+  await emu.close();
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const BASE = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp" };
+const FORGE_SECRET = "ghs_identity_secret_4296";
+const TOKENS = Object.fromEntries(FORGE_TOKEN_VARS.map((v) => [v, `${FORGE_SECRET}_${v}`]));
+
+/** Run one step's script as a forge does: a file, `sh -e`. */
+async function runStep(script: string, cwd: string, env: Record<string, string>): Promise<{ code: number; stdout: string; stderr: string }> {
+  const file = join(cwd, "..", `step-${Math.random().toString(36).slice(2)}.sh`);
+  writeFileSync(file, script);
+  try {
+    const r = await run("sh", ["-e", file], { cwd, env: { ...BASE, ...env } });
+    return { code: 0, stdout: r.stdout, stderr: r.stderr };
+  } catch (e) {
+    const err = e as { code: number; stdout: string; stderr: string };
+    return { code: err.code, stdout: err.stdout, stderr: err.stderr };
+  }
+}
+
+/** GITHUB_ENV's `NAME=value` lines as the runner applies them to the job's later steps. */
+const githubEnv = (text: string): Record<string, string> =>
+  Object.fromEntries(text.split("\n").filter((l) => l.includes("=")).map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]));
+
+/** A probe: what the step's shell and a child see, and whether a request for an apply-audience token succeeds. */
+const PROBE = [
+  'env > "$SEEN"',
+  `sh -c 'env' >> "$SEEN"`,
+  `node -e 'const u=process.env.ACTIONS_ID_TOKEN_REQUEST_URL,k=process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;if(!u||!k){console.log("no-request-vars");process.exit(0)}fetch(u+"&audience=sts.amazonaws.com",{headers:{authorization:"bearer "+k}}).then(r=>r.text()).then(t=>console.log("minted:"+t))' >> "$SEEN"`,
+].join("\n");
+
+describe("the generated plan job, run: the change's code never holds a token or the apply identity (#4296)", () => {
+  test("the trade mints and trades for the plan identity alone; every later step sees plan credentials and nothing to request a token with", async () => {
+    const identity: PipelineCloudIdentity = { plan: emu.pointAt(IDENTITY.plan), apply: emu.pointAt(IDENTITY.apply) };
+    const plan = workflow(identity).jobs.plan!;
+    const top = mkdtempSync(join(tmpdir(), "chant-identity-job-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(work);
+    const envFile = join(top, "github-env");
+    writeFileSync(envFile, "");
+    // The runner gives every step of a job with id-token: write the request variables, and the forge tokens.
+    const runner = { ...emu.requestEnv, ...TOKENS, GITHUB_ENV: envFile };
+    const before = { minted: emu.log.minted.length, assumed: emu.log.assumed.length, impersonated: emu.log.impersonated.length, clients: emu.log.clients.length };
+
+    const trade = plan.steps[0]!;
+    const traded = await runStep(trade.run!, work, { ...runner, ...trade.env });
+    expect(traded.stderr).not.toContain("failed");
+    expect(traded.code).toBe(0);
+    expect(emu.log.minted.length - before.minted).toBe(3);
+    expect(emu.log.assumed.slice(before.assumed).map((a) => a.role)).toEqual([PLAN_ROLE]);
+    expect(emu.log.impersonated.slice(before.impersonated)).toEqual(["plan@test.iam.gserviceaccount.com"]);
+    expect(emu.log.clients.slice(before.clients).map((c) => c.clientId)).toEqual(["plan-client"]);
+    const left = githubEnv(readFileSync(envFile, "utf-8"));
+    expect(left.AWS_ACCESS_KEY_ID).toBe(emulatedCredentials(PLAN_ROLE).accessKeyId);
+
+    const later = plan.steps.slice(2);
+    expect(later.length).toBeGreaterThan(2);
+    const mintedAfterTrade = emu.log.minted.length;
+    for (const [i, step] of later.entries()) {
+      const seen = join(top, `seen-${i}`);
+      const lines = step.run!.split("\n");
+      const r = await runStep([lines[0], PROBE].join("\n"), work, { ...runner, ...left, ...(step.env ?? {}), SEEN: seen });
+      expect(r.code, step.name ?? lines[1]).toBe(0);
+      const text = readFileSync(seen, "utf-8");
+      expect(text).toContain(`AWS_ACCESS_KEY_ID=${emulatedCredentials(PLAN_ROLE).accessKeyId}`);
+      expect(text).toContain("no-request-vars");
+      expect(text).not.toContain("minted:");
+      expect(text).not.toContain(EMULATED_JWT_PREFIX);
+      expect(text).not.toContain(EMULATED_REQUEST_TOKEN);
+      expect(text).not.toContain(FORGE_SECRET);
+      for (const id of APPLY_IDENTITIES) expect(text).not.toContain(id);
+      expect(text).not.toContain(emulatedCredentials(APPLY_ROLE).accessKeyId);
+      for (const v of OIDC_REQUEST_VARS) expect(text).not.toMatch(new RegExp(`^${v}=`, "m"));
+    }
+    // No step after the trade minted a token.
+    expect(emu.log.minted.length).toBe(mintedAfterTrade);
+    expect(emu.log.assumed.some((a) => a.role === APPLY_ROLE)).toBe(false);
+  });
+});