クラウドのコンテナから新しい npm の名前を確保する

  • npm
  • Trusted Publishing
  • GitHub Actions
  • Claude Code

masseater.dev のすべてのパッケージは、公開するワークスペースを指定して手動でディスパッチして公開する GitHub Actions ワークフローである publish.yml によって公開されている。これは Trusted Publishing (OIDC) を用いて npm と認証するため、リポジトリに npm トークンは保持されない。この仕組みは、npm 上に既に存在する名前にのみ適用される。2026-11-18 時点で、スコープ @r_masseater の 8 つの新しい名前が一斉に必要となった。fu4-presets、fumx-parser、h56m、h56m-linux-x64-gnu、h56m-win32-x64-msvc、h56m-presets、wism-presets、y8-presets である。規約チェッカーである msch はこれらの大半に依存しているため、それらがリリースされるまで msch を npm からインストールできなかった。

なぜ新しい名前に所有者が必要なのか

npmでは、既に存在するパッケージに対してのみ信頼できるパブリッシャーを設定できる1。そのため、新しい名前の最初のバージョンをOIDCワークフローから公開できない。信頼設定にはアカウントの2FAも必要であり、npmは信頼コマンドの2FAをバイパスするきめ細かなアクセストークンを受け付けない1。CIが到達可能なトークンは、新しい名前を作成しようとするとE404となる。

残るは、オーナーにしかできない1つのステップで、書き込みごとに2FAプロンプトを承認することだ。それ以外のすべては、次のようにコンテナ側で処理する計画だった。

  1. npm login --auth-type=web でログインし、オーナーにログインリンクを承認してもらう。
  2. 各名称のプレースホルダー版 0.0.0 を公開する。これには package.json(MITライセンス、リポジトリURL)と、バージョンが名称のみを保持することを示す README のみを含める。
  3. 各名前に対して npm trust github <name> --file publish.yml --repository masseater/masseater.dev --environment npm --yes を実行する。
  4. プルリクエストで本番版を更新し、publish.yml をディスパッチする。

ステップ2と3はそれぞれパッケージごとに1件の承認が必要であるため、8つの名前にはログイン1回分と16件の承認が必要となる。

npmのWeb認証の機能

npmがブラウザ経由で2FAを必要とする場合、レジストリは401レスポンスと2つのURLを含むボディで書き込みを応答する。authUrlはオーナーが開くページである。doneUrlはCLIによってポーリングされる。オーナーがまだ承認していない場合は202を、承認済みの場合はワンタイムトークンと共に200を、そしてリクエストが期限切れとなる約5分後に404を返す。その後、CLIはそのトークンをOTPとして書き込みを繰り返す。401ボディにこれらのURLが含まれるのは、リクエストにnpm-auth-type: webヘッダーが含まれている場合に限られる。

何が失敗したか

初回ログインでは、標準入力を閉じた状態で npm login --auth-type=web を使用した。ターミナルがない状態で、npm は Username: プロンプトに戻り、リンクを一度も出力しなかった。これを script でラップして擬似ターミナル化したところ、リンクが出力され、ログインが承認された。しかし、npm が終了した後も script プロセスは CPU 使用率 90% のまま動作し続け、保存済みのトークンもそれと共に失われた。

正常に動作したログインでは、CLIではなく小規模なNode.jsスクリプトが使用された。https://registry.npmjs.org/-/v1/login にPOSTし、loginUrl を出力する。そして単一のkeep-alive接続(https.Agent かつ maxSockets: 1)を介して300msごとに doneUrl をポーリングする。ポーリングの結果が200を返すと、トークンをモード600の一時的なnpmrcに書き込む。

プレースホルダーについては、まず script 配下で 8 つの npm publish プロセスを並列に実行し、その出力から 8 つの authUrl を収集してまとめて投稿した。8 つすべてが期限切れとなった。各プロセスのデバッグログには同様の結果が表示されていた。96 件のポーリングで 202 が返され、その後 1 件の 404 が返された。npm は一度も承認を検知しなかった。2 つ目の 8 件のセットでも、全く同じ結果となった。

前回のセッションでは、このコンテナが接続ごとにエグレスIPを変更しており、doneUrl がリクエストを開始したIPとは別のIPに対して 403 を返すことが判明した。今回はポーリングで 403 が返されなかったため、ログにその問題は記録されていない。記録されているのは、リンクの有効期限が切れる前に npm への承認が得られなかったことだけである。オーナーの承認がどこかで失われたのか、あるいは一度も行われなかったのかは確認できていない。

うまくいったこと

3回目と4回目の試行では、npm独自のライブラリを用いてCLI外で書き込みを行った。1つのパッケージにつき1つのNode.jsプロセスが、グローバルのnpm installからlibnpmpublishとnpm-registry-fetchを読み込み、authType: "web"とmaxSockets: 1を渡す。このプロセスはパブリッシュを送信し、401をキャッチしてauthUrlを出力し、単一の接続で1秒ごとにdoneUrlをポーリングし、ポーリングの結果が200になった時点でトークンを用いてパブリッシュを繰り返す。

3つ目のセットも、最初の2つと同様に期限が切れた。UTC 03:46に送信された4つ目のセットは、8つのプレースホルダーすべてが約2分以内に公開された。所有者は承認ページで「5分間、再度問い合わせない」にチェックを入れていたが、それでも各書き込みによって個別のリンクが生成された。

Trustは同じパターンを使用した。npm trustは、次のようなボディで/-/package/<name>/trustにPOSTする。

[
  {
    "type": "github",
    "claims": {
      "repository": "masseater/masseater.dev",
      "workflow_ref": { "file": "publish.yml" },
      "environment": "npm"
    },
    "permissions": ["createPackage"]
  }
]

permissions フィールドは必須である。CLI は --allow-publish でこのフィールドを補完し、少なくとも1つの権限フラグを指定する必要がある1。レジストリがそのパッケージに対して 200 を返した時点で、ウォッチャースクリプトは各名前の信頼リクエストを開始した。レジストリがまだ表示していない名前では信頼が失敗するためである。fumx-parser のプレースホルダーが表示されるまで約4分かかったため、信頼リンクは最後に表示された。2つの信頼リンクが期限切れとなり、再送された。

最終承認後、npmセッションがログアウトされ、一時的なnpmrcが削除された。その後、publish.ymlがy8-presets、wism-presets、fumx-parser、h56m-presets、およびh56mをOIDC経由で公開し、続いてmschが公開された。

変更事項

コストの大部分は承認数によるものだった。新しい名前1つにつき2件の承認が必要であり、h56m-linux-x64-gnuのようなOS固有のパッケージでは、名前の数がそれに乗じられる。新しい名前の数が少なければ、例えばメインパッケージ内にネイティブバイナリを同梱したり、今回のようにプリセットをツールごとに1つのパッケージにまとめたりすることで、承認数を減らすことができる。

シングルコネクションのパブリッシャーおよびトラストスクリプトは、リポジトリの名前を確保するツールにおけるCLI呼び出しを置き換えるべきであり、これにより次の確保が失敗したCLIの経路から始まらないようにする。

出典

  1. npm trust, npm Docs, 2026-11-18に確認済み。 ↩ ↩2 ↩3