@intentius/chant 0.124.40 → 0.124.41

package/dist/ci-identity.d.ts

@@ -0,0 +1,190 @@
+/**
+ * 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.
+ */
+/** The clouds `ci.identity.cloud` names. */
+export declare const CLOUDS: readonly ["aws", "gcp", "azure"];
+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;
+}
+/** The first rule that covers `env` and `member`, or undefined. */
+export declare function ruleFor(rules: readonly CloudIdentityRule[], env: string, member?: string): CloudIdentityRule | undefined;
+/**
+ * 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 declare function resolveCloudIdentity(decl: CloudIdentityDeclaration | undefined, env: string, member?: string): PipelineCloudIdentity | undefined;
+/** The clouds a trade covers, in {@link CLOUDS} order. */
+export declare function tradedClouds(spec: CloudTradeSpec): Cloud[];
+/** Every identity a trade names: the role, the service account, the client id. */
+export declare function tradeIdentities(spec: CloudTradeSpec): string[];
+/**
+ * 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 declare function cloudIdentityProblems(decl: CloudIdentityDeclaration): Array<{
+    pointer: string;
+    message: string;
+}>;
+/** The variable the trade step reads its {@link CloudTradeSpec} from, as JSON. */
+export declare 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 declare function idTokenVar(cloud: Cloud): string;
+/**
+ * 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 declare const OIDC_REQUEST_VARS: readonly ["ACTIONS_ID_TOKEN_REQUEST_TOKEN", "ACTIONS_ID_TOKEN_REQUEST_URL", ...string[], "CHANT_CLOUD_TRADE"];
+/** The variables the trade sets, per cloud. */
+export declare const TRADED_VARS: Record<Cloud, readonly string[]>;
+/**
+ * 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 declare const TRADE_JS: string;
+/**
+ * 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 declare function tradeLine(out: string, format: TradeFormat): string;
+/** The GitLab file the trade writes and the plan script sources, outside the project directory. */
+export declare 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 declare function gitlabTradeLines(extraUnset?: readonly string[]): string[];
+/** GitLab's `id_tokens:` for a trade: one per cloud, with the cloud's audience. */
+export declare function gitlabTradeIdTokens(spec: CloudTradeSpec): Record<string, {
+    aud: string;
+}>;
+//# sourceMappingURL=ci-identity.d.ts.map

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

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

package/dist/ci-identity.js

