@chatpanel/bridge 0.10.41 → 0.11.0

package/src/events/event.js

@@ -0,0 +1,183 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/event.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// The event envelope — durable facts only.
+//
+// ORDER WITHOUT CLOCKS. `at` is wall time and is ADVISORY: it is shown to humans and
+// never consulted for ordering. `(host, seq)` plus `causes` are the authority, because
+// once two hosts append concurrently a timestamp is not an order (see order.js).
+//
+// EPHEMERAL STREAMS ARE NOT THIS TYPE. Market ticks, live captions and DOM mutations
+// live in an in-memory ring buffer with no id, no seq and no persistence; only the
+// windowed aggregate that entered a model request or crossed the device boundary is
+// promoted to an Event. That is structural rather than a rule to remember: durably
+// logging a caption stream is ~3 MB per meeting, ~5.5 GB/year, and there is no Event
+// type that would accept one.
+//
+// METADATA ONLY. Payloads carry Refs and counts, never content. `privacy.redacted`
+// carries how many of each entity type were redacted and never the values — a log of
+// what was redacted must not itself contain the redacted data.
+
+import { isRef } from './ref.js';
+
+export const CURRENT_VERSION = 1;
+
+/** The seven families of v1. Adding is cheap; removing is not. */
+export const EVENT_TYPES = Object.freeze({
+  turn: ['started', 'ended'],
+  // What the model was SHOWN and what it SAID. Deliberately arriving as refs, not text —
+  // see the note on the validators below.
+  assistant: ['prompted', 'message', 'reasoning'],
+  context: ['assembled', 'attached', 'expanded'],
+  capability: ['offered', 'granted', 'denied', 'activated', 'revoked', 'invoked', 'resulted'],
+  privacy: ['redacted', 'egress'],
+  policy: ['changed', 'guard_denied'],
+  data: ['created', 'updated', 'deleted'],
+  automation: ['fired', 'suppressed'],
+});
+
+export const ALL_TYPES = Object.freeze(
+  Object.entries(EVENT_TYPES).flatMap(([fam, kinds]) => kinds.map((k) => `${fam}.${k}`)),
+);
+
+// 'channel' is a message arriving from a paired external surface — Telegram, WhatsApp — that
+// drives a turn the same way a person pressing send does. It is turn-independent for the same
+// reason 'schedule' and 'agent' are: nobody is sitting in the panel when it fires, so consent
+// and reach have to be settled at pairing time, not at the keystroke. The actor.id carries the
+// surface and the sender, e.g. 'telegram:8412…'. See chatpanel-channels for the invoker.
+export const ACTOR_KINDS = Object.freeze(['user', 'rule', 'schedule', 'model', 'agent', 'channel']);
+export const SCOPE_KINDS = Object.freeze(['global', 'site', 'tab', 'session', 'agent']);
+export const CLASSES = Object.freeze(['R', 'M', 'L', 'C', 'A', 'X', 'H']);
+export const EFFECTS = Object.freeze(['pure', 'idempotent', 'replay-safe', 'non-replayable']);
+export const EGRESS = Object.freeze(['none', 'redacted', 'delegated']);
+
+export class EventError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'EventError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+const arr = (v) => Array.isArray(v);
+
+function actorOk(a) { return !!a && ACTOR_KINDS.includes(a.kind) && str(a.id); }
+function scopeOk(s) { return !!s && SCOPE_KINDS.includes(s.kind) && str(s.id); }
+
+// Per-type payload requirements. Deliberately light — enough that a malformed event
+// cannot enter an append-only log, not a full schema language.
+const PAYLOAD = {
+  'turn.started': (p) => str(p.turnId),
+  'turn.ended': (p) => str(p.turnId),
+
+  // ── assistant ─────────────────────────────────────────────────────────────
+  // "Model-visible means logged" was true of the toolset and false of the conversation:
+  // the log could say a turn happened and what it cost, but never what was asked or
+  // answered. That is the half a trajectory view needs, and the half replay cannot be
+  // checked without.
+  //
+  // CONTENT IS NEVER IN THE EVENT. Each of these carries a Ref — a content hash — and the
+  // bytes live in the blob store. Three reasons, in order of how much they matter:
+  //   1. The log stays metadata, so exporting or replicating it does not export the user's
+  //      conversations by accident. That property is the whole reason an event log is safe
+  //      to keep at all.
+  //   2. Deletion stays honest: an append-only log cannot unsay a message, but a blob can
+  //      be crypto-shredded and the ref then resolves to verified-but-unavailable. Inlined
+  //      text would make "delete my data" a lie the schema enforces forever.
+  //   3. Repeated content (the same system prompt on every turn) is stored once.
+  'assistant.prompted': (p) => str(p.turnId) && isRef(p.ref),
+  'assistant.message': (p) => str(p.turnId) && isRef(p.ref),
+  'assistant.reasoning': (p) => str(p.turnId) && isRef(p.ref),
+
+  'context.assembled': (p) => num(p.budget) && num(p.used) && !!p.parts && typeof p.parts === 'object'
+    && arr(p.resident) && p.resident.every(isRef) && num(p.reachableCount),
+  'context.attached': (p) => isRef(p.ref),
+  'context.expanded': (p) => isRef(p.ref) && num(p.tokens),
+
+  'capability.offered': (p) => str(p.capability) && str(p.reason),
+  'capability.granted': (p) => str(p.capability) && actorOk(p.actor),
+  'capability.denied': (p) => str(p.capability) && actorOk(p.actor),
+  'capability.activated': (p) => str(p.capability) && CLASSES.includes(p.classUsed),
+  'capability.revoked': (p) => str(p.capability) && str(p.cause),
+  // I3 is enforced here structurally: a non-pure invocation without a key is not a
+  // valid event, so it cannot reach the log at all.
+  'capability.invoked': (p) => str(p.capability) && actorOk(p.actor) && scopeOk(p.scope)
+    && EFFECTS.includes(p.effects) && (p.effects === 'pure' || str(p.idempotencyKey)),
+  'capability.resulted': (p) => str(p.capability) && typeof p.ok === 'boolean'
+    && CLASSES.includes(p.classUsed) && !!p.cost && num(p.cost.ms),
+
+  // counts only — never values
+  'privacy.redacted': (p) => !!p.counts && typeof p.counts === 'object'
+    && Object.values(p.counts).every(num),
+  'privacy.egress': (p) => str(p.host) && typeof p.redacted === 'boolean'
+    && typeof p.controlled === 'boolean',
+
+  'policy.changed': (p) => str(p.dial) && actorOk(p.actor) && 'from' in p && 'to' in p,
+  'policy.guard_denied': (p) => str(p.capability) && str(p.reason),
+
+  'data.created': (p) => isRef(p.ref),
+  'data.updated': (p) => isRef(p.ref),
+  'data.deleted': (p) => isRef(p.ref) && typeof p.shredded === 'boolean',
+
+  'automation.fired': (p) => str(p.ruleId) && CLASSES.includes(p.classUsed),
+  'automation.suppressed': (p) => str(p.ruleId) && str(p.reason),
+};
+
+/** Validate a durable event. Throws EventError; never mutates. */
+export function validateEvent(e) {
+  if (!e || typeof e !== 'object') throw new EventError('SHAPE', 'event must be an object');
+  if (e.v !== CURRENT_VERSION) throw new EventError('VERSION', `expected v=${CURRENT_VERSION}, got ${e.v} — upcast first`, e.v);
+  if (!str(e.id)) throw new EventError('SHAPE', 'id required');
+  if (!str(e.host)) throw new EventError('SHAPE', 'host required');
+  if (!Number.isInteger(e.seq) || e.seq < 0) throw new EventError('SHAPE', 'seq must be a non-negative integer');
+  if (!arr(e.causes) || !e.causes.every(str)) throw new EventError('SHAPE', 'causes must be string[]');
+  if (!num(e.at)) throw new EventError('SHAPE', 'at required (advisory wall clock)');
+  if (!ALL_TYPES.includes(e.type)) throw new EventError('TYPE', `unknown type ${e.type}`, e.type);
+  if (!e.payload || typeof e.payload !== 'object') throw new EventError('SHAPE', 'payload required');
+  const check = PAYLOAD[e.type];
+  if (check && !check(e.payload)) throw new EventError('PAYLOAD', `payload invalid for ${e.type}`, e.type);
+  return e;
+}
+
+export function isValidEvent(e) {
+  try { validateEvent(e); return true; } catch { return false; }
+}
+
+/**
+ * A per-host append cursor. Owns `seq` — the only monotonic thing in the system — so
+ * callers cannot skip or reuse one.
+ *
+ * `now` and `newId` are injected so tests are deterministic and so the package holds no
+ * ambient dependency on a clock or a crypto implementation.
+ */
+export function createAppender({ host, seq = 0, now = () => Date.now(), newId }) {
+  if (!str(host)) throw new EventError('SHAPE', 'host required');
+  const genId = newId || (() => globalThis.crypto.randomUUID());
+  let n = seq;
+  return {
+    get host() { return host; },
+    get seq() { return n; },
+    /** Build + validate the next event for this host. Does not persist — the caller stores it. */
+    append(type, payload, causes = []) {
+      const e = Object.freeze({
+        v: CURRENT_VERSION,
+        id: genId(),
+        host,
+        seq: n++,
+        causes: Object.freeze([...causes]),
+        at: now(),
+        type,
+        payload,
+      });
+      return validateEvent(e);
+    },
+  };
+}

