@glubean/redaction 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,158 @@
+# @glubean/redaction
+
+Scope-based secrets/PII detection and masking for [Glubean](https://glubean.dev).
+
+## Overview
+
+Redaction v2 uses a data-driven scope model. Scopes declare **what** to redact (event type + field path + rules). Handlers declare **how** to interpret payloads (JSON, headers, URL query strings). Plugins provide detection logic (sensitive keys, value patterns).
+
+All scope declarations — built-in HTTP, gRPC, or any future protocol — use the same shape. No hardcoded protocol knowledge in the redaction package.
+
+## Quick Start
+
+```ts
+import {
+  compileScopes,
+  redactEvent,
+  BUILTIN_SCOPES,
+  DEFAULT_GLOBAL_RULES,
+} from "@glubean/redaction";
+
+// Compile scopes once at startup
+const scopes = compileScopes({
+  builtinScopes: BUILTIN_SCOPES,
+  globalRules: DEFAULT_GLOBAL_RULES,
+  replacementFormat: "partial",
+});
+
+// Redact events
+const event = {
+  type: "trace",
+  data: {
+    requestHeaders: { authorization: "Bearer secret-token" },
+    requestBody: { password: "hunter2", username: "alice" },
+  },
+};
+
+const redacted = redactEvent(event, scopes, "partial");
+// redacted.data.requestHeaders.authorization → "Bea***123"
+// redacted.data.requestBody.password → "hun***er2"
+// redacted.data.requestBody.username → "alice" (not sensitive)
+```
+
+## Architecture
+
+```
+scope declarations (built-in + plugins + user overrides)
+  → compile to CompiledScope[]
+    → redactEvent(event, compiledScopes)
+      → for each matching scope:
+        1. extract target value via field path
+        2. run the scope's handler
+        3. handler calls engine with per-scope plugin pipeline
+        4. write redacted value back
+```
+
+### Scopes
+
+A scope declares where to redact and what rules apply:
+
+```ts
+{
+  id: "http.request.headers",
+  name: "HTTP request headers",
+  event: "trace",
+  target: "data.requestHeaders",
+  handler: "headers",
+  rules: {
+    sensitiveKeys: ["authorization", "cookie"],
+  },
+}
+```
+
+- `id` — stable config key for user overrides
+- `event` — which event type to match
+- `target` — dot-path to the payload field
+- `handler` — which handler interprets the payload
+- `rules` — scope-specific sensitive keys and patterns
+
+### Handlers
+
+Built-in handlers:
+
+| Handler | Purpose |
+|---------|---------|
+| `json` | Recursive JSON object/array walker |
+| `raw-string` | Value-pattern matching on plain strings |
+| `url-query` | Parse URL, redact query params, serialize back |
+| `headers` | Header map with cookie/set-cookie parsing |
+
+### Plugins
+
+Detection plugins (unchanged from v1):
+
+- **sensitive-keys** — key-level substring matching
+- **jwt** — JWT token detection
+- **bearer** — Bearer token detection
+- **awsKeys** — AWS access key ID
+- **githubTokens** — GitHub PAT tokens
+- **email** — Email address detection
+- **ipAddress** — IPv4 address detection
+- **creditCard** — Credit card number detection
+- **hexKeys** — Hex key detection (32+ chars)
+
+## Plugin Integration
+
+Plugins declare their own redaction scopes via `PluginFactory.redaction`:
+
+```ts
+// gRPC plugin
+grpc({
+  proto: "./protos/users.proto",
+  address: "{{ADDR}}",
+  package: "acme.users.v1",
+  service: "UsersService",
+});
+
+// Plugin internally declares:
+// redaction: [
+//   { id: "grpc.metadata", handler: "headers", rules: { sensitiveKeys: ["authorization"] } },
+//   { id: "grpc.request",  handler: "json" },
+//   { id: "grpc.response", handler: "json" },
+// ]
+```
+
+The runner collects all plugin declarations and merges them with built-in scopes at compile time.
+
+## User Overrides
+
+Users override scopes by stable `id` in `.glubean/redact.json`:
+
+```json
+{
+  "scopes": {
+    "grpc.metadata": { "enabled": false },
+    "http.request.headers": {
+      "rules": { "sensitiveKeys": ["x-custom-secret"] }
+    }
+  },
+  "globalRules": {
+    "sensitiveKeys": ["my-internal-key"],
+    "customPatterns": [
+      { "name": "internal-id", "regex": "INT-[A-Z0-9]{8}" }
+    ]
+  }
+}
+```
+
+## Replacement Formats
+
+| Format | Example |
+|--------|---------|
+| `simple` | `[REDACTED]` |
+| `labeled` | `[REDACTED:sensitive-keys]` |
+| `partial` | `Bea***123` (smart masking) |
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -1,41 +1,29 @@
 /**
  * @module adapter
  *
- * Scope adapter — maps ExecutionEvent types to redaction scopes.
+ * Generic event redaction dispatcher.
  *
- * Without this adapter, the engine's scope toggles are decorative.
- * This function dispatches each event's payload fields to the correct
- * scope so the engine can gate redaction per-scope.
- *
- * Both the CLI (for --share) and the server (for event ingestion) use
- * this adapter. The server adapter may handle additional premium scopes.
+ * v2 replaces the hardcoded event-type switch with a data-driven dispatcher
+ * that uses compiled scopes to find matching scopes, extract targets,
+ * and apply handlers.
  */
-import type { RedactionEngine } from "./engine.js";
-import type { RedactionConfig } from "./types.js";
+import type { CompiledScope } from "./types.js";
 /**
- * A generic event shape compatible with both ExecutionEvent (oss runner)
- * and RunEvent (server). The adapter only reads `type` and mutates payload
- * fields in-place on a clone.
+ * A generic event shape. The dispatcher only reads `type` and mutates
+ * payload fields on a clone based on compiled scope declarations.
  */
 export interface RedactableEvent {
     type: string;
     [key: string]: unknown;
 }
 /**
- * Redact an event by dispatching its payload fields to the appropriate
- * scopes. Returns a new event object — the original is not mutated.
- *
- * Scope mapping:
- * - trace → requestHeaders, requestQuery, requestBody, responseHeaders, responseBody
- * - log → consoleOutput
- * - assertion → errorMessages
- * - error / status → errorMessages
- * - warning / schema_validation → errorMessages
- * - step_end → returnState
- * - metric, step_start, start, summary → no redaction
+ * Redact an event by dispatching its payload fields to matching scopes.
+ * Returns a new event object — the original is not mutated.
  *
- * @example
- * const redacted = redactEvent(engine, { type: "trace", data: { ... } });
+ * @param event  The event to redact.
+ * @param scopes Pre-compiled scopes from compileScopes().
+ * @param replacementFormat Replacement format for engine instances.
+ * @param maxDepth Optional max object depth.
  */
-export declare function redactEvent<C extends RedactionConfig>(engine: RedactionEngine<C>, event: RedactableEvent): RedactableEvent;
+export declare function redactEvent(event: RedactableEvent, scopes: CompiledScope[], replacementFormat?: "simple" | "labeled" | "partial", maxDepth?: number): RedactableEvent;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,eAAe,EACnD,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,eAAe,GACrB,eAAe,CAgIjB"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAmC,MAAM,YAAY,CAAC;AAGjF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,aAAa,EAAE,EACvB,iBAAiB,GAAE,QAAQ,GAAG,SAAS,GAAG,SAAqB,EAC/D,QAAQ,CAAC,EAAE,MAAM,GAChB,eAAe,CA0BjB"}

