# npm {#npm}

Takumi Guard setup varies depending on your environment and the features you need. This page covers setup for both local development and GitHub Actions.

## Setup {#setup}

### Anonymous Usage {#setup-anonymous}

You can use Takumi Guard's package blocking without authentication. Simply set the registry URL to enable malicious package blocking. Download tracking and [breach notifications](/docs/t/guard/features/breach-notifications.md) are not available, but this is the easiest way to get started.

Add the registry to your project's `.npmrc`:

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

Or set it globally:

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

That's it. All `npm install` commands now route through Takumi Guard.

:::tip Package Manager Compatibility
Takumi Guard works with **npm**, **pnpm**, and **yarn**. All three read the `registry` setting from `.npmrc`. No lockfile migration is needed — existing lockfiles continue to work because package managers verify packages by integrity hash, not by registry URL.

For **pnpm**, you can also set it via:

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

For **yarn** (v1), the `.npmrc` setting is respected. For **yarn berry** (v2+), add to `.yarnrc.yml`:

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

:::

### Email-Verified Access {#setup-email-verified}

Registering your email address enables download tracking and [breach notifications](/docs/t/guard/features/breach-notifications.md) in addition to package blocking. If a security advisory is published for a package you previously downloaded, a notification is sent to your registered email address. No Shisho Cloud account is required, and this is free of charge.

**Step 1: Register your email**

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

The `language` field is optional and defaults to `"en"`. Set it to `"ja"` to receive emails in Japanese. This preference is stored with your token and applies to all future emails, including breach notifications.

You'll receive a welcome email within a few seconds.

**Step 2: Get your API key from the email**

Your API key is included directly in the welcome email. The key is ready to use immediately — no link to click.

:::warning
Save this key somewhere secure. If you need a new one, you can regenerate it anytime: `curl -X POST -H 'Authorization: Bearer tg_anon_xxxxxx' https://npm.flatt.tech/api/v1/tokens/regenerate`
:::

**Step 3: Configure npm**

Add both lines to your project's `.npmrc`:

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

Or configure via the CLI:

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

Your `npm install` commands now authenticate with your token, enabling download tracking and breach notifications.

### GitHub Actions {#setup-ci}

To integrate Takumi Guard into your GitHub Actions workflow, use the `flatt-security/setup-takumi-guard-npm` GitHub Action. You can use it anonymously or linked to an organization.

#### Anonymous Mode {#setup-ci-anonymous}

If you don't have a Shisho Cloud account yet, you can still use Takumi Guard in CI for package blocking. Omit the `bot-id` input:

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

      - uses: flatt-security/setup-takumi-guard-npm@v1
        # No bot-id — anonymous mode, blocking only

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

In anonymous mode, the action only configures the registry URL. Blocked packages are still rejected with a 403 error, but download tracking and [breach notifications](/docs/t/guard/features/breach-notifications.md) are not available.

#### With Shisho Cloud Organization {#setup-ci-org}

Linking to a Shisho Cloud organization enables organization-level download tracking and [breach notifications](/docs/t/guard/features/breach-notifications.md) (via webhook). No long-lived secrets need to be stored in your CI environment. Authentication is performed securely by exchanging a GitHub OIDC token for a short-lived access token via the Shisho Cloud STS service.

**Prerequisites:**

1. A bot identity registered in Shisho Cloud. Copy the **Bot ID** from the registry settings page in the Shisho Cloud console.
2. The `id-token: write` and `contents: read` permissions in your workflow job.

**Step 1: Add the action to your workflow**

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

      - uses: flatt-security/setup-takumi-guard-npm@v1
        with:
          bot-id: "BT01EXAMPLE..." # Copy from Shisho Cloud console

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

The action handles the full OIDC exchange automatically:

1. Requests a GitHub OIDC token
2. Exchanges it for a short-lived Takumi Guard access token via the STS service
3. Configures npm to use the Takumi Guard registry with that token

:::info
The Bot ID is not a secret — it is a public reference key used to look up the allowlist during token exchange. You can commit it directly in your workflow file. The Shisho Cloud console provides a ready-to-copy workflow snippet with the Bot ID pre-filled.
:::

The access token expires after 30 minutes by default (configurable up to 24 hours via the `expires-in` input).

