stwaidele/dorfteich
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 22 Wiki Activity
issue-214-oidc
dorfteich/docs/architecture/audit-events.md
Claude Fable 5 5796b7a5dd
Some checks failed
CI / Lint, typecheck, test (pull_request) Failing after 14s
Details
CI / Import/export fidelity gate (pull_request) Has been skipped
Details
CI / Build container images (pull_request) Has been skipped
Details
CI / Auth e2e pack (pull_request) Has been skipped
Details
#214: OIDC Authorization Code with PKCE, Keycloak as reference IdP 
External authentication (ADR 0021) built on jose (#188's vetted library)
plus fetch — no new dependency enters the supply chain for a security
base function. Discovery-configured; ID tokens validate against the
IdP's JWKS under an explicit RS256/ES256 allowlist with issuer,
audience, expiry and nonce binding. State, nonce and the PKCE verifier
travel in a signed HttpOnly Lax cookie keyed by a dedicated HKDF
purpose (oidc-state, ADR 0020).

Deploy-level configuration (OIDC_ISSUER/CLIENT_ID/CLIENT_SECRET/SCOPES/
PROVIDER_LABEL): who authenticates users is a platform decision. The
login page discovers the provider via GET /auth/methods and renders the
SSO button (i18n de+en).

Identities use the existing slot (provider oidc:<issuer>, subject from
the token). First login creates the account just-in-time — ACTIVE and
mail-verified only when the IdP asserts a verified address. An existing
local account is NEVER adopted silently by e-mail (account-takeover
path): login refuses with oidc_link_required and the owner links
explicitly via GET /auth/oidc/link (audited auth.identity_linked,
catalogue v1.3). Sessions come from the one existing session service.

Tests run the full flow against a protocol-faithful fake IdP: PKCE
verifier at the token endpoint, JIT creation incl. personal pond,
invalid state/nonce/signature/issuer/audience/expiry each rejected, the
linking refusal and the explicit link flow. Verified end-to-end against
a real Keycloak 26.0 (repeatable procedure documented in security.md
§External authentication).

Refs #214.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8
2026-07-31 12:44:52 +02:00

15 KiB
Raw Permalink Blame History

Audit event catalogue

Catalogue version 1.3 (2026-07-31; 1.3 adds 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

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