package/dist/adapter.js

@@ -1,110 +1,40 @@
 /**
  * @module adapter
  *
- * Scope adapter — maps ExecutionEvent types to redaction scopes.
+ * Generic event redaction dispatcher.
  *
- * Without this adapter, the engine's scope toggles are decorative.
- * This function dispatches each event's payload fields to the correct
- * scope so the engine can gate redaction per-scope.
- *
- * Both the CLI (for --share) and the server (for event ingestion) use
- * this adapter. The server adapter may handle additional premium scopes.
+ * v2 replaces the hardcoded event-type switch with a data-driven dispatcher
+ * that uses compiled scopes to find matching scopes, extract targets,
+ * and apply handlers.
  */
+import { createScopeEngine } from "./compiler.js";
 /**
- * Redact an event by dispatching its payload fields to the appropriate
- * scopes. Returns a new event object — the original is not mutated.
- *
- * Scope mapping:
- * - trace → requestHeaders, requestQuery, requestBody, responseHeaders, responseBody
- * - log → consoleOutput
- * - assertion → errorMessages
- * - error / status → errorMessages
- * - warning / schema_validation → errorMessages
- * - step_end → returnState
- * - metric, step_start, start, summary → no redaction
+ * Redact an event by dispatching its payload fields to matching scopes.
+ * Returns a new event object — the original is not mutated.
  *
- * @example
- * const redacted = redactEvent(engine, { type: "trace", data: { ... } });
+ * @param event  The event to redact.
+ * @param scopes Pre-compiled scopes from compileScopes().
+ * @param replacementFormat Replacement format for engine instances.
+ * @param maxDepth Optional max object depth.
  */