@@ -0,0 +1,219 @@
+/**
+ * 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"];
+const matches = (globs, name) => globs === undefined || (name !== undefined && globs.some((g) => picomatch(g)(name)));
+/** The first rule that covers `env` and `member`, or undefined. */
+export function ruleFor(rules, env, member) {
+    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) => 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, env, member) {
+    if (!decl)
+        return undefined;
+    const plan = {};
+    const apply = {};
+    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) {
+    return CLOUDS.filter((c) => spec[c] !== undefined);
+}
+/** Every identity a trade names: the role, the service account, the client id. */
+export function tradeIdentities(spec) {
+    return [spec.aws?.role, spec.gcp?.serviceAccount, spec.azure?.clientId].filter((v) => 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) {
+    const out = [];
+    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) {
+    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];
+/** The variables the trade sets, per cloud. */
+export const TRADED_VARS = {
+    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"],
+};
+/**
+ * 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, format) {
+    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 = []) {
+    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) {
+    return Object.fromEntries(tradedClouds(spec).map((c) => [idTokenVar(c), { aud: spec[c].audience }]));
+}

package/dist/cli/handlers/approve.d.ts

@@ -1,6 +1,7 @@
 import type { GateResolutionRecord, PendingGateRecord } from "../../lifecycle/gate-ledger.js";
 import { type GateOrigin } from "../../lifecycle/gate-origin.js";
 import { type GatePolicyEvaluator, type ResolvedGateApproval } from "../../op/gate-approval.js";
+import { type GateQuorumJudge } from "../../op/gate-quorum.js";
 import type { CommandContext } from "../registry.js";
 export declare function runApprove(ctx: CommandContext): Promise<number>;
 /** What a caller supplies alongside the op and gate names. */
@@ -94,5 +95,5 @@ export declare function recordGateApproval(opName: string, gate: string, opts: G
  * for this plan. The run decides the gate from the ledger; these lines only
  * say what it will find.
  */
-export declare function describeApprovalProgress(approval: ResolvedGateApproval, record: GateResolutionRecord, prior: GateResolutionRecord[], standing: PendingGateRecord | undefined, pending?: readonly PendingGateRecord[]): string[];
+export declare function describeApprovalProgress(approval: ResolvedGateApproval, record: GateResolutionRecord, prior: GateResolutionRecord[], standing: PendingGateRecord | undefined, pending?: readonly PendingGateRecord[], judge?: GateQuorumJudge): string[];
 //# sourceMappingURL=approve.d.ts.map

package/dist/cli/handlers/approve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approve.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/approve.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAC3F,OAAO,EACuE,KAAK,UAAU,EAC5F,MAAM,6BAA6B,CAAC;AAOrC,OAAO,EAEuC,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAChG,MAAM,wBAAwB,CAAC;AAQhC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAkDlD,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6GrE;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AA0ClB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAmX9B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,oBAAoB,EAAE,EAC7B,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,OAAO,GAAE,SAAS,iBAAiB,EAA+B,GACjE,MAAM,EAAE,CA8BV"}
+{"version":3,"file":"approve.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/approve.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAC3F,OAAO,EACuE,KAAK,UAAU,EAC5F,MAAM,6BAA6B,CAAC;AAOrC,OAAO,EAEuC,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAChG,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAiE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAO3H,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAkDlD,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6GrE;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AA0ClB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAqX9B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,oBAAoB,EAAE,EAC7B,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,OAAO,GAAE,SAAS,iBAAiB,EAA+B,EAClE,KAAK,GAAE,eAAgC,GACtC,MAAM,EAAE,CAuCV"}

package/dist/cli/handlers/approve.js

@@ -11,6 +11,7 @@ import { appendGateResolution, appendPendingGate, readGateLedger, latestPendingG
 import { isPlanDigest, samePlanDigest } from "../../lifecycle/plan-digest.js";
 import { gateContextDigest, gatePolicyRequest, loadGatePolicyEvaluator, } from "../../op/gate-approval.js";
 import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate.js";
+import { quorumRuleLine, quorumRules, trustQuorumJudge, UNPROVEN_JUDGE } from "../../op/gate-quorum.js";
 import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, RELEASE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name.js";
 import { PR_GATE_OP } from "../../pr-loop.js";
 import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git.js";
@@ -557,7 +558,9 @@ export async function recordGateApproval(opName, gate, opts) {
             "after it plans again. A moved plan or another commit starts it at the first phase."));
     }
     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));
         }
     }
