workspace-conformance 1.5.0 → 1.6.0

package/README.md

@@ -224,6 +224,7 @@ Every workflow check takes `workflows` (globs of the files to read, `.github/wor
 | `workflow-runner-resolution` | A custom or self-hosted runner label is not named literally in several jobs; a resolver job has a `timeout-minutes` and its output a literal hosted fallback. | `repeated-label`, `resolver-no-timeout`, `resolver-no-fallback`, `resolver-fallback-not-hosted` |
 | `workflow-version-single-source` | A setup step does not hold a literal runtime version when `.nvmrc` or `.tool-versions` already does. | `literal-version` |
 | `workflow-credentials` | Attestation steps have `id-token: write` and `attestations: write`; a publish that passes no token blanks the token variables, or at least requests provenance so that a fallback publish is traceable. | `attestation-permissions`, `tokenless-publish-unprotected` |
+| `workflow-release-job` | The release job is the only job granted `id-token: write`, runs in a deployment environment and checks out with `persist-credentials: false`; no job holding `id-token: write` passes an npm token from a secret. | `id-token-workflow-level`, `id-token-outside-release`, `missing-environment`, `persisted-credentials`, `token-beside-oidc` |
 | `workflow-repository-dispatch` | A `repository_dispatch` handler does not push to the default branch, auto-merge without a required-checks rule, push or open pull requests as `GITHUB_TOKEN`, or dispatch to another repository with it. | `pushes-default-branch`, `auto-merge-without-required-checks`, `default-token-triggers-nothing`, `dispatch-other-repository-with-default-token` |
 | `workflow-update-bot-cooldown` | Dependabot has a `cooldown` in every update entry, and Renovate sets `minimumReleaseAge`. | `dependabot-no-cooldown`, `renovate-no-minimum-release-age` |
 | `workflow-merge-group` | A workflow that runs for `pull_request` also has a `merge_group` trigger. | `missing-trigger` |
@@ -241,6 +242,10 @@ Codes are `<check>/<code>`, so `workflow-job-ordering/release-before-deploy`. Th
 
 **`workflow-credentials`**: an attestation step (`actions/attest`, `actions/attest-build-provenance`, `actions/attest-sbom`) needs `id-token: write` and `attestations: write` in the job's effective permissions. Permissions declared nowhere are the repository's default, which the file cannot show and which does not grant `id-token`, so they are reported. A job with `id-token: write` that runs a publish command (`npm`, `pnpm` or `yarn npm publish`, with options such as `-r` or `--filter <package>` before `publish`, `semantic-release`, `changeset publish`, `lerna publish`, bare or behind `pnpm`, `pnpm exec`, `yarn` or `npx`) and passes no token must set `NODE_AUTH_TOKEN` and `NPM_TOKEN` to the empty string (at step, job or workflow level) or request provenance (`--provenance`, `NPM_CONFIG_PROVENANCE: true`, or `publishConfig.provenance: true` in the `package.json` of the working directory); provenance does not stop an inherited token being used, it makes that publish traceable. Limits: commands are read as text where a command starts, so a script file or composite action is not seen; provenance set in another `package.json` is not read; a job is tokenless only if no token variable has a non-empty value anywhere in it; a job that calls a reusable workflow is not read. `registry-url` is deliberately not reported, see below.
 
+**`workflow-release-job`** takes `releaseJobs` (`release`, the same default as `workflow-job-ordering`). npm binds a trusted publisher to the repository and the workflow file, not to a branch ([trusted publishers](https://docs.npmjs.com/trusted-publishers), [archived](https://web.archive.org/web/20260921070919/https://docs.npmjs.com/trusted-publishers/)), so anyone who can push a branch can edit that branch's copy of the workflow, remove the `if` that keeps publishing to the default branch, and publish. The protection has to live outside the file: a deployment environment whose deployment branch policy allows only the default branch, named as the environment of the trusted publisher on npm, so an OIDC token minted anywhere else is refused. In a workflow with a release job, `id-token-workflow-level` reports workflow-level `permissions` that grant `id-token: write` (directly or through `write-all`), since every job that declares none inherits it, and `id-token-outside-release` reports any other job that declares it, a job that calls a reusable workflow included, because the OIDC identity is the publishing credential and only the release job should be able to mint it. `missing-environment` reports a release job with no `environment` (a name, or a mapping with a `name`). `persisted-credentials` reports a release job's `actions/checkout` that does not set `persist-credentials: false` literally, since the job token, a `token` input or an `ssh-key` would otherwise stay in git config for every later step, the dependency install and third-party actions included. There is no exception for a release that pushes: semantic-release pushes to its `repositoryUrl` as written and, only when that fails, to the same URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment embedded (`lib/get-git-auth-url.js` of `semantic-release`), so it never needs the checkout's credentials. A deploy-key release job, the shape ExaDev's own release jobs use, checks out with `persist-credentials: false`, writes the key to a file in the step before the release, and hands it to git only through the `GIT_SSH_COMMAND` in the `env` of the steps that push; it is accepted as written, and the clean fixture holds one. In every workflow, `token-beside-oidc` reports a job whose effective permissions grant `id-token: write` and whose workflow, job or step `env` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context: a long-lived token beside the OIDC identity is a second way to publish that no environment protection or trusted publisher setting covers. Limits: the environment's protection rules and the npm trusted publisher settings cannot be seen in the file and are not read (`missing-environment` checks only that an environment is named); a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and the steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or set inside a composite action is not seen.
+
+What zizmor already covers, and what this check adds, as observed with zizmor 1.30.1 on this check's fixtures ([audit rules](https://docs.zizmor.sh/audits/), [archived](https://web.archive.org/web/20260929212113/https://docs.zizmor.sh/audits/)): `excessive-permissions` reports a workflow-level `id-token: write`, but not `id-token: write` declared by a second job, which only `undocumented-permissions` mentions when the grant has no comment. `artipacked` reports every `actions/checkout` without `persist-credentials: false`, in every job and every persona, at `help` severity for `actions/checkout` v6 and later, which keeps the credentials under `$RUNNER_TEMP` rather than in `.git/config`; this check reports it as a violation in the release job, where a step that reads git config has the publishing job's push credential. `secrets-outside-env` (auditor persona only) reports a `secrets` reference in a job with no environment, so it catches a missing environment only when the release job reads a secret; a tokenless OIDC release job with no environment produces no zizmor finding at all. `use-trusted-publishing` reports an `npm publish` that uses a token, but is silent once the job also has `id-token: write`, so an `NPM_TOKEN` from a secret beside `id-token: write` in a job with an environment produces no zizmor finding. No zizmor audit relates the grants of one job to the others in a workflow, or requires an environment for the job that holds `id-token: write`.
+
 **`workflow-repository-dispatch`** takes `defaultBranches` (`main` and `master`; the `github.event.repository.default_branch` expression always counts) and `assumeRequiredChecks`. It reads workflows with a `repository_dispatch` trigger, which anyone with write access can start through the API. `pushes-default-branch` reports a `git push` whose destination is the default branch (a leading `+` is ignored, a bare `HEAD` is the checked-out branch, quotes around a word are removed, `git -C <directory>` and `git -c <setting>` before `push` are read, and options that take a value such as `-o` are skipped), a push with no refspec while the default branch is checked out (no `git checkout -b` or `git switch -c` earlier in the job, no non-default `ref` on the checkout) and `stefanzweifel/git-auto-commit-action` on the default branch. `auto-merge-without-required-checks` reports `gh pr merge --auto`, which merges at once when the base branch requires no checks; the file cannot show the rule, so `assumeRequiredChecks: true` states it and `settings-required-checks` verifies it. `default-token-triggers-nothing` reports a push whose checkout kept the default token (no `token` input; a push to a URL that carries its own credentials does not use it), `gh pr create` with `GITHUB_TOKEN` and `peter-evans/create-pull-request` with the default token: events created with `GITHUB_TOKEN` start no workflows, so the result is never checked. `dispatch-other-repository-with-default-token` reports a dispatch (`gh api repos/<o>/<r>/dispatches`, `gh workflow run -R`, `peter-evans/repository-dispatch`) to a repository other than `github.repository` with `GITHUB_TOKEN`, whose access is limited to its own repository. Dispatching in the same repository with `GITHUB_TOKEN` is not reported, because GitHub documents `workflow_dispatch` and `repository_dispatch` as the events that do create runs when made with it ([events that trigger workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows), [archived](https://web.archive.org/web/20261001051219/https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)). Limits: commands are read as text, so a script file is not seen; a dispatch target written literally as this repository's own name is reported, since the file does not know the name.
 
 **`workflow-update-bot-cooldown`** takes `dependabot` (`.github/dependabot.yml`, else `.yaml`) and `renovate` (`renovate.json`, `.renovaterc.json`, `.renovaterc` and `.github/renovate.json`, the first that exists). Every Dependabot `updates` entry needs a `cooldown` with `default-days` or one of the `semver-*-days` above zero. Renovate needs `minimumReleaseAge` at the top level or in a `packageRules` entry, as a duration above zero (`0 days` and `null` wait for nothing). Limits: Dependabot's cooldown does not apply to security updates; a Renovate preset is not resolved (an `extends` entry counts only when its name contains `minimumReleaseAge`); a Renovate config is read as JSON with comments and trailing commas, so other JSON5 syntax and a `renovate` key in `package.json` are not read. A repository with neither bot has nothing to report; a file named in the options that does not exist fails the run.
@@ -306,7 +311,7 @@ it('conforms to the workspace layout', async () => {
 });
 ```
 
-Every check is also exported as a function taking `{ cwd, options }` (and `layout` for the import checks): `aggregateMappers`, `codecPairs`, `commandTypes`, `derivedTypes`, `importUphill`, `importRankSkip`, `importCrossSlice`, `importIsolatedGroups`, `importCycles`, `instructionSymlinks`, `singleStorybook`, `commitTypes`, `dockerfilePackageManager`, `migrationsDirectory`, `eslint`, the workflow checks (`workflowJobOrdering`, `workflowSkippableJobs`, `workflowRunnerResolution`, `workflowVersionSingleSource`, `workflowCredentials`, `workflowRepositoryDispatch`, `workflowUpdateBotCooldown`, `workflowMergeGroup` and `workflowActionPinning`) and, taking `{ cwd, options, github }`, the settings checks (`settingsMergeMethods`, `settingsRequiredChecks` and `settingsReviewThreadResolution`). These take options and a layout as already validated and do not check them again; go through `runChecks` for validation. `parseWorkflow` and `loadWorkflows` expose the workflow model the workflow checks read. A check is a function that returns `Promise<readonly Violation[]>`, where a `Violation` is `{ code, message, file, location? }`.
+Every check is also exported as a function taking `{ cwd, options }` (and `layout` for the import checks): `aggregateMappers`, `codecPairs`, `commandTypes`, `derivedTypes`, `importUphill`, `importRankSkip`, `importCrossSlice`, `importIsolatedGroups`, `importCycles`, `instructionSymlinks`, `singleStorybook`, `commitTypes`, `dockerfilePackageManager`, `migrationsDirectory`, `eslint`, the workflow checks (`workflowJobOrdering`, `workflowSkippableJobs`, `workflowRunnerResolution`, `workflowVersionSingleSource`, `workflowCredentials`, `workflowReleaseJob`, `workflowRepositoryDispatch`, `workflowUpdateBotCooldown`, `workflowMergeGroup` and `workflowActionPinning`) and, taking `{ cwd, options, github }`, the settings checks (`settingsMergeMethods`, `settingsRequiredChecks` and `settingsReviewThreadResolution`). These take options and a layout as already validated and do not check them again; go through `runChecks` for validation. `parseWorkflow` and `loadWorkflows` expose the workflow model the workflow checks read. A check is a function that returns `Promise<readonly Violation[]>`, where a `Violation` is `{ code, message, file, location? }`.
 
 ### Proving a handler map is exhaustive
 

package/dist/cli.js

@@ -1098,6 +1098,9 @@ function runsOnOf(reader, value, what) {
 		group
 	};
 }
