fix(release): publish through existing OIDC workflow before tag

Author: Ralph Küpper

.github/workflows/npm-stage-publish.yml

@@ -0,0 +1,8 @@
+## Release engineering
+
+- Publish all nine npm artifacts directly from GitHub Actions through npm
+  Trusted Publisher/OIDC. The release path no longer needs an npm login, npm
+  token, staged-package approval, or a local Socket credential.
+- Pack once in the existing `release-packages.yml` workflow, optionally
+  Socket-scan those exact tarballs, publish the same bytes, and verify their public
+  registry shasums before creating the version tag and GitHub Release last.

.github/workflows/release-packages.yml

@@ -8,9 +8,9 @@ release gate.
 ## 1. Pre-release checklist (every release)
 
 Start from a clean checkout that contains current `origin/main`. Do not release
-from a detached HEAD or from a moving `main` branch. The staged pipeline records
-the candidate branch, commit SHA, and build run, then refuses to approve or tag
-if any of them changes.
+from a detached HEAD or from a moving `main` branch. The npm-first pipeline
+pins the candidate branch and commit SHA, retains the exact npm tarballs, and
+refuses to tag if the branch moves or any public registry shasum differs.
 
 ```bash
 # Confirm the checkout is current and clean.
@@ -61,27 +61,31 @@ gh workflow run test.yml --ref "release/v$VERSION" -f tier=full
 gh workflow run simctl-tests.yml --ref "release/v$VERSION"
 ```
 
-Then use the staged pipeline:
-
-The local publish/approve process requires npm 11.17 or newer and a valid
-`SOCKET_API_TOKEN` for the mandatory tarball scan. CI uses OIDC for staging;
-do not set a long-lived npm publish token. The local npm account must be a
-maintainer of all nine packages because it lists and approves their staged
-entries.
-
-```bash
-npm --version                 # must be >= 11.17.0
-# If needed: npm install -g npm@latest
-npm whoami                    # must succeed as an @perryts package maintainer
-```
-
-One-time GitHub setup: create the environment named in the OIDC identity and
-store the Socket credential at environment scope (the secret value is entered
-interactively and must never be committed):
+Freeze that candidate SHA. Unrelated merges to `main` after the branch is cut do
+not invalidate successful gates and do not require another test cycle. Refresh
+the candidate only for a release-blocking fix or a required version change.
+
+Then use the npm-first pipeline. npm publication happens only in GitHub Actions
+through Trusted Publisher/OIDC. There is no `npm login`, npm account session,
+2FA approval, or long-lived npm token in CI or on the maintainer machine. The
+local command uses GitHub authentication to dispatch/watch the workflow and
+anonymous registry reads to verify the published bytes.
+
+Socket is an optional pre-publish tarball scan, not an npm credential. When
+enabled, Actions submits each of the exact nine `.tgz` files as a temporary
+Socket full scan and evaluates the results against the `perryts` Socket
+organization's security policy. Policy actions configured as `error` block
+publication; `warn` findings are recorded but do not block. The same tarballs
+that pass are then sent to npm. For the current release, omit `--socket-scan`;
+the workflow records an explicit skipped receipt and continues.
+
+To enable the gate later, store `SOCKET_API_TOKEN` as a repository or
+organization Actions secret with permission to create/read full scans, read the
+organization policy, and read quota. No GitHub Environment is required. The
+value stays only in GitHub and must never be committed or exported locally:
 
 ```bash
-gh api --method PUT repos/PerryTS/perry/environments/npm-publish
-gh secret set SOCKET_API_TOKEN --repo PerryTS/perry --env npm-publish
+gh secret set SOCKET_API_TOKEN --repo PerryTS/perry
 ```
 
 Before the first nine-package release, an npm organization owner must confirm
@@ -90,51 +94,51 @@ Trusted Publisher configuration:
 
 - provider: GitHub Actions
 - organization/repository: `PerryTS/perry`
-- workflow filename: `npm-stage-publish.yml`
-- environment: `npm-publish`
-- allowed action: **`npm stage publish`**
+- workflow filename: `release-packages.yml`
+- environment: none
+- allowed action: **`npm publish`**
 
-npm permits only one trusted publisher per package. Configurations created
-before May 20, 2026 were carried forward with only direct **`npm publish`**
-allowed, so edit every existing package and explicitly enable
-**`npm stage publish`**; merely seeing a trusted publisher entry is not enough.
-The old `release-packages.yml` direct-publish path cannot occupy a second
-trusted-publisher slot and is not part of the canonical release.
+npm permits only one trusted publisher per package. The canonical identity is
+the existing `release-packages.yml` workflow above, with direct **`npm
+publish`** enabled. Do not configure `npm-stage-publish.yml` as a second
+publisher and do not add an environment name that the other packages do not
+use.
 
 In particular, verify the ARM64 Windows package:
 
 ```bash
 npm view @perryts/perry-win32-arm64 name
 ```
 
