repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(leaks): persist authenticated session mappings

9787e990a8d0a6bb7d66e50dce341b6bfc1460e8

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (13)

extensions/leaks/SPEC.md

Modified
38 38 Bound learned exact values and restorable placeholder mappings to 8192 each.
39 39 Bound deep traversal by object identity and depth 64.
40 40 On learned-value cap overflow, stop learning new dotenv/env exact values and warn once.
41 -Phase 1 retains the volatile HMAC12 mapping format.
42 -Durable V1 mappings are deferred to Phase 2.
43 -Until Phase 2 lands, mapping-cap behavior remains unchanged.
41 +Every emitted placeholder must have an authenticated active-generation mapping appended before provider use.
42 +Mapping, collision, capacity, encryption, or append failure leaves the original value visible and warns.
45 44 `leaks` must tolerate faulty user input.
46 45 The only planned user input is the `regex` setting.
63 62 ## Core model
65 64 Provider sees placeholders.
66 -Local Pi keeps placeholder mappings in memory only.
67 -Mappings must never be persisted to session files, logs, settings, or disk.
68 -Reload, new session, process exit, and `/leaks clear` may make old placeholders unrestorable.
65 +Pi persists a random generation root key and AES-256-GCM encrypted mapping records as custom session entries.
66 +The root key and ciphertext are co-located obfuscation and context isolation, not encryption at rest.
67 +State reconstruction uses only the active branch from `getBranch()`.
69 68 Local restoration may happen for tool args and final assistant messages.
69 +Unknown placeholders block every tool.
70 70 Placeholders are local capabilities.
71 71 Normal Pi workflows must keep working locally when placeholders are copied or moved exactly.
73 73 Placeholder format:
75 75 ```text
76 -__LEAK_<TAG>[_<TAG>...]_<HMAC12>[_N]__
76 +__LEAK_V1_<TAG>[_<TAG>...]_<HMAC32>__
79 -`HMAC12` is the first 12 lowercase hex chars of an HMAC over the secret value.
80 -The HMAC key is random, in-memory, and never persisted.
81 -`_N` is used only to resolve an actual placeholder collision inside the current mapping table.
79 +`HMAC32` is the first 16 HMAC-SHA-256 bytes encoded as 32 lowercase hexadecimal characters.
80 +The generation root key derives separate HMAC and AES-GCM keys with HKDF.
81 +Collisions never gain suffixes; the colliding value remains visible and warns.
83 83 Tags preserve metadata.
84 84 Secret values stay hidden.
96 96 The same secret value must keep one stable placeholder once first seen and stored.
97 97 Tags do not evolve after first mapping.
98 98 This avoids confusing the model with multiple placeholders for one secret.
99 -Non-restorable overflow placeholders are exempt from stability.
100 99 When multiple tags are available for the same secret span on first mapping, order them by semantic priority:
102 101 1. dotenv key name or `ENV_KEY`
121 120 Examples:
123 122 ```text
124 -__LEAK_STRIPE_LIVE_SECRET_KEY_STRIPE_TOKEN_8f31aa77c901__
125 -__LEAK_OPENROUTER_API_KEY_OPENROUTER_TOKEN_41c0e9aa1204__
126 -__LEAK_DATABASE_URL_DB_PASSWORD_POSTGRES_URL_ba29d4ff8810__
123 +__LEAK_V1_STRIPE_LIVE_SECRET_KEY_STRIPE_TOKEN_8f31aa77c90129a76d253a748660f5b7__
124 +__LEAK_V1_OPENROUTER_API_KEY_OPENROUTER_TOKEN_41c0e9aa1204a7342836516dc01b9490__
125 +__LEAK_V1_DATABASE_URL_DB_PASSWORD_POSTGRES_URL_ba29d4ff8810c412e1341ef2839572aa__
129 128 Do not encode secret length, alphabet, prefix bytes, suffix bytes, entropy, or shape.
137 136 Use these Pi hooks:
139 -- `session_start`: initialize settings, dotenv/env learning, status
138 +- `session_start`: rebuild the active generation, initialize settings and learning, update status
139 +- `session_tree`: rebuild from the newly active branch
140 140 - `context`: redact message copies opportunistically
141 -- `before_provider_request`: redact final provider payload authoritatively
142 -- `tool_call`: restore placeholders in tool args before local execution
141 +- `before_provider_request`: persist mappings, then redact final provider payload authoritatively
142 +- `tool_call`: hydrate known placeholders and block unknown or incompletely inspected input
143 143 - `message_end`: restore placeholders in finalized local assistant messages
145 -Do not persist mappings with `appendEntry`.
145 +Persist generations and encrypted mappings with `appendEntry`.
146 146 Do not register tools.
147 147 Use one slash command: `/leaks`.

extensions/leaks/__fuzz__/lifecycle.fuzz.test.ts

Added
new file mode 100644
1 +import { fc, test } from "@fast-check/vitest";
2 +import { expect } from "vitest";
3 +import { __test } from "../index.ts";
4 +import type { PersistedEntry } from "../src/placeholders.ts";
6 +const base = { numRuns: 500 };
7 +const operation = fc.oneof(
8 + fc.constant({ kind: "clear" } as const),
9 + fc.record({
10 + kind: fc.constant("add" as const),
11 + id: fc.integer({ min: 0, max: 40 }),
12 + }),
13 +);
15 +test.prop(
16 + { operations: fc.array(operation, { minLength: 1, maxLength: 100 }) },
17 + base,
18 +)("reconstructs only the modeled active generation", ({ operations }) => {
19 + const entries: PersistedEntry[] = [];
20 + const append = (customType: string, data: unknown) =>
21 + entries.push({ type: "custom" as const, customType, data });
22 + const store = new __test.PlaceholderStore();
23 + store.configure(entries, append);
24 + const active = new Map<string, string>();
25 + const inactive = new Map<string, string>();
26 + for (const item of operations) {
27 + if (item.kind === "clear") {
28 + for (const entry of active) inactive.set(...entry);
29 + active.clear();
30 + store.clear();
31 + continue;
32 + }
33 + const value = `lifecycle-fixture-${item.id}-ordinary`;
34 + const placeholder = store.create(value, [
35 + { tag: "TOKEN", priority: 10, source: "custom" },
36 + ]);
37 + if (placeholder) active.set(placeholder, value);
38 + }
39 + const resumed = new __test.PlaceholderStore();
40 + resumed.configure(entries, append);
41 + for (const [placeholder, value] of active)
42 + expect(resumed.restore(placeholder)).toBe(value);
43 + for (const placeholder of inactive.keys())
44 + if (!active.has(placeholder))
45 + expect(resumed.restore(placeholder)).toBe(placeholder);
46 +});
48 +test.prop(
49 + {
50 + value: fc.string({
51 + unit: fc.constantFrom(..."abcdefghijklmnopqrstuvwxyz"),
52 + minLength: 8,
53 + maxLength: 80,
54 + }),
55 + path: fc.array(fc.integer({ min: 0, max: 3 }), { maxLength: 20 }),
56 + },
57 + base,
58 +)("known placeholders hydrate through generated arrays", ({ value, path }) => {
59 + const entries: PersistedEntry[] = [];
60 + const engine = new __test.LeaksEngine({
61 + detectors: [
62 + (text) => [
63 + {
64 + start: 0,
65 + end: text.length,
66 + value: text,
67 + labels: [{ tag: "TOKEN", priority: 10, source: "custom" }],
68 + kind: "custom",
69 + confidence: 100,
70 + wholeSpan: false,
71 + },
72 + ],
73 + ],
74 + });
75 + engine.configurePersistence(entries, (customType, data) =>
76 + entries.push({ type: "custom", customType, data }),
77 + );
78 + const token = engine.redactText(value).text;
79 + let nested: unknown = token;
80 + for (const index of path) {
81 + const array = Array.from({ length: index + 1 }, () => null as unknown);
82 + array[index] = nested;
83 + nested = array;
84 + }
85 + const result = engine.hydrateToolInput(nested);
86 + expect(result.issue).toBeUndefined();
87 + expect(JSON.stringify(result.value)).toContain(value);
88 +});

