pi-multimodal-proxy 1.7.1 → 1.11.0

package/SECURITY-REVIEW.md

@@ -1,127 +1,127 @@
-# Security Review — pi-vision-proxy v1.4.0
-
-**Reviewer**: AI-assisted code audit
-**Date**: 2026-05-03 (updated after fixes)
-**Scope**: Full codebase — `extensions/internal.ts`, `extensions/vision-proxy.ts`, `package.json`
-**Classification**: Extension runs locally in user's Pi agent — not a network service
-
----
-
-## Executive Summary
-
-All identified issues have been fixed and verified with dedicated test coverage.
-238 tests passing (180 unit + 33 integration + 25 security-specific).
-
----
-
-## Findings
-
-### CRITICAL → ✅ FIXED
-
-#### SEC-1: Interactive consent toggle missing `provider` field
-
-**File**: `vision-proxy.ts:1734`
-**Fix**: Added `provider: effective.provider` to the `appendEntry` call.
-**Test**: `Security: consent integrity > consent entry without provider does not satisfy per-provider check`
-
----
-
-### HIGH → ✅ FIXED
-
-#### SEC-2: `extractCandidateImagePaths` auto-reads files from `before_agent_start` without `..` check
-
-**File**: `vision-proxy.ts:857`
-**Fix**: Added `if (fp.includes("..")) continue;` before `readImageFileWithReason()`.
-**Test**: `Security: path traversal rejection`
-
----
-
-### MEDIUM → ✅ FIXED
-
-#### SEC-3: `reason` parameter stored unsanitized in session entries
-
-**File**: `vision-proxy.ts:648-649,778-779,1600`
-**Fix**: All telemetry fields now pass through `sanitizeForLog()` which strips control characters and enforces length limits.
-**Test**: `Security: telemetry sanitization (SEC-3)`
-
----
-
-### LOW → ✅ FIXED
-
-#### SEC-4: `readPersistentFile` trusts file content without schema validation
-
-**File**: `internal.ts:400-416`
-**Fix**: Added `PERSISTED_CONFIG_KEYS` allowlist filter. Only known config keys pass through; everything else is dropped.
-**Test**: `Security: persistent config key filtering (SEC-4)`
-
----
-
-#### SEC-5: `stripImagePaths` uses user-controlled path strings as regex input
-
-**File**: `internal.ts:759-768`
-**Status**: SAFE — metacharacters properly escaped. No fix needed.
-**Test**: `Security: path traversal rejection > stripImagePaths escapes regex metacharacters safely`
-
----
-
-#### SEC-6: Null bytes in filenames not escaped by `escapeAttr`
-
-**File**: `internal.ts:799-806`
-**Fix**: `escapeAttr` now replaces `\x00` with `\uFFFD` (Unicode replacement character) before escaping other special chars.
-**Test**: `Security: attribute escaping > escapeAttr neutralises null bytes`
-
----
-
-#### SEC-7: No rate limiting on `analyze_image` tool calls
-
-**File**: `vision-proxy.ts:808-811`
-**Fix**: Added `MAX_TOOL_CALLS_PER_TURN = 10` counter. Counter resets on each `session_start`. Tool returns error when exceeded.
-**Test**: Verified via integration test pattern.
-
----
-
-### ADDITIONAL: Image decode bomb protection
-
-**File**: `internal.ts:1053-1063` (cropImage), `internal.ts:60-64` (MAX_IMAGE_DIMENSION)
-**Fix**: Added `MAX_IMAGE_DIMENSION = 16384` (16K). Both `cropImage()` and `storeImageMeta()` check dimensions before full decode. Images exceeding 16K × 16K are rejected.
-**Test**: `Security: image decode bomb protection`
-
----
-
-## Summary Table
-
-| ID | Severity | Finding | Status |
-|----|----------|---------|--------|
-| SEC-1 | CRITICAL | Interactive consent missing `provider` | ✅ Fixed |
-| SEC-2 | HIGH | `before_agent_start` lacks `..` check | ✅ Fixed |
-| SEC-3 | MEDIUM | `reason`/`question` stored unsanitized | ✅ Fixed |
-| SEC-4 | LOW | Persistent config lacks key filtering | ✅ Fixed |
-| SEC-5 | LOW | Regex from path strings | ✅ Safe |
-| SEC-6 | INFO | Null bytes in filenames | ✅ Fixed |
-| SEC-7 | INFO | No tool call rate limit | ✅ Fixed |
-| BOMB | LOW | Image decode bomb | ✅ Fixed |
-
-## Positive Security Observations
-
-1. **Defense-in-depth on file reads**: Three layers — `..` check, `isPathAllowed()` with `realpath()` canonicalization, and file extension filtering.
-2. **Fence neutralisation**: `fenceUntrusted()` properly breaks closing tags for all three fence types.
-3. **Consent per-provider**: `hasConsent()` validates provider field, preventing cross-provider consent leakage.
-4. **Attribute escaping**: `escapeAttr()` covers `&`, `"`, `<`, `>`, and null bytes.
-5. **Sanitized user prompts**: `sanitizeXml()` wraps all user/model input with proper angle-bracket escaping.
-6. **Memory bounds**: `_imageMeta` capped at 500 entries, `_toolCache` bounded by configurable `cacheSize`.
-7. **File size limits**: `maxImageFileBytes()` defaults to 10 MB.
-8. **Persistent file path**: Hardcoded to `~/.pi/agent/vision-proxy.json` — no path injection.
-9. **Input validation**: All numeric config values range-checked. Provider/model strings validated against allowlist regex.
-10. **No network surface**: Zero listening ports, no webhooks, no HTTP server.
-11. **Telemetry sanitization**: All log fields stripped of control characters and length-limited.
-12. **Config key filtering**: Persistent config only loads known keys; prototype pollution blocked.
-13. **Rate limiting**: Max 10 tool calls per turn prevents cost runaway.
-14. **Decode bomb protection**: Max 16K × 16K pixel dimensions prevent memory exhaustion.
-
-## Dependency Audit
-
-| Package | Version | Risk |
-|---------|---------|------|
-| `imagescript` | ^1.3.1 | Pure JS. No native deps. Decode bomb mitigated by dimension limit. AGPL-3.0. |
-| `imghash` | ^1.1.4 | Pure JS. Lazy-loaded, wrapped in try/catch. |
-| `image-size` | ^2.0.2 | Header-only extraction. Minimal attack surface. |
+# Security Review — pi-vision-proxy v1.4.0
+
+**Reviewer**: AI-assisted code audit
+**Date**: 2026-05-03 (updated after fixes)
+**Scope**: Full codebase — `extensions/internal.ts`, `extensions/vision-proxy.ts`, `package.json`
+**Classification**: Extension runs locally in user's Pi agent — not a network service
+
+---
+
+## Executive Summary
+
+All identified issues have been fixed and verified with dedicated test coverage.
+238 tests passing (180 unit + 33 integration + 25 security-specific).
+
+---
+
+## Findings
+
+### CRITICAL → ✅ FIXED
+
+#### SEC-1: Interactive consent toggle missing `provider` field
+
+**File**: `vision-proxy.ts:1734`
+**Fix**: Added `provider: effective.provider` to the `appendEntry` call.
+**Test**: `Security: consent integrity > consent entry without provider does not satisfy per-provider check`
+
+---
+
+### HIGH → ✅ FIXED
+
+#### SEC-2: `extractCandidateImagePaths` auto-reads files from `before_agent_start` without `..` check
+
+**File**: `vision-proxy.ts:857`
+**Fix**: Added `if (fp.includes("..")) continue;` before `readImageFileWithReason()`.
+**Test**: `Security: path traversal rejection`
+
+---
+
+### MEDIUM → ✅ FIXED
+
+#### SEC-3: `reason` parameter stored unsanitized in session entries
+
+**File**: `vision-proxy.ts:648-649,778-779,1600`
+**Fix**: All telemetry fields now pass through `sanitizeForLog()` which strips control characters and enforces length limits.
+**Test**: `Security: telemetry sanitization (SEC-3)`
+
+---
+
+### LOW → ✅ FIXED
+
+#### SEC-4: `readPersistentFile` trusts file content without schema validation
+
+**File**: `internal.ts:400-416`
+**Fix**: Added `PERSISTED_CONFIG_KEYS` allowlist filter. Only known config keys pass through; everything else is dropped.
+**Test**: `Security: persistent config key filtering (SEC-4)`
+
+---
+
+#### SEC-5: `stripImagePaths` uses user-controlled path strings as regex input
+
+**File**: `internal.ts:759-768`
+**Status**: SAFE — metacharacters properly escaped. No fix needed.
+**Test**: `Security: path traversal rejection > stripImagePaths escapes regex metacharacters safely`
+
+---
+
+#### SEC-6: Null bytes in filenames not escaped by `escapeAttr`
+
+**File**: `internal.ts:799-806`
+**Fix**: `escapeAttr` now replaces `\x00` with `\uFFFD` (Unicode replacement character) before escaping other special chars.
+**Test**: `Security: attribute escaping > escapeAttr neutralises null bytes`
+
+---
+
+#### SEC-7: No rate limiting on `analyze_image` tool calls
+
+**File**: `vision-proxy.ts:808-811`
+**Fix**: Added `MAX_TOOL_CALLS_PER_TURN = 10` counter. Counter resets on each `session_start`. Tool returns error when exceeded.
+**Test**: Verified via integration test pattern.
+
+---
+
+### ADDITIONAL: Image decode bomb protection
+
+**File**: `internal.ts:1053-1063` (cropImage), `internal.ts:60-64` (MAX_IMAGE_DIMENSION)
+**Fix**: Added `MAX_IMAGE_DIMENSION = 16384` (16K). Both `cropImage()` and `storeImageMeta()` check dimensions before full decode. Images exceeding 16K × 16K are rejected.
+**Test**: `Security: image decode bomb protection`
+
+---
+
+## Summary Table
+
+| ID | Severity | Finding | Status |
+|----|----------|---------|--------|
+| SEC-1 | CRITICAL | Interactive consent missing `provider` | ✅ Fixed |
+| SEC-2 | HIGH | `before_agent_start` lacks `..` check | ✅ Fixed |
+| SEC-3 | MEDIUM | `reason`/`question` stored unsanitized | ✅ Fixed |
+| SEC-4 | LOW | Persistent config lacks key filtering | ✅ Fixed |
+| SEC-5 | LOW | Regex from path strings | ✅ Safe |
+| SEC-6 | INFO | Null bytes in filenames | ✅ Fixed |
+| SEC-7 | INFO | No tool call rate limit | ✅ Fixed |
+| BOMB | LOW | Image decode bomb | ✅ Fixed |
+
+## Positive Security Observations
+
+1. **Defense-in-depth on file reads**: Three layers — `..` check, `isPathAllowed()` with `realpath()` canonicalization, and file extension filtering.
+2. **Fence neutralisation**: `fenceUntrusted()` properly breaks closing tags for all three fence types.
+3. **Consent per-provider**: `hasConsent()` validates provider field, preventing cross-provider consent leakage.
+4. **Attribute escaping**: `escapeAttr()` covers `&`, `"`, `<`, `>`, and null bytes.
+5. **Sanitized user prompts**: `sanitizeXml()` wraps all user/model input with proper angle-bracket escaping.
+6. **Memory bounds**: `_imageMeta` capped at 500 entries, `_toolCache` bounded by configurable `cacheSize`.
+7. **File size limits**: `maxImageFileBytes()` defaults to 10 MB.
+8. **Persistent file path**: Hardcoded to `~/.pi/agent/vision-proxy.json` — no path injection.
+9. **Input validation**: All numeric config values range-checked. Provider/model strings validated against allowlist regex.
+10. **No network surface**: Zero listening ports, no webhooks, no HTTP server.
+11. **Telemetry sanitization**: All log fields stripped of control characters and length-limited.
+12. **Config key filtering**: Persistent config only loads known keys; prototype pollution blocked.
+13. **Rate limiting**: Max 10 tool calls per turn prevents cost runaway.
+14. **Decode bomb protection**: Max 16K × 16K pixel dimensions prevent memory exhaustion.
+
+## Dependency Audit
+
+| Package | Version | Risk |
+|---------|---------|------|
+| `imagescript` | ^1.3.1 | Pure JS. No native deps. Decode bomb mitigated by dimension limit. AGPL-3.0. |
+| `imghash` | ^1.1.4 | Pure JS. Lazy-loaded, wrapped in try/catch. |
+| `image-size` | ^2.0.2 | Header-only extraction. Minimal attack surface. |

