Migrate npm publish to Trusted Publishing (OIDC), drop NPM_TOKEN

[stonematt]

Problem

publish.yml authenticates to npm with a long-lived NPM_TOKEN secret. Two costs:

1. It expires. The token created 2026-05-20 expired 2026-08-18 and broke the v2.1.0 release (see publish.yml: notify on failure #101). Every replacement token carries the same fuse.
2. npm is restricting this path. The npm dashboard currently warns: "npm tokens that bypass 2FA are being restricted — account changes (Aug 2026) and direct publishing (Jan 2027)." Our token needs the 2FA-bypass flag set, because CI cannot answer an OTP prompt. That combination is on a deprecation clock.

npm supports Trusted Publishing: GitHub Actions authenticates over OIDC, no stored credential. The workflow is most of the way there already — it has permissions: id-token: write, publishes with --provenance, and uses OIDC for the MCP Registry publish two steps later. The npm step is the odd one out.

Acceptance criteria

• stonematt/mcp-obsidian-cli is registered as a trusted publisher for the mcp-obsidian-cli package on npmjs.com, scoped to publish.yml.
• The Publish to npm step no longer sets NODE_AUTH_TOKEN.
• A real release publishes to npm end to end with no token present.
• Provenance attestation still attaches (the current setup signs to sigstore; do not lose that).
• The NPM_TOKEN secret is deleted from repo secrets only after a successful tokenless release, not before.
• docs/agents/issue-tracker.md release ritual section updated if the steps change.

Notes

Verify the setup against npm's current Trusted Publishing docs before editing the workflow — the feature has moved quickly and details may have shifted.

Sequencing: land #101 first. A failure notification is worth having in place before changing how releases authenticate, so a botched migration announces itself instead of silently dropping another version.

[stonematt]

This was generated by AI during triage.

Human Brief

Category: enhancement
State: ready-for-human — see "Why this isn't delegable" below
Summary: npm publish authenticates over OIDC as a registered trusted publisher, and the stored NPM_TOKEN is retired

Current behavior:
The publish workflow already grants id-token: write at the job level and already authenticates to the MCP Registry over OIDC two steps after the npm publish. The npm step alone still reads a stored credential via NODE_AUTH_TOKEN, sourced from the NPM_TOKEN repository secret. That token expires on a fixed date and sits on npm's 2FA-bypass deprecation clock.

Desired behavior:
The npm publish step carries no credential. npm authenticates the workflow by its OIDC identity against a trusted-publisher configuration registered on the package. The NPM_TOKEN secret no longer exists in repository secrets. Provenance attestation continues to attach.

Why this isn't delegable:
Three of the acceptance criteria require a human at an authenticated npm session:

• Registering the trusted publisher happens in the npmjs.com dashboard under the package's settings, behind your npm login and 2FA. There is a npm trust CLI path, but it is a bulk-configuration tool for applying a config across many packages, not a substitute for the initial setup on a single package.
• "A real release publishes end to end with no token" can only be satisfied by cutting an actual release.
• Deleting the secret is an irreversible credential action whose timing depends on your judgment that the tokenless release genuinely succeeded.

The workflow YAML edit in the middle is small and mechanical, but it is worthless before the npm-side registration exists, so it is not worth splitting out.

Sequencing:
Land #101 first, as the issue notes. If this migration goes wrong, the failure notification from #101 is the thing that tells you — otherwise a botched release fails the same silent way v2.1.0 did.

Implementation notes — verified against current docs, 2026-09-08:

These were researched during triage because the feature has moved since its 2025 launch. Two of them will break the migration if missed.

1. npm CLI version is a hard blocker. Trusted publishing requires npm 11.5.1 or newer. actions/setup-node@v5 at Node 22 currently ships npm in the 10.9.x range — below the floor. The workflow needs an explicit npm upgrade step after setup-node before the publish step. (docs.npmjs.com/trusted-publishers)

2. Staged publishing became the default on 2026-09-03, four days before this issue was filed. Trusted-publisher configurations now default to npm stage publish, with direct npm publish available only as an explicit per-config opt-in, and staged releases gate on a malware scan before approval. Decide which model you want before registering, because it is a field on the configuration. If you accept the staged default, the release ritual gains an approval step and the docs/agents/issue-tracker.md update in the acceptance criteria becomes mandatory rather than conditional. (GitHub changelog, 2026-09-03)

3. The registry-url interaction is a live risk, not a settled fact. actions/setup-node's registry-url input writes //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN} into .npmrc. Community reports hold that with NODE_AUTH_TOKEN unset — the intended OIDC state — npm sees an auth line present, skips the OIDC exchange, and fails with ENEEDAUTH or a 404. npm's own documented example still shows registry-url set, so the docs and the field reports disagree. Circulating workarounds are to strip that line from .npmrc after setup-node runs, or to drop registry-url and set the registry in .npmrc or package.json instead. Treat this as the most likely failure point of the first tokenless run; confirm against actions/setup-node issue #1551 and npm/documentation issue #1960 at implementation time.

4. --provenance is no longer needed. Provenance is automatic under trusted publishing; the opt-out is NPM_CONFIG_PROVENANCE=false. Dropping the flag does not lose the sigstore attestation. (GitHub changelog, 2025-07-31)

5. Enabling trusted publishing does not disable token publishing. They coexist until you separately toggle "require two-factor authentication and disallow tokens" on the package. This is what makes the acceptance criteria's ordering safe: the token keeps working as a fallback right up until you delete it.

6. Registration fields, for the dashboard: organization or user, repository, workflow filename — the bare filename, not a path — and optionally an environment name and an allowed-actions restriction. The environment is optional; this repo's publish workflow does not currently use one.

7. Deprecation timing, for context on urgency: bypass-2FA granular tokens lost account, org, and package-management operations on 2026-07-31, and lose direct publish access in January 2027. (GitHub changelog, 2026-07-31)

Acceptance criteria:

• stonematt/mcp-obsidian-cli is registered as a trusted publisher for the mcp-obsidian-cli package on npmjs.com, scoped to the publish workflow's filename.
• A decision is recorded on whether the configuration uses staged or direct publishing, and the workflow matches it.
• The npm publish step no longer sets NODE_AUTH_TOKEN.
• The workflow ensures npm 11.5.1 or newer is in use before publishing.
• A real release publishes to npm end to end with no token present.
• Provenance attestation still attaches to the published version.
• The NPM_TOKEN secret is deleted from repository secrets only after a successful tokenless release.
• docs/agents/issue-tracker.md's release ritual section reflects any change to the steps, including an approval step if staged publishing is adopted.

Out of scope:

• The MCP Registry publish step, which already authenticates over OIDC and needs no change.
• Failure notification for the publish workflow — that is publish.yml: notify on failure #101, and this issue depends on it rather than duplicating it.
• Changing when the git tag is pushed relative to the publish steps.
• Enabling the package-level "disallow tokens" toggle. That is a separate hardening decision, worth making after this lands rather than during it.