feat(audit): add tamper-evident evlog audit trail (#154)

### 🔗 Linked issue

<!-- No open issue — this is a self-contained infrastructure feature -->

### 🧭 Context

WolfStar.rocks needed a tamper-evident audit trail for security-relevant
actions. Without it, there was no durable record of who changed guild
settings, when sessions were cleared, or when OAuth CSRF verification
failed. This PR introduces the full audit pipeline powered by `evlog`'s
`log.audit()` API, persisted to PostgreSQL with a SHA-256 hash chain.

### 📚 Description

**Infrastructure (new files)**

- `shared/audit/actions.ts` — 6 typed action creators
(`guildSettingsUpdate`, `guildSettingsAccessDenied`, `userLogin`,
`userLogout`, `sessionRefresh`, `oauthStateInvalid`) plus the
`AuditActionName` union type
- `shared/audit/envelope.ts` — `canonicalize()` (deterministic
sorted-key JSON) and `hashEnvelope()` (SHA-256 hex) for the hash chain
- `server/utils/audit/postgres-drain.ts` — audit drain: serializable
transaction, upserts `AuditChainHead`, hashes each envelope against the
previous hash, swallows `P2002` unique constraint violations, retries
`P2034` serialization failures up to 5× with exponential backoff
- `server/utils/audit/actor-bridge.ts` — resolves the actor from the
`evlog` enrichment context
- `server/plugins/00.evlog-init.ts` — initialises evlog with redaction
config on boot

**Instrumentation (modified files)**

- `server/api/guilds/[guild]/settings.patch.ts` — wraps `canManage()` in
try/catch to emit `guildSettingsAccessDenied` on denial; captures
before/after snapshot and emits `guildSettingsUpdate` with `auditDiff`
on success
- `server/api/auth/discord.get.ts` — emits `userLogin` in the
`onSuccess` callback
- `server/api/auth/refresh.get.ts` — emits `userLogout` when tokens are
missing; emits `sessionRefresh` success or failure after the token
exchange
- `server/api/auth/verify-state.get.ts` — emits `oauthStateInvalid` with
the specific `reason` code (`missing-fields`, `decode-failed`,
`nonce-mismatch`, `expired`, `bad-hmac`) before throwing 400

**Tests**

- `test/unit/audit/envelope.spec.ts` — 8 tests covering `canonicalize`
stability and `hashEnvelope` correctness
- `test/unit/audit/actions.spec.ts` — 8 tests covering all 6 action
creators
- `test/unit/audit/postgres-drain.spec.ts` — 6 tests covering
early-return, Prisma call, PII exclusion, hash correctness, P2002
swallow, and P2034 retry exhaustion
- `test/unit/server/utils/oauth-state.test.ts` — updated 17 tests to
assert on `result.valid` and `result.reason` after the typed result
refactor

**Documentation**

- `AGENTS.md` — added Audit Logging section with action registry table
and instrumentation pattern
- `README.md` — added Audit Trail feature bullet

All 383 unit tests pass. Zero new type errors in our files. `pnpm
lint:fix` clean.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: lorypelli <87276663+lorypelli@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: CodeRabbit <noreply@coderabbit.ai>

Author: 7 people

.claude/skills/evlog-skilld/SKILL.md

@@ -1,12 +1,50 @@
 ---
 name: evlog-skilld
-description: "Wide event logging library with structured error handling. Inspired by LoggingSucks. ALWAYS use when writing code importing \"evlog\". Consult for debugging, best practices, or modifying evlog."
+description: "ALWAYS use when writing code importing \"evlog\". Consult for debugging, best practices, or modifying evlog."
 metadata:
-  version: 2.13.0
-  generated_at: 2026-04-23
+  version: 2.14.0
+  generated_by: Anthropic · claude-haiku-4-5
+  generated_at: 2026-04-26
 ---
 
-# HugoRCD/evlog `evlog@2.13.0`
-**Tags:** reserved: 0.0.0-reserved, latest: 2.13.0
+# HugoRCD/evlog `evlog@2.14.0`
+**Tags:** reserved: 0.0.0-reserved, latest: 2.14.0
 
-**References:** [Docs](./references/docs/_INDEX.md) • [Issues](./references/issues/_INDEX.md) • [Releases](./references/releases/_INDEX.md)
+**References:** [package.json](./.skilld/pkg/package.json) • [README](./.skilld/pkg/README.md) • [Docs](./.skilld/docs/_INDEX.md)
+
+## Search
+
+Use `npx -y skilld search "query" -p evlog` instead of grepping `.skilld/` directories. Run `npx -y skilld search --guide -p evlog` for full syntax, filters, and operators.
+
+<!-- skilld:api-changes -->
+## Summary
+
+I have successfully generated the **API Changes** section for evlog v2.14.0 and written it to `/home/jailuser/git/.claude/skills/evlog-skilld/.skilld/_API_CHANGES.md`.
+
+### Key Findings from evlog v2.14.0:
+
+The file contains **12 detailed API change items** covering:
+
+1. **NEW APIs for AI Integration**: `createAILogger()` and `createEvlogIntegration()` for Vercel AI SDK integration
+2. **NEW APIs for Authentication**: `createAuthMiddleware()` and `identifyUser()` from `evlog/better-auth`
+3. **NEW Production Features**: `createDrainPipeline()` for batching, retry, and buffer management
+4. **NEW Background Work Pattern**: `log.fork(label, fn)` for intentional async operations with correlation
+5. **NEW Audit Logging System**: Complete audit API with `audit()`, `log.audit()`, `withAudit()`, `defineAuditAction()`, `auditDiff()`, etc.
+6. **NEW Auto-Redaction**: `redact` config option with PII scrubbing in production
+7. **BREAKING Change**: Logger sealing after `log.emit()` to prevent silent data loss
+8. **NEW Client Logging**: Browser logging via `evlog/http` with identity sync
+9. **NEW Configuration Option**: `minLevel` for global log level threshold
+10. **NEW AI Telemetry**: `createEvlogIntegration()` for tool timing and wall time
+11. **NEW Metadata API**: `ai.onUpdate(callback)` for streaming progress and billing
+12. **NEW Framework Matrix**: Detailed support matrix for `log.fork()` across frameworks
+
+All source links are verified to exist in the documentation with proper anchor references (e.g., `#quick-start`, `#after-emit-sealing-and-background-work`).
+
+The output follows the required format with:
+- NEW/BREAKING/DEPRECATED labels
+- Clear descriptions of what changed and why
+- Verified source links to local documentation
+- Compact "Also changed" line for additional related items
+- No emoji, plain text markers only
+- Under 144 lines total
+<!-- /skilld:api-changes -->

.claude/skills/skilld-lock.yaml

@@ -48,11 +48,11 @@ skills:
     generator: skilld
   evlog-skilld:
     packageName: evlog
-    version: 2.13.0
-    packages: "evlog@2.13.0"
+    version: 2.14.0
+    packages: "evlog@2.14.0"
     repo: HugoRCD/evlog
     source: "https://evlog.dev/llms.txt"
-    syncedAt: 2026-04-23
+    syncedAt: 2026-04-26
     generator: skilld
   vitest-skilld:
     packageName: vitest

.env.example

@@ -77,3 +77,11 @@ SENTRY_DSN=
 # Environment variables declared in this file are automatically made available to Prisma.
 # See the documentation for more detail: https://pris.ly/d/prisma-schema#accessing-environment-variables-from-the-schema
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/wolfstar?schema=public"
+
+# ===================================
+# Audit log (dev only)
+# ===================================
+# No configuration required. When NODE_ENV=development, audit events are written
+# to .audit/ via evlog/signed + FS drain (hash-chain, local inspection only).
+# Run `pnpm audit:verify` to validate chain integrity offline.
+# In production, audit events go to the AuditEvent Postgres table instead.

.gitignore

@@ -33,6 +33,9 @@ deno.lock
 # Prisma generated files
 server/database/generated/
 
+# TypeScript build artifacts in server/database (not the TypeScript sources)
+server/database/**/*.js
+
 # Testing
 test-results
 
@@ -43,6 +46,9 @@ coverage/
 playwright-report/
 test-results/
 
+# Audit log (dev-only FS drain, never commit)
+.audit/
+
 # Benchmarks
 .codspeed
 

README.md

@@ -75,6 +75,10 @@ multi-purpose Discord bot for moderation and community management.
 - **Responsive Design**: Works seamlessly on desktop, tablet, and mobile
   devices.
 - **OAuth Integration**: Secure Discord authentication and authorization.
+- **Audit Trail**: All security-relevant actions (guild settings changes,
+  logins, token refreshes, and OAuth CSRF denials) are captured via a
+  tamper-evident audit log. Each event is persisted to PostgreSQL with a SHA-256
+  hash chain, making the audit trail verifiable and tamper-evident.
 - **Multi-language Support**: Support for multiple languages (coming soon).
 - **Dashboard Analytics**: View server statistics and bot usage metrics.
 

knip.ts

@@ -72,7 +72,7 @@ const config: KnipConfig = {
 				/** Used in nuxt.config.ts for postcss */
 				"postcss-nested",
 			],
-			ignoreUnresolved: ["#server/database/generated/client", "#build/auth.config"],
+			ignoreUnresolved: ["#build/auth.config"],
 			ignoreFiles: [
 				"**/*.unused.*",
 				"shared/utils/index.ts" /* Used for type exports only, not imported directly */,

package.json

@@ -85,7 +85,7 @@
 		"@vueuse/nuxt": "^14.2.1",
 		"@vueuse/router": "^14.2.1",
 		"dotenv": "^17.3.1",
-		"evlog": "^2.10.0",
+		"evlog": "^2.14.0",
 		"fuse.js": "^7.1.0",
 		"nuxt": "^4.4.2",
 		"nuxt-auth-utils": "^0.5.29",
@@ -135,6 +135,7 @@
 		"skilld": "^1.6.2",
 		"tailwindcss": "^4.2.1",
 		"taze": "^19.10.0",
+		"tsx": "^4.21.0",
 		"typescript": "~5.9.3",
 		"vitest": "npm:@voidzero-dev/vite-plus-test@0.1.19",
 		"vue-tsc": "^3.2.5"

pnpm-lock.yaml

@@ -2,13 +2,14 @@ import type { APIUser, RESTPostOAuth2AccessTokenResult } from "discord-api-types
 import type { H3Event } from "h3";
 import type { NuxtError } from "nuxt/app";
 import { createOAuthState } from "#server/utils/oauth-state";
+import { userLogin } from "#shared/audit/actions";
 import { isSafeRedirectPath } from "#shared/utils/redirect";
-import { createError, useLogger } from "evlog";
+import { createError, useLogger, withAuditMethods } from "evlog";
 
 export default defineWrappedResponseHandler(
 	async (event) => {
 		const query = getQuery(event);
-		const log = useLogger(event);
+		const log = withAuditMethods(useLogger(event));
 
 		const authorizationParams: Record<string, string> = { prompt: "none" };
 
@@ -85,6 +86,12 @@ export default defineWrappedResponseHandler(
 				});
 
 				log.set({ user: { id: user.id, username: user.username } });
+				log.audit(
+					userLogin({
+						actor: { type: "user", id: user.id, displayName: user.username },
+						outcome: "success",
+					}),
+				);
 				log.info("User authenticated with Discord");
 			},
 		});