package/src/events/reach.js

@@ -0,0 +1,31 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/reach.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// reach.js — how far a request may travel, on its own so it can travel alone.
+//
+// One ordered vocabulary answers "how far may this go" for three very different callers: the
+// model router ranks a model's reach against a turn's requirement, pairing gives a phone a
+// ceiling, and the bridge maps that ceiling to a toolset. Three declarations, one vocabulary,
+// or "how far may this reach" gets three answers that drift.
+//
+// A separate module rather than a constant inside router.js for the reason scopes.js exists:
+// the consumers have wildly different weights. The bridge has zero runtime dependencies by
+// design and vendors what it needs — pulling the 50 KB model router in to reach a
+// three-element array is exactly the transitive-graph mistake that split DATA_SCOPES out of
+// capability.js.
+//
+// ORDERED, least to most: a ceiling comparison is an index comparison.
+export const REACH = Object.freeze(['device', 'trusted', 'any']);
+
+/** Position in the ladder; an unknown tier ranks LOWEST, so a typo never widens reach. */
+export const reachRank = (r) => Math.max(0, REACH.indexOf(r));
+
+/** Does `have` satisfy `need`? Fails closed — an unknown `have` is treated as 'device'. */
+export function reachSatisfies(have, need) {
+  return reachRank(have) >= reachRank(need);
+}

