curriculum-project-hub/docs/adr/0039-filelib-audit-log-module.md

ADR 0039: File Library Audit Log Is A Cross-Cutting Append-Only Module

Status

Accepted.

Context

Audit was previously a single sink function (filelib/audit.ts) writing rows into the shared AuditEntry table: action + actorUserId + organizationId + a free metadata JSON blob. It satisfied "the write happened", nothing more.

The file-library requirements ask for materially stronger properties across the version-management and permission-management submodules: structured before/after values, actor name snapshot, client IP/User-Agent, success/failure with a reason, conflict-detection events carrying base and conflicting versions, combined multi-dimension query with export, three-tier read visibility, tamper resistance, and a retention floor of 180 days.

Three of those cannot be expressed on the old shape at all:

• Failure results. Every audit write sat inside the business transaction, so a failed operation rolled its own audit row back. "Operation result = failure and reason" was structurally unrecordable. This also silently dropped file.conflict_detected, an event the requirements name explicitly — it was written and then rolled back with the 409.
• Query by dimension. Object type, object id, result, and path lived inside the metadata JSON. Filtering on them means JSON path scans, and there is no index to hang on them.
• Tamper resistance. AuditEntry is documented as best-effort telemetry (ADR-0023) and is Project/Run oriented. It carries no hash chain and no append-only enforcement.

ADR-0023 already fixed that privileged platform audit must be separate from customer Project/Run audit. It did not cover the file library's own submodule audit, which is the subject here.

Decision

Separate store

File-library audit gets its own table, FileLibAuditLog, distinct from both AuditEntry (Project/Run, best-effort) and Platform Audit Entry (ADR-0023). Every required field is a real column: occurredAt (timestamptz), actorUserId plus actorName snapshot, actorIsAdmin, objectType/objectId/objectName/ objectPath, beforeValue/afterValue/context (JSONB), result and failureReason, clientIp and userAgent, and the chain fields seq, entryHash, prevHash.

actorName is a snapshot, not a join: audit records who acted under the name they had at the time. Object references carry no foreign key — a purged object's history must survive the object.

Two write paths with opposite error semantics

• Success writes inside the caller's business transaction and does not swallow errors. If the audit row cannot be written, the business operation rolls back. This is the implementation of "operation succeeded ⟹ log exists".
• Failure and conflict-detection write out-of-band on an independent connection, and do swallow errors. The business transaction has already rolled back, so a same-transaction write would vanish; and an audit failure at that point must not turn a 409 into a 500.

The two paths' error handling is deliberately inverted. Unifying them breaks one guarantee or the other.

Tamper resistance

Three independent layers, in order of what each defends against:

1. Service paths only INSERT and SELECT.
2. A BEFORE UPDATE OR DELETE trigger rejects every row change except a write-once archivedAt stamp; a BEFORE TRUNCATE statement trigger blocks the row-trigger bypass. This holds even when the application layer is wrong.
3. A sha256 hash chain: entryHash = sha256(prevHash + canonical payload), linked per organization by a monotonic seq. The chain is recomputable offline, so changes made by bypassing the service entirely — direct DB access, restoring a doctored backup — still surface as a break.

Payload canonicalization sorts object keys. Without it the same record serialized in a different key order hashes differently and verification reports phantom tampering.

Retention

Default retention is 180 days and that is a floor, not a default: HUB_FILELIB_AUDIT_RETENTION_DAYS may raise it and cannot lower it. Expired records are archived by stamping archivedAt, never physically deleted — consistent with the DELETE trigger. Archived records drop out of default queries but remain readable with an explicit flag, and remain in the hash chain. The archive run itself is audited.

Read visibility

Three tiers, resolved entirely in the query layer so no second authorization implementation can drift from it:

• Website administrator (silo org OWNER/ADMIN, D19): the whole system.
• MANAGE holder: logs for nodes they hold MANAGE on and their subtrees, matched by objectPath prefix against the pathIds materialized path. File logs use <pathIds>:<filePath>, so subtree matching covers them without a second rule.
• Everyone else: an empty result, not a 403 — consistent with D8's refusal to leak existence.

Group logs use group:<id> as their objectPath. That is outside the node path space, so they are visible to website administrators only.

Module boundary

The audit capability lives in src/database/audit/ and imports no file-library business type. Business services depend on it through one adapter, filelib/audit.ts, which translates domain concepts (FileLibActor, node kind, pathIds) into audit ones. The dependency is one-directional, so the module can be replaced by a standalone audit service without touching business code.

Client IP and User-Agent are captured once in the HTTP guard and travel on the actor. Business services never see the request object.

Consequences

• AuditEntry remains for Project/Run telemetry. File-library audit no longer writes to it; the dashboard's recent-activity feed reads the new table, which is why it can show actor and object names without a join.
• Audit failure can now fail a business write. That is the intended trade: a silently unlogged permission change is worse than a failed one.
• Failure records exist without a corresponding state change. Consumers must read result — counting rows per action no longer counts successful operations.
• The hash chain serializes audit writes per organization through a max(seq) + 1 read. Under the alpha Silo's one-org-one-process deployment (ADR-0025) contention is negligible; the unique constraint on (organizationId, seq) makes a collision a retry rather than a corrupt chain. A future high-write deployment will need a sequence or a per-org writer.
• Changing the set of fields fed into computeEntryHash invalidates every existing chain. It is a breaking change requiring a new ADR and a re-anchoring procedure, not a refactor.
• The requirement names "project independent permission enable/disable/change". ADR-0030 removed that feature — FileLibProjectSettings is no longer read — so no code path can emit those events today. The three action values are reserved in the vocabulary; if the feature returns, it wires into the existing writer.