@nebutra/audit 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,7 @@
 # @nebutra/audit
 
+Status: **WIP**
+
 > **Status: WIP** — Not yet integrated into any production app. Do not import until this notice is removed.
 
 Audit logging for compliance and security.

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Audit Logging System for Nebutra Services
+ *
+ * Records sensitive operations for:
+ * - Security compliance (SOC 2, ISO 27001)
+ * - Debugging
+ * - User activity tracking
+ * - Billing verification
+ *
+ * Exports:
+ *   - This module: legacy `audit()` API + Prisma storage adapter (stable for
+ *     internal callers; see `INTEGRATION_NOTES.md` for migration plan).
+ *   - `@nebutra/audit/schema`: Zod schemas + `defineAction` + `ACTIONS`
+ *   - `@nebutra/audit/middleware`: `auditLogger(req, ...)`, `withAudit(...)`
+ *   - `@nebutra/audit/providers`: `getAuditProvider()`, provider classes
+ */
+export { type AuditLoggerDefaults, type AuditLoggerLogInput, type AuditRequestContext, auditLogger, type BoundAuditLogger, extractRequestContext, type WithAuditOptions, withAudit, } from "./middleware";
+export { type AuditFactoryConfig, type AuditProvider, type AuditProviderType, ClickHouseAuditProvider, createAuditProvider, getAuditProvider, MemoryAuditProvider, PostgresAuditProvider, } from "./providers";
+export * from "./schema";
+export type AuditAction = "user.login" | "user.logout" | "user.signup" | "user.password_change" | "user.email_change" | "user.delete" | "org.create" | "org.update" | "org.delete" | "org.member_add" | "org.member_remove" | "org.role_change" | "billing.subscription_create" | "billing.subscription_update" | "billing.subscription_cancel" | "billing.payment_success" | "billing.payment_failed" | "api.key_create" | "api.key_revoke" | "data.export" | "data.delete" | "admin.impersonate" | "admin.settings_change" | "custom";
+/**
+ * Legacy audit event shape.
+ *
+ * Prefer the Zod-validated `AuditEvent` from `@nebutra/audit/schema` for new
+ * code. This interface is preserved for existing call sites and the legacy
+ * `audit()` helper. See `INTEGRATION_NOTES.md` for migration guidance.
+ */
+export interface LegacyAuditEvent {
+    id?: string;
+    action: AuditAction;
+    actorId: string;
+    actorType: "user" | "system" | "api_key" | "admin";
+    tenantId?: string;
+    targetType?: string;
+    targetId?: string;
+    metadata?: Record<string, unknown>;
+    ipAddress?: string;
+    userAgent?: string;
+    timestamp?: Date;
+    outcome: "success" | "failure" | "pending";
+    reason?: string;
+}
+export interface AuditStorage {
+    store: (event: LegacyAuditEvent) => Promise<void>;
+    query: (filter: LegacyAuditQueryFilter) => Promise<LegacyAuditEvent[]>;
+}
+interface PrismaAuditLogClient {
+    auditLog: {
+        create: (data: {
+            data: unknown;
+        }) => Promise<unknown>;
+        findMany: (args: unknown) => Promise<unknown[]>;
+    };
+}
+export interface LegacyAuditQueryFilter {
+    tenantId?: string;
+    actorId?: string;
+    action?: AuditAction;
+    targetType?: string;
+    targetId?: string;
+    startDate?: Date;
+    endDate?: Date;
+    limit?: number;
+    offset?: number;
+}
+/** @internal — exposed for tests so they can reset the legacy in-memory buffer. */
+export declare function __resetLegacyMemoryStorage(): void;
+export declare const inMemoryStorage: AuditStorage;
+export declare function createPrismaStorage(prisma: PrismaAuditLogClient): AuditStorage;
+export declare function setAuditStorage(newStorage: AuditStorage): void;
+export declare function audit(event: Omit<LegacyAuditEvent, "id" | "timestamp">): Promise<void>;
+export declare function queryAuditLogs(filter: LegacyAuditQueryFilter): Promise<LegacyAuditEvent[]>;
+export declare function auditUserLogin(userId: string, tenantId: string, success: boolean, ipAddress?: string, userAgent?: string): Promise<void>;
+export declare function auditUserLogout(userId: string, tenantId: string): Promise<void>;
+export declare function auditRoleChange(adminId: string, tenantId: string, targetUserId: string, oldRole: string, newRole: string): Promise<void>;
+export declare function auditBillingEvent(tenantId: string, action: "billing.subscription_create" | "billing.subscription_update" | "billing.subscription_cancel" | "billing.payment_success" | "billing.payment_failed", metadata: Record<string, unknown>): Promise<void>;
+export declare function auditApiKeyCreate(userId: string, tenantId: string, keyId: string, keyName: string): Promise<void>;
+export declare function auditDataExport(userId: string, tenantId: string, exportType: string, metadata?: Record<string, unknown>): Promise<void>;
+export declare function auditMiddleware(): (c: {
+    req: {
+        header: (name: string) => string | undefined;
+    };
+    set: (key: string, value: unknown) => void;
+}, next: () => Promise<void>) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,288 @@
+/**
+ * Audit Logging System for Nebutra Services
+ *
+ * Records sensitive operations for:
+ * - Security compliance (SOC 2, ISO 27001)
+ * - Debugging
+ * - User activity tracking
+ * - Billing verification
+ *
+ * Exports:
+ *   - This module: legacy `audit()` API + Prisma storage adapter (stable for
+ *     internal callers; see `INTEGRATION_NOTES.md` for migration plan).
+ *   - `@nebutra/audit/schema`: Zod schemas + `defineAction` + `ACTIONS`
+ *   - `@nebutra/audit/middleware`: `auditLogger(req, ...)`, `withAudit(...)`
+ *   - `@nebutra/audit/providers`: `getAuditProvider()`, provider classes
+ */
+import { getSystemDb } from "@nebutra/db";
+import { logger } from "@nebutra/logger";
+export { auditLogger, extractRequestContext, withAudit, } from "./middleware";
+export { ClickHouseAuditProvider, createAuditProvider, getAuditProvider, MemoryAuditProvider, PostgresAuditProvider, } from "./providers";
+// Re-exports for the new schema/provider/middleware surface.
+export * from "./schema";
+function parseAuditMetadata(metadata) {
+    if (!metadata)
+        return undefined;
+    if (typeof metadata !== "string")
+        return metadata;
+    try {
+        const parsed = JSON.parse(metadata);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : { value: parsed };
+    }
+    catch {
+        return { value: metadata };
+    }
+}
+function mapPrismaAuditRow(row) {
+    const metadata = parseAuditMetadata(row.metadata);
+    return {
+        ...(row.id ? { id: row.id } : {}),
+        action: row.action,
+        actorId: row.userId,
+        actorType: row.actorType,
+        ...(row.organizationId ? { tenantId: row.organizationId } : {}),
+        ...(row.entityType ? { targetType: row.entityType } : {}),
+        ...(row.entityId ? { targetId: row.entityId } : {}),
+        ...(metadata ? { metadata } : {}),
+        ...(row.ipAddress ? { ipAddress: row.ipAddress } : {}),
+        ...(row.userAgent ? { userAgent: row.userAgent } : {}),
+        ...(row.createdAt ? { timestamp: row.createdAt } : {}),
+        outcome: row.outcome,
+        ...(row.reason ? { reason: row.reason } : {}),
+    };
+}
+// ============================================
+// In-Memory Storage (for development)
+// ============================================
+const memoryStorage = [];
+/** @internal — exposed for tests so they can reset the legacy in-memory buffer. */
+export function __resetLegacyMemoryStorage() {
+    memoryStorage.length = 0;
+}
+export const inMemoryStorage = {
+    store: async (event) => {
+        memoryStorage.push({
+            ...event,
+            id: event.id || crypto.randomUUID(),
+            timestamp: event.timestamp || new Date(),
+        });
+    },
+    query: async (filter) => {
+        // Walk newest-to-oldest insertion order so that callers reading `logs[0]`
+        // always see the most recently inserted match, even when timestamps tie at
+        // millisecond resolution.
+        let results = [...memoryStorage].reverse();
+        if (filter.tenantId) {
+            results = results.filter((e) => e.tenantId === filter.tenantId);
+        }
+        if (filter.actorId) {
+            results = results.filter((e) => e.actorId === filter.actorId);
+        }
+        if (filter.action) {
+            results = results.filter((e) => e.action === filter.action);
+        }
+        if (filter.targetType) {
+            results = results.filter((e) => e.targetType === filter.targetType);
+        }
+        if (filter.targetId) {
+            results = results.filter((e) => e.targetId === filter.targetId);
+        }
+        if (filter.startDate) {
+            results = results.filter((e) => e.timestamp && filter.startDate && e.timestamp >= filter.startDate);
+        }
+        if (filter.endDate) {
+            results = results.filter((e) => e.timestamp && filter.endDate && e.timestamp <= filter.endDate);
+        }
+        // Sort by timestamp descending; with stable sort, ties retain the
+        // insertion-order-reversed sequence above (newest first).
+        results.sort((a, b) => {
+            const timeA = a.timestamp?.getTime() || 0;
+            const timeB = b.timestamp?.getTime() || 0;
+            return timeB - timeA;
+        });
+        // Apply pagination
+        const offset = filter.offset || 0;
+        const limit = filter.limit || 100;
+        return results.slice(offset, offset + limit);
+    },
+};
+// ============================================
+// Database Storage (using Prisma)
+// ============================================
+export function createPrismaStorage(prisma) {
+    return {
+        store: async (event) => {
+            // Field mapping: AuditEvent interface → Prisma AuditLog columns
+            //   actorId    → userId          (Prisma model uses userId for the actor)
+            //   tenantId   → organizationId  (Prisma model uses organizationId)
+            //   targetType → entityType      (Prisma model uses entity* naming)
+            //   targetId   → entityId
+            //   actorType, outcome, reason → added in migration 20260316000000
+            await prisma.auditLog.create({
+                data: {
+                    id: event.id || crypto.randomUUID(),
+                    action: event.action,
+                    userId: event.actorId,
+                    actorType: event.actorType,
+                    organizationId: event.tenantId,
+                    entityType: event.targetType ?? "unknown",
+                    entityId: event.targetId,
+                    metadata: event.metadata ? JSON.stringify(event.metadata) : null,
+                    ipAddress: event.ipAddress,
+                    userAgent: event.userAgent,
+                    outcome: event.outcome,
+                    reason: event.reason,
+                    createdAt: event.timestamp || new Date(),
+                },
+            });
+        },
+        query: async (filter) => {
+            const where = {};
+            if (filter.tenantId)
+                where.organizationId = filter.tenantId;
+            if (filter.actorId)
+                where.userId = filter.actorId;
+            if (filter.action)
+                where.action = filter.action;
+            if (filter.targetType)
+                where.entityType = filter.targetType;
+            if (filter.targetId)
+                where.entityId = filter.targetId;
+            if (filter.startDate || filter.endDate) {
+                where.createdAt = {};
+                if (filter.startDate)
+                    where.createdAt.gte = filter.startDate;
+                if (filter.endDate)
+                    where.createdAt.lte = filter.endDate;
+            }
+            const results = await prisma.auditLog.findMany({
+                where,
+                orderBy: { createdAt: "desc" },
+                take: filter.limit || 100,
+                skip: filter.offset || 0,
+            });
+            return results.map(mapPrismaAuditRow);
+        },
+    };
+}
+// ============================================
+// Audit Logger
+// ============================================
+let storage = inMemoryStorage;
+// Attach Prisma DB storage.
+// AUDIT(no-tenant): audit logs are written for every tenant through a single
+// shared storage adapter. Each AuditEvent carries its own organizationId/
+// tenantId, so cross-tenant writes here are intentional.
+try {
+    setAuditStorage(createPrismaStorage(getSystemDb()));
+}
+catch (e) {
+    logger.warn("Prisma storage adapter failed to initialize, relying on in-memory audit logs", {
+        error: e,
+    });
+}
+export function setAuditStorage(newStorage) {
+    storage = newStorage;
+}
+export async function audit(event) {
+    const fullEvent = {
+        ...event,
+        id: crypto.randomUUID(),
+        timestamp: new Date(),
+    };
+    try {
+        await storage.store(fullEvent);
+    }
+    catch (error) {
+        // Log via structured logger as fallback, but don't throw
+        logger.error("Audit log storage failed", error, { event: fullEvent });
+    }
+}
+export async function queryAuditLogs(filter) {
+    return storage.query(filter);
+}
+// ============================================
+// Convenience Functions
+// ============================================
+export function auditUserLogin(userId, tenantId, success, ipAddress, userAgent) {
+    return audit({
+        action: "user.login",
+        actorId: userId,
+        actorType: "user",
+        tenantId,
+        outcome: success ? "success" : "failure",
+        ...(ipAddress && { ipAddress }),
+        ...(userAgent && { userAgent }),
+    });
+}
+export function auditUserLogout(userId, tenantId) {
+    return audit({
+        action: "user.logout",
+        actorId: userId,
+        actorType: "user",
+        tenantId,
+        outcome: "success",
+    });
+}
+export function auditRoleChange(adminId, tenantId, targetUserId, oldRole, newRole) {
+    return audit({
+        action: "org.role_change",
+        actorId: adminId,
+        actorType: "admin",
+        tenantId,
+        targetType: "user",
+        targetId: targetUserId,
+        outcome: "success",
+        metadata: { oldRole, newRole },
+    });
+}
+export function auditBillingEvent(tenantId, action, metadata) {
+    return audit({
+        action,
+        actorId: "system",
+        actorType: "system",
+        tenantId,
+        outcome: action.includes("failed") ? "failure" : "success",
+        metadata,
+    });
+}
+export function auditApiKeyCreate(userId, tenantId, keyId, keyName) {
+    return audit({
+        action: "api.key_create",
+        actorId: userId,
+        actorType: "user",
+        tenantId,
+        targetType: "api_key",
+        targetId: keyId,
+        outcome: "success",
+        metadata: { keyName },
+    });
+}
+export function auditDataExport(userId, tenantId, exportType, metadata) {
+    return audit({
+        action: "data.export",
+        actorId: userId,
+        actorType: "user",
+        tenantId,
+        outcome: "success",
+        metadata: { exportType, ...metadata },
+    });
+}
+// ============================================
+// Middleware for Hono
+// ============================================
+export function auditMiddleware() {
+    return async (c, next) => {
+        // Store audit context
+        const ipAddress = c.req.header("x-forwarded-for") || c.req.header("x-real-ip");
+        const userAgent = c.req.header("user-agent");
+        c.set("auditContext", {
+            tenantId: c.req.header("x-tenant-id"),
+            ...(ipAddress && { ipAddress }),
+            ...(userAgent && { userAgent }),
+        });
+        await next();
+    };
+}