package/src/events/ref.js

@@ -0,0 +1,60 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/ref.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// References — how the log addresses content WITHOUT copying it.
+//
+// An event records "note n_88, lines 10-40, hash H" and never the text. Content that
+// actually entered a model request is written once into a content-addressed blob store
+// keyed by hash, so the same excerpt across a hundred turns costs one copy.
+//
+// Replay resolves a Ref by hash: match => exact reconstruction; blob absent or
+// crypto-shredded => VERIFIED_BUT_UNAVAILABLE. It never silently substitutes today's
+// version of the note, because that would make replay quietly wrong instead of loudly
+// incomplete.
+
+export const REF_KINDS = Object.freeze(['note', 'meeting', 'chat', 'page', 'result', 'blob']);
+
+export const RESOLUTION = Object.freeze({
+  EXACT: 'exact',                              // blob present, hash matches
+  UNAVAILABLE: 'verified-but-unavailable',     // we know what it was; we no longer hold it
+  DRIFTED: 'drifted',                          // source still exists but its hash changed
+});
+
+/** Build a Ref. `hash` is the content hash AT CAPTURE TIME — that is the whole point. */
+export function makeRef({ kind, id, hash, range = null, stored = false }) {
+  if (!REF_KINDS.includes(kind)) throw new TypeError(`ref: unknown kind ${kind}`);
+  if (typeof id !== 'string' || !id) throw new TypeError('ref: id required');
+  if (typeof hash !== 'string' || !hash) throw new TypeError('ref: hash required');
+  const ref = { kind, id, hash };
+  if (range) {
+    if (!Number.isInteger(range.from) || !Number.isInteger(range.to) || range.to < range.from) {
+      throw new TypeError('ref: range must be {from,to} integers with to >= from');
+    }
+    ref.range = { from: range.from, to: range.to };
+  }
+  if (stored) ref.stored = true;
+  return Object.freeze(ref);
+}
+
+export function isRef(v) {
+  return !!v && typeof v === 'object'
+    && REF_KINDS.includes(v.kind)
+    && typeof v.id === 'string' && v.id.length > 0
+    && typeof v.hash === 'string' && v.hash.length > 0;
+}
+
+/**
+ * Classify what a replay can say about a Ref, given what the blob store holds now.
+ * `lookup(ref) -> { hash } | null`. Pure: the caller owns the store.
+ */
+export function resolveRef(ref, lookup) {
+  const got = lookup(ref);
+  if (!got) return { resolution: RESOLUTION.UNAVAILABLE, ref };
+  if (got.hash !== ref.hash) return { resolution: RESOLUTION.DRIFTED, ref, actualHash: got.hash };
+  return { resolution: RESOLUTION.EXACT, ref, value: got.value };
+}

