@usebetterdev/audit-core 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -452,6 +452,120 @@ declare const AUDIT_LOG_SCHEMA: AuditLogSchema;
  */
 declare function parseDuration(input: string, referenceDate?: Date): Date;
 
+/**
+ * Encodes a cursor from a timestamp and id.
+ * Format: base64(JSON.stringify({ t: iso_string, i: id }))
+ */
+declare function encodeCursor(timestamp: Date, id: string): string;
+/**
+ * Decodes an opaque cursor string back to timestamp + id.
+ * Throws on invalid input.
+ */
+declare function decodeCursor(cursor: string): {
+    timestamp: Date;
+    id: string;
+};
+
+/**
+ * Escapes LIKE/ILIKE wildcard characters so they match literally.
+ * Backslash is the default escape character in PostgreSQL and SQLite LIKE patterns.
+ */
+declare function escapeLikePattern(input: string): string;
+
+/**
+ * Resolves a `TimeFilter` to an absolute `Date`.
+ * Absolute dates are returned as-is; duration strings are parsed relative to now.
+ */
+declare function resolveTimeFilter(filter: TimeFilter): Date;
+
+/** Column names that support simple equality / IN filtering. */
+type AuditFilterField = "tableName" | "recordId" | "actorId" | "severity" | "operation";
+/**
+ * Intermediate representation for a single filter condition.
+ *
+ * Adapters map each variant to their native expression type
+ * (Drizzle `SQL`, Prisma `QueryState` fragments, etc.).
+ */
+type FilterCondition = {
+    readonly kind: "eq";
+    readonly field: AuditFilterField;
+    readonly value: string;
+} | {
+    readonly kind: "in";
+    readonly field: AuditFilterField;
+    readonly values: string[];
+} | {
+    readonly kind: "timestampGte";
+    readonly value: Date;
+} | {
+    readonly kind: "timestampLte";
+    readonly value: Date;
+} | {
+    readonly kind: "search";
+    readonly pattern: string;
+} | {
+    readonly kind: "compliance";
+    readonly tags: string[];
+} | {
+    readonly kind: "cursor";
+    readonly timestamp: Date;
+    readonly id: string;
+    readonly sortOrder: "asc" | "desc";
+};
+interface InterpretFiltersOptions {
+    cursor?: {
+        timestamp: Date;
+        id: string;
+    } | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+}
+/**
+ * Converts `AuditQueryFilters` + optional cursor into a flat array of
+ * `FilterCondition` values. Pure, zero-dep, independently testable.
+ *
+ * Decision logic (shared across all adapters):
+ * - Array filters with 1 element → `eq`, >1 → `in`, 0/undefined → skip
+ * - Time filters → resolved to absolute `Date` via `resolveTimeFilter()`
+ * - Search text → escaped + wrapped with `%` for LIKE/ILIKE
+ * - Compliance tags → passed through (adapter handles JSONB vs json_each)
+ * - Cursor → emitted with sort order for adapter-specific comparison
+ */
+declare function interpretFilters(filters: AuditQueryFilters, options?: InterpretFiltersOptions): readonly FilterCondition[];
+
+/**
+ * Safely converts a count value (number, string, or bigint) to a JavaScript number.
+ * Handles PostgreSQL bigint-as-string, Prisma BigInt, and SQLite numeric returns.
+ */
+declare function toCount(value: unknown): number;
+/**
+ * Assembles raw query result arrays into an `AuditStats` object.
+ * Works for both Date objects (PostgreSQL) and strings (SQLite, Prisma raw).
+ */
+declare function assembleStats(summaryRows: Array<{
+    totalLogs: unknown;
+    tablesAudited: unknown;
+}>, eventsPerDayRows: Array<{
+    date: unknown;
+    count: unknown;
+}>, topActorsRows: Array<{
+    actorId: unknown;
+    count: unknown;
+}>, topTablesRows: Array<{
+    tableName: unknown;
+    count: unknown;
+}>, operationRows: Array<{
+    operation: unknown;
+    count: unknown;
+}>, severityRows: Array<{
+    severity: unknown;
+    count: unknown;
+}>): AuditStats;
+
+declare const VALID_OPERATIONS: ReadonlySet<string>;
+declare const VALID_SEVERITIES: ReadonlySet<string>;
+declare function isAuditOperation(value: string): value is AuditOperation;
+declare function isAuditSeverity(value: string): value is AuditSeverity;
+
 /**
  * Core export engine. Fetches rows in cursor-paginated batches and writes
  * them to the sink as CSV or JSON. Memory stays flat regardless of total rows.
@@ -585,6 +699,12 @@ declare function fromCookie(cookieName: string): ValueExtractor;
  * @param headerName - Header name (case-insensitive per the Web API)
  */
 declare function fromHeader(headerName: string): ValueExtractor;
