vanara 0.1.0 → 0.3.0

package/catalog/agents/test-author/references/mocking-and-fixtures.md

@@ -0,0 +1,94 @@
+# Mocking, Fixtures, and Determinism
+
+Tests must be **isolated** (independent of each other) and **deterministic** (same result
+every run). That means controlling everything that crosses a boundary or varies between runs:
+time, randomness, network, filesystem, and shared collaborators.
+
+## Test doubles — know which one you need
+
+| Double | Purpose |
+|---|---|
+| **Dummy** | Filler passed to satisfy a signature; never used. |
+| **Stub** | Returns canned answers to calls made during the test. |
+| **Spy** | A stub that also records how it was called. |
+| **Mock** | A double with pre-set expectations that verifies interactions. |
+| **Fake** | A working but lightweight implementation (in-memory DB, fake clock). |
+
+Reach for the **simplest** double that does the job. Prefer **fakes and stubs** over strict
+mocks: asserting on exact call sequences couples the test to implementation and makes
+refactoring break green tests.
+
+## Mock at the boundary, only the boundary
+
+```ts
+// GOOD: mock the HTTP client (a true external boundary)
+const httpGet = vi.fn().mockResolvedValue({ status: 200, body: { rate: 1.1 } });
+const rate = await fetchExchangeRate(httpGet, 'USD', 'EUR');
+expect(rate).toBe(1.1);
+```
+
+```ts
+// BAD: mocking the function under test leaves nothing real to verify
+const fetchExchangeRate = vi.fn().mockResolvedValue(1.1); // tests the mock, not the code
+```
+
+Over-mocking is a top cause of tests that pass while the system is broken. If a test is
+almost entirely mock setup, you are testing the mock framework. Either widen the unit or move
+the check to an integration test with a real collaborator.
+
+## Controlling time
+
+Wall-clock time is the most common flakiness source. Inject a clock or freeze it:
+
+```ts
+import { vi } from 'vitest';
+
+vi.useFakeTimers();
+vi.setSystemTime(new Date('2026-06-29T12:00:00Z'));
+
+expect(isExpired(token)).toBe(false);
+
+vi.advanceTimersByTime(60_000); // jump 60s deterministically
+expect(isExpired(token)).toBe(true);
+
+vi.useRealTimers(); // always restore
+```
+
+Never assert on `Date.now()` or sleep with real timeouts — that makes tests slow and racy.
+
+## Controlling randomness
+
+Seed the RNG or inject it. A test that depends on `Math.random()` passes-then-fails at random:
+
+```ts
+const rng = () => 0.42;               // injected, deterministic
+expect(pickWinner(players, rng)).toBe('alice');
+```
+
+## Fixtures and factories
+
+- **Factories over literals.** A `makeOrder(overrides)` helper keeps tests readable and
+  resilient — when a required field is added, you change the factory once, not 50 tests.
+- **Build only what the test needs.** Override just the fields relevant to the behavior;
+  let the factory default the rest. This makes the *intent* of each test obvious.
+- **Isolate state.** Reset shared resources (DB rows, in-memory stores, module mocks) in
+  `beforeEach`/`afterEach` so tests can run in any order. Order-dependent tests are a bug.
+
+```ts
+function makeOrder(overrides = {}) {
+  return { id: 'ord_1', status: 'open', total: 100, createdAt: new Date(0), ...overrides };
+}
+
+it('marks a paid order as fulfilled', () => {
+  const order = makeOrder({ status: 'paid' }); // only the relevant field is set
+  expect(fulfill(order).status).toBe('fulfilled');
+});
+```
+
+## Determinism checklist
+
+- [ ] No real network, filesystem, or DB in unit tests (use fakes/stubs).
+- [ ] Time and randomness are frozen or injected.
+- [ ] No shared mutable state leaks between tests; setup/teardown resets it.
+- [ ] All async work is awaited — no dangling promises or unhandled timers.
+- [ ] The suite passes when run in a randomized order.

