Security

The trust model behind every integration and the programme-wide baseline (#303) mapped item by item to the test or CI check that enforces it.

The short version is in SECURITY.md at the repository root: how to report, what is supported, and the trust model — installed packages are trusted, your machine definition is trusted, events and snapshots are not. This page is the longer companion: the numbered baseline every integration is built against, with the evidence for each item. Its twin, Guarantees, covers crash consistency.

Trust boundaries in one picture

flowchart LR
    subgraph trusted["Trusted — your process"]
        M["machine JSON"] --> I["Interpreter"]
        L["actions · guards · services"] --> I
        X["contrib extras you installed"] --> I
    end
    E["events<br/><small>event_schemas · strict</small>"] -.-> I
    S["snapshots from a store<br/><small>size cap · shape · hash · state ids</small>"] -.-> I
    I --> O["logs · audit · dead letters<br/><small>redact()</small>"]

Solid arrows are code you wrote or chose. Dotted arrows cross the boundary and are validated at the send() and from_snapshot() seams; nothing that crosses them is ever executed.

The baseline, item by item

Item numbers are those of #303 — the same numbers every integration page’s Threat model box cites. “Evidence” is a test that fails if the property regresses, or the CI job that enforces it. Every integration the baseline covers has shipped; each item cites its enforcing test.

Two properties the table folds in rather than numbering separately, because #303 lists them under other items: loud failure over silence (unknown config keys raise under strictConfig; missing implementations and undeclared events under strict raise — see Reliability), and the caller-pinned machine hash on restore (under X0.4).

Configuration you own

The table above is what the library does unprompted. These are the switches you must set deliberately; each is the “What you must do” column of SECURITY.md in more detail.

• event_schemas= / strict=True. Without a schema an event payload is an opaque dict. With the [pydantic] extra, context_model and event_schemas validate at the boundary and reject before any action runs.
• principal= on IdempotencyPlugin. Derive it from your authenticated identity, never from the payload — an attacker who controls it can replay another tenant’s receipt.
• codec= on any store if context holds anything you would not put in a log line. Redaction protects sinks; it does not encrypt the snapshot.
• redact_keys= to extend the denylist with your own field names (card_number, ssn, …).
• Exception messages in receipts. receipt_to_json() copies the exception’s class name and str(error) verbatim into error.message — it does not redact. The idempotency inbox caches that JSON and the web adapters’ RFC 9457 problem bodies deliberately carry the class name only (X0.7); if you serialise a receipt yourself (your own cache, your own response body), scrub message first, or raise exceptions whose str() never contains a secret. Pinned by tests/test_battle_305_snapshots_clock_codec.py::test_secret_in_error_message_is_not_redacted_by_codec.
• prefix= per application on Redis, and credentials/TLS on the connection.
• purge_older_than / ttl_s / maxlen so an unbounded key space is a decision, not an accident.

What is out of scope

The library does not authenticate callers, rate-limit send(), or encrypt at rest on its own. Those belong to the layer that owns the socket — the web framework, the broker, the host — and the integration pages for those layers say exactly what they add.