ci: Use OIDC for npm publish

.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Release
+
+# Single entry point for every path that publishes to npm. npm allows one trusted
+# publisher per package and validates the entry-point workflow filename, so `cut`,
+# `next` and `publish-final` all have to run from this file.
+on:
+  push:
+    branches:
+      - master
+  schedule:
+    - cron: '28 21 20 * *' # run at minute 28 to avoid the chance of delay due to high load on GH
+  workflow_dispatch:
+    inputs:
+      name:
+        type: choice
+        description: Release type
+        default: next
+        required: true
+        options:
+          - next
+          - patch
+          - cut
+      base-ref:
+        description: Base version
+        default: develop
+        required: false
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+env:
+  HUSKY: 0
+
+permissions: {}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # npm trusted publishing (OIDC)
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event_name == 'schedule' && github.ref_name || github.event_name == 'workflow_dispatch' && inputs.base-ref || '' }}
+          fetch-depth: 0
+          token: ${{ secrets.CI_PAT }}
+
+      - name: Setup NodeJS
+        uses: ./.github/actions/setup-node
+        with:
+          cache-modules: true
+          install: true
+          # Transitional: npm attempts the OIDC exchange first and overrides this token on
+          # success, so it only takes effect when the exchange fails. That keeps releases
+          # alive while packages are registered as trusted publishers one by one. Remove
+          # once every package reports a non-null dist.attestations — see docs/npm-publishing.md.
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Node 22 bundles npm 10, trusted publishing needs >= 11.5.1
+      - name: Setup npm
+        run: |
+          npm install -g npm@^11.15.0
+          npm --version
+
+      - uses: rharkor/caching-for-turbo@2238fae6eb9a9936f92356f54cb3660200d105e7 # v2.5.1
+
+      - name: Build packages
+        run: yarn build
+
+      - name: Release
+        uses: ./packages/release-action
+        with:
+          action: ${{ github.event_name == 'push' && 'publish-final' || github.event_name == 'schedule' && 'next' || inputs.name }}
+          base-ref: ${{ github.event_name == 'schedule' && github.ref_name || github.event_name == 'workflow_dispatch' && inputs.base-ref || '' }}
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }} # transitional, see the Setup NodeJS step
+          GITHUB_TOKEN: ${{ secrets.CI_PAT }}

CLAUDE.md

@@ -33,6 +33,7 @@ Read the doc that matches the task instead of scanning `docs/` wholesale.
 
 - [docs/meteor-modern-stack.md](docs/meteor-modern-stack.md) — Meteor modern build stack, file-watching caveats
 - [docs/coverage.md](docs/coverage.md) — coverage instrumentation in build and CI
+- [docs/npm-publishing.md](docs/npm-publishing.md) — how the public packages reach npm: `release.yml`, changesets, OIDC trusted publishing, provenance
 
 ### Other
 

docs/npm-publishing.md

