stwaidele/dorfteich
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 22 Wiki Activity
issue-204-page-classification
dorfteich/docs/architecture/audit-events.md
Claude Fable 5 000d110727
All checks were successful
CI / Lint, typecheck, test (pull_request) Successful in 6m9s
Details
CI / Build container images (pull_request) Successful in 3m5s
Details
CI / Auth e2e pack (pull_request) Successful in 8m40s
Details
CI / Import/export fidelity gate (pull_request) Successful in 1m2s
Details
CD / Build and push images (push) Successful in 20s
Details
CD / Deploy to Test (push) Successful in 14s
Details
CD / Smoke tests against Test (push) Successful in 1m18s
Details
CD / Promote to Int (push) Successful in 11s
Details
CI / Lint, typecheck, test (push) Successful in 5m40s
Details
CI / Build container images (push) Has been skipped
Details
CI / Auth e2e pack (push) Successful in 8m10s
Details
CI / Import/export fidelity gate (push) Successful in 57s
Details
#201: stable audit event catalogue for syslog/SIEM export 
The 36 audit action ids become a typed union (AUDIT_EVENTS in
audit-actions.ts) — an uncatalogued id is now a compile error; every
existing id keeps its name. The published, versioned catalogue
(docs/architecture/audit-events.md, v1.0) documents per event: trigger,
severity, actor and target semantics, and every field, plus the
compatibility promise (ids are never repurposed; retiring keeps the row
forever) and the stable stdout field set. audit-catalogue.test.ts is
the fence: it parses the document's event tables and fails when ids or
severities drift from the code (negative case verified). Audit stdout
lines now carry the catalogue severity as a routing hint — pino level
stays 30 so transport is unaffected; no DB migration.

Forwarding path documented: container stdout -> operator's collector;
deliberately no application-side syslog client.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168Ph5uBmHm8X28CSVpbpnJ
2026-07-31 04:51:09 +02:00

146 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Audit event catalogue
**Catalogue version 1.0 (2026-07-31, issue #201).**
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 | info | the new user | — | — |
| `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 | — | — |
| `auth.password_reset` | Password changed via reset token | notice | the user | — | — |
### 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` |
### 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` |
### 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) |
| `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.
Reference in New Issue View Git Blame Copy Permalink