schemas/options

(no submodules)

Purpose

Zod schema that validates AuditPluginOptions at the createAuditPlugin factory boundary and produces the resolved AuditPluginConfig shape consumed by the lifecycle hooks. Centralises every default value the plugin ships with (sampling rate, exclude paths, redaction rules, dev-only secret key) so the rest of the code can rely on a fully-populated config object.

This is the single source of truth for option defaults; anything not here is either a runtime decision (sink injection, logger choice) or a per-request decision (sampling RNG draw).

Features

Zod 4 schema with .transform(...) returning a strongly-typed resolved config.
Defaults for samplingRate (1), excludePaths (health probes + openapi doc), redaction lists (Authorization/Cookie/Token/Password/etc), recordResponseSize (true), recordRequestBody (false), enableChainIntegrity (false).
samplingRate clamped to [0, 1].
Optional sink, logger, rng slots remain unknown here; the factory narrows them at the call site with concrete imports to avoid pulling @suaveplan/audit-logging into the schemas barrel as a value dep.
Exposes DEV_DEFAULT_SECRET_KEY constant so callers and tests can inspect the fallback.

Usage: Basic

import { AuditPluginOptionsSchema } from "@suaveplan/api-plugin-audit/schemas/options";

const config = AuditPluginOptionsSchema.parse({
    secretKey: process.env.AUDIT_SECRET_KEY,
});

console.log(config.samplingRate); // 1
console.log(config.excludePaths); // ["/health", "/healthz", "/ready", "/openapi.json"]

Usage: Advanced

import { AuditPluginOptionsSchema } from "@suaveplan/api-plugin-audit/schemas/options";

const result = AuditPluginOptionsSchema.safeParse({
    samplingRate: 0.25,
    redactBodyFields: ["password", "ssn", "credit_card"],
    enableChainIntegrity: true,
    secretKey: process.env.AUDIT_SECRET_KEY,
});

if (!result.success) {
    // ZodError carrying every boundary violation
    throw result.error;
}

const resolved = result.data;

API Reference

AuditPluginOptionsSchema — Zod schema returning AuditPluginOptionsResolved.
AuditPluginOptionsInput — z.input<typeof AuditPluginOptionsSchema>.
AuditPluginOptionsResolved — z.output<typeof AuditPluginOptionsSchema>.
DEFAULT_REDACT_HEADERS, DEFAULT_REDACT_QUERY, DEFAULT_REDACT_BODY, DEFAULT_EXCLUDE_PATHS — readonly string[] defaults.
DEV_DEFAULT_SECRET_KEY — string fallback used when secretKey is omitted.

Implementation Notes

The schema keeps the sink and logger slots as unknown rather than typed Zod schemas because both interfaces are runtime objects and Zod cannot validate their shape without arbitrary z.custom predicates. The factory passes them straight through to new AuditLogger({ ... }), which already validates secretKey and the storage adapter contract. The secretKey default exists so the dev path works without env wiring; the factory MUST log a warn when the default is used so operators do not ship it to production.

3.1 KiB Raw Blame History