@usebetterdev/audit-core 0.4.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,524 @@
+import { ConsoleRegistration, ConsoleProductEndpoint } from '@usebetterdev/console-contract';
+export { ConsoleRegistration } from '@usebetterdev/console-contract';
+
+/** Identifies a specific resource (table + optional record). */
+interface ResourceFilter {
+    tableName: string;
+    recordId?: string;
+}
+/**
+ * Time-based filter. Discriminated union:
+ * - `{ date: Date }` — absolute cutoff
+ * - `{ duration: string }` — relative duration string (e.g. "30d"), resolved at query time
+ */
+type TimeFilter = {
+    date: Date;
+    duration?: never;
+} | {
+    duration: string;
+    date?: never;
+};
+/** All optional filter fields. OR within arrays, AND across fields. */
+interface AuditQueryFilters {
+    resource?: ResourceFilter;
+    /** Actor IDs to include (OR semantics — entry matches any). */
+    actorIds?: string[];
+    /** Severity levels to include (OR semantics — entry matches any). */
+    severities?: AuditSeverity[];
+    /** Compliance tags (AND semantics — entry must have ALL listed tags). */
+    compliance?: string[];
+    since?: TimeFilter;
+    until?: TimeFilter;
+    /**
+     * Full-text search filter. Adapters MUST use parameterized queries when
+     * passing this value to the database — never interpolate into raw SQL.
+     */
+    searchText?: string;
+    /** Operation types to include (OR semantics — entry matches any). */
+    operations?: AuditOperation[];
+}
+/** Full query specification: filters + pagination controls. */
+interface AuditQuerySpec {
+    filters: AuditQueryFilters;
+    limit?: number;
+    /** Opaque cursor string — adapters define their own encoding. */
+    cursor?: string;
+    /** Sort direction for results. When undefined, the adapter chooses its default. */
+    sortOrder?: "asc" | "desc";
+}
+/** Paginated query result. */
+interface AuditQueryResult {
+    entries: AuditLog[];
+    /** If present, more results are available. Pass to `.after()` for the next page. */
+    nextCursor?: string;
+}
+
+/** Callback that executes a query spec against the adapter. */
+type QueryExecutor = (spec: AuditQuerySpec) => Promise<AuditQueryResult>;
+/**
+ * Fluent, immutable query builder for audit logs.
+ *
+ * Each method returns a **new** instance — safe to fork and share.
+ * Call `.list()` to execute, or `.toSpec()` to inspect without executing.
+ */
+declare class AuditQueryBuilder {
+    #private;
+    constructor(executor: QueryExecutor, filters?: AuditQueryFilters, limit?: number, cursor?: string, maxLimit?: number, sortOrder?: "asc" | "desc");
+    /** Filter by table name and optional record ID. Last-write-wins. */
+    resource(tableName: string, recordId?: string): AuditQueryBuilder;
+    /** Filter by actor IDs (OR semantics, deduplicates). */
+    actor(...ids: string[]): AuditQueryBuilder;
+    /** Add severity levels to the filter (OR semantics, deduplicates). */
+    severity(...levels: AuditSeverity[]): AuditQueryBuilder;
+    /** Add compliance tags to the filter (AND semantics, deduplicates). */
+    compliance(...tags: string[]): AuditQueryBuilder;
+    /**
+     * Filter entries created after a point in time.
+     *
+     * Accepts a `Date` or a duration string (e.g. "4h", "30d", "2w", "3m", "1y").
+     * Duration strings are eagerly validated but resolved at query time for a fresh "now".
+     * Last-write-wins.
+     */
+    since(value: Date | string): AuditQueryBuilder;
+    /**
+     * Filter entries created before a point in time.
+     *
+     * Accepts a `Date` or a duration string (e.g. "4h", "30d", "2w", "3m", "1y").
+     * Duration strings are eagerly validated but resolved at query time for a fresh "now".
+     * Last-write-wins.
+     */
+    until(value: Date | string): AuditQueryBuilder;
+    /** Full-text search filter. Last-write-wins. Max 500 characters. */
+    search(text: string): AuditQueryBuilder;
+    /** Add operation types to the filter (OR semantics, deduplicates). */
+    operation(...ops: AuditOperation[]): AuditQueryBuilder;
+    /** Set maximum number of entries to return. Must be > 0 and <= maxLimit. */
+    limit(n: number): AuditQueryBuilder;
+    /** Set the pagination cursor for fetching the next page. */
+    after(cursor: string): AuditQueryBuilder;
+    /** Set the sort direction for results. */
+    order(direction: "asc" | "desc"): AuditQueryBuilder;
+    /** Returns the query specification without executing. Useful for tests and debugging. */
+    toSpec(): AuditQuerySpec;
+    /** Execute the query against the adapter. */
+    list(): Promise<AuditQueryResult>;
+}
+
+type AuditOperation = "INSERT" | "UPDATE" | "DELETE";
+type AuditSeverity = "low" | "medium" | "high" | "critical";
+/** A single audit log entry as stored in the database. */
+interface AuditLog {
+    id: string;
+    timestamp: Date;
+    tableName: string;
+    operation: AuditOperation;
+    recordId: string;
+    beforeData?: Record<string, unknown>;
+    afterData?: Record<string, unknown>;
+    diff?: {
+        changedFields: string[];
+    };
+    actorId?: string;
+    label?: string;
+    description?: string;
+    severity?: AuditSeverity;
+    compliance?: string[];
+    notify?: boolean;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+    /** Field names that were removed by enrichment redaction. Only set when fields were actually redacted. */
+    redactedFields?: string[];
+}
+/** Context propagated via AsyncLocalStorage for the duration of a request. */
+interface AuditContext {
+    /** User or system identifier performing the action. */
+    actorId?: string;
+    /** Human-readable label for the event (e.g., "User updated"). */
+    label?: string;
+    /** Justification or reason for the action. */
+    reason?: string;
+    /** Compliance framework tags (e.g., ["soc2", "gdpr"]). */
+    compliance?: string[];
+    /** Arbitrary key-value metadata. Redaction rules do not apply to metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Database adapter provided by ORM packages (e.g. drizzle, prisma).
+ * Passed as the `database` field in `BetterAuditConfig`.
+ *
+ * `writeLog` is required. `queryLogs` is optional — only needed when `query()` is used.
+ */
+/** Aggregated statistics returned by `AuditApi.getStats()`. */
+interface AuditStats {
+    totalLogs: number;
+    tablesAudited: number;
+    eventsPerDay: Array<{
+        date: string;
+        count: number;
+    }>;
+    topActors: Array<{
+        actorId: string;
+        count: number;
+    }>;
+    topTables: Array<{
+        tableName: string;
+        count: number;
+    }>;
+    operationBreakdown: Record<string, number>;
+    severityBreakdown: Record<string, number>;
+}
+interface AuditDatabaseAdapter {
+    writeLog(log: AuditLog): Promise<void>;
+    queryLogs?(spec: AuditQuerySpec): Promise<AuditQueryResult>;
+    getLogById?(id: string): Promise<AuditLog | null>;
+    getStats?(options?: {
+        since?: Date;
+        tenantId?: string;
+    }): Promise<AuditStats>;
+    purgeLogs?(options: {
+        before: Date;
+        tableName?: string;
+    }): Promise<{
+        deletedCount: number;
+    }>;
+}
+/**
+ * Hook that runs before a log is written. May mutate the log. Errors abort the write.
+ *
+ * The log has already been enriched (labels, severity, redaction) by the time
+ * beforeLog hooks run. Hooks see post-redaction data.
+ */
+type BeforeLogHook = (log: AuditLog) => void | Promise<void>;
+/** Hook that runs after a log is written. Receives a readonly snapshot. */
+type AfterLogHook = (log: Readonly<AuditLog>) => void | Promise<void>;
+
+/**
+ * Top-level config passed to `betterAudit()`.
+ *
+ * Async error handling: when `asyncWrite` is true (or overridden per-call), write
+ * failures and afterLog hook errors are caught. If `onError` is set, it receives
+ * the error. Otherwise, a sanitized message is logged to `console.error`.
+ */
+interface BetterAuditConfig {
+    /** Database adapter (from an ORM package) that handles writing and querying audit logs. */
+    database: AuditDatabaseAdapter;
+    /** Tables to audit. Only events for these tables are captured; others are silently skipped. */
+    auditTables: string[];
+    /** When true, writes are fire-and-forget by default. Per-call `asyncWrite` overrides this. */
+    asyncWrite?: boolean;
+    /**
+     * Hooks that run before each log is written. Sequential, may mutate the log.
+     * Hooks see post-enrichment, post-redaction data.
+     */
+    beforeLog?: BeforeLogHook[];
+    /** Hooks that run after each log is written. Sequential, observational. */
+    afterLog?: AfterLogHook[];
+    /**
+     * Hard upper-bound for query results. Defaults to 1000.
+     * `.limit(n)` will throw if `n` exceeds this value.
+     * When no explicit limit is set, this value is used as the default.
+     */
+    maxQueryLimit?: number;
+    /**
+     * Called when an async write or afterLog hook fails. Receives the raw error.
+     * If not set, falls back to `console.error` with sanitized output (no PII).
+     */
+    onError?: (error: unknown) => void;
+    /** Console integration. Pass a BetterConsoleInstance to register audit dashboard endpoints. */
+    console?: ConsoleRegistration;
+}
+/** Input to a manual captureLog call. Context fields override the current AsyncLocalStorage scope. */
+interface CaptureLogInput {
+    tableName: string;
+    operation: AuditOperation;
+    recordId: string;
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+    actorId?: string;
+    label?: string;
+    /** Capture-time description (not stored in AuditContext). */
+    description?: string;
+    /** Capture-time severity override (not stored in AuditContext). */
+    severity?: AuditSeverity;
+    compliance?: string[];
+    notify?: boolean;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+    /** Override the config-level asyncWrite for this specific call. */
+    asyncWrite?: boolean;
+}
+/**
+ * Context passed to an enrichment description function.
+ *
+ * **Important:** The `before`, `after`, and `diff` fields contain **post-redaction**
+ * data. If a field was redacted, its value will be absent from these objects.
+ * Use `diff.changedFields` for field names — redacted fields are excluded from
+ * that list as well.
+ */
+interface EnrichmentDescriptionContext {
+    before: Record<string, unknown> | undefined;
+    after: Record<string, unknown> | undefined;
+    diff: {
+        changedFields: string[];
+    } | undefined;
+    actorId: string | undefined;
+    metadata: Record<string, unknown> | undefined;
+}
+/** Declarative enrichment config registered via audit.enrich(). */
+interface EnrichmentConfig {
+    label?: string;
+    description?: (context: EnrichmentDescriptionContext) => string;
+    severity?: AuditSeverity;
+    compliance?: string[];
+    notify?: boolean;
+    /**
+     * Fields to remove from beforeData, afterData, and diff. Mutually exclusive with `include`.
+     *
+     * Redaction does NOT apply to `metadata` — avoid putting PII in metadata directly.
+     * Only top-level keys are matched. To redact a nested field like `profile.ssn`,
+     * list the parent key `"profile"`.
+     */
+    redact?: string[];
+    /**
+     * Fields to keep in beforeData, afterData, and diff — all others are removed.
+     * Mutually exclusive with `redact`.
+     *
+     * Redaction does NOT apply to `metadata` — avoid putting PII in metadata directly.
+     * Only top-level keys are matched. To keep a nested field like `profile.name`,
+     * list the parent key `"profile"`.
+     */
+    include?: string[];
+}
+interface BetterAuditInstance {
+    captureLog(input: CaptureLogInput): Promise<void>;
+    /** Returns a fluent query builder. Requires `queryAdapter` in config. */
+    query(): AuditQueryBuilder;
+    withContext<T>(context: AuditContext, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Register an enrichment config for a table/operation pair.
+     *
+     * Table names are case-sensitive and must match the `tableName` passed to
+     * `captureLog()` exactly. Use `"*"` for wildcard matching.
+     */
+    enrich(table: string, operation: AuditOperation | "*", config: EnrichmentConfig): void;
+    /** Register a hook that runs before each log is written. Returns a dispose function to unregister the hook. */
+    onBeforeLog(hook: BeforeLogHook): () => void;
+    /** Register a hook that runs after each log is written. Returns a dispose function to unregister the hook. */
+    onAfterLog(hook: AfterLogHook): () => void;
+}
+
+declare function betterAudit(config: BetterAuditConfig): BetterAuditInstance;
+
+/**
+ * Returns the current audit context, or undefined when not inside a request
+ * scope (middleware or withContext).
+ */
+declare function getAuditContext(): AuditContext | undefined;
+/**
+ * Run fn inside a scope where getAuditContext() returns the given context.
+ */
+declare function runWithAuditContext<T>(context: AuditContext, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Merge additional context into the current scope and run fn.
+ * If no scope exists, a new one is created from the partial context.
+ * Properties in override take precedence over the existing context.
+ */
+declare function mergeAuditContext<T>(override: Partial<AuditContext>, fn: () => T | Promise<T>): Promise<T>;
+
+/**
+ * Normalize before/after data based on the operation type.
+ *
+ * - **INSERT** → `before` is dropped (only `after` is meaningful)
+ * - **DELETE** → `after` is dropped (only `before` is meaningful)
+ * - **UPDATE** → both are kept as-is
+ */
+declare function normalizeInput(operation: AuditOperation, before: Record<string, unknown> | undefined, after: Record<string, unknown> | undefined): {
+    before: Record<string, unknown> | undefined;
+    after: Record<string, unknown> | undefined;
+};
+
+/**
+ * Logical schema for the `audit_logs` table.
+ *
+ * ORM adapters translate this into their own migration format.
+ * Core never runs SQL — this is a declarative data structure only.
+ */
+type ColumnType = "uuid" | "timestamptz" | "text" | "jsonb" | "boolean";
+interface ColumnDefinition {
+    type: ColumnType;
+    nullable: boolean;
+    primaryKey?: boolean;
+    defaultExpression?: string;
+    indexed?: boolean;
+    description: string;
+}
+/**
+ * Column names in the `audit_logs` table use snake_case.
+ * These map to camelCase properties in the `AuditLog` TypeScript type:
+ *
+ * | Column (snake_case) | AuditLog property (camelCase) |
+ * |---------------------|-------------------------------|
+ * | table_name          | tableName                     |
+ * | record_id           | recordId                      |
+ * | actor_id            | actorId                       |
+ * | before_data         | beforeData                    |
+ * | after_data          | afterData                     |
+ * | redacted_fields     | redactedFields                |
+ */
+type AuditLogColumnName = "id" | "timestamp" | "table_name" | "operation" | "record_id" | "actor_id" | "before_data" | "after_data" | "diff" | "label" | "description" | "severity" | "compliance" | "notify" | "reason" | "metadata" | "redacted_fields";
+interface AuditLogSchema {
+    tableName: string;
+    columns: Record<string, ColumnDefinition>;
+}
+declare const AUDIT_LOG_SCHEMA: AuditLogSchema;
+
+/**
+ * Parses a duration string (e.g. "30d", "2w", "3m", "1y") and returns
+ * a Date that is `duration` before `referenceDate`.
+ *
+ * Supported units: h (hours), d (days), w (weeks), m (months), y (years).
+ * Zero values are rejected.
+ */
+declare function parseDuration(input: string, referenceDate?: Date): Date;
+
+/** Resolved enrichment config after merging all matching tiers. */
+interface ResolvedEnrichment {
+    label?: string;
+    description?: (context: EnrichmentDescriptionContext) => string;
+    severity?: AuditSeverity;
+    compliance?: string[];
+    notify?: boolean;
+    redact?: string[];
+    include?: string[];
+}
+declare class EnrichmentRegistry {
+    private readonly entries;
+    register(table: string, operation: AuditOperation | "*", config: EnrichmentConfig): void;
+    getEntries(): Array<{
+        table: string;
+        operation: string;
+        configs: EnrichmentConfig[];
+    }>;
+    resolve(table: string, operation: string): ResolvedEnrichment | undefined;
+}
+
+/** Flat console-friendly query filters. Single-value fields translated to multi-value internal filters. */
+interface ConsoleQueryFilters {
+    tableName?: string;
+    operation?: string;
+    actorId?: string;
+    severity?: string;
+    compliance?: string;
+    since?: Date;
+    until?: Date;
+    search?: string;
+    limit?: number;
+    cursor?: string;
+}
+/** Serializable summary of an enrichment config (function fields stripped). */
+interface EnrichmentSummary {
+    table: string;
+    operation: string;
+    label?: string;
+    severity?: AuditSeverity;
+    compliance?: string[];
+    notify?: boolean;
+    redact?: string[];
+    include?: string[];
+}
+/** Query result extended with a convenience `hasNextPage` flag. */
+interface ConsoleQueryResult extends AuditQueryResult {
+    hasNextPage: boolean;
+}
+/**
+ * High-level API consumed by console endpoints.
+ *
+ * Wraps the low-level `AuditDatabaseAdapter` methods with sensible defaults
+ * (e.g. clamping `limit` to the configured maximum).
+ */
+interface AuditApi {
+    /** Query audit log entries with optional flat filters and cursor-based pagination. */
+    queryLogs(filters?: ConsoleQueryFilters): Promise<ConsoleQueryResult>;
+    /** Retrieve a single audit log entry by its ID. Returns `null` when not found. */
+    getLog(id: string): Promise<AuditLog | null>;
+    /** Get aggregated audit statistics. Requires adapter.getStats. */
+    getStats(options?: {
+        since?: Date;
+        tenantId?: string;
+    }): Promise<AuditStats>;
+    /** Get serializable summaries of all registered enrichments. */
+    getEnrichments(): EnrichmentSummary[];
+    /** Export logs as CSV or JSON string. */
+    exportLogs(filters?: ConsoleQueryFilters, format?: "csv" | "json"): Promise<string>;
+    /** Purge audit logs before a given date. Requires adapter.purgeLogs. */
+    purgeLogs(options: {
+        before: Date;
+        tableName?: string;
+    }): Promise<{
+        deletedCount: number;
+    }>;
+}
+declare function createAuditApi(adapter: AuditDatabaseAdapter, registry: EnrichmentRegistry, maxQueryLimit?: number): AuditApi;
+
+declare function createAuditConsoleEndpoints(api: AuditApi): ConsoleProductEndpoint[];
+
+/**
+ * Function that extracts a string value from a Web Request.
+ * Return undefined if the value cannot be extracted.
+ * May be sync or async.
+ */
+type ValueExtractor = (request: Request) => string | undefined | Promise<string | undefined>;
+/**
+ * Describes how to extract audit identity from an incoming HTTP request.
+ * All fields are optional — if omitted, the corresponding context field
+ * will be undefined.
+ */
+interface ContextExtractor {
+    /** Extracts the actor identifier (user / service account). */
+    actor?: ValueExtractor;
+}
+/**
+ * Options for `handleMiddleware`.
+ */
+interface MiddlewareHandlerOptions {
+    /** Called when an extractor throws. Defaults to silent fail-open. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Extracts a JWT claim from the `Authorization: Bearer <token>` header.
+ *
+ * Decodes the token **without** signature verification — signing is the
+ * auth layer's responsibility. This is intentional: the audit layer only
+ * needs the identity, not proof of authenticity.
+ *
+ * @param claim - JWT claim name to extract (e.g. `"sub"`, `"tenant_id"`)
+ */
+declare function fromBearerToken(claim: string): ValueExtractor;
+/**
+ * Extracts a value from a named cookie in the `Cookie` header.
+ *
+ * The raw cookie value is returned as-is. To resolve it into a user identity,
+ * compose with a resolver function (e.g. look up a session in a database).
+ *
+ * @param cookieName - Name of the cookie to read
+ */
+declare function fromCookie(cookieName: string): ValueExtractor;
+/**
+ * Extracts a value from a custom request header.
+ *
+ * @param headerName - Header name (case-insensitive per the Web API)
+ */
+declare function fromHeader(headerName: string): ValueExtractor;
+/**
+ * Shared middleware handler used by all framework adapters.
+ *
+ * 1. Extracts actor from the request using the provided extractor
+ * 2. Builds an `AuditContext` (undefined if nothing was extracted)
+ * 3. Wraps `next()` inside `runWithAuditContext()` if context is available
+ * 4. Calls `next()` without context if extraction yields nothing
+ *
+ * Extraction failures never break the request (fail open).
+ */
+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 MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type TimeFilter, type ValueExtractor, betterAudit, createAuditApi, createAuditConsoleEndpoints, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, mergeAuditContext, normalizeInput, parseDuration, runWithAuditContext };