feat: allow token to be optional for OIDC-based publish (#247)

Closes #242

Author: mcous

.github/workflows/ci-cd.yaml

@@ -230,6 +230,7 @@ jobs:
     if: ${{ github.ref == 'refs/heads/main' }}
     name: Publish
     runs-on: ubuntu-latest
+    environment: npm
     timeout-minutes: 10
 
     permissions:
@@ -259,5 +260,3 @@ jobs:
 
       - name: Publish to NPM
         uses: ./
-        with:
-          token: ${{ secrets.NPM_TOKEN }}

README.md

@@ -44,7 +44,10 @@ jobs:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
 
-See [GitHub's Node.js publishing guide](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages) for more details and examples.
+See GitHub's [Node.js publishing][] guide and npm's [trusted publishing][] docs for more details and examples.
+
+[Node.js publishing]: https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages
+[trusted publishing]: https://docs.npmjs.com/trusted-publishers#supported-cicd-providers
 
 ## Features
 
@@ -97,6 +100,30 @@ jobs:
           token: ${{ secrets.NPM_TOKEN }}
 ```
 
+If you have [trusted publishing][] configured for your package and use `npm@>=11.5.1`, you can omit the `token` input and use OIDC instead.
+
+> [!IMPORTANT]
+> If you're publishing a private package, you will still need to provide a read-only `token` so the action can read existing versions from the registry before publish.
+
+```diff
+  jobs:
+    publish:
+      runs-on: ubuntu-latest
++     permissions:
++       contents: read
++       id-token: write  # required to use OIDC
+      steps:
+        - uses: actions/checkout@v5
+        - uses: actions/setup-node@v5
+          with:
+            node-version: "24"  # includes [email protected]
+        - run: npm ci
+        - run: npm test
+        - uses: JS-DevTools/npm-publish@v4
+-         with:
+-           token: ${{ secrets.NPM_TOKEN }}
+```
+
 You can also publish to third-party registries. For example, to publish to the [GitHub Package Registry][], set `token` to `secrets.GITHUB_TOKEN` and `registry` to `https://npm.pkg.github.com`:
 
 ```yaml
@@ -134,7 +161,7 @@ You can set any or all of the following input parameters using `with`:
 
 | Name             | Type                   | Default                       | Description                                                                      |
 | ---------------- | ---------------------- | ----------------------------- | -------------------------------------------------------------------------------- |
-| `token`          | string                 | **required**                  | Authentication token to use with the configured registry.                        |
+| `token`          | string                 | unspecified                   | Registry authentication token, not required if using [trusted publishing][]³     |
 | `registry`¹      | string                 | `https://registry.npmjs.org/` | Registry URL to use.                                                             |
 | `package`        | string                 | Current working directory     | Path to a package directory, a `package.json`, or a packed `.tgz` to publish.    |
 | `tag`¹           | string                 | `latest`                      | [Distribution tag][npm-tag] to publish to.                                       |
@@ -146,6 +173,7 @@ You can set any or all of the following input parameters using `with`:
 
 1. May be specified using `publishConfig` in `package.json`.
 2. Provenance requires npm `>=9.5.0`.
+3. Trusted publishing npm `>=11.5.1` and must be run from a supported cloud provider.
 
 [npm-tag]: https://docs.npmjs.com/cli/v9/commands/npm-publish#tag
 [npm-access]: https://docs.npmjs.com/cli/v9/commands/npm-publish#access
@@ -209,7 +237,7 @@ import type { Options } from "@jsdevtools/npm-publish";
 
 | Name                 | Type                   | Default                       | Description                                                                      |
 | -------------------- | ---------------------- | ----------------------------- | -------------------------------------------------------------------------------- |
-| `token`              | string                 | **required**                  | Authentication token to use with the configured registry.                        |
+| `token`              | string                 | **required**                  | Registry authentication token, not required if using [trusted publishing][]³     |
 | `registry`¹          | string, `URL`          | `https://registry.npmjs.org/` | Registry URL to use.                                                             |
 | `package`            | string                 | Current working directory     | Path to a package directory, a `package.json`, or a packed `.tgz` to publish.    |
 | `tag`¹               | string                 | `latest`                      | [Distribution tag][npm-tag] to publish to.                                       |
@@ -223,6 +251,7 @@ import type { Options } from "@jsdevtools/npm-publish";
 
 1. May be specified using `publishConfig` in `package.json`.
 2. Provenance requires npm `>=9.5.0`.
+3. Trusted publishing npm `>=11.5.1` and must be run from a supported cloud provider.
 
 ### API output
 
@@ -281,7 +310,9 @@ Arguments:
 
 Options:
 
-  --token <token>         (Required) npm authentication token.
+  --token <token>         npm authentication token.
+                          Not required if using trusted publishing.
+                          See npm documentation for details.
 
   --registry <url>        Registry to read from and write to.
                           Defaults to "https://registry.npmjs.org/".

action.yaml

@@ -9,7 +9,7 @@ branding:
 inputs:
   token:
     description: The NPM access token to use when publishing
-    required: true
+    required: false
 
   registry:
     description: The NPM registry URL to use

dist/main.js

@@ -57,15 +57,22 @@ describe("normalizeOptions", () => {
     });
 
     it("should throw if token invalid", () => {
-      expect(() => {
-        subject.normalizeOptions(manifest, { token: "" });
-      }).toThrow(errors.InvalidTokenError);
-
       expect(() => {
         // @ts-expect-error: intentionally mistyped for validation testing
-        subject.normalizeOptions({ token: 42 }, manifest);
+        subject.normalizeOptions(manifest, { token: 0 });
       }).toThrow(errors.InvalidTokenError);
     });
+
+    // eslint-disable-next-line unicorn/no-null
+    it.each([undefined, null, ""])(
+      "should set unspecified token %j to undefined",
+      (token) => {
+        // @ts-expect-error: intentionally mistyped for validation testing
+        const result = subject.normalizeOptions(manifest, { token });
+
+        expect(result).toMatchObject({ token: undefined });
+      }
+    );
   });
 
   describe("publishConfig", () => {

src/__tests__/normalize-options.test.ts

@@ -14,7 +14,9 @@ Arguments:
 
 Options:
 
-  --token <token>         (Required) npm authentication token.
+  --token <token>         npm authentication token.
+                          Not required if using trusted publishing.
+                          See npm documentation for details.
 
   --registry <url>        Registry to read from and write to.
                           Defaults to "https://registry.npmjs.org/".

src/cli/index.ts

@@ -19,7 +19,7 @@ export const TAG_LATEST = "latest";
 /** Normalized and sanitized auth, publish, and runtime configurations. */
 export interface NormalizedOptions {
   registry: URL;
-  token: string;
+  token: string | undefined;
   tag: ConfigValue<string>;
   access: ConfigValue<Access | undefined>;
   provenance: ConfigValue<boolean>;
@@ -58,7 +58,7 @@ export function normalizeOptions(
   const defaultProvenance = manifest.publishConfig?.provenance ?? false;
 
   return {
-    token: validateToken(options.token),
+    token: validateToken(options.token ?? undefined),
     registry: validateRegistry(options.registry ?? defaultRegistry),
     tag: setValue(options.tag, defaultTag, validateTag),
     access: setValue(options.access, defaultAccess, validateAccess),
@@ -80,12 +80,12 @@ const setValue = <TValue>(
   isDefault: value === undefined,
 });
 
-const validateToken = (value: unknown): string => {
-  if (typeof value === "string" && value.length > 0) {
-    return value;
+const validateToken = (value: unknown): string | undefined => {
+  if (typeof value !== "string" && value !== undefined && value !== null) {
+    throw new errors.InvalidTokenError();
   }
 
-  throw new errors.InvalidTokenError();
+  return typeof value === "string" && value.length > 0 ? value : undefined;
 };
 
 const validateRegistry = (value: unknown): URL => {

src/normalize-options.ts

@@ -77,4 +77,24 @@ describe("useNpmEnvironment", () => {
       await expect(fs.access(npmrcPath!)).rejects.toThrow(/ENOENT/);
     }
   );
+
+  it("allows unspecified token", async () => {
+    const inputManifest = { name: "fizzbuzz" } as PackageManifest;
+    const inputOptions = {
+      token: undefined,
+      registry: new URL("http://example.com/"),
+      temporaryDirectory: directory,
+    } as NormalizedOptions;
+
+    const result = await subject.useNpmEnvironment(
+      inputManifest,
+      inputOptions,
+      async (_manifest, _options, environment) => {
+        await Promise.resolve();
+        return environment;
+      }
+    );
+
+    expect(result).toMatchObject({ NODE_AUTH_TOKEN: "" });
+  });
 });

src/npm/__tests__/use-npm-environment.test.ts

@@ -36,7 +36,6 @@ export const VIEW = "view";
 export const PUBLISH = "publish";
 
 export const E404 = "E404";
-export const E409 = "E409";
 export const EPUBLISHCONFLICT = "EPUBLISHCONFLICT";
 
 const IS_WINDOWS = os.platform() === "win32";

src/npm/call-npm-cli.ts

@@ -42,7 +42,10 @@ export async function useNpmEnvironment<TReturn>(
     path.join(temporaryDirectory, "npm-publish-")
   );
   const npmrc = path.join(npmrcDirectory, ".npmrc");
-  const environment = { NODE_AUTH_TOKEN: token, npm_config_userconfig: npmrc };
+  const environment = {
+    NODE_AUTH_TOKEN: token ?? "",
+    npm_config_userconfig: npmrc,
+  };
 
   await fs.writeFile(npmrc, config, "utf8");