# npm {#npm}

Takumi Guard のセットアップは、利用環境と必要な機能に応じて異なります。このページでは、ローカル開発環境と GitHub Actions の両方について、それぞれの利用方法を説明します。

## 設定方法 {#setup}

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

認証なしで Takumi Guard のパッケージブロック機能を利用できます。レジストリ URL を設定するだけで、悪意あるパッケージのブロックが有効になります。ダウンロード追跡や[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)は利用できませんが、最も手軽に導入できる方法です。

プロジェクトの `.npmrc` にレジストリを追加してください。

```ini
registry=https://npm.flatt.tech/
```

またはグローバルに設定します。

```bash
npm config set registry https://npm.flatt.tech/
```

以上です。以降の `npm install` コマンドはすべて Takumi Guard 経由でルーティングされます。

:::tip パッケージマネージャーの互換性
Takumi Guard は **npm**、**pnpm**、**yarn** に対応しています。いずれも `.npmrc` の `registry` 設定を読み取ります。ロックファイルの移行は不要です。パッケージマネージャーはレジストリ URL ではなくインテグリティハッシュでパッケージを検証するため、既存のロックファイルはそのまま使用できます。

**pnpm** の場合は以下でも設定できます。

```bash
pnpm config set registry https://npm.flatt.tech/
```

**yarn** (v1) の場合、`.npmrc` の設定がそのまま反映されます。**yarn berry** (v2+) の場合は `.yarnrc.yml` に追加してください。

```yaml
npmRegistryServer: "https://npm.flatt.tech/"
```

:::

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

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

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

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

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

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

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

API キーはウェルカムメールに直接記載されています。リンクをクリックする手順は不要で、キーはすぐに使用できます。

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

**ステップ 3: npm を設定する**

プロジェクトの `.npmrc` に以下の 2 行を追加します。

```ini
registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_anon_xxxxxx
```

または CLI で設定します。

```bash
npm config set registry https://npm.flatt.tech/
npm config set //npm.flatt.tech/:_authToken tg_anon_xxxxxx
```

以降の `npm install` コマンドはトークンで認証され、ダウンロード追跡と感染可能性の通知が有効になります。

### GitHub Actions で利用する {#setup-ci}

GitHub Actions ワークフローに Takumi Guard を導入するには、`flatt-security/setup-takumi-guard-npm` GitHub Action を使用します。匿名で利用する方法と、組織に紐づけて利用する方法があります。

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

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

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - run: npm install
      - run: npm test
```

匿名モードでは、Action はレジストリ URL の設定のみを行います。ブロック済みパッケージは引き続き 403 エラーで拒否されますが、ダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)は利用できません。

#### 組織に紐づけて利用する {#setup-ci-org}

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

**前提条件:**

1. Shisho Cloud に Bot ID が登録されていること。Shisho Cloud コンソールのレジストリ設定ページから **Bot ID** をコピーしてください。
2. ワークフロージョブに `id-token: write` および `contents: read` 権限が設定されていること。

**ステップ 1: ワークフローに Action を追加する**

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC トークン交換に必要
      contents: read
    steps:
      - uses: actions/checkout@v4

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

      - run: npm install
      - run: npm test
```

Action は OIDC 交換をすべて自動で処理します。

1. GitHub の OIDC トークンをリクエストする
2. STS サービスを通じて Takumi Guard の短命なアクセストークンと交換する
3. そのトークンを使用して npm を Takumi Guard レジストリに向けるよう設定する

:::info
Bot ID はシークレットではありません。トークン交換時にトラスト条件を検索するための公開参照キーです。ワークフローファイルに直接コミットできます。Shisho Cloud コンソールには Bot ID があらかじめ入力された、コピーしてすぐ使えるワークフローのスニペットが用意されています。
:::

アクセストークンのデフォルト有効期限は 30 分です（`expires-in` 入力で最大 24 時間まで設定可能です）。

#### 参考：Action 入力パラメータ {#action-inputs}

| 入力           | 必須   | デフォルト                | 説明                                                                            |
| -------------- | ------ | ------------------------- | ------------------------------------------------------------------------------- |
| `bot-id`       | いいえ | —                         | Shisho Cloud の Bot ID。匿名ブロックモードの場合は省略します。                  |
| `set-registry` | いいえ | `true`                    | `.npmrc` を自分で管理し、認証トークンのみ必要な場合は `false` に設定します。    |
| `registry-url` | いいえ | `https://npm.flatt.tech/` | カスタムレジストリ URL。Shisho Cloud サポートから指示された場合のみ変更します。 |
| `expires-in`   | いいえ | `30m`                     | アクセストークンの有効期間。最大 `24h`。                                        |

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

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

Takumi Guard は公開 npm パッケージ向けの読み取り専用セキュリティプロキシです。プロジェクトがプライベートパッケージに依存している場合は、プライベートパッケージが Takumi Guard を経由せず、直接レジストリから取得されるように `.npmrc` を設定する必要があります。