package/dist/middleware.d.ts

@@ -0,0 +1,75 @@
+import { type ActorType, type AuditEvent, type Outcome, type Resource } from "./schema";
+interface HeaderLike {
+    get(name: string): string | null;
+}
+interface RequestLike {
+    headers: HeaderLike;
+}
+export interface AuditRequestContext {
+    ip?: string;
+    userAgent?: string;
+    requestId?: string;
+}
+export declare function extractRequestContext(req: RequestLike | undefined): AuditRequestContext;
+export interface AuditLoggerDefaults {
+    actor: {
+        id: string;
+        type: ActorType;
+        email?: string;
+        name?: string;
+    };
+    tenantId: string;
+    resource?: Resource;
+}
+export interface AuditLoggerLogInput {
+    action: string;
+    outcome: Outcome;
+    resource?: Resource;
+    severity?: AuditEvent["severity"];
+    changes?: AuditEvent["changes"];
+    metadata?: Record<string, unknown>;
+}
+export interface BoundAuditLogger {
+    log(input: AuditLoggerLogInput): Promise<void>;
+}
+/**
+ * Build a request-scoped audit logger. The returned object pre-populates
+ * actor/tenant/ip/userAgent fields so call sites only need to supply the
+ * action-specific data.
+ */
+export declare function auditLogger(req: RequestLike | undefined, defaults: AuditLoggerDefaults): BoundAuditLogger;
+export interface WithAuditOptions {
+    action: string;
+    /** A function that derives actor/tenant/resource from the incoming request. */
+    resolveContext: (req: Request) => Promise<AuditLoggerDefaults | null> | AuditLoggerDefaults | null;
+    /** A function that derives the resource from the request (after handler success). */
+    resolveResource?: (req: Request, response: Response) => Promise<Resource | undefined> | Resource | undefined;
+    severity?: AuditEvent["severity"];
+}
+/**
+ * Wrap a Next.js Route Handler with automatic audit logging. The handler is
+ * invoked exactly once; its outcome is observed and recorded.
+ *
+ * @example
+ * ```ts
+ * export const POST = withAudit(
+ *   {
+ *     action: "api_key.created",
+ *     resolveContext: async (req) => {
+ *       const auth = await getAuth(req);
+ *       if (!auth.userId || !auth.orgId) return null;
+ *       return {
+ *         actor: { id: auth.userId, type: "user" },
+ *         tenantId: auth.orgId,
+ *       };
+ *     },
+ *   },
+ *   async (req) => {
+ *     // ... existing handler body
+ *   },
+ * );
+ * ```
+ */
+export declare function withAudit(options: WithAuditOptions, handler: (req: Request) => Promise<Response>): (req: Request) => Promise<Response>;
+export {};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAqBA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EAEf,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,UAAU,CAAC;AAMlB,UAAU,UAAU;IAClB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,UAAU,WAAW;IACnB,OAAO,EAAE,UAAU,CAAC;CACrB;AAQD,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,mBAAmB,CAevF;AAMD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,WAAW,GAAG,SAAS,EAC5B,QAAQ,EAAE,mBAAmB,GAC5B,gBAAgB,CA+BlB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,cAAc,EAAE,CACd,GAAG,EAAE,OAAO,KACT,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,GAAG,mBAAmB,GAAG,IAAI,CAAC;IACtE,qFAAqF;IACrF,eAAe,CAAC,EAAE,CAChB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,QAAQ,KACf,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAC3C,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiErC"}

