#74: Secure npm release publishing

Author: emoriwan

.github/workflows/release.yml

@@ -9,6 +9,8 @@ jobs:
   # When a prerelease is promoted to a full release, update the npm latest tag
   promote:
     if: github.event.action == 'released'
+    permissions:
+      contents: read
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout code
@@ -18,6 +20,10 @@ jobs:
         with:
           node-version-file: '.node-version'
           registry-url: https://registry.npmjs.org
+      - name: Install supported npm CLI
+        run: |
+          npm install --global npm@11.5.1
+          npm --version
       - name: Promote edge to latest
         run: |
           VERSION=$(echo "$TAG_NAME" | sed 's/^v//')
@@ -26,10 +32,13 @@ jobs:
           echo "::notice title=Promoted $VERSION to latest::The latest tag now points to $VERSION (was edge-only)"
         env:
           TAG_NAME: ${{ github.event.release.tag_name }}
-          NODE_AUTH_TOKEN: ${{secrets.NPM_DEPLOY_TOKEN}}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_DIST_TAG_TOKEN }}
 
   deploy:
     if: github.event.action == 'published'
+    permissions:
+      contents: read
+      id-token: write
     runs-on: ${{ matrix.os }}
     env:
       TERM: xterm
@@ -48,6 +57,10 @@ jobs:
           node-version-file: '.node-version'
           registry-url: https://registry.npmjs.org
           cache: npm
+      - name: Install supported npm CLI
+        run: |
+          npm install --global npm@11.5.1
+          npm --version
       - name: Install dependencies
         run: npm clean-install --prefer-offline --frozen-lockfile
 
@@ -84,5 +97,3 @@ jobs:
             npm publish --access public --tag ${{ env.PRERELEASE_TAG }}
             echo "::notice title=Published ${{ github.ref_name }} to @${{ github.repository }}@${{ env.PRERELEASE_TAG }}::This is a pre-release published to the '${{ env.PRERELEASE_TAG }}' npm tag"
           fi
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_DEPLOY_TOKEN }}

README.md

@@ -266,9 +266,14 @@ npm run test:unit
 
 ## Releasing
 
-To deploy and publish a new version of the package to the `npm` registry you need only [create a release on GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) with a [semver](https://semver.org) tag.
+To deploy and publish a new version of the package to the `npm` registry you need only [create a release on GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) with a [semver](https://semver.org) tag. Stable releases publish to the `latest` tag, while prereleases publish to `edge`. Promoting a prerelease to a full release moves that version to `latest`.
 
-Note that prereleases will get pushed to the `edge` tag on the `npm` registry.
+Before releasing, maintainers must configure the following external access:
+
+* Add a GitHub Actions trusted publisher to the `@lando/leia` package on npm with organization `lando`, repository `leia`, workflow filename `release.yml`, no environment, and the `npm publish` allowed action. The workflow publishes through OIDC and does not use an npm token.
+* Create a short-lived granular npm token with read and write access only to the `@lando/leia` package, no organization access, and 2FA bypass only when the package settings require it for unattended writes. Store it as the `NPM_DIST_TAG_TOKEN` GitHub Actions secret. npm granular tokens cannot be limited to one CLI command, so package-only read and write access is the narrowest permission available for the `npm dist-tag add` promotion step.
+
+Configure both before running this workflow. After an authorized release verifies trusted publishing and promotion, revoke the broader `NPM_DEPLOY_TOKEN` that the previous workflow used.
 
 ## Maintainers
 

package.json

@@ -4,7 +4,10 @@
   "version": "1.0.0-beta.4",
   "author": "Mike Pirog @pirog",
   "license": "MIT",
-  "repository": "github:lando/leia",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lando/leia.git"
+  },
   "bugs": "https://github.com/lando/leia/issues/new/choose/",
   "homepage": "https://github.com/lando/leia",
   "keywords": [
@@ -19,7 +22,7 @@
   },
   "main": "lib/leia.js",
   "bin": {
-    "leia": "./bin/leia"
+    "leia": "bin/leia"
   },
   "files": [
     "/bin",