auth/audit_log_queries.ts

Audit log database queries.

Records and retrieves auth mutation events for security monitoring. The canonical fire-and-forget entry point is AppDeps.audit.emit(ctx, input) (see auth/audit_emitter.ts) — it closes over the pool so audit rows persist even when the request transaction rolls back. This module only exposes the in-transaction query_* primitives and the drift counters; the bound emitter writes through query_audit_log against its captured pool.

view source

Declarations
#

11 declarations

AUDIT_LOG_COLUMNS
#

auth/audit_log_queries.ts view source

readonly ["id", "seq", "event_type", "outcome", "actor_id", "account_id", "target_account_id", "target_actor_id", "ip", "created_at", "metadata"] import {AUDIT_LOG_COLUMNS} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

The full audit_log column set, named explicitly so a row read fails loud on schema drift — audit rows ride the audit_log_list / role-grant-history RPC responses and the SSE broadcast raw, so a SELECT * would silently carry a dropped or leftover column into the strict-validated wire shapes (see ACCOUNT_COLUMNS in auth/account_queries.ts for the outage class; the Rust twin names columns at every audit site). Keep in sync with AuditLogEvent and the migration chain's end state. Exported for the per-cell timeline read in db/cell_audit_queries.ts.

audit_log_expr
#

auth/audit_log_queries.ts view source

(alias: string) => ColumnExpr import {audit_log_expr} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

The audit_log timestamp override, by row qualifier ('' bare, al for the username JOINs). Exported for the per-cell timeline read in db/cell_audit_queries.ts, which projects the same table.

get_audit_metadata_validation_failures
#

auth/audit_log_queries.ts view source

(): number import {get_audit_metadata_validation_failures} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

Number of audit metadata validation failures observed since process start.

returns

number

get_audit_unknown_event_type_failures
#

auth/audit_log_queries.ts view source

(): number import {get_audit_unknown_event_type_failures} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

Number of audit unknown-event-type failures observed since process start.

returns

number

query_audit_log
#

auth/audit_log_queries.ts view source

<T extends string>(deps: QueryDeps, input: AuditLogInput<T>, config?: AuditLogConfig): Promise<AuditLogEvent> import {query_audit_log} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

Insert an audit log entry.

Returns the full row (AUDIT_LOG_COLUMNS) so callers receive DB-assigned fields (id, seq, created_at). Validates metadata against config.metadata_schemas; unknown event_type and metadata mismatches log + bump their counters but write the row anyway. Consumers extend the recognized set via create_audit_log_config({extra_events}).

In-transaction call site for query helpers that must atomically write the row alongside other mutations (e.g. query_accept_offer). Fire-and-forget call sites should reach for AppDeps.audit.emit instead — that wrapper closes over the pool so audit rows persist when the parent transaction rolls back.

deps

query dependencies

input

the audit event to record

type AuditLogInput<T>

config

audit-log config. Defaults to builtin_audit_log_config.

default builtin_audit_log_config

returns

Promise<AuditLogEvent>

the inserted audit log row

generics

query_audit_log<T extends string>
T
constraint string

mutates

  • drift — counters - bumps `audit_unknown_event_type_failures` and/or `audit_metadata_validation_failures` on mismatch

query_audit_log_cleanup_before
#

auth/audit_log_queries.ts view source

(deps: QueryDeps, before: Date): Promise<number> import {query_audit_log_cleanup_before} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

Delete audit log entries older than the given date.

deps

query dependencies

before

delete entries created before this date

type Date

returns

Promise<number>

the number of entries deleted

query_audit_log_list
#

auth/audit_log_queries.ts view source

(deps: QueryDeps, options?: AuditLogListOptions | undefined): Promise<AuditLogEvent[]> import {query_audit_log_list} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

List audit log entries, newest first.

deps

query dependencies

options?

filters and pagination

type AuditLogListOptions | undefined
optional

returns

Promise<AuditLogEvent[]>

matching audit log entries

query_audit_log_list_role_grant_history
#

auth/audit_log_queries.ts view source

(deps: QueryDeps, limit?: number, offset?: number): Promise<{ id: string & $brand<"Uuid">; seq: number; event_type: string; outcome: "success" | "failure"; actor_id: (string & $brand<...>) | null; ... 7 more ...; target_username: string | null; }[]> import {query_audit_log_list_role_grant_history} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

List role_grant grant/revoke events with resolved usernames.

deps

query dependencies

limit

maximum entries to return

type number
default AUDIT_LOG_DEFAULT_LIMIT

offset

number of entries to skip

type number
default 0

returns

Promise<{ id: string & $brand<"Uuid">; seq: number; event_type: string; outcome: "success" | "failure"; actor_id: (string & $brand<"Uuid">) | null; account_id: (string & $brand<...>) | null; ... 6 more ...; target_username: string | null; }[]>

role_grant history events with username and target_username

query_audit_log_list_with_usernames
#

auth/audit_log_queries.ts view source

(deps: QueryDeps, options?: AuditLogListOptions | undefined): Promise<{ id: string & $brand<"Uuid">; seq: number; event_type: string; outcome: "success" | "failure"; ... 8 more ...; target_username: string | null; }[]> import {query_audit_log_list_with_usernames} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

List audit log entries with resolved usernames, newest first.

deps

query dependencies

options?

filters and pagination

type AuditLogListOptions | undefined
optional

returns

Promise<{ id: string & $brand<"Uuid">; seq: number; event_type: string; outcome: "success" | "failure"; actor_id: (string & $brand<"Uuid">) | null; account_id: (string & $brand<...>) | null; ... 6 more ...; target_username: string | null; }[]>

matching audit log entries with username and target_username

reset_audit_metadata_validation_failures
#

auth/audit_log_queries.ts view source

(): void import {reset_audit_metadata_validation_failures} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

Reset the counter — for tests only.

returns

void

reset_audit_unknown_event_type_failures
#

auth/audit_log_queries.ts view source

(): void import {reset_audit_unknown_event_type_failures} from '@fuzdev/fuz_app/auth/audit_log_queries.js';

Reset the counter — for tests only.

returns

void

Depends on
#

Imported by
#