audit-plugin/src/index.ts - Setu-TS documentation

Classes

Audit service backed by an IAuditStorage port.

log(entry: AuditEntry): Promise<void>
Appends an entry to the audit trail. Entries are immutable once written.

Database-backed audit storage. Requires an injected IAuditDbClient at construction time.

append(entry: StoredAuditEntry): Promise<void>
Appends one row via client.insert.
close(): Promise<void>
The injected client owns the connection lifecycle; nothing to drain here.
isHealthy(): Promise<boolean>
Probes the injected client with a select that matches nothing.
isReady(): boolean
Database storage is always ready once constructed.
query(criteria?: AuditQuery): Promise<StoredAuditEntry[]>
Selects rows via client.select, filters, maps to frozen entries.

File-backed audit storage. Writes JSONL to path via runtime.fs.

append(entry: StoredAuditEntry): Promise<void>
Read-modify-write with serialized in-process appends via _lock. Cross-process file contention is inherent to the OS file and not solved here.
close(): Promise<void>
Awaits the serialized write chain so no in-flight append is lost on close.
isHealthy(): Promise<boolean>
Reports whether the audit file's sink is reachable.
isReady(): boolean
File storage is always ready once constructed (we don't probe the FS).
query(criteria?: AuditQuery): Promise<StoredAuditEntry[]>
Reads and filters lines via matchAuditQuery.

Logs audit records through an ILogger. When constructed without a logger and used as a storage backend, queries return empty arrays.

append(entry: StoredAuditEntry): Promise<void>
Routes the frozen record to logger[level]('audit', record).
close(): Promise<void>
The logger owns its own flush lifecycle; nothing to drain here.
isHealthy(): Promise<boolean>
Lifecycle truth: the sink is the resolved ILogger, which is in-process, so reachability IS readiness. Where that logger's own transport goes is the logger's health to report, not this backend's.
isReady(): boolean
Ready as long as a logger is configured.
query(_criteria?: AuditQuery): Promise<StoredAuditEntry[]>
The log sink is the durable trail; read-back happens through the logging backend, not this object. Returns [].
setContextLogger(logger: ILogger): void
Initializes the logger from context when not injected.
setLogLevel(level: LogLevel): void
Sets the log level for emitting audit records.

In-memory audit storage backed by an array. Stores already-frozen records; isReady() always returns true. Non-durable across restarts.

append(entry: StoredAuditEntry): Promise<void>
Appends a (already frozen) entry.
close(): Promise<void>
No buffered state — appends complete synchronously.
isHealthy(): Promise<boolean>
Lifecycle truth: an in-process array has no separate sink to reach, so reachability IS readiness — the process either holds the entries or it does not.
isReady(): boolean
Whether the storage is ready to accept writes.
query(criteria?: AuditQuery): Promise<StoredAuditEntry[]>
Filters entries via matchAuditQuery, then orders ascending by timestamp and applies limit (newest) via orderAndLimit.

AuditPlugin factory — registers an IAuditLogger under CAPABILITIES.AUDIT.

One immutable audit trail entry.

action: string
The action performed (e.g. "user.delete").
after: Readonly<Record<string, unknown>>
Resource state after the action.
before: Readonly<Record<string, unknown>>
Resource state before the action.
metadata: Readonly<Record<string, unknown>>
Additional context (IP, request ID, …).
resource: string
The resource kind acted on (e.g. "user").
resourceId: string
The specific resource instance, when applicable.
result: "success" | "failure"
Whether the action succeeded.
userId: string
The acting principal's ID.

Options accepted by the AuditPlugin factory.

Query criteria for IAuditStorage.query. Every field is optional and combines as AND. An omitted field does not constrain.

action: string
Matches entries whose action equals this value exactly.
from: number
Lower time bound, inclusive (epoch ms).
limit: number
Cap on returned count, applied after filtering and ordering.
resource: string
Matches entries whose resource equals this value exactly.
resourceId: string
Matches entries whose resourceId equals this value exactly.
result: "success" | "failure"
Matches entries whose outcome equals this value.
to: number
Upper time bound, inclusive (epoch ms).
userId: string
Matches entries whose userId equals this value exactly.

Options passed to individual storage backends.

client: IAuditDbClient
Injected database client for DatabaseAuditStorage.
level: "info" | "warn" | "error"
Logger method to emit at ('info'/'warn'/'error'); default 'info'.
logger: ILogger
Injected ILogger for LogAuditStorage; overrides ctx.logger.
path: string
JSONL file path for FileAuditStorage; defaults to './audit.log'.
table: string
Table name for DatabaseAuditStorage; defaults to 'audit_logs'.

Structural shape of an injected database client facade. The DB backend is inject-only — it never touches the database capability token.

Immutable audit trail writer.

log(entry: AuditEntry): Promise<void>
Appends an entry to the audit trail. Entries are immutable once written.

A stored audit record extends AuditEntry with an internally assigned id (UUID v4) and timestamp (wall-clock epoch ms).

action: string
The audited action (e.g. 'user.login').
after: Readonly<Record<string, unknown>> | undefined
Resource state after the operation, when captured.
before: Readonly<Record<string, unknown>> | undefined
Resource state before the operation, when captured.
id: string
Internally assigned unique identifier (UUID v4).
metadata: Readonly<Record<string, unknown>> | undefined
Free-form structured context attached by the caller.
resource: string
The audited resource type (e.g. 'session').
resourceId: string | undefined
The affected resource instance identifier, when known.
result: "success" | "failure"
Whether the audited operation succeeded or failed.
timestamp: number
Wall-clock epoch milliseconds, assigned by the storage at append.
userId: string | undefined
The acting principal's identifier, when authenticated.

Storage backend identifier — closed union.