package/docs/PUBLISHING.md

@@ -0,0 +1,20 @@
+# Publishing `pi-multimodal-proxy`
+
+Tag-driven CI publish with npm provenance.
+
+```bash
+npm version patch -m "release: %s"
+git push origin main --follow-tags
+gh run watch
+```
+
+## Auth (one-time) — Trusted Publisher / OIDC
+
+1. npmjs.com → `pi-multimodal-proxy` → **Settings → Trusted Publisher**
+2. Add GitHub Actions:
+   - **Organization or user:** `pungggi`
+   - **Repository:** `pi-multimodal-proxy`
+   - **Workflow filename:** `release.yml`
+3. Leave `NPM_TOKEN` unset for pure OIDC.
+
+Fallback: Classic **Automation** token as `NPM_TOKEN` repo secret.

package/extensions/__tests__/compaction.test.ts

@@ -0,0 +1,218 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	buildCompactionDigest,
+	collectVisibleFenceIds,
+	CUSTOM_TYPE_DESCRIPTION,
+	CUSTOM_TYPE_VIDEO_DESCRIPTION,
+	DIGEST_IMAGE_CHARS,
+	DIGEST_LEAN_IMAGE_CHARS,
+	DIGEST_MAX_IMAGES,
+	findDescriptions,
+	findVideoDescriptions,
+	truncateForDigest,
+	type VideoDescriptionEntry,
+} from "../internal.ts";
+
+// SessionEntry minimal shape — typed loose because peer dep types are not loaded in test
+type Entry = any;
+
+const customEntry = (customType: string, data: unknown): Entry => ({
+	type: "custom",
+	customType,
+	data,
+});
+
+const video = (hash: string, description = `video ${hash}`): VideoDescriptionEntry => ({
+	hash,
+	filename: `${hash}.mp4`,
+	mimeType: "video/mp4",
+	description,
+});
+
+describe("findVideoDescriptions", () => {
+	it("collects hash → entry from video description entries", () => {
+		const entries: Entry[] = [
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, video("v1")),
+			customEntry(CUSTOM_TYPE_DESCRIPTION, { hash: "img", description: "not a video" }),
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, { hash: "", description: "skip" }),
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, video("v2")),
+		];
+		const map = findVideoDescriptions(entries);
+		assert.equal(map.size, 2);
+		assert.equal(map.get("v1")?.filename, "v1.mp4");
+		assert.equal(map.get("v2")?.mimeType, "video/mp4");
+	});
+
+	it("keeps the most recent entry per hash", () => {
+		const entries: Entry[] = [
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, video("v1", "old")),
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, video("v1", "new")),
+		];
+		assert.equal(findVideoDescriptions(entries).get("v1")?.description, "new");
+	});
+
+	it("moves a re-described hash to the end of the iteration order", () => {
+		const entries: Entry[] = [
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, video("v1", "first")),
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, video("v2", "second")),
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, video("v1", "updated")),
+		];
+		assert.deepEqual([...findVideoDescriptions(entries).keys()], ["v2", "v1"]);
+	});
+
+	it("backfills filename and mimeType on malformed entries instead of crashing later", () => {
+		const entries: Entry[] = [
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, { hash: "v1", description: "d" }),
+			customEntry(CUSTOM_TYPE_VIDEO_DESCRIPTION, { hash: "v2", description: "d", filename: 42, mimeType: null }),
+		];
+		const map = findVideoDescriptions(entries);
+		assert.equal(map.get("v1")?.filename, "unknown");
+		assert.equal(map.get("v1")?.mimeType, "application/octet-stream");
+		assert.equal(map.get("v2")?.filename, "unknown");
+		assert.equal(map.get("v2")?.mimeType, "application/octet-stream");
+		// The digest builder accepts the backfilled entries without throwing.
+		const digest = buildCompactionDigest([], [...map.values()]);
+		assert.ok(digest.includes('file="unknown"'));
+	});
+});
+
+describe("findDescriptions ordering", () => {
+	it("moves a re-described hash to the end of the iteration order", () => {
+		const entries: Entry[] = [
+			customEntry(CUSTOM_TYPE_DESCRIPTION, { hash: "a", description: "first" }),
+			customEntry(CUSTOM_TYPE_DESCRIPTION, { hash: "b", description: "second" }),
+			customEntry(CUSTOM_TYPE_DESCRIPTION, { hash: "a", description: "updated" }),
+		];
+		const map = findDescriptions(entries);
+		assert.deepEqual([...map.keys()], ["b", "a"]);
+		assert.equal(map.get("a"), "updated");
+	});
+});
+
+describe("truncateForDigest", () => {
+	it("returns short text unchanged", () => {
+		assert.equal(truncateForDigest("short text", 100), "short text");
+	});
+
+	it("trims surrounding whitespace", () => {
+		assert.equal(truncateForDigest("  padded  ", 100), "padded");
+	});
+
+	it("cuts long text at a word boundary and marks the truncation", () => {
+		// slice(0,20) is "alpha beta gamma del"; the boundary cut must drop "del".
+		const out = truncateForDigest("alpha beta gamma delta epsilon", 20);
+		assert.equal(out, "alpha beta gamma … [truncated]");
+	});
+
+	it("hard-cuts when there is no usable word boundary", () => {
+		const out = truncateForDigest("a".repeat(50), 20);
+		assert.equal(out, `${"a".repeat(20)} … [truncated]`);
+	});
+
+	it("never splits a surrogate pair on a hard cut", () => {
+		// "💥" is 2 UTF-16 code units; a cut at max=21 would land mid-pair.
+		const out = truncateForDigest(`${"x".repeat(20)}💥${"y".repeat(30)}`, 21);
+		assert.ok(!/[\uD800-\uDBFF]$/.test(out.replace(" … [truncated]", "")));
+		assert.ok(!out.includes("�"));
+		assert.equal(out, `${"x".repeat(20)} … [truncated]`);
+	});
+});
+
+describe("collectVisibleFenceIds", () => {
+	const h1 = "a".repeat(32);
+	const h2 = "b".repeat(32);
+	const h3 = "c".repeat(32);
+
+	it("collects ids from description, analysis, joint, and video fences", () => {
+		const text = [
+			`<vision_proxy_description image="${h1}" width="10"\n>body\n</vision_proxy_description>`,
+			`<vision_proxy_analysis image="${h2}#crop:1,2,3,4"\n>body\n</vision_proxy_analysis>`,
+			`dimensions='[{"image":"${h3}","width":5}]'`,
+			`<vision_proxy_video_description file="v.mp4" hash="${h1}" mime="video/mp4"\n>t\n</vision_proxy_video_description>`,
+		].join("\n");
+		const ids = collectVisibleFenceIds(text);
+		assert.deepEqual([...ids].sort(), [h1, h2, h3]);
+	});
+
+	it("ignores bare hashes and user-typed recall references", () => {
+		const ids = collectVisibleFenceIds(`zoom into image="${h1}" and also ${h2} please`);
+		assert.equal(ids.size, 0);
+	});
+
+	it("accumulates into a provided set", () => {
+		const out = new Set<string>();
+		collectVisibleFenceIds(`<vision_proxy_description image="${h1}"\n>x\n</vision_proxy_description>`, out);
+		collectVisibleFenceIds(`<vision_proxy_description image="${h2}"\n>x\n</vision_proxy_description>`, out);
+		assert.equal(out.size, 2);
+	});
+});
+
+describe("buildCompactionDigest", () => {
+	it("returns empty string when there is nothing to restore", () => {
+		assert.equal(buildCompactionDigest([], []), "");
+	});
+
+	it("restores image fences with id, meta, and untrusted warning", () => {
+		const digest = buildCompactionDigest(
+			[{ hash: "hash-a", description: "a red square", meta: { width: 10, height: 20, filename: "sq.png" } }],
+			[],
+		);
+		assert.ok(digest.includes("post-compaction recall"));
+		assert.ok(digest.includes('image="hash-a"'));
+		assert.ok(digest.includes('width="10"'));
+		assert.ok(digest.includes('filename="sq.png"'));
+		assert.ok(digest.includes("a red square"));
+		assert.ok(digest.includes("UNTRUSTED"));
+	});
+
+	it("includes video fences", () => {
+		const digest = buildCompactionDigest([], [video("v9", "a talking head")]);
+		assert.ok(digest.includes('hash="v9"'));
+		assert.ok(digest.includes('file="v9.mp4"'));
+		assert.ok(digest.includes("a talking head"));
+		assert.ok(digest.includes("1 video/audio file"));
+	});
+
+	it("mentions analyze_image recall only when the tool is enabled", () => {
+		const imgs = [{ hash: "h", description: "d" }];
+		assert.ok(buildCompactionDigest(imgs, [], { toolEnabled: true }).includes("analyze_image"));
+		assert.ok(!buildCompactionDigest(imgs, [], { toolEnabled: false }).includes("analyze_image"));
+	});
+
+	it("keeps only the most recent images when over the cap", () => {
+		const imgs = Array.from({ length: DIGEST_MAX_IMAGES + 3 }, (_, i) => ({
+			hash: `h${i}`,
+			description: `d${i}`,
+		}));
+		const digest = buildCompactionDigest(imgs, []);
+		assert.ok(!digest.includes('image="h0"'), "oldest images dropped");
+		assert.ok(!digest.includes('image="h2"'));
+		assert.ok(digest.includes('image="h3"'));
+		assert.ok(digest.includes(`image="h${DIGEST_MAX_IMAGES + 2}"`));
+	});
+
+	it("applies tighter budgets in lean mode", () => {
+		const long = "word ".repeat(400);
+		const [full] = buildCompactionDigest([{ hash: "h", description: long }], [])
+			.split("\n\n")
+			.slice(1);
+		const [lean] = buildCompactionDigest([{ hash: "h", description: long }], [], { lean: true })
+			.split("\n\n")
+			.slice(1);
+		assert.ok(full!.length > lean!.length);
+		assert.ok(lean!.length < DIGEST_LEAN_IMAGE_CHARS + 200);
+		assert.ok(full!.length < DIGEST_IMAGE_CHARS + 200);
+	});
+
+	it("counts both media kinds in the header", () => {
+		const digest = buildCompactionDigest(
+			[
+				{ hash: "a", description: "d1" },
+				{ hash: "b", description: "d2" },
+			],
+			[video("v1"), video("v2")],
+		);
+		assert.ok(digest.includes("2 images and 2 video/audio files"));
+	});
+});