first commit

docs/api-stack/api/api-logger-worker-proxy/src/redaction-passthrough/redaction-passthrough.md

@@ -0,0 +1,74 @@
+# `redaction-passthrough`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Lets the main-side server apply the host logger's redaction policy to
+records arriving from worker-isolated plugins. Workers run in their own
+runtime — they cannot reach the main process's redaction configuration —
+so the only safe place to redact is at the boundary, where the
+main-side server holds the policy and can normalise records before they
+hit the sink. This module is the seam where that happens.
+
+The module also ships a small `maskKeys` helper that produces a redactor
+for the common case (mask a fixed list of top-level keys with a
+replacement string). Callers that need richer policy — nested matching,
+prefix patterns, length-preserving masks — wire `@suaveplan/logger`'s
+redactor through the `Redactor` structural type.
+
+## Features
+
+- `applyRedactionPassthrough(record, opts)` — pure function returning a
+  new {@link WireLogRecord} with `ctx` and/or `msg` rewritten.
+- `Redactor<T>(value: T): T` — structural type matching
+  `@suaveplan/logger`'s redactor surface; passes any record-shaped
+  value through the policy.
+- `maskKeys(keys, replacement?)` — built-in fixed-key redactor.
+
+## Usage: Basic
+
+```ts
+import {
+    applyRedactionPassthrough,
+    maskKeys,
+} from "@suaveplan/api-logger-worker-proxy/redaction-passthrough";
+
+const redact = maskKeys(["password", "token"]);
+const safe = applyRedactionPassthrough(record, { ctxRedactor: redact });
+mainLogger.info(safe.msg, safe.ctx);
+```
+
+## Usage: Advanced
+
+Combine with a message-level scrubber for free-form text:
+
+```ts
+import { applyRedactionPassthrough } from "@suaveplan/api-logger-worker-proxy/redaction-passthrough";
+
+const safe = applyRedactionPassthrough(record, {
+    ctxRedactor: hostLoggerRedactor, // from @suaveplan/logger
+    msgRedactor: (msg) => msg.replace(/\b\d{16}\b/g, "[CARD]"),
+});
+```
+
+## API Reference
+
+- `applyRedactionPassthrough(record, options)` — returns a redacted
+  clone. If `record.ctx` is undefined the ctx redactor is a no-op for
+  that record. If no redactors are configured the original record is
+  returned by reference (zero allocations).
+- `maskKeys(keys: ReadonlyArray<string>, replacement = "[REDACTED]")` —
+  builds a `Redactor`. Operates only on plain-object top-level keys.
+
+## Implementation Notes
+
+The pass-through is intentionally narrow: it does not walk arrays or
+nested objects. `@suaveplan/logger`'s full redactor handles those cases
+and is what production callers should plug in. `maskKeys` is the
+zero-config fallback so this package stays useful on its own (e.g. in
+tests, or in callers who don't take a runtime dep on the logger's
+redactor module). Input records are never mutated; a clone is produced
+when redaction actually runs.