llm-switcher 1.1.3 → 1.1.5

package/README.md

@@ -191,7 +191,15 @@ flowchart LR
 
 ---
 
-## Changes in 1.1.3
+## Changes in 1.1.5
+
+- **Contract lab privacy.** Masking now uses an allowlist. Every string value is masked except the enum values that intact reads. 1.1.4 masked a list of content keys and missed 16 fields (citations, document and web titles, web search queries, logprobs tokens, file names and URIs, stop sequences, participant names, error messages, tool descriptions).
+
+### Changes in 1.1.4
+
+- **Contract lab privacy.** A sample that the gateway sends to intact carries no client content. Prompts, answers, tool arguments and results, files and user ids are masked on this machine before the upload. The fields that intact needs for analysis stay.
+
+### Changes in 1.1.3
 
 - **Dashboard.** Opened without its access token, the page no longer waits on "Checking status...". It says that it is locked and names `switch ui`, which opens it with the token.
 - **Dashboard.** The Codex model names (session, review, subagent) are on the **Models** tab, next to the other model settings. The **Blindfold** tab holds only the interceptor settings.
@@ -552,6 +560,8 @@ re-opened from a shell where the shim is on `PATH`.
 
 The contract lab finds fields that the converter loses. It is off by default.
 
+Before it sends a sample, the gateway masks every string value with `x` of the same length. Only the short enum values that intact reads stay: `type`, `role`, `object`, `model`, `status`, `event`, `finish_reason` and `stop_reason`. Numbers, flags, SSE event names and the keys of the API also stay. Inside user data (tool arguments, tool input, `metadata`) the keys are masked too. intact keeps only the length of any other string, so the analysis loses nothing.
+
 - Set `contractLab: {url, apiKey, enabled}` in `config.json`. If `enabled` is `true`, the gateway sends a sample of complete exchanges to intact.
 - `switch contract-probe [--model m]` sends six test requests per model and format through the gateway.
 - `switch contract-check` gets the open findings from intact and writes one test file for each lost field.

package/README.vi.md

@@ -191,7 +191,15 @@ flowchart LR
 
 ---
 
-## Thay đổi trong bản 1.1.3
+## Thay đổi trong bản 1.1.5
+
+- **Bảo mật contract lab.** Việc che giờ dùng allowlist. Mọi giá trị string đều bị che, trừ các giá trị enum mà intact đọc. Bản 1.1.4 che theo danh sách key nội dung và bỏ sót 16 field (trích dẫn, tiêu đề tài liệu và trang web, câu truy vấn web search, token logprobs, tên và URI file, stop sequence, tên người tham gia, thông báo lỗi, mô tả tool).
+
+### Thay đổi trong bản 1.1.4
+
+- **Bảo mật contract lab.** Mẫu mà gateway gửi lên intact không chứa nội dung của client. Prompt, câu trả lời, tham số và kết quả của tool, file và user id bị che ngay trên máy trước khi gửi. Các field mà intact cần để phân tích được giữ nguyên.
+
+### Thay đổi trong bản 1.1.3
 
 - **Dashboard.** Khi mở mà thiếu access token, trang không còn đứng ở "Checking status...". Trang báo đang bị khoá và chỉ lệnh `switch ui`, lệnh này mở trang kèm token.
 - **Dashboard.** Tên model của Codex (session, review, subagent) nằm ở tab **Models**, cạnh các cấu hình model khác. Tab **Blindfold** chỉ còn cấu hình interceptor.
@@ -552,6 +560,8 @@ trong `PATH`.
 
 Contract lab tìm các field mà converter làm mất. Mặc định tính năng này tắt.
 
+Trước khi gửi mẫu, gateway che mọi giá trị string bằng chuỗi `x` cùng độ dài. Chỉ các giá trị enum ngắn mà intact đọc được giữ nguyên: `type`, `role`, `object`, `model`, `status`, `event`, `finish_reason` và `stop_reason`. Số, flag, tên event SSE và tên key của API cũng được giữ. Trong dữ liệu người dùng (tham số tool, input của tool, `metadata`), tên key cũng bị che. intact chỉ lưu độ dài của các string khác, nên phân tích không mất gì.
+
 - Đặt `contractLab: {url, apiKey, enabled}` trong `config.json`. Nếu `enabled` là `true`, gateway gửi một phần các lượt trao đổi hoàn chỉnh lên intact.
 - `switch contract-probe [--model m]` gửi sáu request thử cho mỗi model và mỗi format qua gateway.
 - `switch contract-check` lấy các finding còn mở từ intact và ghi một file test cho mỗi field bị mất.