+/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */
+declare const defaultExtractor: ContextExtractor;
+/**
+ * Runs an extractor safely, catching errors and returning undefined on failure.
+ */
+declare function safeExtract(extractor: ValueExtractor | undefined, request: Request, onError: ((error: unknown) => void) | undefined): Promise<string | undefined>;
 /**
  * Shared middleware handler used by all framework adapters.
  *
@@ -597,4 +717,4 @@ declare function fromHeader(headerName: string): ValueExtractor;
  */
 declare function handleMiddleware(extractor: ContextExtractor, request: Request, next: () => Promise<void>, options?: MiddlewareHandlerOptions): Promise<void>;
 
-export { AUDIT_LOG_SCHEMA, type AfterLogHook, type AuditApi, type AuditContext, type AuditDatabaseAdapter, type AuditLog, type AuditLogColumnName, type AuditLogSchema, type AuditOperation, AuditQueryBuilder, type AuditQueryFilters, type AuditQueryResult, type AuditQuerySpec, type AuditSeverity, type AuditStats, type BeforeLogHook, type BetterAuditConfig, type BetterAuditInstance, type CaptureLogInput, type ColumnDefinition, type ColumnType, type ConsoleQueryFilters, type ConsoleQueryResult, type ContextExtractor, type EnrichmentConfig, type EnrichmentDescriptionContext, type EnrichmentSummary, type ExportOptions, type ExportResponseOptions, type ExportResult, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type TimeFilter, type ValueExtractor, betterAudit, createAuditApi, createAuditConsoleEndpoints, createExportResponse, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, mergeAuditContext, normalizeInput, parseDuration, runExport, runWithAuditContext };
+export { AUDIT_LOG_SCHEMA, type AfterLogHook, type AuditApi, type AuditContext, type AuditDatabaseAdapter, type AuditFilterField, type AuditLog, type AuditLogColumnName, type AuditLogSchema, type AuditOperation, AuditQueryBuilder, type AuditQueryFilters, type AuditQueryResult, type AuditQuerySpec, type AuditSeverity, type AuditStats, type BeforeLogHook, type BetterAuditConfig, type BetterAuditInstance, type CaptureLogInput, type ColumnDefinition, type ColumnType, type ConsoleQueryFilters, type ConsoleQueryResult, type ContextExtractor, type EnrichmentConfig, type EnrichmentDescriptionContext, type EnrichmentSummary, type ExportOptions, type ExportResponseOptions, type ExportResult, type FilterCondition, type InterpretFiltersOptions, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type TimeFilter, VALID_OPERATIONS, VALID_SEVERITIES, type ValueExtractor, assembleStats, betterAudit, createAuditApi, createAuditConsoleEndpoints, createExportResponse, decodeCursor, defaultExtractor, encodeCursor, escapeLikePattern, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, interpretFilters, isAuditOperation, isAuditSeverity, mergeAuditContext, normalizeInput, parseDuration, resolveTimeFilter, runExport, runWithAuditContext, safeExtract, toCount };

package/dist/index.d.ts

@@ -452,6 +452,120 @@ declare const AUDIT_LOG_SCHEMA: AuditLogSchema;
  */
 declare function parseDuration(input: string, referenceDate?: Date): Date;
 
