Architectural & security boundaries

Where responsibilities begin and end, architecturally, for security, and for the local-first execution model.

Architectural boundaries

The system is layered, and every layer depends only on the ones below it. Higher layers compose lower ones; they never reach around them or duplicate their logic.

flowchart TB
  L5["Control Center, fleet overview (read-only over the registry)"]
  L4["Distribution, Signals & Connectors (generation only)"]
  L3["Identity, Passport & Reputation (composition)"]
  L2["Intelligence, Compliance · Risk · Quality · Trust (over evidence)"]
  L1["Evidence Engine, envelope · receipt · provenance"]
  L0["Provider Router + adapters (mock default, live opt-in)"]
  L5 --> L4 --> L3 --> L2 --> L1 --> L0

Architectural layers, each depends only downward. Source: package layout under src/vailidator/.

Transport vs. logic. api/routes.py validates and composes; it holds no business logic. Every endpoint delegates to an engine and serializes via that capability's to_export_dict().
No logic duplication. TrustEngine reuses Compliance/Risk/Quality; passport/reputation reuse identity + trust profile; the registry only records what upstream produced; the Control Center only reads registry entries. This is stated in each module docstring and enforced by tests.
Stateless vs. stateful. All capability engines are stateless module singletons; the only long-lived state is the in-memory registry (and the SQLite-backed legacy validation store).
Additive evolution. New capabilities arrive as new endpoints / new response fields; existing contracts are preserved byte-for-byte (the audit endpoint's legacy path is kept intact).

Security boundaries

The central security invariant is that secrets and prompts never cross onto the evidence path. The boundary is enforced in several concrete places:

providers/config.py · providers/diagnostics.py · api/routes.py · security/secrets.py

Boundary	Enforcement
API keys	`ProviderConfig` stores presence booleans only, never key values; adapters read keys from the environment at call time; `__repr__` reports present/absent. `mask_secret` returns length, never characters.
Prompts / input	never logged, never placed in `result`/`diagnostics`/evidence; engines inspect only structural fields.
Egress	the audit endpoint returns provider verdict + safe routing/evidence metadata; assessment/identity/signal endpoints operate on structural evidence, so prompts/secrets cannot appear in responses.
HTTP headers	`_SecurityHeadersMiddleware` sets `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `X-XSS-Protection`, `Referrer-Policy`.
CORS	`CORS_ORIGINS` env (JSON array), credentials disabled, methods limited to GET/POST/DELETE/OPTIONS.
Startup gates	V-F3 blocks start when the session secret is ephemeral in production; V-F2 warns on soft secrets.
Build hygiene	`_build.py` excludes `.env` and every `.env.*` except `.env.example` from the shipped zip.

Local-first execution model

VerifAIer runs fully offline by default. Nothing on the evidence path requires a network call unless an operator explicitly opts in.

Mock is the default. ProviderConfig defaults default_provider and provider_mode to mock. The mock adapter is deterministic and never touches the network.
Live is triple-gated. A live provider runs only when enabled AND keyed AND provider_mode == "live". Missing any gate → the router skips it (routing) or the adapter self-falls-back (forced), landing on mock.
Deterministic offline. Every assessment can be re-derived from a stored evidence envelope with no network and no keys, see replay.
In-memory persistence by default. The registry uses MemoryPersistenceStore; JsonPersistenceStore is available for local durability without any external database.
Deploy anywhere. The same deterministic engine runs local-first, air-gapped or sovereign; the docs site itself vendors its assets (including Mermaid) so it renders with no external requests.

Consequence for pilots. A first audit needs no API key and no internet: install, POST an audit, and inspect the receipt, trust score, passport and reputation entirely offline. See First audit.