# Package Blocking {#package-blocking}

When you request a package that Takumi Guard has identified as malicious, the registry returns a `403 Forbidden` error. This applies to all authentication tiers — blocking is always on.

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

npm will report the install as failed. The package tarball is never downloaded.

Blocklist checks apply to the specific version requested. If a later version of a package is clean, you can pin to that version and install it normally.

## Request Flow {#request-flow}

Takumi Guard operates as a **transparent proxy** between your npm client and the public npm registry. When your npm client runs `npm install`, requests are processed in two stages: **metadata retrieval** and **tarball download**.

```mermaid
sequenceDiagram
    participant Client as npm Client
    participant Guard as Takumi Guard
    participant NPM as Public npm Registry

    Note over Client,NPM: ① Metadata retrieval
    Client->>Guard: GET /lodash
    Guard->>Guard: Check blocklist
    rect rgba(220, 38, 38, 0.08)
    Note right of Guard: If blocked
    Guard--xClient: 403 Forbidden
    end
    rect rgba(34, 197, 94, 0.08)
    Note right of Guard: If allowed
    Guard->>NPM: Fetch metadata
    NPM-->>Guard: Metadata (package.json)
    Guard->>Guard: Rewrite tarball URLs to route through Guard
    Guard-->>Client: Metadata
    end

    Note over Client,NPM: ② Tarball download
    Client->>Guard: GET /lodash/-/lodash-4.17.21.tgz
    Guard->>Guard: Check blocklist
    rect rgba(220, 38, 38, 0.08)
    Note right of Guard: If blocked
    Guard--xClient: 403 Forbidden
    end
    rect rgba(34, 197, 94, 0.08)
    Note right of Guard: If allowed
    Guard-->>Client: 302 Redirect (to public npm registry)
    Client->>NPM: Download tarball directly
    NPM-->>Client: Tarball (.tgz)
    end
```

Tarballs are not proxied through Takumi Guard — the client downloads them directly from the public npm registry. This minimizes proxy bandwidth while ensuring blocklist checks are always enforced.

### Tarball URL Rewriting {#tarball-url-rewriting}

Tarball download URLs in metadata are rewritten to route through Takumi Guard. This ensures that even if your lockfile contains direct `registry.npmjs.org` URLs, subsequent installs are routed through Takumi Guard.

### Package Manager Compatibility {#compatibility}

Takumi Guard implements the standard npm registry API, so it works with npm, pnpm, and yarn. No lockfile migration is required — package managers verify packages using **integrity hashes**, not registry URLs, so switching registries does not cause integrity issues.

### Authentication {#authentication}

Takumi Guard adjusts its behavior based on the authentication token included in the request:

| Token Type           | Auth Method                                                   | Download Tracking                            |
| -------------------- | ------------------------------------------------------------- | -------------------------------------------- |
| None (anonymous)     | Not required                                                  | None                                         |
| Email-verified token | `_authToken` in `.npmrc`                                      | Per token                                    |
| STS access token     | OIDC exchange (see [CI Integration](/docs/t/guard/architecture/oidc.md)) | Per bot (with GitHub repo/workflow metadata) |

Package blocking via the blocklist is always active regardless of authentication.

## Blocking Criteria {#blocking-criteria}

The Takumi Guard blocklist is built from research conducted by the GMO Flatt Security research team. The following types of packages are blocked:

- **Malware**: Packages that perform malicious actions during installation or execution (credential theft, backdoor installation, etc.)
- **Typosquatting**: Packages with names similar to popular packages that distribute malicious code by exploiting user typos
- **Compromised packages**: Legitimate packages with versions containing injected malicious code due to account takeover

For the npm ecosystem, the change feed ([Replicate API](https://github.com/npm/registry/blob/main/docs/REPLICATE-API.md)) that streams package publications and updates in real time from the npm registry is continuously monitored, and newly published packages are fetched immediately. Fetched packages are run through an analysis pipeline built by the research team to determine the presence of malicious behavior. This enables detection of zero-day malicious packages that are not yet listed in public advisory databases.

The blocklist is updated continuously, ensuring rapid response to newly discovered threats.

## 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.