@tormentalabs/claude-code-wire-compat 0.6.0 → 0.7.0-rc.1

package/src/redaction.ts

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { MAX_INPUT_SIZE } from "./limits.js";
+
 import type {
   ClaudeCodeCapabilityDecisions,
   ClaudeCodeModelFamily,
@@ -10,6 +12,11 @@ import type {
 } from "./contracts.js";
 import { ClaudeCodeWireError } from "./contracts.js";
 import { classifySurrogateAt } from "./unicode.js";
+import {
+  isValidViolationCodeUnit,
+  isValidViolationPath,
+  isValidViolationReason,
+} from "./violation.js";
 
 /** Excludes values used only while validating and assembling the request. */
 export type NormalizedRequestInput = Omit<
@@ -63,7 +70,6 @@ export interface BuildRedactedEvidenceInput {
 }
 
 const MAX_INPUT_DEPTH = 100;
-const MAX_INPUT_SIZE = 1_000_000;
 const ENDPOINT = "https://api.anthropic.com/v1/messages?beta=true";
 /**
  * The profile ids evidence may claim, spelled out here for the same reason
@@ -395,7 +401,7 @@ export function toSafeErrorDetails(
     "maximumDepth",
     "maximumSize",
   ] as const;
-  const booleanKeys = ["hasSystem", "hasTools"] as const;
+  const booleanKeys = ["hasSystem", "hasTools", "violationInKey"] as const;
 
   for (const key of numericKeys) {
     const descriptor = Object.getOwnPropertyDescriptor(safeDetails, key);
@@ -415,6 +421,60 @@ export function toSafeErrorDetails(
         : undefined;
     if (typeof detail === "boolean") details[key] = detail;
   }
+
+  // Violation diagnostics (P1.T1, D4): strings pass only through closed-set
+  // or pattern validators, and numbers only through integer/range guards, so
+  // no caller text, key name or excerpt can ride these fields out of an error.
+  const stringValidators: Readonly<Record<string, (value: string) => boolean>> =
+    {
+      violationReason: isValidViolationReason,
+      violationPath: isValidViolationPath,
+    };
+  for (const [key, validator] of Object.entries(stringValidators)) {
+    const descriptor = Object.getOwnPropertyDescriptor(safeDetails, key);
+    const detail: unknown =
+      descriptor !== undefined && "value" in descriptor
+        ? descriptor.value
+        : undefined;
+    if (typeof detail === "string" && validator(detail)) {
+      details[key] = detail;
+    }
+  }
+  const integerKeys = ["violationOffset", "violationTextLength"] as const;
+  for (const key of integerKeys) {
+    const descriptor = Object.getOwnPropertyDescriptor(safeDetails, key);
+    const detail: unknown =
+      descriptor !== undefined && "value" in descriptor
+        ? descriptor.value
+        : undefined;
+    if (
+      typeof detail === "number" &&
+      Number.isSafeInteger(detail) &&
+      !Object.is(detail, -0) &&
+      detail >= 0 &&
+      detail <= MAX_INPUT_SIZE
+    ) {
+      details[key] = detail;
+    }
+  }
+  {
+    const descriptor = Object.getOwnPropertyDescriptor(
+      safeDetails,
+      "violationCodeUnit",
+    );
+    const detail: unknown =
+      descriptor !== undefined && "value" in descriptor
+        ? descriptor.value
+        : undefined;
+    if (
+      typeof detail === "number" &&
+      isValidViolationCodeUnit(detail) &&
+      ((details["violationReason"] === "lone-surrogate" && detail >= 0xd800) ||
+        (details["violationReason"] === "control-char" && detail <= 0x9f))
+    ) {
+      details["violationCodeUnit"] = detail;
+    }
+  }
   return Object.freeze(details);
 }
 

package/src/request-body.ts

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { MAX_INPUT_SIZE as MAX_SIZE } from "./limits.js";
+
 import { CLAUDE_CODE_2_1_195_PROFILE } from "./profiles/claude-code-2.1.195.js";
 import { clampMaxTokens, resolveThinking } from "./thinking.js";
 import type { ThinkingDisplay, ThinkingRequest } from "./thinking.js";
@@ -29,11 +31,15 @@ import type {
 import { deriveCapabilities } from "./model-capabilities.js";
 import { stripModelMarkers } from "./model-identity.js";
 import { IDENTITY_TEXT } from "./system-prompt.js";
-import { classifySurrogateAt } from "./unicode.js";
+import {
+  inspectText,
+  TEXT_POLICY_IDENTIFIER,
+  TEXT_POLICY_PROSE,
+} from "./unicode.js";
+import { violationDetails, type ViolationPathSegment } from "./violation.js";
 
 const MAX_DEPTH = 100;
 const MAX_ITEMS = 100_000;
-const MAX_SIZE = 1_000_000;
 const FORBIDDEN_KEYS = new Set(["__proto__", "prototype", "constructor"]);
 const MESSAGE_KEYS = new Set(["role", "content"]);
 const CACHE_CONTROL_KEYS = new Set(["type", "ttl"]);
@@ -364,8 +370,9 @@ type ModelResolution = Readonly<{
 
 function fail(
   code: ConstructorParameters<typeof ClaudeCodeWireError>[0],
+  safeDetails: Readonly<Record<string, string | number | boolean>> = {},
 ): never {
-  throw new ClaudeCodeWireError(code);
+  throw new ClaudeCodeWireError(code, safeDetails);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -380,25 +387,21 @@ function inspectString(
   value: string,
   state: InspectionState,
   validateString?: (value: string) => void,
+  path: readonly ViolationPathSegment[] = [],
+  inKey = false,
 ): void {
   state.size += value.length;
   if (state.size > MAX_SIZE) fail("INPUT_TOO_LARGE");
   validateString?.(value);
 
-  for (let index = 0; index < value.length; index += 1) {
-    const unit = value.charCodeAt(index);
-    if (
-      unit <= 0x08 ||
-      unit === 0x0b ||
-      unit === 0x0c ||
-      (unit >= 0x0e && unit <= 0x1f) ||
-      unit === 0x7f
-    ) {
-      fail("INVALID_INPUT");
-    }
-    const classification = classifySurrogateAt(value, index);
-    if (classification === "loneSurrogate") fail("INVALID_UNICODE");
-    if (classification === "surrogatePair") index += 1;
+  // Body prose policy (P1.T1): only a lone surrogate can fail here now, so
+  // the historical INVALID_INPUT-for-controls branch is gone by construction.
+  const violation = inspectText(value, TEXT_POLICY_PROSE);
+  if (violation !== null) {
+    fail(
+      "INVALID_UNICODE",
+      violationDetails(violation, path, value.length, inKey),
+    );
   }
 }
 
@@ -407,11 +410,12 @@ function inspect(
   depth: number,
   state: InspectionState,
   validateString?: (value: string) => void,
+  path: ViolationPathSegment[] = [],
 ): void {
   if (depth > MAX_DEPTH) fail("INPUT_TOO_DEEP");
   if (value === null || typeof value === "boolean") return;
   if (typeof value === "string") {
-    inspectString(value, state, validateString);
+    inspectString(value, state, validateString, path, false);
     return;
   }
   if (typeof value === "number") {
@@ -430,7 +434,9 @@ function inspect(
     if (state.size > MAX_SIZE) fail("INPUT_TOO_LARGE");
     for (let index = 0; index < value.length; index += 1) {
       if (!hasOwn(value, String(index))) fail("INVALID_INPUT");
-      inspect(value[index], depth + 1, state, validateString);
+      path.push(index);
+      inspect(value[index], depth + 1, state, validateString, path);
+      path.pop();
     }
   } else {
     const prototype = Reflect.getPrototypeOf(value);
@@ -441,27 +447,37 @@ function inspect(
       if (typeof key !== "string" || FORBIDDEN_KEYS.has(key)) {
         fail("INVALID_INPUT");
       }
-      inspectString(key, state, validateString);
+      // Object keys stay strings: digits inside user keys must not become
+      // readable numeric path segments (QA F1).
+      path.push(key);
+      inspectString(key, state, validateString, path, true);
       const descriptor = Object.getOwnPropertyDescriptor(value, key);
       if (descriptor === undefined || !("value" in descriptor)) {
         fail("INVALID_INPUT");
       }
-      inspect(descriptor.value, depth + 1, state, validateString);
+      inspect(descriptor.value, depth + 1, state, validateString, path);
+      path.pop();
     }
   }
   state.active.delete(value);
 }
 
+/** Paths without a caller hint are relative to the inspected value's root. */
 export function inspectJsonInputs(
   values: readonly unknown[],
   validateString?: (value: string) => void,
+  paths?: readonly (readonly ViolationPathSegment[])[],
 ): void {
   const state: InspectionState = {
     active: new WeakSet(),
     items: 0,
     size: 0,
   };
-  for (const value of values) inspect(value, 0, state, validateString);
+  for (let index = 0; index < values.length; index += 1) {
+    inspect(values[index], 0, state, validateString, [
+      ...(paths?.[index] ?? []),
+    ]);
+  }
 }
 
 function requireRecord(value: unknown): Record<string, unknown> {
@@ -483,6 +499,13 @@ function requireString(value: unknown): string {
   return value;
 }
 
+function requireIdentifier(value: unknown): string {
+  const text = requireString(value);
+  if (inspectText(text, TEXT_POLICY_IDENTIFIER) !== null)
+    fail("INVALID_UNICODE");
+  return text;
+}
+
 function requirePositiveInteger(value: unknown): number {
   if (!Number.isSafeInteger(value) || typeof value !== "number" || value <= 0) {
     fail("INVALID_INPUT");
@@ -829,7 +852,7 @@ function imageSource(value: unknown): ImageBlock["source"] {
       )
         fail("INVALID_INPUT");
       entries.push([key, item]);
-    } else entries.push([key, requireString(item)]);
+    } else entries.push([key, requireIdentifier(item)]);
   }
   return Object.fromEntries(entries) as unknown as ImageBlock["source"];
 }
