Expand description
S7 (#573, epic #547) — tamper-evident, complete audit of every MAC authorization decision, with OpenTelemetry fan-out.
This is the Accounting leg of the MAC security model: every allow/deny
the PDP (crate::mac::avc) produces is recorded tamper-evidently, and a
decision that cannot be audited is denied (fail-closed). The store is a
data-plane structure — append-only, content-addressed, signed, and
WAL-durable on write (a write is durable before the decision returns).
§Design (the four properties the task requires)
- Append-only — the on-disk log is opened append-only; the API exposes
no mutate/delete. The CAS layer writes content-addressed blobs whose
names are their own hash, so overwrites are no-ops and a name never
points at different bytes. See
WalAuditStoreand its tests. - Content-addressed — every
AuditRecordis BLAKE3-hashed over its canonical CBOR encoding (deterministic: sorted maps, sorted keys), so the same decision yields the same hash (AuditRecord::content_hash). Tamper-evident by construction: changing any field changes the hash, which breaks the signature that covers it. - WAL-durable on write —
WalAuditStore::recordappends the signed record to a journal, thenfsyncs the file and its parent directory before returningOk(()). The caller (the AVC) does not return a Permit untilrecordreturns, so a Permit is never handed out ahead of a durable audit entry. See thewal_record_is_durable_before_returntest. - Signed + hash-chained — each record is signed via the existing COSE
path (
crate::mac::compiled::cose/sign_composite), and each record carries theprev_hashof its predecessor, so the journal is an append-only chain. Tamper evidence is conjoint: altering a record breaks its hash (and thus its signature); reordering or deleting a middle record breaks the successor’sprev_hashlink. A deleted tail leaves a still-valid shorter chain, so it is caught instead by the signed checkpoint (§ Truncation) — the head anchor written out-of-band after every record.
§Truncation detection (the actual guarantee — and its limit)
After every durable append, the store writes a signed checkpoint (a
separate checkpoint file) recording the current head (seq, head_hash).
On open, the store fails closed if the journal’s head sequence is below
the checkpoint’s — i.e. the tail was truncated. [WalAuditStore:: verify_journal] additionally verifies the checkpoint’s signature and that
it matches the journal head, so a forged or rolled-back checkpoint is
rejected offline.
Residual limit (honest): the checkpoint is a local anchor. An attacker with write access to BOTH the journal and the checkpoint can truncate both consistently and evade local detection. Closing that requires an off-host anchor (replicate the signed head to OTel / a second host); that is tracked as a follow-up and deliberately out of scope here. What this store guarantees today: no tampering, reordering, or middle-deletion goes undetected, and tail-truncation is detected unless the checkpoint is destroyed in the same act.
§Complete mediation (the hook point)
AuditedAvc wraps any Avc and routes every decide /
decide_with_token call through the audit sink. Because the AVC is the
single per-op entry point the PEP (S2) calls, auditing there is complete
mediation: no decision bypasses it. On a cache hit the cached decision is
still re-recorded (cheap: a hash + append + fsync) so the audit log reflects
every op the PEP actually performed, not just PDP misses — completeness over
cache efficiency.
§Fail-closed on audit failure
If the audit write fails (disk full, IO error, signer error), the audited
AVC downgrades a Permit to Deny and records the deny it actually
enforced. A decision that cannot be audited is never allowed through. This
is the explicit fail-closed contract; see the permit_downgrades_to_deny_
when_audit_write_fails test.
§OpenTelemetry fan-out (fixes #453)
Every decision emits a structured [tracing] event on the dedicated
hyprstream.mac.audit target with fields decision, subject, resource,
action, generation, and reason. OTel is wired as a tracing
subscriber (see bin/main.rs init_telemetry), so these events fan out to
OTLP automatically when the otel feature is active — denials become
first-class observable signals, no longer buried at debug level.
§What is deferred (documented TODOs)
- Cross-host replication of the audit store — S7 ships the local
tamper-evident store; replication (gossip/OTLP log export to a central
audit collector) is
TODO(S7-followup):inWalAuditStore. - Retention / rotation — the journal grows unbounded; rotation + remote
archival is
TODO(S7-followup):below. - Policy-evolution feedback — denials feeding back into PolicyService is
TODO(S7-followup):— the records are here, the consumer is not. - Hybrid (EdDSA + ML-DSA-65) signing of audit records — S8 (#574) made
the
cose::CoseAuditSignerpolicy-aware: under a Hybrid crypto policy it fails closed if no ML-DSA-65 key is provisioned (no silent downgrade of a security-critical accounting artifact). Production wiring of the audited AVC (constructing aWalAuditStorewith the node’s PQ audit key and installing it in the PEP) isTODO(S7-followup):.
Modules§
- cose
- Production signer/verifier adapters over
hyprstream_rpc::crypto::cose_sign, mirroringcrate::mac::compiled::cose.
Structs§
- Audit
Record - A single authorization decision, as recorded by the audit store. This is the unit of tamper-evidence: it is content-addressed (BLAKE3 over canonical CBOR), signed, and append-logged.
- Audited
Avc - An
Avcthat routes every decision through anAuditSink. This is the S7 complete-mediation hook: because the PEP (S2) calls the AVC per op, wrapping it here audits every decision with no bypass. - Delegation
Principal - The delegator principal recorded on a delegated (two-principal, #680/#681)
decision — the source of authority on whose behalf the record’s
subject_*(the effective, met context) was evaluated. - Null
Audit Sink - A no-op sink for environments that opt out of durable audit (e.g. tests of the PDP itself that are not exercising S7). Not for production — production requires tamper-evident audit, which this provides none of.
- WalAudit
Store - The authoritative tamper-evident audit store. Append-only journal + content-addressed CAS blobs, each record signed. WAL-durable on write.
Enums§
- Audit
Error - Audit-store failures. All are fail-closed at the AVC boundary.
- Decision
Reason - Why the PDP returned this decision. Recorded so denials are diagnosable and so the policy-evolution feedback (deferred) can bucket denials by cause.
Traits§
- Audit
Signer - Abstraction over the authority that signs audit records. Production wires
the hybrid COSE composite (EdDSA + ML-DSA-65) via
crate::mac::compiled::cose; tests use a trivial stub. - Audit
Sink - Where the audited AVC sends records. The authoritative impl is
WalAuditStore; tests / non-durable deployments can swap a no-op or in-memory sink. Fail-closed contract: arecorderror makes the audited AVC downgrade a Permit to Deny (seeAuditedAvc). - Audit
Verifier - Abstraction over signature verification (for log-integrity checks / replay).
Functions§
- audit_
signing_ input - Domain-separated signing input: a fixed tag + the content hash. Binding the hash (not the raw bytes) keeps the signed payload small and stable, and makes the signature independent of the canonical-bytes serialization choice.
- checkpoint_
signing_ input - Domain-separated signing input for the head-anchor checkpoint
(seq, head_hash). The tag differs fromaudit_signing_inputso a per-record signature can never be replayed as a checkpoint signature (and vice-versa).