pi-privacy 0.1.1 → 0.2.0

package/README.md

@@ -49,6 +49,25 @@ Providers with no verifiable or default privacy channel (Together, DeepSeek, Min
 Qwen, …) are intentionally left `standard` with **no badge** — anything else would
 overclaim.
 
+## Posture-aware PII gate
+
+The second axis: not just *is the channel private*, but *should this data go down it*.
+Before a request leaves for an **unverified** channel (anything below verified-TEE /
+on-device), pi-privacy scans it for **structured PII** — emails, phones, SSNs, credit
+cards (Luhn-checked), IPs — and, by default, **warns** you with the choice to send,
+redact, or (implicitly) switch models. On a **verified-TEE** or **local** model it does
+nothing — an attested enclave can't read your data and a loopback endpoint never sends
+it. (ZDR is *not* exempt: a ZDR provider still *sees* the data, it just doesn't retain it.)
+
+```ts
+makePiPrivacyExtension({ piiPolicy: "warn" }); // "warn" (default) | "redact" | "off"
+```
+
+**Honesty bound (the whole point):** this is *best-effort structured-PII detection*,
+never a guarantee. It is local + deterministic — it never sends your data to a model to
+detect PII (that would leak it) — so it catches patterns, not names/addresses/context.
+It says so at the prompt. Treat it as a seatbelt, not a force field.
+
 ## How verification works
 
 - **Tinfoil (SPKI pinning).** Pi's provider requests flow through a process-wide

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-privacy",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Privacy posture + TEE attestation for Pi providers: cryptographically verified confidential-enclave (TEE) inference, enforced/labeled zero-data-retention (ZDR), and on-device detection — honestly graded so a verified guarantee never reads like a claimed one.",
   "type": "module",
   "license": "MIT",

package/src/extension.ts

@@ -11,7 +11,39 @@ import { installAttestationDispatcher, dispatcherTransport } from "./attest/disp
 import { PRIVACY_PROVIDERS, type PrivacyProvider } from "./providers/catalog.ts";
 import { veniceRequestPatch, openRouterZdrPatch } from "./ext/patches.ts";
 import { verifyModelPosture, type PostureResult } from "./posture/verify.ts";
-import { TIERS } from "./posture/tiers.ts";
+import { TIERS, type PrivacyTier } from "./posture/tiers.ts";
+import { detectPii, redactPii, summarizePii } from "./pii/detect.ts";
+
+// Verified-private tiers where PII needs no gate: an attested enclave can't read it,
+// and a loopback endpoint never sends it. NOTE zdr-* is NOT here — a ZDR provider
+// still SEES the data (it just doesn't retain it), so PII exposure remains.
+function isVerifiedPrivate(tier: PrivacyTier | undefined): boolean {
+  return tier === "tee-verified" || tier === "local";
+}
+
+// Extract the outbound message text for detection, and redact PII structurally in the
+// payload's message content (string or content-part arrays).
+function payloadText(payload: any): string {
+  try {
+    return JSON.stringify(payload?.messages ?? payload ?? "");
+  } catch {
+    return "";
+  }
+}
+function redactPayloadPii(payload: any): any {
+  if (!payload || typeof payload !== "object" || !Array.isArray(payload.messages)) return payload;
+  const messages = payload.messages.map((m: any) => {
+    if (typeof m?.content === "string") return { ...m, content: redactPii(m.content) };
+    if (Array.isArray(m?.content)) {
+      return {
+        ...m,
+        content: m.content.map((p: any) => (typeof p?.text === "string" ? { ...p, text: redactPii(p.text) } : p)),
+      };
+    }
+    return m;
+  });
+  return { ...payload, messages };
+}
 
 // ── structural Pi surface (subset we use) ────────────────────────────────────
 interface PiModel {
@@ -19,7 +51,11 @@ interface PiModel {
   id?: string;
 }
 interface PiCtx {
-  ui?: { notify?: (message: string, level?: string) => void };
+  hasUI?: boolean;
+  ui?: {
+    notify?: (message: string, level?: string) => void;
+    select?: (title: string, options: string[], opts?: unknown) => Promise<string | undefined>;
+  };
 }
 interface PiExtensionApiLike {
   registerProvider?(name: string, config: unknown): void;
@@ -48,6 +84,16 @@ export interface PiPrivacyOptions {
   // Bind Tinfoil attestation to the real provider connection via the dispatcher
   // (default true when the dispatcher is installed). Falls back to httpsTransport.
   useDispatcherTransport?: boolean;
+  // Override the tier resolution for providers pi-privacy doesn't know (e.g. a host's
+  // private account channel). Return a PrivacyTier to use it (drives the PII gate +
+  // badge), or undefined to fall back to pi-privacy's built-in verified posture.
+  resolveTier?: (provider: string, modelId: string) => Promise<PrivacyTier | undefined> | PrivacyTier | undefined;
+  // Posture-aware structured-PII policy on outbound requests. "warn" (default):
+  // interactively warn + offer redact before sending PII down an UNVERIFIED channel;
+  // "redact": silently mask; "off": disabled. Only acts below verified-TEE/local
+  // (an attested/on-device channel is safe), and only where a UI can prompt. Detection
+  // is best-effort structured PII (emails/phones/SSNs/cards/IPs) — NOT a guarantee.
+  piiPolicy?: "warn" | "redact" | "off";
 }
 
 // Config-only providers Pi doesn't ship: register these. Built-ins + custom skipped.
@@ -103,6 +149,8 @@ export function makePiPrivacyExtension(opts: PiPrivacyOptions = {}) {
     enforceOpenRouterZdr = false,
     onPosture,
     useDispatcherTransport = true,
+    piiPolicy = "warn",
+    resolveTier,
   } = opts;
 
   return function piPrivacy(pi: PiExtensionApiLike): void {
@@ -116,16 +164,32 @@ export function makePiPrivacyExtension(opts: PiPrivacyOptions = {}) {
 
     let currentProviderId: string | undefined;
     let currentModelId: string | undefined;
+    // The VERIFIED tier of the current model (attestation result), cached for the PII
+    // gate. Undefined until computed → the gate treats "unknown" as not-verified (safe).
+    let currentTier: PrivacyTier | undefined;
+    // Session PII decision so we don't re-prompt every turn once the user has chosen.
+    let piiChoice: "ask" | "send" | "redact" = "ask";
 
-    // Recompute + publish posture for the current model.
+    // Recompute posture for the current model; cache the tier and publish the badge.
     const refreshPosture = async () => {
-      if (!currentProviderId || !currentModelId || !onPosture) return;
+      if (!currentProviderId || !currentModelId) return;
+      // A host-supplied resolver (e.g. a private account channel pi-privacy doesn't
+      // know) wins — otherwise use the built-in verified posture.
+      if (resolveTier) {
+        const t = await resolveTier(currentProviderId, currentModelId);
+        if (t !== undefined) {
+          currentTier = t;
+          onPosture?.({ providerId: currentProviderId, modelId: currentModelId, tier: t });
+          return;
+        }
+      }
       const result = await verifyModelPosture(currentProviderId, currentModelId, {
         apiKey: currentProviderId === "nearai" ? nearApiKey() : undefined,
         zdrEnforced: currentProviderId === "openrouter" && enforceOpenRouterZdr,
         transport: useDispatcherTransport && installDispatcher ? dispatcherTransport : undefined,
       });
-      onPosture(result);
+      currentTier = result.tier;
+      onPosture?.(result);
     };
 
     pi.on("model_select", (event) => {
@@ -135,14 +199,37 @@ export function makePiPrivacyExtension(opts: PiPrivacyOptions = {}) {
       void refreshPosture();
     });
 
-    // Per-provider request patches. Scoped to the current provider so we never
-    // mutate a payload bound for a different endpoint.
-    pi.on("before_provider_request", (event) => {
-      if (currentProviderId === "venice") return veniceRequestPatch(event?.payload);
-      if (currentProviderId === "openrouter" && enforceOpenRouterZdr) {
-        return openRouterZdrPatch(event?.payload);
+    // Per-provider request patches + the posture-aware PII gate.
+    pi.on("before_provider_request", async (event, ctx) => {
+      let payload = event?.payload;
+      // Provider-specific patches first (scoped to the current provider).
+      if (currentProviderId === "venice") payload = veniceRequestPatch(payload);
+      else if (currentProviderId === "openrouter" && enforceOpenRouterZdr) payload = openRouterZdrPatch(payload);
+
+      // PII gate: only below a VERIFIED-private tier (TEE-verified/local are safe —
+      // the provider can't read the data), and only where we can actually prompt.
+      if (piiPolicy !== "off" && !isVerifiedPrivate(currentTier)) {
+        const hits = detectPii(payloadText(payload));
+        if (hits.length > 0) {
+          let action: "send" | "redact" =
+            piiChoice !== "ask" ? piiChoice : piiPolicy === "redact" ? "redact" : "send";
+          if (piiChoice === "ask" && piiPolicy === "warn" && ctx?.hasUI && typeof ctx.ui?.select === "function") {
+            const tierLabel = TIERS[currentTier ?? "standard"].label;
+            const choice = await ctx.ui.select(
+              `⚠ ${summarizePii(hits)} detected — sending to an unverified channel (${tierLabel}). ` +
+                `Best-effort structured-PII detection only, not a guarantee.`,
+              ["Send as-is", "Redact PII", "Redact + remember for session", "Send + remember for session"],
+            );
+            if (choice === "Redact PII") action = "redact";
+            else if (choice === "Redact + remember for session") ((action = "redact"), (piiChoice = "redact"));
+            else if (choice === "Send + remember for session") ((action = "send"), (piiChoice = "send"));
+            else action = "send"; // "Send as-is" or cancelled
+          }
+          if (action === "redact") payload = redactPayloadPii(payload);
+        }
       }
-      return undefined;
+
+      return payload === event?.payload ? undefined : payload;
     });
 
     if (typeof pi.registerCommand === "function") {

package/src/index.ts

@@ -66,3 +66,13 @@ export {
 } from "./extension.ts";
 
 export { veniceRequestPatch, openRouterZdrPatch } from "./ext/patches.ts";
+
+// Local structured-PII detection (best-effort; emails/phones/SSNs/cards/IPs).
+export {
+  type PiiType,
+  type PiiHit,
+  detectPii,
+  hasPii,
+  redactPii,
+  summarizePii,
+} from "./pii/detect.ts";

package/src/pii/detect.ts

@@ -0,0 +1,115 @@
+// Local, deterministic structured-PII detection. HONESTY BOUND (the whole reason
+// this package exists): this catches STRUCTURED PII — emails, phones, SSNs, credit
+// cards, IPs — via patterns only. It CANNOT catch names, addresses, or contextual
+// PII, and it never uses a model (that would send the PII to detect it). So it is
+// "best-effort structured-PII detection", never a guarantee. Callers must label it
+// that way — the same verified-vs-claimed discipline as the posture engine.
+
+const PLACEHOLDER: Record<PiiType, string> = {
+  email: "«email»",
+  phone: "«phone»",
+  ssn: "«ssn»",
+  "credit-card": "«card»",
+  ip: "«ip»",
+  iban: "«iban»",
+  mac: "«mac»",
+};
+
+export type PiiType = "email" | "phone" | "ssn" | "credit-card" | "ip" | "iban" | "mac";
+
+// Order matters: run more-specific/structured patterns first so a card isn't also
+// counted as a phone. Credit-card + phone are validated further below.
+const PATTERNS: { type: PiiType; re: RegExp; validate?: (m: string) => boolean }[] = [
+  { type: "email", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+  { type: "ssn", re: /\b\d{3}-\d{2}-\d{4}\b/g },
+  // 13–19 digit runs (optionally space/dash grouped) that pass the Luhn check — this
+  // sharply cuts false positives vs "any long number".
+  { type: "credit-card", re: /\b(?:\d[ -]?){13,19}\b/g, validate: luhn },
+  // IPv4 with each octet 0–255.
+  { type: "ip", re: /\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b/g },
+  // IBAN: 2-letter country + 2 check digits + 11–30 alphanumerics, mod-97 validated
+  // (cuts false positives on random alphanumeric runs sharply).
+  { type: "iban", re: /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/g, validate: ibanValid },
+  // MAC address (colon or dash separated).
+  { type: "mac", re: /\b(?:[0-9A-Fa-f]{2}[:-]){5}[0-9A-Fa-f]{2}\b/g },
+  // North-American / international-ish phone. Deliberately last + conservative to
+  // avoid eating IDs; requires a plausible separator or leading +.
+  { type: "phone", re: /(?:\+\d{1,3}[\s.-]?)?\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}\b/g },
+];
+
+function luhn(s: string): boolean {
+  const digits = s.replace(/\D/g, "");
+  if (digits.length < 13 || digits.length > 19) return false;
+  let sum = 0;
+  let alt = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (alt) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    alt = !alt;
+  }
+  return sum % 10 === 0;
+}
+
+// IBAN mod-97 check (ISO 13616): move the first 4 chars to the end, map letters to
+// numbers (A=10…Z=35), and verify the big-integer mod 97 === 1.
+function ibanValid(s: string): boolean {
+  const iban = s.toUpperCase();
+  if (iban.length < 15 || iban.length > 34) return false;
+  const rearranged = iban.slice(4) + iban.slice(0, 4);
+  let remainder = 0;
+  for (const ch of rearranged) {
+    const code = ch >= "A" && ch <= "Z" ? (ch.charCodeAt(0) - 55).toString() : ch;
+    for (const d of code) remainder = (remainder * 10 + (d.charCodeAt(0) - 48)) % 97;
+  }
+  return remainder === 1;
+}
+
+export interface PiiHit {
+  type: PiiType;
+  count: number;
+}
+
+// Detect structured PII in text. Returns the types present with counts (not the raw
+// values — we don't want to log the PII we found).
+export function detectPii(text: string): PiiHit[] {
+  if (!text) return [];
+  const counts = new Map<PiiType, number>();
+  for (const { type, re, validate } of PATTERNS) {
+    for (const m of text.matchAll(re)) {
+      if (validate && !validate(m[0])) continue;
+      counts.set(type, (counts.get(type) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()].map(([type, count]) => ({ type, count }));
+}
+
+export function hasPii(text: string): boolean {
+  return detectPii(text).length > 0;
+}
+
+// Redact structured PII in text, replacing each match with a typed placeholder.
+export function redactPii(text: string): string {
+  let out = text;
+  for (const { type, re, validate } of PATTERNS) {
+    out = out.replace(re, (m) => (validate && !validate(m) ? m : PLACEHOLDER[type]));
+  }
+  return out;
+}
+
+// Human-readable summary of a hit list, e.g. "2 emails, 1 SSN".
+export function summarizePii(hits: PiiHit[]): string {
+  const label: Record<PiiType, [string, string]> = {
+    email: ["email", "emails"],
+    phone: ["phone number", "phone numbers"],
+    ssn: ["SSN", "SSNs"],
+    "credit-card": ["card number", "card numbers"],
+    ip: ["IP address", "IP addresses"],
+    iban: ["IBAN", "IBANs"],
+    mac: ["MAC address", "MAC addresses"],
+  };
+  return hits.map((h) => `${h.count} ${label[h.type][h.count === 1 ? 0 : 1]}`).join(", ");
+}