package/src/events/scopes.js

@@ -17,4 +17,4 @@
 // zero runtime dependencies by design; pulling the capability machinery and the event
 // schema behind it to reach a five-element array would be the transitive-graph mistake
 // the extension's first-paint budget exists to prevent, one repo over.
-export const DATA_SCOPES = Object.freeze(['notes', 'meetings', 'chats', 'page', 'files', 'net']);
+export const DATA_SCOPES = Object.freeze(['notes', 'meetings', 'chats', 'memory', 'page', 'files', 'net']);

package/src/events/view.js

@@ -0,0 +1,96 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/view.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// CAPABILITY VIEWS — a capability may ship its own UI, so a result can be an interactive
+// component instead of a paragraph of text.
+//
+// This is NOT the model writing HTML. That already exists (an ```html artifact runs in the
+// sandbox) and is deliberately powerless: it is untrusted text, so it can only draw. A view
+// is declared by a capability that a user or admin approved at load time, which is what
+// makes it safe to give it something a model-authored page can never have — the ability to
+// ACT, by invoking capabilities.
+//
+// The rule that keeps that safe is one line: a view may invoke only what its own capability
+// is already allowed to invoke. A calculator view can compute because its capability may; it
+// cannot read history unless that capability was granted `history` in the first place. There
+// is no path here that widens a permission — `mayInvoke` can only ever name capabilities the
+// declaring capability already lists in `requires`, and validateViewInvocation refuses
+// anything outside that set before the kernel is ever consulted.
+//
+// Pure and host-free by design: no DOM, no postMessage, no chrome.*. The client owns the
+// transport; this owns what is legal to say over it.
+
+import { EventError } from './event.js';
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+
+/**
+ * Validate a view DECLARATION. Like the rest of the capability contract this must be
+ * readable — and therefore approvable — without executing anything.
+ */
+export function validateView(view, capability = null) {
+  if (!view || typeof view !== 'object') throw new EventError('SHAPE', 'view must be an object');
+  if (!str(view.id)) throw new EventError('SHAPE', 'view.id required');
+  if (!str(view.html)) throw new EventError('SHAPE', 'view.html required — a self-contained document');
+  if (view.mayInvoke != null && !(Array.isArray(view.mayInvoke) && view.mayInvoke.every(str))) {
+    throw new EventError('SHAPE', 'view.mayInvoke must be string[]');
+  }
+  // NO PRIVILEGE ESCALATION BY DECLARATION. A view is part of its capability, so it cannot
+  // reach past it: every id it wants to call must already be in that capability's `requires`
+  // (or be the capability itself). Caught here, at approval time, rather than at call time.
+  if (capability && view.mayInvoke?.length) {
+    const allowed = new Set([capability.id, ...(capability.requires || [])]);
+    const extra = view.mayInvoke.filter((id) => !allowed.has(id));
+    if (extra.length) {
+      throw new EventError('CONTRADICTION',
+        `view.mayInvoke exceeds its capability: ${extra.join(', ')} not in requires`);
+    }
+  }
+  if (view.height != null && !(Number.isInteger(view.height) && view.height > 0 && view.height <= 2000)) {
+    throw new EventError('SHAPE', 'view.height must be a positive integer <= 2000');
+  }
+  return view;
+}
+
+/**
+ * Turn a message a VIEW sent into a capability invocation the kernel can judge — or refuse
+ * it. The view is sandboxed and its messages are untrusted input, so nothing here trusts a
+ * field: the capability id is checked against what the declaration allows, not against what
+ * the message claims to be entitled to.
+ *
+ * Returns { capability, args, callId }. Throws EventError otherwise.
+ */
+export function validateViewInvocation(msg, capability) {
+  if (!capability?.view) throw new EventError('SHAPE', 'capability declares no view');
+  if (!msg || typeof msg !== 'object') throw new EventError('SHAPE', 'view message must be an object');
+  if (!str(msg.callId)) throw new EventError('SHAPE', 'view message needs a callId to correlate its result');
+  if (!str(msg.capability)) throw new EventError('SHAPE', 'view message must name a capability');
+
+  const allowed = new Set([capability.id, ...(capability.view.mayInvoke || [])]);
+  if (!allowed.has(msg.capability)) {
+    // The important refusal. A compromised or buggy view asking for something else stops
+    // here, before any kernel guard has to have an opinion about it.
+    throw new EventError('DENIED',
+      `view of "${capability.id}" may not invoke "${msg.capability}"`);
+  }
+  if (msg.args != null && (typeof msg.args !== 'object' || Array.isArray(msg.args))) {
+    throw new EventError('SHAPE', 'view invocation args must be an object');
+  }
+  return { capability: msg.capability, args: msg.args || {}, callId: msg.callId };
+}
+
+/**
+ * The state a view is mounted with, as it appears on a capability RESULT. Kept separate from
+ * the canonical value: `value` is what the capability computed and what everything else
+ * reasons about; `view`/`state` are only how it is shown. A host that cannot render views
+ * ignores these two fields and still has the whole answer.
+ */
+export function viewResult(value, capability, state = null) {
+  if (!capability?.view) return { value };
+  return { value, view: capability.view.id, state: state ?? value };
+}