@@ -569,7 +572,7 @@ export async function recordGateApproval(opName, gate, opts) {
  * for this plan. The run decides the gate from the ledger; these lines only
  * say what it will find.
  */
-export function describeApprovalProgress(approval, record, prior, standing, pending = standing ? [standing] : []) {
+export function describeApprovalProgress(approval, record, prior, standing, pending = standing ? [standing] : [], judge = UNPROVEN_JUDGE) {
     const lines = [];
     const decision = record.policyDecision;
     if (decision) {
@@ -586,14 +589,25 @@ export function describeApprovalProgress(approval, record, prior, standing, pend
     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/dist/cli/handlers/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAsNlD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAsJnE"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAoOlD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAsJnE"}

package/dist/cli/handlers/build.js

@@ -18,6 +18,7 @@ import { resolvePromotionSource } from "../../components/promote-order.js";
  * `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.
  */
 function prLoopOption(args, reportUrl, requireReview = false, requireRunnerStart = false) {
     return {
@@ -30,6 +31,7 @@ function prLoopOption(args, reportUrl, requireReview = false, requireRunnerStart
         ...(args.requireReview === true || requireReview ? { requireReview: true } : {}),
         ...(args.requireRunnerStart === true || requireRunnerStart ? { requireRunnerStart: true } : {}),
         ...(args.applyOnMerge ? { applyOnMerge: true } : {}),
+        ...(args.prEnv ? { prEnvironment: true } : {}),
     };
 }
 /**
@@ -136,6 +138,17 @@ async function runGenerateComponents(ctx) {
             return 1;
         }
     }
+    // #4296: the plan and apply cloud identities ci.identity.cloud gives this pipeline's environment and member.
+    let identity;
+    if (found && args.prLoop) {
+        try {
+            identity = await (await import("../../workspace/ci-cloud-identity.js")).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
@@ -153,7 +166,8 @@ async function runGenerateComponents(ctx) {
             ? { 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 } : {}),

package/dist/cli/handlers/fan-out.js

@@ -55,7 +55,7 @@ import { samePlanDigest } from "../../lifecycle/plan-digest.js";
 import { affectedStacks } from "../../lifecycle/affected.js";
 import { changedFilesBetween, lexiconChangedUnits } from "../../components/changed-files.js";
 import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support.js";
-import { EarlierWaveNotAppliedError, runFanOut } from "../../components/fan-out-run.js";
+import { EarlierWaveNotAppliedError, EarlierWaveWaitingError, runFanOut } from "../../components/fan-out-run.js";
 import { readFanOutAttempt, writeFanOutAttempt } from "../../components/fan-out-record.js";
 import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs.js";
 import { appliedDigestOf } from "../../components/auto-release.js";
@@ -267,6 +267,7 @@ async function fanOut(ctx, projectPath, config) {
     let priorOutputs = {};
     let priorWaves = [];
     let priorCarried = {};
+    let priorFailed = [];
     let progress;
     if (resumePath) {
         let attempt;
@@ -311,6 +312,12 @@ async function fanOut(ctx, projectPath, config) {
             priorOutputs = Object.fromEntries(Object.entries(attempt.outputs).filter(([name]) => carried.has(name)));
             progress = { completed: split.carried };
             priorWaves = attempt.waves ?? [];
+            // #4291: what failed stays in the record until it applies, so each later wave's job blocks its dependents and runs the rest.
+            priorFailed = attempt.failed.filter((name) => !carried.has(name));
+            if (waveGate?.only !== undefined) {
+                waveGate.failedEarlier = priorFailed;
+                waveGate.waitingEarlier = priorWaves.filter((w) => w.status === "gated").map((w) => ({ wave: w.wave, gate: w.gate, components: w.components }));
+            }
             // What steps kept per member (#3459), such as a choudoufu root's wave
             // resume file. Each step decides whether what it kept still applies.
             priorCarried = attempt.carried ?? {};
@@ -370,7 +377,7 @@ async function fanOut(ctx, projectPath, config) {
     // repeated command picks up from there instead of redoing them.
     const completedSoFar = new Set(priorCompleted);
     const inputsSoFar = { ...priorInputs };
-    const failedSoFar = [];
+    const failedSoFar = new Set(priorFailed);
     const outputsSoFar = { ...priorOutputs };
     let wavesSoFar = priorWaves;
     const carriedSoFar = { ...priorCarried };
@@ -429,9 +436,10 @@ async function fanOut(ctx, projectPath, config) {
                                 inputsSoFar[settled.component] = inputsNow[settled.component];
                             if (outputs)
                                 outputsSoFar[settled.component] = outputs;
+                            failedSoFar.delete(settled.component);
                         }
                         else if (settled.status === "fail") {
-                            failedSoFar.push(settled.component);
+                            failedSoFar.add(settled.component);
                         }
                         recordAttempt();
                     },
@@ -442,6 +450,11 @@ async function fanOut(ctx, projectPath, config) {
     catch (err) {
         events?.settle("failed", err instanceof Error ? err.message : String(err));
         // `--wave <n>` reached before an earlier wave applied: nothing ran.
+        // #4291: an earlier wave waits at its gate, so this one waits too.
+        if (err instanceof EarlierWaveWaitingError) {
+            console.error(formatInfo(err.message));
+            return GATED_EXIT_CODE;
+        }
         if (err instanceof EarlierWaveNotAppliedError) {
             console.error(formatError({ message: err.message }));
             return 1;

package/dist/cli/handlers/gate-resume.d.ts

@@ -19,6 +19,7 @@
  */
 import { type GateResolutionRecord, type PendingGateRecord } from "../../lifecycle/gate-ledger.js";
 import { type AppliedGateLine, type FinishedGateRecord } from "../../lifecycle/gate-applied.js";
+import { type GateQuorumJudge } from "../../op/gate-quorum.js";
 import { type GateResumeOutcome } from "../../op/gate-resume.js";
 import { type GateResumeCandidate, type GateResumeReason } from "../../op/gate-resume-plan.js";
 import type { GateRunLocator } from "../../op/gate-run-locator.js";
@@ -77,6 +78,8 @@ export interface ResumeGateOptions {
     /** The lines of `_gates/<op>/applied.jsonl` (#3858). Read from `chant/lifecycle` by {@link resumeOpGates} when not given. */
     applied?: readonly AppliedGateLine[];
     finished?: readonly FinishedGateRecord[];
+    /** Proves approvers for approval rules that name roles (#4290). Read from the trust policy at base when a fact needs one and none is given. */
+    judge?: GateQuorumJudge;
 }
 /** Every question the workspace at `cwd` lists, by id, the lifecycle ledger's included. Empty when the workspace can't be read. */
 export declare function workspaceQuestions(cwd: string): Promise<Map<string, PointQuestionState>>;