Claude Fable 5
9cf7b85b93
Some checks failed
CI / Lint, typecheck, test (pull_request) Successful in 6m47s
CI / Build container images (pull_request) Successful in 3m59s
CI / Auth e2e pack (pull_request) Successful in 9m7s
CI / Import/export fidelity gate (pull_request) Successful in 57s
CD / Deploy to Test (push) Blocked by required conditions
CD / Smoke tests against Test (push) Blocked by required conditions
CD / Promote to Int (push) Blocked by required conditions
CI / Build container images (push) Blocked by required conditions
CI / Lint, typecheck, test (push) Has been cancelled
CI / Auth e2e pack (push) Blocked by required conditions
CI / Import/export fidelity gate (push) Blocked by required conditions
CD / Build and push images (push) Has been cancelled
POST /admin/users (Site-Admin guard) creates an account with the same field rules as self-registration, but active immediately: the admin vouches for the address, so the e-mail is marked verified and the personal pond is provisioned exactly like the verify-email path does (markEmailVerified alone would skip the pond). The user manager gains a create dialog (useModalFocus/useDismissable, Field wiring, flat RHF field names per the #322 lesson). New audit action user.created_by_admin, catalogue bumped to 1.9. Tests: api e2e-db (create + immediate login + personal pond, duplicate username 409, non-admin 403), web e2e through the dialog, and the admin a11y scan now opens the dialog too. Both packs verified locally against a fresh stack. Closes #331
169 lines
19 KiB
Markdown
169 lines
19 KiB
Markdown
# Audit event catalogue
|
||
|
||
**Catalogue version 1.9 (2026-08-05; 1.9 adds `user.created_by_admin`,
|
||
issue #331; 1.8 added `pond.archived`,
|
||
issue #305; 1.7 added `branding.changed`,
|
||
issue #306; 1.6 added `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.created_by_admin` | Site Admin creates an account directly (#331) | notice | the admin | `user` | — |
|
||
| `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) | — |
|
||
| `branding.changed` | Logo or favicon uploaded or removed (#306/#307) | notice | the admin | `setting` (key) | `scope` (`instance`/`pond`), `asset` (`logo`/`logoDark`/`favicon`), `change` (`set`/`cleared`), `pondId` (pond scope) |
|
||
| `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.archived` | Full pond archive downloaded before deletion or purge (#305) | notice | the pond admin or Site Admin | `pond` | `pages`, `attachments`, `omittedPages`, `complete` |
|
||
| `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.
|