@vitrinka/redact 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0
+
+Initial release: the shared recorder redaction engine.
+
+- Policy-driven rule compilation (`compileRules`) with built-in safe defaults
+  mirroring the vitrinka server's ingest engine: auth-bearing header names
+  (plus the `…api-key`/`…token` suffix rule), sensitive body keys (normalized
+  matching, so `card_number` ≡ `cardNumber`), and URL parameter scrubbing for
+  query AND fragment, split on both `&` and `;`.
+- Token-based key matching on top of the defaults (`X-Dev-Auth-Secret`,
+  `otpCode`, `user_password_hash` are caught without being listed).
+- Surface transforms: `redactHeaders` (with value/budget caps), `redactBody`
+  (JSON structural with recursion guard, form-encoded, multipart/form-data,
+  truncated-JSON key fallback), `redactUrl`, `redactText`, `redactAndCap`
+  (shape-aware redact/cap ordering), `maskDirectives` (rrweb-style DOM
+  recorders), `pixelPolicy` (screenshot recorders).
+- Workspace policy extensions: `extraHeaders`, `extraBodyKeys`, `patterns`
+  (each compiled in its own try/catch; a bad pattern is skipped, never fatal),
+  `maskAllText`, `fullFidelity` passthrough.
+- Language-agnostic `spec/REDACTION-SPEC.md` + `spec/vectors.json`
+  conformance suite for ports to other recorder platforms.

package/README.md

