repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

fix(leaks): restrict redaction to plaintext surfaces

2cda9074ba0ae2c4bdbf06352c72c53ffad5b8b9

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (11)

extensions/leaks/README.md

Modified
4 4 # leaks
6 6 Provider-bound secret redaction for Pi.
8 8 `leaks` replaces only high-confidence secret values before provider requests.
9 9 Local Pi restores authenticated placeholders before tools and user-visible output.
10 +Protection covers explicit plaintext fields, not protocol envelopes: prompts, messages, tool data, and descriptive schema text.
11 +IDs, signatures, signed reasoning, encrypted state, auth headers, cache controls, and binary content stay unchanged.
12 +Unknown provider fields are not scanned automatically; see the [canonical routes](src/surfaces.ts) and [spec](SPEC.md).
11 14 ## Threat model
38 41 - `/leaks clear` appends a fresh generation after confirmation.
40 43 The extension registers no tools.
41 -Non-UI diagnostics go to stderr with a `[leaks]` prefix.
44 +Diagnostics use Pi notifications, never direct terminal output.
43 46 ## Settings

extensions/leaks/SPEC.md

Modified
60 60 Redaction must run on context copies and again on provider payloads.
61 61 Provider serialization may reshape or inject text after context processing.
63 +Traverse explicit plaintext fields, not every string in protocol envelopes.
64 +Cover system instructions, user and assistant text, unsigned thinking, readable reasoning summaries, tool arguments/results, tool descriptions, and schema descriptions/examples/defaults.
65 +Use the same field selection during context redaction, provider payload redaction, streaming restoration, finalized-message restoration, and unresolved-placeholder diagnostics.
66 +Preserve protocol field names, IDs, tool/model names, roles, signatures, encrypted state, auth headers, cache controls, usage, and image/audio/binary fields unchanged.
67 +Signed reasoning is provider-owned replay state, including its signed text; neither redaction nor restoration may modify it.
68 +Do not parse or reserialize a `thinkingSignature` inside `leaks`.
69 +Arbitrary tool argument/result data still uses deep string and property-name processing, even for names such as `thinkingSignature` or `encrypted_content`.
70 +Tool schema structure, property names, references, and validation patterns remain unchanged.
72 +Canonical plaintext routes are in `src/surfaces.ts`.
73 +They cover Pi messages, OpenAI Responses/Codex/Azure, Chat Completions/Mistral, Anthropic, Gemini/Vertex, and Bedrock Converse wire shapes.
74 +Unknown protocol fields and content-block types remain untouched; there is no recursive payload fallback.
75 +Unrecognized payload roots warn once and retain context-level protection only.
76 +A new provider-specific plaintext field requires an explicit route and regression test.
63 78 ## Core model
65 80 Provider sees placeholders.

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

