Initial Commit

packages/api-stack/api/api-secrets-worker-proxy/src/redaction/redaction.md

@@ -0,0 +1,75 @@
+# `redaction`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Re-exports the canonical `<redacted>` marker and `redactSecret` helper
+from `@suaveplan/api-secrets`, plus an additional `redactSecretLine`
+worker-side paranoid helper that scrubs values out of arbitrary log
+lines. The redaction surface is duplicated here so worker code under
+sandbox isolation can scrub its log pipe without taking a direct
+dependency on `@suaveplan/api-secrets` (which transitively pulls in the
+canonical Zod schemas it does not need). Logging is the most common
+secret-leak path and an explicit, documented helper at the proxy
+package boundary is a defence-in-depth measure.
+
+## Features
+
+- `REDACTED_MARKER` — the literal `"<redacted>"` token every sink
+  in the stack grep-matches.
+- `redactSecret(value)` — replaces any secret string with the marker,
+  intentionally ignoring contents so empty-vs-set distinctions cannot
+  leak through observation.
+- `redactSecretLine(line, name)` — finds `name = value` or
+  `name: value` patterns in the supplied line and replaces the value
+  with the marker, preserving the name so an operator can still tell
+  which secret was logged.
+
+## Usage: Basic
+
+```ts
+import {
+    REDACTED_MARKER,
+    redactSecret,
+    redactSecretLine,
+} from "@suaveplan/api-secrets-worker-proxy/redaction";
+
+const masked = redactSecret(value); // "<redacted>"
+const scrubbed = redactSecretLine(
+    "STRIPE_KEY=sk_live_abc loaded",
+    "STRIPE_KEY"
+); // "STRIPE_KEY=<redacted> loaded"
+```
+
+## Usage: Advanced
+
+```ts
+import { redactSecretLine } from "@suaveplan/api-secrets-worker-proxy/redaction";
+
+function scrubAll(line: string, names: readonly string[]): string {
+    return names.reduce(
+        (acc, name) => redactSecretLine(acc, name),
+        line
+    );
+}
+
+logger.info(scrubAll(rawLine, manifest.secrets.map((d) => d.name)));
+```
+
+## API Reference
+
+- `REDACTED_MARKER: "<redacted>"` — canonical token.
+- `redactSecret(value: string): "<redacted>"` — returns the marker.
+- `redactSecretLine(line: string, name: string): string` — name-aware line scrub.
+
+## Implementation Notes
+
+- Regex meta-characters in the supplied name are escaped before
+  compilation so callers can safely pass names containing `.` or `$`.
+- An empty `name` is a no-op so callers can unconditionally invoke
+  the helper without a guard.
+- The value-shape pattern after the delimiter is `\S+` (conservative);
+  callers needing multi-token values should pre-tokenise.