package/contract.mjs

@@ -61,6 +61,64 @@ export function switcherVersion() {
 }
 
 /** Copies what the gateway writes to the client. Past the cap the side is dropped, not cut. */
+// ---------------- masking of client content ----------------
+// A half leaves this machine, so every string value is masked with "x" of the same byte length,
+// except the enum values that intact's reducer reads: the same key list, value shape and exclusions as
+// enumLeafNames / validEnumValue in intact internal/contract/reduce.go. The reducer keeps only the
+// length and a hash of any other string, so masking it loses nothing for the analysis. An allowlist,
+// not a list of content keys: a new content field in any API is masked by default.
+const ENUM_KEYS = new Set(['type', 'role', 'object', 'finish_reason', 'stop_reason', 'status', 'event', 'model']);
+const ENUM_VALUE_RE = /^[A-Za-z0-9_.:/-]{1,64}$/;
+// Under these the reducer collapses keys to {*}: they hold user data, so their keys are masked too.
+const DATA_PARENTS = new Set(['args', 'arguments', 'metadata', 'client_metadata', 'extra_body', 'headers']);
+const SSE_EVENT_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+const maskString = (s) => 'x'.repeat(Buffer.byteLength(s));
+
+// ctx.data: inside user data (a data parent, a JSON string, a tool's input) — no enum kept, keys masked.
+function maskValue(v, key = '', ctx = { data: false }) {
+  if (typeof v === 'string') {
+    if (!ctx.data && ENUM_KEYS.has(key) && ENUM_VALUE_RE.test(v)) return v;
+    const t = v.trim();
+    if ((t.startsWith('{') && t.endsWith('}')) || (t.startsWith('[') && t.endsWith(']'))) {
+      try { return JSON.stringify(maskValue(JSON.parse(t), key, { data: true })); } catch {}
+    }
+    return maskString(v);
+  }
+  if (Array.isArray(v)) return v.map((c) => maskValue(c, key, ctx));
+  if (!v || typeof v !== 'object') return v;
+  const out = {};
+  let i = 0;
+  for (const [k, c] of Object.entries(v)) {
+    const data = ctx.data || DATA_PARENTS.has(k) || (k === 'input' && c && typeof c === 'object' && !Array.isArray(c));
+    out[ctx.data ? `k${i++}` : k] = maskValue(c, k, { data });
+  }
+  return out;
+}
+
+/** Masks the client's content in a request or response body: JSON, SSE, or anything else (masked whole). */
+export function maskHalf(text) {
+  if (!text) return '';
+  try { return JSON.stringify(maskValue(JSON.parse(text))); } catch {}
+  const lines = text.split('\n');
+  if (!lines.some((l) => l.startsWith('data:'))) return maskString(text);
+  return lines.map((raw) => {
+    const cr = raw.endsWith('\r') ? '\r' : '';
+    const line = cr ? raw.slice(0, -1) : raw;
+    if (line === '' || line.startsWith(':')) return raw;
+    if (line.startsWith('event:')) {
+      const name = line.slice(6).trim();
+      return (SSE_EVENT_RE.test(name) ? line : `event: ${maskString(name)}`) + cr;
+    }
+    if (line.startsWith('data:')) {
+      const data = line.slice(5).trim();
+      if (data === '[DONE]') return raw;
+      try { return `data: ${JSON.stringify(maskValue(JSON.parse(data)))}${cr}`; } catch { return `data: ${maskString(data)}${cr}`; }
+    }
+    return maskString(line) + cr;
+  }).join('\n');
+}
+
 export function createHalfTap(limit = MAX_HALF_BYTES) {
   const chunks = [];
   let size = 0;
@@ -206,8 +264,8 @@ export function createContractLab(options = {}) {
 
   async function send(s, { traceId, half }) {
     const body = JSON.stringify({
-      toolRequest: half.toolRequest || '',
-      toolResponse: half.toolResponse || '',
+      toolRequest: maskHalf(half.toolRequest || ''),
+      toolResponse: maskHalf(half.toolResponse || ''),
       ...(half.toolVersion ? { toolVersion: half.toolVersion } : {}),
       switcherVersion: version(),
       converter: { inFormat: half.inFormat, outFormat: half.outFormat }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code, Codex, OpenAI and Gemini clients",
   "keywords": [
     "llm",

package/tests/contract-lab.test.mjs

@@ -398,8 +398,13 @@ test('the half of a sampled request reaches intact with the exchange and the ver
   assert.deepEqual(last.body.converter, { inFormat: 'anthropic', outFormat: 'anthropic' });
   assert.equal(last.body.toolVersion, '1.2.3');
   assert.match(last.body.switcherVersion, SWITCHER_VERSION_RE);
-  assert.equal(JSON.parse(last.body.toolRequest).messages[0].content, 'hello');
-  assert.equal(JSON.parse(last.body.toolResponse).content[0].text, 'direct ok');
+  // The client's content never leaves the machine: it arrives masked, same length; the shape stays.
+  const sentReq = JSON.parse(last.body.toolRequest);
+  assert.equal(sentReq.messages[0].content, 'x'.repeat('hello'.length));
+  assert.equal(sentReq.messages[0].role, 'user');
+  assert.equal(sentReq.model, 'claude-opus-4-6');
+  assert.equal(JSON.parse(last.body.toolResponse).content[0].text, 'x'.repeat('direct ok'.length));
+  assert.ok(!last.body.toolRequest.includes('hello') && !last.body.toolResponse.includes('direct ok'), 'no raw content in the half');
 });
 
 test('with intact at a closed port the tool answer is byte-identical to the answer with the lab off', async () => {
@@ -552,9 +557,9 @@ test('a sampled Codex WS turn is tagged and its half reaches intact', async () =
   assert.match(body.switcherVersion, SWITCHER_VERSION_RE);
   const asked = JSON.parse(body.toolRequest);
   assert.equal(asked.type, 'response.create');
-  assert.equal(asked.input, 'hello over ws');
+  assert.equal(asked.input, 'x'.repeat('hello over ws'.length), 'the WS request is masked');
   assert.ok(body.toolResponse.includes('event: response.completed'), 'the half holds the events the turn wrote');
-  assert.ok(body.toolResponse.includes('ws ok'), 'the answer text is in the half');
+  assert.ok(!body.toolResponse.includes('ws ok'), 'the answer text is masked in the half');
 });
 
 test('a Codex WS client can never choose the trace id, and a down intact leaves the turn unchanged', async () => {

package/tests/contract-mask-leaks.test.mjs

@@ -0,0 +1,58 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { maskHalf } from '../contract.mjs';
+
+// The 16 leaks of the 1.1.4 report, plus the positions 1.1.4 already covered. A marker anywhere in a
+// value must not survive, whatever the key; only the enum values intact's reducer reads may stay.
+const M = (tag) => `LEAK_${tag}`;
+const cases = {
+  anthropic_citation: { content: [{ type: 'text', text: 'x', citations: [{ type: 'char_location', cited_text: M('cited_text'), document_title: M('document_title') }] }] },
+  anthropic_document: { messages: [{ role: 'user', content: [{ type: 'document', title: M('doc_title'), context: M('doc_context'), source: { type: 'text', media_type: 'text/plain', data: M('doc_data') } }] }] },
+  anthropic_web_result: { content: [{ type: 'web_search_tool_result', tool_use_id: 't', content: [{ type: 'web_search_result', url: M('url'), title: M('web_title'), encrypted_content: M('enc') }] }] },
+  anthropic_thinking: { content: [{ type: 'thinking', thinking: M('thinking'), signature: 'SIG_opaque' }] },
+  anthropic_system_blocks: { system: [{ type: 'text', text: M('system_block') }] },
+  anthropic_stop: { stop_sequences: [M('stop_seq')], stop_sequence: M('stop_sequence_resp') },
+  openai_logprobs: { choices: [{ logprobs: { content: [{ token: M('token'), top_logprobs: [{ token: M('top_token') }] }] } }] },
+  openai_name: { messages: [{ role: 'user', name: M('participant_name'), content: 'x' }] },
+  openai_tool_msg: { messages: [{ role: 'tool', tool_call_id: 'c1', content: M('tool_content') }] },
+  responses_annotation: { output: [{ type: 'message', content: [{ type: 'output_text', text: 'x', annotations: [{ type: 'url_citation', url: M('ann_url'), title: M('ann_title') }] }] }] },
+  responses_websearch: { output: [{ type: 'web_search_call', action: { type: 'search', query: M('search_query') } }] },
+  responses_input_items: { input: [{ type: 'message', role: 'user', content: [{ type: 'input_text', text: M('input_text') }] }, { type: 'function_call_output', call_id: 'c', output: M('fc_output') }, { type: 'input_file', filename: M('filename'), file_data: M('file_data') }] },
+  gemini_filedata: { contents: [{ role: 'user', parts: [{ fileData: { mimeType: 'application/pdf', fileUri: M('fileUri') } }, { text: M('gemini_text') }] }] },
+  gemini_func: { contents: [{ parts: [{ functionCall: { name: 'f', args: { q: M('fc_args') } } }, { functionResponse: { name: 'f', response: { r: M('fr_resp') } } }] }] },
+  error_echo: { type: 'error', error: { type: 'invalid_request_error', message: M('error_message') } },
+  tool_desc: { tools: [{ name: 'Bash', description: M('tool_description'), input_schema: { type: 'object' } }] },
+  // An enum key does not keep free text: a value with a space, or one under user data, is masked.
+  enum_free_text: { type: `${M('type_text')} with space`, metadata: { type: M('meta_type') }, model: M('model_ok') },
+  json_keys: { messages: [{ role: 'assistant', tool_calls: [{ type: 'function', function: { name: 'f', arguments: JSON.stringify({ [M('arg_key')]: 1 }) } }] }] }
+};
+
+for (const [name, obj] of Object.entries(cases)) {
+  test(`no marker survives: ${name}`, () => {
+    const out = maskHalf(JSON.stringify(obj));
+    const left = (out.match(/LEAK_[A-Za-z_]+/g) || []).filter((m) => m !== 'LEAK_model_ok');
+    assert.deepEqual(left, [], out);
+  });
+}
+
+test('the enum values the reducer reads stay as sent', () => {
+  const out = JSON.parse(maskHalf(JSON.stringify({
+    model: 'claude-opus-4-6', type: 'message', role: 'assistant', stop_reason: 'end_turn', object: 'chat.completion',
+    content: [{ type: 'tool_use', id: 'toolu_1', name: 'Bash', input: { command: 'ls' } }], usage: { input_tokens: 3 }
+  })));
+  assert.equal(out.model, 'claude-opus-4-6');
+  assert.equal(out.type, 'message');
+  assert.equal(out.role, 'assistant');
+  assert.equal(out.stop_reason, 'end_turn');
+  assert.equal(out.object, 'chat.completion');
+  assert.equal(out.content[0].type, 'tool_use');
+  assert.equal(out.usage.input_tokens, 3);
+  assert.match(out.content[0].name, /^x+$/);
+});
+
+test('SSE with CRLF and a non-JSON data line leaks nothing', () => {
+  const sse = 'event: message_delta\ndata: {"type":"content_block_delta","delta":{"type":"text_delta","text":"LEAK_sse_text"}}\r\n\r\ndata: not json LEAK_sse_raw\n\n';
+  const out = maskHalf(sse);
+  assert.ok(!/LEAK_/.test(out), out);
+  assert.ok(out.includes('"text_delta"'));
+});

package/tests/contract-mask.test.mjs

@@ -0,0 +1,100 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { maskHalf } from '../contract.mjs';
+
+const SECRET = 'SECRET-PII-marker';
+const KEEP = 'keep-model-name';
+const bytes = (s) => Buffer.byteLength(s);
+
+// Every body puts SECRET in each place a client writes its own content, and KEEP in the model name,
+// an enum value that analysis needs. After masking, SECRET must be gone and KEEP must stay.
+const bodies = {
+  anthropic: {
+    model: KEEP, max_tokens: 64, system: [{ type: 'text', text: `sys ${SECRET}` }],
+    metadata: { user_id: `u ${SECRET}` },
+    tools: [{ name: 'get_weather', description: 'Current weather', input_schema: { type: 'object', properties: { city: { type: 'string' } } } }],
+    messages: [
+      { role: 'user', content: `hi ${SECRET}` },
+      { role: 'assistant', content: [{ type: 'thinking', thinking: `t ${SECRET}`, signature: 'sig' },
+        { type: 'tool_use', id: 'toolu_1', name: 'get_weather', input: { city: `c ${SECRET}` } }] },
+      { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_1', content: [{ type: 'text', text: `r ${SECRET}` }] },
+        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: `img ${SECRET}` } }] }
+    ]
+  },
+  openaiChat: {
+    model: KEEP, user: `u ${SECRET}`, temperature: 0.2,
+    messages: [
+      { role: 'system', content: `s ${SECRET}` },
+      { role: 'user', content: [{ type: 'text', text: `q ${SECRET}` }, { type: 'image_url', image_url: { url: `data:${SECRET}` } }] },
+      { role: 'assistant', content: null, tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'get_weather', arguments: JSON.stringify({ city: `c ${SECRET}` }) } }] },
+      { role: 'tool', tool_call_id: 'call_1', content: `o ${SECRET}` }
+    ]
+  },
+  responses: {
+    model: KEEP, instructions: `i ${SECRET}`,
+    input: [
+      { type: 'message', role: 'user', content: [{ type: 'input_text', text: `q ${SECRET}` }] },
+      { type: 'function_call', call_id: 'c1', name: 'get_weather', arguments: JSON.stringify({ city: `c ${SECRET}` }) },
+      { type: 'function_call_output', call_id: 'c1', output: `o ${SECRET}` },
+      { type: 'reasoning', summary: [{ type: 'summary_text', text: `r ${SECRET}` }], encrypted_content: `e ${SECRET}` }
+    ]
+  },
+  gemini: {
+    systemInstruction: { parts: [{ text: `s ${SECRET}` }] },
+    contents: [
+      { role: 'user', parts: [{ text: `q ${SECRET}` }] },
+      { role: 'model', parts: [{ functionCall: { name: 'get_weather', args: { city: `c ${SECRET}` } } }] },
+      { role: 'user', parts: [{ functionResponse: { name: 'get_weather', response: { temp: `t ${SECRET}` } } }] }
+    ]
+  }
+};
+
+for (const [name, body] of Object.entries(bodies)) {
+  test(`${name}: client content is masked, analysis fields stay`, () => {
+    const raw = JSON.stringify(body);
+    const out = maskHalf(raw);
+    assert.ok(!out.includes(SECRET), `${name} leaks content: ${out}`);
+    const parsed = JSON.parse(out);
+    if (body.model) assert.equal(parsed.model, KEEP);
+    assert.ok(!out.includes('get_weather'), 'tool names are not enum values: masked');
+    if (raw.includes('"type":')) assert.ok(out.includes('"type":'), 'types stay');
+  });
+}
+
+test('masking keeps the byte length of every masked string', () => {
+  const out = JSON.parse(maskHalf(JSON.stringify({ model: 'm', messages: [{ role: 'user', content: 'héllo wörld' }] })));
+  assert.equal(bytes(out.messages[0].content), bytes('héllo wörld'));
+  assert.match(out.messages[0].content, /^x+$/);
+});
+
+test('a JSON string argument keeps its shape and masks its keys and values', () => {
+  const out = JSON.parse(maskHalf(JSON.stringify(bodies.openaiChat)));
+  const args = JSON.parse(out.messages[2].tool_calls[0].function.arguments);
+  assert.equal(Object.keys(args).length, 1);
+  assert.ok(!('city' in args), 'keys of user data are masked: the reducer collapses them to {*}');
+  assert.match(Object.values(args)[0], /^x+$/);
+});
+
+test('an SSE stream masks every data line and keeps event names', () => {
+  const sse = [
+    'event: message_start', `data: ${JSON.stringify({ type: 'message_start', message: { model: KEEP, role: 'assistant', content: [] } })}`, '',
+    'event: content_block_delta', `data: ${JSON.stringify({ type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: `a ${SECRET}` } })}`, '',
+    `data: ${JSON.stringify({ choices: [{ index: 0, delta: { content: `b ${SECRET}` } }] })}`, '',
+    `data: ${JSON.stringify({ type: 'response.output_text.delta', delta: `c ${SECRET}` })}`, '',
+    'data: [DONE]', ''
+  ].join('\n');
+  const out = maskHalf(sse);
+  assert.ok(!out.includes(SECRET), out);
+  assert.ok(out.includes('event: content_block_delta'));
+  assert.ok(out.includes('"text_delta"') && out.includes(KEEP));
+  assert.ok(out.includes('data: [DONE]'));
+});
+
+test('text that is not JSON, or a cut body, is masked whole', () => {
+  const cut = JSON.stringify(bodies.anthropic).slice(0, 120);
+  for (const t of [`plain ${SECRET}`, cut]) {
+    const out = maskHalf(t);
+    assert.ok(!out.includes('SECRET'), out);
+    assert.equal(bytes(out), bytes(t));
+  }
+});