From de75f4b3729a5fce6b0e40a33166ba3f31ac194c Mon Sep 17 00:00:00 2001 From: "open-swe[bot]" Date: Sat, 8 Aug 2026 21:27:29 -0400 Subject: [PATCH 1/2] docs(release): OIDC dist-tag scope is now VERIFIED, not speculated MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I overcorrected. An earlier revision called the "OIDC authorizes npm publish but not npm dist-tag add" explanation *wrong*; it is not. npm's own documentation is explicit: "OIDC authentication supports the `npm publish` and `npm stage publish` commands." ... "Other npm commands such as `install`, `view`, or `access` still require traditional authentication methods." — docs.npmjs.com/trusted-publishers The trusted-publisher config states the same in its own field: Allowed = npm publish. So the alignment step MUST use token auth; there is no token-free path and will not be one until npm extends OIDC scope. Two independent facts had been conflated, and I flipped which one was wrong instead of separating them: 1. OIDC cannot move a dist-tag — true, and now cited. 2. The recurring 401s were a wiring bug (bare NPM_TOKEN env var) — also true, and the operative cause of what people kept chasing. Both held simultaneously. The original doc was right about WHY a token is needed and silent about the bug in HOW it was supplied. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d781c99f83..6b64343b3d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -108,9 +108,13 @@ npm's trusted publisher (npmjs.com → package Settings) must match this file ex `Org=nForma-AI · Repo=nForma · Workflow filename=publish.yml · Environment=npm-publish · Allowed=npm publish`. Requirements baked into the workflow: Node ≥ 22.14.0 and npm ≥ 11.5.1 (`npm i -g npm@latest`), `permissions: id-token: write`, **no** `NODE_AUTH_TOKEN` (its presence forces the token path and defeats OIDC). -**Aligning `@next` — current state (2026-08-08).** The long-standing explanation ("OIDC authorizes `npm publish` but not `npm dist-tag add`") is **incomplete, and was not the operative cause** of the drift everyone kept chasing. It may well be true — it has never been tested here, because the step never got far enough to find out. What was actually happening, in order: +**Aligning `@next` — current state (2026-08-08).** Two independent facts, long conflated: -1. **Wiring bug (fixed, #391).** The align step exported `NPM_TOKEN` as a bare `env:` var. npm does not read `NPM_TOKEN` — auth comes from `.npmrc` — so `dist-tag add` ran *unauthenticated* and 401'd every release, while the warning text blamed a token that was configured and healthy. The step now writes `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` for its own duration (safe: it runs after the OIDC publish, so it cannot force publish onto the token path). Whether OIDC alone would suffice is still unverified — the step uses a token, so the question stays open and costs nothing. +**Fact 1 — OIDC genuinely cannot move a dist-tag. VERIFIED against npm's docs, not inferred.** docs.npmjs.com/trusted-publishers states *"OIDC authentication supports the `npm publish` and `npm stage publish` commands"* and *"Other npm commands such as `install`, `view`, or `access` still require traditional authentication methods."* The trusted-publisher config says the same in its own field: `Allowed = npm publish`. So the alignment step **must** use token auth — there is no token-free path, and there will not be one until npm extends OIDC scope. (An earlier revision of this file called that explanation "wrong". It was not: it was right about *why* a token is needed, and merely silent about the bug in *how* the token was supplied.) + +**Fact 2 — the drift everyone kept chasing was a wiring bug, not the OIDC limit.** In order: + +1. **Wiring bug (fixed, #391).** The align step exported `NPM_TOKEN` as a bare `env:` var. npm does not read `NPM_TOKEN` — auth comes from `.npmrc` — so `dist-tag add` ran *unauthenticated* and 401'd every release, while the warning text blamed a token that was configured and healthy. The step now writes `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` for its own duration (safe: it runs after the OIDC publish, so it cannot force publish onto the token path). 2. **The `NPM_TOKEN` secret is currently expired** (created 2026-02-21; CI returns `E401 — authentication token seems to be invalid`). Until it is replaced, **alignment is a manual step after every release** — an accepted trade-off, not an unknown. **Manual alignment.** Run it yourself in an interactive terminal: From f424debe3513eab98aa14c898ab8be50b909db68 Mon Sep 17 00:00:00 2001 From: "open-swe[bot]" Date: Sun, 9 Aug 2026 08:01:28 -0400 Subject: [PATCH 2/2] docs: link the npm source and drop an unsupported prediction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review catch, both parts fair. The paragraph cited docs.npmjs.com textually with no clickable link, and asserted "there will not be one until npm extends OIDC scope" — a forward-looking absolute the cited docs say nothing about. Now a real link, and the claim is scoped to 'as of this writing' with an instruction to re-check. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6b64343b3d..c4e888c23d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,7 +110,7 @@ Requirements baked into the workflow: Node ≥ 22.14.0 and npm ≥ 11.5.1 (`npm **Aligning `@next` — current state (2026-08-08).** Two independent facts, long conflated: -**Fact 1 — OIDC genuinely cannot move a dist-tag. VERIFIED against npm's docs, not inferred.** docs.npmjs.com/trusted-publishers states *"OIDC authentication supports the `npm publish` and `npm stage publish` commands"* and *"Other npm commands such as `install`, `view`, or `access` still require traditional authentication methods."* The trusted-publisher config says the same in its own field: `Allowed = npm publish`. So the alignment step **must** use token auth — there is no token-free path, and there will not be one until npm extends OIDC scope. (An earlier revision of this file called that explanation "wrong". It was not: it was right about *why* a token is needed, and merely silent about the bug in *how* the token was supplied.) +**Fact 1 — OIDC does not cover `npm dist-tag`.** Per [npm's trusted-publishers docs](https://docs.npmjs.com/trusted-publishers): *"OIDC authentication supports the `npm publish` and `npm stage publish` commands"*, and *"Other npm commands such as `install`, `view`, or `access` still require traditional authentication methods."* The trusted-publisher config states the same scope in its own field: `Allowed = npm publish`. So the alignment step must use token auth **as of this writing** — re-check the docs before assuming that still holds, since npm may extend OIDC scope. (An earlier revision of this file called that explanation "wrong". It was not: it was right about *why* a token is needed, and merely silent about the bug in *how* the token was supplied.) **Fact 2 — the drift everyone kept chasing was a wiring bug, not the OIDC limit.** In order: