# Breach Notifications {#breach-notifications}

A **breach notification** is sent when a security advisory is published for a package that you previously downloaded through Takumi Guard. This can happen when a package that was considered safe at the time of download is later found to be malicious or compromised.

## How You Receive Notifications {#notification-methods}

Notification delivery depends on how you use Takumi Guard.

### Email-Verified Users {#breach-email}

If you authenticated with an email-verified token when you downloaded the package, Takumi Guard sends an email notification to your registered address. The email includes:

- The package name and version you downloaded
- When you downloaded it
- Why it was flagged (malware type or vulnerability description)
- Recommended action (remove the package, audit your environment, etc.)

No action is required on your part to enable this — breach notifications are automatic for all email-verified tokens.

### GitHub Actions + Bot ID Users {#breach-webhook}

For downloads attributed to a bot identity linked to a Shisho Cloud organization via GitHub Actions, organization-level webhook notifications will be available in the future. Webhook destinations and authentication settings will be configurable from the Shisho Cloud console.

### Other Cases {#breach-none}

If you use Takumi Guard anonymously (without authentication), downloads are not attributed to any identity, so you cannot receive breach notifications. To receive notifications, set up [email registration](/docs/t/guard/quickstart/npm.md#setup-email-verified) or [Bot ID integration with GitHub Actions](/docs/t/guard/quickstart/npm.md#setup-ci-org).

## Notification Flow {#breach-flow}

When a new advisory is published:

1. Takumi Guard queries the download history for the affected package and version.
2. It identifies all tokens that downloaded the package before the advisory was published.
3. For each affected token, it sends a notification to the associated destination (email address, etc.).

```mermaid
sequenceDiagram
    participant User as User
    participant Guard as Takumi Guard
    participant NPM as Public npm Registry
    participant DB as Download History

    Note over User,NPM: At package installation
    User->>Guard: npm install example-pkg
    Guard->>NPM: Proxy request
    NPM-->>Guard: Package tarball
    Guard->>DB: Record download (token, package, version, timestamp)
    Guard-->>User: Package tarball

    Note over Guard,DB: When advisory is published
    Guard->>DB: Query affected download history
    DB-->>Guard: List of affected tokens
    Guard->>User: Email notification
```

:::info
Only tarball downloads (`.tgz`) are tracked — metadata requests (checking package info without installing) are not recorded. This means notifications reflect actual code execution risk.
:::