feat: production-grade RBAC with editor role, custom roles, API key scoping, and audit log (#89)

* feat(rbac): add editor role, 3 new permissions, ownership helper

* feat(rbac): add audit_log table, apiKeys.permissions column, editor role to schema

* feat(rbac): wire requirePermission into all routes, add editor role support

* refactor(rbac): replace ad-hoc role checks with permission-based ownership

* feat(rbac): add audit log DB writes + query endpoint

Dual-write audit events to stdout (existing) and SQLite audit_log table.
Add GET /api/v1/audit-log with pagination, action filter, and date range
filtering, gated behind audit:read permission.

* feat(rbac): add API key permission scoping with ceiling enforcement

* feat(rbac): add escalation prevention and last-admin protection

* feat(rbac): add editor role to UI, API key permission scoping in settings

* test(rbac): add full permission matrix integration test

* test(rbac): add editor role E2E tests

* feat(rbac): add custom roles with CRUD API and DB-backed permission lookup

* feat(rbac): add API key expiration

* feat(rbac): add roles management UI and API key expiration to settings

* feat(rbac): add audit log UI to settings

* fix: remove any cast in API key permission validation

* test(rbac): add unit tests for username validation rules

* test(rbac): add unit tests for effective permissions and ownership

* test(rbac): add comprehensive route permission matrix (all routes × all roles)

* test(rbac): add auth route edge case tests (login failures, session expiry, password side effects)

* test(rbac): add escalation prevention tests (register, update, self-demote, last-admin)

* test(rbac): add ownership enforcement tests (files, pipelines, editor access, cross-user isolation)

* test(rbac): add API key edge cases (name validation, delete behavior, key revocation)

* test(rbac): add audit log edge cases (all events, pagination clamping, structure)

* test(rbac): add custom roles edge case tests (validation, CRUD, functional permissions)

* test(rbac): add comprehensive E2E tests (roles UI, audit log, custom role, API key scoping)

tests/unit/api/audit-helpers.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Unit tests for audit event mapping and actor extraction logic.
+ *
+ * Since deriveTargetType is not exported from audit.ts, we reproduce the
+ * mapping logic here so we can verify every event type maps correctly.
+ * Actor ID and username extraction logic is tested via the same rules
+ * used in auditLog().
+ */
+
+import { describe, expect, it } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Reproduce the private deriveTargetType logic so we can test its mapping
+// ---------------------------------------------------------------------------
+type AuditEvent =
+  | "LOGIN_SUCCESS"
+  | "LOGIN_FAILED"
+  | "LOGOUT"
+  | "PASSWORD_CHANGED"
+  | "PASSWORD_RESET"
+  | "USER_CREATED"
+  | "USER_DELETED"
+  | "USER_UPDATED"
+  | "FILE_UPLOADED"
+  | "FILE_DELETED"
+  | "API_KEY_CREATED"
+  | "API_KEY_DELETED"
+  | "ROLE_CREATED"
+  | "ROLE_UPDATED"
+  | "ROLE_DELETED"
+  | "SETTINGS_UPDATED";
+
+function deriveTargetType(event: AuditEvent): string | null {
+  if (
+    event.startsWith("USER_") ||
+    event.startsWith("LOGIN") ||
+    event.startsWith("PASSWORD") ||
+    event === "LOGOUT"
+  )
+    return "user";
+  if (event.startsWith("API_KEY")) return "api_key";
+  if (event.startsWith("FILE")) return "file";
+  if (event.startsWith("ROLE")) return "role";
+  if (event === "SETTINGS_UPDATED") return "setting";
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Reproduce the actor extraction logic from auditLog()
+// ---------------------------------------------------------------------------
+function extractActorId(details: Record<string, unknown>): string | null {
+  return (details.userId as string) ?? (details.adminId as string) ?? null;
+}
+
+function extractActorUsername(details: Record<string, unknown>): string {
+  return (
+    (details.username as string) ??
+    (details.newUsername as string) ??
+    "system"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("audit helpers", () => {
+  describe("deriveTargetType", () => {
+    it.each<[AuditEvent, string]>([
+      ["LOGIN_SUCCESS", "user"],
+      ["LOGIN_FAILED", "user"],
+      ["LOGOUT", "user"],
+      ["PASSWORD_CHANGED", "user"],
+      ["PASSWORD_RESET", "user"],
+      ["USER_CREATED", "user"],
+      ["USER_DELETED", "user"],
+      ["USER_UPDATED", "user"],
+    ])("%s -> %s", (event, expected) => {
+      expect(deriveTargetType(event)).toBe(expected);
+    });
+
+    it.each<[AuditEvent, string]>([
+      ["FILE_UPLOADED", "file"],
+      ["FILE_DELETED", "file"],
+    ])("%s -> %s", (event, expected) => {
+      expect(deriveTargetType(event)).toBe(expected);
+    });
+
+    it.each<[AuditEvent, string]>([
+      ["API_KEY_CREATED", "api_key"],
+      ["API_KEY_DELETED", "api_key"],
+    ])("%s -> %s", (event, expected) => {
+      expect(deriveTargetType(event)).toBe(expected);
+    });
+
+    it.each<[AuditEvent, string]>([
+      ["ROLE_CREATED", "role"],
+      ["ROLE_UPDATED", "role"],
+      ["ROLE_DELETED", "role"],
+    ])("%s -> %s", (event, expected) => {
+      expect(deriveTargetType(event)).toBe(expected);
+    });
+
+    it("SETTINGS_UPDATED -> setting", () => {
+      expect(deriveTargetType("SETTINGS_UPDATED")).toBe("setting");
+    });
+  });
+
+  describe("extractActorId", () => {
+    it("returns userId when present", () => {
+      expect(extractActorId({ userId: "u-123" })).toBe("u-123");
+    });
+
+    it("falls back to adminId when userId is absent", () => {
+      expect(extractActorId({ adminId: "a-456" })).toBe("a-456");
+    });
+
+    it("prefers userId over adminId when both are present", () => {
+      expect(extractActorId({ userId: "u-123", adminId: "a-456" })).toBe(
+        "u-123",
+      );
+    });
+
+    it("returns null when neither userId nor adminId is present", () => {
+      expect(extractActorId({})).toBeNull();
+    });
+
+    it("returns null for an empty details object", () => {
+      expect(extractActorId({})).toBeNull();
+    });
+  });
+
+  describe("extractActorUsername", () => {
+    it("returns username when present", () => {
+      expect(extractActorUsername({ username: "alice" })).toBe("alice");
+    });
+
+    it("falls back to newUsername when username is absent", () => {
+      expect(extractActorUsername({ newUsername: "bob" })).toBe("bob");
+    });
+
+    it("prefers username over newUsername when both are present", () => {
+      expect(
+        extractActorUsername({ username: "alice", newUsername: "bob" }),
+      ).toBe("alice");
+    });
+
+    it('returns "system" when neither username nor newUsername is present', () => {
+      expect(extractActorUsername({})).toBe("system");
+    });
+
+    it('returns "system" for an empty details object', () => {
+      expect(extractActorUsername({})).toBe("system");
+    });
+  });
+});