Groundnote threat model#

Status: living document, first version 2026-11-05; state columns checked against the code on 2026-11-05 and updated for the review findings on 2026-11-05 (commits named per row). Method: STRIDE per trust boundary, then one section per named attacker. Every control names where it is enforced and how it is tested, so a reviewer can check the claim instead of trusting the prose. Controls marked open are not built yet; they are listed so nobody mistakes the plan for the state.

What we protect#

Trust boundaries#

 untrusted content            untrusted callers                 trusted (narrowly)
 ─────────────────            ─────────────────                 ───────────────────
 mail / meeting text ──▶ [B1 ingest] ──▶ scope files ◀── [B4 approval] ◀── person in browser
                                          ▲      ▲
 AI client (claude.ai, ─▶ [B2 /mcp] ──────┘      └──── [B5 ops, loopback] ◀── operator CLI
  Claude Code, tasks)
 service clients ──────▶ [B3 /v1 API]
 webhook senders ──────▶ [B6 webhooks: ID only, no content]
 search results ───────▶ [B7 output to a model]  ◀── the boundary most memory tools forget
 backups / exports ────▶ [B8 storage outside the host]
 dependencies, CI ─────▶ [B9 supply chain]
 query + statements ───▶ [B10 external judge: TypeSafe JEV, USA]  (stage c, off by default)

B7 is drawn on purpose: Groundnote does not run the model that reads its search results, but the text it returns becomes part of that model's context. A rule or excerpt is therefore an input to someone else's agent, and Groundnote is responsible for how it is framed.

STRIDE by boundary#

Attackers and controls#

A1 — attacker writes a mail or speaks in a meeting (prompt injection)#

The attacker controls text that Groundnote ingests: a customer mail, a forwarded thread, an attachment, a sentence in a meeting. Goals: (a) get an instruction stored as a confirmed rule, (b) make a reading model act on stored text later, (c) get content of another scope returned, (d) hide a real rule.

Groundnote's position is that no filter recognises all injections. The design therefore makes injected text powerless rather than trying to detect it. The detector exists, but only as a warning signal for the human reviewer.

Residual risk: a person approves a malicious rule whose quote is genuine (for example a customer writes "you must always ship via carrier X" and the reviewer agrees). Groundnote cannot prevent judgement errors; it makes them attributable (decision row with identity and time) and revocable (decision revoke keeps the history).

A2 — stolen token#

JWT verification must pin, in this order: algorithm allow-list (RS256 only; reject none, HS*, and any alg not in the list before looking up a key), key by kid from the configured JWKS only (no jku, x5u or embedded jwk headers), signature, iss equal to the configured team domain, aud containing exactly the audience of this channel, exp in the future and nbf/iat not in the future (clock skew at most 60 s), and an identity claim present. JWKS is cached with a maximum age and refetched on unknown kid at most once per minute, so an attacker cannot force a fetch per request.

A3 — someone reaches the server, a backup or an export#

A4 — data flows to a client that should not get it (MCP exfiltration)#

Groundnote answers whoever holds a valid grant. Exfiltration risks are therefore about which data a valid caller receives and where the client sends it next.

• Scope check on every call, including scope names derived from references (rule/sales-0042 belongs to sales). Unknown and forbidden scopes get the same 403, so scope names cannot be enumerated.
• Cross-scope search only with an explicit flag and only if every scope is in the grant.
• Minimal output. Search returns bundles with excerpts, never full source bodies; the full excerpt needs provenance on a single reference.
• Per-scope provider allow-list (providers_allowed) for any path where content leaves the server (embeddings, reranker, extraction). An empty list means: nothing leaves.
• Logging without content. search_log stores terms, stages and reference ids, plus a SHA-256 of the input, never the text.
• Client side is out of our control. A claude.ai connector may combine Groundnote output with other tools. PI-6 and PI-8 limit what our text can make that client do; the operator decides which clients get a grant.

A5 — malicious contributor or compromised dependency (supply chain)#

A6 — foreign text reaches the external judge (stage c, boundary B10)#

