npmのtrusted publishing、OIDCでdist-tagの移動に対応

GitHubは2026年9月30日、npmのtrusted publishing（信頼された公開）でdist-tagを管理できるようになったと発表しました。dist-tagとは latest のようなラベルで、利用者がパッケージのどのバージョンをインストールするかを決めます。リリースパイプラインは、保存済みのnpmアクセストークンではなく、短期間だけ有効なログイントークンでこれらのラベルを移動できます。これにより、長期間有効なnpmのシークレットをCIシステム内に置いておく、よくある理由の1つがなくなります。

この権限はオプトイン方式です。既存か新規かを問わず、すべての設定で最初はオフになっています。そのため、自分で求めない限り、誰も latest を移動する権限を得ることはありません。

trusted publishingとdist-tagとは

trusted publishingを使うと、GitHub ActionsのワークフローなどのCIジョブが、保存されたパスワードやトークンなしでnpmに公開できます。ジョブはOIDCで自分が何者かを証明します。OIDCはOpenID Connectの略で、短期間だけ有効な身元トークンを発行するための標準的な方法です。npmレジストリは、そのトークンをパッケージの所有者が用意した設定と照合し、その操作を許可します。

dist-tagは、パッケージの特定のバージョンを指す名前付きのポインターです。ほとんどのインストールが従うのは latest タグです。プロジェクトでは、テスト版のリリース用に next や beta などのタグを追加することもよくあります。これまでtrusted publishingはパッケージをリリースできても、これらのポインターを移動できませんでした。そのためチームは、その手順のために長期間有効なトークンを手元に残していました。

新しい権限でできること

GitHubの変更履歴によると、trusted publishingの各設定に「Allow npm dist-tag」という項目が加わりました。これがオンのとき、CIジョブはdist-tagを追加、削除、昇格できます。npmのドキュメントには、対応するコマンドとして npm dist-tag ls、npm dist-tag add、npm dist-tag rm が挙げられています。

GitHubは初期設定を強調しています。変更履歴には「新規と既存のどちらの設定でも初期値はオフなので、新たな機能を自動的に得る設定はない」とあります。

この権限は、公開の権限とは別のものです。ドキュメントによると、ある設定に npm publish の実行を許可しないまま、パッケージのステージングとdist-tagの管理を許可できます。さらにドキュメントは、2026年9月3日より後に作成された設定ではパッケージを自動的にステージングできるものの、dist-tagへのアクセスは引き続き手動でオンにする必要があると付け加えています。

セキュリティ上、重要なルールが1つあります。GitHubによると、dist-tagの変更が許可されるのは「受け取ったOIDCトークンが、権限を有効にした設定のいずれか1つと一致する場合」です。したがって、チェックボックスをオンにした設定は、どれも latest を移動できる経路が1つ増えることを意味します。

要件と制限

npmのドキュメントは、次の最低要件を定めています。

要件	npmのドキュメントの記載
OIDCでのdist-tag操作に必要なnpm CLI	11.21.0以降
trusted publishing全般に必要なnpm CLI	11.5.1以降
Node.js	22.14.0以降
GitHub Actions	GitHubホストランナーのみ
GitLab CI/CD	GitLab.comの共有ランナーのみ
CircleCI	CircleCIクラウドのみ
セルフホストランナー	現時点では未対応

ドキュメントによると、セルフホストランナーは「今後のリリースで予定されている」とのことです。CIへの対応については、情報源によって記述が異なります。Leoという開発者によるDEV Communityの投稿は、BuddyとJenkinsにも触れており、Jenkinsはプラグイン経由としています。しかし、npm自身のドキュメントに挙げられているのは、上記の3つのサービスだけです。

dist-tagが狙われる理由

dist-tagを移動できることは、公開できることと同じくらい強力です。Leoの投稿は、dist-tagの制御を深刻なサプライチェーンのリスクだとしています。latest を書き換えられる攻撃者は、新しいインストールをすべて不正なバージョンに向けられるからです。悪意のあるリリースは、現実に起きているパターンです。8月には、Rustのクレートarrayrefの汚染されたバージョンが、ビルド中にリモートのペイロードを実行しました。

Leoは、人為的なミスについても警告しています。リリースがブロックされたチームは、問題を解消するために、すべての設定でチェックボックスをオンにしてしまうかもしれません。投稿は代わりに、厳密な照合条件を持つリリース専用の設定を1つだけ用意するよう勧めています。その条件とは、特定のワークフローファイル、保護された環境、手動の承認ステップです。

これが開発者にとって意味すること

まず、リリースジョブのnpm CLIをアップグレードしてください。OIDCによるdist-tagの変更には、npm 11.21.0以降とNode.js 22.14.0以降が必要です。バージョンを固定したCIイメージに古いCLIが入っていると、設定をオンにしても失敗します。

権限をオンにするのは1か所だけにしてください。一致する設定が1つでもあれば latest を移動できるため、リリース用の設定でだけ有効にし、ステージング用やテスト用の設定はオフのままにしましょう。変更のたびに一覧を見直してください。

設定は厳密に絞り込みましょう。リリースを作成するワークフローファイルそのものに結び付け、承認ステップのある保護された環境を必須にしてください。そうすれば、プルリクエストのワークフローや、乗っ取られた別のジョブがタグを移動することはできません。

切り替えがうまくいったら、古いトークンを削除しましょう。この変更の目的は、長期間有効なnpmのシークレットをCIに保存しないようにすることです。OIDCでのリリースが成功したら、残っているトークンをCIのシークレットから削除し、npm上で失効させてください。

トークンを残すのは、どうしても必要な場所だけにしましょう。セルフホストランナーでビルドしている場合、trusted publishingはまだ対応していません。npmがセルフホストに対応するまでは、そのトークンを必要なパッケージだけに限定し、定期的にローテーションしてください。

リリースのたびにタグを確認しましょう。パッケージに対して npm dist-tag ls を実行し、latest が想定どおりのバージョンを指しているか確かめてください。2秒で済む確認で、ミスと攻撃の両方を見つけられます。