📐 Spec

Spec-09-Audit-Log

2 min readSpec contributor · Node operatorDraft · v0.9.0aN

What this spec defines

The minimum audit surface for security-relevant events in the reference node. Common event requirements, ordering expectations, retention, and export boundaries.

Extraction status

This file contains the ADR-010 prose extraction for audit-log semantics. Component specs define which events they emit; this spec defines common event requirements.

Required properties

Audit records SHOULD include:

AuditEvent {
  event_type:   string
  timestamp:    ISO 8601 UTC
  actor_entity: URI?
  tenant_id:    string?
  scope:        string?
  fact_id:      string?
  outcome:      "success" | "failure" | "denied"
  metadata:     object
}

Events MUST be append-only.

Operators MAY redact sensitive metadata for export, but redaction MUST NOT change the original stored event.

Required event families

Nodes SHOULD audit:

Fact writes and retractions

Fact reads returning data

Auth key lifecycle

Creation, revocation, failed authentication.

Peer registration lifecycle

Registration, verification, rejection, revocation.

Federation fact decisions

Accept/reject.

Scope violations

Capability-token issuance and revocation

Quarantine lifecycle

Admission, promotion, rejection.

CID mismatch/collision

Once CID support is assigned and implemented.

Admin export + config changes

Ordering

Audit events MUST carry wall-clock timestamps. Implementations SHOULD also carry HLC or monotonic ordering metadata when available so investigators can order events across federation boundaries.

Retention

Default retention SHOULD be long enough to support security investigation and operator review. Deployments MAY configure retention, but reducing retention below the documented default SHOULD be an explicit operator choice.

Export

Admin export MUST require administrative authorization. Export responses SHOULD be paginated or streamed when event volume can be large. Export shape must not reveal data the caller is not authorized to inspect.

Failure handling

Audit emission failure on security-critical writes SHOULD fail closed.

For non-critical observability events, implementations MAY fail open but SHOULD log local diagnostics.

Out of scope

This spec does not define SIEM integrations, external log storage, or component event catalogues beyond the required families above.