@intentius/chant 0.124.40 → 0.124.42

package/src/ci-identity.test.ts

@@ -0,0 +1,201 @@
+/**
+ * #4296: the plan and apply cloud identities, and the OIDC trade. The trade
+ * tests run the generated `node -e` line with `sh`, as a forge step runs
+ * it, against a local emulator of the forge's token URL, AWS STS, Google's
+ * STS and IAM credentials, and Entra (./__fixtures__/oidc-emulator.ts).
+ * Test values only; no cloud is reached.
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, 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 {
+  cloudIdentityProblems,
+  gitlabTradeIdTokens,
+  gitlabTradeLines,
+  idTokenVar,
+  OIDC_REQUEST_VARS,
+  resolveCloudIdentity,
+  TRADE_JS,
+  TRADE_SPEC_ENV,
+  tradeLine,
+  type CloudIdentityDeclaration,
+  type CloudTradeSpec,
+} from "./ci-identity";
+import { emulatedCredentials, EMULATED_JWT_PREFIX, startOidcEmulator, type OidcEmulator } from "./__fixtures__/oidc-emulator";
+import { dropForgeTokens } from "./ci-handover";
+
+const run = promisify(execFile);
+
+const DECL: CloudIdentityDeclaration = {
+  aws: {
+    region: "eu-west-1",
+    rules: [
+      { environments: ["prod"], members: ["net"], plan: "arn:aws:iam::111111111111:role/net-prod-plan", apply: "arn:aws:iam::111111111111:role/net-prod-apply" },
+      { environments: ["prod"], plan: "arn:aws:iam::111111111111:role/prod-plan", apply: "arn:aws:iam::111111111111:role/prod-apply" },
+      { environments: ["staging-*"], plan: "arn:aws:iam::222222222222:role/staging-plan", apply: "arn:aws:iam::222222222222:role/staging-apply" },
+    ],
+  },
+  gcp: {
+    provider: "projects/123/locations/global/workloadIdentityPools/ci/providers/forge",
+    rules: [{ plan: "plan@test-project.iam.gserviceaccount.com", apply: "apply@test-project.iam.gserviceaccount.com" }],
+  },
+  azure: { tenantId: "00000000-0000-0000-0000-00000000tena", rules: [{ members: ["app"], plan: "plan-client-id", apply: "apply-client-id" }] },
+};
+
+describe("which identities a pipeline takes (#4296)", () => {
+  test("the first rule whose environments and members match wins, per cloud", () => {
+    const net = resolveCloudIdentity(DECL, "prod", "net")!;
+    expect(net.plan.aws!.role).toBe("arn:aws:iam::111111111111:role/net-prod-plan");
+    expect(net.apply.aws!.role).toBe("arn:aws:iam::111111111111:role/net-prod-apply");
+    expect(resolveCloudIdentity(DECL, "prod", "web")!.plan.aws!.role).toBe("arn:aws:iam::111111111111:role/prod-plan");
+    expect(resolveCloudIdentity(DECL, "staging-eu", "net")!.apply.aws!.role).toBe("arn:aws:iam::222222222222:role/staging-apply");
+    expect(net.plan.aws).toMatchObject({ region: "eu-west-1", audience: "sts.amazonaws.com" });
+  });
+
+  test("a cloud no rule covers is left out, and so is a pipeline no rule covers", () => {
+    expect(resolveCloudIdentity(DECL, "prod", "net")!.plan.azure).toBeUndefined();
+    expect(resolveCloudIdentity(DECL, "prod", "app")!.plan.azure).toMatchObject({ clientId: "plan-client-id", audience: "api://AzureADTokenExchange" });
+    expect(resolveCloudIdentity({ aws: DECL.aws }, "dev", "net")).toBeUndefined();
+    expect(resolveCloudIdentity(undefined, "prod")).toBeUndefined();
+  });
+
+  test("a rule with members never matches a pipeline outside a member", () => {
+    expect(resolveCloudIdentity(DECL, "prod")!.plan.aws!.role).toBe("arn:aws:iam::111111111111:role/prod-plan");
+  });
+
+  test("GCP's default audience names the provider", () => {
+    expect(resolveCloudIdentity(DECL, "prod")!.plan.gcp!.audience).toBe("https://iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/ci/providers/forge");
+  });
+
+  test("a rule may not plan as an identity it or another rule applies as", () => {
+    expect(cloudIdentityProblems(DECL)).toEqual([]);
+    const same = cloudIdentityProblems({ aws: { rules: [{ plan: "r", apply: "r" }] } });
+    expect(same).toEqual([{ pointer: "/ci/identity/cloud/aws/rules/0", message: expect.stringContaining("plans and applies as r") }]);
+    const crossed = cloudIdentityProblems({ gcp: { provider: "p", rules: [{ plan: "a", apply: "b" }, { plan: "b", apply: "c" }] } });
+    expect(crossed).toEqual([{ pointer: "/ci/identity/cloud/gcp/rules/1", message: expect.stringContaining("plans as b, which another rule applies as") }]);
+  });
+});
+
+describe("the trade script stays inside one shell word", () => {
+  test("it holds no single quote, so tradeLine can quote it", () => {
+    expect(TRADE_JS).not.toContain("'");
+  });
+  test("GitLab's lines trade, unset the token variables and the extra ones, then source the credentials", () => {
+    const [trade, unset, source] = gitlabTradeLines(["CHANT_FORGE_TOKEN"]);
+    expect(trade).toContain("node -e");
+    expect(unset).toBe(`unset CHANT_FORGE_TOKEN ${OIDC_REQUEST_VARS.join(" ")}`);
+    expect(source).toMatch(/^\. "\$\{TMPDIR:-\/tmp\}\/chant-cloud-\$CI_JOB_ID\.sh" && rm -f /);
+    expect(gitlabTradeIdTokens(resolveCloudIdentity(DECL, "prod", "app")!.plan)).toEqual({
+      CHANT_ID_TOKEN_AWS: { aud: "sts.amazonaws.com" },
+      CHANT_ID_TOKEN_GCP: { aud: "https://iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/ci/providers/forge" },
+      CHANT_ID_TOKEN_AZURE: { aud: "api://AzureADTokenExchange" },
+    });
+  });
+});
+
+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" };
+
+/** Run the trade line as a step does, with `spec` pointed at the emulator. */
+async function trade(spec: CloudTradeSpec, format: "github-env" | "sh", env: Record<string, string> = emu.requestEnv): Promise<{ out: string; stdout: string; stderr: string; code: number; file: string }> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-trade-"));
+  dirs.push(dir);
+  const file = join(dir, format === "sh" ? "cloud.sh" : "github-env");
+  if (format === "github-env") writeFileSync(file, "EARLIER=1\n");
+  try {
+    const r = await run("sh", ["-c", tradeLine(file, format)], { env: { ...BASE, ...env, [TRADE_SPEC_ENV]: JSON.stringify(emu.pointAt(spec)) } });
+    return { out: existsSync(file) ? readFileSync(file, "utf-8") : "", stdout: r.stdout, stderr: r.stderr, code: 0, file };
+  } catch (e) {
+    const err = e as { stdout: string; stderr: string; code: number };
+    return { out: existsSync(file) ? readFileSync(file, "utf-8") : "", stdout: err.stdout, stderr: err.stderr, code: err.code, file };
+  }
+}
+
+describe("the trade, run against the emulator (#4296)", () => {
+  const prodApp = () => resolveCloudIdentity(DECL, "prod", "app")!;
+
+  test("it trades one minted token per cloud for the plan identity alone, and writes the credentials to GITHUB_ENV", async () => {
+    const before = { minted: emu.log.minted.length, assumed: emu.log.assumed.length };
+    const r = await trade(prodApp().plan, "github-env");
+    expect(r.stderr).not.toContain("failed");
+    expect(r.code).toBe(0);
+    const aws = emulatedCredentials("arn:aws:iam::111111111111:role/prod-plan");
+    expect(r.out).toContain("EARLIER=1\n");
+    expect(r.out).toContain(`AWS_ACCESS_KEY_ID=${aws.accessKeyId}\n`);
+    expect(r.out).toContain(`AWS_SESSION_TOKEN=${aws.token}\n`);
+    expect(r.out).toContain("AWS_REGION=eu-west-1\n");
+    expect(r.out).toMatch(/^GOOGLE_OAUTH_ACCESS_TOKEN=ya29\.session-/m);
+    expect(r.out).toMatch(/^AZURE_ACCESS_TOKEN=azure\.session-/m);
+    expect(r.out).toContain("AZURE_CLIENT_ID=plan-client-id\n");
+    // The minted token itself is in no line the later steps get, and no apply identity was asked for.
+    expect(r.out).not.toContain(EMULATED_JWT_PREFIX);
+    expect(r.stdout + r.stderr).not.toContain(EMULATED_JWT_PREFIX);
+    expect(emu.log.minted.slice(before.minted)).toEqual(["sts.amazonaws.com", "https://iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/ci/providers/forge", "api://AzureADTokenExchange"]);
+    expect(emu.log.assumed.slice(before.assumed).map((a) => a.role)).toEqual(["arn:aws:iam::111111111111:role/prod-plan"]);
+    expect(emu.log.impersonated.at(-1)).toBe("plan@test-project.iam.gserviceaccount.com");
+    expect(emu.log.clients.at(-1)!.clientId).toBe("plan-client-id");
+    // GitHub masks each secret in every later step's log.
+    expect(r.stdout).toContain(`::add-mask::${aws.secret}`);
+    expect(r.stdout).toContain(`::add-mask::${aws.token}`);
+  });
+
+  test("the sh format writes export lines a GitLab script sources, mode 0600", async () => {
+    const r = await trade({ aws: prodApp().apply.aws }, "sh");
+    expect(r.code).toBe(0);
+    expect(statSync(r.file).mode & 0o777).toBe(0o600);
+    const probe = await run("sh", ["-c", `. "${r.file}"; echo "$AWS_ACCESS_KEY_ID"`], { env: BASE });
+    expect(probe.stdout.trim()).toBe(emulatedCredentials("arn:aws:iam::111111111111:role/prod-apply").accessKeyId);
+  });
+
+  test("on GitLab the token comes from the job's id_tokens variable, and no request URL is needed", async () => {
+    const before = emu.log.minted.length;
+    const jwt = `${EMULATED_JWT_PREFIX}.gitlab.1`;
+    const r = await trade({ aws: prodApp().plan.aws }, "sh", { [idTokenVar("aws")]: jwt });
+    expect(r.code).toBe(0);
+    expect(emu.log.minted.length).toBe(before);
+    expect(emu.log.assumed.at(-1)).toEqual({ role: "arn:aws:iam::111111111111:role/prod-plan", token: jwt });
+    expect(r.out).not.toContain(jwt);
+  });
+
+  test("a job that can request no token fails the step and writes nothing", async () => {
+    const r = await trade({ aws: prodApp().plan.aws }, "sh", {});
+    expect(r.code).not.toBe(0);
+    expect(r.stderr).toContain("the job can request no OIDC token for aws");
+    expect(r.out).toBe("");
+  });
+
+  test("an answer that would add a line of its own to GITHUB_ENV is refused", async () => {
+    const r = await trade({ aws: { ...prodApp().plan.aws!, region: "eu-west-1\nNODE_OPTIONS=--require=/tmp/x" } }, "github-env");
+    expect(r.code).not.toBe(0);
+    expect(r.out).toBe("EARLIER=1\n");
+  });
+});
+
+describe("after the trade, a step that runs the change's code cannot request a token (#4296)", () => {
+  test("the drop line with the OIDC request variables leaves none of them, and a request from the step fails", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-trade-drop-"));
+    dirs.push(dir);
+    const file = join(dir, "step.sh");
+    const ask = `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))'`;
+    writeFileSync(file, `${dropForgeTokens("sh", OIDC_REQUEST_VARS)}\nenv\n${ask}\n`);
+    const before = emu.log.minted.length;
+    const r = await run("sh", ["-e", file], { cwd: dir, env: { ...BASE, ...emu.requestEnv, [idTokenVar("aws")]: `${EMULATED_JWT_PREFIX}.x.y`, [TRADE_SPEC_ENV]: "{}" } });
+    expect(r.stdout).toContain("no-request-vars");
+    expect(r.stdout).not.toContain(EMULATED_JWT_PREFIX);
+    for (const v of OIDC_REQUEST_VARS) expect(r.stdout).not.toMatch(new RegExp(`^${v}=`, "m"));
+    expect(emu.log.minted.length).toBe(before);
+  });
+});

