block / block/buzz

feat(audit): expose paginated, verifiable community audit export

Open
#3,228 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

## Summary

Expose Buzz's existing community-scoped audit chain through a stable, operator-facing export and verification contract.

The current implementation already provides the core primitives in `crates/buzz-audit/src/service.rs`:

- `AuditService::get_entries(...)` for community-scoped, sequence-based pagination;
- `AuditService::verify_chain(...)` for hash-chain verification.

Buzz also has an existing `GET /moderation/audit` route. That endpoint serves the moderation-review workflow; this proposal is for a bounded, verifiable operator export contract suitable for archival and external compliance integrations.

Related umbrella discussion: #2754.

## Motivation

Self-hosted and organizational deployments commonly need to:

- export administrative and security activity;
- archive audit records outside the primary Buzz database;
- feed records into a SIEM, compliance archive, or incident-review system;
- verify that an exported range has not been modified;
- perform investigations without granting direct PostgreSQL access.

Buzz already maintains the underlying per-community hash chain. The missing piece is a supported export surface with stable authorization, pagination, output, and verification semantics.

## Proposed scope

Add an owner/admin-authorized API and corresponding `buzz-admin` commands for bounded audit export and verification.

A possible CLI shape:

```text
buzz-admin audit export --from-seq 1 --limit 1000 --format jsonl
buzz-admin audit verify --from-seq 1 --to-seq 1000
```

The exact API and command names can follow maintainer preference.

The export should support:

- pagination by audit sequence number;
- a configurable page size with a safe maximum;
- strict community scoping derived from the authenticated request context;
- JSON and/or JSONL output;
- `seq`, `hash`, `prev_hash`, `action`, actor, object, detail, and timestamp;
- optional verification of the selected range before returning it;
- a small manifest containing the exported sequence range and final chain hash.

## Relationship to the existing moderation audit route

`GET /moderation/audit` should remain focused on moderation review and its existing UI/API consumers.

This proposal should either:

1. add a separate operator export endpoint, or
2. explicitly version and extend a shared lower-level audit API without changing the moderation route's current contract.

The important distinction is that the new surface is paginated, stable for integrations, and carries enough chain material for independent verification.

## Security requirements

- A request must never return entries belonging to another community.
- Export authorization must require an appropriate operator role.
- Pagination cursors must not contain or override client-controlled tenant identifiers.
- Audit detail fields should be reviewed for secrets before becoming part of a stable export contract.
- Export or verification actions should themselves be audited where practical.
- Errors should not reveal whether another community or sequence range exists.
- The implementation must remain bounded in memory for large audit histories.

## Acceptance criteria

- [ ] An authorized community operator can export a bounded audit range.
- [ ] The export contains sufficient fields for independent hash verification.
- [ ] Altering an exported entry causes verification to fail.
- [ ] Requests cannot cross the host-bound community boundary.
- [ ] Large audit histories can be exported incrementally.
- [ ] Integration tests cover authorization, pagination, tenant isolation, and chain corruption.
- [ ] The output format is documented as a stable integration surface.
- [ ] Existing `/moderation/audit` behavior and consumers remain compatible.

## Non-goals

- Building a complete SIEM product.
- Implementing legal hold or retention policy in this issue.
- Granting ordinary channel members access to the audit chain.
- Changing the current hash-chain construction.
- Claiming that the keyless chain is tamper-resistant against an attacker with database write access; it is tamper-evident, and such an attacker could recompute the chain.

## Contribution

We are interested in contributing the API and/or CLI implementation, tests, and documentation once the preferred operator surface is agreed.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.