Stage c sends the query text and the statements of up to 50 candidate rules per scope to TypeSafe AI (JEV, USA). Two risks: (a) disclosure: the texts leave the host and the EU; (b) prompt injection: a mail that was ingested can land in a query (the caller searches with the mail text) or in a rule statement, and that text can act as an instruction to the judge, pushing the score of a real rule under the threshold and so suppressing a hit. The judge returns numbers only; it cannot write, approve or call tools, so the damage is a hidden or a promoted rule, not an action.

Residual risk. A confirmed rule whose statement carries an injected instruction, or a query built from a hostile mail, can still lower its own or another rule's score. Mitigation is the recall floor (a+b hits remain when c fails, but not when c succeeds with a low score) and that statements are confirmed by a person before they reach c. Switch c on only for scopes whose texts may leave the host. Open: the cap is instance-wide; one grant can use it up, after which c is budget for everyone until month end (a+b keeps working). A quota per grant is not built. Overshoot of the cap: the check reads the spent amount before the call and books after it (check-then-act), so parallel searches can pass the check together; the cap is exceeded by at most (parallel searches × cost of one call), each call holding at most 50 statements and a query of 4000 characters.

Abuse limits#

Logging#

Never logged: request bodies, source text, quotes, tokens, cookies, Authorization and Cf-Access-Jwt-Assertion headers, provider keys. Logged: method, route template, status, duration, grant id, scope names, error codes. A test asserts that a request with a known secret and a known sentence leaves neither in the log output.

Supply chain note: stage b (2026-11-06)#

@huggingface/transformers is an optional dependency (exact version, loaded by dynamic import only in src/search/semantic/transformers-embedder.ts). It pulls sharp and with it libvips (LGPL-3.0). pnpm audit --prod now reports high advisories in libvips, libheif and librsvg. They are not reachable: Groundnote embeds text and never decodes images. The statement "pnpm audit clean" therefore holds only for an install without the optional package. Model files are pinned by revision and SHA-256 and loaded from disk only (env.allowRemoteModels = false); the service never downloads.

Right to erasure despite append-only#

See docs/security/data-at-rest.md, section "Erasure". Short form: redaction with proof is the default (a separate, audited erase path replaces the personal text with a tombstone and its hash); crypto-shredding per source is the option for operators whose backups outlive the erasure deadline.

Out of scope#

• The security of the AI client and its other tools.
• A malicious operator with root on the host.
• Judgement errors of the approving person (mitigated by history and revoke, not prevented).

Findings against the Phase 1 contract (docs/architecture.md, 2026-11-05)#

Checked against the contract before code exists, so they are cheap to fix. Each is a proposal for the contract, not a change made here.

Security review of the built core (2026-11-05, HEAD b303ec0)#

Two-stage review (finder, then an independent verifier per blocker). No blocker. Verified without finding: RS256-only allow-list before key lookup, no jku/x5u/jwk, iss/aud per channel/exp/nbf; bearer only on api; ops listener loopback-only with constant-time token compare; scope names cannot traverse paths; FTS input is quoted; rejected rules are filtered on every read path; logs and error bodies carry no content; pnpm audit had no findings at that review (state of 2026-11-05; see the supply-chain note below for the later finding).

Findings of the review; all are fixed (state per row):

Knowledge graph: entities and links (reviewed before it was built)#

The core adds entity (with a parent, so hierarchies such as department → team → project) and link with an origin deterministic, proposed or human. Threats and the controls the design needs. The graph is built (slices G1–G8, 30fb494 … eb38afd); G1–G8 below are the controls it was built against, and the individual tests are listed in graph.md §14. They have not been re-verified one by one in this pass.

Measured on the private real-data set (counts only; see the operator's notes): of 74 rule sources, 34 carry a mail thread and 4 threads hold more than one rule; 9 sources have 35 attachments, only 2 of them with readable text; 8 rules come from documents with a stable document id; 8 sources are shared by more than one rule. These links follow from headers and ids alone and need no model.

Approval modes A/B/C (slice A, specified 2026-11-06, approval-modes.md)#

Modes A and B let rules become valid without a person. The goal of an attacker shifts from "convince the reviewer" to "pass the classification". The controls below are specified for slice A and land with its commits; "built in this slice" is the target state and must be re-verified against the tests of approval-modes.md §15 after the merge.