+/**
+ * Encodes a cursor from a timestamp and id.
+ * Format: base64(JSON.stringify({ t: iso_string, i: id }))
+ */
+declare function encodeCursor(timestamp: Date, id: string): string;
+/**
+ * Decodes an opaque cursor string back to timestamp + id.
+ * Throws on invalid input.
+ */
+declare function decodeCursor(cursor: string): {
+    timestamp: Date;
+    id: string;
+};
+
+/**
+ * Escapes LIKE/ILIKE wildcard characters so they match literally.
+ * Backslash is the default escape character in PostgreSQL and SQLite LIKE patterns.
+ */
+declare function escapeLikePattern(input: string): string;
+
+/**
+ * Resolves a `TimeFilter` to an absolute `Date`.
+ * Absolute dates are returned as-is; duration strings are parsed relative to now.
+ */
+declare function resolveTimeFilter(filter: TimeFilter): Date;
+
+/** Column names that support simple equality / IN filtering. */
+type AuditFilterField = "tableName" | "recordId" | "actorId" | "severity" | "operation";
+/**
+ * Intermediate representation for a single filter condition.
+ *
+ * Adapters map each variant to their native expression type
+ * (Drizzle `SQL`, Prisma `QueryState` fragments, etc.).
+ */
+type FilterCondition = {
+    readonly kind: "eq";
+    readonly field: AuditFilterField;
+    readonly value: string;
+} | {
+    readonly kind: "in";
+    readonly field: AuditFilterField;
+    readonly values: string[];
+} | {
+    readonly kind: "timestampGte";
+    readonly value: Date;
+} | {
+    readonly kind: "timestampLte";
+    readonly value: Date;
+} | {
+    readonly kind: "search";
+    readonly pattern: string;
+} | {
+    readonly kind: "compliance";
+    readonly tags: string[];
+} | {
+    readonly kind: "cursor";
+    readonly timestamp: Date;
+    readonly id: string;
+    readonly sortOrder: "asc" | "desc";
+};
+interface InterpretFiltersOptions {
+    cursor?: {
+        timestamp: Date;
+        id: string;
+    } | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+}
+/**
+ * Converts `AuditQueryFilters` + optional cursor into a flat array of
+ * `FilterCondition` values. Pure, zero-dep, independently testable.
+ *
+ * Decision logic (shared across all adapters):
+ * - Array filters with 1 element → `eq`, >1 → `in`, 0/undefined → skip
+ * - Time filters → resolved to absolute `Date` via `resolveTimeFilter()`
+ * - Search text → escaped + wrapped with `%` for LIKE/ILIKE
+ * - Compliance tags → passed through (adapter handles JSONB vs json_each)
+ * - Cursor → emitted with sort order for adapter-specific comparison
+ */
+declare function interpretFilters(filters: AuditQueryFilters, options?: InterpretFiltersOptions): readonly FilterCondition[];
+
+/**
+ * Safely converts a count value (number, string, or bigint) to a JavaScript number.
+ * Handles PostgreSQL bigint-as-string, Prisma BigInt, and SQLite numeric returns.
+ */
+declare function toCount(value: unknown): number;
+/**
+ * Assembles raw query result arrays into an `AuditStats` object.
+ * Works for both Date objects (PostgreSQL) and strings (SQLite, Prisma raw).
+ */
+declare function assembleStats(summaryRows: Array<{
+    totalLogs: unknown;
+    tablesAudited: unknown;
+}>, eventsPerDayRows: Array<{
+    date: unknown;
+    count: unknown;
+}>, topActorsRows: Array<{
+    actorId: unknown;
+    count: unknown;
+}>, topTablesRows: Array<{
+    tableName: unknown;
+    count: unknown;
+}>, operationRows: Array<{
+    operation: unknown;
+    count: unknown;
+}>, severityRows: Array<{
+    severity: unknown;
+    count: unknown;
+}>): AuditStats;
+
+declare const VALID_OPERATIONS: ReadonlySet<string>;
+declare const VALID_SEVERITIES: ReadonlySet<string>;
+declare function isAuditOperation(value: string): value is AuditOperation;
+declare function isAuditSeverity(value: string): value is AuditSeverity;
+
 /**
  * Core export engine. Fetches rows in cursor-paginated batches and writes
  * them to the sink as CSV or JSON. Memory stays flat regardless of total rows.
@@ -585,6 +699,12 @@ declare function fromCookie(cookieName: string): ValueExtractor;
  * @param headerName - Header name (case-insensitive per the Web API)
  */
 declare function fromHeader(headerName: string): ValueExtractor;
+/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */
+declare const defaultExtractor: ContextExtractor;
+/**
+ * Runs an extractor safely, catching errors and returning undefined on failure.
+ */
+declare function safeExtract(extractor: ValueExtractor | undefined, request: Request, onError: ((error: unknown) => void) | undefined): Promise<string | undefined>;
 /**
  * Shared middleware handler used by all framework adapters.
  *
@@ -597,4 +717,4 @@ declare function fromHeader(headerName: string): ValueExtractor;
  */
 declare function handleMiddleware(extractor: ContextExtractor, request: Request, next: () => Promise<void>, options?: MiddlewareHandlerOptions): Promise<void>;
 
