Package Registry Service - Publish Endpoint

Package Registry の仕様に、パッケージリリースを公開するためのエンドポイントを追加します。対象は Swift Package Manager 本体ではなく、あくまでレジストリサービスが実装する Web API の仕様です。

追加されるエンドポイント

次の 1 本のエンドポイントが追加されます。

このエンドポイントの実装はレジストリにとって任意（optional）です。つまり、取得専用のレジストリとして運用することも引き続き可能です。また、一度公開されたリリースは原則として削除されない（durability）前提で設計されており、最終的に何を公開可能とするかはレジストリ側が判断します。

公開フローの例

メンテナが mona.LinkedList の 1.1.1 をリリースしてレジストリ packages.example.com に登録する場合、おおむね次の流れになります。

まず、swift package archive-source サブコマンドでパッケージのソースを Zip アーカイブ化します。

$ swift package archive-source

次に、生成された Zip をマルチパートで PUT リクエストにのせてレジストリへアップロードします。version はクエリで指定します。

$ curl -X PUT --netrc                                      \
       -H "Accept: application/vnd.swift.registry.v1+json" \
       -F source-archive="@LinkedList-1.1.1.zip"           \
       "https://registry.example.com/mona/LinkedList?version=1.1.1"

レジストリはこのリクエストを同期／非同期のどちらで処理することもできます。サーバ側で品質チェックや内部データストアの更新などを行う余地を残すためです。

受理・処理が終わると、当該バージョンが一覧エンドポイントから返るようになります。

$ curl -X GET -H "Accept: application/vnd.swift.registry.v1+json" \
       "https://registry.example.com/mona/LinkedList"             \
    | jq ".[] | keys"
[
  "1.0.0",
  "1.1.0",
  "1.1.1",
]

以降、依存解決を行うクライアントは 1.1.1 を検出し、必要に応じて GET /mona/LinkedList/1.1.1.zip でソースアーカイブを取得できます。

「push」と「pull」の統合

公開モデルには、成果物をクライアントからサーバへアップロードする push 型と、メンテナはレジストリに通知するだけでサーバ側がソースコードを取り寄せてパッケージ化する pull 型の考え方があります。本 proposal では検討の結果、両者を別エンドポイントに分けず、単一の PUT エンドポイントで両方を表現できる形にしました。pull 型は「クライアントとサーバが同一主体である push」とみなせるためです。

セキュリティ上の考慮点

公開エンドポイントは攻撃対象となりやすいため、仕様として次のような注意点が示されています。実装する各レジストリが、これらに対応することが期待されています。

• なりすまし対策として、公開リクエストに対する多要素認証の利用が推奨されます。また、既存のパッケージ名と似た名前での登録（typosquatting）を検出するため、Damerau–Levenshtein 距離などの文字列類似度で既存名と比較する運用も推奨されます。
• アップロードされた Zip アーカイブの展開時には、Zip Slip や Zip bomb のような既知の脆弱性・弱点への対策が必要です。
• リリース内容に関する紛争に備え、SBOM（software bill of materials）やデジタル署名といった、来歴（provenance）を裏付ける仕組みと組み合わせられる設計になっています。
• アップロードされたアーカイブにクレデンシャルなどの機微情報が含まれていないか、サーバ側でスキャンして拒否することが推奨されます。
• 大きなペイロードによる DoS を避けるため、リクエストボディを処理する前に認証を済ませる、最大サイズを制限する、リバースプロキシ／ロードバランサを経由させる、といった一般的な防御策が推奨されます。
• Package.swift は実行可能なコードであり、プラットフォームや依存関係などのメタ情報を得るには Swift ツールチェーンで評価する必要があります。悪意ある Package.swift による遠隔コード実行を避けるため、マニフェストの評価は権限を絞ったコンテナ内で行うことが推奨されます。

既存パッケージへの影響

公開エンドポイントは、既存の URL ベースの配布から新しいレジストリ方式への移行経路を、各レジストリ運用者が用意するための土台になります。具体的な移行ポリシー（どのパッケージを取り込むか、どの時点から公開エンドポイント経由のみに切り替えるか等）は、各レジストリ運用者の裁量に委ねられます。