-If that returns `E404`, an `@perryts` npm owner must make the initial public
-name-reservation publish (the repository permits version `0.0.0` only for this
-bootstrap), then configure the same Trusted Publisher fields above. The
-pipeline intentionally refuses a partial set.
+If that returns `E404`, stop: npm does not allow a Trusted Publisher to be
+configured for a package that does not exist, so OIDC cannot perform its first
+publish. An `@perryts` owner must provision that package name once before this
+nine-package OIDC-only flow can work, then configure the Trusted Publisher
+fields above. The release pipeline intentionally refuses a partial set.
 
 ```bash
-npm run publish:stage       # CI builds all platforms, stages 9 npm packages,
-                            # verifies sha1, runs the mandatory Socket scan,
-                            # and downloads the exact proof tarballs locally
-npm run publish:status      # inspect the commit/run/package receipt
-npm run publish:approve     # explicit 2FA promote; waits for registry liveness
-                            # and only then creates v0.x.y + the GitHub Release
+npm run publish:release     # one Release Packages run: exact-SHA gates/builds,
+                            # publish + verify all 9 via OIDC, then create
+                            # v0.x.y + the GitHub Release last
+# Later, once the repository/org Socket secret exists:
+npm run publish:release -- --socket-scan
+npm run publish:status      # inspect the commit/run/package/Socket receipt
 ```
 
-Approval promotes nine packages sequentially. If 2FA or the network interrupts
-that loop after some packages are already public, re-run `publish:approve` with
-the same retained CI proof. It resumes only when each already-public package's
-immutable registry shasum matches the exact CI tarball; otherwise use a new
-version. Do not discard the proof directory until the tag and release exist.
+Publication sends the eight platform packages first and the wrapper last. If a
+network or registry error interrupts it before the tag exists, rerun the failed
+jobs (or `publish:release`) on the same candidate. Actions skips an
+already-public package only when its immutable registry shasum matches the exact
+CI tarball; otherwise it stops and requires a new version.
 
 If the accumulated changelog fragments exceed the inline release-note budget,
 the publisher keeps the GitHub Release body concise and uploads the complete
 notes as the checksummed `release-notes-full.md` asset. No fragment is dropped.
 
-Do not run `git tag`, manually publish a GitHub Release, or use the legacy
-`release-packages.yml cut_release=true` route for a normal release. That older
-route creates the tag before npm publication; it does not satisfy the stricter
-registry-first/tag-last contract.
+Do not run `npm login`, `git tag`, or manually publish a GitHub Release. The
+local command dispatches `release-packages.yml` with `cut_release=true`; that
+workflow creates the tag only after all nine npm versions are public and their
+registry shasums match the exact CI tarballs.
 
 ## 2. Additional major-release verification
 
@@ -212,17 +216,17 @@ Artifacts are published to:
 4. **winget** — manifest auto-update
 5. **hub.perryts.com** — worker notification so cloud build workers refresh
 
-In the canonical staged flow, any failing host or cross build prevents all npm
-staging, so no partial package set is promoted. Once a version has become public,
-fix-forward with a new patch version rather than amending an existing tag.
+In the canonical npm-first flow, any failing host or cross build prevents npm
+publication. The wrapper is not published when a platform package fails. Once a
+version has become public, fix-forward with a new patch version rather than
+amending an existing tag.
 
 ## 4. Release gates (what blocks a release)
 
-`npm-stage-publish.yml` rejects a real stage unless `test.yml` has a successful
+`release-packages.yml` rejects a cut release unless `test.yml` has a successful
 **`full-suite-gate`** and `simctl-tests.yml` has a successful run on the exact
-candidate SHA. A green PR-tier or push-to-main sweep does *not* count. The same
-two gates are enforced by `release-packages.yml`'s legacy release path. See
-[CI tiers](../testing/ci-tiers.md). The full tier is:
+candidate SHA. A green PR-tier or push-to-main sweep does *not* count. See [CI
+tiers](../testing/ci-tiers.md). The full tier is:
 
 - everything the PR gate and the post-merge sweep run (`lint`, `check`, `warnings`,
   `cargo test --workspace`, the gap suite, `gc-stress`, Windows x64 + ARM64 builds,
@@ -247,11 +251,12 @@ candidate's fault, fix it on `main` first (or open an issue and consciously
 re-add a job-level `continue-on-error: true` with that issue number) — do not
 publish past it.
 