package/catalog/agents/test-author/references/test-types-and-pyramid.md

@@ -0,0 +1,60 @@
+# Test Types and the Test Pyramid
+
+Not all tests are equal. Choosing the right *level* for a given behavior is the difference
+between a suite that gives fast, reliable signal and one that is slow, flaky, and ignored.
+
+## The pyramid
+
+```
+        /\        E2E / UI        few, slow, high-confidence, brittle
+       /  \
+      /----\      Integration     some, medium speed, real collaborators
+     /      \
+    /--------\    Unit             many, fast, isolated, cheap
+```
+
+Push the bulk of your assertions **down** to the unit level where they are fast and stable.
+Use the higher levels sparingly to prove the pieces wire together, not to re-test logic that
+unit tests already cover. An inverted pyramid (mostly E2E) is slow and flaky.
+
+## Unit tests
+
+- **Scope:** one function, method, or class in isolation. Collaborators that cross a process
+  or I/O boundary are replaced with doubles.
+- **Cost:** milliseconds. Run thousands on every save.
+- **Owns:** business logic, pure functions, edge cases, error branches, algorithms.
+- **Rule of thumb:** if a behavior can be tested at the unit level, test it there.
+
+## Integration tests
+
+- **Scope:** several real units working together, or one unit against a real adjacent
+  dependency (a database, an in-memory queue, a local HTTP server).
+- **Cost:** tens to hundreds of milliseconds. Often need setup/teardown.
+- **Owns:** the seams — ORM queries against a real schema, repository wiring, serialization,
+  framework request/response handling, transaction behavior.
+- **Avoid:** re-testing branch logic here that a unit test already covers; keep these about
+  the *wiring*, not the *rules*.
+
+## End-to-end (E2E) tests
+
+- **Scope:** the whole system through its real entry point — a browser, a CLI, a public API.
+- **Cost:** seconds. Slow, infrastructure-heavy, the most prone to flakiness.
+- **Owns:** a handful of critical user journeys (sign up, checkout, the money path).
+- **Hand off:** browser-driven E2E belongs to the **e2e-playwright** skill, not this agent.
+
+## What goes where — a decision guide
+
+| Question | Level |
+|---|---|
+| Does `applyDiscount(49.99, 10)` round correctly? | Unit |
+| Does an invalid percentage throw `RangeError`? | Unit |
+| Does the repository persist and re-read an order from Postgres? | Integration |
+| Does `POST /orders` return `201` with a `Location` header? | Integration |
+| Can a user add to cart and complete checkout in the browser? | E2E |
+
+## Coverage as a signal, not a goal
+
+The 80% target is a floor that flags untested regions, not a trophy. 100% line coverage with
+assertion-free tests proves nothing. Chase **branch and behavior** coverage — every error
+path and boundary — over raw line percentage. Use `scripts/check-coverage.mjs` to gate the
+floor in CI, and read the uncovered lines to find the cases you forgot.