package/src/mcp-quarantine.js

@@ -0,0 +1,110 @@
+// Why a turn should not die because a server it never used could not log in.
+//
+// A CLI agent loads EVERY MCP server in the user's own config on every single run. One that
+// cannot authenticate — an expired OAuth token, a VPN-only host seen from a coffee shop —
+// takes the whole turn down with it, even when the question had nothing to do with that
+// server. The user is then told to go re-login to something they never asked for.
+//
+// So: read the failure, name the server, drop it, run again. Two ways in —
+//   1. the user's own deny list (`options.mcpDisabled`), for servers they know they don't
+//      want ChatPanel to load at all; and
+//   2. QUARANTINE — a server that just killed a run is dropped automatically and stays
+//      dropped for the rest of the bridge's session, since it will not have healed in the
+//      twenty seconds before the next message.
+//
+// Two rules keep this honest. It is never silent: dropping a tool without saying so is worse
+// than failing loudly, so the engine emits a status line naming what it skipped. And it never
+// drops ChatPanel's OWN injected server — that one failing is our bug to surface, not a
+// nuisance to route around (silently disabling it would take "Act on page" with it).
+//
+// Engine-agnostic on purpose: Codex renders this as `-c mcp_servers.X.enabled=false`, Claude
+// Code and Copilot as their own flags, but the POLICY — which servers may load this turn —
+// is one decision, made here, not re-derived per engine.
+
+import { mcpFailure } from './cli-errors.js';
+
+// A server that failed is dropped for this long. Long enough that a chat session never pays
+// the same failed startup twice; short enough that reconnecting the VPN and waiting a while
+// brings the server back without restarting the bridge.
+const TTL_MS = Number(process.env.CHATPANEL_MCP_QUARANTINE_MS) || 30 * 60_000;
+
+const dropped = new Map(); // `${agent} ${server}` -> expiry epoch ms
+
+const key = (agent, server) => `${agent} ${server}`;
+
+function prune(now = Date.now()) {
+  for (const [k, expiry] of dropped) if (expiry <= now) dropped.delete(k);
+}
+
+/**
+ * Server names are interpolated into a config override key (`mcp_servers.<name>.enabled`),
+ * so they are validated rather than escaped: anything that isn't a plain MCP server name is
+ * dropped. Dots are excluded too — Codex's `-c` parser reads them as further path segments
+ * and rejects the quoted form. Accepts an array or a comma/space-separated string (what the
+ * settings field holds).
+ */
+const NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** One name, validated whole — no splitting, so junk is rejected rather than chopped valid. */
+export function validName(value) {
+  const name = String(value || '').trim();
+  return NAME_RE.test(name) ? name : null;
+}
+
+export function normalizeNames(value) {
+  const list = Array.isArray(value) ? value : String(value || '').split(/[,\s]+/);
+  const out = [];
+  for (const raw of list) {
+    const name = validName(raw);
+    if (name && !out.includes(name)) out.push(name);
+  }
+  return out;
+}
+
+/** The servers currently quarantined for an agent. */
+export function quarantined(agent) {
+  prune();
+  const prefix = key(agent, '');
+  return [...dropped.keys()].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+}
+
+/** Drop a server for this agent. Returns false when it was already dropped. */
+export function quarantine(agent, server) {
+  const name = validName(server);
+  if (!name) return false;
+  const k = key(agent, name);
+  const fresh = !dropped.has(k);
+  dropped.set(k, Date.now() + TTL_MS);
+  return fresh;
+}
+
+/** Test seam — the store is process-global by design. */
+export function resetQuarantine() {
+  dropped.clear();
+}
+
+/**
+ * Every server this run must not load: the user's deny list plus anything quarantined,
+ * minus the servers ChatPanel itself injected (never route around our own).
+ */
+export function disabledMcpServers(agent, options = {}, protect = []) {
+  const guard = new Set(normalizeNames(protect));
+  const names = [...normalizeNames(options.mcpDisabled), ...quarantined(agent)];
+  return [...new Set(names)].filter((n) => !guard.has(n));
+}
+
+/**
+ * Should this failed run be retried without one of the agent's own MCP servers?
+ * Returns the server to drop, or null — and null is the safe answer: a failure that names no
+ * server, or names one we already dropped, means retrying would only fail the same way.
+ * @returns {{server: string, kind: string, short: string}|null}
+ */
+export function planMcpRetry({ agent = '', text = '', protect = [], already = [] } = {}) {
+  const failure = mcpFailure(text);
+  if (!failure?.server) return null;
+  if (!validName(failure.server)) return null; // a name we could never write as an override
+  if (normalizeNames(protect).includes(failure.server)) return null;
+  if (normalizeNames(already).includes(failure.server)) return null;
+  if (quarantined(agent).includes(failure.server)) return null;
+  return { server: failure.server, kind: failure.kind, short: failure.short };
+}

