@wopr-network/platform-core 1.13.0 → 1.13.2

package/src/api/routes/admin-recovery.ts

@@ -0,0 +1,376 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import type { AuthEnv } from "../../auth/index.js";
+import type { RecoveryEvent } from "../../fleet/repository-types.js";
+import type { AdminAuditLogger } from "./admin-audit-helper.js";
+import { safeAuditLog } from "./admin-audit-helper.js";
+
+// ── Minimal interfaces for injectable deps ──
+
+export interface IRecoveryRepository {
+  listEvents(limit: number, status?: RecoveryEvent["status"]): Promise<RecoveryEvent[]>;
+}
+
+export interface IRecoveryOrchestrator {
+  getEventDetails(eventId: string): Promise<{ event: RecoveryEvent | undefined; items: unknown[] }>;
+  retryWaiting(eventId: string): Promise<unknown>;
+  triggerRecovery(nodeId: string, trigger: string): Promise<unknown>;
+}
+
+export interface INodeRepository {
+  list(): Promise<unknown[]>;
+  getById(nodeId: string): Promise<unknown | null>;
+  transition(nodeId: string, targetStatus: string, reason: string, actor: string): Promise<unknown>;
+}
+
+export interface INodeProvisioner {
+  provision(opts: { region?: string; size?: string; name?: string }): Promise<{
+    nodeId: string;
+    externalId?: string;
+    region?: string;
+    size?: string;
+    monthlyCostCents?: number;
+  }>;
+  destroy(nodeId: string): Promise<void>;
+  listRegions(): Promise<unknown[]>;
+  listSizes(): Promise<unknown[]>;
+}
+
+export interface INodeDrainer {
+  drain(nodeId: string): Promise<{ migrated: unknown[]; failed: unknown[] }>;
+}
+
+export interface IBotInstanceRepository {
+  listByNode(nodeId: string): Promise<unknown[]>;
+  getById(botId: string): Promise<{ nodeId?: string | null; tenantId?: string | null } | null>;
+}
+
+export interface ICommandBus {
+  send(nodeId: string, command: { type: string; payload: Record<string, unknown> }): Promise<{ data?: unknown }>;
+}
+
+export interface IMigrationOrchestrator {
+  migrate(
+    botId: string,
+    targetNodeId?: string,
+  ): Promise<{
+    success: boolean;
+    error?: string;
+    sourceNodeId?: string;
+    targetNodeId?: string;
+    downtimeMs?: number;
+  }>;
+}
+
+export type CapacityAlertChecker = (nodes: unknown[]) => unknown[];
+
+// ── Recovery routes ──
+
+export interface AdminRecoveryDeps {
+  recoveryRepo: () => IRecoveryRepository;
+  recoveryOrchestrator: () => IRecoveryOrchestrator;
+  auditLogger?: () => AdminAuditLogger;
+  logger?: { error(msg: string, meta?: Record<string, unknown>): void };
+}
+
+export function createAdminRecoveryRoutes(deps: AdminRecoveryDeps): Hono<AuthEnv> {
+  const routes = new Hono<AuthEnv>();
+
+  routes.get("/", async (c) => {
+    const rawLimit = Number.parseInt(c.req.query("limit") ?? "50", 10);
+    const limit = Number.isNaN(rawLimit) || rawLimit < 1 ? 50 : Math.min(rawLimit, 500);
+
+    const rawStatus = c.req.query("status");
+    const validStatuses: RecoveryEvent["status"][] = ["in_progress", "partial", "completed"];
+    const statusFilter =
+      rawStatus && (validStatuses as string[]).includes(rawStatus) ? (rawStatus as RecoveryEvent["status"]) : undefined;
+    const events = await deps.recoveryRepo().listEvents(limit, statusFilter);
+
+    return c.json({ success: true, events, count: events.length });
+  });
+
+  routes.get("/:eventId", async (c) => {
+    const eventId = c.req.param("eventId") as string;
+    const { event, items } = await deps.recoveryOrchestrator().getEventDetails(eventId);
+
+    if (!event) {
+      return c.json({ success: false, error: "Recovery event not found" }, 404);
+    }
+
+    return c.json({ success: true, event, items });
+  });
+
+  routes.post("/:eventId/retry", async (c) => {
+    const eventId = c.req.param("eventId") as string;
+
+    try {
+      const report = await deps.recoveryOrchestrator().retryWaiting(eventId);
+      return c.json({ success: true, report });
+    } catch (err) {
+      deps.logger?.error("Failed to retry waiting tenants", { eventId, err });
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  return routes;
+}
+
+// ── Node management routes ──
+
+export interface AdminNodeDeps {
+  nodeRepo: () => INodeRepository;
+  nodeProvisioner: () => INodeProvisioner;
+  nodeDrainer: () => INodeDrainer;
+  botInstanceRepo: () => IBotInstanceRepository;
+  recoveryOrchestrator: () => IRecoveryOrchestrator;
+  migrationOrchestrator: () => IMigrationOrchestrator;
+  commandBus: () => ICommandBus;
+  capacityAlertChecker: CapacityAlertChecker;
+  auditLogger?: () => AdminAuditLogger;
+  logger?: { error(msg: string, meta?: Record<string, unknown>): void };
+}
+
+export function createAdminNodeRoutes(deps: AdminNodeDeps): Hono<AuthEnv> {
+  const routes = new Hono<AuthEnv>();
+
+  routes.get("/", async (c) => {
+    const nodes = await deps.nodeRepo().list();
+    const alerts = deps.capacityAlertChecker(nodes);
+    return c.json({ success: true, nodes, count: nodes.length, alerts });
+  });
+
+  routes.post("/", async (c) => {
+    try {
+      const body = await c.req.json();
+      const parsed = z
+        .object({
+          region: z.string().min(1).max(20).optional(),
+          size: z.string().min(1).max(50).optional(),
+          name: z
+            .string()
+            .min(1)
+            .max(63)
+            .regex(/^[a-zA-Z0-9][a-zA-Z0-9-]*$/)
+            .optional(),
+        })
+        .parse(body);
+
+      const result = await deps.nodeProvisioner().provision(parsed);
+
+      safeAuditLog(deps.auditLogger, {
+        adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+        action: "node.provision",
+        category: "config",
+        details: {
+          nodeId: result.nodeId,
+          externalId: result.externalId,
+          region: result.region,
+          size: result.size,
+          monthlyCostCents: result.monthlyCostCents,
+        },
+      });
+
+      return c.json({ success: true, node: result }, 201);
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("DO_API_TOKEN")) {
+        return c.json(
+          { success: false, error: "Node provisioning not configured. Set DO_API_TOKEN environment variable." },
+          503,
+        );
+      }
+      deps.logger?.error("Node provisioning failed", { err });
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.post("/migrate", async (c) => {
+    try {
+      const body = await c.req.json();
+      const parsed = z
+        .object({
+          botId: z.string().min(1),
+          targetNodeId: z.string().min(1),
+        })
+        .parse(body);
+
+      const bot = await deps.botInstanceRepo().getById(parsed.botId);
+      if (!bot) {
+        return c.json({ success: false, error: "Bot not found" }, 404);
+      }
+      if (!bot.nodeId) {
+        return c.json({ success: false, error: "Bot has no node assignment" }, 400);
+      }
+      if (bot.nodeId === parsed.targetNodeId) {
+        return c.json({ success: false, error: "Source and target nodes are the same" }, 400);
+      }
+
+      const result = await deps.migrationOrchestrator().migrate(parsed.botId, parsed.targetNodeId);
+
+      if (!result.success) {
+        return c.json({ success: false, error: result.error }, 500);
+      }
+
+      safeAuditLog(deps.auditLogger, {
+        adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+        action: "node.migrate",
+        category: "config",
+        details: {
+          botId: parsed.botId,
+          tenantId: bot.tenantId,
+          sourceNode: result.sourceNodeId,
+          targetNode: result.targetNodeId,
+          downtimeMs: result.downtimeMs,
+        },
+      });
+
+      return c.json({
+        success: true,
+        migration: {
+          botId: parsed.botId,
+          from: result.sourceNodeId,
+          to: result.targetNodeId,
+          downtimeMs: result.downtimeMs,
+        },
+      });
+    } catch (err) {
+      deps.logger?.error("Manual migration failed", { err });
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.get("/regions", async (c) => {
+    try {
+      const regions = await deps.nodeProvisioner().listRegions();
+      return c.json({ success: true, regions });
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("DO_API_TOKEN")) {
+        return c.json(
+          { success: false, error: "Node provisioning not configured. Set DO_API_TOKEN environment variable." },
+          503,
+        );
+      }
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.get("/sizes", async (c) => {
+    try {
+      const sizes = await deps.nodeProvisioner().listSizes();
+      return c.json({ success: true, sizes });
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("DO_API_TOKEN")) {
+        return c.json(
+          { success: false, error: "Node provisioning not configured. Set DO_API_TOKEN environment variable." },
+          503,
+        );
+      }
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.get("/:nodeId", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+    const node = await deps.nodeRepo().getById(nodeId);
+    if (!node) {
+      return c.json({ success: false, error: "Node not found" }, 404);
+    }
+
+    const tenants = await deps.botInstanceRepo().listByNode(nodeId);
+    return c.json({ success: true, node, tenants, tenantCount: tenants.length });
+  });
+
+  routes.delete("/:nodeId", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+
+    try {
+      const node = await deps.nodeRepo().getById(nodeId);
+      if (!node) {
+        return c.json({ success: false, error: "Node not found" }, 404);
+      }
+      await deps.nodeProvisioner().destroy(nodeId);
+
+      safeAuditLog(deps.auditLogger, {
+        adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+        action: "node.destroy",
+        category: "config",
+        details: { nodeId },
+      });
+
+      return c.json({ success: true });
+    } catch (err) {
+      deps.logger?.error("Node destruction failed", { nodeId, err });
+      const status = err instanceof Error && err.message.includes("must be drained") ? 409 : 500;
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, status);
+    }
+  });
+
+  routes.get("/:nodeId/tenants", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+    const tenants = await deps.botInstanceRepo().listByNode(nodeId);
+    return c.json({ success: true, tenants, count: tenants.length });
+  });
+
+  routes.get("/:nodeId/stats", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+
+    try {
+      const result = await deps.commandBus().send(nodeId, { type: "stats.get", payload: {} });
+      return c.json({ success: true, stats: result.data });
+    } catch (err) {
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.post("/:nodeId/drain", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+
+    try {
+      const result = await deps.nodeDrainer().drain(nodeId);
+
+      safeAuditLog(deps.auditLogger, {
+        adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+        action: "node.drain",
+        category: "config",
+        details: { nodeId, migrated: result.migrated.length, failed: result.failed.length },
+      });
+
+      return c.json({ success: result.failed.length === 0, result });
+    } catch (err) {
+      deps.logger?.error("Drain failed", { nodeId, err });
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.post("/:nodeId/cancel-drain", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+
+    try {
+      await deps.nodeRepo().transition(nodeId, "active", "drain_cancelled", "admin");
+
+      safeAuditLog(deps.auditLogger, {
+        adminUser: (c.get("user") as { id?: string } | undefined)?.id ?? "unknown",
+        action: "node.cancelDrain",
+        category: "config",
+        details: { nodeId },
+      });
+
+      return c.json({ success: true, message: `Drain cancelled for node ${nodeId}` });
+    } catch (err) {
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  routes.post("/:nodeId/recover", async (c) => {
+    const nodeId = c.req.param("nodeId") as string;
+
+    try {
+      const report = await deps.recoveryOrchestrator().triggerRecovery(nodeId, "manual");
+      return c.json({ success: true, report });
+    } catch (err) {
+      deps.logger?.error("Manual recovery failed", { nodeId, err });
+      return c.json({ success: false, error: err instanceof Error ? err.message : "Unknown error" }, 500);
+    }
+  });
+
+  return routes;
+}

package/src/api/routes/admin-roles.ts

@@ -0,0 +1,205 @@
+import type { Context, Next } from "hono";
+import { Hono } from "hono";
+import { isValidRole, RoleStore } from "../../admin/role-store.js";
+import type { AuthEnv } from "../../auth/index.js";
+import type { AdminAuditLogger } from "./admin-audit-helper.js";
+import { safeAuditLog } from "./admin-audit-helper.js";
+
+// ── Role middleware (generic, no WOPR deps) ──
+
+function resolveRoleStore(storeOrFactory: RoleStore | (() => RoleStore)): RoleStore {
+  return typeof storeOrFactory === "function" ? storeOrFactory() : storeOrFactory;
+}
+
+export function requirePlatformAdmin(storeOrFactory: RoleStore | (() => RoleStore)) {
+  return async (c: Context<AuthEnv>, next: Next) => {
+    let user: { id: string; roles: string[] } | undefined;
+    try {
+      user = c.get("user");
+    } catch {
+      return c.json({ error: "Authentication required" }, 401);
+    }
+
+    if (!user) {
+      return c.json({ error: "Authentication required" }, 401);
+    }
+
+    if (!user.roles.includes("admin") && !(await resolveRoleStore(storeOrFactory).isPlatformAdmin(user.id))) {
+      return c.json({ error: "Platform admin access required" }, 403);
+    }
+
+    return next();
+  };
+}
+
+export function requireTenantAdmin(storeOrFactory: RoleStore | (() => RoleStore), tenantIdKey = "tenantId") {
+  return async (c: Context<AuthEnv>, next: Next) => {
+    let user: { id: string; roles: string[] } | undefined;
+    try {
+      user = c.get("user");
+    } catch {
+      return c.json({ error: "Authentication required" }, 401);
+    }
+
+    if (!user) {
+      return c.json({ error: "Authentication required" }, 401);
+    }
+
+    if (user.roles.includes("admin") || (await resolveRoleStore(storeOrFactory).isPlatformAdmin(user.id))) {
+      return next();
+    }
+
+    const tenantId = c.req.param(tenantIdKey);
+    if (!tenantId) {
+      return c.json({ error: "Tenant ID required" }, 400);
+    }
+
+    const role = await resolveRoleStore(storeOrFactory).getRole(user.id, tenantId);
+    if (role !== "tenant_admin") {
+      return c.json({ error: "Tenant admin access required" }, 403);
+    }
+
+    return next();
+  };
+}
+
+// ── Route factories ──
+
+/**
+ * Create admin role management API routes.
+ * Takes a RoleStore factory and optional audit logger.
+ */
+export function createAdminRolesRoutes(
+  storeFactory: () => RoleStore,
+  auditLogger?: () => AdminAuditLogger,
+): Hono<AuthEnv> {
+  const routes = new Hono<AuthEnv>();
+
+  routes.get("/:tenantId", requireTenantAdmin(storeFactory), async (c) => {
+    const tenantId = c.req.param("tenantId") as string;
+    const roles = await storeFactory().listByTenant(tenantId);
+    return c.json({ roles });
+  });
+
+  routes.put("/:tenantId/:userId", requireTenantAdmin(storeFactory), async (c) => {
+    const tenantId = c.req.param("tenantId") as string;
+    const userId = c.req.param("userId") as string;
+    const body = await c.req.json<{ role: string }>().catch(() => null);
+
+    if (!body?.role || !isValidRole(body.role)) {
+      return c.json({ error: "Invalid role. Must be: platform_admin, tenant_admin, or user" }, 400);
+    }
+
+    if (body.role === "platform_admin") {
+      return c.json({ error: "platform_admin can only be granted via platform admin routes" }, 400);
+    }
+
+    const currentUser = c.get("user");
+
+    await storeFactory().setRole(userId, tenantId, body.role, currentUser.id);
+
+    safeAuditLog(auditLogger, {
+      adminUser: currentUser.id ?? "unknown",
+      action: "role.set",
+      category: "roles",
+      targetTenant: tenantId,
+      targetUser: userId,
+      details: { role: body.role },
+      outcome: "success",
+    });
+
+    return c.json({ ok: true });
+  });
+
+  routes.delete("/:tenantId/:userId", requireTenantAdmin(storeFactory), async (c) => {
+    const tenantId = c.req.param("tenantId") as string;
+    const userId = c.req.param("userId") as string;
+
+    const removed = await storeFactory().removeRole(userId, tenantId);
+    if (!removed) {
+      return c.json({ error: "Role not found" }, 404);
+    }
+
+    const currentUser = c.get("user");
+    safeAuditLog(auditLogger, {
+      adminUser: currentUser?.id ?? "unknown",
+      action: "role.remove",
+      category: "roles",
+      targetTenant: tenantId,
+      targetUser: userId,
+      details: {},
+      outcome: "success",
+    });
+
+    return c.json({ ok: true });
+  });
+
+  return routes;
+}
+
+/**
+ * Create platform admin management routes.
+ * Takes a RoleStore factory and optional audit logger.
+ */
+export function createPlatformAdminRoutes(
+  storeFactory: () => RoleStore,
+  auditLogger?: () => AdminAuditLogger,
+): Hono<AuthEnv> {
+  const routes = new Hono<AuthEnv>();
+
+  routes.use("*", requirePlatformAdmin(storeFactory));
+
+  routes.get("/", async (c) => {
+    const admins = await storeFactory().listPlatformAdmins();
+    return c.json({ admins });
+  });
+
+  routes.post("/", async (c) => {
+    const body = await c.req.json<{ userId: string }>().catch(() => null);
+
+    if (!body?.userId) {
+      return c.json({ error: "userId is required" }, 400);
+    }
+
+    const currentUser = c.get("user");
+    await storeFactory().setRole(body.userId, RoleStore.PLATFORM_TENANT, "platform_admin", currentUser.id);
+
+    safeAuditLog(auditLogger, {
+      adminUser: currentUser.id ?? "unknown",
+      action: "platform_admin.add",
+      category: "roles",
+      targetUser: body.userId,
+      details: {},
+      outcome: "success",
+    });
+
+    return c.json({ ok: true });
+  });
+
+  routes.delete("/:userId", async (c) => {
+    const userId = c.req.param("userId") as string;
+
+    if ((await storeFactory().countPlatformAdmins()) <= 1 && (await storeFactory().isPlatformAdmin(userId))) {
+      return c.json({ error: "Cannot remove the last platform admin" }, 409);
+    }
+
+    const removed = await storeFactory().removeRole(userId, RoleStore.PLATFORM_TENANT);
+    if (!removed) {
+      return c.json({ error: "Platform admin not found" }, 404);
+    }
+
+    const currentUser = c.get("user");
+    safeAuditLog(auditLogger, {
+      adminUser: currentUser?.id ?? "unknown",
+      action: "platform_admin.remove",
+      category: "roles",
+      targetUser: userId,
+      details: {},
+      outcome: "success",
+    });
+
+    return c.json({ ok: true });
+  });
+
+  return routes;
+}

package/src/api/routes/audit.ts

@@ -0,0 +1,106 @@
+import type { Context } from "hono";
+import { Hono } from "hono";
+import { DrizzleAuditLogRepository, type IAuditLogRepository } from "../../audit/audit-log-repository.js";
+import { countAuditLog, queryAuditLog } from "../../audit/query.js";
+import { purgeExpiredEntriesForUser } from "../../audit/retention.js";
+import type { AuditEnv } from "../../audit/types.js";
+import type { DrizzleDb } from "../../db/index.js";
+
+async function handleUserAudit(c: Context<AuditEnv>, repo: IAuditLogRepository) {
+  const user = c.get("user");
+  if (!user) return c.json({ error: "Unauthorized" }, 401);
+
+  void purgeExpiredEntriesForUser(repo, user.id).catch(() => {
+    /* purge is best-effort — must not break request */
+  });
+
+  const sinceRaw = c.req.query("since") ? Number(c.req.query("since")) : undefined;
+  const untilRaw = c.req.query("until") ? Number(c.req.query("until")) : undefined;
+  const limitRaw = c.req.query("limit") ? Number(c.req.query("limit")) : undefined;
+  const offsetRaw = c.req.query("offset") ? Number(c.req.query("offset")) : undefined;
+
+  const filters = {
+    userId: user.id,
+    action: c.req.query("action") ?? undefined,
+    resourceType: c.req.query("resourceType") ?? undefined,
+    resourceId: c.req.query("resourceId") ?? undefined,
+    since: sinceRaw !== undefined && Number.isFinite(sinceRaw) ? sinceRaw : undefined,
+    until: untilRaw !== undefined && Number.isFinite(untilRaw) ? untilRaw : undefined,
+    limit: limitRaw !== undefined && Number.isFinite(limitRaw) ? limitRaw : undefined,
+    offset: offsetRaw !== undefined && Number.isFinite(offsetRaw) ? offsetRaw : undefined,
+  };
+
+  try {
+    const [entries, total] = await Promise.all([queryAuditLog(repo, filters), countAuditLog(repo, filters)]);
+    return c.json({ entries, total });
+  } catch {
+    return c.json({ error: "Internal server error" }, 500);
+  }
+}
+
+async function handleAdminAudit(c: Context<AuditEnv>, repo: IAuditLogRepository) {
+  const user = c.get("user");
+  if (!user?.isAdmin) return c.json({ error: "Forbidden" }, 403);
+
+  const sinceRaw = c.req.query("since") ? Number(c.req.query("since")) : undefined;
+  const untilRaw = c.req.query("until") ? Number(c.req.query("until")) : undefined;
+  const limitRaw = c.req.query("limit") ? Number(c.req.query("limit")) : undefined;
+  const offsetRaw = c.req.query("offset") ? Number(c.req.query("offset")) : undefined;
+
+  const filters = {
+    userId: c.req.query("userId") ?? undefined,
+    action: c.req.query("action") ?? undefined,
+    resourceType: c.req.query("resourceType") ?? undefined,
+    resourceId: c.req.query("resourceId") ?? undefined,
+    since: sinceRaw !== undefined && Number.isFinite(sinceRaw) ? sinceRaw : undefined,
+    until: untilRaw !== undefined && Number.isFinite(untilRaw) ? untilRaw : undefined,
+    limit: limitRaw !== undefined && Number.isFinite(limitRaw) ? limitRaw : undefined,
+    offset: offsetRaw !== undefined && Number.isFinite(offsetRaw) ? offsetRaw : undefined,
+  };
+
+  try {
+    const [entries, total] = await Promise.all([queryAuditLog(repo, filters), countAuditLog(repo, filters)]);
+    return c.json({ entries, total });
+  } catch {
+    return c.json({ error: "Internal server error" }, 500);
+  }
+}
+
+type DbOrFactory = DrizzleDb | (() => DrizzleDb);
+
+function resolveRepo(dbOrFactory: DbOrFactory): IAuditLogRepository {
+  const db = typeof dbOrFactory === "function" ? dbOrFactory() : dbOrFactory;
+  return new DrizzleAuditLogRepository(db);
+}
+
+/**
+ * Create audit log API routes.
+ *
+ * Pass a `DrizzleDb` directly or a `() => DrizzleDb` factory for lazy init.
+ * Expects `c.get("user")` to provide `{ id: string }`.
+ */
+export function createAuditRoutes(db: DbOrFactory): Hono<AuditEnv> {
+  let repo: IAuditLogRepository | null = typeof db === "function" ? null : resolveRepo(db);
+  const routes = new Hono<AuditEnv>();
+  routes.get("/", (c) => {
+    if (!repo) repo = resolveRepo(db);
+    return handleUserAudit(c, repo);
+  });
+  return routes;
+}
+
+/**
+ * Create admin audit log API routes.
+ *
+ * Pass a `DrizzleDb` directly or a `() => DrizzleDb` factory for lazy init.
+ * Expects `c.get("user")` to provide `{ id: string, isAdmin: boolean }`.
+ */
+export function createAdminAuditRoutes(db: DbOrFactory): Hono<AuditEnv> {
+  let repo: IAuditLogRepository | null = typeof db === "function" ? null : resolveRepo(db);
+  const routes = new Hono<AuditEnv>();
+  routes.get("/", (c) => {
+    if (!repo) repo = resolveRepo(db);
+    return handleAdminAudit(c, repo);
+  });
+  return routes;
+}