-export function redactEvent(engine, event) {
-    const t = event.type;
-    // Events that don't need redaction — return as-is
-    if (t === "metric" ||
-        t === "step_start" ||
-        t === "start" ||
-        t === "summary" ||
-        t === "timeout_update") {
+export function redactEvent(event, scopes, replacementFormat = "partial", maxDepth) {
+    // Find all enabled scopes matching this event type
+    const matching = scopes.filter((scope) => scope.enabled && scope.event === event.type);
+    if (matching.length === 0)
         return event;
-    }
-    // step_end: only needs redaction if returnState is present
-    if (t === "step_end") {
-        if (event.returnState != null) {
-            const clone = structuredClone(event);
-            clone.returnState = engine.redact(clone.returnState, "returnState").value;
-            return clone;
-        }
-        return event;
-    }
     // Clone to avoid mutating the original
     const clone = structuredClone(event);
-    if (t === "trace") {
-        // Trace events have data: ApiTrace with headers/bodies
-        const data = clone.data;
-        if (data) {
-            if (data.requestHeaders != null) {
-                data.requestHeaders = engine.redact(data.requestHeaders, "requestHeaders").value;
-            }
-            if (data.requestBody != null) {
-                data.requestBody = engine.redact(data.requestBody, "requestBody").value;
-            }
-            if (data.responseHeaders != null) {
-                data.responseHeaders = engine.redact(data.responseHeaders, "responseHeaders").value;
-            }
-            if (data.responseBody != null) {
-                data.responseBody = engine.redact(data.responseBody, "responseBody").value;
-            }
-            // URL may contain query params with secrets
-            if (typeof data.url === "string") {
-                data.url = engine.redact(data.url, "requestQuery").value;
-            }
-        }
-    }
-    else if (t === "log") {
-        if (clone.message != null) {
-            clone.message = engine.redact(clone.message, "consoleOutput").value;
-        }
-        if (clone.data != null) {
-            clone.data = engine.redact(clone.data, "consoleOutput").value;
-        }
-    }
-    else if (t === "assertion") {
-        if (clone.message != null) {
-            clone.message = engine.redact(clone.message, "errorMessages").value;
-        }
-        if (clone.actual != null) {
-            clone.actual = engine.redact(clone.actual, "errorMessages").value;
-        }
-        if (clone.expected != null) {
-            clone.expected = engine.redact(clone.expected, "errorMessages").value;
-        }
-    }
-    else if (t === "error") {
-        if (clone.message != null) {
-            clone.message = engine.redact(clone.message, "errorMessages").value;
-        }
-    }
-    else if (t === "status") {
-        if (clone.error != null) {
-            clone.error = engine.redact(clone.error, "errorMessages").value;
-        }
-        if (clone.stack != null) {
-            clone.stack = engine.redact(clone.stack, "errorMessages").value;
-        }
-    }
-    else if (t === "warning" || t === "schema_validation") {
-        if (clone.message != null) {
-            clone.message = engine.redact(clone.message, "errorMessages").value;
-        }
+    for (const scope of matching) {
+        const current = scope.get(clone);
+        if (current === undefined)
+            continue;
+        const engine = createScopeEngine(scope, replacementFormat, maxDepth);
+        const ctx = {
+            scopeId: scope.id,
+            scopeName: scope.name,
+        };
+        const result = scope.handler.process(current, ctx, engine);
+        scope.set(clone, result.value);
     }
     return clone;
 }

package/dist/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAWlD;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,KAAsB,EACtB,MAAuB,EACvB,oBAAsD,SAAS,EAC/D,QAAiB;IAEjB,mDAAmD;IACnD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAC5B,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,CACvD,CAAC;IAEF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAExC,uCAAuC;IACvC,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAErC,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QAEpC,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,CAAC,CAAC;QACrE,MAAM,GAAG,GAAmB;YAC1B,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,SAAS,EAAE,KAAK,CAAC,IAAI;SACtB,CAAC;QAEF,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;QAC3D,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/compiler.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module compiler
+ *
+ * Compiles scope declarations into ready-to-execute CompiledScope[].
+ *
+ * Flow:
+ * 1. Merge built-in + plugin scope declarations
+ * 2. Apply user overrides by scope id
+ * 3. Resolve handler for each scope
+ * 4. Build per-scope plugin pipeline (scope keys + global keys + patterns)
+ * 5. Return CompiledScope[] for use by redactEvent()
+ */
+import type { CompiledScope, GlobalRules, RedactionHandler, RedactionScopeDeclaration, ScopeRules } from "./types.js";
+import { RedactionEngine } from "./engine.js";
+/** User-provided scope overrides keyed by scope id. */
+export interface ScopeOverride {
+    enabled?: boolean;
+    rules?: ScopeRules;
+}
+/** Compiler options. */
+export interface CompilerOptions {
+    /** Built-in scope declarations (HTTP, log, error, etc.). */
+    builtinScopes: RedactionScopeDeclaration[];
+    /** Plugin-provided scope declarations. */
+    pluginScopes?: RedactionScopeDeclaration[];
+    /** Plugin-provided custom handlers. */
+    pluginHandlers?: RedactionHandler[];
+    /** User overrides by scope id. */
+    userOverrides?: Record<string, ScopeOverride>;
+    /** Global additive rules. */
+    globalRules: GlobalRules;
+    /** Replacement format. */
+    replacementFormat: "simple" | "labeled" | "partial";
+    /** Max object nesting depth. Default: 10. */
+    maxDepth?: number;
+}
+/**
+ * Compile scope declarations into ready-to-execute CompiledScope[].
+ */
+export declare function compileScopes(options: CompilerOptions): CompiledScope[];
+/**
+ * Create a scope-specific RedactionEngine instance.
+ *
+ * Each scope gets its own engine with its own plugin pipeline.
+ */
+export declare function createScopeEngine(scope: CompiledScope, replacementFormat: "simple" | "labeled" | "partial", maxDepth?: number): RedactionEngine;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EAEX,gBAAgB,EAGhB,yBAAyB,EACzB,UAAU,EACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAM9C,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,wBAAwB;AACxB,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,aAAa,EAAE,yBAAyB,EAAE,CAAC;IAC3C,0CAA0C;IAC1C,YAAY,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAC3C,uCAAuC;IACvC,cAAc,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACpC,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,6BAA6B;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,0BAA0B;IAC1B,iBAAiB,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACpD,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA4GD;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa,EAAE,CA4DvE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,EACpB,iBAAiB,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,EACnD,QAAQ,CAAC,EAAE,MAAM,GAChB,eAAe,CAMjB"}

package/dist/compiler.js

@@ -0,0 +1,178 @@
+/**
+ * @module compiler
+ *
+ * Compiles scope declarations into ready-to-execute CompiledScope[].
+ *
+ * Flow:
+ * 1. Merge built-in + plugin scope declarations
+ * 2. Apply user overrides by scope id
+ * 3. Resolve handler for each scope
+ * 4. Build per-scope plugin pipeline (scope keys + global keys + patterns)
+ * 5. Return CompiledScope[] for use by redactEvent()
+ */
+import { RedactionEngine } from "./engine.js";
+import { BUILTIN_HANDLERS } from "./handlers.js";
+import { sensitiveKeysPlugin } from "./plugins/sensitive-keys.js";
+import { createPatternPlugins } from "./plugins/mod.js";
+/**
+ * Resolve field path accessor functions.
+ *
+ * Supports dot-separated paths (e.g., "data.requestHeaders")
+ * and "$self" for the whole event.
+ */
+function makeAccessors(target) {
+    if (target === "$self") {
+        return {
+            get: (event) => event,
+            set: (event, value) => {
+                // $self: merge redacted properties back onto the event
+                if (value && typeof value === "object" && !Array.isArray(value)) {
+                    const redacted = value;
+                    for (const key of Object.keys(redacted)) {
+                        event[key] = redacted[key];
+                    }
+                }
+            },
+        };
+    }
+    const parts = target.split(".");
+    return {
+        get(event) {
+            let current = event;
+            for (const part of parts) {
+                if (current == null || typeof current !== "object")
+                    return undefined;
+                current = current[part];
+            }
+            return current;
+        },
+        set(event, value) {
+            let current = event;
+            for (let i = 0; i < parts.length - 1; i++) {
+                const next = current[parts[i]];
+                if (next == null || typeof next !== "object")
+                    return;
+                current = next;
+            }
+            current[parts[parts.length - 1]] = value;
+        },
+    };
+}
+/**
+ * Build the plugin pipeline for a specific scope.
+ *
+ * Order:
+ * 1. Sensitive keys plugin (scope-specific + global additive keys)
+ * 2. Pattern plugins (scope-specific + global patterns)
+ * 3. Custom patterns from global rules
+ */
+function buildScopePlugins(scopeRules, globalRules) {
+    const plugins = [];
+    // Merge sensitive keys: scope-specific + global
+    const allKeys = new Set();
+    if (scopeRules?.sensitiveKeys) {
+        for (const k of scopeRules.sensitiveKeys)
+            allKeys.add(k.toLowerCase());
+    }
+    for (const k of globalRules.sensitiveKeys)
+        allKeys.add(k.toLowerCase());
+    if (allKeys.size > 0) {
+        plugins.push(sensitiveKeysPlugin({
+            useBuiltIn: false,
+            additional: [...allKeys],
+            excluded: [],
+        }));
+    }
+    // Merge pattern names: scope-specific + global
+    const enabledPatterns = new Set();
+    if (scopeRules?.patterns) {
+        for (const p of scopeRules.patterns)
+            enabledPatterns.add(p);
+    }
+    for (const p of globalRules.patterns)
+        enabledPatterns.add(p);
+    // Add pattern plugins for enabled patterns
+    const patternPlugins = createPatternPlugins(enabledPatterns);
+    plugins.push(...patternPlugins);
+    // Add custom patterns from global rules
+    for (const custom of globalRules.customPatterns) {
+        try {
+            new RegExp(custom.regex, "g");
+            plugins.push({
+                name: custom.name,
+                matchValue: () => new RegExp(custom.regex, "g"),
+            });
+        }
+        catch {
+            // Skip invalid regex
+        }
+    }
+    return plugins;
+}
+/**
+ * Compile scope declarations into ready-to-execute CompiledScope[].
+ */
+export function compileScopes(options) {
+    // Merge all scope declarations
+    const allDeclarations = [
+        ...options.builtinScopes,
+        ...(options.pluginScopes ?? []),
+    ];
+    // Build handler registry
+    const handlers = { ...BUILTIN_HANDLERS };
+    if (options.pluginHandlers) {
+        for (const h of options.pluginHandlers) {
+            handlers[h.name] = h;
+        }
+    }
+    // Compile each scope
+    const compiled = [];
+    for (const decl of allDeclarations) {
+        // Apply user overrides
+        const override = options.userOverrides?.[decl.id];
+        const enabled = override?.enabled ?? true;
+        const rules = {
+            sensitiveKeys: [
+                ...(decl.rules?.sensitiveKeys ?? []),
+                ...(override?.rules?.sensitiveKeys ?? []),
+            ],
+            patterns: [
+                ...(decl.rules?.patterns ?? []),
+                ...(override?.rules?.patterns ?? []),
+            ],
+        };
+        // Resolve handler
+        const handler = handlers[decl.handler];
+        if (!handler) {
+            throw new Error(`Redaction scope "${decl.id}" references unknown handler "${decl.handler}"`);
+        }
+        // Build per-scope plugin pipeline
+        const plugins = buildScopePlugins(rules, options.globalRules);
+        // Build field accessors
+        const accessors = makeAccessors(decl.target);
+        compiled.push({
+            id: decl.id,
+            name: decl.name,
+            event: decl.event,
+            enabled,
+            get: accessors.get,
+            set: accessors.set,
+            handler,
+            plugins,
+        });
+    }
+    return compiled;
+}
+/**
+ * Create a scope-specific RedactionEngine instance.
+ *
+ * Each scope gets its own engine with its own plugin pipeline.
+ */
+export function createScopeEngine(scope, replacementFormat, maxDepth) {
+    return new RedactionEngine({
+        plugins: scope.plugins,
+        replacementFormat,
+        maxDepth,
+    });
+}
+//# sourceMappingURL=compiler.js.map

package/dist/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"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"}

package/dist/defaults.d.ts

@@ -1,29 +1,39 @@
 /**
  * @module defaults
  *
- * Built-in sensitive keys, pattern source strings, and the default
- * redaction configuration used as the mandatory baseline for --share.
+ * Built-in scope declarations, pattern source strings, and default config.
+ *
+ * v2: HTTP scopes are declared as data, not as a fixed interface.
+ * They use the same shape as external plugin declarations.
  */
-import type { RedactionConfig } from "./types.js";
+import type { GlobalRules, RedactionConfig, RedactionScopeDeclaration } from "./types.js";
 /**
- * Keys whose values are always redacted when matched (case-insensitive
- * substring match). Ported from glubean-v1 RedactionService for parity.
+ * Built-in scope declarations for HTTP, log, error, assertion, and step events.
+ *
+ * These are the "http-plugin" built-in contributor — they use the same
+ * declaration model as any external plugin.
  */
-export declare const BUILT_IN_SENSITIVE_KEYS: readonly string[];
+export declare const BUILTIN_SCOPES: RedactionScopeDeclaration[];
 /**
  * Regex source strings for built-in value-level patterns.
- * Plugins create new RegExp instances from these on each call
- * to avoid stale lastIndex state.
+ * Plugins create new RegExp instances from these on each call.
  */
 export declare const PATTERN_SOURCES: Record<string, {
     source: string;
     flags: string;
 }>;
 /**
- * The mandatory baseline configuration for --share.
+ * Default global additive rules.
+ *
+ * These are intentionally minimal — most sensitive keys now live
+ * in scope-specific declarations, not in globals.
+ */
+export declare const DEFAULT_GLOBAL_RULES: GlobalRules;
+/**
+ * Default redaction config v2.
  *
- * All scopes on, all patterns on, useBuiltIn keys, simple replacement.
- * User .glubean/redact.json can only add rules on top — never weaken this.
+ * All built-in scopes enabled, all patterns enabled globally,
+ * scope-specific sensitive keys declared per scope.
  */
 export declare const DEFAULT_CONFIG: RedactionConfig;
 //# sourceMappingURL=defaults.d.ts.map