package/src/ci-identity.ts

@@ -0,0 +1,310 @@
+/**
+ * Plan and apply cloud identities (#4296): the pull-request jobs plan with
+ * one identity and apply with another, per cloud, and the plan job trades
+ * its OIDC token before the change's code is checked out.
+ *
+ * The workspace declaration's `ci.identity.cloud` gives each cloud a list of
+ * rules. A rule names environment globs and member globs, and a plan and an
+ * apply identity: an AWS role, a GCP service account or an Azure client id.
+ * The first rule whose globs match the pipeline's environment and member is
+ * the pipeline's ({@link resolveCloudIdentity}). A workspace generates one
+ * pull-request pipeline per member and environment, so each member's apply
+ * jobs hold that member's apply identity and no other.
+ *
+ * The plan job runs the pull request's code. Its first step, before the
+ * checkout, runs {@link tradeJs} with `node -e`: it asks the forge for an
+ * OIDC token, trades it for the plan identity's own credentials, and leaves
+ * those credentials for the later steps. Each later step then starts again
+ * without the variables a token is requested with ({@link OIDC_REQUEST_VARS},
+ * through `dropForgeTokens` in ./ci-handover.ts), so the change's code holds
+ * no OIDC token and cannot request one. The plan job's file names no apply
+ * identity. The record job plans the merged commit with the plan identity,
+ * and the apply jobs trade for the apply identity.
+ *
+ * The trade is terragucci's `oidc-trade.ts` (INTENTIUS/terragucci e6cb431,
+ * packages/terragucci/src/oidc-trade.ts) with these clients:
+ *
+ *   AWS    STS AssumeRoleWithWebIdentity, as session keys in
+ *          AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN
+ *   GCP    Google's STS token exchange, then IAM generateAccessToken for the
+ *          service account, in GOOGLE_OAUTH_ACCESS_TOKEN and
+ *          CLOUDSDK_AUTH_ACCESS_TOKEN
+ *   Azure  Entra's client credentials grant with the token as the client
+ *          assertion, as an ARM access token in AZURE_ACCESS_TOKEN, with
+ *          AZURE_CLIENT_ID and AZURE_TENANT_ID (and ARM_ spellings)
+ *
+ * terragucci leaves Azure untraded because the azurerm provider takes only
+ * the OIDC token. chant trades it, so the change's code never holds a token
+ * another client could be traded for; a tool that needs the OIDC token
+ * itself cannot plan under this block.
+ */
+
+// @ts-ignore: picomatch has no types declaration
+import picomatch from "picomatch";
+
+/** The clouds `ci.identity.cloud` names. */
+export const CLOUDS = ["aws", "gcp", "azure"] as const;
+export type Cloud = (typeof CLOUDS)[number];
+
+/** One rule: the environments and members it covers, and their two identities. */
+export interface CloudIdentityRule {
+  /** Environment-name globs. Absent: every environment. */
+  environments?: string[];
+  /** Member-name globs. Absent: every member, and a pipeline outside a workspace member. */
+  members?: string[];
+  /** The identity the plan and record jobs take. */
+  plan: string;
+  /** The identity the apply jobs take. */
+  apply: string;
+}
+
+export interface AwsCloudIdentity {
+  /** The STS region. Default `us-east-1`. */
+  region?: string;
+  /** The OIDC token's audience. Default `sts.amazonaws.com`. */
+  audience?: string;
+  /** The STS endpoint, for an emulator. Default the region's, or `AWS_ENDPOINT_URL_STS` in the job. */
+  endpoint?: string;
+  rules: CloudIdentityRule[];
+}
+
+export interface GcpCloudIdentity {
+  /** The workload identity provider: `projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>`. */
+  provider: string;
+  /** The OIDC token's audience. Default `https://iam.googleapis.com/<provider>`. */
+  audience?: string;
+  /** Google's STS, for an emulator. Default `https://sts.googleapis.com`. */
+  stsEndpoint?: string;
+  /** IAM credentials, for an emulator. Default `https://iamcredentials.googleapis.com`. */
+  iamEndpoint?: string;
+  rules: CloudIdentityRule[];
+}
+
+export interface AzureCloudIdentity {
+  /** The Entra tenant. */
+  tenantId: string;
+  /** Set as AZURE_SUBSCRIPTION_ID and ARM_SUBSCRIPTION_ID when given. */
+  subscriptionId?: string;
+  /** The OIDC token's audience. Default `api://AzureADTokenExchange`. */
+  audience?: string;
+  /** The Entra authority host, for an emulator. Default `https://login.microsoftonline.com`. */
+  authority?: string;
+  rules: CloudIdentityRule[];
+}
+
+/** `ci.identity.cloud` as the declaration holds it. */
+export interface CloudIdentityDeclaration {
+  aws?: AwsCloudIdentity;
+  gcp?: GcpCloudIdentity;
+  azure?: AzureCloudIdentity;
+}
+
+/** What one job trades for: per cloud, the one identity and where to trade it. */
+export interface CloudTradeSpec {
+  aws?: { role: string; region: string; audience: string; endpoint?: string };
+  gcp?: { serviceAccount: string; provider: string; audience: string; stsEndpoint?: string; iamEndpoint?: string };
+  azure?: { clientId: string; tenantId: string; audience: string; subscriptionId?: string; authority?: string };
+}
+
+/** A pipeline's two trades: the plan and record jobs', and the apply jobs'. */
+export interface PipelineCloudIdentity {
+  plan: CloudTradeSpec;
+  apply: CloudTradeSpec;
+}
+
+const matches = (globs: readonly string[] | undefined, name: string | undefined): boolean =>
+  globs === undefined || (name !== undefined && globs.some((g) => (picomatch(g) as (s: string) => boolean)(name)));
+
+/** The first rule that covers `env` and `member`, or undefined. */
+export function ruleFor(rules: readonly CloudIdentityRule[], env: string, member?: string): CloudIdentityRule | undefined {
+  return rules.find((r) => matches(r.environments, env) && matches(r.members, member));
+}
+
+/** The provider's resource name without the `//iam.googleapis.com/` prefix. */
+const providerPath = (p: string): string => p.replace(/^(https:)?\/\/iam\.googleapis\.com\//, "");
+
+/**
+ * The plan and apply trades of the pipeline for `env` and `member`, or
+ * undefined when no rule of any cloud covers them. A cloud no rule covers
+ * is left out of both.
+ */
+export function resolveCloudIdentity(decl: CloudIdentityDeclaration | undefined, env: string, member?: string): PipelineCloudIdentity | undefined {
+  if (!decl) return undefined;
+  const plan: CloudTradeSpec = {};
+  const apply: CloudTradeSpec = {};
+  const aws = decl.aws && ruleFor(decl.aws.rules, env, member);
+  if (decl.aws && aws) {
+    const at = { region: decl.aws.region ?? "us-east-1", audience: decl.aws.audience ?? "sts.amazonaws.com", ...(decl.aws.endpoint ? { endpoint: decl.aws.endpoint } : {}) };
+    plan.aws = { role: aws.plan, ...at };
+    apply.aws = { role: aws.apply, ...at };
+  }
+  const gcp = decl.gcp && ruleFor(decl.gcp.rules, env, member);
+  if (decl.gcp && gcp) {
+    const provider = providerPath(decl.gcp.provider);
+    const at = {
+      provider,
+      audience: decl.gcp.audience ?? `https://iam.googleapis.com/${provider}`,
+      ...(decl.gcp.stsEndpoint ? { stsEndpoint: decl.gcp.stsEndpoint } : {}),
+      ...(decl.gcp.iamEndpoint ? { iamEndpoint: decl.gcp.iamEndpoint } : {}),
+    };
+    plan.gcp = { serviceAccount: gcp.plan, ...at };
+    apply.gcp = { serviceAccount: gcp.apply, ...at };
+  }
+  const azure = decl.azure && ruleFor(decl.azure.rules, env, member);
+  if (decl.azure && azure) {
+    const at = {
+      tenantId: decl.azure.tenantId,
+      audience: decl.azure.audience ?? "api://AzureADTokenExchange",
+      ...(decl.azure.subscriptionId ? { subscriptionId: decl.azure.subscriptionId } : {}),
+      ...(decl.azure.authority ? { authority: decl.azure.authority } : {}),
+    };
+    plan.azure = { clientId: azure.plan, ...at };
+    apply.azure = { clientId: azure.apply, ...at };
+  }
+  return Object.keys(plan).length > 0 ? { plan, apply } : undefined;
+}
+
+/** The clouds a trade covers, in {@link CLOUDS} order. */
+export function tradedClouds(spec: CloudTradeSpec): Cloud[] {
+  return CLOUDS.filter((c) => spec[c] !== undefined);
+}
+
+/** Every identity a trade names: the role, the service account, the client id. */
+export function tradeIdentities(spec: CloudTradeSpec): string[] {
+  return [spec.aws?.role, spec.gcp?.serviceAccount, spec.azure?.clientId].filter((v): v is string => v !== undefined);
+}
+
+/**
+ * The problems of a declared `ci.identity.cloud`, each with its JSON
+ * pointer: a rule whose plan and apply are one identity, or a plan identity
+ * that is another rule's apply identity. Either would let the plan job,
+ * which runs the change's code, act as an apply identity.
+ */
+export function cloudIdentityProblems(decl: CloudIdentityDeclaration): Array<{ pointer: string; message: string }> {
+  const out: Array<{ pointer: string; message: string }> = [];
+  for (const cloud of CLOUDS) {
+    const rules = decl[cloud]?.rules ?? [];
+    const applies = new Set(rules.map((r) => r.apply));
+    rules.forEach((r, i) => {
+      const pointer = `/ci/identity/cloud/${cloud}/rules/${i}`;
+      if (r.plan === r.apply) out.push({ pointer, message: `ci.identity.cloud.${cloud}.rules[${i}] plans and applies as ${r.plan}; the plan runs the pull request's code, so give it an identity of its own` });
+      else if (applies.has(r.plan)) out.push({ pointer, message: `ci.identity.cloud.${cloud}.rules[${i}] plans as ${r.plan}, which another rule applies as; the plan runs the pull request's code, so give it an identity no rule applies as` });
+    });
+  }
+  return out;
+}
+
+/** The variable the trade step reads its {@link CloudTradeSpec} from, as JSON. */
+export const TRADE_SPEC_ENV = "CHANT_CLOUD_TRADE";
+
+/** The GitLab `id_tokens` variable a cloud's token comes in: `CHANT_ID_TOKEN_AWS`, `_GCP`, `_AZURE`. */
+export function idTokenVar(cloud: Cloud): string {
+  return `CHANT_ID_TOKEN_${cloud.toUpperCase()}`;
+}
+
+/**
+ * The variables a GitHub or Forgejo step requests an OIDC token with, and
+ * the GitLab `id_tokens` variables the trade reads. A step that runs the
+ * change's code starts without them, once the trade is done.
+ */
+export const OIDC_REQUEST_VARS = ["ACTIONS_ID_TOKEN_REQUEST_TOKEN", "ACTIONS_ID_TOKEN_REQUEST_URL", ...CLOUDS.map(idTokenVar), TRADE_SPEC_ENV] as const;
+
+/** The variables the trade sets, per cloud. */
+export const TRADED_VARS: Record<Cloud, readonly string[]> = {
+  aws: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_REGION", "AWS_DEFAULT_REGION"],
+  gcp: ["GOOGLE_OAUTH_ACCESS_TOKEN", "CLOUDSDK_AUTH_ACCESS_TOKEN"],
+  azure: ["AZURE_ACCESS_TOKEN", "AZURE_CLIENT_ID", "AZURE_TENANT_ID", "ARM_CLIENT_ID", "ARM_TENANT_ID", "AZURE_SUBSCRIPTION_ID", "ARM_SUBSCRIPTION_ID"],
+};
+
+/**
+ * How the trade leaves what it got. `github-env`: `NAME=value` lines
+ * appended to the file argv 1 names (`$GITHUB_ENV`), and an `::add-mask::`
+ * line for each secret, so every later step of the job has them. `sh`: a
+ * file of `export` lines a GitLab script sources, mode 0600.
+ */
+export type TradeFormat = "github-env" | "sh";
+
+/**
+ * The trade, a script for `node -e` with no dependency, so it runs before
+ * the checkout and reads none of the change's files. argv 1 is the file it
+ * writes and argv 2 its {@link TradeFormat}; {@link TRADE_SPEC_ENV} is the
+ * spec. The token comes from a cloud's {@link idTokenVar} when the job has
+ * it (GitLab's `id_tokens`), else from the forge's request URL with the
+ * cloud's audience. A value that holds anything but printable ASCII with no
+ * space is refused, so no answer can add a line of its own to the file. The
+ * script never prints a token.
+ */
+export const TRADE_JS = [
+  'const fs=require("fs");',
+  "const [out,format]=process.argv.slice(1);",
+  "const Q=String.fromCharCode(39);",
+  'const fail=(m)=>{console.error("chant: the OIDC trade failed: "+m);process.exit(1)};',
+  `let spec;try{spec=JSON.parse(process.env.${TRADE_SPEC_ENV}||"")}catch{fail("${TRADE_SPEC_ENV} is not JSON")}`,
+  'const clean=(v)=>typeof v==="string"&&/^[\\x21-\\x7e]+$/.test(v);',
+  'const trim=(u)=>String(u).replace(/\\/+$/,"");',
+  'const post=async(url,headers,body)=>{const r=await fetch(url,{method:"POST",headers,body});const t=await r.text();if(!r.ok)throw new Error(url+" answered "+r.status+": "+t.slice(0,200).replace(/\\s+/g," "));return t};',
+  'const json=(t,what)=>{try{return JSON.parse(t)}catch{throw new Error(what+" answered with no JSON")}};',
+  "const idToken=async(cloud,aud)=>{",
+  'const named=process.env["CHANT_ID_TOKEN_"+cloud.toUpperCase()];if(named)return named;',
+  "const u=process.env.ACTIONS_ID_TOKEN_REQUEST_URL,k=process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;",
+  'if(!u||!k)throw new Error("the job can request no OIDC token for "+cloud+": it needs id-token: write, and a pull request from a fork gets none");',
+  'const r=await fetch(u+(u.includes("?")?"&":"?")+"audience="+encodeURIComponent(aud),{headers:{authorization:"bearer "+k,accept:"application/json"}});',
+  'if(!r.ok)throw new Error("the OIDC token request answered "+r.status);',
+  'const v=json(await r.text(),"the OIDC token request").value;if(!clean(v))throw new Error("the OIDC token request gave no token");return v};',
+  "const vars={},secrets=[],said=[];",
+  "const run=async()=>{",
+  "if(spec.aws){const a=spec.aws;const tok=await idToken(\"aws\",a.audience);",
+  'const ep=trim(a.endpoint||process.env.AWS_ENDPOINT_URL_STS||("https://sts."+a.region+".amazonaws.com"+(a.region.startsWith("cn-")?".cn":"")));',
+  'const t=await post(ep+"/",{"content-type":"application/x-www-form-urlencoded",accept:"application/xml"},new URLSearchParams({Action:"AssumeRoleWithWebIdentity",Version:"2011-06-15",RoleArn:a.role,RoleSessionName:"chant-"+(process.env.GITHUB_RUN_ID||process.env.CI_JOB_ID||"job"),WebIdentityToken:tok}).toString());',
+  'const g=(k)=>{const m=new RegExp("<"+k+">([^<]+)</"+k+">").exec(t);return m?m[1].trim():undefined};',
+  'const id=g("AccessKeyId"),key=g("SecretAccessKey"),st=g("SessionToken");if(!clean(id)||!clean(key)||!clean(st))throw new Error("STS gave no credentials for "+a.role);',
+  'Object.assign(vars,{AWS_ACCESS_KEY_ID:id,AWS_SECRET_ACCESS_KEY:key,AWS_SESSION_TOKEN:st,AWS_REGION:a.region,AWS_DEFAULT_REGION:a.region});secrets.push(key,st);said.push(a.role)}',
+  "if(spec.gcp){const c=spec.gcp;const tok=await idToken(\"gcp\",c.audience);",
+  'const sts=trim(c.stsEndpoint||"https://sts.googleapis.com"),iam=trim(c.iamEndpoint||"https://iamcredentials.googleapis.com");',
+  'const fed=json(await post(sts+"/v1/token",{"content-type":"application/json"},JSON.stringify({grantType:"urn:ietf:params:oauth:grant-type:token-exchange",audience:"//iam.googleapis.com/"+c.provider,scope:"https://www.googleapis.com/auth/cloud-platform",requestedTokenType:"urn:ietf:params:oauth:token-type:access_token",subjectToken:tok,subjectTokenType:"urn:ietf:params:oauth:token-type:jwt"})),"Google STS").access_token;',
+  'if(!clean(fed))throw new Error("Google STS gave no token");',
+  'const at=json(await post(iam+"/v1/projects/-/serviceAccounts/"+encodeURIComponent(c.serviceAccount)+":generateAccessToken",{"content-type":"application/json",authorization:"Bearer "+fed},JSON.stringify({scope:["https://www.googleapis.com/auth/cloud-platform"]})),"IAM credentials").accessToken;',
+  'if(!clean(at))throw new Error("IAM credentials gave no token for "+c.serviceAccount);',
+  "Object.assign(vars,{GOOGLE_OAUTH_ACCESS_TOKEN:at,CLOUDSDK_AUTH_ACCESS_TOKEN:at});secrets.push(at);said.push(c.serviceAccount)}",
+  "if(spec.azure){const z=spec.azure;const tok=await idToken(\"azure\",z.audience);",
+  'const host=trim(z.authority||"https://login.microsoftonline.com");',
+  'const at=json(await post(host+"/"+encodeURIComponent(z.tenantId)+"/oauth2/v2.0/token",{"content-type":"application/x-www-form-urlencoded"},new URLSearchParams({client_id:z.clientId,scope:"https://management.azure.com/.default",grant_type:"client_credentials",client_assertion_type:"urn:ietf:params:oauth:client-assertion-type:jwt-bearer",client_assertion:tok}).toString()),"Entra").access_token;',
+  'if(!clean(at))throw new Error("Entra gave no token for "+z.clientId);',
+  "Object.assign(vars,{AZURE_ACCESS_TOKEN:at,AZURE_CLIENT_ID:z.clientId,AZURE_TENANT_ID:z.tenantId,ARM_CLIENT_ID:z.clientId,ARM_TENANT_ID:z.tenantId});",
+  "if(z.subscriptionId)Object.assign(vars,{AZURE_SUBSCRIPTION_ID:z.subscriptionId,ARM_SUBSCRIPTION_ID:z.subscriptionId});secrets.push(at);said.push(z.clientId)}",
+  'for(const [k,v] of Object.entries(vars))if(!clean(v))throw new Error(k+" is not a value the job can hold");',
+  'if(format==="github-env"){for(const s of secrets)console.log("::add-mask::"+s);fs.appendFileSync(out,Object.entries(vars).map(([k,v])=>k+"="+v+"\\n").join(""))}',
+  'else fs.writeFileSync(out,Object.entries(vars).map(([k,v])=>"export "+k+"="+Q+v.split(Q).join(Q+"\\\\"+Q+Q)+Q+"\\n").join(""),{mode:0o600});',
+  'for(const s of said)console.error("chant: traded the job\\u0027s OIDC token for "+s)};',
+  "run().catch((e)=>fail(e&&e.message?e.message:String(e)));",
+].join("");
+
+/**
+ * The shell line of a trade step: `node -e` from `/`, so no file of the
+ * checkout (a `package.json`, an `.npmrc`) is in reach, writing `out` in
+ * `format`.
+ */
+export function tradeLine(out: string, format: TradeFormat): string {
+  return `(cd / && node -e '${TRADE_JS}' "${out}" ${format})`;
+}
+
+/** The GitLab file the trade writes and the plan script sources, outside the project directory. */
+export const GITLAB_TRADE_FILE = "${TMPDIR:-/tmp}/chant-cloud-$CI_JOB_ID.sh";
+
+/**
+ * The lines a GitLab job's script starts with when it trades: the trade,
+ * the unset of the token variables (and, with `extraUnset`, the forge
+ * tokens'), and the source of what the trade wrote, which it then deletes.
+ */
+export function gitlabTradeLines(extraUnset: readonly string[] = []): string[] {
+  return [
+    tradeLine(GITLAB_TRADE_FILE, "sh"),
+    `unset ${[...extraUnset, ...OIDC_REQUEST_VARS].join(" ")}`,
+    `. "${GITLAB_TRADE_FILE}" && rm -f "${GITLAB_TRADE_FILE}"`,
+  ];
+}
+
+/** GitLab's `id_tokens:` for a trade: one per cloud, with the cloud's audience. */
+export function gitlabTradeIdTokens(spec: CloudTradeSpec): Record<string, { aud: string }> {
+  return Object.fromEntries(tradedClouds(spec).map((c) => [idTokenVar(c), { aud: spec[c]!.audience }]));
+}

package/src/cli/handlers/approve.ts

@@ -21,6 +21,7 @@ import {
   type GateApprover, type GatePolicyDecision, type GatePolicyEvaluator, type ResolvedGateApproval,
 } from "../../op/gate-approval";
 import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate";
+import { quorumRuleLine, quorumRules, trustQuorumJudge, UNPROVEN_JUDGE, type GateQuorumJudge } from "../../op/gate-quorum";
 import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, RELEASE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
 import { PR_GATE_OP } from "../../pr-loop";
 import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
@@ -680,7 +681,9 @@ export async function recordGateApproval(
     ));
   }
   if (approval) {
-    for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin, ledger.pending)) {
+    // #4290: the rules count roles from .chant/trust.json at base, for a proven approver.
+    const judge = trustQuorumJudge({ signers: scope.policy, roles: scope.policy.roles });
+    for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin, ledger.pending, judge)) {
       console.error(formatInfo(line));
     }
   }