package/dist/middleware.js

@@ -0,0 +1,197 @@
+// =============================================================================
+// Request-bound audit helpers
+// =============================================================================
+// Two ergonomic entry points for application code:
+//
+//   auditLogger(req, defaults)
+//     Returns a thin context-bound logger pre-populated with actor, tenant, IP,
+//     userAgent, and requestId derived from a Request/Headers. Application
+//     code calls `await audit.log({ action, resource, outcome, ... })`.
+//
+//   withAudit({ action, resource, ... }, handler)
+//     Wraps a Next.js Route Handler — runs the handler and emits a
+//     success/failure audit event around it. Handler exceptions are re-thrown
+//     after logging so callers' error handling is preserved.
+//
+// Both helpers are provider-agnostic: they go through getAuditProvider() and
+// honor the AUDIT_PROVIDER env var.
+// =============================================================================
+import { logger } from "@nebutra/logger";
+import { getAuditProvider } from "./providers";
+import { AuditEventInputSchema, } from "./schema";
+function readHeader(req, name) {
+    if (!req)
+        return undefined;
+    const value = req.headers.get(name);
+    return value ?? undefined;
+}
+export function extractRequestContext(req) {
+    if (!req)
+        return {};
+    const xff = readHeader(req, "x-forwarded-for");
+    const ip = xff?.split(",")[0]?.trim() ?? readHeader(req, "x-real-ip");
+    const userAgent = readHeader(req, "user-agent");
+    const requestId = readHeader(req, "x-request-id") ??
+        readHeader(req, "x-vercel-id") ??
+        readHeader(req, "x-amzn-trace-id");
+    return {
+        ...(ip ? { ip } : {}),
+        ...(userAgent ? { userAgent } : {}),
+        ...(requestId ? { requestId } : {}),
+    };
+}
+/**
+ * Build a request-scoped audit logger. The returned object pre-populates
+ * actor/tenant/ip/userAgent fields so call sites only need to supply the
+ * action-specific data.
+ */
+export function auditLogger(req, defaults) {
+    const context = extractRequestContext(req);
+    return {
+        async log(input) {
+            const resource = input.resource ?? defaults.resource;
+            if (!resource) {
+                // Defensive: a missing resource means the call site forgot to specify
+                // what was acted upon. Log via @nebutra/logger so this never silently
+                // breaks audit coverage.
+                logger.warn("[audit] auditLogger.log called without resource — event dropped", {
+                    action: input.action,
+                });
+                return;
+            }
+            const eventInput = {
+                actor: defaults.actor,
+                tenantId: defaults.tenantId,
+                action: input.action,
+                outcome: input.outcome,
+                resource,
+                severity: input.severity ?? "info",
+                context,
+                ...(input.changes ? { changes: input.changes } : {}),
+                ...(input.metadata ? { metadata: input.metadata } : {}),
+            };
+            await emitAuditEvent(eventInput);
+        },
+    };
+}
+/**
+ * Wrap a Next.js Route Handler with automatic audit logging. The handler is
+ * invoked exactly once; its outcome is observed and recorded.
+ *
+ * @example
+ * ```ts
+ * export const POST = withAudit(
+ *   {
+ *     action: "api_key.created",
+ *     resolveContext: async (req) => {
+ *       const auth = await getAuth(req);
+ *       if (!auth.userId || !auth.orgId) return null;
+ *       return {
+ *         actor: { id: auth.userId, type: "user" },
+ *         tenantId: auth.orgId,
+ *       };
+ *     },
+ *   },
+ *   async (req) => {
+ *     // ... existing handler body
+ *   },
+ * );
+ * ```
+ */
+export function withAudit(options, handler) {
+    return async (req) => {
+        const context = extractRequestContext(req);
+        let defaults = null;
+        try {
+            defaults = await options.resolveContext(req);
+        }
+        catch (error) {
+            logger.warn("[audit] withAudit.resolveContext threw — skipping audit", {
+                action: options.action,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        let response = null;
+        let handlerError = null;
+        try {
+            response = await handler(req);
+        }
+        catch (error) {
+            handlerError = error;
+        }
+        if (defaults) {
+            // Determine outcome:
+            //   - handler threw            → "failure"
+            //   - response 4xx (auth/perm) → "denied"
+            //   - response 5xx             → "failure"
+            //   - else                     → "success"
+            let outcome = "success";
+            if (handlerError || !response) {
+                outcome = "failure";
+            }
+            else {
+                const status = response.status;
+                if (status === 401 || status === 403)
+                    outcome = "denied";
+                else if (status >= 500)
+                    outcome = "failure";
+            }
+            let resource = defaults.resource ?? {
+                type: "request",
+                id: req.url,
+            };
+            if (options.resolveResource && response && !handlerError) {
+                try {
+                    const resolved = await options.resolveResource(req, response);
+                    if (resolved)
+                        resource = resolved;
+                }
+                catch {
+                    // Keep the default — resource resolution is best-effort.
+                }
+            }
+            await emitAuditEvent({
+                actor: defaults.actor,
+                tenantId: defaults.tenantId,
+                action: options.action,
+                outcome,
+                resource,
+                severity: options.severity ?? "info",
+                context,
+            });
+        }
+        if (handlerError)
+            throw handlerError;
+        // After re-throwing on error, `response` is guaranteed non-null here.
+        return response;
+    };
+}
+// -----------------------------------------------------------------------------
+// Internal: validate + dispatch
+// -----------------------------------------------------------------------------
+async function emitAuditEvent(input) {
+    try {
+        const parsed = AuditEventInputSchema.parse(input);
+        const event = {
+            id: parsed.id ?? crypto.randomUUID(),
+            timestamp: parsed.timestamp ?? new Date().toISOString(),
+            actor: parsed.actor,
+            tenantId: parsed.tenantId,
+            action: parsed.action,
+            resource: parsed.resource,
+            outcome: parsed.outcome,
+            severity: parsed.severity ?? "info",
+            context: parsed.context ?? {},
+            ...(parsed.changes ? { changes: parsed.changes } : {}),
+            ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
+        };
+        const provider = await getAuditProvider();
+        await provider.log(event);
+    }
+    catch (error) {
+        // Audit failures must NEVER break the calling code path — log and swallow.
+        logger.error("[audit] Failed to emit audit event", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}