80 lines
4.7 KiB
Markdown
80 lines
4.7 KiB
Markdown
# @suaveplan/api-audit-stdout - Stdout `RequestAuditSink` for @suaveplan/api-host. Writes JSON-per-line audit records to a Writable (default process.stdout) with an HMAC-SHA-256 signature over canonical bytes. Implements the design-doc §12.5 audit-record shape, Zod-validated at the boundary, with bounded backpressure (maxQueueMs default 100ms), observable drop counter, and a once-per-minute warning throttle. OTel counters api.audit.records_total{sink=stdout,type,outcome} and api.audit.dropped_total{sink=stdout}. Server-tier — Bun + Node.
|
|
|
|
Stdout audit sink for `@suaveplan/api-host`. Writes JSON-per-line
|
|
audit records to a `LineWriter` (default `process.stdout`) with an
|
|
HMAC-SHA-256 signature appended as a `_hmac` field. Implements
|
|
`RequestAuditSink` from `@suaveplan/api-host/request-pipeline`, so the
|
|
host's request pipeline accepts the instance directly via its `audit`
|
|
capability slot.
|
|
|
|
The record shape is the design-doc §12.5 canonical wire format —
|
|
`ts`, `type`, `principal`, `tenant`, `request_id`, `trace_id`,
|
|
`subject`, `outcome`, and a conditional `cause`. Each record is
|
|
Zod-validated at the boundary before signing, so a malformed record
|
|
never reaches the log pipeline.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [error-codes](./src/error-codes/error-codes.md) — This module declares the four stable error codes the stdout audit sink exposes to consumers. Every failure path inside…
|
|
- [error-codes](./src/error-codes/error-codes.md) — This module declares the four stable error codes the stdout audit sink exposes to consumers. Every failure path inside…
|
|
- [hmac](./src/hmac/hmac.md) — This module produces the HMAC-SHA-256 tag attached to every audit line. Signing operates on a *canonical* byte represen…
|
|
- [hmac](./src/hmac/hmac.md) — This module produces the HMAC-SHA-256 tag attached to every audit line. Signing operates on a *canonical* byte represen…
|
|
- [instruments](./src/instruments/instruments.md) — This module owns the two counters the stdout sink emits at runtime, matching design doc §12.3's metric surface for the…
|
|
- [instruments](./src/instruments/instruments.md) — This module owns the two counters the stdout sink emits at runtime, matching design doc §12.3's metric surface for the…
|
|
- [options](./src/options/options.md) — This module owns the Zod schema and defaults for the scalar slice of `createStdoutAuditSink({...})`'s input. Validation…
|
|
- [options](./src/options/options.md) — This module owns the Zod schema and defaults for the scalar slice of `createStdoutAuditSink({...})`'s input. Validation…
|
|
- [schema](./src/schema/schema.md) — This module locks the wire shape of the JSON line the stdout sink writes. The shape is exactly what design doc §12.5 sp…
|
|
- [schema](./src/schema/schema.md) — This module locks the wire shape of the JSON line the stdout sink writes. The shape is exactly what design doc §12.5 sp…
|
|
- [sink](./src/sink/sink.md) — This module wires the schema, HMAC signer, instruments, and options into a `RequestAuditSink` implementation that write…
|
|
- [sink](./src/sink/sink.md) — This module wires the schema, HMAC signer, instruments, and options into a `RequestAuditSink` implementation that write…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Modules
|
|
|
|
- [`./sink`](./src/sink/sink.md) — `createStdoutAuditSink`, the
|
|
factory that ties everything together.
|
|
- [`./schema`](./src/schema/schema.md) — `AuditRecord` Zod schema and
|
|
boundary parser.
|
|
- [`./hmac`](./src/hmac/hmac.md) — canonical bytes and HMAC-SHA-256
|
|
signer / verifier.
|
|
- [`./instruments`](./src/instruments/instruments.md) — OTel counters
|
|
(`api.audit.records_total`, `api.audit.dropped_total`).
|
|
- [`./options`](./src/options/options.md) — scalar option schema +
|
|
defaults (`maxQueueMs = 100`, `warnThrottleMs = 60_000`).
|
|
- [`./error-codes`](./src/error-codes/error-codes.md) —
|
|
`AUDIT_STDOUT.*` registry (`INVALID_RECORD`, `WRITER_FAILED`,
|
|
`QUEUE_FULL`, `INVALID_OPTIONS`).
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
import { createStdoutAuditSink } from "@suaveplan/api-audit-stdout";
|
|
|
|
const sink = createStdoutAuditSink({
|
|
hmacKey: new TextEncoder().encode(process.env["AUDIT_HMAC_KEY"]!),
|
|
});
|
|
|
|
await sink.emit({
|
|
at: "2026-05-26T10:00:00.000Z",
|
|
requestId: "req_1",
|
|
traceId: null,
|
|
route: "/admin/plugin",
|
|
plugin: "@core/admin",
|
|
method: "POST",
|
|
principal: { id: "u1", scopes: ["admin"] },
|
|
tenantId: "t1",
|
|
status: 200,
|
|
outcome: "success",
|
|
});
|
|
```
|
|
|
|
## Drop policy
|
|
|
|
Backpressure is bounded by `maxQueueMs` (default 100ms). When the
|
|
queue wait exceeds the bound the record is dropped, the
|
|
`api.audit.dropped_total{sink,reason}` counter increments, and
|
|
(subject to a once-per-`warnThrottleMs` throttle) a single warning is
|
|
logged. Drops are NEVER silent.
|
|
|