package/src/pii/index.js

@@ -0,0 +1,29 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-pii/index.js (npm @chatpanel/pii).
+// Edit there, then run: npm run sync:pii
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// chatpanel-pii — the canonical ChatPanel privacy engine. Single source of truth
+// for reversible PII redaction + pseudonymization, shared by the extension, the
+// gateway, and the bridge. Pure + dependency-free ESM.
+//
+//   import { createVault, redactText, restoreText, detectEntities } from 'chatpanel-pii';
+//
+// Submodules are also importable directly:
+//   'chatpanel-pii/pii-redact.js'   deterministic redact/restore + vault
+//   'chatpanel-pii/pii-detect.js'   local NER / LLM entity detection
+//   'chatpanel-pii/pipeline.js'     pure turn orchestration + tier/scope selection
+//   'chatpanel-pii/tool-rank.js'    deterministic tool narrowing (auto mode)
+//   'chatpanel-pii/sanitize.js'     Unicode de-steganography (strip invisible/format chars)
+//   'chatpanel-pii/net.js'          SSRF host classifier + outbound-URL guard
+
+export * from './pii-redact.js';
+export * from './pii-detect.js';
+export * from './pipeline.js';
+export * from './tool-rank.js';
+export * from './tool-harness.js';
+export * from './sanitize.js';
+export * from './net.js';

package/src/pii/net.js

