# Packagist {#packagist}

Takumi Guard は [Composer のリポジトリプロトコル](https://getcomposer.org/doc/05-repositories.md#composer)に対応しているため、[Private Packagist](https://packagist.com/) や Toran Proxy などのミラーと同じ要領で `composer install`・`composer update` を経由させることができます。このページでは、ローカル開発環境と CI の両方について、それぞれの利用方法を説明します。

:::info Composer 2.10 以降が必要です
既存の `composer.lock` からのインストールに対するブロックは、Composer 2.10（2026 年 5 月）で追加された依存ポリシー機能を利用します。それより古い Composer では、ブロックは `composer update` や `composer require` には適用されますが、既存ロックファイルからの `composer install` には適用されません。Composer をアップグレードするか、ロックファイルを一度再解決してください（下記参照）。
:::

## 設定方法 {#setup}

Takumi Guard には3つの利用方法があります。

- **[匿名で利用する](#setup-anonymous)**：トークン不要。リポジトリを設定するだけでパッケージブロックが有効になります。
- **[ユーザー登録して利用する](#setup-email-verified)**：メール認証トークン（`tg_anon_…`）を使い、ダウンロード追跡と感染可能性の通知を有効にします。
- **[組織ユーザートークンで利用する](#setup-org-user-token)**：組織ユーザートークン（`tg_org_…`）を使い、組織全体のインストール状況を追跡できます。

:::info 有料機能
組織ユーザートークンを利用するには、Guard を有効化した基本サブスクリプションが必要です。詳しくは[料金と請求](/docs/ja/t/guard/billing/index.md)を参照してください。
:::

### 匿名で利用する {#setup-anonymous}

認証なしで Takumi Guard のパッケージブロック機能を利用できます。プロキシを Composer のリポジトリとして追加し、デフォルトの packagist.org を無効化することで、すべてのパッケージがプロキシ経由で解決されるようになります。

```bash
# Guard プロキシを Composer のリポジトリとして追加する（グローバル設定）
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech

# デフォルトの packagist.org を無効化する。パッケージの二重読み込みを防ぎ、
# ブロックリストを回避する直接フォールバックを起こさないためです。
composer config --global repositories.packagist.org false
```

Composer v2 は packagist.org から取得するはずのパッケージを Guard 経由でミラーします。packagist.org を無効化することで経路が明確になり、ブロックリストを回避する直接フォールバックを防げます。詳しくは[こちら](#why-disable-packagist)をご覧ください。

これで設定は完了です。パッケージブロックは `composer install` と `composer update` の両方に適用され、既存の `composer.lock` からのインストールも対象になります（Composer 2.10 以降）。

**任意：ダウンロード追跡を有効にする**

```bash
composer update mirrors
```

`composer update mirrors` は `composer update --lock` と同じ動作で、パッケージのバージョンを変えずに `composer.lock` 内の dist URL をプロキシ経由に書き換えます。これは**ブロックには不要**で、ダウンロードしたパッケージが後から悪性と判明した際に通知を受け取れるよう、バージョン単位のダウンロード追跡を有効にするためのものです（[ユーザー登録して利用する](#setup-email-verified)を参照）。プロジェクトごとに一度実行してください。実行しなくても、次回の `composer update` 時に自動的に反映されます。

:::tip グローバル設定ではなくプロジェクト単位で設定する
グローバル設定を変更したくない場合は、同じ 2 つの `repositories` エントリをプロジェクトの `composer.json` に直接記述することもできます。

```json
{
  "repositories": [
    { "type": "composer", "url": "https://packagist.flatt.tech" },
    { "packagist.org": false }
  ]
}
```

:::

### ユーザー登録して利用する {#setup-email-verified}

メールアドレスを登録すると、匿名利用のパッケージブロックに加えて、ダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)が利用可能になります。ダウンロードしたパッケージが後から悪性であると判明した場合、登録したメールアドレスに通知が届きます。Shisho Cloud アカウントは不要で、無料で利用できます。

:::info 別のエコシステムで `tg_anon_` トークンを取得済みの場合
お持ちの `tg_anon_` トークンは、そのまま npm / PyPI / RubyGems / Go / Composer いずれのエコシステムでも利用できます。再登録は不要で、下記の **ステップ 3** から進めてください。
:::

**ステップ 1: メールアドレスを登録する**

```bash
curl -X POST https://packagist.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "ja"}'
```

`language` フィールドは省略可能で、デフォルトは `"en"`（英語）です。`"ja"` を指定すると、確認メールや感染可能性の通知を含むすべてのメールが日本語で届きます。この設定はトークンに保存され、以降のメールすべてに適用されます。

数秒以内にウェルカムメールが届きます。

**ステップ 2: メールに記載された API キーを確認する**

API キーはウェルカムメールの本文に直接記載されています。リンクをクリックする必要はなく、すぐに利用できます。

:::warning
このキーは安全な場所に保管してください。新しいキーが必要な場合は、いつでも再生成できます。`curl -X POST -H 'Authorization: Bearer tg_anon_xxxxxx' https://packagist.flatt.tech/api/v1/tokens/regenerate`
:::

**ステップ 3: トークンを送信するよう Composer を設定する**

Composer はホスト名ごとの HTTP Basic 認証でリポジトリに認証します。ユーザー名は無視され、トークンはパスワード欄に入れます。

```bash
# 1. リポジトリを追加する（未設定の場合）
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false

# 2. トークンを保存する（グローバルの auth.json に書き込まれます）
composer config --global --auth http-basic.packagist.flatt.tech token tg_anon_xxxxxx

# 3. ダウンロードをプロキシ経由にし、インストールをトークンに紐づけて追跡する
#    （プロジェクトごとに一度実行。バージョンは変わらず URL のみ更新されます）
composer update mirrors
```

これ以降、Composer はパッケージ取得のたびに `tg_anon_` トークンで認証します。ロックファイルをプロキシ経由にしておくと、インストールが追跡され、ダウンロードした正確なバージョンに対して感染可能性の通知が届きます。

### 組織ユーザートークンで利用する {#setup-org-user-token}

組織ユーザートークン（`tg_org_…`）は、Takumi / Shisho Cloud コンソール、または Bot から Guard API 経由で発行できます。発行方法の詳細は [トークンの管理](/docs/ja/t/guard/features/token-management.md#user-tokens) を参照してください。

:::info
1 つの `tg_org_` トークンは、すべての Takumi Guard エコシステム（npm、PyPI、RubyGems、Go、Composer）で利用できます。別のエコシステムで発行済みであれば、同じトークンをそのまま利用できます。
:::

トークンを取得したら、リポジトリを設定し、トークンを保存します。最後の `composer update mirrors` は任意で、ダウンロードをプロキシ経由にしてインストールをトークンに紐づけて追跡するためのものです。

```bash
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_org_xxxxxx

# 任意（インストール追跡を有効化。ブロックには不要）
composer update mirrors
```

これ以降、`composer install` は組織ユーザートークンで認証し、[組織全体のインストール追跡](/docs/ja/t/guard/features/installation-logs.md)と、組織宛の感染可能性の通知（Slack、Webhook など）が有効になります。

### packagist.org を無効化する理由 {#why-disable-packagist}

公開パッケージのリポジトリは Guard プロキシのみとし、`packagist.org` は無効化してください。

packagist.org を有効なままにすると、Composer はそれを同列のリポジトリとして扱い、パッケージを packagist.org や GitHub から**直接**解決・ダウンロードして、Guard のブロックリストを回避することがあります。無効化することで、すべての公開パッケージが必ず Takumi Guard 経由で解決されるようになります。

なお、組織独自のプライベートパッケージはこのプロキシを経由させるべきではありません。[プライベートパッケージとの併用](#private-packages)で説明するとおり、別の `vcs` リポジトリや `path` リポジトリとして宣言してください。

## GitHub Actions {#setup-ci}

GitHub Actions のワークフローに Takumi Guard を組み込むには、`flatt-security/setup-takumi-guard-packagist` Action を使います。匿名でも、組織と連携しても利用できます。Action はリポジトリ設定とトークン注入を行い、既存の `composer install` がそのまま保護されます。コミット済みのロックファイルに対してもブロックが適用され、移行の手順は不要です（Composer 2.10 以降）。

### 匿名モード {#setup-ci-anonymous}

まだ Shisho Cloud アカウントがなくても、CI でパッケージブロックを利用できます。`bot-id` 入力を省略してください。

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.3"
          tools: composer:v2

      - uses: flatt-security/setup-takumi-guard-packagist@v1
        # bot-id なし — 匿名モード、ブロックのみ

      # 既存のインストールがそのまま保護されます。コミット済みの composer.lock
      # からでもブロック対象のパッケージは拒否されます（Composer 2.10 以降）。移行は不要です。
      - run: composer install --no-interaction
```

匿名モードでは、Action は Composer のリポジトリ設定のみを行います。ブロック対象のパッケージは `composer install` 時に拒否されますが、ダウンロード追跡や[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)は利用できません。

### Shisho Cloud 組織と連携する {#setup-ci-org}

Shisho Cloud 組織と連携すると、組織全体のダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)（Webhook 経由）が利用できます。**CI 環境に長期シークレットを保存する必要はありません。** GitHub OIDC トークンを Shisho Cloud STS サービスで短期アクセストークンに交換することで、安全に認証します。

**事前準備:**

1. Shisho Cloud に登録した Bot アイデンティティ。Shisho Cloud コンソールのレジストリ設定ページから **Bot ID** をコピーします。
2. ワークフローのジョブに `id-token: write` と `contents: read` の権限を付与します。

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC トークン交換に必要
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.3"
          tools: composer:v2

      - uses: flatt-security/setup-takumi-guard-packagist@v1
        with:
          bot-id: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー

      # すぐに保護されます。コミット済みの composer.lock もブロック対象です。
      # （バージョン単位のダウンロード追跡を Bot 認証で行いたい場合は、この前に
      #  `composer update mirrors` を追加してください。）
      - run: composer install --no-interaction
```

Action は OIDC 交換の全体を自動で処理します。

1. GitHub OIDC トークンを取得する（audience はレジストリホスト）
2. STS サービスで短期 Takumi Guard アクセストークンに交換する
3. Composer のリポジトリを設定し、トークンを `COMPOSER_AUTH` に書き込む

:::info
Bot ID はシークレットではありません。トークン交換時に許可リストを参照するための公開された参照キーであり、ワークフローファイルに直接コミットして構いません。Shisho Cloud コンソールでは、Bot ID を埋め込んだコピー可能なワークフロー断片を提供しています。
:::

アクセストークンはデフォルトで 30 分後に失効します（`expires-in` 入力で最大 24 時間まで設定可能）。認証に失敗した場合（`bot-id` の誤り、OIDC 権限の不足、STS への到達不可など）、ステップは明確なエラーメッセージで終了します。匿名モードへ暗黙的にフォールバックすることはありません。

#### Action の入力リファレンス {#action-inputs}

| 入力             | 必須   | デフォルト                     | 説明                                                                                                                                                     |
| ---------------- | ------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bot-id`         | いいえ | —                              | Shisho Cloud の Bot ID。省略すると匿名（ブロックのみ）モードになります。                                                                                 |
| `set-repository` | いいえ | `true`                         | Composer のリポジトリを自分で管理する場合は `false` を指定します。                                                                                       |
| `fail-closed`    | いいえ | `false`                        | `true` を指定すると、Guard プロキシに到達できない場合に `composer install`・`composer update` を素通りさせず失敗させます。Composer 2.10 以降が必要です。 |
| `registry-url`   | いいえ | `https://packagist.flatt.tech` | カスタムレジストリ URL。Shisho Cloud サポートの指示がある場合のみ変更します。                                                                            |
| `sts-url`        | いいえ | `https://sts.cloud.shisho.dev` | OIDC からアクセストークンへの交換に使う STS サービス URL。                                                                                               |
| `expires-in`     | いいえ | `1800`（秒）                   | アクセストークンの有効期間（秒）。最大 `86400`（24 時間）。                                                                                              |

入力・出力の全一覧は [Action リポジトリ](https://github.com/flatt-security/setup-takumi-guard-packagist) を参照してください。

:::tip CI でフェイルクローズドにする（任意）
デフォルトでは、`composer install` の実行中に Guard プロキシへ到達できない場合、Composer は警告を出して処理を続行します（到達できない間はパッケージがブロックされません）。一時的な障害でもインストールを素通りさせたくない場合は、Action の `fail-closed` 入力を指定して CI を失敗させられます。

```yaml
- uses: flatt-security/setup-takumi-guard-packagist@v1
  with:
    fail-closed: true
```

GitHub Actions 以外の環境では、次の設定が同じ動作になります。

```bash
composer config --global policy.ignore-unreachable false
```

さらに多層防御として、パイプラインに `composer audit --locked` を追加することもできます。これはロックファイル内のブロック対象パッケージを報告し、Composer 2.10 より古いバージョンでも機能します。
:::

## プライベートパッケージとの併用 {#private-packages}

Takumi Guard は公開パッケージ向けの読み取り専用セキュリティプロキシです。プロジェクトがプライベートパッケージ（プライベートな GitHub リポジトリや Private Packagist など）に依存している場合は、それらを独自のリポジトリとして宣言し、Guard を経由せず直接取得させます。

```json
{
  "repositories": [
    { "type": "composer", "url": "https://packagist.flatt.tech" },
    { "type": "vcs", "url": "https://github.com/your-org/private-lib" },
    { "packagist.org": false }
  ]
}
```

Composer は各パッケージを、それを提供するリポジトリから解決します。公開パッケージは Takumi Guard を経由し、`vcs` / `path` リポジトリは既存の Git 認証情報を使って直接取得されます。

:::warning
VCS から直接取得されるプライベートパッケージは、Takumi Guard のセキュリティ検査を経由しません。組織独自のパッケージであれば許容できますが、これらのパッケージはブロックリストと照合されない点に注意してください。
:::

## 設定の確認 {#verify-setup}

Composer が Takumi Guard 経由になっているかを確認するには、設定されたリポジトリを確認し、実際の取得がプロキシホストを経由する様子を観察します。

```bash
# 1. Guard リポジトリが設定され、packagist.org が無効化されていることを確認する
composer config --global --list | grep -E 'repositories|packagist'

# 2. ブロックが機能していることを確認する。flatt-security/hola-takumi-php は、
#    当社が公開している無害なテスト用パッケージで、常にブロックリストに登録されています。
#    そのため、このコマンドは必ず失敗します。--dry-run はプロジェクトに書き込まずに解決します。
composer require --dry-run flatt-security/hola-takumi-php
```

2 番目のコマンドは必ず**失敗**し、パッケージがフラグ付けされているためインストールできないと報告されます。もし成功してしまう場合は、リクエストが Takumi Guard を経由していません（手順 1 を再確認してください）。ブロックリストに登録されたパッケージは `composer install`・`composer update`・`composer require` のいずれでも拒否されます（Composer 2.10 以降では、既存ロックファイルからのインストールでも適用されます）。許可されたパッケージの特定バージョンがブロック対象の場合は、そのバージョンが解決から除外されるため、Composer はそのバージョンを選択しません。

## 利用をやめる {#uninstall}

Takumi Guard の利用をやめるには、リポジトリ設定を削除し、デフォルトの Packagist に対して再解決します。

### ローカル環境 {#uninstall-local}

```bash
# 1. Guard リポジトリを削除し、packagist.org を再度有効化する
composer config --global --unset repositories.takumi-guard
composer config --global --unset repositories.packagist.org

# 2. 保存したトークンを削除する
composer config --global --unset --auth http-basic.packagist.flatt.tech

# 3. 各プロジェクトのロックファイルをデフォルトの Packagist で再解決する
composer update mirrors
```

### 組織ユーザートークンの失効 {#uninstall-org-token}

組織ユーザートークン（`tg_org_…`）を利用している場合は、ローカル設定の更新に加えて、Shisho Cloud コンソールの **Guard** > **トークン** からトークンを失効させてください。有効なトークンは課金が継続します。詳しくは [料金](/docs/ja/t/guard/billing/pricing.md) を参照してください。

## クイックリファレンス {#quick-reference}

各利用ティアの最小構成です。`tg_anon_xxxxxx` / `tg_org_xxxxxx` は実際のトークンに置き換えてください。ブロックの設定は 2 行の `composer config` で完了します。末尾の `composer update mirrors` は**任意**で、ダウンロード追跡を有効にするためのものです（プロジェクトごとに一度実行）。

### 匿名 {#quick-reference-anonymous}

```bash
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer update mirrors  # 任意: ダウンロード追跡
```

### 匿名（メール認証） {#quick-reference-email}

```bash
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_anon_xxxxxx
composer update mirrors  # 任意: ダウンロード追跡
```

### 組織 {#quick-reference-org}

```bash
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_org_xxxxxx
composer update mirrors  # 任意: ダウンロード追跡
```