-export { AUDIT_LOG_SCHEMA, type AfterLogHook, type AuditApi, type AuditContext, type AuditDatabaseAdapter, type AuditLog, type AuditLogColumnName, type AuditLogSchema, type AuditOperation, AuditQueryBuilder, type AuditQueryFilters, type AuditQueryResult, type AuditQuerySpec, type AuditSeverity, type AuditStats, type BeforeLogHook, type BetterAuditConfig, type BetterAuditInstance, type CaptureLogInput, type ColumnDefinition, type ColumnType, type ConsoleQueryFilters, type ConsoleQueryResult, type ContextExtractor, type EnrichmentConfig, type EnrichmentDescriptionContext, type EnrichmentSummary, type ExportOptions, type ExportResponseOptions, type ExportResult, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type TimeFilter, type ValueExtractor, betterAudit, createAuditApi, createAuditConsoleEndpoints, createExportResponse, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, mergeAuditContext, normalizeInput, parseDuration, runExport, runWithAuditContext };
+export { AUDIT_LOG_SCHEMA, type AfterLogHook, type AuditApi, type AuditContext, type AuditDatabaseAdapter, type AuditFilterField, type AuditLog, type AuditLogColumnName, type AuditLogSchema, type AuditOperation, AuditQueryBuilder, type AuditQueryFilters, type AuditQueryResult, type AuditQuerySpec, type AuditSeverity, type AuditStats, type BeforeLogHook, type BetterAuditConfig, type BetterAuditInstance, type CaptureLogInput, type ColumnDefinition, type ColumnType, type ConsoleQueryFilters, type ConsoleQueryResult, type ContextExtractor, type EnrichmentConfig, type EnrichmentDescriptionContext, type EnrichmentSummary, type ExportOptions, type ExportResponseOptions, type ExportResult, type FilterCondition, type InterpretFiltersOptions, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type TimeFilter, VALID_OPERATIONS, VALID_SEVERITIES, type ValueExtractor, assembleStats, betterAudit, createAuditApi, createAuditConsoleEndpoints, createExportResponse, decodeCursor, defaultExtractor, encodeCursor, escapeLikePattern, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, interpretFilters, isAuditOperation, isAuditSeverity, mergeAuditContext, normalizeInput, parseDuration, resolveTimeFilter, runExport, runWithAuditContext, safeExtract, toCount };

package/dist/index.js

@@ -1468,6 +1468,171 @@ var AUDIT_LOG_SCHEMA = {
   }
 };
 