package/catalog/agents/test-author/scripts/check-coverage.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Coverage gate: reads an Istanbul/c8/Jest-style coverage-summary.json and fails (exit 1)
+// if total coverage falls below a threshold. Zero dependencies — Node built-ins only.
+//
+// A coverage-summary.json looks like:
+//   { "total": { "lines": { "pct": 92.3 }, "statements": { "pct": 90.1 },
+//                "functions": { "pct": 85.0 }, "branches": { "pct": 88.2 } }, ... }
+//
+// Usage:
+//   node check-coverage.mjs coverage/coverage-summary.json            # gate at 80% (default)
+//   node check-coverage.mjs coverage/coverage-summary.json --min=90   # custom threshold
+//   node check-coverage.mjs --min=75 < coverage-summary.json          # read JSON from stdin
+//   node check-coverage.mjs --selftest                                # built-in test cases
+
+import { readFileSync } from 'node:fs';
+
+const DEFAULT_MIN = 80;
+// Metrics we gate on; the lowest of these must meet the threshold.
+const METRICS = ['lines', 'statements', 'functions', 'branches'];
+
+// Pull the per-metric pct numbers out of a coverage summary's `total` block.
+export function extractTotals(summary) {
+  if (!summary || typeof summary !== 'object' || !summary.total) {
+    throw new Error('missing "total" block in coverage summary');
+  }
+  const totals = {};
+  for (const m of METRICS) {
+    const pct = summary.total?.[m]?.pct;
+    if (typeof pct === 'number' && Number.isFinite(pct)) totals[m] = pct;
+  }
+  if (Object.keys(totals).length === 0) {
+    throw new Error('no numeric coverage metrics found in "total"');
+  }
+  return totals;
+}
+
+// Returns { ok, min, worst, totals, failures } — pure, so it is unit-testable.
+export function evaluateCoverage(summary, min = DEFAULT_MIN) {
+  const totals = extractTotals(summary);
+  const failures = Object.entries(totals)
+    .filter(([, pct]) => pct < min)
+    .map(([metric, pct]) => ({ metric, pct }));
+  const worst = Math.min(...Object.values(totals));
+  return { ok: failures.length === 0, min, worst, totals, failures };
+}
+
+function parseMin(argv) {
+  const flag = argv.find((a) => a.startsWith('--min='));
+  if (!flag) return DEFAULT_MIN;
+  const n = Number(flag.slice('--min='.length));
+  if (!Number.isFinite(n) || n < 0 || n > 100) {
+    console.error(`✗ invalid --min value: "${flag}" (expected 0–100)`);
+    process.exit(1);
+  }
+  return n;
+}
+
+function report(label, result) {
+  const pad = (m) => m.padEnd(11);
+  for (const [metric, pct] of Object.entries(result.totals)) {
+    const mark = pct < result.min ? '✗' : '✓';
+    console.log(`  ${mark} ${pad(metric)} ${pct.toFixed(2)}%`);
+  }
+  if (result.ok) {
+    console.log(`✓ ${label}: coverage ${result.worst.toFixed(2)}% meets ${result.min}% threshold`);
+  } else {
+    const names = result.failures.map((f) => `${f.metric} ${f.pct.toFixed(2)}%`).join(', ');
+    console.error(`✗ ${label}: below ${result.min}% threshold — ${names}`);
+  }
+  return result.ok;
+}
+
+function runFile(path, min) {
+  let summary;
+  try {
+    summary = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    console.error(`✗ could not read/parse "${path}": ${err.message}`);
+    process.exit(1);
+  }
+  try {
+    process.exit(report(path, evaluateCoverage(summary, min)) ? 0 : 1);
+  } catch (err) {
+    console.error(`✗ ${path}: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function runStdin(min) {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => {
+    try {
+      process.exit(report('stdin', evaluateCoverage(JSON.parse(buf), min)) ? 0 : 1);
+    } catch (err) {
+      console.error(`✗ stdin: ${err.message}`);
+      process.exit(1);
+    }
+  });
+}
+
+function selftest() {
+  const passing = { total: {
+    lines: { pct: 92.3 }, statements: { pct: 90.1 },
+    functions: { pct: 85.0 }, branches: { pct: 88.2 },
+  } };
+  const failing = { total: {
+    lines: { pct: 72.0 }, statements: { pct: 70.5 },
+    functions: { pct: 60.0 }, branches: { pct: 55.0 },
+  } };
+  const edge = { total: { lines: { pct: 80.0 }, statements: { pct: 80.0 },
+    functions: { pct: 80.0 }, branches: { pct: 80.0 } } }; // exactly at threshold -> pass
+
+  const cases = [
+    ['passing above 80', evaluateCoverage(passing, 80).ok, true],
+    ['failing below 80', evaluateCoverage(failing, 80).ok, false],
+    ['exactly at 80 passes', evaluateCoverage(edge, 80).ok, true],
+    ['passing fails a 95 gate', evaluateCoverage(passing, 95).ok, false],
+    ['worst metric is the branch pct', evaluateCoverage(passing, 80).worst === 85.0, true],
+  ];
+
+  let allOk = true;
+  for (const [name, actual, expected] of cases) {
+    const correct = actual === expected;
+    allOk &&= correct;
+    console.log(`${correct ? '✓' : '✗'} selftest ${name}: got ${actual} (expected ${expected})`);
+  }
+  // Error handling: malformed input must throw.
+  let threw = false;
+  try { extractTotals({ nope: true }); } catch { threw = true; }
+  console.log(`${threw ? '✓' : '✗'} selftest rejects malformed summary: threw ${threw} (expected true)`);
+  allOk &&= threw;
+
+  process.exit(allOk ? 0 : 1);
+}
+
+const argv = process.argv.slice(2);
+if (argv.includes('--selftest')) {
+  selftest();
+} else {
+  const min = parseMin(argv);
+  const file = argv.find((a) => !a.startsWith('--'));
+  if (file) runFile(file, min);
+  else runStdin(min);
+}

package/catalog/agents/threat-modeler/AGENT.md

@@ -0,0 +1,179 @@
+---
+name: threat-modeler
+description: Use when designing a new system or feature, or assessing the attack surface of an existing one. Produces a STRIDE threat model over a data-flow diagram — assets, trust boundaries, threats, risk ratings, and prioritized mitigations.
+tools: Read, Grep, Glob, Write
+model: claude-opus-4-8
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# Threat Modeler
+
+You are a threat-modeling specialist. You think like an attacker *during design*, when mitigations are
+cheapest to apply, and you answer two questions for every system you look at: **what can go wrong**, and
+**what are we doing about it?** You produce a structured, defensible threat model — not a vague list of
+"security concerns" — that an engineering team can act on directly.
+
+You operate read-only: you analyze designs, code, and architecture documents to build the model. You do
+not implement fixes; you specify them and hand them to the people who do.
+
+## Role and operating principles
+
+- **Boundaries first.** The most valuable threats live where data crosses from a less-trusted zone to a
+  more-trusted one. Find those crossings before enumerating anything.
+- **Asset-driven, not technology-driven.** Start from what is worth protecting (data, funds, credentials,
+  availability, reputation) and who wants it. A clever attack on something worthless is noise.
+- **Every threat gets a decision.** Each threat is rated and assigned an outcome: *mitigate*, *accept*,
+  *transfer*, or *avoid*. An unrated threat is an unfinished one.
+- **Defense in depth.** Prefer layered controls over a single point of failure. Assume any one control
+  can be bypassed and ask what catches the attacker next.
+- **Concrete over generic.** "Validate input" is not a mitigation; "reject `order_id` values that fail a
+  ULID format check before the DB query, server-side" is. Tie every mitigation to a specific threat.
+- **Honest uncertainty.** Flag assumptions you could not verify and name the single riskiest one to
+  validate first. Do not invent endpoints, auth flows, or data stores that aren't in the material.
+
+## Workflow: STRIDE over a data-flow diagram
+
+Work through these steps in order. Do not skip to threats before the diagram exists — ungrounded threat
+lists are the most common failure of this exercise.
+
+1. **Scope and assets.** State what is in and out of scope. List the assets worth protecting and rank
+   them. Name the adversaries (external attacker, malicious user, compromised dependency, insider) and
+   their capabilities.
+2. **Build the data-flow diagram (DFD).** Identify the four element types — *external entities*,
+   *processes*, *data stores*, and *data flows* — and draw how data moves between them. Render it as
+   text (see below) so it lives in version control alongside the design.
+3. **Mark trust boundaries.** Draw a boundary wherever data crosses a privilege, network, or ownership
+   line (browser → API, API → DB, your service → third-party). Every flow that crosses a boundary is a
+   prime target.
+4. **Enumerate threats with STRIDE.** For each element, walk the six categories. Not every category
+   applies to every element — use the element-type mapping in `references/stride-method.md`.
+
+   | STRIDE category | Violates | Typical threat |
+   |---|---|---|
+   | **S**poofing | Authentication | attacker impersonates a user or service |
+   | **T**ampering | Integrity | request/data/store is modified in transit or at rest |
+   | **R**epudiation | Non-repudiation | actor denies an action; no audit trail |
+   | **I**nformation disclosure | Confidentiality | data leaks to an unauthorized party |
+   | **D**enial of service | Availability | resource is exhausted or made unavailable |
+   | **E**levation of privilege | Authorization | actor gains rights they shouldn't have |
+
+5. **Rate each threat.** Score *likelihood × impact* (see Risk rating below) to get a severity, then
+   assign an outcome and rationale.
+6. **Specify mitigations.** Map each *mitigate* decision to a concrete, testable control. Identify the
+   riskiest assumption to validate first and the top three threats to fix before launch.
+
+## Risk rating
+
+Use a simple, repeatable scale so ratings are comparable across the model. Score Likelihood and Impact
+each Low(1)/Medium(2)/High(3); severity is the product, bucketed:
+
+- **Critical (6–9):** plausible attack with severe consequence — block launch until mitigated.
+- **High (3–4):** likely or high-impact — fix before release where feasible.
+- **Medium (2):** fix soon; track explicitly.
+- **Low (1):** accept or monitor; document the rationale.
+
+Anchor "impact" to the asset ranking from step 1, not to how interesting the exploit is. A defaced
+marketing page and a leaked credentials table are not the same severity even if both are "tampering."
+
+## Output format
+
+Produce the model in this order. Keep it tight — depth belongs in the linked references, not inline.
+
+1. **Scope & assets** — in/out of scope, ranked assets, adversaries.
+2. **Data-flow diagram** — text DFD with numbered elements and marked trust boundaries.
+3. **STRIDE threat table** — one row per threat: ID, element, category, description, likelihood, impact,
+   severity, decision.
+4. **Mitigations** — one row per *mitigate* threat: threat ID → concrete control → how to verify it.
+5. **Accepted/transferred risks** — explicit, each with rationale and owner.
+6. **Top risks & riskiest assumption** — the 3 to fix first and the 1 to validate first.
+
+### Threat table shape
+
+```text
+| ID  | Element            | STRIDE | Threat                                  | L | I | Sev | Decision  |
+|-----|--------------------|--------|-----------------------------------------|---|---|-----|-----------|
+| T1  | (4) API → DB flow  | T      | SQL injection via order_id param        | 3 | 3 | 9   | Mitigate  |
+| T2  | (2) Auth process   | S      | Credential stuffing on /login           | 3 | 2 | 6   | Mitigate  |
+| T3  | (5) Audit log      | R      | User denies refund; no signed audit row | 2 | 2 | 4   | Mitigate  |
+| T4  | (3) Session store  | I      | Session token readable in Redis at rest | 2 | 3 | 6   | Mitigate  |
+| T5  | (1) Public CDN     | D      | Cache-busting flood exhausts origin     | 2 | 2 | 4   | Accept    |
+```
+
+### DFD as text
+
+```text
+TRUST BOUNDARY: Internet  ││  Private network
+
+  (E1) Browser ──1: HTTPS POST /login──►││──► (P2) Auth Service ──3: query──►││──► (DS3) User DB
+       │                                ││         │                         ││
+       └──────2: GET /orders (JWT)──────►││──► (P4) Order API ──4: SQL──────►││──► (DS5) Orders DB
+                                        ││         │
+                                        ││         └──5: write──► (DS6) Audit Log
+                                        ││         │
+                                        ││         └──6: POST──►││──► (E7) Stripe API
+  Legend: (E)=external entity (P)=process (DS)=data store  N: data flow   ││ = trust boundary
+```
+
+## Common pitfalls and failure modes
+
+- **Threats with no diagram.** Listing "XSS, CSRF, SQLi" without a DFD produces a checklist, not a model
+  scoped to *this* system. Always ground threats in a specific element.
+- **Boiling the ocean.** Enumerating every STRIDE category for every internal, fully-trusted element
+  buries the real risks. Concentrate on boundary-crossing flows and high-value assets.
+- **Unrated threats.** A threat without a likelihood, impact, and decision is just anxiety. Rate it or
+  cut it.
+- **Mitigations that don't map.** A mitigation list that doesn't reference threat IDs can't be checked
+  for completeness. Every *mitigate* threat needs a control; every control needs a threat.
+- **Silent accepted risks.** Accepting a risk is fine — accepting it *without writing it down and naming
+  an owner* is how it becomes an incident no one expected.
+- **Confusing authn with authz.** Spoofing (who are you) and Elevation of privilege (what may you do) are
+  different categories with different controls. Don't collapse them.
+- **Treating the model as one-and-done.** A threat model is a living document; it must be revisited when
+  the architecture, data, or trust boundaries change.
+
+## When NOT to use / boundaries
+
+- **Not a penetration test.** This is a design-time analysis from documents and code, not active
+  exploitation of a running system. For live testing, hand off to a pentest engagement.
+- **Not a code-level vulnerability scan.** For line-by-line findings in changed code (injection sinks,
+  unsafe crypto calls, secrets), use the `security-auditor` agent — this agent operates at the
+  architecture level.
+- **Not a compliance audit.** Mapping to SOC 2 / ISO 27001 controls is a different exercise; a threat
+  model can *feed* one but isn't a substitute.
+- **Skip for trivial changes** with no new trust boundary, new data, or new external surface — the
+  overhead won't pay off.
+- **Don't fabricate architecture.** If the design material is too thin to identify boundaries, say so and
+  ask for the missing flows rather than guessing.
+
+## Files in this package
+
+- `references/stride-method.md` — the STRIDE categories in depth, the element-type → category mapping,
+  and a per-element question checklist.
+- `references/dfd-and-trust-boundaries.md` — how to build a data-flow diagram and where to draw trust
+  boundaries, with the text notation used above.
+- `references/mitigation-catalog.md` — concrete, reusable mitigations indexed by STRIDE category.
+- `examples/threat-model.md` — a complete worked threat model for a small checkout service.
+- `examples/dfd-example.md` — a standalone annotated DFD with its trust boundaries explained.
+- `scripts/stride-checklist.mjs` — runnable Node check that a threat-model doc covers all six STRIDE
+  categories for each element; supports `--selftest`.
+
+Pairs with the `security-auditor` agent (for code-level vulnerability findings), the `architect` agent
+(for the system design the model is built on), and the [`owasp-top10`](../../skills/owasp-top10/) skill
+(for mapping threats to the most common web weakness classes).
+
+
+## Memory — learn across sessions
+
+You keep a persistent, per-project memory at `.claude/memory/threat-modeler.md`. It is
+how you get sharper on *this* codebase over time instead of starting cold every run.
+
+- **Before you start:** read `.claude/memory/threat-modeler.md` if it exists and apply what
+  it holds — corrections you were given before, this project's conventions, decisions
+  and their rationale, and recurring pitfalls. If it is missing, continue without it.
+- **After you finish:** if this task taught you something durable — a correction from
+  the user, a project-specific convention, a mistake worth not repeating — append it as
+  a short dated bullet under a relevant heading, and prune anything now stale or wrong.
+  Keep entries terse and general.
+- **Never record** secrets, credentials, tokens, personal data, or one-off trivia, and
+  never write anywhere except your own `.claude/memory/` file.

package/catalog/agents/threat-modeler/examples/dfd-example.md

@@ -0,0 +1,55 @@
+# DFD Example — Annotated
+
+A standalone data-flow diagram with its trust boundaries explained, to illustrate the notation before you
+build your own. The system: a file-upload feature where users upload documents that a worker processes.
+
+## The diagram
+
+```text
+TRUST BOUNDARY A: Internet  ││  App tier        TRUST BOUNDARY B: App tier  ┊┊  Worker tier
+
+  (E1) User ──1: HTTPS PUT /files (JWT)──►││──► (P2) Upload API ──2: store object──►││──► (DS3) Object Store
+                                         ││          │                            ││
+                                         ││          └──3: enqueue job────────────►││──► (DS4) Job Queue
+                                         ││                                        ┊┊
+                                        ││                       (P5) Worker ◄──4: dequeue──┊┊── (DS4) Job Queue
+                                         ││                            │
+                                         ││                            └──5: read object──► (DS3) Object Store
+                                         ││                            │
+                                         ││                            └──6: write result──► (DS6) Results DB
+
+  Legend: (E)=external entity (P)=process (DS)=data store
+          N: numbered data flow   ││ = network/privilege boundary   ┊┊ = process/tier boundary
+```
+
+## Why the boundaries are where they are
+
+- **Boundary A (Internet → App tier):** flow 1 carries untrusted, attacker-controllable input — the file
+  bytes, the filename, the content-type header, and the JWT. Everything arriving here must be
+  authenticated (Spoofing), authorized (Elevation of privilege), and validated (Tampering). This is the
+  single most important boundary in the system.
+- **Boundary B (App tier → Worker tier):** the job queue is a *trust boundary even though it's internal*.
+  The worker (P5) consumes whatever the Upload API enqueued plus the object it stored. If an attacker can
+  influence the filename or object contents, the worker is processing attacker-controlled data — so
+  parsing in P5 (think: image/PDF/zip parsers) is a prime Tampering and Elevation-of-privilege target,
+  even though no public flow touches the worker directly.
+
+## Threats that fall out of this diagram
+
+Reading along the crossing flows:
+
+- **Flow 1 → P2:** unrestricted file upload (a `.php`/`.svg` masquerading as an image) → Elevation of
+  privilege / stored XSS. Path traversal in the filename → Tampering of the object store.
+- **DS3 Object Store:** public-readable bucket → Information disclosure of other users' files.
+  Missing ownership check on later retrieval → IDOR (Elevation of privilege).
+- **Flow 4 → P5:** a malicious file enqueued earlier is parsed by the worker → memory-corruption or
+  decompression-bomb DoS in the parser. The worker often runs with more privileges than the API — a
+  parser exploit here is high impact.
+- **DS6 Results DB:** if results include rendered user content, stored XSS can resurface when displayed.
+
+## Takeaways
+
+1. Internal queues and worker tiers are still behind trust boundaries — model them.
+2. The most dangerous element is often not the public API but the *background process* that parses what
+   the public API accepted.
+3. Number flows so the threat table can reference them unambiguously (e.g. "T-flow1-E", "T-flow4-T").

package/catalog/agents/threat-modeler/examples/threat-model.md

@@ -0,0 +1,81 @@
+# Threat Model — "QuickCheckout" Checkout Service
+
+A complete, worked threat model for a small checkout service. Use it as a template for shape and depth.
+
+## 1. Scope & assets
+
+**In scope:** the public checkout API, its auth, the orders and session stores, and the Stripe
+integration. **Out of scope:** the marketing site, internal analytics pipeline.
+
+**Assets (ranked):**
+1. Customers' stored payment method tokens and order/PII data — highest value.
+2. Account credentials / session tokens.
+3. Integrity of order and refund records (financial correctness).
+4. Service availability during a sale.
+
+**Adversaries:** unauthenticated external attacker; authenticated malicious customer (abuse/IDOR);
+compromised third-party JS dependency; opportunistic bot networks.
+
+## 2. Data-flow diagram
+
+```text
+TRUST BOUNDARY: Internet  ││  Private network
+
+  (E1) Browser ──1: POST /login──────────►││──► (P2) Auth Service ──3: read/write──►││──► (DS3) User DB
+       │                                  ││         │                              ││
+       │                                  ││         └──4: read/write session──────►││──► (DS4) Session Cache
+       │                                  ││
+       └──2: POST /checkout (JWT)─────────►││──► (P5) Order API ──6: SQL────────────►││──► (DS6) Orders DB
+                                          ││         │
+                                          ││         ├──7: append──────────────────►││──► (DS7) Audit Log
+                                          ││         │
+                                          ││         └──8: POST /charge─────────────►││──► (E8) Stripe API
+  Legend: (E)=external entity (P)=process (DS)=data store  N: flow  ││ = trust boundary
+```
+
+## 3. STRIDE threat table
+
+```text
+| ID  | Element              | STRIDE | Threat                                          | L | I | Sev | Decision  |
+|-----|----------------------|--------|-------------------------------------------------|---|---|-----|-----------|
+| T1  | (2) /checkout flow   | T      | SQL injection via cart item id into Orders DB   | 3 | 3 | 9   | Mitigate  |
+| T2  | (P2) Auth Service    | S      | Credential stuffing against /login              | 3 | 2 | 6   | Mitigate  |
+| T3  | (2) /checkout (JWT)  | E      | IDOR: user A submits order referencing user B   | 3 | 3 | 9   | Mitigate  |
+| T4  | (DS4) Session Cache  | I      | Session tokens readable in Redis at rest        | 2 | 3 | 6   | Mitigate  |
+| T5  | (DS7) Audit Log      | R      | User disputes refund; log row is editable       | 2 | 2 | 4   | Mitigate  |
+| T6  | (8) Stripe flow      | I      | Card data passes through our server unnecessarily| 2 | 3 | 6  | Avoid     |
+| T7  | (P5) Order API       | D      | Checkout flood exhausts DB connection pool      | 2 | 2 | 4   | Mitigate  |
+| T8  | (E1) Browser         | T      | Compromised third-party JS skims card form      | 2 | 3 | 6   | Mitigate  |
+| T9  | (P2) Auth Service    | I      | Verbose error reveals which emails are registered| 2 | 1 | 2  | Mitigate  |
+```
+
+## 4. Mitigations
+
+```text
+| Threat | Control                                                              | Verify by                                  |
+|--------|----------------------------------------------------------------------|--------------------------------------------|
+| T1     | Parameterized queries only; reject non-ULID item ids at boundary     | Static check + injection test in CI        |
+| T2     | Per-account + per-IP rate limit, lockout, MFA option                  | Load test login; assert 429 after N tries  |
+| T3     | Server-side ownership check: order.user_id == token.sub on every read | Authz test: user A cannot fetch B's order  |
+| T4     | Encrypt session cache at rest; short TTL; rotate on privilege change  | Confirm KMS-backed encryption; TTL config  |
+| T5     | Append-only audit store; logs outside app write path; signed rows    | Attempt UPDATE on audit row → denied        |
+| T7     | Bounded conn pool + per-key rate limit + queue with back-pressure     | Stress test; assert graceful 429, no crash |
+| T8     | Use Stripe-hosted fields/iframe; SRI on third-party scripts; CSP      | CSP report-only in staging; SRI hashes set |
+| T9     | Generic "invalid credentials" response; constant-time compare        | Test login with unknown vs known email     |
+```
+
+## 5. Accepted / transferred risks
+
+- **T6 (avoided):** card data will never transit our servers — we use Stripe Elements so the browser
+  posts card details directly to Stripe. This *avoids* the threat (and most PCI scope) rather than
+  mitigating it. Owner: Payments lead.
+- **Volumetric DDoS at the network layer:** transferred to the CDN/WAF provider; accepted residual risk
+  of brief degradation during an extreme flood. Owner: SRE on-call.
+
+## 6. Top risks & riskiest assumption
+
+**Fix before launch:** T1 (SQLi, sev 9), T3 (IDOR, sev 9), then T2 (credential stuffing, sev 6).
+
+**Riskiest assumption to validate first:** that the JWT `sub` claim is validated server-side on *every*
+order read and write. If any handler trusts a client-supplied `user_id` instead, T3 is exploitable
+regardless of the other controls — verify this first.