@vieko/pi-redact 0.1.1 → 0.2.0

package/NOTICE

@@ -7,6 +7,9 @@ Local changes in src/detect.ts are marked with "pi-redact:" comments:
 - keep the macOS per-user temp dir (/var/folders/xx/<random>/T/)
 - name Linear (lin_api_) and Vercel AI Gateway (vck_) keys as vendor shapes
 - export findVendorKeys() for the history scan
+- mint placeholders as a keyed HMAC of the value (setTagKey()) instead of
+  random bytes, so a reloaded process mints the same tags; the vendored
+  test/random-tags.vendor.mts is replaced by test/stable-tags.test.ts
 
 In test/detect.vendor.mts:
 - the 5 s timing limit can be raised with REDACT_PERF_LIMIT_MS (CI uses 10 s)

package/README.md

@@ -25,9 +25,13 @@ pi install npm:@vieko/pi-redact
 
 Placeholders stay placeholders in `git commit`/`git tag` and `gh pr|issue|api|...`, and in every tool that is not in the restore list (`codemode` itself, `send_message`, MCP tools, web tools).
 
+## Placeholders
+
+A placeholder is an HMAC-SHA256 of the value. The key belongs to the session lineage (a fork or clone uses its root's key) and comes from a machine key in `~/.pi/agent/pi-redact.key`, created with mode 0600 on first use. After `/reload`, a restart or a resume, the same value gets the same placeholder, so the history pi sends does not change and the prompt cache holds. Two unrelated sessions get different placeholders. The machine key never reaches the model, so a placeholder cannot be matched to a guessed value. If the key file cannot be read or written, placeholders fall back to random tags per process.
+
 ## Tracking
 
-Each value seen for the first time in a session is logged as a `pi-redact` custom entry: `{ "source": "tool:bash", "values": 1, "vendor": 1 }`. The entry holds counts and the channel only, never the value, and is not sent to the model. `vendor` counts values with a known vendor shape; the rest came from entropy rules.
+Each value seen for the first time in a session is logged as a `pi-redact` custom entry. Its fields are `source` (channel), `values` (new distinct values), `vendor` (new values with a known vendor shape), and `families` (family name to count, summing to `values`). The entry holds counts only, never the value or a piece of it, and is not sent to the model. Families are `uuid`, `prefixed-id`, `identifier`, and `high-entropy`; vendor-shaped values use the detector's public prefix or pattern as their family.
 
 ## Old sessions
 
@@ -56,7 +60,7 @@ Optional `~/.pi/agent/pi-redact.json`, same keys as the upstream plugin:
 
 ## Limits
 
-- The vault lives in memory. After `/reload`, a restart or a resume, old placeholders no longer map to a value and reach tools as written.
+- The vault lives in memory. After `/reload`, a restart or a resume, an old placeholder maps to its value again only when that value turns up again; until then it reaches tools as written.
 - Output of `!cmd` is persisted by pi before any hook sees it. The model gets placeholders (the `context` net), but the raw output stays in the session file.
 - Custom messages appended while pi is idle are persisted without `message_end`; the `context` net covers what the model sees.
 - Sessions recorded before you install it keep their raw values on disk until you run `scripts/scrub-sessions.ts`.

package/extensions/pi-redact.ts

@@ -21,11 +21,20 @@
  * custom entry (counts and channel only, never the value), so audits can
  * tell how often and how secrets reach a session.
  *
- * The vault lives in memory. After /reload or a resume, old placeholders no
- * longer map to a value and reach tools as written.
+ * Placeholders are keyed per session lineage (a fork or clone shares its
+ * root's key) with a machine key in ~/.pi/agent/pi-redact.key, so /reload,
+ * a restart or a resume mints the same placeholder for the same value and
+ * the prompt cache survives. The vault (placeholder -> value) lives in
+ * memory: after /reload or a resume, old placeholders no longer map to a
+ * value until the value is seen again, and reach tools as written.
+ *
+ * The footer shows `redact:N`: distinct values kept out of this session's
+ * transcript. It counts the `pi-redact` entries on the branch, so the
+ * number survives /reload and resume even though the vault does not.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { createHash, createHmac, randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -39,12 +48,15 @@ import {
 	restore,
 	scrubPii,
 	scrubSecrets,
+	setTagKey,
 	type WalkState,
 	walk,
 } from "../src/detect.ts";
+import { familyOf } from "../src/family.ts";
 
 const NAME = "pi-redact";
 const CONFIG_PATH = join(homedir(), ".pi", "agent", "pi-redact.json");
+const KEY_PATH = join(homedir(), ".pi", "agent", "pi-redact.key");
 
 /** Tools that run on this machine and may receive real values. */
 export const DEFAULT_RESTORE_TOOLS = "bash,powershell,write,edit,read,grep,find,ls";
@@ -109,15 +121,93 @@ function mapContent<T>(content: T, fn: (s: string) => string): T {
 export interface RedactOptions {
 	/** Overrides ~/.pi/agent/pi-redact.json, for tests. */
 	options?: Record<string, unknown>;
+	/** Machine key file; defaults to ~/.pi/agent/pi-redact.key. */
+	keyPath?: string;
+	/** Machine key itself, skipping the file, for tests. */
+	machineKey?: string;
+}
+
+/**
+ * The machine key, created on first use (0600). It never reaches the model;
+ * without it a placeholder cannot be tied to a guessed value. Undefined when
+ * the file cannot be read or written: tags then stay per-process random.
+ */
+export function loadMachineKey(path: string): string | undefined {
+	try {
+		const key = readFileSync(path, "utf8").trim();
+		if (/^[0-9a-f]{64}$/.test(key)) return key;
+	} catch {
+		// Missing: create it below.
+	}
+	try {
+		writeFileSync(path, `${randomBytes(32).toString("hex")}\n`, { mode: 0o600, flag: "wx" });
+	} catch {
+		// Another process won the race, or the directory is read-only.
+	}
+	try {
+		const key = readFileSync(path, "utf8").trim();
+		return /^[0-9a-f]{64}$/.test(key) ? key : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+type Header = { id?: string; parentSession?: string } | null | undefined;
+
+/** Id of the oldest session this one was forked or cloned from. */
+export function lineageId(header: Header): string | undefined {
+	let id = header?.id;
+	let parent = header?.parentSession;
+	for (let hop = 0; parent && hop < 16; hop++) {
+		try {
+			const first = readFileSync(parent, "utf8").split("\n", 1)[0] ?? "";
+			const up = JSON.parse(first) as { type?: string; id?: string; parentSession?: string };
+			if (up.type !== "session" || !up.id) break;
+			id = up.id;
+			parent = up.parentSession;
+		} catch {
+			break;
+		}
+	}
+	return id;
 }
 
 export function createRedactor(pi: ExtensionAPI, init: RedactOptions = {}): void {
 	const cfg = buildConfig(init.options ?? loadOptions(CONFIG_PATH));
 	let enabled = true;
 	let hiddenTotal = 0;
+	let kept = 0;
+	let ui: ExtensionContext | undefined;
+	const showStatus = (): void => {
+		if (!ui?.hasUI || kept <= 0) return;
+		try {
+			ui.ui.setStatus(NAME, ui.ui.theme.fg("dim", `redact:${kept}`));
+		} catch {
+			// The context went stale (session replaced); the next session_start resets it.
+		}
+	};
 	const handedById = new Map<string, Set<string>>();
-	const contextMemo = new WeakMap<object, AnyMessage>();
+	let contextMemo = new WeakMap<object, AnyMessage>();
+	let contextMemoById = new Map<string, AnyMessage>();
 	const tracked = new Set<string>();
+	let machineKey = init.machineKey;
+	let sessionKey: string | undefined;
+
+	// One key per session lineage. A new lineage starts a new vault, so tags
+	// do not link one session to another.
+	const keySession = (header: Header): void => {
+		machineKey ??= loadMachineKey(init.keyPath ?? KEY_PATH);
+		const lineage = lineageId(header);
+		if (!machineKey || !lineage) return;
+		const key = createHmac("sha256", machineKey).update(`pi-redact/tags/v1\u0000${lineage}`).digest();
+		const hex = key.toString("hex");
+		if (hex === sessionKey) return;
+		sessionKey = hex;
+		setTagKey(key);
+		contextMemo = new WeakMap();
+		contextMemoById = new Map();
+		tracked.clear();
+	};
 
 	// One entry per channel event that brought in values not seen before.
 	// `vendor` counts the ones with a known vendor shape (high confidence);
@@ -126,9 +216,17 @@ export function createRedactor(pi: ExtensionAPI, init: RedactOptions = {}): void
 		const fresh = [...tags].filter((t) => !t.startsWith("[REDACTED-LITERAL-") && !tracked.has(t));
 		if (fresh.length === 0) return;
 		for (const t of fresh) tracked.add(t);
-		const vendor = fresh.filter((t) => findVendorKeys(restore(t)).length > 0).length;
+		kept += fresh.length;
+		showStatus();
+		const values = fresh.map((t) => restore(t));
+		const vendor = values.filter((value) => findVendorKeys(value).length > 0).length;
+		const families: Record<string, number> = {};
+		for (const value of values) {
+			const family = familyOf(value);
+			families[family] = (families[family] ?? 0) + 1;
+		}
 		try {
-			pi.appendEntry(NAME, { source, values: fresh.length, vendor });
+			pi.appendEntry(NAME, { source, values: fresh.length, vendor, families });
 		} catch {
 			// Tracking is best-effort; redaction already happened.
 		}
@@ -146,7 +244,6 @@ export function createRedactor(pi: ExtensionAPI, init: RedactOptions = {}): void
 		if (n <= 0) return;
 		hiddenTotal += n;
 		if (!ctx?.hasUI) return;
-		ctx.ui.setStatus(NAME, `redact ${hiddenTotal}`);
 		if (cfg.notify && where) ctx.ui.notify(`${NAME}: hid ${n} value(s) from ${where}`, "info");
 	};
 
@@ -161,6 +258,18 @@ export function createRedactor(pi: ExtensionAPI, init: RedactOptions = {}): void
 		return out;
 	};
 
+	pi.on("session_start", (_event, ctx) => {
+		ui = ctx;
+		kept = 0;
+		const sm = ctx.sessionManager as { getHeader?: () => Header };
+		keySession(typeof sm.getHeader === "function" ? sm.getHeader() : undefined);
+		for (const e of ctx.sessionManager.getBranch() as { type: string; customType?: string; data?: { values?: number } }[]) {
+			if (e.type === "custom" && e.customType === NAME) kept += e.data?.values ?? 0;
+		}
+		if (ctx.hasUI) ctx.ui.setStatus(NAME, undefined);
+		showStatus();
+	});
+
 	// 1. What the user types. `!cmd` is the user's own shell and runs as typed.
 	pi.on("input", (event, ctx) => {
 		if (!enabled || event.text.startsWith("!")) return { action: "continue" as const };
@@ -264,12 +373,30 @@ export function createRedactor(pi: ExtensionAPI, init: RedactOptions = {}): void
 		}
 	});
 
+	// pi may rebuild message objects on each request, so key the memo by the
+	// unscrubbed message's digest as well as by object. A digest, not role +
+	// timestamp: two messages that share a timestamp must never share output.
+	const contextMessageId = (message: AnyMessage): string | undefined => {
+		try {
+			return createHash("sha256").update(JSON.stringify(message)).digest("hex");
+		} catch {
+			return undefined;
+		}
+	};
+
 	// 6. The last net, request-local: bashExecution output, custom messages
 	//    appended while idle, and history from sessions recorded before this
-	//    extension. Same value -> same placeholder, so the cached prefix holds.
+	//    extension. Freeze each message's first scrub result: the echo set may
+	//    grow later, but already-sent bytes must not change.
 	const cleanMessage = (message: AnyMessage): AnyMessage => {
 		const cached = contextMemo.get(message);
 		if (cached) return cached;
+		const id = contextMessageId(message);
+		const stableCached = id === undefined ? undefined : contextMemoById.get(id);
+		if (stableCached) {
+			contextMemo.set(message, stableCached);
+			return stableCached;
+		}
 		let out = message;
 		switch (message.role) {
 			case "user":
@@ -293,6 +420,7 @@ export function createRedactor(pi: ExtensionAPI, init: RedactOptions = {}): void
 			}
 		}
 		contextMemo.set(message, out);
+		if (id !== undefined) contextMemoById.set(id, out);
 		return out;
 	};
 

package/package.json

@@ -1,25 +1,54 @@
 {
   "name": "@vieko/pi-redact",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Keeps secrets out of pi session transcripts: stable placeholders in, real values back for local tools.",
-  "keywords": ["pi-package", "pi-extension", "secrets", "redaction", "privacy"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "secrets",
+    "redaction",
+    "privacy"
+  ],
   "license": "MIT",
   "author": "Vieko Franetovic",
-  "repository": { "type": "git", "url": "git+https://github.com/vieko/pi-redact.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vieko/pi-redact.git"
+  },
   "homepage": "https://github.com/vieko/pi-redact#readme",
-  "bugs": { "url": "https://github.com/vieko/pi-redact/issues" },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org" },
+  "bugs": {
+    "url": "https://github.com/vieko/pi-redact/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "type": "module",
-  "files": ["extensions", "src", "scripts", "README.md", "NOTICE", "LICENSE"],
+  "files": [
+    "extensions",
+    "src",
+    "scripts",
+    "README.md",
+    "NOTICE",
+    "LICENSE"
+  ],
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
-    "test:vendor": "node test/detect.vendor.mts && node test/pii-options.vendor.mts && node test/random-tags.vendor.mts && node test/session-privacy.vendor.mts",
+    "test:vendor": "node test/detect.vendor.mts && node test/pii-options.vendor.mts && node test/session-privacy.vendor.mts",
     "test": "node --test \"test/*.test.ts\" && npm run test:vendor",
     "check": "npm run typecheck && npm run test"
   },
-  "engines": { "node": ">=22.18" },
-  "pi": { "extensions": ["./extensions/pi-redact.ts"] },
-  "peerDependencies": { "@earendil-works/pi-coding-agent": ">=0.1.0" },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/pi-redact.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.1.0"
+  },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@types/node": "^24.0.0",

package/src/detect.ts

@@ -16,6 +16,8 @@
 //
 // Nothing is written to disk. The vault dies with the session.
 
+import { createHash, type Hash, randomBytes } from 'node:crypto'
+
 export type Kind = 'SECRET' | 'EMAIL' | 'IP' | 'LITERAL'
 
 export type Config = {
@@ -51,12 +53,39 @@ let minted: Set<string> | null = null
 const TAG = /\[REDACTED-(?:SECRET|EMAIL|IP|LITERAL)-[0-9a-f]{8}\]/g
 const WHOLE_TAG = /^\[REDACTED-(?:SECRET|EMAIL|IP|LITERAL)-[0-9a-f]{8}\]$/
 
-function randomHex8(): string {
-  const bytes = new Uint8Array(4)
-  const crypto = (globalThis as { crypto?: { getRandomValues?: (values: Uint8Array) => Uint8Array } }).crypto
-  if (crypto?.getRandomValues) crypto.getRandomValues(bytes)
-  else for (let index = 0; index < bytes.length; index++) bytes[index] = Math.floor(Math.random() * 256)
-  return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('')
+// pi-redact: a tag is a keyed hash of the value, not a random draw, so a
+// reloaded or restarted process mints the same tag for the same value and
+// the history it sends keeps its prompt-cache prefix. The host sets the key
+// per session with setTagKey(); without one, each module load draws a random
+// key, so tags stay unlinkable across processes as upstream intends.
+let tagKey: Uint8Array = randomBytes(32)
+let pads = hmacPads(tagKey)
+
+// HMAC-SHA256 with the two padded key blocks hashed once and copied per tag:
+// createHmac() per value made the vendored timing cases twice as slow.
+function hmacPads(key: Uint8Array): { inner: Hash; outer: Hash } {
+  const block = Buffer.alloc(64)
+  Buffer.from(key.length > 64 ? createHash('sha256').update(key).digest() : key).copy(block)
+  const inner = createHash('sha256').update(block.map(b => b ^ 0x36))
+  const outer = createHash('sha256').update(block.map(b => b ^ 0x5c))
+  return { inner, outer }
+}
+
+function tagHex(kind: Kind, value: string, attempt: number): string {
+  const inner = pads.inner.copy().update(`${kind}\u0000${attempt}\u0000${value}`).digest()
+  return pads.outer.copy().update(inner).digest('hex').slice(0, 8)
+}
+
+// pi-redact: swaps the tag key. A different key starts a new vault: tags
+// minted under the old key would no longer match what a fresh process mints.
+export function setTagKey(key: Uint8Array): void {
+  if (Buffer.from(key).equals(Buffer.from(tagKey))) return
+  tagKey = Uint8Array.from(key)
+  pads = hmacPads(tagKey)
+  byValue.clear()
+  byTag.clear()
+  echo.clear()
+  echoIndex = null
 }
 
 // Swaps a value for its placeholder and remembers both. A value that already
@@ -72,7 +101,8 @@ export function mint(kind: Kind, raw: string): string {
     return seen
   }
   let tag: string
-  do tag = `[REDACTED-${kind}-${randomHex8()}]`
+  let attempt = 0
+  do tag = `[REDACTED-${kind}-${tagHex(kind, value, attempt++)}]`
   while (byTag.has(tag))
   byValue.set(value, tag)
   byTag.set(tag, value)

package/src/family.ts

@@ -0,0 +1,14 @@
+import { findVendorKeys } from "./detect.ts";
+
+/** Shape classes for values without a vendor-specific family. */
+export const FAMILIES = ["uuid", "prefixed-id", "identifier", "high-entropy"] as const;
+
+// Vendor rules take precedence so audit counts retain their public shape label.
+export function familyOf(value: string): string {
+	const vendor = findVendorKeys(value)[0];
+	if (vendor) return vendor.family;
+	if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)) return "uuid";
+	if (/^[a-z][a-z0-9]{1,15}_[A-Za-z0-9]{8,}$/.test(value)) return "prefixed-id";
+	if (/^(?=.*[a-z])(?=.*[A-Z])[A-Za-z0-9]+$/.test(value)) return "identifier";
+	return "high-entropy";
+}