Modified
251 251 await t.session.extensionRunner.emit("tool_call", {});
252 252 const provider = await t.session.extensionRunner.emitBeforeProviderRequest({
253 - text: `sk-or-v1-${"b".repeat(64)}`,
253 + instructions: `sk-or-v1-${"b".repeat(64)}`,
255 255 const message = await t.session.extensionRunner.emitMessageEnd({
256 256 type: "message_end",
257 257 message: {
258 258 role: "assistant",
259 - content: [{ type: "text", text: provider.text }],
259 + content: [{ type: "text", text: provider.instructions }],
261 261 } as never);
262 262 expect(JSON.stringify(message)).toContain("sk-or-v1-");

extensions/leaks/__tests__/harness.test.ts

Modified
157 + it("preserves protocol metadata across real Pi context, provider, and restoration hooks", async () => {
158 + t = await createTestSession({ extensions: [extPath()] });
159 + const runner = t.session.extensionRunner;
160 + const message = {
161 + role: "assistant",
162 + model: secret,
163 + responseId: secret,
164 + content: [
165 + { type: "text", text: secret, textSignature: secret },
166 + { type: "thinking", thinking: secret, thinkingSignature: secret },
167 + ],
168 + };
169 + const context = await runner.emitContext([message] as never);
170 + const placeholder = latestPlaceholder(t);
171 + expect(context[0]).toEqual({
172 + ...message,
173 + content: [
174 + { ...message.content[0], text: placeholder },
175 + message.content[1],
176 + ],
177 + });
178 + const headers = { authorization: secret };
179 + const payload = {
180 + model: secret,
181 + headers,
182 + messages: context,
183 + instructions: secret,
184 + };
185 + const provider = (await runner.emitBeforeProviderRequest(
186 + payload,
187 + )) as typeof payload;
188 + expect(provider.model).toBe(secret);
189 + expect(provider.headers).toEqual(headers);
190 + expect(provider.instructions).toBe(placeholder);
191 + const ended = await runner.emitMessageEnd({
192 + type: "message_end",
193 + message: context[0],
194 + } as never);
195 + expect(ended).toEqual(message);
196 + });
157 198 it("restores tool args and finalized assistant messages locally", async () => {
158 199 t = await createTestSession({ extensions: [extPath()] });
159 200 const redacted = await t.session.extensionRunner.emitBeforeProviderRequest({
160 - text: secret,
201 + instructions: secret,
162 203 const placeholder = JSON.stringify(redacted).match(
163 204 /__LEAK_V1_[A-Z0-9_]+_[a-f0-9]{32}__/,
188 229 const manager = t.session.sessionManager;
189 230 const runner = t.session.extensionRunner;
190 231 const firstResult = await runner.emitBeforeProviderRequest({
191 - text: secret,
232 + instructions: secret,
193 234 const firstPlaceholder = JSON.stringify(firstResult).match(
194 235 /__LEAK_V1_[A-Z0-9_]+_[a-f0-9]{32}__/,
217 258 const siblingFixture = "sk-or-v1-" + "e".repeat(64);
218 259 const secondResult = await runner.emitBeforeProviderRequest({
219 - text: siblingFixture,
260 + instructions: siblingFixture,
221 262 const secondPlaceholder = JSON.stringify(secondResult).match(
222 263 /__LEAK_V1_[A-Z0-9_]+_[a-f0-9]{32}__/,
336 377 t = await createTestSession({ cwd, extensions: [extPath()] });
338 379 const result = await t.session.extensionRunner.emitBeforeProviderRequest({
339 - text: dotenvSecret,
380 + instructions: dotenvSecret,
342 383 expect(JSON.stringify(result)).not.toContain(dotenvSecret);

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

Modified
1 1 import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
2 2 import { tmpdir } from "node:os";
3 3 import path from "node:path";
4 -import { describe, expect, it, vi } from "vitest";
4 +import { convertResponsesMessages } from "@earendil-works/pi-ai/api/openai-responses-shared";
5 +import { describe, expect, it } from "vitest";
5 6 import leaks from "../src/pi.ts";
7 8 type Handler = (event: any, ctx: any) => unknown | Promise<unknown>;
82 83 describe("leaks direct Pi hooks", () => {
84 + it("preserves opaque reasoning through restoration, context, and provider serialization", async () => {
85 + const runtime = fakePi();
86 + leaks(runtime.pi as never);
87 + const view = ui();
88 + await runtime.handlers.get("session_start")?.({}, view.ctx);
89 + const secret = "TOKEN_123";
90 + const redacted = await runtime.handlers.get("before_provider_request")?.(
91 + { payload: { instructions: secret } },
92 + view.ctx,
93 + );
94 + const placeholder = serialized(redacted).match(LEAK_PLACEHOLDER_RE)?.[0];
95 + expect(placeholder).toBeTruthy();
96 + const reasoning = {
97 + type: "reasoning",
98 + id: "rs_fixture",
99 + encrypted_content: `opaque_${secret}_${placeholder}_end`,
100 + summary: [{ type: "summary_text", text: secret }],
101 + };
102 + const thinkingSignature = JSON.stringify(reasoning, null, 2);
103 + const message = {
104 + role: "assistant",
105 + provider: "openai-codex",
106 + api: "openai-codex-responses",
107 + model: "fixture-model",
108 + content: [
109 + { type: "thinking", thinking: placeholder, thinkingSignature },
110 + { type: "text", text: placeholder },
111 + { type: "thinking", thinking: placeholder },
112 + ],
113 + };
114 + const updated = { message };
115 + await runtime.handlers.get("message_update")?.(updated, view.ctx);
116 + expect(updated.message.content[0].thinkingSignature).toBe(
117 + thinkingSignature,
118 + );
119 + expect(updated.message.content[0].thinking).toBe(placeholder);
120 + expect(updated.message.content[2].thinking).toBe(secret);
121 + const ended = (await runtime.handlers.get("message_end")?.(
122 + updated,
123 + view.ctx,
124 + )) as typeof updated;
125 + expect(ended.message.content[0].thinkingSignature).toBe(thinkingSignature);
126 + expect(ended.message.content[1].text).toBe(secret);
128 + const context = (await runtime.handlers.get("context")?.(
129 + { messages: [ended.message] },
130 + view.ctx,
131 + )) as { messages: (typeof message)[] };
132 + expect(context.messages[0].content[0].thinkingSignature).toBe(
133 + thinkingSignature,
134 + );
135 + expect(context.messages[0].content[0].thinking).toBe(placeholder);
136 + expect(context.messages[0].content[2].thinking).toBe(placeholder);
137 + expect(context.messages[0].content[1].text).toBe(placeholder);
138 + expect(ended.message.content[1].text).toBe(secret);
139 + const input = convertResponsesMessages(
141 + id: message.model,
142 + provider: message.provider,
143 + api: message.api,
144 + input: ["text"],
145 + } as never,
146 + context as never,
147 + new Set([message.provider]),
148 + );
149 + const payload = { input, instructions: secret };
150 + for (let attempt = 0; attempt < 2; attempt++) {
151 + const result = (await runtime.handlers.get("before_provider_request")?.(
152 + { payload },
153 + view.ctx,
154 + )) as { input: (typeof reasoning)[]; instructions: string };
155 + expect(result.input[0].encrypted_content).toBe(
156 + reasoning.encrypted_content,
157 + );
158 + expect(result.input[0].summary[0].text).toBe(placeholder);
159 + expect(result.instructions).toBe(placeholder);
161 + expect(payload.instructions).toBe(secret);
162 + expect(input[0]).toEqual(reasoning);
163 + });
165 + it("does not exempt protocol-looking fields in ordinary text and tool data", async () => {
166 + const runtime = fakePi();
167 + leaks(runtime.pi as never);
168 + const view = ui();
169 + await runtime.handlers.get("session_start")?.({}, view.ctx);
170 + const secret = "TOKEN_456";
171 + const data = {
172 + type: "reasoning",
173 + encrypted_content: secret,
174 + thinkingSignature: secret,
175 + nested: { type: "thinking", thinkingSignature: secret },
176 + };
177 + const messages = [
179 + role: "user",
180 + content: [{ type: "text", text: serialized(data) }],
181 + },
183 + role: "toolResult",
184 + content: [{ type: "text", text: serialized(data) }],
185 + details: data,
186 + },
188 + role: "assistant",
189 + content: [{ type: "toolCall", arguments: data }],
190 + },
191 + ];
192 + const context = await runtime.handlers.get("context")?.(
193 + { messages },
194 + view.ctx,
195 + );
196 + expect(serialized(context)).not.toContain(secret);
197 + const provider = await runtime.handlers.get("before_provider_request")?.(
199 + payload: {
200 + input: [{ type: "function_call", arguments: serialized(data) }],
201 + },
202 + },
203 + view.ctx,
204 + );
205 + expect(serialized(provider)).not.toContain(secret);
206 + const placeholder = serialized(provider).match(LEAK_PLACEHOLDER_RE)?.[0];
207 + expect(placeholder).toBeTruthy();
208 + const toolEvent = {
209 + toolName: "custom",
210 + input: JSON.parse(
211 + serialized(data).replaceAll(secret, placeholder as string),
212 + ),
213 + };
214 + await runtime.handlers.get("tool_call")?.(toolEvent, view.ctx);
215 + expect(toolEvent.input).toEqual(data);
216 + });
83 218 it("marks persistence degradation in the status footer", async () => {
84 219 const runtime = fakePi();
85 220 leaks(runtime.pi as never);
122 257 const custom = await runtime.handlers.get("before_provider_request")?.(
123 - { payload: { text: "TOKEN_123" } },
258 + { payload: { instructions: "TOKEN_123" } },
124 259 view.ctx,
126 261 expect(JSON.stringify(custom)).not.toContain("TOKEN_123");
133 268 expect(view.statuses.at(-1)).toMatch(/^󰒘  [1-9]/);
134 269 const providerClean = await runtime.handlers.get(
135 270 "before_provider_request",
136 - )?.({ payload: { text: "clean" } }, view.ctx);
137 - expect(providerClean).toEqual({ text: "clean" });
271 + )?.({ payload: { instructions: "clean" } }, view.ctx);
272 + expect(providerClean).toEqual({ instructions: "clean" });
138 273 const provider = await runtime.handlers.get("before_provider_request")?.(
139 - { payload: { text: secret } },
274 + { payload: { instructions: secret } },
140 275 view.ctx,
142 277 expect(JSON.stringify(provider)).not.toContain(secret);
146 281 await runtime.handlers.get("before_provider_request")?.(
147 - { payload: { text: secret } },
282 + { payload: { instructions: secret } },
148 283 { ...view.ctx, hasUI: false },
197 332 details: { diff: `+${secret}` },
199 334 const message = await runtime.handlers.get("message_end")?.(
200 - { message: placeholder },
336 + message: {
337 + role: "assistant",
338 + content: [{ type: "text", text: placeholder }],
339 + },
340 + },
201 341 view.ctx,
203 - expect(message).toEqual({ message: secret });
343 + expect(message).toEqual({
344 + message: { role: "assistant", content: [{ type: "text", text: secret }] },
345 + });
205 347 const command = runtime.commands.get("leaks");
206 348 if (!command) throw new Error("missing leaks command");
222 364 ).toBe(true);
225 - it("writes sanitized non-UI diagnostics only to stderr", async () => {
367 + it("does not emit diagnostics without a UI", async () => {
226 368 const runtime = fakePi();
227 369 leaks(runtime.pi as never);
228 370 const view = ui();
229 371 const ctx = { ...view.ctx, hasUI: false };
230 - const stderr = vi.spyOn(console, "error").mockImplementation(() => {});
231 - const stdout = vi.spyOn(console, "log").mockImplementation(() => {});
232 - try {
233 - await runtime.handlers.get("session_start")?.({}, ctx);
234 - await runtime.handlers.get("before_provider_request")?.(
235 - {
236 - payload: {
237 - text: "agendaFlick.visibleArea.yPosition",
238 - },
373 + await runtime.handlers.get("session_start")?.({}, ctx);
374 + await runtime.handlers.get("before_provider_request")?.(
376 + payload: {
377 + instructions: "agendaFlick.visibleArea.yPosition",
240 - ctx,
241 - );
242 - await runtime.commands.get("leaks")?.handler("status", ctx);
243 - expect(stderr.mock.calls.length).toBeGreaterThan(0);
244 - expect(
245 - stderr.mock.calls.every(([line]) =>
246 - String(line).startsWith("[leaks] "),
247 - ),
248 - ).toBe(true);
249 - expect(
250 - stderr.mock.calls.some(([line]) =>
251 - String(line).includes("agendaFlick"),
252 - ),
253 - ).toBe(false);
254 - expect(stdout).not.toHaveBeenCalled();
255 - } finally {
256 - stderr.mockRestore();
257 - stdout.mockRestore();
258 - }
379 + },
380 + ctx,
381 + );
382 + await runtime.commands.get("leaks")?.handler("status", ctx);
384 + expect(view.notices).toEqual([]);
261 387 it("reports repeated actionable ambiguity families once", async () => {
270 396 for (let index = 0; index < 2; index++)
271 397 await runtime.handlers.get("before_provider_request")?.(
272 - { payload: { text: secret } },
398 + { payload: { instructions: secret } },
273 399 view.ctx,
311 437 const secret = "ghp_" + "B".repeat(36);
312 438 const result = await runtime.handlers.get("before_provider_request")?.(
313 - { payload: { text: secret } },
439 + { payload: { instructions: secret } },
316 442 expect(JSON.stringify(result)).toContain(secret);
321 447 flushed = true;
322 448 const afterFlush = await runtime.handlers.get("before_provider_request")?.(
323 - { payload: { text: secret } },
449 + { payload: { instructions: secret } },
326 452 expect(JSON.stringify(afterFlush)).not.toContain(secret);
357 483 leaks(first.pi as never);
358 484 await first.handlers.get("session_start")?.({}, ctx);
359 485 const failed = await first.handlers.get("before_provider_request")?.(
360 - { payload: { text: secret } },
486 + { payload: { instructions: secret } },
363 489 expect(JSON.stringify(failed)).toContain(secret);
367 493 await reloaded.handlers.get("session_start")?.({}, ctx);
368 494 const afterReload = await reloaded.handlers.get(
369 495 "before_provider_request",
370 - )?.({ payload: { text: secret } }, ctx);
496 + )?.({ payload: { instructions: secret } }, ctx);
371 497 expect(JSON.stringify(afterReload)).toContain(secret);
372 498 await reloaded.commands.get("leaks")?.handler("clear", ctx);
373 499 expect(view.notices.at(-1)).toContain("clear failed");
388 514 const provider = await runtime.handlers.get("before_provider_request")?.(
389 - { payload: { text: secret } },
515 + { payload: { instructions: secret } },
400 526 const view = ui();
401 527 await runtime.handlers.get("session_start")?.({}, view.ctx);
402 528 const secret = "ghp_" + "S".repeat(36);
403 - const providerPayload = { nested: { text: secret } };
529 + const providerPayload = {
530 + input: [
531 + { type: "function_call", arguments: { nested: { text: secret } } },
532 + ],
533 + };
404 534 const provider = await runtime.handlers.get("before_provider_request")?.(
405 535 { payload: providerPayload },
406 536 view.ctx,
476 606 await runtime.handlers.get("session_start")?.({}, view.ctx);
477 607 const provider = await runtime.handlers.get("before_provider_request")?.(
478 - { payload: { text: "__proto__" } },
608 + { payload: { instructions: "__proto__" } },
479 609 view.ctx,
481 611 const placeholder =
497 627 const view = ui();
498 628 const secret = "ghp_" + "M".repeat(36);
499 629 const provider = await runtime.handlers.get("before_provider_request")?.(
500 - { payload: { text: secret } },
630 + { payload: { instructions: secret } },
501 631 view.ctx,
503 633 const placeholder =

extensions/leaks/__tests__/surfaces.test.ts

Added
new file mode 100644
1 +import { describe, expect, it } from "vitest";
2 +import { LeaksEngine } from "../src/engine.ts";
4 +const secret = "TOKEN_123";
5 +const opaque = "TOKEN_999 __LEAK_TOKEN_abcdef123456__";
7 +function engine() {
8 + return new LeaksEngine({
9 + settings: { regex: [{ pattern: "TOKEN_[0-9]+", label: "TOKEN" }] },
10 + });
13 +const fixtures: Array<[string, (text: string) => unknown]> = [
14 + [
15 + "OpenAI Responses and Codex",
16 + (text) => ({
17 + model: opaque,
18 + instructions: text,
19 + prompt_cache_key: opaque,
20 + previous_response_id: opaque,
21 + metadata: { text: opaque },
22 + text: { format: { name: opaque } },
23 + input: [
24 + { role: "user", content: [{ type: "input_text", text }] },
25 + {
26 + type: "message",
27 + id: opaque,
28 + role: "assistant",
29 + content: [{ type: "output_text", text, annotations: [opaque] }],
30 + },
31 + {
32 + type: "reasoning",
33 + id: opaque,
34 + encrypted_content: opaque,
35 + summary: [{ type: "summary_text", text }],
36 + },
37 + {
38 + type: "function_call",
39 + id: opaque,
40 + call_id: opaque,
41 + name: opaque,
42 + arguments: JSON.stringify({ thinkingSignature: text }),
43 + },
44 + {
45 + type: "function_call_output",
46 + call_id: opaque,
47 + output: [
48 + { type: "input_text", text },
49 + { type: "input_image", image_url: opaque },
50 + ],
51 + },
52 + { type: "custom_tool_call", name: opaque, input: text },
53 + { type: "custom_tool_call_output", call_id: opaque, output: text },
54 + { type: "compaction", encrypted_content: opaque },
55 + { type: "future_protocol", text: opaque },
56 + ],
57 + }),
58 + ],
59 + [
60 + "Anthropic",
61 + (text) => ({
62 + model: opaque,
63 + headers: { authorization: opaque },
64 + system: [{ type: "text", text, cache_control: { type: opaque } }],
65 + messages: [
66 + {
67 + role: "assistant",
68 + content: [
69 + { type: "text", text },
70 + { type: "thinking", thinking: text },
71 + { type: "thinking", thinking: opaque, signature: opaque },
72 + { type: "redacted_thinking", data: opaque },
73 + {
74 + type: "tool_use",
75 + id: opaque,
76 + name: opaque,
77 + input: { encrypted_content: text },
78 + },
79 + {
80 + type: "tool_result",
81 + tool_use_id: opaque,
82 + content: [{ type: "text", text }],
83 + },
84 + { type: "image", source: { type: "base64", data: opaque } },
85 + ],
86 + },
87 + ],
88 + }),
89 + ],
90 + [
91 + "Chat Completions and Mistral",
92 + (text) => ({
93 + model: opaque,
94 + messages: [
95 + { role: "system", content: text },
96 + {
97 + role: "user",
98 + content: [
99 + { type: "text", text },
100 + { type: "image_url", image_url: { url: opaque } },
101 + ],
102 + },
104 + role: "assistant",
105 + content: text,
106 + reasoning: text,
107 + reasoning_content: text,
108 + reasoning_details: [
109 + { type: "reasoning.text", text: opaque, signature: opaque },
110 + { type: "reasoning.text", text },
111 + { type: "reasoning.summary", summary: text },
112 + { type: "reasoning.encrypted", data: opaque },
113 + ],
114 + tool_calls: [
116 + id: opaque,
117 + type: "function",
118 + function: {
119 + name: opaque,
120 + arguments: JSON.stringify({ value: text }),
121 + },
122 + },
123 + ],
124 + },
125 + { role: "tool", tool_call_id: opaque, content: text },
126 + ],
127 + }),
128 + ],
130 + "Gemini and Vertex",
131 + (text) => ({
132 + model: opaque,
133 + config: {
134 + systemInstruction: text,
135 + cachedContent: opaque,
136 + httpOptions: { headers: { authorization: opaque } },
137 + },
138 + contents: [
140 + role: "model",
141 + parts: [
142 + { text },
143 + { thought: true, text: opaque, thoughtSignature: opaque },
145 + functionCall: {
146 + id: opaque,
147 + name: opaque,
148 + args: { signature: text },
149 + },
150 + thoughtSignature: opaque,
151 + },
153 + functionResponse: {
154 + id: opaque,
155 + name: opaque,
156 + response: { output: text },
157 + parts: [{ inlineData: { data: opaque, mimeType: opaque } }],
158 + },
159 + },
160 + { inlineData: { data: opaque, mimeType: opaque } },
161 + ],
162 + },
163 + ],
164 + }),
165 + ],
167 + "Bedrock Converse",
168 + (text) => ({
169 + modelId: opaque,
170 + system: [{ text }, { cachePoint: { type: opaque } }],
171 + messages: [
173 + role: "assistant",
174 + content: [
175 + { text },
176 + { reasoningContent: { reasoningText: { text } } },
178 + reasoningContent: {
179 + reasoningText: { text: opaque, signature: opaque },
180 + },
181 + },
183 + reasoningContent: { redactedContent: new Uint8Array([1, 2, 3]) },
184 + },
186 + toolUse: {
187 + toolUseId: opaque,
188 + name: opaque,
189 + input: { signature: text },
190 + },
191 + },
193 + toolResult: {
194 + toolUseId: opaque,
195 + status: opaque,
196 + content: [
197 + { text },
198 + { json: { value: text } },
199 + { image: { source: { bytes: opaque } } },
200 + ],
201 + },
202 + },
203 + ],
204 + },
205 + ],
206 + }),
207 + ],
209 + "Pi message gateway",
210 + (text) => ({
211 + model: opaque,
212 + options: { sessionId: opaque },
213 + context: {
214 + systemPrompt: text,
215 + messages: [
216 + { role: "user", content: text },
218 + role: "assistant",
219 + model: opaque,
220 + provider: opaque,
221 + responseId: opaque,
222 + content: [
223 + { type: "text", text, textSignature: opaque },
224 + { type: "thinking", thinking: text },
225 + { type: "thinking", thinking: opaque, thinkingSignature: opaque },
227 + type: "toolCall",
228 + id: opaque,
229 + name: opaque,
230 + arguments: { [text]: text },
231 + thoughtSignature: opaque,
232 + },
233 + ],
234 + usage: { diagnostic: opaque },
235 + },
237 + role: "toolResult",
238 + toolName: opaque,
239 + toolCallId: opaque,
240 + content: [
241 + { type: "text", text },
242 + { type: "image", data: opaque },
243 + ],
244 + details: { value: text },
245 + },
246 + ],
247 + },
248 + }),
249 + ],
252 +function schema(text: string) {
253 + return {
254 + type: "object",
255 + $id: opaque,
256 + required: [opaque],
257 + properties: {
258 + [opaque]: {
259 + type: "string",
260 + description: text,
261 + default: text,
262 + examples: [text],
263 + enum: [text],
264 + pattern: opaque,
265 + },
266 + },
267 + $defs: { [opaque]: { title: text, const: text } },
268 + allOf: [
270 + if: { description: text },
271 + // biome-ignore lint/suspicious/noThenProperty: JSON Schema conditional keyword, not a thenable.
272 + then: { description: text },
273 + else: { description: text },
274 + },
275 + ],
276 + additionalProperties: { description: text },
277 + };
280 +const toolFixtures: Array<[string, (text: string) => unknown]> = [
282 + "Responses",
283 + (text) => ({
284 + tools: [
286 + type: "function",
287 + name: opaque,
288 + description: text,
289 + parameters: schema(text),
290 + },
291 + ],
292 + }),
293 + ],
295 + "Completions",
296 + (text) => ({
297 + tools: [
299 + type: "function",
300 + function: {
301 + name: opaque,
302 + description: text,
303 + parameters: schema(text),
304 + },
305 + },
306 + ],
307 + }),
308 + ],
310 + "Anthropic",
311 + (text) => ({
312 + tools: [
314 + name: opaque,
315 + description: text,
316 + input_schema: schema(text),
317 + cache_control: { type: opaque },
318 + },
319 + ],
320 + }),
321 + ],
323 + "Gemini",
324 + (text) => ({
325 + config: {
326 + tools: [
328 + functionDeclarations: [
330 + name: opaque,
331 + description: text,
332 + parametersJsonSchema: schema(text),
333 + },
334 + ],
335 + },
336 + ],
337 + },
338 + }),
339 + ],
341 + "Bedrock",
342 + (text) => ({
343 + toolConfig: {
344 + tools: [
346 + toolSpec: {
347 + name: opaque,
348 + description: text,
349 + inputSchema: { json: schema(text) },
350 + },
351 + },
352 + ],
353 + },
354 + }),
355 + ],
357 + "deferred Responses tools",
358 + (text) => ({
359 + input: [
361 + type: "tool_search_output",
362 + call_id: opaque,
363 + tools: [
364 + { name: opaque, description: text, parameters: schema(text) },
365 + ],
366 + },
367 + ],
368 + }),
369 + ],
372 +describe("leaks plaintext surfaces", () => {
373 + it.each([...fixtures, ...toolFixtures])(
374 + "redacts only plaintext in %s",
375 + (_name, fixture) => {
376 + const runtime = engine();
377 + const placeholder = runtime.redactText(secret).text;
378 + const payload = fixture(secret);
379 + const result = runtime.redactDeep(payload, "provider", "provider");
380 + expect(result.value).toEqual(fixture(placeholder));
381 + expect(result.count).toBeGreaterThan(0);
382 + expect(runtime.restoreDeep(result.value, "provider").value).toEqual(
383 + payload,
384 + );
385 + expect(payload).toEqual(fixture(secret));
386 + },
387 + );
389 + it("leaves unknown payloads untouched and warns without a raw recursive fallback", () => {
390 + const runtime = engine();
391 + const payload = {
392 + customEnvelope: { text: secret },
393 + headers: { authorization: secret },
394 + };
395 + expect(runtime.redactDeep(payload, "provider", "provider").value).toEqual(
396 + payload,
397 + );
398 + runtime.redactDeep(payload, "provider", "provider");
399 + expect(
400 + runtime
401 + .stats()
402 + .warnings.filter((warning) => warning.code === "surface.provider"),
403 + ).toHaveLength(1);
404 + expect(runtime.stats().mappingCount).toBe(0);
405 + });
407 + it("does not scan signatures, binary fields, or metadata for unresolved placeholders", () => {
408 + const runtime = engine();
409 + const message = {
410 + role: "assistant",
411 + id: opaque,
412 + content: [
413 + { type: "thinking", thinking: opaque, thinkingSignature: opaque },
414 + { type: "text", text: "clean", textSignature: opaque },
415 + { type: "image", data: opaque },
416 + ],
417 + };
418 + expect(runtime.hydrateToolInput(message, "message")).toEqual({
419 + value: message,
420 + issue: undefined,
421 + });
422 + expect(runtime.redactDeep([message], "context", "context").count).toBe(0);
423 + expect(runtime.stats().mappingCount).toBe(0);
424 + });
426 + it.each(["google-generative-ai", "google-vertex"])(
427 + "preserves signed text in %s context before serialization",
428 + (api) => {
429 + const runtime = engine();
430 + const message = {
431 + role: "assistant",
432 + api,
433 + content: [
434 + { type: "text", text: opaque, textSignature: opaque },
435 + { type: "text", text: secret },
436 + ],
437 + };
438 + const result = runtime.redactDeep([message], "context", "context");
439 + expect(result.value[0].content[0]).toEqual(message.content[0]);
440 + expect(result.value[0].content[1].text).not.toContain(secret);
441 + expect(
442 + runtime.hydrateToolInput(result.value[0], "message").issue,
443 + ).toBeUndefined();
444 + },
445 + );
447 + it("still scans arbitrary tool data including protocol-looking names and values", () => {
448 + const runtime = engine();
449 + const data = {
450 + type: "reasoning",
451 + encrypted_content: secret,
452 + thinkingSignature: secret,
453 + nested: { [secret]: secret },
454 + };
455 + const result = runtime.redactDeep(data);
456 + expect(JSON.stringify(result.value)).not.toContain(secret);
457 + expect(runtime.hydrateToolInput(result.value)).toEqual({
458 + value: data,
459 + issue: undefined,
460 + });
461 + expect(
462 + runtime.hydrateToolInput({ encrypted_content: opaque }).issue,
463 + ).toBeDefined();
464 + });
465 +});

extensions/leaks/__tests__/unit.test.ts

Modified
4 4 import { describe, expect, it } from "vitest";
5 5 import { __test } from "../index.ts";
7 7 const fixtureSecret = "shell-fixture-secret-value-123456";
9 9 describe("leaks engine shell", () => {
10 + it.each([true, false])(
11 + "does not share opaque exemptions with ordinary aliases (protocol first: %s)",
12 + (protocolFirst) => {
13 + const engine = new __test.LeaksEngine();
14 + const secret = "ghp_" + "Q".repeat(36);
15 + const reasoning = { type: "reasoning", encrypted_content: secret };
16 + const call = { type: "function_call", arguments: reasoning };
17 + const input = protocolFirst ? [reasoning, call] : [call, reasoning];
18 + const result = engine.redactDeep({ input }, "provider", "provider");
19 + expect(result.value.input[protocolFirst ? 0 : 1]).toEqual(reasoning);
20 + expect(
21 + JSON.stringify(result.value.input[protocolFirst ? 1 : 0]),
22 + ).not.toContain(secret);
23 + expect(result.count).toBe(1);
24 + },
25 + );
27 + it("preserves opaque field names even when custom rules match them", () => {
28 + const engine = new __test.LeaksEngine({
29 + settings: {
30 + regex: [
31 + {
32 + pattern: "thinkingSignature|encrypted_content|TOKEN_[0-9]+",
33 + label: "TOKEN",
34 + },
35 + ],
36 + },
37 + });
38 + const message = {
39 + role: "assistant",
40 + content: [
41 + {
42 + type: "thinking",
43 + thinkingSignature: "TOKEN_123",
44 + thinking: "TOKEN_123",
45 + },
46 + { type: "thinking", thinking: "TOKEN_123" },
47 + ],
48 + };
49 + const context = engine.redactDeep([message], "context", "context");
50 + expect(context.value[0].content[0].thinkingSignature).toBe("TOKEN_123");
51 + expect(context.count).toBe(1);
52 + const payload = {
53 + input: [{ type: "reasoning", encrypted_content: "TOKEN_123" }],
54 + };
55 + const result = engine.redactDeep(payload, "provider", "provider");
56 + expect(result.value).toEqual(payload);
57 + expect(result.count).toBe(0);
58 + });
10 60 it("creates active engine with empty volatile state", () => {
11 61 const engine = new __test.LeaksEngine();

extensions/leaks/__tests__/ux.test.ts

Modified
18 18 it("notifies once for a redacting provider turn and not for clean turns", async () => {
19 19 t = await createTestSession({ extensions: [extPath()] });
20 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
21 20 await t.session.extensionRunner.emitBeforeProviderRequest({
22 - text: "ordinary metadata",
21 + instructions: secret,
22 + });
23 + await t.session.extensionRunner.emitBeforeProviderRequest({
24 + instructions: "ordinary text",
25 27 const notices = t.events
33 35 it("does not re-notify the same redacted value across provider turns", async () => {
34 36 t = await createTestSession({ extensions: [extPath()] });
35 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
36 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
37 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
37 + await t.session.extensionRunner.emitBeforeProviderRequest({
38 + instructions: secret,
39 + });
40 + await t.session.extensionRunner.emitBeforeProviderRequest({
41 + instructions: secret,
42 + });
43 + await t.session.extensionRunner.emitBeforeProviderRequest({
44 + instructions: secret,
45 + });
39 47 const notices = t.events
40 48 .uiCallsFor("notify")
53 61 t.session.extensionRunner.extensions[0].commands.get("leaks");
54 62 const ctx = t.session.extensionRunner.createContext();
56 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
57 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
64 + await t.session.extensionRunner.emitBeforeProviderRequest({
65 + instructions: secret,
66 + });
67 + await t.session.extensionRunner.emitBeforeProviderRequest({
68 + instructions: secret,
69 + });
58 70 await command.handler("clear", ctx);
59 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
71 + await t.session.extensionRunner.emitBeforeProviderRequest({
72 + instructions: secret,
73 + });
61 75 const notices = t.events
62 76 .uiCallsFor("notify")
80 94 await t.session.extensionRunner.emitBeforeProviderRequest({
81 - text: `first ${oldSecret}`,
95 + instructions: `first ${oldSecret}`,
83 97 await t.session.extensionRunner.emitBeforeProviderRequest({
84 - text: `again ${oldSecret} and now ${newSecret}`,
98 + instructions: `again ${oldSecret} and now ${newSecret}`,
87 101 const leakNotices = t.events
128 142 input: [
130 144 arguments: `Cookie: session=${sessionSecret}; auth=${authSecret}; theme=dark`,
145 + type: "function_call",
157 172 '\n\n\tpi.on("session_shutdown", async (_event, ctx)' +
159 174 secretValue,
175 + type: "function_call",
172 188 it("status reports required safe fields", async () => {
173 189 t = await createTestSession({ extensions: [extPath()] });
174 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
190 + await t.session.extensionRunner.emitBeforeProviderRequest({
191 + instructions: secret,
192 + });
175 193 const command =
176 194 t.session.extensionRunner.extensions[0].commands.get("leaks");
177 195 await command.handler("status", t.session.extensionRunner.createContext());
210 228 await command.handler("test " + secret, ctx);
211 229 await command.handler("reload", ctx);
212 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
230 + await t.session.extensionRunner.emitBeforeProviderRequest({
231 + instructions: secret,
232 + });
213 233 await command.handler("clear", ctx);
214 234 await command.handler("status", ctx);
231 251 extensions: [extPath()],
232 252 mockUI: { confirm: false },
234 - await t.session.extensionRunner.emitBeforeProviderRequest({ text: secret });
254 + await t.session.extensionRunner.emitBeforeProviderRequest({
255 + instructions: secret,
256 + });
235 257 const command =
236 258 t.session.extensionRunner.extensions[0].commands.get("leaks");
237 259 await command.handler("clear", t.session.extensionRunner.createContext());

extensions/leaks/src/engine.ts

Modified
14 14 customRegexSpans,
15 15 } from "./settings.ts";
16 16 import { findStructureAmbiguities, findStructureSpans } from "./structures.ts";
17 +import {
18 + isPlaintextPosition,
19 + type TextPosition,
20 + type TextSurface,
21 + textFieldPosition,
22 +} from "./surfaces.ts";
17 23 import type {
18 24 DeepRedactionResult,
19 25 Detector,
159 165 redactDeep<T>(
160 166 value: T,
161 167 origin: RedactionOrigin = "provider",
168 + surface?: TextSurface,
162 169 ): DeepRedactionResult<T> {
163 - return this.walk(value, origin, false);
170 + return this.walk(value, origin, false, surface);
166 173 configurePersistence(
178 185 return this.placeholders.restore(text);
181 - hydrateToolInput<T>(value: T): {
188 + hydrateToolInput<T>(
189 + value: T,
190 + surface?: TextSurface,
191 + ): {
182 192 value: T;
183 193 issue?: { path: string; label: string };
185 - const keyIssue = this.inspectHydratedKeys(value);
195 + const keyIssue = this.inspectHydratedKeys(value, surface);
186 196 if (keyIssue) return { value, issue: keyIssue };
187 - const restored = this.restoreDeep(value).value;
197 + const restored = this.restoreDeep(value, surface).value;
188 198 const seen = new WeakSet<object>();
189 199 const inspect = (
190 200 item: unknown,
191 201 depth: number,
192 202 path: string,
203 + position: TextPosition,
193 204 ): { path: string; label: string } | undefined => {
194 - if (typeof item === "string") {
205 + if (typeof item === "string" && isPlaintextPosition(position)) {
195 206 const unresolved = this.placeholders.unresolved(item)[0];
196 207 return unresolved
197 208 ? { path: path || "$", label: placeholderLabel(unresolved) }
204 215 seen.add(item);
205 216 if (Array.isArray(item)) {
206 217 for (let index = 0; index < item.length; index++) {
207 - const issue = inspect(item[index], depth + 1, `${path}[${index}]`);
218 + const issue = inspect(
219 + item[index],
220 + depth + 1,
221 + `${path}[${index}]`,
222 + position,
223 + );
208 224 if (issue) {
209 225 seen.delete(item);
210 226 return issue;
218 234 return { path: path || "$", label: "UNSUPPORTED_OBJECT" };
220 236 for (const [index, [key, child]] of Object.entries(item).entries()) {
237 + const childPosition = textFieldPosition(position, item, key);
238 + if (childPosition === undefined) continue;
221 239 const keyPath = childPath(path, index);
222 - const keyIssue = inspect(key, depth + 1, `${keyPath}.key`);
240 + const keyIssue =
241 + position === "data"
242 + ? inspect(key, depth + 1, `${keyPath}.key`, "data")
243 + : undefined;
223 244 if (keyIssue) {
224 245 seen.delete(item);
225 246 return keyIssue;
227 - const issue = inspect(child, depth + 1, keyPath);
248 + const issue = inspect(child, depth + 1, keyPath, childPosition);
228 249 if (issue) {
229 250 seen.delete(item);
230 251 return issue;
233 254 seen.delete(item);
234 255 return undefined;
236 - return { value: restored, issue: inspect(restored, 0, "") };
257 + return {
258 + value: restored,
259 + issue: inspect(restored, 0, "", surface ?? "data"),
260 + };
239 - restoreDeep<T>(value: T): DeepRedactionResult<T> {
240 - return this.walk(value, "provider", true);
263 + restoreDeep<T>(value: T, surface?: TextSurface): DeepRedactionResult<T> {
264 + return this.walk(value, "provider", true, surface);
243 - private inspectHydratedKeys(value: unknown) {
267 + private inspectHydratedKeys(value: unknown, surface?: TextSurface) {
244 268 const stack = new WeakSet<object>();
245 269 const visit = (
246 270 item: unknown,
247 271 depth: number,
248 272 path: string,
273 + position: TextPosition,
249 274 ): { path: string; label: string } | undefined => {
250 275 if (item === null || typeof item !== "object") return undefined;
251 276 if (depth >= 64) return { path: path || "$", label: "TRAVERSAL_DEPTH" };
254 279 stack.add(item);
255 280 if (Array.isArray(item)) {
256 281 for (let index = 0; index < item.length; index++) {
257 - const issue = visit(item[index], depth + 1, `${path}[${index}]`);
282 + const issue = visit(
283 + item[index],
284 + depth + 1,
285 + `${path}[${index}]`,
286 + position,
287 + );
258 288 if (issue) {
259 289 stack.delete(item);
260 290 return issue;
270 300 const keys = new Set<string>();
271 301 for (const [index, [key, child]] of Object.entries(item).entries()) {
302 + const childPosition = textFieldPosition(position, item, key);
303 + if (childPosition === undefined) continue;
272 304 const keyPath = childPath(path, index);
273 - const hydrated = this.restoreText(key);
274 - const unresolved = this.placeholders.unresolved(hydrated)[0];
305 + const hydrated = position === "data" ? this.restoreText(key) : key;
306 + const unresolved =
307 + position === "data"
308 + ? this.placeholders.unresolved(hydrated)[0]
309 + : undefined;
275 310 if (unresolved) {
276 311 stack.delete(item);
277 312 return {
284 319 return { path: `${keyPath}.key`, label: "KEY_COLLISION" };
286 321 keys.add(hydrated);
287 - const issue = visit(child, depth + 1, keyPath);
322 + const issue = visit(child, depth + 1, keyPath, childPosition);
288 323 if (issue) {
289 324 stack.delete(item);
290 325 return issue;
293 328 stack.delete(item);
294 329 return undefined;
296 - return visit(value, 0, "");
331 + return visit(value, 0, "", surface ?? "data");
299 334 clear() {
355 390 input: T,
356 391 origin: RedactionOrigin,
357 392 restore: boolean,
393 + surface?: TextSurface,
358 394 ): DeepRedactionResult<T> {
359 - const seen = new WeakMap<object, unknown>();
395 + if (
396 + surface === "provider" &&
397 + (!isPlainObject(input) ||
398 + !Object.keys(input).some(
399 + (key) => textFieldPosition("provider", input, key) !== undefined,
400 + ))
401 + ) {
402 + this.warnOnce(
403 + "surface.provider",
404 + "unrecognized provider payload; only context plaintext is protected",
405 + );
407 + const seenByPosition = new Map<TextPosition, WeakMap<object, unknown>>();
360 408 const redactions: RedactionRecord[] = [];
361 409 const ambiguities: Array<{ path: string; family: string }> = [];
362 410 let count = 0;
363 411 let changed = false;
364 - const visit = (value: unknown, depth: number, trace: string): unknown => {
412 + const visit = (
413 + value: unknown,
414 + depth: number,
415 + trace: string,
416 + position: TextPosition,
417 + ): unknown => {
365 418 if (typeof value === "string") {
419 + if (!isPlaintextPosition(position)) return value;
366 420 if (restore) {
367 421 const next = this.restoreText(value);
368 422 if (next !== value) {
389 443 return value;
445 + // The same object can also appear outside its protocol-owned slot.
446 + let seen = seenByPosition.get(position);
447 + if (!seen) {
448 + seen = new WeakMap<object, unknown>();
449 + seenByPosition.set(position, seen);
391 451 const cached = seen.get(value);
392 452 if (cached) {
393 453 this.warnOnce(
400 460 const copy: unknown[] = [];
401 461 seen.set(value, copy);
402 462 for (let index = 0; index < value.length; index++)
403 - copy.push(visit(value[index], depth + 1, `${trace}[${index}]`));
463 + copy.push(
464 + visit(value[index], depth + 1, `${trace}[${index}]`, position),
465 + );
404 466 if (copy.some((item, index) => item !== value[index])) changed = true;
405 467 return copy;
415 477 const copy: Record<string, unknown> = {};
416 478 seen.set(value, copy);
417 479 for (const [index, [key, item]] of Object.entries(source).entries()) {
480 + const childPosition = textFieldPosition(position, source, key);
418 481 const keyPath = `${childPath(trace, index)}.key`;
419 - let keyResult = this.restoreText(key);
420 - if (!restore) {
482 + let keyResult = position === "data" ? this.restoreText(key) : key;
483 + if (!restore && position === "data") {
421 484 const result = this.redactText(key, origin);
422 485 keyResult = result.text;
423 486 count += result.count;
427 490 ambiguities.push({ ...ambiguity, path: keyPath });
429 492 Object.defineProperty(copy, keyResult, {
430 - value: visit(item, depth + 1, childPath(trace, index)),
493 + value:
494 + childPosition === undefined
495 + ? item
496 + : visit(item, depth + 1, childPath(trace, index), childPosition),
431 497 enumerable: true,
432 498 configurable: true,
433 499 writable: true,
437 503 changed = true;
438 504 return copy;
440 - const value = visit(input, 0, "") as T;
506 + const value = visit(input, 0, "", surface ?? "data") as T;
441 507 if (origin === "provider" && !restore) {
442 508 this.lastProviderRedactionCount = count;
443 509 this.lastProviderAmbiguityCount = ambiguities.length;

extensions/leaks/src/pi.ts

Modified
8 8 import { LeaksEngine } from "./engine.ts";
9 9 import { isPlainObject, sanitizeTag } from "./safety.ts";
10 10 import { loadLeaksSettings } from "./settings.ts";
11 +import type { TextSurface } from "./surfaces.ts";
12 13 class NondurableAppendError extends Error {}
32 33 pi.on("context", async (event, ctx) => {
33 - const result = engine.redactDeep(event.messages, "context");
34 + const result = engine.redactDeep(event.messages, "context", "context");
34 35 updateLeakStatus(ctx, engine);
35 36 return { messages: result.value };
38 39 pi.on("before_provider_request", async (event, ctx) => {
39 40 if (ctx.sessionManager) rebuildPersistence(engine, pi, ctx, persistence);
40 - const result = engine.redactDeep(event.payload, "provider");
41 + const result = engine.redactDeep(event.payload, "provider", "provider");
41 42 try {
42 43 flushWarnings(engine, ctx, reportedWarnings);
43 44 updateProviderUi(ctx, engine, result, reportedWarnings);
102 103 "tool result",
103 104 reportedWarnings,
105 + "content",
105 107 warnUnknownLocal(
106 108 engine,
116 118 pi.on("message_end", async (event, ctx) => {
117 119 if (containsLeaksSourceMutation(event.message, ctx.cwd)) return;
118 - const restored = engine.restoreDeep(event.message).value;
120 + const restored = engine.restoreDeep(event.message, "message").value;
119 121 warnUnknownLocal(
120 122 engine,
121 123 restored,
123 125 "assistant message",
124 126 reportedWarnings,
127 + "message",
126 129 return { message: restored };
237 240 const current = event[key];
238 241 if (current === undefined) return;
239 - const restored = engine.restoreDeep(current).value;
242 + const restored = engine.restoreDeep(
243 + current,
244 + key === "message" ? "message" : undefined,
245 + ).value;
240 246 event[key] = restored;
241 247 copyRestoredInPlace(current, restored);
249 255 for (const key of ["content", "details"] as const) {
250 256 const current = event[key];
251 257 if (current === undefined) continue;
252 - const result = engine.restoreDeep(current);
258 + const result = engine.restoreDeep(
259 + current,
260 + key === "content" ? "content" : undefined,
261 + );
253 262 if (!result.changed) continue;
254 263 event[key] = result.value;
255 264 copyRestoredInPlace(current, result.value);
308 317 ctx: ExtensionContext,
309 318 surface: string,
310 319 reported: Set<string>,
320 + textSurface?: TextSurface,
312 322 if (value === undefined) return;
313 - const issue = engine.hydrateToolInput(value).issue;
323 + const issue = engine.hydrateToolInput(value, textSurface).issue;
315 325 !issue ||
316 326 issue.label.startsWith("TRAVERSAL_") ||
432 442 if (ctx.hasUI) ctx.ui.notify(message, severity);
433 - else console.error(`[leaks] ${message.replace(/\s*\n\s*/g, " | ")}`);
434 443 } catch {
435 444 // Diagnostics are best-effort and never alter extension behavior.

extensions/leaks/src/surfaces.ts

Added
new file mode 100644
1 +// Explicit plaintext routes through Pi and provider envelopes.
2 +// Everything else is protocol metadata and must remain untouched.
3 +export type TextSurface = "context" | "message" | "provider" | "content";
4 +export type TextPosition =
5 + | TextSurface
6 + | "data"
7 + | "text"
8 + | "response"
9 + | "call"
10 + | "result"
11 + | "tool"
12 + | "schema"
13 + | "schema-map"
14 + | "schema-wrapper"
15 + | "signed-content";
17 +const providerFields: Record<string, TextPosition> = {
18 + instructions: "text",
19 + systemPrompt: "text",
20 + system: "content",
21 + systemInstruction: "content",
22 + messages: "message",
23 + input: "response",
24 + contents: "message",
25 + context: "provider",
26 + config: "provider",
27 + tools: "tool",
28 + toolConfig: "provider",
29 +};
31 +const messageFields: Record<string, TextPosition> = {
32 + content: "content",
33 + parts: "content",
34 + tool_calls: "call",
35 + function_call: "call",
36 + reasoning: "text",
37 + reasoning_content: "text",
38 + reasoning_details: "content",
39 + refusal: "text",
40 +};
42 +const toolFields: Record<string, TextPosition> = {
43 + description: "text",
44 + parameters: "schema",
45 + parametersJsonSchema: "schema",
46 + input_schema: "schema",
47 + inputSchema: "schema-wrapper",
48 + function: "tool",
49 + toolSpec: "tool",
50 + functionDeclarations: "tool",
51 + tools: "tool",
52 +};
54 +const schemaFields: Record<string, TextPosition> = {
55 + description: "text",
56 + title: "text",
57 + $comment: "text",
58 + default: "data",
59 + examples: "data",
60 + enum: "data",
61 + const: "data",
62 + properties: "schema-map",
63 + patternProperties: "schema-map",
64 + $defs: "schema-map",
65 + definitions: "schema-map",
66 + dependentSchemas: "schema-map",
67 + items: "schema",
68 + prefixItems: "schema",
69 + additionalProperties: "schema",
70 + unevaluatedProperties: "schema",
71 + unevaluatedItems: "schema",
72 + contains: "schema",
73 + propertyNames: "schema",
74 + allOf: "schema",
75 + anyOf: "schema",
76 + oneOf: "schema",
77 + not: "schema",
78 + if: "schema",
79 + else: "schema",
80 +};
82 +function route(fields: Record<string, TextPosition>, key: string) {
83 + return Object.hasOwn(fields, key) ? fields[key] : undefined;
86 +export function textFieldPosition(
87 + position: TextPosition,
88 + source: Record<string, unknown>,
89 + key: string,
90 +): TextPosition | undefined {
91 + switch (position) {
92 + case "data":
93 + return "data";
94 + case "provider":
95 + return route(providerFields, key);
96 + case "context":
97 + case "message":
98 + if (
99 + key === "content" &&
100 + (source.api === "google-generative-ai" ||
101 + source.api === "google-vertex")
103 + return "signed-content";
104 + if (source.role === "toolResult" && key === "details") return "data";
105 + return route(messageFields, key);
106 + case "response":
107 + switch (source.type) {
108 + case "reasoning":
109 + if (key === "summary" || key === "content") return "content";
110 + return undefined;
111 + case "function_call":
112 + case "tool_search_call":
113 + return key === "arguments" ? "data" : undefined;
114 + case "custom_tool_call":
115 + return key === "input" ? "text" : undefined;
116 + case "function_call_output":
117 + case "custom_tool_call_output":
118 + return key === "output" ? "content" : undefined;
119 + case "tool_search_output":
120 + return key === "tools" ? "tool" : undefined;
121 + case "message":
122 + return route(messageFields, key);
123 + default:
124 + return source.role ? route(messageFields, key) : undefined;
126 + case "signed-content":
127 + if (source.type === "text" && source.textSignature) return undefined;
128 + return textFieldPosition("content", source, key);
129 + case "content":
130 + if (source.type === "reasoning.text" && source.signature)
131 + return undefined;
132 + switch (source.type) {
133 + case "text":
134 + case "input_text":
135 + case "output_text":
136 + case "summary_text":
137 + case "reasoning.text":
138 + return key === "text" ? "text" : undefined;
139 + case "reasoning.summary":
140 + return key === "summary" ? "text" : undefined;
141 + case "thinking":
142 + // Signed reasoning is provider replay state, including its text.
143 + if (source.redacted || source.thinkingSignature || source.signature)
144 + return undefined;
145 + return key === "thinking" ? "content" : undefined;
146 + case "toolCall":
147 + return key === "arguments" ? "data" : undefined;
148 + case "tool_use":
149 + return key === "input" ? "data" : undefined;
150 + case "tool_result":
151 + return key === "content" ? "content" : undefined;
152 + case "refusal":
153 + return key === "refusal" ? "text" : undefined;
154 + case undefined:
155 + // Gemini parts and Bedrock content blocks have no type tag.
156 + if (key === "text")
157 + return source.signature || source.thoughtSignature
158 + ? undefined
159 + : "text";
160 + if (key === "json") return "data";
161 + if (key === "functionCall" || key === "toolUse") return "call";
162 + if (key === "functionResponse" || key === "toolResult")
163 + return "result";
164 + if (
165 + key === "reasoningContent" ||
166 + key === "reasoningText" ||
167 + key === "parts"
169 + return "content";
170 + return undefined;
171 + default:
172 + return undefined;
174 + case "call":
175 + if (key === "arguments" || key === "args" || key === "input")
176 + return "data";
177 + if (key === "function" || key === "custom") return "call";
178 + return undefined;
179 + case "result":
180 + if (key === "response") return "data";
181 + if (key === "content" || key === "parts") return "content";
182 + return undefined;
183 + case "tool":
184 + return route(toolFields, key);
185 + case "schema":
186 + return key === "then" ? "schema" : route(schemaFields, key);
187 + case "schema-map":
188 + return "schema";
189 + case "schema-wrapper":
190 + return key === "json" ? "schema" : undefined;
191 + case "text":
192 + return undefined;
196 +export function isPlaintextPosition(position: TextPosition) {
197 + return (
198 + position === "data" ||
199 + position === "text" ||
200 + position === "content" ||
201 + position === "response"
202 + );