@@ -699,6 +702,7 @@ export function describeApprovalProgress(
   prior: GateResolutionRecord[],
   standing: PendingGateRecord | undefined,
   pending: readonly PendingGateRecord[] = standing ? [standing] : [],
+  judge: GateQuorumJudge = UNPROVEN_JUDGE,
 ): string[] {
   const lines: string[] = [];
   const decision = record.policyDecision;
@@ -717,15 +721,24 @@ export function describeApprovalProgress(
   const since = standing?.timestamp ?? new Date(0).toISOString();
   // #3206: count the humans the way the run will, back past facts re-recorded for this plan.
   const humansSince = standing && samePlanDigest(standing.planDigest, record.planDigest) ? humanQuorumSince(pending, standing) : since;
-  const tally = tallyGateApprovals([...prior, record], record.gate, since, record.planDigest, approval, humansSince);
-  const roles = approval.quorum?.roles ? ` with role ${approval.quorum.roles.join(" or ")}` : "";
+  const tally = tallyGateApprovals([...prior, record], record.gate, since, record.planDigest, approval, humansSince, judge);
   const who = tally.counted.map((r) => r.resolvedBy).join(", ") || "none yet";
-  lines.push(`Quorum: ${tally.counted.length} of ${tally.need} human approval(s)${roles} for this plan (${who}).`);
+  if (!Array.isArray(approval.quorum)) {
+    const one = quorumRules(approval.quorum)[0];
+    const roles = one?.roles ? ` with role ${one.roles.join(" or ")}` : "";
+    lines.push(`Quorum: ${tally.counted.length} of ${tally.need} human approval(s)${roles} for this plan (${who}).`);
+  } else {
+    // #4290: one line per approval rule the gate takes.
+    for (const p of tally.rules ?? []) lines.push(`Quorum: ${quorumRuleLine(p)}.`);
+  }
   if (!tally.counted.includes(record)) {
+    const roles = quorumRules(approval.quorum).flatMap((r) => r.roles ?? []);
     lines.push(
       approverOf(record).kind === "agent"
         ? "An agent's approval does not count toward the quorum."
-        : `This approval does not count toward the quorum: the approver claims none of its roles (${approval.quorum?.roles?.join(", ")}).`,
+        : judge(record).proven
+          ? `This approval does not count toward the quorum: .chant/trust.json at base gives ${record.resolvedBy} none of its roles (${[...new Set(roles)].join(", ")}).`
+          : `This approval does not count toward the quorum: its roles are read from .chant/trust.json at base, and only for an approval sealed by a signer listed at base (chant approve --sign).`,
     );
   }
   return lines;

package/src/cli/handlers/build.ts

@@ -21,6 +21,9 @@ import type { PrLoopPipelineOptions } from "../../components/pr-pipeline";
  * `review-rules` security group (#4168); off otherwise. `requireRunnerStart`
  * is `--require-runner-start`, or the `isolated-runners` group. `--apply-on-merge`
  * (#4168) writes the apply job on merge in place of the record job.
+ * `--pr-env` (#4298) adds the jobs of a pull request's environment.
+ * `--apply-before-merge` (#4301) writes the apply job that applies an open
+ * pull request before it merges, beside the record job.
  */
 function prLoopOption(args: CommandContext["args"], reportUrl: string | undefined, requireReview = false, requireRunnerStart = false): PrLoopPipelineOptions {
   return {
@@ -33,6 +36,8 @@ function prLoopOption(args: CommandContext["args"], reportUrl: string | undefine
     ...(args.requireReview === true || requireReview ? { requireReview: true } : {}),
     ...(args.requireRunnerStart === true || requireRunnerStart ? { requireRunnerStart: true } : {}),
     ...(args.applyOnMerge ? { applyOnMerge: true } : {}),
+    ...(args.prEnv ? { prEnvironment: true } : {}),
+    ...(args.applyBeforeMerge ? { applyBeforeMerge: true } : {}),
   };
 }
 
@@ -141,6 +146,17 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
     }
   }
 
+  // #4296: the plan and apply cloud identities ci.identity.cloud gives this pipeline's environment and member.
+  let identity: import("../../ci-identity").PipelineCloudIdentity | undefined;
+  if (found && args.prLoop) {
+    try {
+      identity = await (await import("../../workspace/ci-cloud-identity")).declaredCloudIdentity(resolve(args.path), args.env ?? "production", plan?.member.name);
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
+
   // Which lexicons support generate mode is a property of the loaded lexicon
   // plugins (those implementing `generateComponentPipeline`, #688), not a
   // hard-coded core list — `generateComponentsPipeline` returns a descriptive
@@ -161,7 +177,8 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
         ? { gatedWaves: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } }
         : {}),
       // #3183: a plan job per pull request and an apply job per merge.
-      ...(args.prLoop ? { prLoop: prLoopOption(args, reportUrl, reviewRules, isolatedRunners) } : {}),
+      // #4292: on the branch ci.branches routes the member to, when it routes it.
+      ...(args.prLoop ? { prLoop: { ...prLoopOption(args, reportUrl, reviewRules, isolatedRunners), ...(plan?.branch ? { branch: plan.branch } : {}), ...(identity ? { identity } : {}) } } : {}),
       // #4002: the job image and the lines that install what it lacks, chant itself included.
       ...(args.image ? { image: args.image } : {}),
       ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),