@@ -0,0 +1,111 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-pii/net.js (npm @chatpanel/pii).
+// Edit there, then run: npm run sync:pii
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// Shared host classifier + outbound-URL guard — the SSRF primitive.
+//
+// One implementation of "what is a loopback / cloud-metadata / private host",
+// delivered the way the rest of @chatpanel/pii is: npm dependency for the
+// gateway/bridge, vendorable into the browser extension (pure — only URL + string
+// ops, no node APIs, so it runs in a Worker/service-worker too). Replaces the
+// hand-maintained copies in the bridge (src/ssrf.js) and the extension
+// (js/context.js isBlockedHost) so a security guard can't silently drift between
+// the direct client path and the proxied path. See docs/secure-data-plane.md.
+//
+// The policy knobs cover the two legitimate trust contexts:
+//   • A MODEL / API / MCP endpoint (gateway upstream, bridge MCP proxy) may live on
+//     loopback (Ollama, LM Studio) or the LAN (a homelab GPU box) — so those are
+//     allowed by default — but must NEVER reach cloud instance metadata.
+//   • A WEB PAGE fetch (link title, page context) has no business touching loopback
+//     or any private host at all — call with { allowLoopback:false, allowPrivate:false }.
+// Cloud metadata (169.254.169.254 & friends) and non-http(s) schemes are blocked in
+// BOTH contexts, unconditionally. Re-run the assert on every redirect hop.
+
+function ipv4(h) {
+  const m = String(h).match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!m) return null;
+  const o = m.slice(1).map(Number);
+  if (o.some((n) => n > 255)) return null;
+  return o;
+}
+
+const norm = (hostname) => String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+
+// Loopback = this host's own services (127.0.0.0/8, ::1, localhost, *.localhost).
+export function isLoopbackHost(hostname) {
+  const h = norm(hostname);
+  if (!h) return false;
+  if (h === 'localhost' || h.endsWith('.localhost')) return true;
+  if (h === '::1') return true;
+  const o = ipv4(h);
+  return !!(o && o[0] === 127);
+}
+
+// Cloud instance metadata — the sharpest SSRF target (credential theft). Covers the
+// link-local IMDS address used by AWS/GCP/Azure/DO (169.254.169.254), Alibaba's
+// 100.100.100.200, and the GCP/name-based metadata hosts. ALWAYS blocked.
+export function isMetadataHost(hostname) {
+  const h = norm(hostname);
+  if (h === 'metadata.google.internal' || h === 'metadata') return true;
+  const o = ipv4(h);
+  if (!o) return false;
+  if (o[0] === 169 && o[1] === 254) return true;                 // 169.254.169.254 (+ link-local)
+  if (o[0] === 100 && o[1] === 100 && o[2] === 100 && o[3] === 200) return true; // Alibaba IMDS
+  return false;
+}
+
+// Private / internal address space, EXCLUDING loopback + metadata (checked
+// separately): RFC1918, CGNAT, IPv6 ULA/link-local, mDNS .local, this-host 0.x/::.
+export function isPrivateHost(hostname) {
+  const h = norm(hostname);
+  if (!h) return true;
+  if (h.endsWith('.local')) return true;
+  if (
+    h === '::' || h.startsWith('fc') || h.startsWith('fd')       // IPv6 ULA
+    || h.startsWith('fe8') || h.startsWith('fe9') || h.startsWith('fea') || h.startsWith('feb') // link-local
+  ) return true;
+  const o = ipv4(h);
+  if (o) {
+    const [a, b] = o;
+    if (a === 0 || a === 10) return true;                        // this-host / RFC1918
+    if (a === 169 && b === 254) return true;                     // link-local
+    if (a === 172 && b >= 16 && b <= 31) return true;            // RFC1918
+    if (a === 192 && b === 168) return true;                     // RFC1918
+    if (a === 100 && b >= 64 && b <= 127) return true;           // CGNAT
+  }
+  return false;
+}
+
+// Policy-driven classifier. Returns true if `hostname` must be blocked under `policy`.
+// Defaults model the ENDPOINT context (loopback + LAN allowed, metadata never).
+export function isBlockedHost(hostname, { allowLoopback = true, allowPrivate = true } = {}) {
+  const h = norm(hostname);
+  if (!h) return true;
+  if (isMetadataHost(h)) return true;                            // never, in any context
+  if (isLoopbackHost(h)) return !allowLoopback;
+  if (isPrivateHost(h)) return !allowPrivate;
+  return false;                                                  // public host
+}
+
+// Assert a URL is fetchable under `policy`; returns the parsed URL or throws.
+// Call on the initial URL AND after every redirect hop.
+export function assertFetchableUrl(u, policy = {}) {
+  let parsed;
+  try { parsed = new URL(u); } catch { throw new Error(`invalid URL: ${u}`); }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`only http(s) URLs allowed (got "${parsed.protocol}")`);
+  }
+  if (isBlockedHost(parsed.hostname, policy)) {
+    throw new Error(`refusing to reach a blocked address (${parsed.hostname})`);
+  }
+  return parsed;
+}
+
+// Endpoint context: model/API/MCP upstream — loopback + LAN OK, metadata never.
+export const assertEndpointUrl = (u, opts = {}) => assertFetchableUrl(u, { allowLoopback: true, allowPrivate: true, ...opts });
+// Web-page context: no loopback, no private, no metadata — genuinely public only.
+export const assertPublicWebUrl = (u) => assertFetchableUrl(u, { allowLoopback: false, allowPrivate: false });