@@ -890,7 +913,11 @@ function documentSource(value: unknown): DocumentBlock["source"] {
           }),
         ]);
       }
-    } else entries.push([key, requireString(item)]);
+    } else
+      entries.push([
+        key,
+        type === "text" ? requireString(item) : requireIdentifier(item),
+      ]);
   }
   return Object.fromEntries(entries) as unknown as DocumentBlock["source"];
 }
@@ -925,7 +952,11 @@ function thinkingBlock(
     if (key === "type") entries.push([key, "thinking"]);
     else if (key === "cache_control")
       entries.push([key, nullable(item, cacheControl)]);
-    else entries.push([key, requireString(item)]);
+    else
+      entries.push([
+        key,
+        key === "signature" ? requireIdentifier(item) : requireString(item),
+      ]);
   }
   return Object.fromEntries(entries) as unknown as ThinkingBlock;
 }
@@ -950,7 +981,7 @@ function redactedThinkingBlock(
     if (key === "type") entries.push([key, "redacted_thinking"]);
     else if (key === "cache_control")
       entries.push([key, nullable(item, cacheControl)]);
-    else entries.push([key, requireString(item)]);
+    else entries.push([key, requireIdentifier(item)]);
   }
   return Object.fromEntries(entries) as unknown as RedactedThinkingBlock;
 }
