Claude Opus 5
b96997501a
All checks were successful
CI / Build container images (pull_request) Successful in 3m53s
CI / Auth e2e pack (pull_request) Successful in 8m42s
CI / Auth e2e pack (push) Successful in 8m41s
CI / Lint, typecheck, test (pull_request) Successful in 6m30s
CI / Import/export fidelity gate (pull_request) Successful in 58s
CD / Build and push images (push) Successful in 18s
CD / Smoke tests against Test (push) Successful in 1m19s
CD / Deploy to Test (push) Successful in 16s
CD / Promote to Int (push) Successful in 12s
CI / Lint, typecheck, test (push) Successful in 6m41s
CI / Build container images (push) Has been skipped
CI / Import/export fidelity gate (push) Successful in 52s
An operator holding a font licence could only use it by baking the file into a custom image, which tied every change to a rebuild and left the file out of the backup. ADR 0016 said there is no runtime font management. It also listed this exact case under "Alternatives considered" — *may become a Site-Admin- level feature later*. The amendment takes that option and answers the two objections it raised: licensing risk (Site Admins only, licence recorded with the family) and file-format attack surface (magic-byte check and a size cap, never a parse). - `CUSTOM_FONTS_DIR` (default `./data/fonts`) — a sibling of uploads and plugins, NOT inside the image-baked `FONTS_DIR`, where a deploy would overwrite it and no backup would ever see it. - One list of data directories (`apps/backup/src/data-dirs.ts`) now feeds both the nightly archive and the restore, so they cannot drift. #306 and #307 add one line each instead of a second mechanism. - Both Dockerfiles bake the path. The backup image sets its volume paths itself ("self-sufficient without compose env" — #71's lesson) and reads no *_DIR from compose; without the ENV entry the archive would have skipped the directory silently. - The PDF path already read WOFF2 from disk at request time, so it only had to pick the other base directory for a custom family. - `fontStack`/`fontEntry` take the instance's uploaded families as an argument — they are runtime data. The catalog is searched first, and a colliding family name is rejected at upload, so a custom font can never shadow a catalog one. - Deletion is never blocked by usage: an unknown family already falls back to the system stack, so affected ponds degrade instead of breaking. The count of affected ponds travels into the audit entry. - Audit catalogue v1.6 (`font.uploaded`, `font.deleted`). Verified: api full suite against a fresh database, 102 files / 571 tests. The upload suite writes into a real temp directory and reads the bytes back off disk, so the storage layer is exercised rather than mocked.
163 lines
17 KiB
Markdown
163 lines
17 KiB
Markdown
# Audit event catalogue
|
||
|
||
**Catalogue version 1.6 (2026-08-01; 1.6 adds `font.uploaded` and
|
||
`font.deleted`, issue #303; 1.5 added `plugin.rejected`,
|
||
issue #232; 1.4 added `auth.proxy_rejected`, issue #215; 1.3 added `auth.identity_linked`, issue #214; 1.2 added
|
||
`read_trail.pruned`, issue #224; 1.1 added `page.classification_*`,
|
||
issue #205).**
|
||
|
||
This is the operator-facing contract for the audit trail: every event id
|
||
the application can emit, with its trigger, severity, actor/target
|
||
semantics, and fields. SIEM/syslog rules written against this document
|
||
survive application updates because of the compatibility promise below.
|
||
|
||
The code half of this catalogue is `apps/api/src/audit/audit-actions.ts`
|
||
(a typed union — an uncatalogued id cannot be emitted), and
|
||
`audit-catalogue.test.ts` fails CI whenever this document and that code
|
||
drift. Changing either alone is impossible.
|
||
|
||
## Compatibility promise
|
||
|
||
- **Ids are never repurposed.** The meaning of an id listed here is frozen.
|
||
- **Adding events** bumps the catalogue's minor version; existing rules
|
||
are unaffected.
|
||
- **Retiring an event** (it stops being emitted) keeps its row here,
|
||
marked retired, forever; removal of a row is a major version and is
|
||
called out in the release notes.
|
||
- Fields listed per event are stable; new optional fields may be added
|
||
(minor version), fields are never renamed or repurposed.
|
||
|
||
## Transport & field set
|
||
|
||
Audit events reach the operator on **two channels**, both fed by the same
|
||
`AuditService.record()` call:
|
||
|
||
1. **stdout log line** (pino JSON, the forwarding channel): the container
|
||
runtime captures stdout (Docker `json-file` with rotation); the
|
||
operator's collector (promtail/fluent-bit/vector/…) picks it up from
|
||
there and forwards to syslog/SIEM. **There is deliberately no
|
||
application-side syslog client** — transport, TLS and buffering are the
|
||
collector's job, one layer below the app.
|
||
2. **`audit_log` table** (the queryable trail with its own retention,
|
||
#196), shown in the Site-Admin panel.
|
||
|
||
Every audit stdout line carries this stable field set:
|
||
|
||
| Field | Meaning |
|
||
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||
| `msg` | `audit: <event id>` — the selector; collectors match on the `audit: ` prefix and take the id from the remainder. |
|
||
| `severity` | The catalogue severity of the id (`info` \| `notice` \| `warning` \| `critical`) — the routing hint for rules. |
|
||
| `actor` | Acting user id, or `null` for anonymous/system events (each row below states which). |
|
||
| `targetType` / `targetId` | What the event is about (absent when the event has no target). |
|
||
| _event fields_ | The per-event fields from the tables below, flattened into the line's top level. |
|
||
| `level`, `time`, `context` | pino plumbing: always `30`/epoch-ms/`AuditService`. Severity routing uses `severity`, not `level`. |
|
||
|
||
The `audit_log` row stores the same data structurally: `action`,
|
||
`actor_id`, `target_type`, `target_id`, `details` (the per-event fields as
|
||
JSON), `at`. Secrets, tokens, request bodies, and page content never
|
||
appear in either channel (security.md §Logging).
|
||
|
||
## Events
|
||
|
||
Severity vocabulary: `critical` = page someone (integrity/security
|
||
failure), `warning` = feeds detection (suspicious or destructive),
|
||
`notice` = configuration/privilege change, `info` = normal lifecycle.
|
||
|
||
### Authentication (`auth.*`)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| ---------------------- | ----------------------------------------------------------------------------------------- | -------- | ------------------------------------ | ------ | ------------------------------------- |
|
||
| `auth.signup` | Account created via self-registration or OIDC just-in-time (issue #214) | info | the new user | — | `provider` (optional; absent = local) |
|
||
| `auth.email_verified` | E-mail double-opt-in completed | info | the verified user | — | — |
|
||
| `auth.login_failed` | Login rejected (bad credentials) | warning | matched user, `null` if unknown name | — | — |
|
||
| `auth.login_succeeded` | Session created | info | the user | — | `provider` (optional; absent = local) |
|
||
| `auth.password_reset` | Password changed via reset token | notice | the user | — | — |
|
||
| `auth.identity_linked` | OIDC identity linked to an existing account via the explicit link flow (issue #214) | notice | the linking user | — | `provider` |
|
||
| `auth.proxy_rejected` | Proxy-auth header received from a peer outside the allowlist — spoof attempt (issue #215) | warning | `null` (unauthenticated) | — | `peer`, `header` |
|
||
|
||
### Access & membership (`grant.*`, `member.*`)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| --------------------- | --------------------------- | -------- | ------------- | ------ | ----------------------------------------------------------------------- |
|
||
| `grant.created` | Access rule added to a pond | notice | granting user | `pond` | `grantId`, `subject`, `subjectId`, `role`, `scope`, `scopeId`, `effect` |
|
||
| `grant.deleted` | Access rule removed | notice | acting user | `pond` | `grantId`, `subjectId`, `role` |
|
||
| `member.added` | User added to a pond | notice | acting user | `pond` | `member` (user id), `role` |
|
||
| `member.role_changed` | Member's role changed | notice | acting user | `pond` | `member`, `role` (new) |
|
||
| `member.removed` | Member removed from a pond | notice | acting user | `pond` | `member` |
|
||
|
||
### Administration (`user.*`, `quota.*`, `settings.*`, `job.*`)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| -------------------------- | ------------------------------------------------------ | -------- | --------------- | ---------------- | -------------------- |
|
||
| `user.disabled_set` | Site Admin disables/enables an account | notice | the admin | `user` | `disabled` (bool) |
|
||
| `user.site_admin_set` | Site-Admin privilege granted/revoked | notice | the admin | `user` | `isSiteAdmin` (bool) |
|
||
| `user.deleted` | Account deleted by a Site Admin | notice | the admin | `user` | — |
|
||
| `user.pseudonymized` | GDPR pseudonymization of authorship completed | notice | `null` (system) | `user` | — |
|
||
| `user.verification_resent` | Site Admin re-sends the verification mail | info | the admin | `user` | — |
|
||
| `quota.override_set` | Per-user/per-pond quota override set | notice | the admin | `user` \| `pond` | `quotaKey`, `value` |
|
||
| `quota.override_cleared` | Quota override removed | notice | the admin | `user` \| `pond` | `quotaKey` |
|
||
| `settings.changed` | Instance setting written | notice | the admin | `setting` (key) | — |
|
||
| `job.triggered` | Maintenance job started manually from the System panel | info | the admin | `job` (name) | `outcome` |
|
||
|
||
### Classification (`page.classification_*`, ADR 0022, issue #205)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| ----------------------------- | ------------------------------------------------------------------------------------------------------- | -------- | --------------- | ------ | ------------------------------------------------------------------------ |
|
||
| `page.classification_raised` | Page's VS-NfD level raised — by an editor, or automatically when moved under a higher-classified parent | notice | the acting user | `page` | `from`, `to` (levels, lowercase), `trigger` (`edit` \| `move`), `pondId` |
|
||
| `page.classification_lowered` | Page's VS-NfD level lowered — requires the dedicated capability (pond-wide Pond Admin) | warning | the acting user | `page` | `from`, `to`, `trigger` (`edit`), `pondId` |
|
||
|
||
### Content integrity & lifecycle (`file.*`, `pond.*`, `audit.*`)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| ----------------------- | -------------------------------------------------------------------- | -------- | ---------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `file.integrity_failed` | Attachment download hash mismatch — fail-closed (issue #199) | critical | `null` (any downloader; detection) | `attachment` | `pondId`, `expected` (stored sha256), `actual` (computed sha256) |
|
||
| `pond.purged` | Pond irreversibly destroyed (manual or trash retention, issue #193) | notice | admin, `null` when retention-run | `pond` | `trigger` (`manual` \| `retention`) plus per-object-type deletion counts (e.g. `pages`, `attachments`, … — informational, keys may grow) |
|
||
| `audit.pruned` | Audit retention deleted rows past the period (issue #196) | info | `null` (system) | — | `count`, `cutoff` (ISO), `retentionDays` |
|
||
| `read_trail.pruned` | Read-trail retention removed events past its own period (issue #224) | info | `null` (system) | — | `count`, `cutoff` (ISO), `retentionDays` |
|
||
|
||
### Public API (`api.*`)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| ------------------- | ----------------------------------------- | -------- | ----------- | ----------------------- | -------------------------------- |
|
||
| `api.token_created` | Personal access token created | info | token owner | `api_token` | `name`, `scope`, `ponds` (count) |
|
||
| `api.token_revoked` | Personal access token revoked | info | token owner | `api_token` | — |
|
||
| `api.write` | Mutation performed through the public API | info | token owner | `api_write` (object id) | `op`, `tokenId`, `tokenName` |
|
||
|
||
### Plugins (`plugin.*`)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| --------------------- | ----------------------------------------------------------------- | -------- | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `plugin.installed` | Plugin package installed or updated | notice | admin, `null` for dropzone drop | `plugin` | `version`, `update` (bool) |
|
||
| `font.uploaded` | Site Admin uploaded a custom font family or added a weight (#303) | notice | admin | `font` | `family`, `weight` (when a single weight was added) |
|
||
| `font.deleted` | Site Admin removed a custom font family (#303) | notice | admin | `font` | `family`, `pondsAffected` (count of ponds still referencing it) |
|
||
| `plugin.rejected` | Install or load blocked by the hash-pinning allowlist (#232) | warning | admin for installs, `null` for loads | `plugin` | `surface` (`install`/`load`), `reason` (`not_pinned`/`hash_mismatch`/`unpinned`/`mismatch`), `version`, `bundleHash` (installs) |
|
||
| `plugin.mode_set` | Instance mode changed (disabled/optional/required) | notice | the admin | `plugin` | `mode` |
|
||
| `plugin.uninstalled` | Plugin removed | notice | the admin | `plugin` | — |
|
||
| `plugin.pond_toggled` | Optional plugin toggled for one pond | info | the pond admin | `pond` | `plugin`, `enabled` |
|
||
|
||
### Backup & restore (`backup.*`)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| -------------------------- | ------------------------------------------------- | -------- | --------- | -------------------- | ------------------ |
|
||
| `backup.settings_changed` | Backup target settings written | notice | the admin | — | `nextcloudEnabled` |
|
||
| `backup.run_triggered` | On-demand backup requested ("Back up now") | info | the admin | — | — |
|
||
| `backup.restore_requested` | In-app restore requested (type-to-confirm passed) | warning | the admin | `backup` (backup id) | `source` |
|
||
|
||
### First-run setup (`setup.*`)
|
||
|
||
| Id | Trigger | Severity | Actor | Target | Fields |
|
||
| --------------------- | ---------------------------------------- | -------- | ----------------- | ------ | ------ |
|
||
| `setup.preseeded` | Instance pre-configured from stage env | info | the seeded admin | — | — |
|
||
| `setup.admin_created` | First Site Admin created by the wizard | notice | the created admin | `user` | — |
|
||
| `setup.smtp_stored` | SMTP settings stored by the wizard | info | the admin | — | — |
|
||
| `setup.completed` | Setup wizard finished; instance unlocked | info | the admin | — | — |
|
||
|
||
## Scope boundary
|
||
|
||
Content activity (who edited which page, file up/downloads that succeed,
|
||
exports, labels) intentionally stays out of this trail — it answers "who
|
||
changed access/configuration and did the platform detect tampering", not
|
||
"who edited what" (security.md §Logging). The read-access trail for
|
||
classified content is a separate, VS-NfD-specific mechanism (#222–#225)
|
||
with its own catalogue entry when it lands.
|