# レジストリごとの転送挙動 {#registry-forwarding}

Takumi Guard が各レジストリへのリクエストをどのように転送し、応答しているかを記載しています。プロキシやファイアウォールなどで外部への通信を制限している環境での設定にご利用ください。

:::warning 変更の可能性について
本ページに記載している挙動は現時点のものです。変更する場合はリリースノートで予告しますが、セキュリティ上の緊急対応などにより、予告なく変更する場合があります。
:::

## 通信経路 {#communication-flow}

Takumi Guard はパッケージ実体を中継しません。メタデータは Takumi Guard を経由しますが、パッケージ実体の取得時には HTTP 302 を返し、クライアントが公式配布元へ直接接続して取得します。この流れの詳細は[パッケージのブロック](/docs/ja/t/guard/features/package-blocking.md#request-flow)を参照してください。

## 通信先 {#destinations}

公式レジストリのホストでは、以下に記載するパスと、Takumi Guard を経由するため通信が発生しないパスが同じホスト上に混在します。**ホスト名だけでは両者を区別できません。**

### Takumi Guard {#guard-hosts}

Takumi Guard はエコシステムごとに次のホストで提供しており、ご利用のエコシステムに応じて該当するホストへの通信が発生します。

| ホスト                 | エコシステム |
| ---------------------- | ------------ |
| `npm.flatt.tech`       | npm          |
| `pypi.flatt.tech`      | PyPI         |
| `rubygems.flatt.tech`  | RubyGems     |
| `golang.flatt.tech`    | Go           |
| `packagist.flatt.tech` | Packagist    |

### 公式レジストリ（パッケージ実体の取得先） {#official-artifact-hosts}

パッケージ実体は、Takumi Guard がリダイレクトした先のホストから直接ダウンロードされます。

| ホスト                   | 使用するパス                                                                                                                                    | 用途                   |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `registry.npmjs.org`     | `GET /{パッケージ名}/-/*.tgz`<br />`GET /@{スコープ}/{パッケージ名}/-/*.tgz`                                                                    | npm パッケージ実体     |
| `files.pythonhosted.org` | `GET /packages/**`                                                                                                                              | wheel・sdist 実体      |
| `rubygems.org`           | `GET /gems/*.gem`<br />`GET /quick/Marshal.4.8/**`<br />`GET /specs.4.8.gz`<br />`GET /latest_specs.4.8.gz`<br />`GET /prerelease_specs.4.8.gz` | gem 実体とインデックス |
| `proxy.golang.org`       | `GET /**/@v/*.zip`                                                                                                                              | Go モジュール実体      |

RubyGems では、Bundler が Compact Index を利用できない場合にレガシーインデックス（`/specs.4.8.gz` 系と `/quick/Marshal.4.8/`）へ切り替わります。この経路も Takumi Guard がリダイレクトを返します。

Composer の実体取得先は、パッケージのメタデータに記載された配布元です。GitHub 上のパッケージであれば `api.github.com` へリダイレクトし、そこから `codeload.github.com` へさらにリダイレクトされます。GitHub 以外に配布元を持つパッケージが依存関係に含まれる場合は、そのホストへの通信が発生します。依存パッケージごとの配布元は、`https://packagist.flatt.tech/p2/{ベンダー}/{パッケージ}.json` の `dist.url` で確認できます。

### リダイレクト先以外に発生する通信 {#other-required-hosts}

パッケージ実体のリダイレクト先ではありませんが、次の通信も発生します。

#### Go のチェックサムデータベース {#go-checksum-database}

Go ツールチェーンは、チェックサム検証が有効な構成では、モジュールの取得前にチェックサムデータベースへ問い合わせます。Takumi Guard はこの検証を代理しないため、クライアントから `sum.golang.org`（全パス）へ直接接続します。

## エコシステム別の通信 URL {#url-inventory}

エコシステムごとに発生する通信です。

### npm {#npm-urls}

npm・pnpm・yarn・bun で共通です。

- **`GET https://npm.flatt.tech/{パッケージ名}`**
  - **目的**: メタデータの取得
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200 / 304
- **`POST https://npm.flatt.tech/-/npm/v1/security/advisories/bulk`**
  - **目的**: 脆弱性情報の照会（npm のみ）
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200
- **`POST https://npm.flatt.tech/-/npm/v1/security/audits`**、**`/-/npm/v1/security/audits/quick`**
  - **目的**: 脆弱性情報の照会（pnpm・yarn）
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200
- **`GET https://npm.flatt.tech/-/npm/v1/keys`**、**`GET https://npm.flatt.tech/-/npm/v1/attestations/{パス}`**
  - **目的**: 署名鍵と provenance の検証
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200
- **`GET https://npm.flatt.tech/-/v1/search`**
  - **目的**: パッケージの検索（`npm search` の実行時）
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200
- **`GET https://npm.flatt.tech/{パッケージ名}/-/{ファイル名}.tgz`**
  - **目的**: パッケージ実体の要求
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 302（`registry.npmjs.org` へリダイレクト）
- **`GET https://registry.npmjs.org/{パッケージ名}/-/{ファイル名}.tgz`**
  - **目的**: パッケージ実体のダウンロード
  - **通信先**: 公式レジストリ
  - **ステータス**: 200

スコープ付きパッケージのパスは `/@{スコープ}/{パッケージ名}` です。yarn・pnpm・bun はメタデータの取得時にスラッシュを URL エンコードし、`/@{スコープ}%2f{パッケージ名}` の形で送信します。`%2F` も同じく処理されるため、パスで判定する場合は大文字小文字の両方を考慮してください。

:::info bun の場合
ロックファイルがない初回のインストールでは、パッケージ実体の要求が Takumi Guard を経由せず、`registry.npmjs.org` へ直接行われます。メタデータの取得は Takumi Guard を経由します。通信先のホストは上記と同じです。
:::

### PyPI {#pypi-urls}

pip・uv で共通です。

- **`GET https://pypi.flatt.tech/simple/{プロジェクト名}/`**
  - **目的**: メタデータの取得
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200
- **`GET https://pypi.flatt.tech/files/packages/{ハッシュパス}/{ファイル名}`**
  - **目的**: パッケージ実体の要求
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 302（`files.pythonhosted.org` へリダイレクト）
- **`GET https://files.pythonhosted.org/packages/{ハッシュパス}/{ファイル名}`**
  - **目的**: パッケージ実体のダウンロード
  - **通信先**: 公式の配布元
  - **ステータス**: 200

:::warning Poetry の場合
リポジトリごとの設定をしたプロジェクトでは、pip や uv と同様に `pypi.flatt.tech` を経由します。一方、設定していない場合は、メタデータの取得が Takumi Guard を経由せず、次の通信となりますのでご注意ください。

設定方法は、[クイックスタートの poetry](/docs/ja/t/guard/quickstart/pypi.md#quick-reference-poetry)を参照してください。

- **`GET https://pypi.org/simple/{プロジェクト名}/`**
  - **目的**: メタデータの取得
  - **通信先**: 公式レジストリ
  - **ステータス**: 200
- **`GET https://pypi.org/pypi/{プロジェクト名}/{バージョン}/json`**
  - **目的**: メタデータの取得
  - **通信先**: 公式レジストリ
  - **ステータス**: 200

:::

### RubyGems {#rubygems-urls}

Bundler での通信です。

- **`GET https://rubygems.flatt.tech/versions`**
  - **目的**: インデックスの取得
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200 / 206 / 304（差分取得では 206）
- **`GET https://rubygems.flatt.tech/info/{gem 名}`**
  - **目的**: メタデータの取得
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200
- **`GET https://rubygems.flatt.tech/gems/{gem 名}-{バージョン}.gem`**
  - **目的**: パッケージ実体の要求
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 302（`rubygems.org` へリダイレクト）
- **`GET https://rubygems.org/gems/{gem 名}-{バージョン}.gem`**
  - **目的**: パッケージ実体のダウンロード
  - **通信先**: 公式レジストリ
  - **ステータス**: 200
- **`GET https://rubygems.flatt.tech/specs.4.8.gz`**、**`/latest_specs.4.8.gz`**、**`/prerelease_specs.4.8.gz`**、**`/quick/Marshal.4.8/{gem 名}-{バージョン}.gemspec.rz`**
  - **目的**: レガシーインデックスの取得（Compact Index を利用できない場合）
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 302（`rubygems.org` の同じパスへリダイレクト）
- **`GET https://rubygems.org/specs.4.8.gz`** ほか上記のリダイレクト先
  - **目的**: レガシーインデックスのダウンロード
  - **通信先**: 公式レジストリ
  - **ステータス**: 200

### Go {#golang-urls}

Go ツールチェーンでの通信です。

- **`GET https://golang.flatt.tech/sumdb/sum.golang.org/supported`**
  - **目的**: チェックサムデータベースの照会可否の確認
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 404（仕様上の応答。クライアントは `sum.golang.org` へ直接接続します）
- **`GET https://golang.flatt.tech/{モジュールパス}/@v/list`**
  - **目的**: バージョン一覧の取得
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 上流のステータスをそのまま返します
- **`GET https://golang.flatt.tech/{モジュールパス}/@latest`**
  - **目的**: 最新バージョンの取得（`go get モジュール@latest` などの実行時）
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 上流のステータスをそのまま返します
- **`GET https://golang.flatt.tech/{モジュールパス}/@v/{バージョン}.info`**
  - **目的**: メタデータの取得
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 上流のステータスをそのまま返します
- **`GET https://golang.flatt.tech/{モジュールパス}/@v/{バージョン}.mod`**
  - **目的**: メタデータの取得
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 上流のステータスをそのまま返します
- **`GET https://golang.flatt.tech/{モジュールパス}/@v/{バージョン}.zip`**
  - **目的**: パッケージ実体の要求
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 302（`proxy.golang.org` へリダイレクト）
- **`GET https://proxy.golang.org/{モジュールパス}/@v/{バージョン}.zip`**
  - **目的**: パッケージ実体のダウンロード
  - **通信先**: 公式プロキシ
  - **ステータス**: 200
- **`GET https://sum.golang.org/lookup/{モジュールパス}@{バージョン}`**
  - **目的**: チェックサムの検証
  - **通信先**: チェックサムデータベース
  - **ステータス**: 200
- **`GET https://sum.golang.org/tile/{タイルパス}`**
  - **目的**: チェックサムの検証
  - **通信先**: チェックサムデータベース
  - **ステータス**: 200

### Packagist {#packagist-urls}

Composer での通信です。

- **`GET https://packagist.flatt.tech/packages.json`**
  - **目的**: リポジトリ定義の取得
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200 / 304
- **`GET https://packagist.flatt.tech/p2/{ベンダー}/{パッケージ}.json`**、**`/p2/{ベンダー}/{パッケージ}~dev.json`**
  - **目的**: メタデータの取得（Composer 2 は両方を取得します）
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200 / 304
- **`POST https://packagist.flatt.tech/api/filter`**
  - **目的**: インストール対象の照会（`composer install` および `composer audit` の実行時）
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 200
- **`GET https://packagist.flatt.tech/dist/{ベンダー}/{パッケージ}/{バージョン}/{リファレンス}.{形式}`**
  - **目的**: パッケージ実体の要求
  - **通信先**: <GuardIcon /> Takumi Guard
  - **ステータス**: 302（メタデータに記載された配布元へリダイレクト。GitHub 上のパッケージでは `api.github.com`）
- **`GET https://api.github.com/repos/{owner}/{repo}/zipball/{リファレンス}`**
  - **目的**: パッケージ実体の要求
  - **通信先**: GitHub
  - **ステータス**: 302（`codeload.github.com` へリダイレクト）
- **`GET https://codeload.github.com/{owner}/{repo}/legacy.zip/{リファレンス}`**
  - **目的**: パッケージ実体のダウンロード
  - **通信先**: GitHub
  - **ステータス**: 200
- **`POST https://packagist.org/downloads/`**
  - **目的**: インストール統計の送信（**インストールの成否には影響しません**）
  - **通信先**: 公式サイト
  - **ステータス**: 201

:::info 検証したバージョン
本ページの内容は、2026 年 9 月時点の次のバージョンに基づいています。

- npm v10.8 / v11.19 / v12.0、pnpm v10.33 / v11.25、yarn v1.22 / v4.12 / v4.18、bun v1.4
- pip v22.0 / v26.2、uv v0.12、Poetry v2.4
- Bundler v2.5 / v4.0
- Go v1.23 / v1.27
- Composer v2.10

:::

## 参考情報 {#reference}

### プロキシやファイアウォールの設定について {#proxy-and-firewall}

転送処理では、Takumi Guard 以外にも以下の通信先が使用されます。いずれもパッケージ実体の取得またはチェックサムの検証に必要な通信先であり、到達できない場合はインストールが完了しません。

| ホスト                   | パス                                                                                                                        |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `registry.npmjs.org`     | `/{パッケージ名}/-/*.tgz`<br />`/@{スコープ}/{パッケージ名}/-/*.tgz`                                                        |
| `files.pythonhosted.org` | `/packages/**`                                                                                                              |
| `rubygems.org`           | `/gems/*.gem`<br />`/quick/Marshal.4.8/**`<br />`/specs.4.8.gz`<br />`/latest_specs.4.8.gz`<br />`/prerelease_specs.4.8.gz` |
| `proxy.golang.org`       | `/**/@v/*.zip`                                                                                                              |
| `sum.golang.org`         | 全パス                                                                                                                      |

#### Composer をご利用の場合 {#composer-case}

Composer をご利用の場合、配布元は依存パッケージごとに異なります。そのため、`https://packagist.flatt.tech/p2/{ベンダー}/{パッケージ}.json` の `dist.url` を確認し、依存パッケージごとに通信先を確認・設定する必要があります。

例えば、GitHub 上で公開されているパッケージの場合、以下の通信先が使用されます。

| ホスト                | パス                   |
| --------------------- | ---------------------- |
| `api.github.com`      | `/repos/*/*/zipball/*` |
| `codeload.github.com` | `/*/*/legacy.zip/*`    |

GitHub 以外に配布元を持つパッケージが依存関係に含まれる場合は、その配布元への通信も発生します。

#### プライベートパッケージ（npm・PyPI・RubyGems・Packagist） {#private-packages}

別のレジストリを設定した場合、そのレジストリへ直接接続します。設定方法はエコシステムごとに異なります。

- [npm のプライベートパッケージ](/docs/ja/t/guard/quickstart/npm.md#private-packages)（スコープ別のレジストリ設定）
- [PyPI のプライベートパッケージ](/docs/ja/t/guard/quickstart/pypi.md#private-packages)（Extra Index URL）
- [RubyGems のプライベート gem](/docs/ja/t/guard/quickstart/rubygems.md#private-gems)（`Gemfile` の `source` ブロック）
- [Packagist のプライベートパッケージ](/docs/ja/t/guard/quickstart/packagist.md#private-packages)（リポジトリの宣言）

#### プライベートモジュール（Go） {#private-go-modules}

`GOPRIVATE` に指定したモジュールは、Takumi Guard とチェックサムデータベースのいずれも経由せず、モジュールパスのホストから `git` で直接取得されます。設定方法は[プライベートモジュールと併用する](/docs/ja/t/guard/quickstart/golang.md#private-modules)を参照してください。

#### 通信が発生しないホスト {#no-traffic-hosts}

Takumi Guard を設定した環境では、以下のホストへの通信は発生しません。

| ホスト               | 理由                                                              |
| -------------------- | ----------------------------------------------------------------- |
| `repo.packagist.org` | メタデータは Takumi Guard がサーバー側で取得します                |
| `pypi.org`           | pip・uv、およびリポジトリごとの設定を行った Poetry は通信しません |
| `index.rubygems.org` | Bundler は通信しません                                            |

`packagist.org` へはインストール統計の送信のみが発生します。この通信が届かない場合でも、インストールは完了します。

:::warning サポート範囲について
これらの通信を遮断した場合に発生する不具合については、可能な限り調査・対応に協力いたしますが、場合によってはサポートの対象外となることがございます。
:::