Skip to content

How a request is protected

Three parts, with all security enforced in the middle one: a PostgreSQL database reachable only by the application container, the FastAPI backend where every rule lives, and one HTML page that holds no security logic on purpose, because a browser page is fully under its user's control and anything enforced there is decoration.

Every request to the backend passes the same gates in order, and each gate exists because of a specific failure:

  • Session check. Who is calling. The session token is an opaque random value, and the database stores only its SHA-256 digest, a one-way fingerprint: someone who reads the table holds nothing they can replay. Sessions are individually revocable and expire absolutely, because expiry without revocation means one stolen token can only be ended by logging everyone out, which in practice means nobody does it.
  • Two different refusals. A missing or dead session gets 401, a valid session without the needed role gets 403 naming the roles that would be admitted. An authenticated caller deserves an answer they can act on, and separating no identity from insufficient authority costs an attacker nothing they could not learn anyway.
  • The role matrix. May this role call this route. One data structure in manifest_identity/core/roles.py is the single answer: the route dependencies read it to enforce and the tests read it to verify, so the enforced matrix and the tested matrix cannot drift apart. A route missing from the matrix fails the build, and a typo in a matrix key crashes the process at startup rather than leaving a route unguarded.
  • The scope check. May this caller act here. The matrix answers which roles a route admits; a write whose target belongs to a place in the estate asks a second question, answered by bindings at that node, at any node above it, or at the global node (D-072). An operator for one account holding the role the matrix admits is still refused on another account's identity, and the refusal says it is the scope, not the role. Authority is answered in one function so the tests can walk it and the mutation check can remove it and watch them fail.
  • Typed validation. Is the request sane. Every body passes a typed model with bounds, and a rejected value is never echoed back, because an error message that repeats attacker input is a reflection surface.
  • The action, through the ORM. The object-relational mapper, the library that turns Python objects into parameterized database queries, is the only path to the database, which removes SQL injection, attacker text becoming database commands, as a class rather than defending it query by query.
  • The audit row, in the same transaction. Any action that changes governance state commits together with its audit record, so neither can exist without the other. A best-effort trail was rejected because the gap between action and record is exactly where an investigation dies.
  • The response, through a declared model. What a client may see is defined by schema, not by what the row happens to contain, so an internal field added next year does not leak by default.

In classic terms the gates implement authentication, access control, and accounting; the design principle is that each is a mechanism that runs, not a rule that hopes. This product reserves the word authorization for the record of what an identity is allowed to hold (D-073), and calls its own gates the role matrix and the scope check.

Sign-in itself gets four defenses of its own. Passwords hash with bcrypt, which salts automatically and is deliberately slow by an adjustable work factor, turning a bulk password-cracking run from hours into years. An unknown username pays the same bcrypt cost and receives the identical response body as a wrong password, so neither timing nor wording reveals which accounts exist. Failed attempts are rate limited per username and per address, counting failures only, with no account lockout, because a lockout hands any attacker who can spell a username a denial of service against its owner. And the attempted password never reaches a log; the log line records that a failure happened, not what was typed.

The password again, for bulk and for credentials. A session proves who signed in, not who is at the keyboard now. Every export, the bulk import of authorizations, and the creation of a user or an integration token ask for the password again when it was last given more than five minutes ago; signing in counts as giving it (D-089). The page asks once and repeats the request. Every export also writes an audit record of who took what, because a bulk export is a disclosure. The routes are one list in core/roles.py, and a test holds the list and the routes' declarations to each other.

Trust boundaries

The four boundaries, the three of version one and the one the authorized half added, are in ARCHITECTURE.md.