auth/audit_log_queries.ts

Audit log database queries.

Records and retrieves auth mutation events for security monitoring. All write operations should use audit_log_fire_and_forget to ensure audit logging never blocks or breaks auth flows.

Rollback resilience: audit_log_fire_and_forget writes to background_db (pool-level), not the handler's transaction-scoped db, so audit entries persist even when the request transaction rolls back.

Declarations
#

8 declarations

view source

AUDIT_LOG_DEFAULT_LIMIT
#

audit_log_fire_and_forget
#

auth/audit_log_queries.ts view source

<T extends AuditEventType>(route: Pick<RouteContext, "background_db" | "pending_effects">, input: AuditLogInput<T>, log: Logger, on_event: (event: AuditLogEvent) => void): Promise<...>

Log an audit event without blocking the caller.

Errors are logged to console — audit logging never breaks auth flows. Uses background_db so audit entries persist even if the request transaction rolls back. Write failures and on_event callback failures are logged separately so the error message indicates which phase failed.

route

background_db and pending_effects from the route context

type Pick<RouteContext, "background_db" | "pending_effects">

input

the audit event to record

type AuditLogInput<T>

log

the logger instance

type Logger

on_event

callback invoked with the inserted row after a successful write

type (event: AuditLogEvent) => void

returns

Promise<void>

the settled promise (callers may ignore it — fire-and-forget semantics preserved)

query_audit_log
#

auth/audit_log_queries.ts view source

<T extends AuditEventType>(deps: QueryDeps, input: AuditLogInput<T>): Promise<AuditLogEvent>

Insert an audit log entry.

Uses RETURNING * to return the full inserted row including DB-assigned fields (id, seq, created_at).

In DEV mode, validates metadata against the per-event-type schema before writing (warns on mismatch, never throws).

deps

query dependencies

type QueryDeps

input

the audit event to record

type AuditLogInput<T>

returns

Promise<AuditLogEvent>

the inserted audit log row

query_audit_log_cleanup_before
#

auth/audit_log_queries.ts view source

(deps: QueryDeps, before: Date): Promise<number>

Delete audit log entries older than the given date.

deps

query dependencies

type QueryDeps

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[]>

List audit log entries, newest first.

deps

query dependencies

type QueryDeps

options?

filters and pagination

type AuditLogListOptions | undefined
optional

returns

Promise<AuditLogEvent[]>

matching audit log entries

query_audit_log_list_for_account
#

auth/audit_log_queries.ts view source

(deps: QueryDeps, account_id: string, limit?: number): Promise<AuditLogEvent[]>

List audit log entries related to an account (as actor or target).

deps

query dependencies

type QueryDeps

account_id

the account to query for

type string

limit

maximum entries to return

type number
default AUDIT_LOG_DEFAULT_LIMIT

returns

Promise<AuditLogEvent[]>

query_audit_log_list_permit_history
#

auth/audit_log_queries.ts view source

(deps: QueryDeps, limit?: number, offset?: number): Promise<{ id: string; seq: number; event_type: "login" | "logout" | "bootstrap" | "signup" | "password_change" | "session_revoke" | ... 8 more ... | "app_settings_update"; ... 8 more ...; target_username: string | null; }[]>

List permit grant/revoke events with resolved usernames.

deps

query dependencies

type QueryDeps

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; seq: number; event_type: "login" | "logout" | "bootstrap" | "signup" | "password_change" | "session_revoke" | "session_revoke_all" | "token_create" | "token_revoke" | ... 5 more ... | "app_settings_update"; ... 8 more ...; target_username: string | null; }[]>

permit 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; seq: number; event_type: "login" | "logout" | "bootstrap" | "signup" | ... 10 more ... | "app_settings_update"; ... 8 more ...; target_username: string | null; }[]>

List audit log entries with resolved usernames, newest first.

deps

query dependencies

type QueryDeps

options?

filters and pagination

type AuditLogListOptions | undefined
optional

returns

Promise<{ id: string; seq: number; event_type: "login" | "logout" | "bootstrap" | "signup" | "password_change" | "session_revoke" | "session_revoke_all" | "token_create" | "token_revoke" | ... 5 more ... | "app_settings_update"; ... 8 more ...; target_username: string | null; }[]>

matching audit log entries with username and target_username

Depends on
#

Imported by
#