# Identity Watchlist

## Implementation Status

- Status: `shipped`
- Owner shell: `Setup > Trust & Signing`
- Canonical routes:
  - `/setup/trust-signing/watchlist/entries`
  - `/setup/trust-signing/watchlist/alerts`
  - `/setup/trust-signing/watchlist/tuning`
- Secondary entry points:
  - `Mission Control > Alerts` deep-links into `Alerts`
  - `Ops > Notifications` deep-links into `Tuning` and `Alerts`

## Recommendation

Restore Watchlist as a narrow operational shell owned by `Setup > Trust & Signing`, not as a standalone top-level product.

- Canonical mount: `/setup/trust-signing/watchlist`
- Suggested user-facing title: `Identity Watchlist`
- Suggested nav label: `Watchlist`

This capability is primarily about trust policy administration around signer identities, with alert outcomes surfaced into `Mission Control` and `Ops > Notifications`.

## Why This Is The Right Shape

- The current implementation already supports CRUD, pattern testing, scope, severity, deduplication, and alert history.
- Those are configuration and trust-governance behaviors, not a broad cross-product workspace.
- The supporting runbook and Attestor guide describe watchlist as an operator control around identities and alerting hygiene.
- The best product shape is one owned shell with secondary visibility in alert-centric surfaces.

## Operator Modes

### 1. Tenant Trust Mode
- Used by tenant operators tuning their own issuer, SAN, or key-id watch rules.
- Focus: entries, scopes, severity, enable/disable, and match testing.

### 2. Platform Trust Admin Mode
- Used by system admins managing global and system-scoped entries.
- Focus: global coverage, noisy patterns, dedup performance, and notification routing.

### 3. Incident Triage Mode
- Entered from `Mission Control > Alerts` or `Ops > Notifications`.
- Focus: alert detail, matched identity context, and jumping back into the owning watchlist rule.

## Recommended IA

### Primary tabs
- `Entries`
  - list, filter, create, edit, enable/disable, delete, and test matching rules
- `Alerts`
  - recent watchlist alerts, alert severity, tenant/source context, and jump-to-entry actions
- `Tuning`
  - dedup windows, notification channels, alert volume controls, and performance guidance

### Header context
- scope switcher: `Tenant`, `Global`, `System`
- summary chips:
  - enabled entries
  - alerts last 24h
  - suppression ratio
  - scan latency p99

## Page Anatomy

### Entries tab
- left: searchable/filterable table with scope, match mode, severity, enabled state, and recent-match count
- right: split detail panel or drawer for create/edit
- row actions:
  - enable/disable
  - edit
  - duplicate
  - delete
  - test pattern

### Alerts tab
- top filters:
  - severity
  - time window
  - scope
  - tenant
  - suppression state
- main list:
  - alert time
  - matched entry
  - signer identity
  - source channel
  - dedup status
- detail drawer:
  - raw match context
  - related entry
  - recent similar alerts
  - jump to Mission Control or Notifications if needed

### Tuning tab
- cards for:
  - dedup effectiveness
  - scan latency
  - top noisy rules
  - notification channel health
- forms for:
  - default dedup window
  - per-severity channel overrides
  - alert storm guidance

## Route Contract

Keep one canonical route family under trust/signing setup.

### Canonical routes
- `/setup/trust-signing/watchlist`
- `/setup/trust-signing/watchlist/entries`
- `/setup/trust-signing/watchlist/alerts`
- `/setup/trust-signing/watchlist/tuning`

### Query-param state
- `tab=entries|alerts|tuning`
- `scope=tenant|global|system`
- `entryId=<id>` for opening the edit drawer
- `alertId=<id>` for opening the alert detail drawer
- `returnTo=<encoded route>` when entered from Mission Control or Notifications

### Alias and entry rules
- `Mission Control > Alerts` should deep-link into `?tab=alerts&alertId=...`
- `Ops > Notifications` should deep-link into `?tab=tuning`
- no separate sidebar product or parallel route family should exist

## What To Merge

### Merge into `Entries`
- `WatchlistPageComponent` list mode
- existing create/edit form
- existing pattern test behavior

### Merge into `Alerts`
- `WatchlistPageComponent` alert table and alert drill-down behavior

### Merge into `Tuning`
- duplicate-suppression controls
- notification behavior controls
- runbook-driven KPIs and tuning guidance

## Single Actions And Supporting Surfaces

### Create or edit rule
- use a drawer or split detail panel inside `Entries`
- add a standalone route only if audit/history requires a permalink

### Test pattern
- keep inside the edit experience
- never give it a dedicated page

### Alert detail
- open as a drawer from `Alerts`
- preserve deep links via `alertId`

### Dedup diagnostics
- keep in `Tuning`
- optionally expose summary KPIs in `Ops > Notifications`

## Cross-Product Entry Points

- `Mission Control > Alerts`
  - watchlist source chip opens the `Alerts` tab
- `Ops > Notifications`
  - channel health card links to `Tuning`
- `Security` or `Evidence` surfaces
  - only deep-link to alert detail when a signer-identity event matters to an investigation

## UI Standards For Implementation

- Use one shell component with tabbed child routes or stable tab state.
- Preserve scope awareness in header and filters.
- Support list/detail without forcing route churn for every edit.
- Keep alert outcomes visible in mission/notification surfaces without duplicating the configuration shell.
- Preserve deterministic sort order for entries and alerts.

## Non-Goals

- Do not make Watchlist a top-level sidebar product.
- Do not split configuration and alert history across different owner areas.
- Do not move trust ownership into Mission Control.

## Source Inputs

- `docs/modules/attestor/guides/identity-watchlist.md`
- `docs/operations/watchlist-monitoring-runbook.md`
- `docs/features/checked/web/identity-watchlist-management-ui.md`
- `src/Web/StellaOps.Web/src/app/features/watchlist/watchlist-page.component.ts`
- `src/Web/StellaOps.Web/src/app/routes/mission-control.routes.ts`
- `src/Web/StellaOps.Web/src/app/routes/operations.routes.ts`