Multi-Tenant Audit Stream

Project roadmap

1. 01

   Design the audit service

   ~2.5h

   Write DESIGN.md: the event format (id, tenant, actor, action, target, time, metadata, the previous event's hash and this event's hash), how the hash is computed (SHA-256 of a canonical JSON of the event plus the previous hash, per tenant), how tenant isolation is enforced (tenant taken from the authenticated API key, never from the request body, and filtered in every query), the export bundle format (events as JSON Lines, a manifest with the first and last hashes, and an Ed25519 signature), and retention. Done when: DESIGN.md covers events, isolation, integrity and exports.

2. 02

   Ingest events safely

   ~2.5h

   Build a Node.js API with POST /events (single or batch), authenticated by per-tenant API keys (stored hashed). Validate events with Zod, reject unknown fields, and append them in a transaction that locks the tenant's chain head, computes the hash from the previous one, and inserts the event (in PostgreSQL or SQLite), with the client's event id as an idempotency key. Done when: events are stored with a valid chain, and duplicates are ignored.

3. 03

   Make storage append-only

   ~1.5h

   Prevent changes at the database level: revoke UPDATE and DELETE for the application's user and add a trigger that rejects them. Add a verify endpoint that walks a tenant's chain and reports the first broken link, if any. Done when: updating an event directly in the database is refused, and the verifier detects an event altered by an administrator on purpose.

4. 04

   Query events

   ~2h

   Add GET /events with filters (actor, action, target, and a time range) and cursor pagination, always scoped to the authenticated tenant. Add indexes on (tenant, time) and (tenant, actor). Write a test showing a tenant can never read another tenant's events, whatever filters it sends. Done when: filtered queries are fast and strictly isolated.

5. 05

   Export signed bundles

   ~2.5h

   Add POST /exports for a time range, which creates the bundle in the background: events as JSON Lines, a manifest with counts, time range and the chain hashes at both ends, and an Ed25519 signature of the manifest made with Node's crypto module. Write a small verify-bundle command that checks the signature, recomputes the chain and confirms the counts, using only the public key. Done when: a downloaded bundle verifies, and editing one byte of it makes verification fail.

6. 06

   Build the dashboard

   ~2h

   Build a React dashboard for tenant admins (logged in with their API key or a simple login) with a filterable, paginated event table, event details, the chain verification status, and buttons to create and download exports. Share the Zod types with the server. Done when: admins can browse their events and download exports.

7. 07

   Test it

   ~2.5h

   Write tests: validation, chain hashing (including concurrent inserts for the same tenant producing a valid chain), idempotency, tenant isolation for every endpoint, the append-only protections, and export verification (valid, tampered and wrong key). Done when: all tests pass.

Resources

• DocsZod documentation
• DocsNode.js: crypto (sign and verify)
• DocsOWASP logging cheat sheet
• ArticleHash chain (Wikipedia)
• DocsRFC 8785: JSON canonicalization scheme