-The staging workflow then requires every host/cross package build, all nine npm
-stages, sha1 verification, and the Socket scan. `benchmark.yml`, docs, container
-tests, Homebrew, APT, winget, and worker refresh are tag riders or distribution
-steps: monitor them after the GitHub Release is created, but do not mistake them
-for pre-tag gates.
+The release workflow then requires every host/cross package build, all nine
+exact npm publishes, and public-registry sha1 verification. Socket is an
+optional pre-publish gate and is currently skipped. `benchmark.yml`, docs,
+container tests, Homebrew, APT, winget, and worker refresh are tag riders or
+distribution steps: monitor them after the GitHub Release is created, but do
+not mistake them for pre-tag gates.
 
 ## 4a. What tells you a release is overdue
 
@@ -290,9 +295,9 @@ a release has been cut is not something a PR author can fix.
 
 - **Wrong artifact published**: tag a new patch release with the fix; npm
   rejects re-publishes of the same version anyway.
-- **Broken build before approval**: fix it and stage the complete nine-package
-  set again; the canonical flow will not promote a partial set.
-- **Broken binary discovered after approval**: ship a follow-up patch version;
+- **Broken build before npm publication**: fix it and rebuild the complete
+  nine-package set; the canonical flow will not tag a partial set.
+- **Broken binary discovered after publication**: ship a follow-up patch version;
   neither npm versions nor release tags are mutable.
 - **A post-tag distribution hook failed**: re-run the failed workflow. To retry
   the legacy release-packages distribution legs, dispatch it with

changelog.d/8791-npm-oidc-only-release.md

@@ -8,12 +8,8 @@
     "tools:fix": "node scripts/soak/external-tools.mts --fix",
     "tools:install": "node scripts/soak/external-tools.mts --install-all --shims",
     "test:scripts": "node --test scripts/soak/*.test.mts scripts/publish/*.test.mts",
-    "publish:pipeline": "node scripts/publish/pipeline.mts",
-    "publish:stage": "node scripts/publish/pipeline.mts --stage-only",
-    "publish:scan": "node scripts/publish/pipeline.mts --scan-only",
-    "publish:approve": "node scripts/publish/pipeline.mts --approve",
+    "publish:release": "node scripts/publish/pipeline.mts --publish",
     "publish:status": "node scripts/publish/pipeline.mts --status",
-    "publish:release": "node scripts/publish/pipeline.mts --release-only",
     "publish:brew": "node scripts/publish/brew/tap-publish.mts",
     "publish:ffi": "node scripts/publish/cargo/ffi-publish.mts",
     "prepublishOnly": "node scripts/publish/auth-posture.mts --guard"

docs/src/contributing/releasing.md

@@ -174,18 +174,6 @@ def _workflow_pins(text: str) -> list[str]:
         ),
         locator=_workflow_pins,
     ),