#### Action Inputs Reference {#action-inputs}

| Input          | Required | Default                   | Description                                                                  |
| -------------- | -------- | ------------------------- | ---------------------------------------------------------------------------- |
| `bot-id`       | No       | —                         | Bot ID from Shisho Cloud. Omit for anonymous blocking-only mode.             |
| `set-registry` | No       | `true`                    | Set to `false` if you manage `.npmrc` yourself and only need the auth token. |
| `registry-url` | No       | `https://npm.flatt.tech/` | Custom registry URL. Override only if directed by Shisho Cloud support.      |
| `expires-in`   | No       | `30m`                     | Access token lifetime. Maximum `24h`.                                        |

For the full list of inputs and outputs, see the [action repository](https://github.com/flatt-security/setup-takumi-guard-npm).

## Using with Private Packages {#private-packages}

Takumi Guard is a read-only security proxy for public npm packages. If your project depends on private packages, you need to configure your `.npmrc` so that private packages bypass Takumi Guard and are fetched directly from their registry.

### Scoped Private Packages {#private-packages-scoped}

npm and pnpm support per-scope registry routing. By adding a scoped registry entry to your `.npmrc`, you can route private packages directly to their registry while public packages continue to go through Takumi Guard.

For example, if your organization uses the `@your-company` scope for private packages on npmjs.org:

```ini
# Public packages → scanned by Takumi Guard
registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_anon_xxxxxx

# Private packages → bypass Takumi Guard, fetch directly
@your-company:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
```

If you have multiple private scopes, add a line for each:

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

If your private packages are hosted on a different registry such as GitHub Packages or Artifactory, point the scope to that registry instead:

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

With this configuration, package managers route requests as follows:

- `npm install lodash` → fetched via Takumi Guard (security scanning applied)
- `npm install @your-company/private-sdk` → fetched directly from your private registry (bypasses Takumi Guard)

:::warning
Private packages routed to a different registry bypass Takumi Guard's security scanning. This is acceptable for your organization's own packages, but be aware that those packages will not be checked against the blocklist.
:::

### Unscoped Private Packages {#private-packages-unscoped}

npm and pnpm only support per-scope registry routing, not per-package routing. If your project depends on unscoped private packages (packages without an `@scope/` prefix), the `.npmrc` workaround described above does not apply.

In this case, we recommend migrating your private packages to use scoped names (e.g., `private-utils` → `@your-company/private-utils`). Scoped packages are the standard approach recommended by npm for organizational packages.

### GitHub Actions with Private Packages {#private-packages-ci}

When using the `flatt-security/setup-takumi-guard-npm` action with private packages, set `set-registry` to `false` and manage your `.npmrc` manually:

```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 # Manage .npmrc manually

      # Configure registries manually
      - 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 Your Setup {#verify-setup}

You can confirm that Takumi Guard is working by attempting to install a known test package:

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

This package is permanently on the blocklist. If Takumi Guard is configured correctly, npm will report a `403 Forbidden` error and the install will fail. You can safely remove it from your `package.json` afterward.

## Publishing and Login {#publishing-and-login}

Takumi Guard is a read-only security proxy. Write operations such as `npm login`, `npm publish`, and `npm adduser` are not supported through the proxy. When performing these operations, specify the target registry directly:

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

If you set Takumi Guard as your global registry and need to publish, always pass the `--registry` flag to ensure the command goes to the correct registry.

## Uninstall {#uninstall}

To stop using Takumi Guard, revert your registry settings to the public npm registry.

### Local Environment {#uninstall-local}

Remove the Takumi Guard lines from your project's `.npmrc`:

```ini
# Remove the following lines
registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_anon_xxxxxx
```

If you changed the global configuration, reset it to the default:

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

If you use pnpm or yarn berry, similarly remove the Takumi Guard registry URL from the respective config files (`.npmrc` or `.yarnrc.yml`).

### GitHub Actions {#uninstall-ci}

Remove the `flatt-security/setup-takumi-guard-npm` step from your workflow file:

```yaml
# Remove the following step
- uses: flatt-security/setup-takumi-guard-npm@v1
  with:
    bot-id: "BT01EXAMPLE..."
```

:::info
Once the registry setting is removed, `npm install` will access the public npm registry directly. No lockfile changes are required.
:::