extensions/leaks/__tests__/edge-coverage.test.ts

Modified
98 98 it("covers placeholder fallback and clear branches", () => {
99 99 const store = new __test.PlaceholderStore({ digest: () => "xyz" });
100 100 const placeholder = store.create(fixture, []);
101 - expect(placeholder).toBe("__LEAK_000000000000__");
101 + expect(placeholder).toBe(
102 + "__LEAK_V1_SECRET_00000000000000000000000000000000__",
103 + );
102 104 expect(store.restore(placeholder)).toBe(fixture);
103 105 store.clear();
104 106 expect(store.restore(placeholder)).toBe(placeholder);
107 109 digest: () => "abcdef123456",
109 111 collision.create("a", [label()]);
110 - collision.create("b", [label()]);
111 - expect(collision.create("c", [label()])).toBe(
112 - "__LEAK_TOKEN_abcdef123456_3__",
113 - );
112 + expect(collision.create("b", [label()])).toBeUndefined();
113 + expect(collision.create("c", [label()])).toBeUndefined();
116 116 it("covers selector invalid, placeholder, merge, and ranking branches", () => {

extensions/leaks/__tests__/harness.test.ts

Modified
38 38 expect(JSON.stringify(result)).not.toContain(secret);
39 - expect(JSON.stringify(result)).toMatch(/__LEAK_[A-Z0-9_]+_[a-f0-9]{12}__/);
39 + expect(JSON.stringify(result)).toMatch(
40 + /__LEAK_V1_[A-Z0-9_]+_[a-f0-9]{32}__/,
41 + );
40 42 expect(messages[0].content).toContain(secret);
62 64 text: secret,
64 66 const placeholder = JSON.stringify(redacted).match(
65 - /__LEAK_[A-Z0-9_]+_[a-f0-9]{12}__/,
67 + /__LEAK_V1_[A-Z0-9_]+_[a-f0-9]{32}__/,
66 68 )?.[0];
67 69 expect(placeholder).toBeTruthy();
85 87 expect(JSON.stringify(message)).toContain(secret);
88 - it("loads dotenv values from Pi cwd without persisting mappings", async () => {
90 + it("persists encrypted dotenv mappings without plaintext", async () => {
89 91 const cwd = path.join(os.tmpdir(), `leaks-harness-${Date.now()}`);
90 92 mkdirSync(cwd, { recursive: true });
91 93 writeFileSync(path.join(cwd, ".env"), `TOKEN=${dotenvSecret}\n`, "utf8");
98 100 expect(JSON.stringify(result)).not.toContain(dotenvSecret);
99 - expect(JSON.stringify(t.session.sessionManager.getEntries())).not.toContain(
100 - "LEAK_",
101 - );
101 + const entries = JSON.stringify(t.session.sessionManager.getEntries());
102 + expect(entries).toContain("leaks-generation-v1");
103 + expect(entries).toContain("leaks-mapping-v1");
104 + expect(entries).not.toContain(dotenvSecret);

extensions/leaks/__tests__/lifecycle.test.ts

Added
new file mode 100644
1 +import { describe, expect, it } from "vitest";
2 +import { __test } from "../index.ts";
3 +import type { PersistedEntry } from "../src/placeholders.ts";
5 +const fixture = "lifecycle-fixture-value-123456";
7 +const detector = (text: string) => {
8 + const start = text.indexOf(fixture);
9 + return start < 0
10 + ? []
11 + : [
12 + {
13 + start,
14 + end: start + fixture.length,
15 + value: fixture,
16 + labels: [{ tag: "TOKEN", priority: 10, source: "custom" as const }],
17 + kind: "custom" as const,
18 + confidence: 100,
19 + wholeSpan: false,
20 + },
21 + ];
22 +};
24 +function configuredEngine(entries: PersistedEntry[] = []) {
25 + const engine = new __test.LeaksEngine({ detectors: [detector] });
26 + engine.configurePersistence(entries, (customType, data) =>
27 + entries.push({ type: "custom", customType, data }),
28 + );
29 + return engine;
32 +describe("leaks durable lifecycle", () => {
33 + it("hydrates persisted mappings after a fresh engine reload", () => {
34 + const entries: PersistedEntry[] = [];
35 + const first = configuredEngine(entries);
36 + const placeholder = first.redactText(fixture).text;
37 + const resumed = configuredEngine(entries);
38 + const result = resumed.hydrateToolInput({ nested: [`run ${placeholder}`] });
40 + expect(result.issue).toBeUndefined();
41 + expect(result.value).toEqual({ nested: [`run ${fixture}`] });
42 + });
44 + it("blocks unknown placeholders at exact recursive paths", () => {
45 + const engine = configuredEngine();
46 + const result = engine.hydrateToolInput({
47 + args: ["__LEAK_TOKEN_abcdef123456__"],
48 + });
50 + expect(result.issue).toEqual({ path: "args[0]", label: "TOKEN" });
51 + });
53 + it("blocks incomplete cyclic and unsupported traversal", () => {
54 + const engine = configuredEngine();
55 + const cycle: unknown[] = [];
56 + cycle.push(cycle);
58 + expect(engine.hydrateToolInput(cycle).issue?.label).toBe("TRAVERSAL_CYCLE");
59 + expect(engine.hydrateToolInput({ value: new Date() }).issue).toEqual({
60 + path: "value",
61 + label: "UNSUPPORTED_OBJECT",
62 + });
63 + });
65 + it("leaves provider values visible when mapping append fails", () => {
66 + const engine = new __test.LeaksEngine({ detectors: [detector] });
67 + let calls = 0;
68 + engine.configurePersistence([], () => {
69 + calls++;
70 + if (calls > 1) throw new Error("disk full");
71 + });
72 + const result = engine.redactText(fixture);
74 + expect(result.text).toBe(fixture);
75 + expect(result.count).toBe(0);
76 + expect(engine.stats().warnings.map((warning) => warning.code)).toContain(
77 + "placeholder.persistence",
78 + );
79 + });
81 + it("clear shadows old mappings with a new generation", () => {
82 + const entries: PersistedEntry[] = [];
83 + const store = new __test.PlaceholderStore();
84 + const append = (customType: string, data: unknown) =>
85 + entries.push({ type: "custom" as const, customType, data });
86 + store.configure(entries, append);
87 + const oldPlaceholder = store.create(fixture, [
88 + { tag: "TOKEN", priority: 10, source: "custom" },
89 + ]) as string;
90 + store.clear();
91 + const newPlaceholder = store.create(`${fixture}-new`, [
92 + { tag: "TOKEN", priority: 10, source: "custom" },
93 + ]) as string;
94 + const resumed = new __test.PlaceholderStore();
95 + resumed.configure(entries, append);
97 + expect(resumed.restore(oldPlaceholder)).toBe(oldPlaceholder);
98 + expect(resumed.restore(newPlaceholder)).toBe(`${fixture}-new`);
99 + });
100 +});

extensions/leaks/__tests__/pi-direct.test.ts

Modified
17 17 handlers,
18 18 commands,
19 19 pi: {
20 + appendEntry() {},
20 21 on(name: string, handler: Handler) {
21 22 handlers.set(name, handler);
30 -const LEAK_PLACEHOLDER_RE = /__LEAK_[A-Z0-9_]+_[a-f0-9]{12}(?:_\d+)?__/;
31 +const LEAK_PLACEHOLDER_RE = /__LEAK_V1_[A-Z0-9_]+_[a-f0-9]{32}__/;
32 33 function serialized(value: unknown) {
33 34 return JSON.stringify(value);
125 126 const placeholder =
126 - JSON.stringify(provider).match(/__LEAK_[A-Z0-9_]+_[a-f0-9]{12}__/)?.[0] ??
127 - "";
127 + JSON.stringify(provider).match(
128 + /__LEAK_V1_[A-Z0-9_]+_[a-f0-9]{32}__/,
129 + )?.[0] ?? "";
128 130 const rawToolInput = { value: placeholder };
129 131 const toolEvent = { input: rawToolInput };
130 132 await runtime.handlers.get("tool_call")?.(toolEvent, view.ctx);
285 287 expectLocalRestored(messageEnd, secret, placeholder);
288 - it("blocks unresolved leak placeholders in mutating tools outside leaks", async () => {
290 + it("blocks unresolved placeholders in every tool input path", async () => {
289 291 const runtime = fakePi();
290 292 leaks(runtime.pi as never);
291 293 const view = ui();
305 307 expect(writeResult).toEqual({
306 308 block: true,
307 - reason:
308 - "Blocked: unresolved `__LEAK_*__` placeholder in write target outside `pi-ext/extensions/leaks/`. Ask user for real value, restore from source, or remove placeholder.",
309 + reason: "Blocked write: unresolved leaks placeholder at content (TOKEN)",
311 312 const editResult = await hook(
335 336 view.ctx,
337 - expect(oldTextOnly).toBeUndefined();
338 + expect(oldTextOnly).toMatchObject({ block: true });
339 340 const bashResult = await hook(
348 349 expect(bashResult).toMatchObject({ block: true });
351 - it("allows unresolved leak placeholders inside the leaks extension", async () => {
352 + it("blocks unresolved placeholders in custom tools", async () => {
352 353 const runtime = fakePi();
353 354 leaks(runtime.pi as never);
354 - const placeholder = "__LEAK_TOKEN_abcdef123456__";
355 - const root = path.resolve(import.meta.dirname, "..");
356 355 const hook = runtime.handlers.get("tool_call");
357 356 if (!hook) throw new Error("missing tool_call hook");
359 - await expect(
360 - hook(
361 - {
362 - type: "tool_call",
363 - toolName: "write",
364 - toolCallId: "write-1",
365 - input: { path: path.join(root, "README.md"), content: placeholder },
366 - },
367 - ui().ctx,
368 - ),
369 - ).resolves.toBeUndefined();
370 - await expect(
371 - hook(
372 - {
373 - type: "tool_call",
374 - toolName: "bash",
375 - toolCallId: "bash-1",
376 - input: { command: `printf %s ${placeholder}` },
377 - },
378 - { ...ui().ctx, cwd: root },
379 - ),
380 - ).resolves.toBeUndefined();
357 + const result = await hook(
359 + type: "tool_call",
360 + toolName: "custom",
361 + toolCallId: "custom-1",
362 + input: { nested: ["__LEAK_TOKEN_abcdef123456__"] },
363 + },
364 + ui().ctx,
365 + );
366 + expect(result).toMatchObject({ block: true });

extensions/leaks/__tests__/placeholders.test.ts

Modified
1 1 import { describe, expect, it } from "vitest";
2 2 import { __test } from "../index.ts";
3 +import type { PersistedEntry } from "../src/placeholders.ts";
3 4 import type { SpanLabel } from "../src/types.ts";
5 6 const secretA = "placeholder-fixture-secret-A-123456";
13 14 return { tag, priority, source };
17 +function persistentStore(
18 + options: ConstructorParameters<typeof __test.PlaceholderStore>[0] = {},
19 +) {
20 + const entries: PersistedEntry[] = [];
21 + const store = new __test.PlaceholderStore(options);
22 + store.configure(entries, (customType, data) =>
23 + entries.push({ type: "custom", customType, data }),
24 + );
25 + return { entries, store };
16 28 describe("leaks placeholder store", () => {
17 - it("creates tagged HMAC12 placeholders", () => {
18 - const store = new __test.PlaceholderStore();
29 + it("persists tagged V1 HMAC32 mappings before emission", () => {
30 + const { entries, store } = persistentStore();
19 31 const placeholder = store.create(secretA, [label("API_KEY", 10, "dotenv")]);
21 - expect(placeholder).toMatch(/^__LEAK_API_KEY_[a-f0-9]{12}__$/);
22 - expect(placeholder).not.toContain(secretA);
23 - });
25 - it("uses random per-store HMAC keys", () => {
26 - const left = new __test.PlaceholderStore().create(secretA, [
27 - label("TOKEN", 10, "dotenv"),
33 + expect(placeholder).toMatch(/^__LEAK_V1_API_KEY_[a-f0-9]{32}__$/);
34 + expect(JSON.stringify(entries)).not.toContain(secretA);
35 + expect(entries.map((entry) => entry.customType)).toEqual([
36 + "leaks-generation-v1",
37 + "leaks-mapping-v1",
29 - const right = new __test.PlaceholderStore().create(secretA, [
30 - label("TOKEN", 10, "dotenv"),
39 + });
41 + it("reconstructs authenticated mappings from the active branch", () => {
42 + const { entries, store } = persistentStore();
43 + const placeholder = store.create(secretA, [label("TOKEN", 10, "dotenv")]);
44 + const resumed = new __test.PlaceholderStore();
45 + resumed.configure(entries, () => {});
47 + expect(resumed.restore(`run ${placeholder}`)).toBe(`run ${secretA}`);
48 + expect(resumed.stats().mappingCount).toBe(1);
49 + });
51 + it("uses random generation keys and stable same-value mappings", () => {
52 + const left = persistentStore().store;
53 + const right = persistentStore().store;
54 + const first = left.create(secretA, [label("FIRST", 10, "dotenv")]);
55 + const repeated = left.create(secretA, [label("SECOND", 90, "builtin")]);
56 + const otherGeneration = right.create(secretA, [
57 + label("FIRST", 10, "dotenv"),
33 - expect(left).not.toBe(right);
60 + expect(repeated).toBe(first);
61 + expect(otherGeneration).not.toBe(first);
36 - it("keeps same-value placeholders stable and freezes tags", () => {
37 - const store = new __test.PlaceholderStore();
38 - const first = store.create(secretA, [label("FIRST", 10, "dotenv")]);
39 - const second = store.create(secretA, [label("SECOND", 90, "builtin")]);
41 - expect(second).toBe(first);
42 - expect(second).toContain("FIRST");
43 - expect(second).not.toContain("SECOND");
44 - });
46 - it("orders tags by semantic priority and caps tag count and length", () => {
47 - const store = new __test.PlaceholderStore({ digest: () => "0123456789ab" });
64 + it("orders and bounds tags", () => {
65 + const { store } = persistentStore({ digest: () => "0123456789ab" });
48 66 const placeholder = store.create(secretA, [
49 67 label("GENERIC", 50, "generic"),
50 68 label("BUILTIN", 40, "builtin"),
58 76 expect(placeholder).toBe(
59 - `__LEAK_${"X".repeat(64)}_ENV_KEY_STRUCTURE_CUSTOM_BUILTIN_GENERIC_0123456789ab__`,
77 + `__LEAK_V1_${"X".repeat(64)}_ENV_KEY_STRUCTURE_CUSTOM_BUILTIN_GENERIC_0123456789ab00000000000000000000__`,
63 - it("adds collision suffixes when HMAC collides", () => {
64 - const store = new __test.PlaceholderStore({ digest: () => "abcdef123456" });
66 - const first = store.create(secretA, [label("TOKEN", 10, "dotenv")]);
67 - const second = store.create(secretB, [label("TOKEN", 10, "dotenv")]);
69 - expect(first).toBe("__LEAK_TOKEN_abcdef123456__");
70 - expect(second).toBe("__LEAK_TOKEN_abcdef123456_2__");
71 - });
73 - it("caps restorable mappings and warns once", () => {
81 + it("leaves colliding and overflow values visible", () => {
74 82 const warnings: string[] = [];
75 - // Tiny explicit cap tests overflow behavior without constructing 8192 mappings.
76 - const store = new __test.PlaceholderStore({
77 - digest: (value) =>
78 - Number(value.match(/\d+$/)?.[0] ?? 999999)
79 - .toString(16)
80 - .padStart(12, "0"),
81 - onWarning: (warning) => warnings.push(warning.message),
82 - cap: 2,
83 + const { store } = persistentStore({
84 + digest: () => "abcdef123456",
85 + cap: 1,
86 + onWarning: (warning) => warnings.push(warning.code),
84 - for (let index = 0; index < 2; index++) {
85 - store.create(`cap-fixture-${index}`, [label("TOKEN", 10, "dotenv")]);
86 - }
88 + const first = store.create(secretA, [label("TOKEN", 10, "dotenv")]);
89 + const collision = store.create(secretB, [label("TOKEN", 10, "dotenv")]);
88 - const overflow = store.create(secretA, [label("TOKEN", 10, "dotenv")]);
89 - const overflowAgain = store.create(secretB, [label("TOKEN", 10, "dotenv")]);
91 - expect(store.stats().mappingCount).toBe(2);
92 - expect(overflow).toMatch(/^__LEAK_TOKEN_[a-f0-9]{12}__$/);
93 - expect(store.restore(overflow)).toBe(overflow);
94 - expect(overflowAgain).not.toBe(overflow);
95 - expect(warnings).toEqual([
96 - "placeholder mapping cap reached; new placeholders are not restorable",
97 - ]);
91 + expect(first).toBeDefined();
92 + expect(collision).toBeUndefined();
93 + expect(warnings).toEqual(["placeholder.cap"]);
100 - it("restores only exact placeholders", () => {
101 - const store = new __test.PlaceholderStore({ digest: () => "bbbbbbbbbbbb" });
96 + it("rejects collisions before the cap", () => {
97 + const warnings: string[] = [];
98 + const { store } = persistentStore({
99 + digest: () => "abcdef123456",
100 + onWarning: (warning) => warnings.push(warning.code),
101 + });
102 + store.create(secretA, [label("TOKEN", 10, "dotenv")]);
103 + expect(
104 + store.create(secretB, [label("TOKEN", 10, "dotenv")]),
105 + ).toBeUndefined();
106 + expect(warnings).toEqual(["placeholder.collision"]);
107 + });
109 + it("disables new redaction when authentication fails", () => {
110 + const { entries, store } = persistentStore();
102 111 const placeholder = store.create(secretA, [label("TOKEN", 10, "dotenv")]);
112 + const mapping = entries[1].data as { authTag: string };
113 + mapping.authTag = `${mapping.authTag[0] === "A" ? "B" : "A"}${mapping.authTag.slice(1)}`;
114 + const warnings: string[] = [];
115 + const resumed = new __test.PlaceholderStore({
116 + onWarning: (warning) => warnings.push(warning.code),
117 + });
118 + resumed.configure(entries, () => {});
120 + expect(resumed.restore(placeholder as string)).toBe(placeholder);
121 + expect(
122 + resumed.create(secretB, [label("TOKEN", 10, "dotenv")]),
123 + ).toBeUndefined();
124 + expect(warnings).toContain("placeholder.state");
125 + });
127 + it("leaves values visible when append fails", () => {
128 + const store = new __test.PlaceholderStore();
129 + store.configure([], () => {
130 + throw new Error("disk full");
131 + });
132 + expect(
133 + store.create(secretA, [label("TOKEN", 10, "dotenv")]),
134 + ).toBeUndefined();
135 + });
137 + it("restores exact known placeholders and reports unknown ones", () => {
138 + const { store } = persistentStore();
139 + const placeholder = store.create(secretA, [
140 + label("TOKEN", 10, "dotenv"),
141 + ]) as string;
142 + const unknown = "__LEAK_TOKEN_abcdef123456__";
104 144 expect(store.restore(`run ${placeholder}`)).toBe(`run ${secretA}`);
105 - expect(store.restore(`run ${placeholder.slice(0, -2)}`)).not.toContain(
106 - secretA,
107 - );
108 - });
110 - it("engine redacts selected spans through the store", () => {
111 - const engine = new __test.LeaksEngine({
112 - detectors: [
113 - (text) => [
114 - {
115 - start: text.indexOf(secretA),
116 - end: text.indexOf(secretA) + secretA.length,
117 - value: secretA,
118 - labels: [label("TOKEN", 10, "dotenv")],
119 - kind: "exact",
120 - confidence: 100,
121 - wholeSpan: false,
122 - },
123 - ],
124 - ],
125 - });
127 - const redacted = engine.redactText(`send ${secretA}`, "provider");
129 - expect(redacted.text).not.toContain(secretA);
130 - expect(redacted.count).toBe(1);
131 - expect(engine.restoreText(redacted.text)).toBe(`send ${secretA}`);
132 - expect(engine.stats().mappingCount).toBe(1);
145 + expect(store.restore(placeholder.slice(0, -2))).not.toContain(secretA);
146 + expect(store.unresolved(unknown)).toEqual([unknown]);

extensions/leaks/__tests__/settings.test.ts

Modified
139 139 const result = engine.redactText(`${fixtureSecret}-tail`, "provider");
141 - expect(result.text).toMatch(/^__LEAK_FOO_TOKEN_[a-f0-9]{12}__-tail$/);
141 + expect(result.text).toMatch(/^__LEAK_V1_FOO_TOKEN_[a-f0-9]{32}__-tail$/);
142 142 expect(engine.stats().warnings.map((warning) => warning.code)).toContain(
143 143 "settings.regex.multiple-captures",

extensions/leaks/__tests__/structures.test.ts

Modified
148 148 const jwtResult = engine.redactText(`jwt=${jwt}`, "provider");
149 149 const keyResult = engine.redactText(privateKey, "provider");
151 - expect(jwtResult.text).toMatch(/^jwt=__LEAK_JWT_[a-f0-9]{12}__$/);
151 + expect(jwtResult.text).toMatch(/^jwt=__LEAK_V1_JWT_[a-f0-9]{32}__$/);
152 152 expect(keyResult.text).toMatch(
153 - /^__LEAK_OPENSSH_PRIVATE_KEY_[a-f0-9]{12}__$/,
153 + /^__LEAK_V1_OPENSSH_PRIVATE_KEY_[a-f0-9]{32}__$/,

extensions/leaks/__tests__/unit.test.ts

Modified
79 79 path: "messages[0].content",
80 80 labels: ["ALPHA_SECRET"],
81 81 placeholders: [
82 - expect.stringMatching(/^__LEAK_ALPHA_SECRET_[a-f0-9]{12}__$/),
82 + expect.stringMatching(/^__LEAK_V1_ALPHA_SECRET_[a-f0-9]{32}__$/),

extensions/leaks/src/engine.ts

Modified
5 5 learnedValueSpans,
6 6 loadDotenvValues,
7 7 } from "./dotenv.ts";
8 -import { PlaceholderStore } from "./placeholders.ts";
8 +import { type PersistedEntry, PlaceholderStore } from "./placeholders.ts";
9 9 import { isPlainObject } from "./safety.ts";
10 10 import { selectSecretSpans } from "./selector.ts";
11 11 import {
100 100 for (const span of selected) {
101 101 const spanLabels = span.labels.map((label) => label.tag);
102 102 const placeholder = this.placeholders.create(span.value, span.labels);
103 + if (!placeholder) continue;
103 104 redacted = `${redacted.slice(0, span.start)}${placeholder}${redacted.slice(span.end)}`;
104 105 placeholders.push(placeholder);
105 106 labels.push(...spanLabels);
113 - const count = selected.length;
114 + const count = placeholders.length;
114 115 if (origin === "provider") {
115 116 this.lastProviderRedactionCount = count;
116 117 this.totalProviderRedactionCount += count;
133 134 return this.walk(value, origin, false);
137 + configurePersistence(
138 + entries: PersistedEntry[],
139 + append: (customType: string, data: unknown) => void,
140 + ) {
141 + this.placeholders.configure(entries, append);
136 144 restoreText(text: string) {
137 145 return this.placeholders.restore(text);
148 + hydrateToolInput<T>(value: T): {
149 + value: T;
150 + issue?: { path: string; label: string };
151 + } {
152 + const restored = this.restoreDeep(value).value;
153 + const seen = new WeakSet<object>();
154 + const inspect = (
155 + item: unknown,
156 + depth: number,
157 + path: string,
158 + ): { path: string; label: string } | undefined => {
159 + if (typeof item === "string") {
160 + const unresolved = this.placeholders.unresolved(item)[0];
161 + return unresolved
162 + ? { path: path || "$", label: placeholderLabel(unresolved) }
163 + : undefined;
165 + if (item === null || typeof item !== "object") return undefined;
166 + if (depth >= 64) return { path: path || "$", label: "TRAVERSAL_DEPTH" };
167 + if (seen.has(item))
168 + return { path: path || "$", label: "TRAVERSAL_CYCLE" };
169 + seen.add(item);
170 + if (Array.isArray(item)) {
171 + for (let index = 0; index < item.length; index++) {
172 + const issue = inspect(item[index], depth + 1, `${path}[${index}]`);
173 + if (issue) return issue;
175 + return undefined;
177 + if (!isPlainObject(item))
178 + return { path: path || "$", label: "UNSUPPORTED_OBJECT" };
179 + for (const [key, child] of Object.entries(item)) {
180 + const issue = inspect(child, depth + 1, childPath(path, key));
181 + if (issue) return issue;
183 + return undefined;
184 + };
185 + return { value: restored, issue: inspect(restored, 0, "") };
140 188 restoreDeep<T>(value: T): DeepRedactionResult<T> {
141 189 return this.walk(value, "provider", true);
219 267 return value;
221 269 const cached = seen.get(value);
222 - if (cached) return cached;
270 + if (cached) {
271 + this.warnOnce(
272 + "traversal.cycle",
273 + "cyclic value left unchanged during redaction traversal",
274 + );
275 + return cached;
223 277 if (Array.isArray(value)) {
224 278 const copy: unknown[] = [];
225 279 seen.set(value, copy);
228 282 if (copy.some((item, index) => item !== value[index])) changed = true;
229 283 return copy;
231 - if (!isPlainObject(value)) return value;
285 + if (!isPlainObject(value)) {
286 + this.warnOnce(
287 + "traversal.unsupported",
288 + "unsupported object left unchanged during redaction traversal",
289 + );
290 + return value;
232 292 const source = value as Record<string, unknown>;
233 293 const copy: Record<string, unknown> = {};
234 294 seen.set(value, copy);
318 +function placeholderLabel(placeholder: string) {
319 + const match = /^__LEAK_(?:V1_)?([A-Z0-9_]+)/.exec(placeholder);
320 + return match?.[1]?.replace(/_+$/, "") ?? "UNKNOWN";
258 323 function childPath(parent: string, key: string) {
259 324 if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key))
260 325 return parent ? `${parent}.${key}` : key;

extensions/leaks/src/pi.ts

Modified
1 -import path from "node:path";
2 1 import {
3 2 type ExtensionAPI,
4 3 type ExtensionContext,
11 10 export default function leaks(pi: ExtensionAPI) {
12 11 const engine = new LeaksEngine();
12 + const reportedWarnings = new Set<string>();
14 14 pi.on("session_start", async (_event, ctx) => {
15 + rebuildPersistence(engine, pi, ctx);
15 16 engine.reload(ctx.cwd, readSettings(ctx.cwd), process.env);
17 + notifyInMemorySession(ctx, reportedWarnings);
18 + flushWarnings(engine, ctx, reportedWarnings);
16 19 if (ctx.hasUI) ctx.ui.setStatus("leaks", "leaks on | last 0");
22 + pi.on("session_tree", async (_event, ctx) => {
23 + rebuildPersistence(engine, pi, ctx);
24 + flushWarnings(engine, ctx, reportedWarnings);
25 + });
19 27 pi.on("context", async (event) => {
20 28 return { messages: engine.redactDeep(event.messages, "context").value };
23 31 pi.on("before_provider_request", async (event, ctx) => {
24 32 const result = engine.redactDeep(event.payload, "provider");
33 + flushWarnings(engine, ctx, reportedWarnings);
25 34 updateProviderUi(ctx, engine, result);
26 35 return result.value;
37 46 pi.on("tool_call", async (event, ctx) => {
38 - restoreEventProperty(
39 - engine,
40 - event as unknown as Record<string, unknown>,
41 - "input",
42 - );
43 - return blockUnresolvedPlaceholderToolCall(event, ctx.cwd);
47 + const record = event as unknown as Record<string, unknown>;
48 + const current = record.input;
49 + const result = engine.hydrateToolInput(current);
50 + record.input = result.value;
51 + copyRestoredInPlace(current, result.value);
52 + if (!result.issue) return;
53 + const toolName =
54 + typeof event.toolName === "string" ? event.toolName : "tool";
55 + const reason = `Blocked ${toolName}: unresolved leaks placeholder at ${result.issue.path} (${result.issue.label})`;
56 + notify(ctx, reason, "warning");
57 + return { block: true, reason };
46 60 pi.on("tool_execution_start", async (event) => {
80 94 return;
82 96 if (command === "reload") {
97 + rebuildPersistence(engine, pi, ctx);
83 98 engine.reload(ctx.cwd, readSettings(ctx.cwd), process.env);
99 + flushWarnings(engine, ctx, reportedWarnings);
84 100 ctx.ui.notify("leaks reloaded", "info");
85 101 return;
98 114 engine.clear();
115 + flushWarnings(engine, ctx, reportedWarnings);
99 116 ctx.ui.notify("leaks cleared", "info");
100 117 return;
187 204 Object.assign(target, source);
190 -const LEAK_PLACEHOLDER_RE = /__LEAK_[A-Za-z0-9_]*__/;
191 -const LEAKS_EXTENSION_ROOT = path.resolve(import.meta.dirname, "..");
192 -const BLOCK_REASON_SUFFIX =
193 - "outside `pi-ext/extensions/leaks/`. Ask user for real value, restore from source, or remove placeholder.";
195 -function blockUnresolvedPlaceholderToolCall(
196 - event: unknown,
197 - cwd: string,
198 -): { block: true; reason: string } | undefined {
199 - if (!isPlainObject(event)) return undefined;
200 - const toolName = event.toolName;
201 - const input = event.input;
202 - if (!isPlainObject(input)) return undefined;
204 - if (toolName === "bash") {
205 - if (containsLeakPlaceholder(input.command) && !isInLeaksExtension(cwd))
206 - return blockPlaceholder("bash command");
207 - return undefined;
208 - }
210 - if (toolName === "write") {
211 - if (
212 - containsLeakPlaceholder(input.content) &&
213 - !isPathInLeaksExtension(cwd, input.path)
214 - )
215 - return blockPlaceholder("write target");
216 - return undefined;
217 - }
219 - if (toolName === "edit") {
220 - if (isPathInLeaksExtension(cwd, input.path)) return undefined;
221 - if (!Array.isArray(input.edits)) return undefined;
222 - if (input.edits.some((edit) => containsEditWritePlaceholder(edit)))
223 - return blockPlaceholder("edit target");
224 - }
226 - return undefined;
229 -function containsEditWritePlaceholder(edit: unknown) {
230 - return isPlainObject(edit) && containsLeakPlaceholder(edit.newText);
233 -function containsLeakPlaceholder(value: unknown) {
234 - return typeof value === "string" && LEAK_PLACEHOLDER_RE.test(value);
237 -function blockPlaceholder(target: string) {
238 - return {
239 - block: true,
240 - reason: `Blocked: unresolved \`__LEAK_*__\` placeholder in ${target} ${BLOCK_REASON_SUFFIX}`,
241 - } as const;
244 -function isPathInLeaksExtension(cwd: string, file: unknown) {
245 - if (typeof file !== "string") return false;
246 - return isInLeaksExtension(path.resolve(cwd, file));
249 -function isInLeaksExtension(candidate: string) {
250 - const relative = path.relative(LEAKS_EXTENSION_ROOT, path.resolve(candidate));
251 - return (
252 - relative === "" ||
253 - (!relative.startsWith("..") && !path.isAbsolute(relative))
207 +function rebuildPersistence(
208 + engine: LeaksEngine,
209 + pi: ExtensionAPI,
210 + ctx: ExtensionContext,
211 +) {
212 + const entries = (ctx.sessionManager?.getBranch() ?? [])
213 + .filter((entry) => entry.type === "custom")
214 + .map((entry) => ({
215 + type: "custom" as const,
216 + customType: entry.customType,
217 + data: entry.data,
218 + }));
219 + engine.configurePersistence(entries, (customType, data) =>
220 + pi.appendEntry(customType, data),
224 +function notifyInMemorySession(ctx: ExtensionContext, reported: Set<string>) {
225 + if (ctx.sessionManager?.getSessionFile() !== undefined) return;
226 + const key = "session.in-memory";
227 + if (reported.has(key)) return;
228 + reported.add(key);
229 + notify(
230 + ctx,
231 + "in-memory session mappings cannot survive process restart",
232 + "warning",
233 + );
236 +function flushWarnings(
237 + engine: LeaksEngine,
238 + ctx: ExtensionContext,
239 + reported: Set<string>,
240 +) {
241 + for (const warning of engine.stats().warnings) {
242 + const key = `${warning.code}:${warning.message}`;
243 + if (reported.has(key)) continue;
244 + reported.add(key);
245 + notify(ctx, warning.message, warning.severity);
249 +function notify(
250 + ctx: ExtensionContext,
251 + message: string,
252 + severity: "info" | "warning" | "error",
253 +) {
254 + if (ctx.hasUI) ctx.ui.notify(message, severity);
255 + else console.error(`[leaks] ${message}`);
257 258 function readSettings(cwd: string) {
258 259 const manager = SettingsManager.create(cwd);
259 260 const global = manager.getGlobalSettings() as Record<string, unknown>;

extensions/leaks/src/placeholders.ts

Modified
1 -import { createHmac, randomBytes } from "node:crypto";
1 +import {
2 + createCipheriv,
3 + createDecipheriv,
4 + createHmac,
5 + hkdfSync,
6 + randomBytes,
7 +} from "node:crypto";
2 8 import { sanitizeTag } from "./safety.ts";
3 9 import type { SpanLabel, WarningRecord } from "./types.ts";
5 11 const CAP = 8192;
6 -const PLACEHOLDER_RE = /__LEAK(?:_[A-Z0-9]{1,64})*_[a-f0-9]{12}(?:_\d+)?__/g;
12 +const GENERATION_TYPE = "leaks-generation-v1";
13 +const MAPPING_TYPE = "leaks-mapping-v1";
14 +const PLACEHOLDER_RE = /__LEAK_V1(?:_[A-Z0-9_]{1,64}){1,6}_[a-f0-9]{32}__/g;
15 +export const ANY_PLACEHOLDER_RE = /__LEAK_[A-Za-z0-9_]+__/g;
7 16 const SOURCE_RANK: Record<SpanLabel["source"], number> = {
8 17 dotenv: 0,
9 18 env: 0,
13 22 generic: 4,
25 +export type GenerationRecord = {
26 + version: 1;
27 + generationId: string;
28 + rootKey: string;
29 +};
31 +export type MappingRecord = {
32 + version: 1;
33 + generationId: string;
34 + placeholder: string;
35 + nonce: string;
36 + ciphertext: string;
37 + authTag: string;
38 +};
40 +export type PersistedEntry = {
41 + type: "custom";
42 + customType: string;
43 + data?: unknown;
44 +};
46 +type AppendEntry = (customType: string, data: unknown) => void;
16 48 type PlaceholderStoreOptions = {
17 49 digest?: (value: string) => string;
18 50 onWarning?: (warning: WarningRecord) => void;
19 51 cap?: number;
52 + append?: AppendEntry;
22 55 export class PlaceholderStore {
23 - private readonly key = randomBytes(32);
24 56 private readonly digestOverride?: (value: string) => string;
25 57 private readonly onWarning?: (warning: WarningRecord) => void;
26 58 private readonly cap: number;
59 + private append?: AppendEntry;
60 + private generation?: GenerationRecord;
61 + private hmacKey?: Buffer;
62 + private encryptionKey?: Buffer;
27 63 private readonly secretToPlaceholder = new Map<string, string>();
28 64 private readonly placeholderToSecret = new Map<string, string>();
29 - private readonly overflowPlaceholders = new Set<string>();
30 65 private warnedCap = false;
31 - private overflowNonce = 1;
66 + private enabled = true;
33 68 constructor(options: PlaceholderStoreOptions = {}) {
34 69 this.digestOverride = options.digest;
35 70 this.onWarning = options.onWarning;
36 71 this.cap = options.cap ?? CAP;
72 + this.append = options.append;
73 + this.startGeneration();
39 - create(value: string, labels: SpanLabel[]): string {
76 + configure(entries: PersistedEntry[], append: AppendEntry) {
77 + this.append = append;
78 + this.reset();
79 + let generationIndex = -1;
80 + for (let index = 0; index < entries.length; index++) {
81 + const entry = entries[index];
82 + if (entry.customType === GENERATION_TYPE) generationIndex = index;
83 + else if (entry.customType.startsWith("leaks-generation-"))
84 + this.disable("unsupported leaks generation version");
85 + }
86 + if (!this.enabled) return;
87 + if (generationIndex < 0) {
88 + this.startGeneration();
89 + return;
90 + }
91 + const generation = parseGeneration(entries[generationIndex].data);
92 + if (!generation) {
93 + this.disable("invalid leaks generation record");
94 + return;
95 + }
96 + this.activate(generation);
97 + for (const entry of entries.slice(generationIndex + 1)) {
98 + if (
99 + entry.customType.startsWith("leaks-mapping-") &&
100 + entry.customType !== MAPPING_TYPE
101 + ) {
102 + this.disable("unsupported leaks mapping version");
103 + continue;
105 + if (entry.customType !== MAPPING_TYPE) continue;
106 + const record = parseMapping(entry.data);
107 + if (!record || record.generationId !== generation.generationId) {
108 + this.disable("invalid leaks mapping record");
109 + continue;
111 + const value = this.decrypt(record);
112 + if (value === undefined) {
113 + this.disable("leaks mapping authentication failed");
114 + continue;
116 + const existing = this.placeholderToSecret.get(record.placeholder);
117 + if (existing !== undefined && existing !== value) {
118 + this.disable("conflicting leaks mapping record");
119 + continue;
121 + this.placeholderToSecret.set(record.placeholder, value);
122 + this.secretToPlaceholder.set(value, record.placeholder);
126 + create(value: string, labels: SpanLabel[]): string | undefined {
40 127 const known = this.secretToPlaceholder.get(value);
41 128 if (known) return known;
43 - const base = this.format(value, labels);
129 + if (!this.enabled || !this.generation || !this.encryptionKey)
130 + return undefined;
44 131 if (this.secretToPlaceholder.size >= this.cap) {
45 132 this.warnCap();
46 - return this.nonRestorable(base);
133 + return undefined;
135 + const placeholder = this.format(value, labels);
136 + const collision = this.placeholderToSecret.get(placeholder);
137 + if (collision !== undefined && collision !== value) {
138 + this.warn(
139 + "placeholder.collision",
140 + "placeholder collision; value left visible",
141 + );
142 + return undefined;
144 + try {
145 + const record = this.encrypt(placeholder, value);
146 + this.append?.(MAPPING_TYPE, record);
147 + } catch {
148 + this.warn(
149 + "placeholder.persistence",
150 + "mapping persistence failed; value left visible",
151 + );
152 + return undefined;
49 - const placeholder = this.nextAvailable(base);
50 154 this.secretToPlaceholder.set(value, placeholder);
51 155 this.placeholderToSecret.set(placeholder, value);
52 156 return placeholder;
55 159 restore(text: string): string {
56 - return text.replace(PLACEHOLDER_RE, (placeholder) => {
57 - return this.placeholderToSecret.get(placeholder) ?? placeholder;
58 - });
160 + return text.replace(
161 + PLACEHOLDER_RE,
162 + (placeholder) => this.placeholderToSecret.get(placeholder) ?? placeholder,
163 + );
166 + unresolved(text: string) {
167 + return [...text.matchAll(ANY_PLACEHOLDER_RE)]
168 + .map((match) => match[0])
169 + .filter((placeholder) => !this.placeholderToSecret.has(placeholder));
61 172 clear() {
62 - this.secretToPlaceholder.clear();
63 - this.placeholderToSecret.clear();
64 - this.overflowPlaceholders.clear();
65 - this.warnedCap = false;
66 - this.overflowNonce = 1;
173 + const generation = newGeneration();
174 + try {
175 + this.append?.(GENERATION_TYPE, generation);
176 + this.reset();
177 + this.activate(generation);
178 + } catch {
179 + this.warn(
180 + "placeholder.persistence",
181 + "generation persistence failed; mappings kept active",
182 + );
69 186 stats() {
70 - return { mappingCount: this.secretToPlaceholder.size };
187 + return {
188 + mappingCount: this.secretToPlaceholder.size,
189 + generationId: this.generation?.generationId,
190 + persistenceEnabled: this.enabled,
191 + };
194 + private startGeneration() {
195 + const generation = newGeneration();
196 + try {
197 + this.append?.(GENERATION_TYPE, generation);
198 + this.activate(generation);
199 + } catch {
200 + this.disable("generation persistence failed");
204 + private activate(generation: GenerationRecord) {
205 + const root = Buffer.from(generation.rootKey, "base64url");
206 + this.generation = generation;
207 + this.hmacKey = derive(root, "leaks-placeholder-hmac-v1");
208 + this.encryptionKey = derive(root, "leaks-mapping-encryption-v1");
211 + private reset() {
212 + this.generation = undefined;
213 + this.hmacKey = undefined;
214 + this.encryptionKey = undefined;
215 + this.secretToPlaceholder.clear();
216 + this.placeholderToSecret.clear();
217 + this.warnedCap = false;
218 + this.enabled = true;
73 221 private format(value: string, labels: SpanLabel[]) {
74 222 const tags = labels
75 223 .toSorted((left, right) => {
76 224 const rank = SOURCE_RANK[left.source] - SOURCE_RANK[right.source];
77 - if (rank !== 0) return rank;
78 - return left.priority - right.priority;
225 + return rank || left.priority - right.priority;
80 - .map((label) => sanitizeTag(label.tag))
81 - .filter((tag, index, all) => all.indexOf(tag) === index)
227 + .map((item) => sanitizeTag(item.tag))
228 + .filter((tag, index, all) => tag && all.indexOf(tag) === index)
82 229 .slice(0, 6);
83 - const tagText = tags.length === 0 ? "" : `_${tags.join("_")}`;
84 - return `__LEAK${tagText}_${this.digest(value)}__`;
85 - }
87 - private digest(value: string) {
88 - const raw =
230 + const tagText = tags.length > 0 ? tags.join("_") : "SECRET";
231 + const digest =
89 232 this.digestOverride?.(value) ??
90 - createHmac("sha256", this.key).update(value).digest("hex");
91 - return raw
233 + createHmac("sha256", this.hmacKey as Buffer)
234 + .update(value)
235 + .digest("hex");
236 + const hmac32 = digest
92 237 .toLowerCase()
93 238 .replace(/[^a-f0-9]/g, "0")
94 - .slice(0, 12)
95 - .padEnd(12, "0");
239 + .slice(0, 32)
240 + .padEnd(32, "0");
241 + return `__LEAK_V1_${tagText}_${hmac32}__`;
98 - private nextAvailable(base: string) {
99 - if (!this.placeholderToSecret.has(base)) return base;
100 - let index = 2;
101 - while (true) {
102 - const candidate = base.replace(/__$/, `_${index}__`);
103 - if (!this.placeholderToSecret.has(candidate)) return candidate;
104 - index++;
244 + private encrypt(placeholder: string, value: string): MappingRecord {
245 + const generation = this.generation as GenerationRecord;
246 + const nonce = randomBytes(12);
247 + const cipher = createCipheriv(
248 + "aes-256-gcm",
249 + this.encryptionKey as Buffer,
250 + nonce,
251 + );
252 + cipher.setAAD(aad(generation.generationId, placeholder));
253 + const ciphertext = Buffer.concat([
254 + cipher.update(value, "utf8"),
255 + cipher.final(),
256 + ]);
257 + return {
258 + version: 1,
259 + generationId: generation.generationId,
260 + placeholder,
261 + nonce: nonce.toString("base64url"),
262 + ciphertext: ciphertext.toString("base64url"),
263 + authTag: cipher.getAuthTag().toString("base64url"),
264 + };
267 + private decrypt(record: MappingRecord) {
268 + try {
269 + const decipher = createDecipheriv(
270 + "aes-256-gcm",
271 + this.encryptionKey as Buffer,
272 + Buffer.from(record.nonce, "base64url"),
273 + );
274 + decipher.setAAD(aad(record.generationId, record.placeholder));
275 + decipher.setAuthTag(Buffer.from(record.authTag, "base64url"));
276 + return new TextDecoder("utf-8", { fatal: true }).decode(
277 + Buffer.concat([
278 + decipher.update(Buffer.from(record.ciphertext, "base64url")),
279 + decipher.final(),
280 + ]),
281 + );
282 + } catch {
283 + return undefined;
108 - private nonRestorable(base: string) {
109 - let candidate = base;
110 - while (
111 - this.placeholderToSecret.has(candidate) ||
112 - this.overflowPlaceholders.has(candidate)
113 - ) {
114 - this.overflowNonce++;
115 - candidate = base.replace(/__$/, `_${this.overflowNonce}__`);
116 - }
117 - this.overflowPlaceholders.add(candidate);
118 - this.overflowNonce++;
119 - return candidate;
287 + private disable(message: string) {
288 + this.enabled = false;
289 + this.warn("placeholder.state", `${message}; new redaction disabled`);
122 292 private warnCap() {
123 293 if (this.warnedCap) return;
124 294 this.warnedCap = true;
125 - this.onWarning?.({
126 - code: "placeholder.cap",
127 - message:
128 - "placeholder mapping cap reached; new placeholders are not restorable",
129 - severity: "warning",
130 - });
295 + this.warn(
296 + "placeholder.cap",
297 + "placeholder mapping cap reached; value left visible",
298 + );
301 + private warn(code: string, message: string) {
302 + this.onWarning?.({ code, message, severity: "warning" });
306 +function newGeneration(): GenerationRecord {
307 + return {
308 + version: 1,
309 + generationId: randomBytes(16).toString("hex"),
310 + rootKey: randomBytes(32).toString("base64url"),
311 + };
314 +function derive(root: Buffer, info: string) {
315 + return Buffer.from(hkdfSync("sha256", root, Buffer.alloc(0), info, 32));
318 +function aad(generationId: string, placeholder: string) {
319 + return Buffer.from(`1\0${generationId}\0${placeholder}`);
322 +function parseGeneration(data: unknown): GenerationRecord | undefined {
323 + if (!isRecord(data) || data.version !== 1) return undefined;
324 + if (
325 + typeof data.generationId !== "string" ||
326 + !/^[a-f0-9]{32}$/.test(data.generationId)
328 + return undefined;
329 + if (
330 + typeof data.rootKey !== "string" ||
331 + Buffer.from(data.rootKey, "base64url").length !== 32
333 + return undefined;
334 + return data as GenerationRecord;
337 +function parseMapping(data: unknown): MappingRecord | undefined {
338 + if (!isRecord(data) || data.version !== 1) return undefined;
339 + for (const key of [
340 + "generationId",
341 + "placeholder",
342 + "nonce",
343 + "ciphertext",
344 + "authTag",
345 + ])
346 + if (typeof data[key] !== "string") return undefined;
347 + PLACEHOLDER_RE.lastIndex = 0;
348 + const validPlaceholder = PLACEHOLDER_RE.test(data.placeholder as string);
349 + PLACEHOLDER_RE.lastIndex = 0;
350 + if (!validPlaceholder) return undefined;
351 + return data as MappingRecord;
354 +function isRecord(value: unknown): value is Record<string, unknown> {
355 + return value !== null && typeof value === "object" && !Array.isArray(value);