import { logger } from "@/lib/logger"

/**
 * File-event audit log (KAR-538 / ASVS V5.8.1).
 *
 * Every file lifecycle event (upload, download, delete) emits a
 * structured log record through the existing logger facade so the same
 * scrubbing (KAR-535) and transport (KAR-519) apply. Sensitive fields
 * are never passed — only IDs, sizes, and MIME types.
 *
 * Adoption: any API route or Server Action that creates a signed URL,
 * stores a blob, or removes a file calls `logFileEvent(...)` immediately
 * before/after the storage operation. The event is mandatory for
 * compliance audit-trail, not optional.
 */
export type FileEvent = "file.uploaded" | "file.downloaded" | "file.deleted"

export interface FileEventContext {
  user_id: string
  file_id: string
  bucket?: string
  mime?: string
  size_bytes?: number
  reason?: string
}

export function logFileEvent(event: FileEvent, ctx: FileEventContext): void {
  logger.info(event, {
    user_id: ctx.user_id,
    file_id: ctx.file_id,
    bucket: ctx.bucket,
    mime: ctx.mime,
    size_bytes: ctx.size_bytes,
    reason: ctx.reason,
  })
}