+// src/cursor.ts
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function encodeCursor(timestamp, id) {
+  const payload = JSON.stringify({ t: timestamp.toISOString(), i: id });
+  return btoa(payload);
+}
+function decodeCursor(cursor) {
+  let parsed;
+  try {
+    parsed = JSON.parse(atob(cursor));
+  } catch {
+    throw new Error("Invalid cursor: failed to decode");
+  }
+  if (typeof parsed !== "object" || parsed === null || !("t" in parsed) || !("i" in parsed)) {
+    throw new Error("Invalid cursor: missing required fields");
+  }
+  const record = parsed;
+  const t = record["t"];
+  const i = record["i"];
+  if (typeof t !== "string" || typeof i !== "string") {
+    throw new Error("Invalid cursor: fields must be strings");
+  }
+  const timestamp = new Date(t);
+  if (isNaN(timestamp.getTime())) {
+    throw new Error("Invalid cursor: invalid timestamp");
+  }
+  if (!UUID_PATTERN.test(i)) {
+    throw new Error("Invalid cursor: id must be a valid UUID");
+  }
+  return { timestamp, id: i };
+}
+
+// src/escape.ts
+function escapeLikePattern(input) {
+  return input.replace(/[%_\\]/g, "\\$&");
+}
+
+// src/time-filter.ts
+function resolveTimeFilter(filter) {
+  if ("date" in filter && filter.date !== void 0) {
+    return filter.date;
+  }
+  if ("duration" in filter && filter.duration !== void 0) {
+    return parseDuration(filter.duration);
+  }
+  throw new Error("TimeFilter must have either date or duration");
+}
+
+// src/filter-builder.ts
+function interpretFilters(filters, options) {
+  const conditions = [];
+  if (filters.resource !== void 0) {
+    conditions.push({ kind: "eq", field: "tableName", value: filters.resource.tableName });
+    if (filters.resource.recordId !== void 0) {
+      conditions.push({ kind: "eq", field: "recordId", value: filters.resource.recordId });
+    }
+  }
+  pushArrayFilter(conditions, "actorId", filters.actorIds);
+  pushArrayFilter(conditions, "severity", filters.severities);
+  pushArrayFilter(conditions, "operation", filters.operations);
+  if (filters.since !== void 0) {
+    conditions.push({ kind: "timestampGte", value: resolveTimeFilter(filters.since) });
+  }
+  if (filters.until !== void 0) {
+    conditions.push({ kind: "timestampLte", value: resolveTimeFilter(filters.until) });
+  }
+  if (filters.searchText !== void 0 && filters.searchText.length > 0) {
+    const escaped = escapeLikePattern(filters.searchText);
+    conditions.push({ kind: "search", pattern: `%${escaped}%` });
+  }
+  if (filters.compliance !== void 0 && filters.compliance.length > 0) {
+    conditions.push({ kind: "compliance", tags: [...filters.compliance] });
+  }
+  if (options?.cursor !== void 0) {
+    conditions.push({
+      kind: "cursor",
+      timestamp: options.cursor.timestamp,
+      id: options.cursor.id,
+      sortOrder: options.sortOrder ?? "desc"
+    });
+  }
+  return conditions;
+}
+function pushArrayFilter(conditions, field, values) {
+  if (values === void 0 || values.length === 0) {
+    return;
+  }
+  if (values.length === 1) {
+    const first = values[0];
+    if (first !== void 0) {
+      conditions.push({ kind: "eq", field, value: first });
+    }
+  } else {
+    conditions.push({ kind: "in", field, values: [...values] });
+  }
+}
+
+// src/stats.ts
+function toCount(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string") {
+    const n = Number(value);
+    return Number.isNaN(n) ? 0 : n;
+  }
+  if (typeof value === "bigint") {
+    return Number(value);
+  }
+  return 0;
+}
+function assembleStats(summaryRows, eventsPerDayRows, topActorsRows, topTablesRows, operationRows, severityRows) {
+  const summary = summaryRows[0];
+  const totalLogs = summary !== void 0 ? toCount(summary.totalLogs) : 0;
+  const tablesAudited = summary !== void 0 ? toCount(summary.tablesAudited) : 0;
+  const eventsPerDay = eventsPerDayRows.map((row) => ({
+    date: row.date instanceof Date ? row.date.toISOString().split("T")[0] ?? "" : String(row.date),
+    count: toCount(row.count)
+  }));
+  const topActors = topActorsRows.map((row) => ({
+    actorId: String(row.actorId),
+    count: toCount(row.count)
+  }));
+  const topTables = topTablesRows.map((row) => ({
+    tableName: String(row.tableName),
+    count: toCount(row.count)
+  }));
+  const operationBreakdown = {};
+  for (const row of operationRows) {
+    operationBreakdown[String(row.operation)] = toCount(row.count);
+  }
+  const severityBreakdown = {};
+  for (const row of severityRows) {
+    severityBreakdown[String(row.severity)] = toCount(row.count);
+  }
+  return {
+    totalLogs,
+    tablesAudited,
+    eventsPerDay,
+    topActors,
+    topTables,
+    operationBreakdown,
+    severityBreakdown
+  };
+}
+
+// src/validation.ts
+var VALID_OPERATIONS2 = /* @__PURE__ */ new Set([
+  "INSERT",
+  "UPDATE",
+  "DELETE"
+]);
+var VALID_SEVERITIES2 = /* @__PURE__ */ new Set([
+  "low",
+  "medium",
+  "high",
+  "critical"
+]);
+function isAuditOperation(value) {
+  return VALID_OPERATIONS2.has(value);
+}
+function isAuditSeverity(value) {
+  return VALID_SEVERITIES2.has(value);
+}
+
 // src/context-extractor.ts
 function decodeJwtPayload(token) {
   try {
@@ -1545,6 +1710,9 @@ function fromHeader(headerName) {
     return value.trim();
   };
 }
+var defaultExtractor = {
+  actor: fromBearerToken("sub")
+};
 async function safeExtract(extractor, request, onError) {
   if (!extractor) {
     return void 0;
@@ -1570,19 +1738,32 @@ async function handleMiddleware(extractor, request, next, options = {}) {
 export {
   AUDIT_LOG_SCHEMA,
   AuditQueryBuilder,
+  VALID_OPERATIONS2 as VALID_OPERATIONS,
+  VALID_SEVERITIES2 as VALID_SEVERITIES,
+  assembleStats,
   betterAudit,
   createAuditApi,
   createAuditConsoleEndpoints,
   createExportResponse,
+  decodeCursor,
+  defaultExtractor,
+  encodeCursor,
+  escapeLikePattern,
   fromBearerToken,
   fromCookie,
   fromHeader,
   getAuditContext,
   handleMiddleware,
+  interpretFilters,
+  isAuditOperation,
+  isAuditSeverity,
   mergeAuditContext,
   normalizeInput,
   parseDuration,
+  resolveTimeFilter,
   runExport,
-  runWithAuditContext
+  runWithAuditContext,
+  safeExtract,
+  toCount
 };
 //# sourceMappingURL=index.js.map