Implement the optional append-only audit export sink #49

New issue

Open

opened 2026-07-28 04:59:57 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-07-28 04:59:57 +00:00

Context

The spec notes that the audit ledger may optionally export to a separate append-only sink
for defense in depth, while remaining clear that the sink is not the canonical source of
truth. The value is that an actor who can modify the primary database cannot retroactively
alter what the sink already received.

Scope

An optional append-only audit export sink.

Implementation notes

Optional and off by default. A local family deployment should not be required to
configure external logging.
Behind an interface: append-only file, syslog, or an external service.
Export asynchronously via the worker. A slow or unreachable sink must never block or
fail the user action that produced the event â€” the audit write to the primary database
is already complete and canonical at that point.
Buffer and retry on sink failure, and make sustained failure visible rather than
dropping events silently.
Preserve ordering and include enough identity for each event to be correlated with the
primary ledger.
Be explicit in the documentation that the sink is defense in depth, not the source of truth.
Audit events contain personal data; document the sensitivity of what is being shipped
off-box before anyone enables it.

Done when

The sink is optional, off by default, and behind a swappable interface
Export is asynchronous and cannot affect the originating action
Failures buffer, retry, and surface rather than dropping events
Events remain correlatable with the primary ledger
Documentation states clearly that the sink is not canonical

References

docs/circa-spec.md sections 3, 6.5, Phase 4

Depends on: #2 (worker runtime).

## Context The spec notes that the audit ledger may optionally export to a separate append-only sink for defense in depth, while remaining clear that the sink is not the canonical source of truth. The value is that an actor who can modify the primary database cannot retroactively alter what the sink already received. ## Scope An optional append-only audit export sink. ## Implementation notes - Optional and off by default. A local family deployment should not be required to configure external logging. - Behind an interface: append-only file, syslog, or an external service. - Export asynchronously via the worker. A slow or unreachable sink must never block or fail the user action that produced the event â€” the audit write to the primary database is already complete and canonical at that point. - Buffer and retry on sink failure, and make sustained failure visible rather than dropping events silently. - Preserve ordering and include enough identity for each event to be correlated with the primary ledger. - Be explicit in the documentation that the sink is defense in depth, not the source of truth. - Audit events contain personal data; document the sensitivity of what is being shipped off-box before anyone enables it. ## Done when - [ ] The sink is optional, off by default, and behind a swappable interface - [ ] Export is asynchronous and cannot affect the originating action - [ ] Failures buffer, retry, and surface rather than dropping events - [ ] Events remain correlatable with the primary ledger - [ ] Documentation states clearly that the sink is not canonical ## References - `docs/circa-spec.md` sections 3, 6.5, Phase 4 Depends on: #2 (worker runtime).

claude-bot added this to the v0.6.0 milestone

2026-07-28 04:59:57 +00:00

claude-bot added the

security

backend

labels

2026-07-28 04:59:57 +00:00

claude-bot referenced this issue

2026-07-28 05:57:13 +00:00

Audit log is mutable and deletable through ordinary ORM access #67

claude-bot referenced this issue

2026-07-30 20:41:46 +00:00