Audit log

An append-only record of who did what, chained so that an edit or a gap shows, with filters, export and a retention rule.

This is an app part spec on Spekkr, published by vex. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
vex/audit-log
Version
0.1.2
Published by
vex
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/vex/audit-log/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by vex.

What does the result look like?

Audit log: fieldnote workspaceAudit log: fieldnote audit logAudit log: fieldnote entryAudit log: fieldnote login

What can I customize?

Database
One log for Each workspace has its own log, or the whole app has one.

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance criteria.

    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.
    # 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.
    

    Open spec.md as plain text

  • design.md Data model, rules and flows.

    Design

    This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.

    Data model

    Use the database in the database input.

    TableColumns
    audit_entrieslog_id, seq, at, actor, action, target, data (text), ip, request_id, hash; primary key on log_id and seq
    audit_headslog_id (primary key), seq, hash

    log_id is the workspace's id when the scope input is workspace, and a fixed value when it is app. seq starts at 1 in each log and has no gaps.

    data is stored as text, exactly as it was first written out, and never parsed and written again. The hash covers that text.

    Writing an entry

    In the caller's transaction:

    1. Lock the log's row in audit_heads, creating it if this is the first entry.
    2. Take seq as the stored one plus 1, and the stored hash as the one before.
    3. Redact, write data out as JSON, work out the hash, insert the entry.
    4. Store the new seq and hash in audit_heads.

    The lock is what keeps two entries from taking the same seq. It is held until the caller commits, so keep transactions that record entries short.

    The hash

    line = seq | at | actor | action | target | data      joined by the character |
    hash = SHA-256 of ( hash before, a line feed, line ) as UTF-8, in hexadecimal

    at is written as 2026-01-02T03:04:05Z. A missing target is an empty string.

    Entry 1Entry 2
    seq12
    at2026-01-02T03:04:05Z2026-01-02T03:05:00Z
    actoruser:17user:17
    actionmember.invitedmember.role_changed
    targetworkspace:9user:23
    data{"email":"sam@example.com","role":"member"}{"from":"member","to":"admin"}
    Hash before64 zerosEntry 1's hash

    Entry 1's hash:

    04e07bea7c06897752773ff33cffead84421640c28e9eecfc79608d6a029878e

    Entry 2's hash:

    6ff483be7c06c10095ea69986dfe29da2deeb2e74ac82a3484afc48ade971ae6

    Redaction

    Before data is written out, the value under any key whose lowercase name contains one of these is replaced by [redacted], at any depth: password, secret, token, authorization, api_key, card.

    The trigger

    Reject UPDATE always. Reject DELETE unless the transaction has set a marker that only the job in R8 sets: a setting local to the transaction in Postgres, a row in a one-row table in SQLite. This stops mistakes and casual edits. Someone with full control of the database can still get past it, which is what the chain is for.

    Configuration

    SecretPurpose
    DATABASE_URLConnection string for the chosen database.

    Who is signed in

    The spec reaches the app's sign-in through one function, current_user(request). It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session.

    When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production.

    Named here

    • A request for a workspace the person is not a member of, or that does not exist, gets 404. A member who is not an administrator gets 403.
    • The CSV columns, in order: seq, at, actor, action, target, data, ip, request_id, hash.

    What this spec leaves to you

    Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.

    # Design
    
    This file fixes the parts that are easy to get wrong. Choose the language and
    framework that fit the person's project; nothing here depends on them.
    
    ## Data model
    
    Use the database in the `database` input.
    
    | Table | Columns |
    | --- | --- |
    | `audit_entries` | `log_id`, `seq`, `at`, `actor`, `action`, `target`, `data` (text), `ip`, `request_id`, `hash`; primary key on `log_id` and `seq` |
    | `audit_heads` | `log_id` (primary key), `seq`, `hash` |
    
    `log_id` is the workspace's id when the `scope` input is `workspace`, and a fixed
    value when it is `app`. `seq` starts at 1 in each log and has no gaps.
    
    `data` is stored as text, exactly as it was first written out, and never parsed
    and written again. The hash covers that text.
    
    ## Writing an entry
    
    In the caller's transaction:
    
    1. Lock the log's row in `audit_heads`, creating it if this is the first entry.
    2. Take `seq` as the stored one plus 1, and the stored hash as the one before.
    3. Redact, write `data` out as JSON, work out the hash, insert the entry.
    4. Store the new `seq` and hash in `audit_heads`.
    
    The lock is what keeps two entries from taking the same `seq`. It is held until
    the caller commits, so keep transactions that record entries short.
    
    ## The hash
    
    ```
    line = seq | at | actor | action | target | data      joined by the character |
    hash = SHA-256 of ( hash before, a line feed, line ) as UTF-8, in hexadecimal
    ```
    
    `at` is written as `2026-01-02T03:04:05Z`. A missing target is an empty string.
    
    | | Entry 1 | Entry 2 |
    | --- | --- | --- |
    | `seq` | `1` | `2` |
    | `at` | `2026-01-02T03:04:05Z` | `2026-01-02T03:05:00Z` |
    | `actor` | `user:17` | `user:17` |
    | `action` | `member.invited` | `member.role_changed` |
    | `target` | `workspace:9` | `user:23` |
    | `data` | `{"email":"sam@example.com","role":"member"}` | `{"from":"member","to":"admin"}` |
    | Hash before | 64 zeros | Entry 1's hash |
    
    Entry 1's hash:
    
    ```
    04e07bea7c06897752773ff33cffead84421640c28e9eecfc79608d6a029878e
    ```
    
    Entry 2's hash:
    
    ```
    6ff483be7c06c10095ea69986dfe29da2deeb2e74ac82a3484afc48ade971ae6
    ```
    
    ## Redaction
    
    Before `data` is written out, the value under any key whose lowercase name
    contains one of these is replaced by `[redacted]`, at any depth: `password`,
    `secret`, `token`, `authorization`, `api_key`, `card`.
    
    ## The trigger
    
    Reject `UPDATE` always. Reject `DELETE` unless the transaction has set a marker
    that only the job in R8 sets: a setting local to the transaction in Postgres, a
    row in a one-row table in SQLite. This stops mistakes and casual edits. Someone
    with full control of the database can still get past it, which is what the chain
    is for.
    
    ## Configuration
    
    | Secret | Purpose |
    | --- | --- |
    | `DATABASE_URL` | Connection string for the chosen database. |
    
    ## Who is signed in
    
    The spec reaches the app's sign-in through one function, `current_user(request)`.
    It answers with the person's id, and says whether they are an administrator where
    this spec asks. In the person's app it reads their session.
    
    When there is no app yet, build this stand-in and nothing more: a page that lists
    two seeded people, one of them an administrator, with a button for each that sets
    a signed cookie naming them. The stand-in refuses to start in production.
    
    ## Named here
    
    - A request for a workspace the person is not a member of, or that does not
      exist, gets 404. A member who is not an administrator gets 403.
    - The CSV columns, in order: `seq`, `at`, `actor`, `action`, `target`, `data`,
      `ip`, `request_id`, `hash`.
    
    ## What this spec leaves to you
    
    Where this spec names something, use that name, so that two builds of it agree.
    Where it does not, the choice is yours. List what you chose in the README.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. Add the tables in design.md. If there is no app yet, build the smallest one: a signed-in user who may be an administrator, a workspace if scope is workspace, and three things that change, to record. Check: migrations run from empty.
    2. Record (R1, R2). The list of actions, audit, and redaction. Check: the R1 and R2 acceptance tests pass.
    3. Append only (R3). The trigger. Check: the R3 acceptance tests pass.
    4. The chain (R4). Only if hash_chain is on. A pure function for the hash, the lock, and the command that checks. Check: a test reproduces both hashes in design.md, and the R4 tests pass.
    5. Read (R5). Check: the R5 acceptance tests pass.
    6. Export (R6, R7). Only if export is on. Check: the R6 and R7 acceptance tests pass.
    7. Forget (R8). Use the retention_days input and a clock that tests set. Check: the R8 acceptance test passes.
    8. Pages (R9). Check: the page can be used with a keyboard alone and at 360 pixels wide.
    9. Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** Add the tables in `design.md`. If there is no app yet, build the
       smallest one: a signed-in user who may be an administrator, a workspace if
       `scope` is `workspace`, and three things that change, to record.
       Check: migrations run from empty.
    
    2. **Record (R1, R2).** The list of actions, `audit`, and redaction.
       Check: the R1 and R2 acceptance tests pass.
    
    3. **Append only (R3).** The trigger.
       Check: the R3 acceptance tests pass.
    
    4. **The chain (R4).** Only if `hash_chain` is on. A pure function for the hash,
       the lock, and the command that checks.
       Check: a test reproduces both hashes in `design.md`, and the R4 tests pass.
    
    5. **Read (R5).**
       Check: the R5 acceptance tests pass.
    
    6. **Export (R6, R7).** Only if `export` is on.
       Check: the R6 and R7 acceptance tests pass.
    
    7. **Forget (R8).** Use the `retention_days` input and a clock that tests set.
       Check: the R8 acceptance test passes.
    
    8. **Pages (R9).**
       Check: the page can be used with a keyboard alone and at 360 pixels wide.
    
    9. **Finish.** Write the README and run the whole test suite.
       Check: every item under "Definition of done" in `spec.md` is true.
    

    Open tasks.md as plain text

Is it for me?

Platforms
backend, web

What does it need?

Agent permissions
shell, network
Secrets it reads
DATABASE_URL

What changed?

  • 0.1.215 Nov 2026Names what it builds.
  • 0.1.114 Nov 2026Says "person" where it said "buyer".
  • 0.1.014 Nov 2026Moved from dwrtz/audit-log.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.