@@ -966,8 +997,8 @@ function searchResultBlock(value: unknown): SearchResultBlock {
     if (key === "content") {
       if (!Array.isArray(item)) fail("INVALID_INPUT");
       entries.push([key, item.map((block) => textBlock(block))]);
-    } else if (key === "source" || key === "title")
-      entries.push([key, requireString(item)]);
+    } else if (key === "source") entries.push([key, requireIdentifier(item)]);
+    else if (key === "title") entries.push([key, requireString(item)]);
     else if (key === "type") entries.push([key, "search_result"]);
     else if (key === "cache_control")
       entries.push([key, nullable(item, cacheControl)]);
@@ -984,7 +1015,7 @@ function toolReferenceBlock(value: unknown): ToolReferenceBlock {
   const entries: [string, unknown][] = [];
   for (const key of Object.keys(record)) {
     const item = record[key];
-    if (key === "tool_name") entries.push([key, requireString(item)]);
+    if (key === "tool_name") entries.push([key, requireIdentifier(item)]);
     else if (key === "type") entries.push([key, "tool_reference"]);
     else entries.push([key, nullable(item, cacheControl)]);
   }
@@ -1000,7 +1031,7 @@ function toolUseBlock(value: unknown): ToolUseBlock {
   for (const key of Object.keys(record)) {
     const item = record[key];
     if (key === "id" || key === "name")
-      entries.push([key, requireString(item)]);
+      entries.push([key, requireIdentifier(item)]);
     else if (key === "input") entries.push([key, validatedJson(item)]);
     else if (key === "type") entries.push([key, "tool_use"]);
     else if (key === "cache_control")
@@ -1025,7 +1056,7 @@ function toolCaller(value: unknown): ToolUseBlock["caller"] {
   return Object.fromEntries(
     Object.keys(record).map((key) => [
       key,
-      key === "type" ? type : requireString(record[key]),
+      key === "type" ? type : requireIdentifier(record[key]),
     ]),
   ) as unknown as NonNullable<ToolUseBlock["caller"]>;
 }
@@ -1048,7 +1079,7 @@ function toolResultBlock(value: unknown): ToolResultBlock {
   const entries: [string, unknown][] = [];
   for (const key of Object.keys(record)) {
     const item = record[key];
-    if (key === "tool_use_id") entries.push([key, requireString(item)]);
+    if (key === "tool_use_id") entries.push([key, requireIdentifier(item)]);
     else if (key === "type") entries.push([key, "tool_result"]);
     else if (key === "cache_control")
       entries.push([key, nullable(item, cacheControl)]);
@@ -1327,8 +1358,8 @@ function customToolDefinition(record: Record<string, unknown>): ToolDefinition {
   for (const key of Object.keys(record)) {
     const item = record[key];
     if (key === "input_schema") entries.push([key, toolInputSchema(item)]);
-    else if (key === "name" || key === "description")
-      entries.push([key, requireString(item)]);
+    else if (key === "name") entries.push([key, requireIdentifier(item)]);
+    else if (key === "description") entries.push([key, requireString(item)]);
     else if (key === "allowed_callers")
       entries.push([key, allowedCallers(item)]);
     else if (key === "cache_control")
@@ -1357,7 +1388,7 @@ function builtInToolDefinition(
       if (item !== spec.name) fail("INVALID_INPUT");
       entries.push([key, item]);
     } else if (key === "mcp_server_name" || key === "model")
-      entries.push([key, requireString(item)]);
+      entries.push([key, requireIdentifier(item)]);
     else if (key === "allowed_callers")
       entries.push([key, allowedCallers(item)]);
     else if (key === "cache_control" || key === "caching")
@@ -1401,7 +1432,7 @@ function tools(value: unknown): readonly ToolDefinition[] {
       ? builtInToolDefinition(record)
       : customToolDefinition(record);
     if (hasOwn(record, "name")) {
-      const name = requireString(record["name"]);
+      const name = requireIdentifier(record["name"]);
       if (names.has(name)) fail("INVALID_INPUT");
       names.add(name);
     }
@@ -1462,8 +1493,8 @@ function modelResolution(
     fail("INVALID_INPUT");
   }
   return {
-    id: requireString(record["id"]),
-    wireId: requireString(record["wireId"]),
+    id: requireIdentifier(record["id"]),
+    wireId: requireIdentifier(record["wireId"]),
     capabilities: {
       thinking: capabilityBoolean(capabilities.thinking, derived.thinking),
       adaptiveThinking: capabilityBoolean(
@@ -1647,7 +1678,8 @@ function toolChoice(value: unknown): Readonly<Record<string, unknown>> {
   const entries: [string, unknown][] = [];
   for (const key of Object.keys(record)) {
     if (key === "type") entries.push([key, type]);
-    else if (key === "name") entries.push([key, requireString(record[key])]);
+    else if (key === "name")
+      entries.push([key, requireIdentifier(record[key])]);
     else entries.push([key, requireBoolean(record[key])]);
   }
   return Object.fromEntries(entries);
@@ -1747,13 +1779,17 @@ export function buildCanonicalBody(
   profile?: ClaudeCodeProtocolProfile,
   thinkingDisplayOverride?: "updates",
 ): Readonly<Record<string, unknown>> {
-  inspectJsonInputs([
-    rawInput,
-    rawResolvedModel,
-    rawSystemBlocks,
-    rawMetadata,
-    ...(profile === undefined ? [] : [profile]),
-  ]);
+  inspectJsonInputs(
+    [
+      rawInput,
+      rawResolvedModel,
+      rawSystemBlocks,
+      rawMetadata,
+      ...(profile === undefined ? [] : [profile]),
+    ],
+    undefined,
+    [[], ["model"], ["system"], ["metadata"], ["profileOverride"]],
+  );
 
   const input = requireRecord(rawInput);
   assertExactKeys(input, INPUT_KEY_SET);

package/src/system-prompt.ts

@@ -1,12 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { MAX_INPUT_SIZE } from "./limits.js";
+
 import type {
   ClaudeCodeRuntimeIdentity,
   SystemInput,
   TextBlock,
 } from "./contracts.js";
 import { ClaudeCodeWireError } from "./contracts.js";
-import { classifySurrogateAt } from "./unicode.js";
+import { inspectText, TEXT_POLICY_PROSE } from "./unicode.js";
+import { violationDetails, type ViolationPathSegment } from "./violation.js";
 
 /**
  * The pinned identity text, byte-exact.
@@ -26,7 +29,6 @@ import { classifySurrogateAt } from "./unicode.js";
 export const IDENTITY_TEXT =
   "You are Claude Code, Anthropic's official CLI for Claude.";
 const MAX_INPUT_DEPTH = 64;
-const MAX_INPUT_SIZE = 1_000_000;
 type UnknownRecord = Readonly<Record<PropertyKey, unknown>>;
 
 function fail(
@@ -36,38 +38,34 @@ function fail(
     | "INPUT_TOO_DEEP"
     | "INPUT_TOO_LARGE"
     | "CYCLIC_INPUT",
+  safeDetails: Readonly<Record<string, string | number | boolean>> = {},
 ): never {
-  throw new ClaudeCodeWireError(code);
+  throw new ClaudeCodeWireError(code, safeDetails);
 }
 
-function validateText(text: string): void {
-  for (let index = 0; index < text.length; index += 1) {
-    const codeUnit = text.charCodeAt(index);
-
-    if (
-      codeUnit === 0 ||
-      (codeUnit < 0x20 &&
-        codeUnit !== 0x09 &&
-        codeUnit !== 0x0a &&
-        codeUnit !== 0x0d) ||
-      (codeUnit >= 0x7f && codeUnit <= 0x9f)
-    ) {
-      fail("INVALID_UNICODE");
-    }
-
-    const classification = classifySurrogateAt(text, index);
-    if (classification === "loneSurrogate") fail("INVALID_UNICODE");
-    if (classification === "surrogatePair") index += 1;
+function validateText(
+  text: string,
+  path: readonly ViolationPathSegment[],
+  inKey: boolean,
+): void {
+  // Body prose policy (P1.T1): the system field follows the same rule as
+  // every other body lane — only lone surrogates are rejected.
+  const violation = inspectText(text, TEXT_POLICY_PROSE);
+  if (violation !== null) {
+    fail(
+      "INVALID_UNICODE",
+      violationDetails(violation, path, text.length, inKey),
+    );
   }
 }
 
 function isUnknownRecord(value: unknown): value is UnknownRecord {
   return value !== null && typeof value === "object";
 }
-
 function validateStructure(value: unknown): void {
   const ancestors = new WeakSet();
   let size = 0;
+  const path: ViolationPathSegment[] = ["system"];
 
   function visit(current: unknown, depth: number): void {
     if (depth > MAX_INPUT_DEPTH) fail("INPUT_TOO_DEEP");
@@ -75,7 +73,7 @@ function validateStructure(value: unknown): void {
     if (typeof current === "string") {
       size += current.length;
       if (size > MAX_INPUT_SIZE) fail("INPUT_TOO_LARGE");
-      validateText(current);
+      validateText(current, path, false);
       return;
     }
 
@@ -84,12 +82,22 @@ function validateStructure(value: unknown): void {
 
     ancestors.add(current);
     for (const key of Reflect.ownKeys(current)) {
+      // Only ARRAY indices become numeric segments (QA F1/F4); object keys
+      // stay strings and digits inside them render as `*`.
+      const segment: ViolationPathSegment =
+        typeof key !== "string"
+          ? "*"
+          : Array.isArray(current) && /^(?:0|[1-9]\d{0,5})$/u.test(key)
+            ? Number(key)
+            : key;
+      path.push(segment);
       if (typeof key === "string") {
         size += key.length;
         if (size > MAX_INPUT_SIZE) fail("INPUT_TOO_LARGE");
-        validateText(key);
+        validateText(key, path, true);
       }
       visit(current[key], depth + 1);
+      path.pop();
     }
     ancestors.delete(current);
   }

package/src/unicode.ts

@@ -22,3 +22,74 @@ export function classifySurrogateAt(
   if (unit >= 0xdc00 && unit <= 0xdfff) return "loneSurrogate";
   return "notSurrogate";
 }
+
+export type TextViolationReason = "control-char" | "lone-surrogate";
+
+/**
+ * One character-level policy violation found while screening a string.
+ *
+ * `offset` is the UTF-16 code-unit index of the offending unit and `codeUnit`
+ * is the unit itself. Both are safe diagnostics: offsets are numbers and the
+ * only code units ever reported are control characters or surrogate halves,
+ * never prose content.
+ */
+export interface TextViolation {
+  readonly reason: TextViolationReason;
+  readonly offset: number;
+  readonly codeUnit: number;
+}
+
+/**
+ * Character-level acceptance policy for one string lane.
+ *
+ * `rejectControls` rejects every C0 control except TAB (0x09), LF (0x0A) and
+ * CR (0x0D), plus DEL (0x7F). Lone surrogates are always rejected, rather than
+ * depending on whether a caller serializes or directly encodes the string.
+ */
+export interface TextPolicy {
+  readonly rejectControls: boolean;
+}
+
+/** Body prose: every well-formed UTF-16 string is accepted. */
+export const TEXT_POLICY_PROSE: TextPolicy = Object.freeze({
+  rejectControls: false,
+});
+
+/**
+ * Identifier graph screening: C0 except TAB/LF/CR, plus DEL, plus lone
+ * surrogates. This is exactly the set the graph inspectors rejected before the
+ * shared validator existed.
+ */
+export const TEXT_POLICY_IDENTIFIER: TextPolicy = Object.freeze({
+  rejectControls: true,
+});
+
+/**
+ * Screens one string under `policy`, returning the first violation or null.
+ *
+ * The walk order matches the historical per-module inspectors: at each index
+ * the control check runs before the surrogate check, and a well-formed pair
+ * consumes two code units. `classifySurrogateAt` is the single surrogate
+ * authority; this function never re-implements it.
+ */
+export function inspectText(
+  value: string,
+  policy: TextPolicy,
+): TextViolation | null {
+  for (let index = 0; index < value.length; index += 1) {
+    const unit = value.charCodeAt(index);
+    if (
+      policy.rejectControls &&
+      ((unit <= 0x1f && unit !== 0x09 && unit !== 0x0a && unit !== 0x0d) ||
+        unit === 0x7f)
+    ) {
+      return { reason: "control-char", offset: index, codeUnit: unit };
+    }
+    const classification = classifySurrogateAt(value, index);
+    if (classification === "loneSurrogate") {
+      return { reason: "lone-surrogate", offset: index, codeUnit: unit };
+    }
+    if (classification === "surrogatePair") index += 1;
+  }
+  return null;
+}