first commit

docs/api-stack/api/api-plugin-audit/src/schemas/options.md

@@ -0,0 +1,64 @@
+# schemas/options
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## 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
+
+```ts
+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
+
+```ts
+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.