@@ -0,0 +1,61 @@
+# @vitrinka/redact
+
+The vitrinka recorder redaction engine: safe-by-default scrubbing of
+auth-bearing headers, sensitive body keys, and URL query/fragment secrets in
+recorded sessions — extensible per workspace via the redaction policy the
+vitrinka server serves, and shared by every vitrinka capture client
+([`@vitrinka/expo`](../expo) and the [browser extension](../../apps/extension)).
+
+The vitrinka server applies the same policy again at ingest as the
+load-bearing backstop. This engine is defense in depth: with it, secrets never
+leave the device at all, and recorded payloads are smaller on the wire.
+
+## Usage
+
+```ts
+import {
+  compileRules,
+  redactHeaders,
+  redactBody,
+  redactUrl,
+  redactAndCap,
+  maskDirectives,
+  pixelPolicy,
+} from '@vitrinka/redact';
+
+// Fetch the workspace policy at session start (GET /api/v1/recorder/policy).
+// FAIL CLOSED: on any failure, compile null — the built-in safe defaults.
+const rules = compileRules(policyOrNull);
+
+redactHeaders(rules, { Authorization: 'Bearer …' });
+//  → { Authorization: '[redacted]' }
+
+redactBody(rules, '{"password":"hunter2"}', 'application/json');
+//  → '{"password":"[redacted]"}'
+
+redactUrl(rules, 'https://app.example.com/cb#access_token=…');
+//  → 'https://app.example.com/cb#access_token=[redacted]'
+
+redactAndCap(rules, body, 64 * 1024, contentType); // redact-then-cap, shape-aware
+
+maskDirectives(rules); // rrweb-style DOM recorders: maskAllInputs/maskAllText
+pixelPolicy(rules);    // screenshot recorders: 'none' | 'blur'
+```
+
+`compileRules` caches by policy identity — call it per event for free.
+`fullFidelity: true` in the policy (the self-host escape hatch, env-gated
+server-side) turns every transform into a pass-through; clients only honor
+the field, never default to it.
+
+## Porting to other platforms
+
+The engine is specified language-agnostically in
+[`spec/REDACTION-SPEC.md`](spec/REDACTION-SPEC.md), with a portable
+conformance suite in [`spec/vectors.json`](spec/vectors.json) (ported from the
+server engine's table tests). A recorder for any UI technology — Flutter,
+native iOS/Android, desktop — implements the spec's surface transforms and
+must pass every vector. This TypeScript implementation is the reference.
+
+## License
+
+[Elastic License 2.0](../../LICENSE).

package/build/iife.d.ts

@@ -0,0 +1,10 @@
+/**
+ * IIFE entry for build-free consumers (the browser extension's service worker
+ * loads the built file via importScripts). Attaches the whole engine as
+ * `globalThis.VitrinkaRedact`. Built with `bun run build:iife`; the extension
+ * checks the artifact in and CI diffs it against a fresh build.
+ */
+import * as engine from './index';
+declare global {
+    var VitrinkaRedact: typeof engine;
+}

package/build/iife.js

@@ -0,0 +1,8 @@
+/**
+ * IIFE entry for build-free consumers (the browser extension's service worker
+ * loads the built file via importScripts). Attaches the whole engine as
+ * `globalThis.VitrinkaRedact`. Built with `bun run build:iife`; the extension
+ * checks the artifact in and CI diffs it against a fresh build.
+ */
+import * as engine from './index';
+globalThis.VitrinkaRedact = engine;

package/build/index.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @vitrinka/redact — the recorder redaction engine.
+ *
+ * Safe-by-default, capture-side scrubbing of auth-bearing headers, sensitive
+ * body keys, and URL query/fragment secrets, extensible per workspace via the
+ * redaction policy the vitrinka server serves at
+ * `GET /api/v1/recorder/policy`. The server re-applies the same policy at
+ * ingest (its `internal/redact` engine) as the load-bearing backstop — this
+ * engine is defense in depth: secrets never transit, stored payloads shrink.
+ *
+ * The engine is a PLATFORM, not a client: it owns no I/O and no capture. A
+ * recorder (browser extension, Expo, or a future Flutter/Swift/Kotlin port)
+ * compiles the policy into a {@link RuleSet} once, then routes each capture
+ * surface through the matching transform:
+ *
+ *   headers     → {@link redactHeaders}
+ *   bodies      → {@link redactBody} / {@link redactAndCap}
+ *   URLs        → {@link redactUrl}
+ *   free text   → {@link redactText}
+ *   DOM capture → {@link maskDirectives}   (rrweb-style recorders)
+ *   pixels      → {@link pixelPolicy}      (screenshot recorders)
+ *
+ * Conformance is defined by `spec/REDACTION-SPEC.md` + `spec/vectors.json`
+ * (ported from the server engine's table tests): any implementation, in any
+ * language, must pass the vectors. This TS implementation is the reference.
+ *
+ * Matching is DELIBERATELY a superset of the server's: the server matches
+ * normalized names (lowercase, `-`/`_` stripped) against its default sets;
+ * this engine additionally token-matches key names (so `X-Dev-Auth-Secret`,
+ * `otpCode` and `user_password_hash` hit without being listed). Over-redacting
+ * a value the server would keep is acceptable; the reverse is not.
+ *
+ * FAIL CLOSED: `compileRules(null)` is the full default rule set. A client
+ * whose policy fetch fails must use it — never capture-everything. Only an
+ * explicit `fullFidelity: true` from the server (self-host escape hatch,
+ * env-gated there) disables scrubbing.
+ */
+/** Replaces every scrubbed value — a marker, not "", so a replayed session
+ * still shows that a header/field WAS present. */
+export declare const REDACTED = "[redacted]";
+/**
+ * The workspace-configurable redaction policy, exactly as the server serves
+ * it. The zero/absent policy is the safe default.
+ */
+export interface RedactionPolicy {
+    /** Additional header names whose values are scrubbed. */
+    extraHeaders?: string[];
+    /** Additional JSON/form body keys to scrub recursively. */
+    extraBodyKeys?: string[];
+    /**
+     * Extra regex patterns; every match in recorded string values is replaced.
+     * The server pre-filters these to a backtracking-safe subset before serving
+     * them to clients; each is still compiled in its own try/catch here.
+     */
+    patterns?: string[];
+    /** Mask ALL text in DOM recordings; screenshot recorders degrade pixels. */
+    maskAllText?: boolean;
+    /**
+     * Disables redaction entirely — the self-host escape hatch. Only ever
+     * honored when the server explicitly served it; clients never default to it.
+     */
+    fullFidelity?: boolean;
+}
+/** A compiled policy — build once per policy via {@link compileRules}. */
+export interface RuleSet {
+    readonly full: boolean;
+    readonly maskAllText: boolean;
+    /** Normalized header names (defaults + policy extras). */
+    readonly headers: ReadonlySet<string>;
+    /** Normalized body-key names (defaults + policy extras). */
+    readonly bodyKeys: ReadonlySet<string>;
+    readonly patterns: readonly RegExp[];
+}
+/** Canonicalize a header/body-key name: lowercase, `-` and `_` removed. */
+export declare function norm(s: string): string;
+/**
+ * Compile a policy (or null/undefined = the safe defaults) into a RuleSet.
+ * Cached by policy identity, so calling per event is free. Bad regexes are
+ * skipped individually — the server backstop still applies them at ingest.
+ */
+export declare function compileRules(policy?: RedactionPolicy | null): RuleSet;
+/**
+ * Token-wise secret detection: TOKEN matching, not substring, so `author`,
+ * `authorId`, `shippingAddress` and `pinned` stay intact while
+ * `Authorization`, `accessToken` and `X-Dev-Auth-Secret` are caught.
+ */
+export declare function isSecretKey(key: string): boolean;
+/**
+ * Is this header's value scrubbed? Listed (defaults + policy), an
+ * api-key/token-suffixed variant (the server's suffix rule), or token-secret.
+ */
+export declare function sensitiveHeader(rules: RuleSet, name: string): boolean;
+/** Is this JSON/form key's value scrubbed? Listed (normalized) or token-secret. */
+export declare function sensitiveBodyKey(rules: RuleSet, name: string): boolean;
+/**
+ * Is this URL query/fragment parameter's value scrubbed? Every sensitive body
+ * key, plus the api-key/token suffix rule (?access_token=…, ?sas_token=…).
+ */
+export declare function sensitiveParam(rules: RuleSet, name: string): boolean;
+/**
+ * Redact sensitive-keyed pairs in one raw query/fragment/form string,
+ * splitting on BOTH separators (`&` and `;`). Never URLSearchParams (it
+ * treats `;` as a literal, hiding a trailing `;access_token=…` inside the
+ * previous value) and never the platform URL parser (React Native's is
+ * incomplete). A pair with a benign name still loses its value when the
+ * DECODED value carries an embedded secret pair (`?next=%2Fcb%3Ftoken%3D…`).
+ * A fully benign string comes back byte-identical.
+ */
+export declare function scrubPairs(rules: RuleSet, sensitive: (rules: RuleSet, name: string) => boolean, raw: string): string;
+/**
+ * Redact sensitive query/fragment parameter values in one URL — OAuth/OIDC
+ * callbacks (?access_token=…), magic links (?token=…), SAS URLs. The fragment
+ * scrubs too (implicit-grant OAuth returns tokens as `#access_token=…`).
+ * String-split rather than URL-parsed: React Native's URL is incomplete, and
+ * an unparseable URL must never be a free pass. Benign URLs pass through
+ * byte-identical; the extra patterns run over the result.
+ */
+export declare function redactUrl(rules: RuleSet, raw: string): string;
+/**
+ * Scrub one request/response body. JSON parses + scrubs recursively (shape
+ * preserved so a timeline still shows which fields were sent); a JSON-looking
+ * body that fails to parse — or is too big to parse safely — gets the
+ * key-pair fallback; form-encoded and multipart bodies scrub key-wise;
+ * anything else gets the free-text scanner + patterns. Never throws — capture
+ * must not break the recorded app.
+ */
+export declare function redactBody(rules: RuleSet, body: string, contentType?: string): string;
+/**
+ * Redact a free-text capture (console line, unknown-shape body, URL-bearing
+ * log). JSON is walked structurally; anything else gets the text scanner.
+ * Never throws.
+ */
+export declare function redactText(rules: RuleSet, text: string | undefined): string | undefined;
+/**
+ * Redact, then cap to `cap` characters — with the ORDER chosen by shape:
+ * JSON redacts WHOLE then caps (capping first would slice it into invalid
+ * JSON, downgrading exactly the payloads most likely to carry credentials);
+ * anything else caps first (slicing text is harmless and bounds masking
+ * cost), then the truncation fallback still guards the sliced tail.
+ */
+export declare function redactAndCap(rules: RuleSet, body: string, cap: number, contentType?: string): string | undefined;
+/** Size caps for a captured header map (one giant cookie must not bloat events). */
+export interface HeaderCaps {
+    /** Max characters kept of one header value (default 1024). */
+    maxValueLen?: number;
+    /** Total budget in characters across the whole map (default 8192). */
+    budget?: number;
+}
+/**
+ * Scrub + cap a captured header map: sensitive names lose their value, the
+ * rest pass the extra patterns; values are bounded individually and by a
+ * total budget (the map gains a `…: (truncated)` marker when it overflows).
+ */
+export declare function redactHeaders(rules: RuleSet, headers: Record<string, unknown> | undefined | null, caps?: HeaderCaps): Record<string, string> | undefined;
+/** rrweb-style DOM-capture masking options derived from the rules. */
+export interface MaskDirectives {
+    /** Fail-closed default: input VALUES are always masked unless fullFidelity. */
+    maskAllInputs: boolean;
+    /** Mask every text node (policy `maskAllText`). */
+    maskAllText: boolean;
+    /** Older rrweb spelling of maskAllText; set to `*` when it applies. */
+    maskTextSelector?: string;
+}
+/** DOM-capture masking for rrweb-style recorders. */
+export declare function maskDirectives(rules: RuleSet): MaskDirectives;
+/**
+ * What a PIXEL capture surface (screenshots — real rendered text, no DOM to
+ * mask) must do under these rules: `blur` = degrade resolution until text is
+ * unreadable while layout survives; `none` = capture normally.
+ */
+export declare function pixelPolicy(rules: RuleSet): 'none' | 'blur';