# Audit log ## What this builds A record of who did what and when, for the people who run an account and for whoever asks them to prove it. Entries are written with the change they describe, cannot be edited, and can be checked for tampering. Read `spekkr.inputs.json` first. `scope` says whether each workspace has a log or the app has one. Entries are kept `retention_days` days. `hash_chain` decides whether R4 exists and `export` whether R7 does. This spec needs the app to know who is signed in and who is an administrator. ## Out of scope - A feed of activity for ordinary users. This is for administrators. - Logs of requests and errors for developers. - Sending entries to an outside system as they happen. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Record - App code calls `audit(actor, action, target, data)` in the same database transaction as the change it describes. The entry exists exactly when the change was committed. - Actions are a fixed list in code, each written as a thing, a full stop and what happened: `member.invited`, `member.role_changed`, `settings.updated`. An action that is not in the list is an error. - The spec records three example actions from a small example of its own. Accept when: a rolled-back transaction leaves no entry, and an unknown action is refused. ### R2. What an entry holds - A number that only grows, the time in UTC to the second, the actor, the action, the target, and data about the change of at most 4 KB (4,000 bytes). - The actor is a kind and an id: `user:17`, `api_key:k3`, or `system` for the app itself. The target is written the same way. - The IP address and the request's id, when there is a request. - For a change of a value, the data holds the value before and after. Accept when: an entry made from a request holds its IP address, and one made by a background job has `system` as its actor. ### R3. Append only - No route and no function changes or deletes an entry. The only removal is R8. - The database refuses too: a trigger rejects every `UPDATE` and `DELETE` on the table that does not come from R8. - Values under keys that name a secret are never written. Their place holds `[redacted]`. The list of such keys is in `design.md`. Accept when: an `UPDATE` sent straight to the database is refused, and data with a `password` key is stored with `[redacted]` in its place. ### R4. Chain the entries Only if `hash_chain` is on. - Each entry holds a hash made from the hash of the entry before it and its own content, as `design.md` describes. The first entry of a log uses 64 zeros. - Entries of one log are written one at a time, so the chain never forks. - A command checks a log from start to end and names the first entry whose hash does not match, or says the log is whole. Accept when: the test vector in `design.md` is reproduced, the check passes on an untouched log, and after one entry's data is changed behind the trigger's back the check names that entry. ### R5. Read - Administrators see the log newest first, 50 entries at a time, and load more with a cursor. - Filters: actor, action, target, and a range of dates. They can be combined. - Each entry is shown in words, such as "Ana invited sam@example.com as member", with the raw entry one click away. - With `scope` set to `workspace`, an administrator sees their workspace's log and no other. Accept when: each filter narrows the list, and a request for another workspace's log gets 404. ### R6. Reading is recorded - Opening the log is not recorded. Exporting it is, as `log.exported`, with the filters used. Accept when: an export leaves one entry that names who exported. ### R7. Export Only if `export` is on. - Administrators download the entries the current filters show, as CSV, in the order of the chain. - The file is written as a stream. A log of a million entries does not need a million entries of memory. - A cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return gets a single quote in front, so a spreadsheet does not run it as a formula. Accept when: an entry whose data starts with `=` is exported with a quote in front. ### R8. Forget old entries - A daily job deletes entries older than `retention_days` days, oldest first. - If `hash_chain` is on, the job then writes an entry, `log.trimmed`, that holds the number and the hash of the last entry it deleted. The check in R4 starts from that entry and still passes. Accept when: after the job runs, only entries young enough remain and the check passes. ### R9. Pages - The log, with its filters and the raw view of one entry. Accept when: the page works with a keyboard alone and at a 360 pixel wide screen, and a person who is not an administrator gets 403. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. - A README explains how to add an action, how to record one, how to run the check, and how to run the tests.