### スコープ付きプライベートパッケージ {#private-packages-scoped}

npm や pnpm はスコープごとのレジストリルーティングに対応しています。`.npmrc` にスコープ付きのレジストリ設定を追加することで、プライベートパッケージをそれぞれのレジストリから直接取得しつつ、公開パッケージは引き続き Takumi Guard 経由でスキャンできます。

たとえば、`@your-company` スコープのプライベートパッケージを npmjs.org で管理している場合は、以下のように設定してください。

```ini
# 公開パッケージ → Takumi Guard でスキャン
registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_anon_xxxxxx

# プライベートパッケージ → Takumi Guard をバイパスし、直接取得
@your-company:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
```

複数のプライベートスコープがある場合は、スコープごとに行を追加します。

```ini
@your-company:registry=https://registry.npmjs.org/
@your-other-scope:registry=https://registry.npmjs.org/
```

プライベートパッケージが GitHub Packages や Artifactory など別のレジストリにホストされている場合は、そのレジストリを指定してください。

```ini
@your-company:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```

この設定により、パッケージマネージャーは以下のようにリクエストをルーティングします。

- `npm install lodash` → Takumi Guard 経由で取得（セキュリティスキャン適用）
- `npm install @your-company/private-sdk` → プライベートレジストリから直接取得（Takumi Guard をバイパス）

:::warning
別のレジストリにルーティングされたプライベートパッケージは、Takumi Guard のセキュリティスキャンを受けません。自組織のパッケージであれば問題ありませんが、ブロックリストによるチェックが適用されない点にご注意ください。
:::

### スコープなしプライベートパッケージ {#private-packages-unscoped}

npm や pnpm はスコープ単位のレジストリルーティングのみに対応しており、パッケージ単位のルーティングには対応していません。`@scope/` プレフィックスのないスコープなしプライベートパッケージを使用している場合、上記の `.npmrc` による回避策は適用できません。

この場合は、プライベートパッケージをスコープ付きの名前に移行することを推奨します（例: `private-utils` → `@your-company/private-utils`）。スコープ付きパッケージは、npm が組織向けパッケージとして推奨する標準的なアプローチです。

### GitHub Actions でのプライベートパッケージの利用 {#private-packages-ci}

`flatt-security/setup-takumi-guard-npm` Action をプライベートパッケージと併用する場合は、`set-registry` を `false` に設定し、`.npmrc` を手動で管理してください。

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: flatt-security/setup-takumi-guard-npm@v1
        with:
          bot-id: "BT01EXAMPLE..."
          set-registry: false # .npmrc を手動管理

      # レジストリを手動で設定
      - run: |
          echo "registry=https://npm.flatt.tech/" >> .npmrc
          echo "//npm.flatt.tech/:_authToken=${{ steps.guard.outputs.token }}" >> .npmrc
          echo "@your-company:registry=https://registry.npmjs.org/" >> .npmrc
          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" >> .npmrc

      - run: npm install
      - run: npm test
```

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

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

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

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

## パッケージの公開とログイン {#publishing-and-login}

Takumi Guard は読み取り専用のセキュリティプロキシです。`npm login`、`npm publish`、`npm adduser` などの書き込み操作はプロキシ経由では実行できません。これらの操作を行う際は、対象のレジストリを直接指定してください。

```bash
npm login --registry=https://registry.npmjs.org/
npm publish --registry=https://registry.npmjs.org/
```

Takumi Guard をグローバルレジストリに設定している場合でも、公開時には必ず `--registry` フラグを指定して、コマンドが正しいレジストリに送信されるようにしてください。

## アンインストール {#uninstall}

Takumi Guard の利用を停止するには、レジストリ設定を公開 npm レジストリに戻してください。

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

プロジェクトの `.npmrc` から Takumi Guard 関連の行を削除します。

```ini
# 以下の行を削除
registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_anon_xxxxxx
```

グローバル設定を変更していた場合は、以下のコマンドでデフォルトに戻します。

```bash
npm config delete registry
npm config delete //npm.flatt.tech/:_authToken
```

pnpm や yarn berry を使用している場合も同様に、それぞれの設定ファイル（`.npmrc` または `.yarnrc.yml`）から Takumi Guard のレジストリ URL を削除してください。

### GitHub Actions {#uninstall-ci}

ワークフローファイルから `flatt-security/setup-takumi-guard-npm` のステップを削除してください。

```yaml
# 以下のステップを削除
- uses: flatt-security/setup-takumi-guard-npm@v1
  with:
    bot-id: "BT01EXAMPLE..."
```

:::info
レジストリ設定を削除すると、`npm install` は公開 npm レジストリに直接アクセスするようになります。ロックファイルの変更は不要です。
:::