server/api/auth/discord.get.ts

@@ -1,5 +1,6 @@
 import type { UserSession } from "#auth-utils";
-import { useLogger } from "evlog";
+import { sessionRefresh, userLogout } from "#shared/audit/actions";
+import { useLogger, withAuditMethods } from "evlog";
 
 async function refreshTokens(refreshToken: string) {
 	const api = useApi();
@@ -25,7 +26,7 @@ function isExpired(expires_in: number | undefined, loggedInAt: number): boolean
 
 export default defineWrappedResponseHandler(
 	async (event) => {
-		const log = useLogger(event);
+		const log = withAuditMethods(useLogger(event));
 		const session: UserSession = await getUserSession(event);
 		if (!session?.secure?.tokens) {
 			return;
@@ -43,6 +44,16 @@ export default defineWrappedResponseHandler(
 		}
 
 		if (!access_token || !refresh_token) {
+			const actor = userId
+				? { type: "user" as const, id: userId }
+				: { type: "system" as const, id: "session-cleanup" };
+			log.audit(
+				userLogout({
+					actor,
+					outcome: "denied",
+					reason: "Session cleared due to missing tokens",
+				}),
+			);
 			await clearUserSession(event);
 			return;
 		}
@@ -58,9 +69,32 @@ export default defineWrappedResponseHandler(
 				},
 			});
 
+			const successActor = userId
+				? { type: "user" as const, id: userId }
+				: { type: "system" as const, id: "session-cleanup" };
+			log.audit(
+				sessionRefresh({
+					actor: successActor,
+					outcome: "success",
+				}),
+			);
 			log.info("Tokens refreshed successfully");
 		} catch (error) {
+			const reason =
+				error instanceof Error && error.message.includes("invalid_grant")
+					? "Refresh token revoked or expired"
+					: "Token refresh failed";
 			log.error("Failed to refresh tokens", { error });
+			const failureActor = userId
+				? { type: "user" as const, id: userId }
+				: { type: "system" as const, id: "session-cleanup" };
+			log.audit(
+				sessionRefresh({
+					actor: failureActor,
+					outcome: "failure",
+					reason,
+				}),
+			);
 			await clearUserSession(event);
 		}
 	},