suaveplan/openspec/changes/enterprise-api-plugin-audit/tasks.md

Tasks: enterprise-api-plugin-audit

Change ID: enterprise-api-plugin-audit Package: @suaveplan/api-plugin-audit Target path: api/data/api-plugin-audit Prerequisite packages on Verdaccio: @suaveplan/api, @suaveplan/api-shared, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/audit-logging, @suaveplan/events, @suaveplan/rate-limiter, @suaveplan/error

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold + types + errors + events

• Create directory; package.json v0.0.0; standard tooling.
• Types: AuditEntry, AuditLogInput, AuditQuery, AuditPluginConfig (Zod; includes retentionDays).
• Errors: 3-code union + registration. Test + doc.
• Events: AuditPluginEventMap (audit:entry:created).

---

2. SurrealQL

• audit_entry.surql — append-only (no UPDATE/DELETE DEFINE PERMISSIONS); tenantId + userId + timestamp indexes.

---

3. AuditPluginService

• log(entry) — validate with Zod; persist to SurrealDB; emit audit:entry:created; OTel counter audit.entries_total.
• query(params) — filter by tenantId, userId, action, resource, dateRange; paginated.
• middleware(action) — Hono middleware: after response, calls log with request metadata (method, path, userId from context, IP, UA).
• Retention: purgeExpired() — removes entries older than retentionDays (scheduled in onInit).
• .test.ts (log + query + middleware + purge) + .md.

---

4. Routes

• GET /audit — requireAuth + requireRole("ADMIN"); paginated query.
• GET /audit/:id — requireAuth + requireRole("ADMIN").
• Route .test.ts + .md.

---

5. Plugin factory + integration tests + publish

• createAuditPlugin: definePlugin, dependencies: ["database", "auth"], migrationsPath: "./surql".
• onInit: register AuditPluginService; start retention purge interval (disposer captured for onClose).
• onClose: clear purge interval.
• Integration: middleware logs request → query returns entry → retention purge removes old records (real SurrealDB).
• bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-audit — green; 100% coverage.
• bun scripts/publish.ts --package @suaveplan/api-plugin-audit.
• Archive → openspec/archive/2026-04-24-enterprise-api-plugin-audit/.