@@ -0,0 +1,144 @@
+# npm publishing
+
+The public `@rocket.chat/*` packages under `packages/` are published to npm by
+`.github/workflows/release.yml`, which delegates to the local `packages/release-action`.
+Everything else in the workspace is `private: true` and never published.
+
+## How a publish happens
+
+`release.yml` is the **only** workflow that publishes. It carries three triggers and maps each one
+to a `release-action` mode:
+
+| Trigger                       | `action`        | Publishes? | dist-tag        |
+| ----------------------------- | --------------- | ---------- | --------------- |
+| `push` to `master`            | `publish-final` | yes        | `latest`        |
+| `schedule` (monthly, 20th)    | `next`          | yes        | `rc`            |
+| `workflow_dispatch` → `cut`   | `cut`           | yes        | `latest` / `rc` |
+| `workflow_dispatch` → `next`  | `next`          | yes        | `rc`            |
+| `workflow_dispatch` → `patch` | `patch`         | no         | —               |
+
+`publishRelease.ts` and `bumpNextVersion.ts` both end with `yarn changeset publish --no-git-tag`.
+Changesets then spawns `npm publish <packageDir> --access public --tag <tag>` from the repo root, so
+**the npm CLI on `PATH` is what authenticates** — not yarn.
+
+## Trusted publishing (OIDC)
+
+Publishing authenticates via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+rather than a long-lived token. GitHub Actions mints a short-lived, job-scoped credential at publish
+time, and npm attaches a provenance attestation to every published tarball.
+
+Two hard requirements, both handled in `release.yml`:
+
+- `permissions: id-token: write` on the publishing job — without it the runner never exposes
+  `ACTIONS_ID_TOKEN_REQUEST_URL` and the OIDC exchange cannot happen.
+- **npm >= 11.5.1** (the `Setup npm` step installs it). `engines.node` is 22.x, which bundles npm 10.
+
+### How `NPM_TOKEN` interacts with the exchange
+
+`npm publish` runs the OIDC exchange *before* it reads credentials, and on success it overrides the
+`~/.npmrc` auth line with the freshly minted token. A present `NPM_TOKEN` therefore does **not**
+prevent trusted publishing — the exchange still wins whenever it succeeds.
+
+The token matters only when the exchange fails. npm's `oidc()` is written to never throw: every
+failure path (missing `id-token` permission, package not registered, exchange rejected) returns
+quietly, and `publish` then proceeds with the npmrc token — no provenance, no error, exit code 0.
+
+That makes the token a **migration aid and a hazard at the same time**:
+
+- While packages are being registered one at a time, it keeps releases from hard-failing on the
+  ones that are not registered yet.
+- Once everything is registered, it hides regressions — a broken registration keeps publishing
+  under token auth instead of failing.
+
+So `release.yml` keeps `NPM_TOKEN` only until every package publishes with provenance, then drops
+both references (the `setup-node` input and the `Release` step's `env`).
+
+### Migrating packages incrementally
+
+npm allows one trusted publisher per package, so packages move over one at a time:
+
+1. Register the package (see below). Watch for packages previously released from another repo —
+   `@rocket.chat/emitter`'s last provenance came from `RocketChat/fuselage`'s `cd.yml`, and that
+   registration has to be re-pointed here before this workflow can publish it.
+2. Let a release run. The job log is not evidence — a token fallback looks identical to success.
+3. Confirm with `npm view @rocket.chat/<name> --json dist.attestations`; non-null means the package
+   is publishing through OIDC.
+4. When all published packages are attested, remove `NPM_TOKEN` from `release.yml`.
+
+### Why there is only one release workflow
+
+npm allows **one trusted publisher per package**, and it validates the _entry-point_ workflow
+filename — the `workflow_ref` OIDC claim. `workflow_call` reusable workflows inherit the caller's
+`workflow_ref`, so splitting the publish step into a shared workflow does not help: every caller
+would need its own registration. Hence the single `release.yml` with three triggers.
+
+**Renaming or moving `release.yml` breaks publishing** until every package's trusted publisher is
+updated on npmjs.com.
+
+### Registering a newly published package
+
+npm cannot configure a trusted publisher for a package that does not exist yet, so a brand-new
+package needs one manual first publish before it can be registered.
+
+Register from a machine with npm >= 11.15.0 and account-level 2FA (granular tokens with the
+bypass-2FA option are rejected):
+
+```sh
+npm trust github @rocket.chat/<name> \
+  --file release.yml \
+  --repo RocketChat/Rocket.Chat \
+  --allow-publish
+
+npm trust list @rocket.chat/<name>
+```
+
+Or on `npmjs.com/package/@rocket.chat/<name>/access`:
+
+| Field             | Value                                  |
+| ----------------- | -------------------------------------- |
+| Provider          | GitHub Actions                         |
+| Organization      | `RocketChat`                           |
+| Repository        | `Rocket.Chat`                          |
+| Workflow filename | `release.yml` (filename only, no path) |
+| Environment       | _(blank)_                              |
+| Allowed actions   | `npm publish`                          |
+
+No GitHub Environment is configured: the monthly RC cron and the push-to-master final release both
+run unattended, and an environment with required reviewers would stall them.
+
+### Provenance requires a correct `repository` field
+
+npm generates provenance automatically for public packages published from a public repo via OIDC,
+and **rejects the publish (422) when `repository.url` does not match the repository the workflow ran
+in**. Every published package therefore needs:
+
+```json
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/RocketChat/Rocket.Chat.git",
+  "directory": "packages/<name>"
+}
+```
+
+The org/repo casing (`RocketChat/Rocket.Chat`) has to match too.
+
+Verify after a release:
+
+```sh
+npm view @rocket.chat/<name> --json dist.attestations
+```
+
+A non-null result is proof the publish went through OIDC — token-based publishes from this repo
+never carried provenance.
+
+## Troubleshooting
+
+- **`E404` / `ENEEDAUTH` on `/-/npm/v1/oidc/token/exchange/package/…`** — almost always a
+  trusted-publisher mismatch: wrong repository, or the workflow filename entered with a path
+  (`.github/workflows/release.yml`) instead of bare `release.yml`.
+- **`E401` / `ENEEDAUTH` with no token configured** — the exchange failed and there was nothing to
+  fall back to. Run with `--loglevel verbose`: `oidc()` logs its reason (`Skipped because incorrect
+  permissions`, `Failed token exchange request…`) instead of throwing.
+- **422 on publish** — provenance mismatch; check the package's `repository` field.
+- **Silent fallback to token auth** — if a valid token is present npm may authenticate with it
+  instead. Confirm via `dist.attestations` rather than the job log.

packages/api-client/package.json

@@ -1,6 +1,11 @@
 {
 	"name": "@rocket.chat/api-client",
 	"version": "0.2.56",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/RocketChat/Rocket.Chat.git",
+		"directory": "packages/api-client"
+	},
 	"main": "./dist/index.js",
 	"typings": "./dist/index.d.ts",
 	"files": [