Skip to content

Security invariants registry

The big picture: .claude/security-invariants.md is a registry of security rules that have to hold on every surface that can reach them — REST, WebSocket, a background job, an import path, an MCP server — not just the one surface a given diff touches. architect, rbac-check, security-review, and threat-model all read it.

Why it matters: A code reviewer, human or agent, only sees the diff in front of them. A fix to a permission check on REST that doesn’t also fix the same check on WebSocket is a complete fix of the diff and an incomplete fix of the rule — and nothing points the reviewer at the surface they aren’t looking at. The registry is where that second surface gets written down, once, so every future review of a touched rule walks the whole row instead of re-discovering it.

  • Each rule is a ## section: a plain-language statement of what must hold, why, and a table of every surface that must enforce it — with the file and function where that surface’s enforcement lives today.
  • A reviewer (agent or human) who touches a listed rule checks every row in that rule’s table, not only the surface in the diff, and reports a surface that falls behind as a finding — the same severity as any other finding in that review.
  • threat-model runs before code exists. It uses the registry the other direction: when a new feature’s design introduces a boundary, grant mechanism, or revocation path the registry doesn’t cover yet, it proposes a new row for architect to confirm before implementation starts.

Blueprint has no application code, so the registry ships with two worked examples — a deactivation rule and a single-use-token rule — clearly marked [EXAMPLE], showing the table shape without claiming to describe your code. A third, under “How to add a rule”, walks through writing a grant-parity rule (every path that grants a role holds the same cap) at the moment a fix caps one grant path, so the fix leaves a rule behind instead of closing one instance. Add your project’s real rules as you find cross-surface behavior worth protecting; “How to add a rule” at the bottom of the file walks through it. An empty or examples-only registry is a normal, temporary state. The failure mode this file guards against isn’t an empty registry — it’s an example row nobody replaced, read later as if it described real enforcement.

It is not a place to track known gaps — “surface X doesn’t enforce this yet” is an issue, not a row annotation; the registry records what’s true today. It is also not a substitute for rbac-check or security-review’s normal per-diff review — it’s the piece those reviews were missing: the sibling surfaces a single diff can’t show them.