# `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.