# パッケージのブロック {#package-blocking}

Takumi Guard が悪性と判定したパッケージをリクエストすると、レジストリは `403 Forbidden` エラーを返します。これはすべての認証ティアに適用されます。ブロックは常に有効です。

```
npm ERR! 403 Forbidden - GET https://npm.flatt.tech/test-blocked-pkg/-/test-blocked-pkg-1.0.0.tgz
```

npm はインストール失敗として報告します。パッケージの tarball はダウンロードされません。

ブロックリストのチェックはリクエストされた特定のバージョンに対して適用されます。後続のバージョンがクリーンであれば、そのバージョンを指定してインストールできます。

## リクエストの流れ {#request-flow}

Takumi Guard は、npm クライアントと公開 npm レジストリの間に位置する**透過プロキシ**として動作します。npm クライアントが `npm install` を実行すると、リクエストは**メタデータの取得**と **tarball のダウンロード**の 2 段階で処理されます。

```mermaid
sequenceDiagram
    participant Client as npm クライアント
    participant Guard as Takumi Guard
    participant NPM as 公開 npm レジストリ

    Note over Client,NPM: ① メタデータの取得
    Client->>Guard: GET /lodash
    Guard->>Guard: ブロックリストを照合
    rect rgba(220, 38, 38, 0.08)
    Note right of Guard: ブロック対象の場合
    Guard--xClient: 403 Forbidden
    end
    rect rgba(34, 197, 94, 0.08)
    Note right of Guard: 許可の場合
    Guard->>NPM: メタデータを取得
    NPM-->>Guard: メタデータ（package.json）
    Guard->>Guard: tarball URL を Takumi Guard 経由に書き換え
    Guard-->>Client: メタデータ
    end

    Note over Client,NPM: ② tarball のダウンロード
    Client->>Guard: GET /lodash/-/lodash-4.17.21.tgz
    Guard->>Guard: ブロックリストを照合
    rect rgba(220, 38, 38, 0.08)
    Note right of Guard: ブロック対象の場合
    Guard--xClient: 403 Forbidden
    end
    rect rgba(34, 197, 94, 0.08)
    Note right of Guard: 許可の場合
    Guard-->>Client: 302 リダイレクト（公開 npm レジストリへ）
    Client->>NPM: tarball を直接ダウンロード
    NPM-->>Client: tarball (.tgz)
    end
```

tarball 自体は Takumi Guard を経由せず、クライアントが公開 npm レジストリから直接ダウンロードします。これにより、プロキシの帯域消費を抑えつつ、ブロックチェックを確実に適用しています。

### tarball URL の書き換え {#tarball-url-rewriting}

メタデータ内の tarball ダウンロード URL は Takumi Guard 経由に書き換えられます。これにより、ロックファイルに `registry.npmjs.org` の URL が直接記載されていても、以降のインストールは Takumi Guard を通るようになります。

### パッケージマネージャーとの互換性 {#compatibility}

Takumi Guard は標準的な npm レジストリ API に準拠しているため、npm・pnpm・yarn のいずれからも利用できます。既存のロックファイルを変更する必要はありません。パッケージマネージャーはレジストリ URL ではなく**インテグリティハッシュ**でパッケージを検証するため、レジストリの切り替えによる整合性の問題は発生しません。

### 認証 {#authentication}

Takumi Guard は、リクエストに含まれる認証トークンに応じて動作を切り替えます。

| トークンの種類       | 認証方式                                            | ダウンロード追跡                                    |
| -------------------- | --------------------------------------------------- | --------------------------------------------------- |
| なし（匿名）         | 不要                                                | なし                                                |
| メール認証トークン   | `.npmrc` の `_authToken`                            | トークン単位                                        |
| STS アクセストークン | OIDC 交換（[CI 連携](/docs/ja/t/guard/architecture/oidc.md)参照） | Bot 単位（GitHub リポジトリ・ワークフロー情報付き） |

認証トークンの有無に関わらず、ブロックリストによるパッケージブロックは常に有効です。

## ブロックの基準 {#blocking-criteria}

Takumi Guard のブロックリストは、GMO Flatt Security のセキュリティリサーチチームが独自に調査・収集した情報をもとに構築されています。具体的には、以下のようなパッケージがブロック対象となります。

- **マルウェア**:インストール時や実行時に悪意ある動作（情報窃取、バックドアの設置など）を行うパッケージ
- **タイポスクワッティング**:人気パッケージに酷似した名前を持ち、ユーザーの入力ミスを狙って悪意あるコードを配布するパッケージ
- **侵害済みパッケージ**:正規のパッケージがアカウント乗っ取りなどにより侵害され、悪意あるコードが混入されたバージョン

npm エコシステムにおいては、npm レジストリがパッケージの新規公開・更新をリアルタイムに配信する変更フィード（[Replicate API](https://github.com/npm/registry/blob/main/docs/REPLICATE-API.md)）を継続的に監視し、公開直後のパッケージを即座に取得しています。取得したパッケージはリサーチチームが構築した分析パイプラインにかけられ、悪意ある挙動の有無が判定されます。この仕組みにより、公開されているアドバイザリデータベースだけでは検出できないゼロデイの悪意あるパッケージにも対応できます。

ブロックリストは随時更新されるため、新たに発見された脅威にも迅速に対応します。

## セットアップの確認 {#verify-setup}

Takumi Guard が正しく動作していることを確認するには、テスト用のブロック済みパッケージをインストールしてみてください。

```bash
npm install @panda-guard/test-malicious
```

このパッケージはブロックリストに常時登録されています。Takumi Guard が正しく設定されていれば、npm は `403 Forbidden` エラーを報告し、インストールは失敗します。確認後、`package.json` から安全に削除できます。