# Threat Model — `<SUBSYSTEM-NAME>`

**Status:** `Draft | Active | Deprecated` &nbsp;**Date:** `<YYYY-MM-DD>`
&nbsp;**Owner:** `eng-<domain>` &nbsp;**Reviewers:** `eng-platform`,
`eng-security` &nbsp;**Backlog item:** `<V1-P2-NNNN>` &nbsp;**Methodology:**
STRIDE

> This file is the V1-P2-0373 threat-model **template**. Every Tier-A subsystem
> in `docs/releases/v1/specs/todos-p2.md` Part III owns a populated copy at
> `docs/<domain>/security/<subsystem>-threat-model.md`. The header above is
> mandatory; reviewers from `eng-platform` and `eng-security` must sign off (PR
> approval) before the doc moves from Draft to Active. Empty `[FILL IN]` blocks
> are not acceptable in an Active threat model.

## 1. Subsystem at a glance

- **Purpose.** [FILL IN: one-sentence summary, identical to §1 of the
  subsystem's runbook.]
- **Code locations.** [FILL IN: `libs/<x>/...` and `apps/<x>/...` paths.]
- **External callers.** [FILL IN: every domain or external client.]
- **External dependencies.** [FILL IN: every vendor API + every shared
  infrastructure component.]
- **Operating runbook.** [FILL IN: link to the subsystem's runbook generated
  from `runbook-template.md` (V1-P2-0372).]
- **Cross-references.**
  - [`architecture-overview.md`](./architecture-overview.md) — the canonical
    Phase-2 data flows; this threat model focuses only on the flows that pass
    through this subsystem.
  - [`isis-cost-tracking-contract.md`](./isis-cost-tracking-contract.md) — for
    any subsystem that issues paid provider calls, the cost-tracking contract is
    the authoritative quota policy.
  - [`crypto-replacement-targets.md`](./crypto-replacement-targets.md) — for
    subsystems that currently use stub crypto, this lists the migration path
    that this threat model **must** require by the time it goes Active.

## 2. Assets

A threat model is a list of bad things that could happen to the assets this
subsystem processes. List every asset at the granularity an attacker would
target.

| Asset                                 | Classification                                     | Description | Owner             | Impact if compromised                       |
| ------------------------------------- | -------------------------------------------------- | ----------- | ----------------- | ------------------------------------------- |
| [FILL IN: e.g. "User session tokens"] | [FILL IN: Restricted/Confidential/Internal/Public] | [FILL IN]   | [FILL IN: domain] | [FILL IN: account takeover, session hijack] |
| [FILL IN]                             | [FILL IN]                                          | [FILL IN]   | [FILL IN]         | [FILL IN]                                   |

**Classification levels.**

- `Restricted` — secrets, keys, password hashes, payment credentials. Loss is
  "stop the world" severity.
- `Confidential` — user-private data (PII, conversations, biometrics, generated
  content with provenance).
- `Internal` — non-public configuration and operational state.
- `Public` — published platform data (course catalog, marketplace listings).

## 3. Trust boundaries

Reproduce or reference the trust boundaries documented in
[`architecture-overview.md` § Trust boundaries](./architecture-overview.md#trust-boundaries).
Then document any subsystem-specific boundaries.

```
[FILL IN: subsystem-specific trust-boundary diagram. Use ASCII or
Mermaid. Mark every boundary that an attacker must cross to reach an
asset listed in §2. Annotate each boundary with the authentication
mechanism (JWT / mTLS / signed event / Vault token) and the
authorisation mechanism (RBAC scope / tenant ownership check).]
```

## 4. Data flow diagram

A DFD is the visualisation of how data, requests, and credentials move through
the subsystem. Mark every place data crosses a trust boundary (§3) — those are
the canonical attack surfaces.

```
[FILL IN: Mermaid or ASCII DFD. Each node is a process / data store;
each edge is a data flow labelled with what is on the wire (request
shape, encoding, auth mechanism). Trust boundaries are annotated
where edges cross them.]
```

> **Tip.** Copy the relevant slice from
> [`architecture-overview.md`](./architecture-overview.md) and specialise. If
> the subsystem is part of the LLM gateway flow, copy the "Caller →
> IsisLLMClient → Provider" diagram and mark every credential store and trust
> boundary on it.

## 5. STRIDE threat analysis

For each STRIDE category, list every applicable threat. **A category with zero
threats must be justified** — at minimum write
`_Not applicable because <reason>_`. Empty categories are a code smell that the
analysis is incomplete.

### 5.1 Spoofing — pretending to be someone else

| ID  | Threat                                         | Affected asset        | Vector                                                          | Likelihood              | Severity  | Mitigation                                                                                                                   | Detection                                                                     |
| --- | ---------------------------------------------- | --------------------- | --------------------------------------------------------------- | ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| S1  | [FILL IN: e.g. "Forged JWT bypasses BFF auth"] | [FILL IN: ref §2 row] | [FILL IN: e.g. "Stolen JWT signing key + replay before expiry"] | [FILL IN: Low/Med/High] | [FILL IN] | [FILL IN: e.g. "JWT signed by `auth-orchestrator` only; key in Vault, rotated every 90d; aud + iss claim binding to tenant"] | [FILL IN: e.g. "Sigma rule on auth log; anomaly detection on `iss` mismatch"] |
| S2  | [FILL IN]                                      | [FILL IN]             | [FILL IN]                                                       | [FILL IN]               | [FILL IN] | [FILL IN]                                                                                                                    | [FILL IN]                                                                     |

### 5.2 Tampering — altering data in transit or at rest

| ID  | Threat                                             | Affected asset | Vector                                                                                        | Likelihood | Severity  | Mitigation                                                                                                                                                        | Detection                                                          |
| --- | -------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- | ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| T1  | [FILL IN: e.g. "Subscriber projects forged event"] | [FILL IN]      | [FILL IN: e.g. "Compromised producer service publishes spoofed event with arbitrary payload"] | [FILL IN]  | [FILL IN] | [FILL IN: e.g. "Event envelopes signed by source domain (V1-P2-0176 crypto replacement); subscriber verifies signature before applying; reject on bad signature"] | [FILL IN: e.g. "Counter alert on `signature_verification_failed`"] |
| T2  | [FILL IN]                                          | [FILL IN]      | [FILL IN]                                                                                     | [FILL IN]  | [FILL IN] | [FILL IN]                                                                                                                                                         | [FILL IN]                                                          |

### 5.3 Repudiation — denying having performed an action

| ID  | Threat                                                                            | Affected asset | Vector                                                         | Likelihood | Severity  | Mitigation                                                                                                            | Detection                                                                         |
| --- | --------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| R1  | [FILL IN: e.g. "User denies submitting a generation request that consumed quota"] | [FILL IN]      | [FILL IN: "Audit gap — request not logged with user identity"] | [FILL IN]  | [FILL IN] | [FILL IN: "BFF logs every request with `correlationId` + `userId` + idempotency key; logs immutable for 90d in Loki"] | [FILL IN: "Customer support tooling correlates `correlationId` to the audit row"] |

### 5.4 Information Disclosure — exposing data to unauthorised parties

| ID  | Threat                                            | Affected asset | Vector                                                                               | Likelihood | Severity  | Mitigation                                                                                                                                                                                   | Detection                                                                                           |
| --- | ------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------ | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| I1  | [FILL IN: e.g. "Cross-tenant query in domain DB"] | [FILL IN]      | [FILL IN: "Missing `tenant_id` filter in query lets one tenant read another's rows"] | [FILL IN]  | [FILL IN] | [FILL IN: "Drizzle query helpers always inject `tenant_id` from request context (V1-P2-0233); RLS enforced at PostgreSQL layer; integration test asserts cross-tenant fetch returns 0 rows"] | [FILL IN: "Query log scans for missing `tenant_id` filter; anomaly alert on per-tenant row counts"] |
| I2  | [FILL IN: e.g. "Vendor API key leak in logs"]     | [FILL IN]      | [FILL IN: "Stack trace or error response includes the bearer token"]                 | [FILL IN]  | [FILL IN] | [FILL IN: "`@oshun/http-client` redacts Authorization headers in logs by default; pino redact config covers known secret keys; `external-api-guard` (V1-P2-0358) enforces wrapped calls"]    | [FILL IN: "Loki query alert on Authorization-header-shape strings"]                                 |

### 5.5 Denial of Service — making the subsystem unavailable

| ID  | Threat                                                 | Affected asset | Vector                                                                                                                   | Likelihood | Severity  | Mitigation                                                                                                                                                                                | Detection                                                                                              |
| --- | ------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| D1  | [FILL IN: e.g. "Per-tenant cost-quota bypass"]         | [FILL IN]      | [FILL IN: "Bug or stub in cost-tracking middleware (V1-P2-0005) lets one tenant consume the platform-wide cost ceiling"] | [FILL IN]  | [FILL IN] | [FILL IN: "Quota check is enforced at gateway layer; deterministic-mode unit test asserts refusal at boundary; platform-wide ceiling per runbook §7.2 short-circuits before vendor call"] | [FILL IN: "Cost-quota burn panel (Grafana isis/generation-pipeline.json); per-tenant burn-rate alert"] |
| D2  | [FILL IN: e.g. "Subscriber backlog stalls projection"] | [FILL IN]      | [FILL IN: "Slow downstream blocks all subscribers on the same consumer group"]                                           | [FILL IN]  | [FILL IN] | [FILL IN: "Per-event-type consumer group; idempotent handlers; PXSEEK / `XAUTOCLAIM` for stalled members"]                                                                                | [FILL IN: "Stream lag alert at 10× SLO; runbook §10 playbook"]                                         |

### 5.6 Elevation of Privilege — gaining unauthorised access

| ID  | Threat                                                            | Affected asset | Vector                                                              | Likelihood | Severity  | Mitigation                                                                                                                                  | Detection                                                                 |
| --- | ----------------------------------------------------------------- | -------------- | ------------------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| E1  | [FILL IN: e.g. "Free-tier tenant escalates to Enterprise quota"]  | [FILL IN]      | [FILL IN: "Tenant claim in JWT not re-checked on every quota call"] | [FILL IN]  | [FILL IN] | [FILL IN: "Tier resolution from authoritative `tenant_db` per request (cache TTL ≤ 60s); cost-tracking middleware refuses on missing tier"] | [FILL IN: "Audit log scan for tier transitions outside the upgrade flow"] |
| E2  | [FILL IN: e.g. "Worker container reads another domain's secrets"] | [FILL IN]      | [FILL IN: "Vault role mis-bound to wider scope"]                    | [FILL IN]  | [FILL IN] | [FILL IN: "Vault roles scoped per service; least-privilege ACL; CI scan on Vault policy diffs"]                                             | [FILL IN: "Vault audit log alert on cross-domain secret reads"]           |

## 6. Threat scenarios

A scenario is a step-by-step walk-through of how an attacker chains threats from
§5. Document at least three high-priority scenarios (one per
"loss-of-everything" asset).

### 6.1 Scenario — [FILL IN: short title, e.g. "Cost-quota bypass via free-tier escalation"]

**Pre-conditions.** [FILL IN: e.g. "Attacker has a free-tier tenant and a stolen
JWT signing key from a separate compromise."]

**Steps.**

1. [FILL IN: e.g. "Attacker forges JWT with `tier=enterprise` claim."]
2. [FILL IN: e.g. "BFF accepts the JWT; quota middleware reads tier from JWT
   instead of `tenant_db`."]
3. [FILL IN: e.g. "Attacker burns the daily platform-wide cost ceiling in 4
   minutes via parallel LLM calls."]

**Impact.** [FILL IN: e.g. "$1,500 vendor cost; legitimate tenants served 503
until cap is raised; status-page incident."]

**Mitigations engaged.** [FILL IN: refer to S1 + E1 + D1 from §5.]

**Residual risk.** [FILL IN: state what's still possible after the mitigations
land. e.g. "If JWT key leaks AND tenant_db is unreachable (graceful-degradation
path), middleware fails-open to JWT tier — risk reduced to ≤ a vendor outage
window."]

### 6.2 Scenario — [FILL IN]

…

### 6.3 Scenario — [FILL IN]

…

## 7. Risk register

The risk register is the executive-summary view: every threat from §5 plotted on
the L×S matrix.

| ID  | Threat (1-line) | Likelihood | Severity  | Risk                                   | Owner     | Status                                           | Linked PRs / tickets           |
| --- | --------------- | ---------- | --------- | -------------------------------------- | --------- | ------------------------------------------------ | ------------------------------ |
| S1  | [FILL IN]       | [FILL IN]  | [FILL IN] | [FILL IN: L×S → Low/Med/High/Critical] | [FILL IN] | [FILL IN: Open / Mitigating / Closed / Accepted] | [FILL IN: V1-P2-NNNN, PR#NNNN] |

**Risk policy.**

- `Critical` (L=High, S=High) — block release until mitigated.
- `High` — must have a backlog ticket and a target sprint.
- `Medium` — quarterly review; can ship with documented residual risk.
- `Low` — annual review; tracked in this register only.
- `Accepted` — explicit business-stakeholder sign-off required, with the
  rationale captured in §8.

## 8. Accepted risks

Risks that the business has explicitly chosen to accept rather than mitigate.
Each line requires sign-off from `eng-security` and the domain lead.

| ID (§7)   | Rationale | Accepted by            | Date      | Re-review trigger                                      |
| --------- | --------- | ---------------------- | --------- | ------------------------------------------------------ |
| [FILL IN] | [FILL IN] | [FILL IN: name + role] | [FILL IN] | [FILL IN: e.g. "On the next vendor SLA renegotiation"] |

If §8 is empty, write `_None — every threat in §7 is being actively mitigated._`

## 9. Security controls inventory

Cross-cutting controls that mitigate multiple threats from §5. List every
control, where it lives, and the threats it covers.

| Control                                                  | Location                                                                       | Threats mitigated                                            | Verification                                  |
| -------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------ | --------------------------------------------- |
| `@oshun/http-client` retry + circuit breaker + telemetry | `libs/shared/http-client/`                                                     | I2, D1, D2 (vendor-side disclosure / DoS)                    | `external-api-guard` CI workflow (V1-P2-0358) |
| Allow-listed stub-indicator scanner                      | `scripts/stub-indicator-scan.sh` + `.github/workflows/stub-indicator-scan.yml` | T1, I1 (forged stub data leaking into prod)                  | `stub-indicator-scan` CI (V1-P2-0350/0351)    |
| Test-coherence reporting                                 | `scripts/test-coherence-check.mjs`                                             | T1, S1 (test asserting only shape — would pass against stub) | `test-coherence-check` CI (V1-P2-0352)        |
| Cost-tracking quota middleware                           | `libs/isis/llm-providers/quota.ts`                                             | D1, E1 (cost DoS, tier escalation)                           | Integration test in domain CI                 |
| Vault-scoped secret roles                                | `infra/vault/policies/<domain>.hcl`                                            | I2, E2 (secret leak, cross-domain access)                    | Vault audit log + Terraform CI                |
| Event envelope signing (post V1-P2-0176)                 | `libs/aje/sign`                                                                | T1 (event tampering)                                         | Subscriber CI integration test                |
| [FILL IN: subsystem-specific control]                    | [FILL IN]                                                                      | [FILL IN]                                                    | [FILL IN]                                     |

## 10. Detection and monitoring

Every mitigation in §5 should reference an alert or audit query that catches the
threat if it materialises. Aggregate them here.

| Signal                                            | Threat IDs | Where it fires                                                 | Runbook anchor                    |
| ------------------------------------------------- | ---------- | -------------------------------------------------------------- | --------------------------------- |
| [FILL IN: e.g. "auth.log → `iss_mismatch_count`"] | S1         | [FILL IN: e.g. "Loki query in `oshun/platform-overview.json`"] | [FILL IN: link to runbook §9 row] |
| [FILL IN]                                         | [FILL IN]  | [FILL IN]                                                      | [FILL IN]                         |

For incident-response procedures (paging, IC, comms), use the runbook generated
from [`runbook-template.md`](./runbook-template.md) (V1-P2-0372). The threat
model lives one level higher — it tells you what could go wrong; the runbook
tells you what to do when it does.

## 11. Cryptography

For subsystems on the V1-P2-0176 crypto-replacement path, document where each
primitive currently sits and where it's heading.

| Use case                                     | Today                                          | Target                                          | Migration ticket      |
| -------------------------------------------- | ---------------------------------------------- | ----------------------------------------------- | --------------------- |
| [FILL IN: e.g. "User session token signing"] | [FILL IN: e.g. "stub HMAC in `libs/aje/sign`"] | [FILL IN: e.g. "Ed25519 via libsodium binding"] | [FILL IN: V1-P2-NNNN] |

If §11 is empty for this subsystem, write
`_Subsystem does not handle cryptographic primitives directly; see crypto-replacement-targets.md (V1-P2-0176) for the platform-wide migration plan._`

## 12. Verification — threat-model completeness

Before the threat model is marked Active, the domain owner must verify:

- [ ] Every `[FILL IN]` placeholder above has been replaced with a concrete
      value.
- [ ] All six STRIDE categories in §5 have at least one row, OR an explicit
      `_Not applicable because <reason>_` justification.
- [ ] At least three §6 scenarios are written, each ending in a "Residual risk"
      statement.
- [ ] Every row in §7 maps to a backlog ticket (Open or Mitigating) or an §8
      accepted-risk row with sign-off.
- [ ] Every §9 control row has a verification source (CI workflow name, test
      path, or audit query) that a reviewer can execute.
- [ ] `eng-security` has approved the PR (or a linked review doc).
- [ ] `eng-platform` has approved the PR.

A threat model that fails any of these checks is `Status: Draft` and cannot be
cited as authoritative during a security review.

## 13. Re-review cadence

Living document — review at:

- **Quarterly** — refresh §7 risk register, §8 accepted risks, §10 detection
  coverage.
- **On significant change** — any of the following triggers an immediate review:
  - New external dependency added in §1.
  - Trust boundary in §3 changes shape.
  - A `Critical` or `High` row is added to §7.
  - A scenario in §6 fires in production.

## 14. Change log

| Date           | Author            | Change                                                                      |
| -------------- | ----------------- | --------------------------------------------------------------------------- |
| `<YYYY-MM-DD>` | `<github handle>` | Initial fill from `docs/releases/p2/threat-model-template.md` (V1-P2-0373). |

---

_This template is the source of truth for threat-model structure. When the
template changes, every existing threat model is reviewed within 30 days for
sections that need backfill. The §14 change-log is the audit trail._