+function environmentOf(reader, value, what) {
+	return isRecord(value) ? reader.text(value["name"], `${what}.name`) : reader.text(value, what);
+}
 function stepOf(reader, value, jobPath, index) {
 	const path = [
 		...jobPath,
@@ -1130,6 +1133,7 @@ function jobOf(reader, id, value) {
 		needs: reader.list(job["needs"], `${what}.needs`),
 		condition: reader.text(job["if"], `${what}.if`),
 		permissions: permissionsOf(reader, job["permissions"], `${what}.permissions`),
+		environment: environmentOf(reader, job["environment"], `${what}.environment`),
 		env: reader.texts(job["env"], `${what}.env`),
 		runsOn: runsOnOf(reader, job["runs-on"], `${what}.runs-on`),
 		timeoutMinutes: reader.text(job["timeout-minutes"], `${what}.timeout-minutes`),
@@ -1165,6 +1169,7 @@ function parseWorkflow(file, source) {
 		triggers,
 		triggerLocations: triggerLocationsOf(reader, triggers, root["on"]),
 		permissions: permissionsOf(reader, root["permissions"], "permissions"),
+		permissionsLocation: root["permissions"] === void 0 ? void 0 : reader.location(["permissions"]),
 		env: reader.texts(root["env"], "env"),
 		jobs: Object.entries(reader.record(root["jobs"], "jobs")).map(([id, job]) => jobOf(reader, id, job)),
 		callOutputs: Object.fromEntries(Object.entries(outputs).map(([name, output]) => [name, reader.text(reader.record(output, `on.workflow_call.outputs.${name}`)["value"], `on.workflow_call.outputs.${name}.value`) ?? ""]))
@@ -1343,6 +1348,14 @@ function callsAlways(condition) {
 * The default ids of junction jobs, shared by the checks that look for one.
 */
 const DEFAULT_JUNCTION_JOBS = ["required-checks"];
+/**
+* The default ids of release jobs, shared by the checks that look for one.
+*/
+const DEFAULT_RELEASE_JOBS = ["release"];
+/**
+* The variables a token for the npm registry is passed in.
+*/
+const REGISTRY_TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 //#endregion
 //#region src/checks/settings-required-checks.ts
 /**
@@ -1478,10 +1491,6 @@ const PACKAGE_MANAGER_OPTIONS = String.raw`(?:\s+(?:(?:--filter|-F|--workspace|-
 * Commands that publish a package to a registry.
 */
 const PUBLISH_COMMAND = new RegExp(String.raw`^(?:(?:npm|pnpm|yarn)${PACKAGE_MANAGER_OPTIONS}(?:\s+npm)?\s+publish|(?:(?:pnpm|yarn)(?:\s+exec)?\s+|npx\s+)?(?:semantic-release|changeset\s+publish|lerna\s+publish))(?:\s|$)`, "u");
-/**
-* The variables a token for the registry is passed in.
-*/
-const TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 const PROVENANCE_FLAG = /--provenance(?:=true)?(?:\s|$)/u;
 /**
 * Whether the `package.json` in the working directory asks for provenance with `publishConfig.provenance: true`, which applies to every publish of that package.
@@ -1505,7 +1514,7 @@ function attestationViolations(workflow, job) {
 * Whether the job passes a registry token to a step, which makes its publish not tokenless: a token variable with a value other than the empty string, anywhere in the environment.
 */
 function passesToken(workflow, job) {
-	return [void 0, ...job.steps].some((step) => TOKEN_VARIABLES.some((variable) => (effectiveEnv(workflow, job, step)[variable] ?? "") !== ""));
+	return [void 0, ...job.steps].some((step) => REGISTRY_TOKEN_VARIABLES.some((variable) => (effectiveEnv(workflow, job, step)[variable] ?? "") !== ""));
 }
 function tokenlessPublishViolations(workflow, job, provenanceInManifest) {
 	if (accessOf(effectivePermissions(workflow, job), "id-token") !== "write" || passesToken(workflow, job)) return [];
@@ -1513,9 +1522,9 @@ function tokenlessPublishViolations(workflow, job, provenanceInManifest) {
 		const publishes = scriptCommands(step.run).filter((line) => PUBLISH_COMMAND.test(line));
 		if (publishes.length === 0) return [];
 		const env = effectiveEnv(workflow, job, step);
-		const blanked = TOKEN_VARIABLES.every((variable) => env[variable] === "");
+		const blanked = REGISTRY_TOKEN_VARIABLES.every((variable) => env[variable] === "");
 		const provenance = provenanceInManifest || publishes.some((line) => PROVENANCE_FLAG.test(line)) || env["NPM_CONFIG_PROVENANCE"] === "true";
-		return blanked || provenance ? [] : [workflowViolation(workflow, "workflow-credentials/tokenless-publish-unprotected", `job '${job.id}' publishes with an OIDC identity and no token, but does not set ${TOKEN_VARIABLES.join(" and ")} to the empty string, so a token inherited from the environment is used when the OIDC exchange fails; set them to the empty string to prevent that, or request provenance so that such a publish at least carries a traceable attestation`, step.location)];
+		return blanked || provenance ? [] : [workflowViolation(workflow, "workflow-credentials/tokenless-publish-unprotected", `job '${job.id}' publishes with an OIDC identity and no token, but does not set ${REGISTRY_TOKEN_VARIABLES.join(" and ")} to the empty string, so a token inherited from the environment is used when the OIDC exchange fails; set them to the empty string to prevent that, or request provenance so that such a publish at least carries a traceable attestation`, step.location)];
 	});
 }
 /**
@@ -1533,7 +1542,6 @@ const workflowCredentials = async ({ cwd, options }) => {
 };
 //#endregion
 //#region src/checks/workflow-job-ordering.ts
-const DEFAULT_RELEASE_JOBS = ["release"];
 const DEFAULT_DEPLOY_JOBS = ["deploy"];
 const DEFAULT_DOCS_DEPLOY_JOBS = ["docs-deploy"];
 const DEFAULT_BRANCH = "main";
@@ -1681,6 +1689,71 @@ const workflowMergeGroup = async ({ cwd, options }) => (await loadWorkflows(cwd,
 	return location === void 0 || workflow.triggers.has("merge_group") ? [] : [workflowViolation(workflow, "workflow-merge-group/missing-trigger", "the workflow runs for pull requests but has no merge_group trigger, so its checks do not report for a pull request in the merge queue", location)];
 });
 //#endregion
+//#region src/checks/workflow-release-job.ts
+const CHECKOUT_ACTION$1 = "actions/checkout";
+/**
+* A value that reads the `secrets` context inside an expression.
+*/
+const FROM_SECRET = /\$\{\{[^}]*\bsecrets\./u;
+/**
+* The release jobs named for a message: `release job 'a'` or `release jobs 'a' and 'b'`.
+*/
+function releaseJobsText(releases) {
+	const ids = releases.map((job) => `'${job.id}'`);
+	return `release job${ids.length === 1 ? "" : "s"} ${ids.join(" and ")}`;
+}
+function grantsIdToken(permissions) {
+	return accessOf(permissions, "id-token") === "write";
+}
+function idTokenViolations(workflow, releases) {
+	const releaseIds = new Set(releases.map((job) => job.id));
+	const named = releaseJobsText(releases);
+	const workflowLevel = grantsIdToken(workflow.permissions) && workflow.permissionsLocation !== void 0 ? [workflowViolation(workflow, "workflow-release-job/id-token-workflow-level", `the workflow's permissions grant id-token: write to every job that declares none of its own; grant it on ${named} only`, workflow.permissionsLocation)] : [];
+	const jobLevel = workflow.jobs.filter((job) => !releaseIds.has(job.id) && grantsIdToken(job.permissions)).map((job) => workflowViolation(workflow, "workflow-release-job/id-token-outside-release", `job '${job.id}' is granted id-token: write but is not a release job, so it can mint the OIDC identity npm trusted publishing accepts for this workflow; only ${named} may hold it`, job.location));
+	return [...workflowLevel, ...jobLevel];
+}
+/**
+* What a checkout that does not set `persist-credentials: false` leaves in git config.
+*/
+function persistedCredential(step) {
+	if (step.with["ssh-key"] !== void 0) return "the SSH key";
+	return step.with["token"] === void 0 ? "the job token" : "the token it was given";
+}
+function releaseJobViolations(workflow, job) {
+	if (job.uses !== void 0) return [];
+	const environment = job.environment === void 0 ? [workflowViolation(workflow, "workflow-release-job/missing-environment", `release job '${job.id}' declares no environment, so nothing outside the workflow file stops a branch's copy of it publishing; run it in a protected environment restricted to the default branch`, job.location)] : [];
+	const checkouts = job.steps.filter((step) => stepUses(step, CHECKOUT_ACTION$1) && step.with["persist-credentials"] !== "false").map((step) => workflowViolation(workflow, "workflow-release-job/persisted-credentials", `release job '${job.id}' checks out without persist-credentials: false, which leaves ${persistedCredential(step)} in git config for every later step`, step.location));
+	return [...environment, ...checkouts];
+}
+/**
+* The token variables an environment sets from a secret.
+*/
+function secretTokens(env) {
+	return REGISTRY_TOKEN_VARIABLES.filter((variable) => FROM_SECRET.test(env[variable] ?? ""));
+}
+function tokenBesideOidcViolations(workflow, job) {
+	if (!grantsIdToken(effectivePermissions(workflow, job))) return [];
+	const report = (variables, location) => variables.length === 0 ? [] : [workflowViolation(workflow, "workflow-release-job/token-beside-oidc", `job '${job.id}' holds id-token: write and passes ${variables.join(" and ")} from a secret, a long-lived npm token beside the OIDC identity; publish through trusted publishing and blank the token variables`, location)];
+	return [...report(secretTokens(effectiveEnv(workflow, job, void 0)), job.location), ...job.steps.flatMap((step) => report(secretTokens(step.env), step.location))];
+}
+/**
+* npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+*
+* In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+*
+* In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+*
+* Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+*/
+const workflowReleaseJob = async ({ cwd, options }) => {
+	return (await loadWorkflows(cwd, options)).flatMap((workflow) => {
+		const releases = jobsNamed(workflow, options.releaseJobs ?? DEFAULT_RELEASE_JOBS);
+		const releaseFindings = releases.length === 0 ? [] : idTokenViolations(workflow, releases);
+		const jobFindings = workflow.jobs.flatMap((job) => [...releases.includes(job) ? releaseJobViolations(workflow, job) : [], ...tokenBesideOidcViolations(workflow, job)]);
+		return [...releaseFindings, ...jobFindings];
+	});
+};
+//#endregion
 //#region src/checks/workflow-repository-dispatch.ts
 const DEFAULT_BRANCHES = ["main", "master"];
 const DEFAULT_BRANCH_EXPRESSION = /\$\{\{\s*github\.event\.repository\.default_branch\s*\}\}/u;
@@ -3380,6 +3453,12 @@ const registry = {
 		select: (checks) => enabledOptions(checks["workflow-credentials"]),
 		check: workflowCredentials
 	}),
+	"workflow-release-job": plain({
+		name: "workflow-release-job",
+		description: "The release job alone holds id-token, runs in an environment and persists no credentials, and no job with id-token passes an npm token secret",
+		select: (checks) => enabledOptions(checks["workflow-release-job"]),
+		check: workflowReleaseJob
+	}),
 	"workflow-repository-dispatch": plain({
 		name: "workflow-repository-dispatch",
 		description: "A repository_dispatch handler does not push to the default branch, auto-merge unguarded, or rely on the default token",
@@ -3574,6 +3653,10 @@ const checks = z.strictObject({
 	}))),
 	"workflow-version-single-source": z.exactOptional(enabled(z.strictObject(selection))),
 	"workflow-credentials": z.exactOptional(enabled(z.strictObject(selection))),
+	"workflow-release-job": z.exactOptional(enabled(z.strictObject({
+		...selection,
+		releaseJobs: z.exactOptional(names)
+	}))),
 	"workflow-repository-dispatch": z.exactOptional(enabled(z.strictObject({
 		...selection,
 		defaultBranches: z.exactOptional(names),

package/dist/index.cjs

@@ -2128,6 +2128,9 @@ function runsOnOf(reader, value, what) {
 		group
 	};
 }
+function environmentOf(reader, value, what) {
+	return isRecord(value) ? reader.text(value["name"], `${what}.name`) : reader.text(value, what);
+}
 function stepOf(reader, value, jobPath, index) {
 	const path = [
 		...jobPath,
@@ -2160,6 +2163,7 @@ function jobOf(reader, id, value) {
 		needs: reader.list(job["needs"], `${what}.needs`),
 		condition: reader.text(job["if"], `${what}.if`),
 		permissions: permissionsOf(reader, job["permissions"], `${what}.permissions`),
+		environment: environmentOf(reader, job["environment"], `${what}.environment`),
 		env: reader.texts(job["env"], `${what}.env`),
 		runsOn: runsOnOf(reader, job["runs-on"], `${what}.runs-on`),
 		timeoutMinutes: reader.text(job["timeout-minutes"], `${what}.timeout-minutes`),
@@ -2195,6 +2199,7 @@ function parseWorkflow(file, source) {
 		triggers,
 		triggerLocations: triggerLocationsOf(reader, triggers, root["on"]),
 		permissions: permissionsOf(reader, root["permissions"], "permissions"),
+		permissionsLocation: root["permissions"] === void 0 ? void 0 : reader.location(["permissions"]),
 		env: reader.texts(root["env"], "env"),
 		jobs: Object.entries(reader.record(root["jobs"], "jobs")).map(([id, job]) => jobOf(reader, id, job)),
 		callOutputs: Object.fromEntries(Object.entries(outputs).map(([name, output]) => [name, reader.text(reader.record(output, `on.workflow_call.outputs.${name}`)["value"], `on.workflow_call.outputs.${name}.value`) ?? ""]))
@@ -2373,6 +2378,14 @@ function callsAlways(condition) {
 * The default ids of junction jobs, shared by the checks that look for one.
 */
 const DEFAULT_JUNCTION_JOBS = ["required-checks"];
+/**
+* The default ids of release jobs, shared by the checks that look for one.
+*/
+const DEFAULT_RELEASE_JOBS = ["release"];
+/**
+* The variables a token for the npm registry is passed in.
+*/
+const REGISTRY_TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 //#endregion
 //#region src/checks/settings-required-checks.ts
 /**
@@ -2523,10 +2536,6 @@ const PACKAGE_MANAGER_OPTIONS = String.raw`(?:\s+(?:(?:--filter|-F|--workspace|-
 * Commands that publish a package to a registry.
 */
 const PUBLISH_COMMAND = new RegExp(String.raw`^(?:(?:npm|pnpm|yarn)${PACKAGE_MANAGER_OPTIONS}(?:\s+npm)?\s+publish|(?:(?:pnpm|yarn)(?:\s+exec)?\s+|npx\s+)?(?:semantic-release|changeset\s+publish|lerna\s+publish))(?:\s|$)`, "u");
-/**
-* The variables a token for the registry is passed in.
-*/
-const TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 const PROVENANCE_FLAG = /--provenance(?:=true)?(?:\s|$)/u;
 /**
 * Whether the `package.json` in the working directory asks for provenance with `publishConfig.provenance: true`, which applies to every publish of that package.
@@ -2550,7 +2559,7 @@ function attestationViolations(workflow, job) {
 * Whether the job passes a registry token to a step, which makes its publish not tokenless: a token variable with a value other than the empty string, anywhere in the environment.
 */
 function passesToken(workflow, job) {
-	return [void 0, ...job.steps].some((step) => TOKEN_VARIABLES.some((variable) => (effectiveEnv(workflow, job, step)[variable] ?? "") !== ""));
+	return [void 0, ...job.steps].some((step) => REGISTRY_TOKEN_VARIABLES.some((variable) => (effectiveEnv(workflow, job, step)[variable] ?? "") !== ""));
 }
 function tokenlessPublishViolations(workflow, job, provenanceInManifest) {
 	if (accessOf(effectivePermissions(workflow, job), "id-token") !== "write" || passesToken(workflow, job)) return [];
@@ -2558,9 +2567,9 @@ function tokenlessPublishViolations(workflow, job, provenanceInManifest) {
 		const publishes = scriptCommands(step.run).filter((line) => PUBLISH_COMMAND.test(line));
 		if (publishes.length === 0) return [];
 		const env = effectiveEnv(workflow, job, step);
-		const blanked = TOKEN_VARIABLES.every((variable) => env[variable] === "");
+		const blanked = REGISTRY_TOKEN_VARIABLES.every((variable) => env[variable] === "");
 		const provenance = provenanceInManifest || publishes.some((line) => PROVENANCE_FLAG.test(line)) || env["NPM_CONFIG_PROVENANCE"] === "true";
-		return blanked || provenance ? [] : [workflowViolation(workflow, "workflow-credentials/tokenless-publish-unprotected", `job '${job.id}' publishes with an OIDC identity and no token, but does not set ${TOKEN_VARIABLES.join(" and ")} to the empty string, so a token inherited from the environment is used when the OIDC exchange fails; set them to the empty string to prevent that, or request provenance so that such a publish at least carries a traceable attestation`, step.location)];
+		return blanked || provenance ? [] : [workflowViolation(workflow, "workflow-credentials/tokenless-publish-unprotected", `job '${job.id}' publishes with an OIDC identity and no token, but does not set ${REGISTRY_TOKEN_VARIABLES.join(" and ")} to the empty string, so a token inherited from the environment is used when the OIDC exchange fails; set them to the empty string to prevent that, or request provenance so that such a publish at least carries a traceable attestation`, step.location)];
 	});
 }
 /**
@@ -2578,7 +2587,6 @@ const workflowCredentials = async ({ cwd, options }) => {
 };
 //#endregion
 //#region src/checks/workflow-job-ordering.ts
-const DEFAULT_RELEASE_JOBS = ["release"];
 const DEFAULT_DEPLOY_JOBS = ["deploy"];
 const DEFAULT_DOCS_DEPLOY_JOBS = ["docs-deploy"];
 const DEFAULT_BRANCH = "main";
@@ -2726,6 +2734,71 @@ const workflowMergeGroup = async ({ cwd, options }) => (await loadWorkflows(cwd,
 	return location === void 0 || workflow.triggers.has("merge_group") ? [] : [workflowViolation(workflow, "workflow-merge-group/missing-trigger", "the workflow runs for pull requests but has no merge_group trigger, so its checks do not report for a pull request in the merge queue", location)];
 });
 //#endregion
+//#region src/checks/workflow-release-job.ts
+const CHECKOUT_ACTION$1 = "actions/checkout";
+/**
+* A value that reads the `secrets` context inside an expression.
+*/
+const FROM_SECRET = /\$\{\{[^}]*\bsecrets\./u;
+/**
+* The release jobs named for a message: `release job 'a'` or `release jobs 'a' and 'b'`.
+*/
+function releaseJobsText(releases) {
+	const ids = releases.map((job) => `'${job.id}'`);
+	return `release job${ids.length === 1 ? "" : "s"} ${ids.join(" and ")}`;
+}
+function grantsIdToken(permissions) {
+	return accessOf(permissions, "id-token") === "write";
+}
+function idTokenViolations(workflow, releases) {
+	const releaseIds = new Set(releases.map((job) => job.id));
+	const named = releaseJobsText(releases);
+	const workflowLevel = grantsIdToken(workflow.permissions) && workflow.permissionsLocation !== void 0 ? [workflowViolation(workflow, "workflow-release-job/id-token-workflow-level", `the workflow's permissions grant id-token: write to every job that declares none of its own; grant it on ${named} only`, workflow.permissionsLocation)] : [];
+	const jobLevel = workflow.jobs.filter((job) => !releaseIds.has(job.id) && grantsIdToken(job.permissions)).map((job) => workflowViolation(workflow, "workflow-release-job/id-token-outside-release", `job '${job.id}' is granted id-token: write but is not a release job, so it can mint the OIDC identity npm trusted publishing accepts for this workflow; only ${named} may hold it`, job.location));
+	return [...workflowLevel, ...jobLevel];
+}
+/**
+* What a checkout that does not set `persist-credentials: false` leaves in git config.
+*/
+function persistedCredential(step) {
+	if (step.with["ssh-key"] !== void 0) return "the SSH key";
+	return step.with["token"] === void 0 ? "the job token" : "the token it was given";
+}
+function releaseJobViolations(workflow, job) {
+	if (job.uses !== void 0) return [];
+	const environment = job.environment === void 0 ? [workflowViolation(workflow, "workflow-release-job/missing-environment", `release job '${job.id}' declares no environment, so nothing outside the workflow file stops a branch's copy of it publishing; run it in a protected environment restricted to the default branch`, job.location)] : [];
+	const checkouts = job.steps.filter((step) => stepUses(step, CHECKOUT_ACTION$1) && step.with["persist-credentials"] !== "false").map((step) => workflowViolation(workflow, "workflow-release-job/persisted-credentials", `release job '${job.id}' checks out without persist-credentials: false, which leaves ${persistedCredential(step)} in git config for every later step`, step.location));
+	return [...environment, ...checkouts];
+}
+/**
+* The token variables an environment sets from a secret.
+*/
+function secretTokens(env) {
+	return REGISTRY_TOKEN_VARIABLES.filter((variable) => FROM_SECRET.test(env[variable] ?? ""));
+}
+function tokenBesideOidcViolations(workflow, job) {
+	if (!grantsIdToken(effectivePermissions(workflow, job))) return [];
+	const report = (variables, location) => variables.length === 0 ? [] : [workflowViolation(workflow, "workflow-release-job/token-beside-oidc", `job '${job.id}' holds id-token: write and passes ${variables.join(" and ")} from a secret, a long-lived npm token beside the OIDC identity; publish through trusted publishing and blank the token variables`, location)];
+	return [...report(secretTokens(effectiveEnv(workflow, job, void 0)), job.location), ...job.steps.flatMap((step) => report(secretTokens(step.env), step.location))];
+}
+/**
+* npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+*
+* In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+*
+* In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+*
+* Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+*/
+const workflowReleaseJob = async ({ cwd, options }) => {
+	return (await loadWorkflows(cwd, options)).flatMap((workflow) => {
+		const releases = jobsNamed(workflow, options.releaseJobs ?? DEFAULT_RELEASE_JOBS);
+		const releaseFindings = releases.length === 0 ? [] : idTokenViolations(workflow, releases);
+		const jobFindings = workflow.jobs.flatMap((job) => [...releases.includes(job) ? releaseJobViolations(workflow, job) : [], ...tokenBesideOidcViolations(workflow, job)]);
+		return [...releaseFindings, ...jobFindings];
+	});
+};
+//#endregion
 //#region src/checks/workflow-repository-dispatch.ts
 const DEFAULT_BRANCHES = ["main", "master"];
 const DEFAULT_BRANCH_EXPRESSION = /\$\{\{\s*github\.event\.repository\.default_branch\s*\}\}/u;
@@ -3302,6 +3375,10 @@ const checks = zod.z.strictObject({
 	}))),
 	"workflow-version-single-source": zod.z.exactOptional(enabled(zod.z.strictObject(selection))),
 	"workflow-credentials": zod.z.exactOptional(enabled(zod.z.strictObject(selection))),
+	"workflow-release-job": zod.z.exactOptional(enabled(zod.z.strictObject({
+		...selection,
+		releaseJobs: zod.z.exactOptional(names)
+	}))),
 	"workflow-repository-dispatch": zod.z.exactOptional(enabled(zod.z.strictObject({
 		...selection,
 		defaultBranches: zod.z.exactOptional(names),
@@ -3595,6 +3672,12 @@ const registry = {
 		select: (checks) => enabledOptions(checks["workflow-credentials"]),
 		check: workflowCredentials
 	}),
+	"workflow-release-job": plain({
+		name: "workflow-release-job",
+		description: "The release job alone holds id-token, runs in an environment and persists no credentials, and no job with id-token passes an npm token secret",
+		select: (checks) => enabledOptions(checks["workflow-release-job"]),
+		check: workflowReleaseJob
+	}),
 	"workflow-repository-dispatch": plain({
 		name: "workflow-repository-dispatch",
 		description: "A repository_dispatch handler does not push to the default branch, auto-merge unguarded, or rely on the default token",
@@ -3902,6 +3985,7 @@ exports.workflowActionPinning = workflowActionPinning;
 exports.workflowCredentials = workflowCredentials;
 exports.workflowJobOrdering = workflowJobOrdering;
 exports.workflowMergeGroup = workflowMergeGroup;
+exports.workflowReleaseJob = workflowReleaseJob;
 exports.workflowRepositoryDispatch = workflowRepositoryDispatch;
 exports.workflowRunnerResolution = workflowRunnerResolution;
 exports.workflowSkippableJobs = workflowSkippableJobs;

package/dist/index.d.cts

@@ -255,6 +255,10 @@ interface Job {
   readonly needs: readonly string[];
   readonly condition: string | undefined;
   readonly permissions: Permissions;
+  /**
+   * The name of the deployment environment the job runs in, written as `environment: <name>` or `environment: { name: <name> }`; `undefined` when it names none.
+   */
+  readonly environment: string | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly runsOn: RunsOn;
   readonly timeoutMinutes: string | undefined;
@@ -282,6 +286,10 @@ interface Workflow {
    */
   readonly triggerLocations: ReadonlyMap<string, SourceLocation>;
   readonly permissions: Permissions;
+  /**
+   * Where the workflow's `permissions` is written; `undefined` when it declares none.
+   */
+  readonly permissionsLocation: SourceLocation | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly jobs: readonly Job[];
   /**
@@ -667,6 +675,15 @@ type WorkflowVersionSingleSourceOptions = WorkflowSelection;
  * Options of the `workflow-credentials` check.
  */
 type WorkflowCredentialsOptions = WorkflowSelection;
+/**
+ * Options of the `workflow-release-job` check: the job that publishes is the only one that can mint the OIDC identity, runs in an environment and leaves no credentials behind.
+ */
+interface WorkflowReleaseJobOptions extends WorkflowSelection {
+  /**
+   * Ids of release jobs: the jobs that publish, and the only ones that may hold `id-token: write`. `release` when omitted.
+   */
+  readonly releaseJobs?: readonly string[];
+}
 /**
  * Options of the `workflow-repository-dispatch` check: what a handler of `repository_dispatch` may do.
  */
@@ -781,6 +798,7 @@ interface CheckOptionsByName {
   readonly "workflow-runner-resolution": WorkflowRunnerResolutionOptions;
   readonly "workflow-version-single-source": WorkflowVersionSingleSourceOptions;
   readonly "workflow-credentials": WorkflowCredentialsOptions;
+  readonly "workflow-release-job": WorkflowReleaseJobOptions;
   readonly "workflow-repository-dispatch": WorkflowRepositoryDispatchOptions;
   readonly "workflow-update-bot-cooldown": WorkflowUpdateBotCooldownOptions;
   readonly "workflow-merge-group": WorkflowMergeGroupOptions;
@@ -1088,6 +1106,18 @@ export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptio
  */
 export declare const workflowMergeGroup: CheckFunction<WorkflowMergeGroupOptions>;
 //#endregion
+//#region src/checks/workflow-release-job.d.ts
+/**
+ * npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+ *
+ * In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+ *
+ * In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+ *
+ * Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+ */
+export declare const workflowReleaseJob: CheckFunction<WorkflowReleaseJobOptions>;
+//#endregion
 //#region src/checks/workflow-repository-dispatch.d.ts
 /**
  * A workflow that handles `repository_dispatch` can be started by anyone with write access through the API, so what it does with the repository is held to a higher bar.
@@ -1356,4 +1386,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };

package/dist/index.d.ts

@@ -255,6 +255,10 @@ interface Job {
   readonly needs: readonly string[];
   readonly condition: string | undefined;
   readonly permissions: Permissions;
+  /**
+   * The name of the deployment environment the job runs in, written as `environment: <name>` or `environment: { name: <name> }`; `undefined` when it names none.
+   */
+  readonly environment: string | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly runsOn: RunsOn;
   readonly timeoutMinutes: string | undefined;
@@ -282,6 +286,10 @@ interface Workflow {
    */
   readonly triggerLocations: ReadonlyMap<string, SourceLocation>;
   readonly permissions: Permissions;
+  /**
+   * Where the workflow's `permissions` is written; `undefined` when it declares none.
+   */
+  readonly permissionsLocation: SourceLocation | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly jobs: readonly Job[];
   /**
@@ -667,6 +675,15 @@ type WorkflowVersionSingleSourceOptions = WorkflowSelection;
  * Options of the `workflow-credentials` check.
  */
 type WorkflowCredentialsOptions = WorkflowSelection;
+/**
+ * Options of the `workflow-release-job` check: the job that publishes is the only one that can mint the OIDC identity, runs in an environment and leaves no credentials behind.
+ */
+interface WorkflowReleaseJobOptions extends WorkflowSelection {
+  /**
+   * Ids of release jobs: the jobs that publish, and the only ones that may hold `id-token: write`. `release` when omitted.
+   */
+  readonly releaseJobs?: readonly string[];
+}
 /**
  * Options of the `workflow-repository-dispatch` check: what a handler of `repository_dispatch` may do.
  */
@@ -781,6 +798,7 @@ interface CheckOptionsByName {
   readonly "workflow-runner-resolution": WorkflowRunnerResolutionOptions;
   readonly "workflow-version-single-source": WorkflowVersionSingleSourceOptions;
   readonly "workflow-credentials": WorkflowCredentialsOptions;
+  readonly "workflow-release-job": WorkflowReleaseJobOptions;
   readonly "workflow-repository-dispatch": WorkflowRepositoryDispatchOptions;
   readonly "workflow-update-bot-cooldown": WorkflowUpdateBotCooldownOptions;
   readonly "workflow-merge-group": WorkflowMergeGroupOptions;
@@ -1088,6 +1106,18 @@ export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptio
  */
 export declare const workflowMergeGroup: CheckFunction<WorkflowMergeGroupOptions>;
 //#endregion
+//#region src/checks/workflow-release-job.d.ts
+/**
+ * npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+ *
+ * In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+ *
+ * In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+ *
+ * Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+ */
+export declare const workflowReleaseJob: CheckFunction<WorkflowReleaseJobOptions>;
+//#endregion
 //#region src/checks/workflow-repository-dispatch.d.ts
 /**
  * A workflow that handles `repository_dispatch` can be started by anyone with write access through the API, so what it does with the repository is held to a higher bar.
@@ -1356,4 +1386,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };

package/dist/index.js

@@ -2127,6 +2127,9 @@ function runsOnOf(reader, value, what) {
 		group
 	};
 }
+function environmentOf(reader, value, what) {
+	return isRecord(value) ? reader.text(value["name"], `${what}.name`) : reader.text(value, what);
+}
 function stepOf(reader, value, jobPath, index) {
 	const path = [
 		...jobPath,
@@ -2159,6 +2162,7 @@ function jobOf(reader, id, value) {
 		needs: reader.list(job["needs"], `${what}.needs`),
 		condition: reader.text(job["if"], `${what}.if`),
 		permissions: permissionsOf(reader, job["permissions"], `${what}.permissions`),
+		environment: environmentOf(reader, job["environment"], `${what}.environment`),
 		env: reader.texts(job["env"], `${what}.env`),
 		runsOn: runsOnOf(reader, job["runs-on"], `${what}.runs-on`),
 		timeoutMinutes: reader.text(job["timeout-minutes"], `${what}.timeout-minutes`),
@@ -2194,6 +2198,7 @@ function parseWorkflow(file, source) {
 		triggers,
 		triggerLocations: triggerLocationsOf(reader, triggers, root["on"]),
 		permissions: permissionsOf(reader, root["permissions"], "permissions"),
+		permissionsLocation: root["permissions"] === void 0 ? void 0 : reader.location(["permissions"]),
 		env: reader.texts(root["env"], "env"),
 		jobs: Object.entries(reader.record(root["jobs"], "jobs")).map(([id, job]) => jobOf(reader, id, job)),
 		callOutputs: Object.fromEntries(Object.entries(outputs).map(([name, output]) => [name, reader.text(reader.record(output, `on.workflow_call.outputs.${name}`)["value"], `on.workflow_call.outputs.${name}.value`) ?? ""]))
@@ -2372,6 +2377,14 @@ function callsAlways(condition) {
 * The default ids of junction jobs, shared by the checks that look for one.
 */
 const DEFAULT_JUNCTION_JOBS = ["required-checks"];
+/**
+* The default ids of release jobs, shared by the checks that look for one.
+*/
+const DEFAULT_RELEASE_JOBS = ["release"];
+/**
+* The variables a token for the npm registry is passed in.
+*/
+const REGISTRY_TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 //#endregion
 //#region src/checks/settings-required-checks.ts
 /**
@@ -2522,10 +2535,6 @@ const PACKAGE_MANAGER_OPTIONS = String.raw`(?:\s+(?:(?:--filter|-F|--workspace|-
 * Commands that publish a package to a registry.
 */
 const PUBLISH_COMMAND = new RegExp(String.raw`^(?:(?:npm|pnpm|yarn)${PACKAGE_MANAGER_OPTIONS}(?:\s+npm)?\s+publish|(?:(?:pnpm|yarn)(?:\s+exec)?\s+|npx\s+)?(?:semantic-release|changeset\s+publish|lerna\s+publish))(?:\s|$)`, "u");
-/**
-* The variables a token for the registry is passed in.
-*/
-const TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 const PROVENANCE_FLAG = /--provenance(?:=true)?(?:\s|$)/u;
 /**
 * Whether the `package.json` in the working directory asks for provenance with `publishConfig.provenance: true`, which applies to every publish of that package.
@@ -2549,7 +2558,7 @@ function attestationViolations(workflow, job) {
 * Whether the job passes a registry token to a step, which makes its publish not tokenless: a token variable with a value other than the empty string, anywhere in the environment.
 */
 function passesToken(workflow, job) {
-	return [void 0, ...job.steps].some((step) => TOKEN_VARIABLES.some((variable) => (effectiveEnv(workflow, job, step)[variable] ?? "") !== ""));
+	return [void 0, ...job.steps].some((step) => REGISTRY_TOKEN_VARIABLES.some((variable) => (effectiveEnv(workflow, job, step)[variable] ?? "") !== ""));
 }
 function tokenlessPublishViolations(workflow, job, provenanceInManifest) {
 	if (accessOf(effectivePermissions(workflow, job), "id-token") !== "write" || passesToken(workflow, job)) return [];
@@ -2557,9 +2566,9 @@ function tokenlessPublishViolations(workflow, job, provenanceInManifest) {
 		const publishes = scriptCommands(step.run).filter((line) => PUBLISH_COMMAND.test(line));
 		if (publishes.length === 0) return [];
 		const env = effectiveEnv(workflow, job, step);
-		const blanked = TOKEN_VARIABLES.every((variable) => env[variable] === "");
+		const blanked = REGISTRY_TOKEN_VARIABLES.every((variable) => env[variable] === "");
 		const provenance = provenanceInManifest || publishes.some((line) => PROVENANCE_FLAG.test(line)) || env["NPM_CONFIG_PROVENANCE"] === "true";
-		return blanked || provenance ? [] : [workflowViolation(workflow, "workflow-credentials/tokenless-publish-unprotected", `job '${job.id}' publishes with an OIDC identity and no token, but does not set ${TOKEN_VARIABLES.join(" and ")} to the empty string, so a token inherited from the environment is used when the OIDC exchange fails; set them to the empty string to prevent that, or request provenance so that such a publish at least carries a traceable attestation`, step.location)];
+		return blanked || provenance ? [] : [workflowViolation(workflow, "workflow-credentials/tokenless-publish-unprotected", `job '${job.id}' publishes with an OIDC identity and no token, but does not set ${REGISTRY_TOKEN_VARIABLES.join(" and ")} to the empty string, so a token inherited from the environment is used when the OIDC exchange fails; set them to the empty string to prevent that, or request provenance so that such a publish at least carries a traceable attestation`, step.location)];
 	});
 }
 /**
@@ -2577,7 +2586,6 @@ const workflowCredentials = async ({ cwd, options }) => {
 };
 //#endregion
 //#region src/checks/workflow-job-ordering.ts
-const DEFAULT_RELEASE_JOBS = ["release"];
 const DEFAULT_DEPLOY_JOBS = ["deploy"];
 const DEFAULT_DOCS_DEPLOY_JOBS = ["docs-deploy"];
 const DEFAULT_BRANCH = "main";
@@ -2725,6 +2733,71 @@ const workflowMergeGroup = async ({ cwd, options }) => (await loadWorkflows(cwd,
 	return location === void 0 || workflow.triggers.has("merge_group") ? [] : [workflowViolation(workflow, "workflow-merge-group/missing-trigger", "the workflow runs for pull requests but has no merge_group trigger, so its checks do not report for a pull request in the merge queue", location)];
 });
 //#endregion
+//#region src/checks/workflow-release-job.ts
+const CHECKOUT_ACTION$1 = "actions/checkout";
+/**
+* A value that reads the `secrets` context inside an expression.
+*/
+const FROM_SECRET = /\$\{\{[^}]*\bsecrets\./u;
+/**
+* The release jobs named for a message: `release job 'a'` or `release jobs 'a' and 'b'`.
+*/
+function releaseJobsText(releases) {
+	const ids = releases.map((job) => `'${job.id}'`);
+	return `release job${ids.length === 1 ? "" : "s"} ${ids.join(" and ")}`;
+}
+function grantsIdToken(permissions) {
+	return accessOf(permissions, "id-token") === "write";
+}
+function idTokenViolations(workflow, releases) {
+	const releaseIds = new Set(releases.map((job) => job.id));
+	const named = releaseJobsText(releases);
+	const workflowLevel = grantsIdToken(workflow.permissions) && workflow.permissionsLocation !== void 0 ? [workflowViolation(workflow, "workflow-release-job/id-token-workflow-level", `the workflow's permissions grant id-token: write to every job that declares none of its own; grant it on ${named} only`, workflow.permissionsLocation)] : [];
+	const jobLevel = workflow.jobs.filter((job) => !releaseIds.has(job.id) && grantsIdToken(job.permissions)).map((job) => workflowViolation(workflow, "workflow-release-job/id-token-outside-release", `job '${job.id}' is granted id-token: write but is not a release job, so it can mint the OIDC identity npm trusted publishing accepts for this workflow; only ${named} may hold it`, job.location));
+	return [...workflowLevel, ...jobLevel];
+}
+/**
+* What a checkout that does not set `persist-credentials: false` leaves in git config.
+*/
+function persistedCredential(step) {
+	if (step.with["ssh-key"] !== void 0) return "the SSH key";
+	return step.with["token"] === void 0 ? "the job token" : "the token it was given";
+}
+function releaseJobViolations(workflow, job) {
+	if (job.uses !== void 0) return [];
+	const environment = job.environment === void 0 ? [workflowViolation(workflow, "workflow-release-job/missing-environment", `release job '${job.id}' declares no environment, so nothing outside the workflow file stops a branch's copy of it publishing; run it in a protected environment restricted to the default branch`, job.location)] : [];
+	const checkouts = job.steps.filter((step) => stepUses(step, CHECKOUT_ACTION$1) && step.with["persist-credentials"] !== "false").map((step) => workflowViolation(workflow, "workflow-release-job/persisted-credentials", `release job '${job.id}' checks out without persist-credentials: false, which leaves ${persistedCredential(step)} in git config for every later step`, step.location));
+	return [...environment, ...checkouts];
+}
+/**
+* The token variables an environment sets from a secret.
+*/
+function secretTokens(env) {
+	return REGISTRY_TOKEN_VARIABLES.filter((variable) => FROM_SECRET.test(env[variable] ?? ""));
+}
+function tokenBesideOidcViolations(workflow, job) {
+	if (!grantsIdToken(effectivePermissions(workflow, job))) return [];
+	const report = (variables, location) => variables.length === 0 ? [] : [workflowViolation(workflow, "workflow-release-job/token-beside-oidc", `job '${job.id}' holds id-token: write and passes ${variables.join(" and ")} from a secret, a long-lived npm token beside the OIDC identity; publish through trusted publishing and blank the token variables`, location)];
+	return [...report(secretTokens(effectiveEnv(workflow, job, void 0)), job.location), ...job.steps.flatMap((step) => report(secretTokens(step.env), step.location))];
+}
+/**
+* npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+*
+* In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+*
+* In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+*
+* Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+*/
+const workflowReleaseJob = async ({ cwd, options }) => {
+	return (await loadWorkflows(cwd, options)).flatMap((workflow) => {
+		const releases = jobsNamed(workflow, options.releaseJobs ?? DEFAULT_RELEASE_JOBS);
+		const releaseFindings = releases.length === 0 ? [] : idTokenViolations(workflow, releases);
+		const jobFindings = workflow.jobs.flatMap((job) => [...releases.includes(job) ? releaseJobViolations(workflow, job) : [], ...tokenBesideOidcViolations(workflow, job)]);
+		return [...releaseFindings, ...jobFindings];
+	});
+};
+//#endregion
 //#region src/checks/workflow-repository-dispatch.ts
 const DEFAULT_BRANCHES = ["main", "master"];
 const DEFAULT_BRANCH_EXPRESSION = /\$\{\{\s*github\.event\.repository\.default_branch\s*\}\}/u;
@@ -3301,6 +3374,10 @@ const checks = z.strictObject({
 	}))),
 	"workflow-version-single-source": z.exactOptional(enabled(z.strictObject(selection))),
 	"workflow-credentials": z.exactOptional(enabled(z.strictObject(selection))),
+	"workflow-release-job": z.exactOptional(enabled(z.strictObject({
+		...selection,
+		releaseJobs: z.exactOptional(names)
+	}))),
 	"workflow-repository-dispatch": z.exactOptional(enabled(z.strictObject({
 		...selection,
 		defaultBranches: z.exactOptional(names),
@@ -3594,6 +3671,12 @@ const registry = {
 		select: (checks) => enabledOptions(checks["workflow-credentials"]),
 		check: workflowCredentials
 	}),
+	"workflow-release-job": plain({
+		name: "workflow-release-job",
+		description: "The release job alone holds id-token, runs in an environment and persists no credentials, and no job with id-token passes an npm token secret",
+		select: (checks) => enabledOptions(checks["workflow-release-job"]),
+		check: workflowReleaseJob
+	}),
 	"workflow-repository-dispatch": plain({
 		name: "workflow-repository-dispatch",
 		description: "A repository_dispatch handler does not push to the default branch, auto-merge unguarded, or rely on the default token",
@@ -3845,4 +3928,4 @@ function proveExhaustive(input) {
 	}) };
 }
 //#endregion
-export { ConformanceError, DEFAULT_DERIVED_TYPE_INFERENCES, DEFAULT_INFERENCES, DEFAULT_WORKFLOWS, EXIT_CODES, ExhaustivenessError, PRESET_COMMIT_TYPES, accessOf, aggregateMappers, checkNames, classifyPackages, codecPairs, commandTypes, commitTypes, conformanceSchema, conformanceSection, createGitHubClient, crossSliceRules, cycleRule, deployTools, derivedTypes, dockerfilePackageManager, effectiveEnv, effectivePermissions, eslint, generators, handlerCases, importCrossSlice, importCycles, importIsolatedGroups, importRankSkip, importUphill, instructionSymlinks, isCheckName, isolatedGroupRules, loadWorkflows, migrationsDirectory, packagesPattern, parseUses, parseWorkflow, proveExhaustive, rankSkipRules, registry, removeCase, runChecks, settingsMergeMethods, settingsRequiredChecks, settingsReviewThreadResolution, singleStorybook, transitiveNeeds, typeErrors, uphillRules, workflowActionPinning, workflowCredentials, workflowJobOrdering, workflowMergeGroup, workflowRepositoryDispatch, workflowRunnerResolution, workflowSkippableJobs, workflowUpdateBotCooldown, workflowVersionSingleSource };
+export { ConformanceError, DEFAULT_DERIVED_TYPE_INFERENCES, DEFAULT_INFERENCES, DEFAULT_WORKFLOWS, EXIT_CODES, ExhaustivenessError, PRESET_COMMIT_TYPES, accessOf, aggregateMappers, checkNames, classifyPackages, codecPairs, commandTypes, commitTypes, conformanceSchema, conformanceSection, createGitHubClient, crossSliceRules, cycleRule, deployTools, derivedTypes, dockerfilePackageManager, effectiveEnv, effectivePermissions, eslint, generators, handlerCases, importCrossSlice, importCycles, importIsolatedGroups, importRankSkip, importUphill, instructionSymlinks, isCheckName, isolatedGroupRules, loadWorkflows, migrationsDirectory, packagesPattern, parseUses, parseWorkflow, proveExhaustive, rankSkipRules, registry, removeCase, runChecks, settingsMergeMethods, settingsRequiredChecks, settingsReviewThreadResolution, singleStorybook, transitiveNeeds, typeErrors, uphillRules, workflowActionPinning, workflowCredentials, workflowJobOrdering, workflowMergeGroup, workflowReleaseJob, workflowRepositoryDispatch, workflowRunnerResolution, workflowSkippableJobs, workflowUpdateBotCooldown, workflowVersionSingleSource };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "workspace-conformance",
   "description": "Conformance checks for a pnpm workspace that ESLint cannot express: type-graph, import-graph and cross-file checks driven by the shared layout section of @exadev/config",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "bin": {
     "workspace-conformance": "./dist/cli.js"
   },