-    Exemption(
-        path=".github/workflows/npm-stage-publish.yml",
-        value="26",
-        major_tracks_oracle=True,
-        reason=(
-            "npm *publishing* toolchain (OIDC staged-upload + npm stage "
-            "publishing), never a test oracle. Major literal for the same "
-            "reason as release-packages.yml -- a gap-suite oracle bump must "
-            "not move the runtime that publishes releases."
-        ),
-        locator=_workflow_pins,
-    ),
     Exemption(
         path="benchmarks/public-baseline-config.json",
         value="v22.23.1",

package.json

@@ -1,27 +1,22 @@
 /**
  * @file Auth-posture gate, modeled on a tiered registry-infra design
- *   Perry's publish is OIDC-in-CI (the npm-stage-publish
- *   workflow, id-token: write) + browser web-OTP 2FA locally (npm stage
- *   approve). A long-lived npm token present during a publish is a DEFECT,
- *   not a convenience — it bypasses provenance and outlives the release.
+ *   Perry's npm publication runs only in release-packages.yml with GitHub
+ *   OIDC (`id-token: write`). There is no local npm login/approval path. A
+ *   long-lived npm token present during a publish is a DEFECT, not a
+ *   convenience — it bypasses provenance and outlives the release.
  *
  *   - PREFLIGHT: refuse BEFORE any upload if a long-lived token is present in
  *     CI (where OIDC is the only sanctioned path).
  *   - POSTFLIGHT: scan command output for a failed OIDC exchange that
  *     "succeeded" anyway (ERR_PNPM_AUTH_TOKEN_EXCHANGE / Skipped OIDC) — a
  *     publish that landed after a broken exchange is treated as a failure.
  *
- *   The read-only token (PERRY_NPM_READONLY_TOKEN) is permitted everywhere —
- *   it powers registry reads (npm view, staged-download) and can never
- *   publish.
+ *   Public registry verification uses anonymous `npm view` reads.
  */
 
 import process from 'node:process'
 
-import {
-  LONG_LIVED_NPM_TOKEN_ENV_VARS,
-  READONLY_TOKEN_ENV,
-} from './constants.mts'
+import { LONG_LIVED_NPM_TOKEN_ENV_VARS } from './constants.mts'
 
 /** True when running inside GitHub Actions (the OIDC-sanctioned channel). */
 export function isCI(): boolean {
@@ -37,15 +32,9 @@ export const OIDC_FAILURE_MARKERS = [
 
 /**
  * Preflight: refuse before an upload if a long-lived publish token is present.
- * In CI, OIDC is the only sanctioned path. Locally, a direct publish is
- * permitted only for the 0.0.0 name reservation (escape hatch) — real
- * releases stage in CI and approve locally with 2FA. A direct publish of any
- * OTHER version with a long-lived token present is refused, so the escape
- * hatch cannot be widened into a general bypass.
- *
- * Pass `version` (the manifest version being published) so the reservation
- * can be enforced; without it, a direct upload with a long-lived token is
- * refused (fail-closed — the caller must prove it is the reservation).
+ * In CI, OIDC is the only sanctioned path. Local npm writes are never
+ * sanctioned, including package-name reservation; provisioning a missing npm
+ * package is an external organization-owner prerequisite, not a release path.
  *
  * Returns a non-empty string reason when the posture is refused, or undefined
  * when it is clean.
@@ -70,22 +59,16 @@ export function publishAuthPreflight(config: {
   }
   if (!direct) {
     return (
-      `Refusing to stage with a long-lived token present: ${present.join(', ')}. ` +
-      'Staging runs in CI under OIDC; locally only the 2FA approve is sanctioned. ' +
-      'Unset the token and dispatch the stage workflow instead.'
+      `Refusing to dispatch with a long-lived token present: ${present.join(', ')}. ` +
+      'npm publication runs in GitHub Actions under OIDC. ' +
+      'Unset the token and dispatch the release workflow instead.'
     )
   }
-  // direct local publish with a long-lived token: permitted ONLY for the 0.0.0
-  // name reservation escape hatch. Any other version (or an unknown version)
-  // is refused — the escape hatch must not become a general bypass.
-  if (version !== '0.0.0') {
-    return (
-      `Refusing a direct publish with a long-lived token present: ${present.join(', ')}. ` +
-      `The direct escape hatch is reserved for the 0.0.0 name reservation only (got version ${version ?? '<unknown>'}). ` +
-      'Real releases stage in CI under OIDC and approve locally with 2FA — unset the token and dispatch the stage workflow.'
-    )
-  }
-  return undefined
+  return (
+    `Refusing a local direct publish with a long-lived token present: ${present.join(', ')}. ` +
+    `Local npm writes are not sanctioned (requested version ${version ?? '<unknown>'}); ` +
+    'real releases publish in GitHub Actions under OIDC.'
+  )
 }
 
 /**
@@ -99,7 +82,7 @@ export function publishAuthPostflight(output: string): boolean {
 /**
  * The prepublishOnly guard entrypoint. Refuses any `npm publish` / `npm
  * publish` run that carries a long-lived token, and reminds the operator to
- * use the staged pipeline instead.
+ * use the Actions OIDC pipeline instead.
  */
 export function prepublishOnlyGuard(): number {
   const reason = publishAuthPreflight({
@@ -115,7 +98,7 @@ export function prepublishOnlyGuard(): number {
     return 1
   }
   console.error(
-    "ERROR: use `npm run publish:pipeline` (staged) — direct publish is not the sanctioned path.",
+    "ERROR: use `npm run publish:release` — npm publication is only sanctioned in GitHub Actions with OIDC.",
   )
   return 1
 }

scripts/check_node_version_consistency.py

@@ -0,0 +1,15 @@
+/** Shared shape for the exact npm tarballs packed, scanned, and published in CI. */
+
+export const CI_PACKAGE_MANIFEST = 'npm-publish-manifest.json'
+
+export interface CiPackageProof {
+  name: string
+  version: string
+  path: string
+  sha1: string
+}
+
+export interface CiPackageManifest {
+  packages: CiPackageProof[]
+  version: string
+}