@chatpanel/events 0.8.0 → 0.10.0

package/index.js

@@ -28,6 +28,10 @@ export { createRegistry, REGISTRY_STATES } from './registry.js';
 export { defineSearchEngine, reconcileEngines, attemptOrder, ENGINE_KINDS, SearchEngineError } from './search-engines.js';
 export { defineToolGroup, createToolGroupRegistry, ToolGroupError } from './tool-groups.js';
 export { toolNeedFor } from './tool-need.js';
+export {
+  ACCESS_LOG_VERSION, ACCESS_LOG_MAX, redactAccessArgs, makeAccessEvent,
+  createAccessLog, makeStorageTier, formatBytes,
+} from './observability.js';
 export { routeGraph, projectChain } from './route-graph.js';
 export { defineAdapter, createAdapterRegistry, AdapterError } from './adapters.js';
 export { linkifyCitations, sourcesFromToolText } from './citations.js';

package/observability.js

@@ -0,0 +1,116 @@
+// observability.js — the contract for "who consumed what, when, and how much is stored".
+//
+// ChatPanel's data is reachable by more than one agent now: the side panel, and any CLI
+// (Codex, Claude Code, OpenCode…) wired to the gateway's MCP server. Once several agents
+// read your history and skills, you need to SEE that — which agent touched what, and how
+// much sits in each storage tier. That is one question with one answer shape, so it lives
+// here, not re-derived in every client. The extension renders it; the gateway records it;
+// a desktop/mobile app will do both against this same contract.
+//
+// Pure and dependency-free (the @chatpanel/events rule): identical code in browser ESM,
+// the gateway (Node) and a mobile JS runtime. No clock, no storage, no platform APIs —
+// the caller passes `ts`; the caller owns persistence.
+//
+// PRIVACY IS THE POINT of the redactor below. An access log that stored raw tool arguments
+// would quietly become a second copy of every search query — the exact PII we redact
+// everywhere else. So the note attached to each event is built from a per-tool WHITELIST of
+// non-sensitive fields; a search query's TEXT is never recorded, only that a search ran.
+
+export const ACCESS_LOG_VERSION = 1;
+
+// Default ring size — enough to see a working session's activity without unbounded growth.
+export const ACCESS_LOG_MAX = 500;
+
+// Per-tool whitelist: which argument fields are safe to keep in the human note. Anything not
+// listed here is dropped. Content-bearing fields (a search `query`) are deliberately ABSENT —
+// the tool name already says "a search happened"; the words searched are not logged.
+const SAFE_ARGS = {
+  search_history: ['limit'],
+  list_history: ['limit', 'offset'],
+  get_record: ['id'],            // opaque record id, not content
+  open_skill: ['skill'],         // skill names are catalog identifiers, not PII
+  read_skill_file: ['skill', 'path'],
+  list_skills: ['limit'],
+};
+
+/**
+ * A short, SAFE descriptor of a call's arguments for display. Never returns content that
+ * could carry PII. Unknown tools get an empty note (the tool name is the only signal).
+ */
+export function redactAccessArgs(tool, args) {
+  const allow = SAFE_ARGS[tool];
+  if (!allow || !args || typeof args !== 'object') return '';
+  const parts = [];
+  for (const key of allow) {
+    const v = args[key];
+    if (v === undefined || v === null || v === '') continue;
+    // Cap any string field so a long id/path can't smuggle content or blow up the row.
+    const s = typeof v === 'string' ? (v.length > 80 ? `${v.slice(0, 77)}…` : v) : String(v);
+    parts.push(`${key}=${s}`);
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Normalize one access into the record everything stores and renders. `client` is the calling
+ * agent's self-reported name (MCP clientInfo) — untrusted, so it's coerced to a short string.
+ */
+export function makeAccessEvent({ ts, client, tool, ok = true, ms, args, error } = {}) {
+  return {
+    v: ACCESS_LOG_VERSION,
+    ts: Number(ts) || 0,
+    client: shortStr(client, 'unknown', 60),
+    tool: shortStr(tool, 'unknown', 60),
+    ok: !!ok,
+    ms: Number.isFinite(ms) ? Math.max(0, Math.round(ms)) : null,
+    note: redactAccessArgs(tool, args),
+    error: error ? shortStr(error, '', 200) : '',
+  };
+}
+
+function shortStr(v, fallback, max) {
+  const s = (v == null ? '' : String(v)).trim() || fallback;
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+/**
+ * A tiny fixed-capacity ring for access events. Pure and synchronous — the gateway keeps one
+ * in memory and snapshots it for the dashboard; the caller decides whether/how to persist.
+ */
+export function createAccessLog(max = ACCESS_LOG_MAX) {
+  const cap = Math.max(1, max | 0);
+  let buf = [];
+  return {
+    push(evt) { buf.push(evt); if (buf.length > cap) buf = buf.slice(buf.length - cap); return evt; },
+    // Newest first, optionally limited — the order a dashboard wants.
+    snapshot(limit) { const out = buf.slice().reverse(); return limit ? out.slice(0, limit) : out; },
+    get size() { return buf.length; },
+    clear() { buf = []; },
+  };
+}
+
+// ── Storage tiers ────────────────────────────────────────────────────────────────────────
+// One descriptor per place data lives: hot (browser), warm (local gateway), cold (cloud,
+// future). The dashboard renders a row per tier; a tier that isn't configured says so.
+
+export function makeStorageTier({ tier, label, present = true, records = null, bytes = null, newest = null, note = '' } = {}) {
+  return {
+    tier: String(tier || ''),
+    label: String(label || tier || ''),
+    present: !!present,
+    records: records == null ? null : Math.max(0, records | 0),
+    bytes: bytes == null ? null : Math.max(0, Number(bytes) || 0),
+    newest: newest == null ? null : Number(newest) || 0,
+    note: String(note || ''),
+  };
+}
+
+/** Human-friendly byte size. Binary units, one decimal above KB. */
+export function formatBytes(n) {
+  const b = Number(n);
+  if (!Number.isFinite(b) || b <= 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let i = 0, v = b;
+  while (v >= 1024 && i < units.length - 1) { v /= 1024; i++; }
+  return `${i === 0 ? Math.round(v) : v.toFixed(1)} ${units[i]}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
@@ -27,6 +27,7 @@
     "./scopes.js": "./scopes.js",
     "./search-engines.js": "./search-engines.js",
     "./skill-manifest.js": "./skill-manifest.js",
+    "./skill-scan.js": "./skill-scan.js",
     "./skill-sources.js": "./skill-sources.js",
     "./skill-vars.js": "./skill-vars.js",
     "./sources-retrieval.js": "./sources-retrieval.js",
@@ -36,7 +37,8 @@
     "./tool-groups.js": "./tool-groups.js",
     "./tool-need.js": "./tool-need.js",
     "./trajectory.js": "./trajectory.js",
-    "./upcast.js": "./upcast.js"
+    "./upcast.js": "./upcast.js",
+    "./observability.js": "./observability.js"
   },
   "files": [
     "LICENSE",
@@ -54,6 +56,7 @@
     "markdown-authoring.js",
     "mcp-errors.js",
     "meeting-analyzers.js",
+    "observability.js",
     "order.js",
     "ref.js",
     "registry.js",
@@ -63,6 +66,7 @@
     "scopes.js",
     "search-engines.js",
     "skill-manifest.js",
+    "skill-scan.js",
     "skill-sources.js",
     "skill-vars.js",
     "sources-retrieval.js",

package/skill-scan.js

@@ -0,0 +1,210 @@
+// skill-scan.js — is this skill safe to admit?
+//
+// A SKILL.md is a prompt that will run with page tools, MCP servers and history attached.
+// Once skills can arrive from a hub, a repo or a shared folder, that makes it an injection
+// payload with a distribution channel — the reason every serious agent harness quarantines
+// what it installs. This is the gate F6 puts in front of admission.
+//
+// THE PRECISION PROBLEM IS THE WHOLE DESIGN. A scanner that flags legitimate skills is
+// worse than none: people learn to click past it, and then it protects nothing. Real
+// skills are full of shell examples, curl commands and API docs. So:
+//
+//   • `dangerous` requires high-precision evidence — an instruction override aimed at the
+//     model, or a CREDENTIAL PATH combined with an OUTBOUND SINK in the same breath.
+//     Neither half alone is enough: `curl https://api.example.com` is documentation and
+//     `~/.aws/credentials` is a sentence about configuration.
+//   • `suspicious` is for things worth a human glance that are not proof of anything.
+//   • everything else is `clean`, and the common case must be clean.
+//
+// It is a heuristic gate, not a proof. It stops the obvious and the careless; it is not a
+// claim that an admitted skill is safe, which is why provenance stays visible at use time
+// and why scripts stay behind a separate confirmation.
+//
+// Pure and clock-free: the caller stamps the time, so the same input always produces the
+// same finding list and a verdict can be cached by content hash.
+
+export class SkillScanError extends Error {
+  constructor(code, message) { super(message); this.name = 'SkillScanError'; this.code = code; }
+}
+
+/** Bump when a rule changes: a cached verdict from an older scanner must not be trusted. */
+export const SCANNER_VERSION = 1;
+
+export const SCAN_VERDICTS = Object.freeze(['clean', 'suspicious', 'dangerous']);
+
+const RANK = { clean: 0, suspicious: 1, dangerous: 2 };
+
+// Characters that carry no visible meaning and exist in a prompt for one reason: to hide
+// text from the person reading it while the model still sees it. Zero-width joiners,
+// bidirectional overrides, and the Unicode tag block used for "invisible" instructions.
+// eslint-disable-next-line no-misleading-character-class
+const HIDDEN = /[​-‏‪-‮⁠-⁤⁦-⁩\u{e0000}-\u{e007f}]/u;
+
+// Aimed at the MODEL rather than describing anything. Deliberately narrow: "ignore the
+// previous section" is ordinary prose, "ignore all previous instructions" is not.
+const OVERRIDE = [
+  /\bignore\s+(?:all\s+|any\s+)?(?:previous|prior|earlier|above)\s+(?:instructions?|prompts?|rules?|directions?)\b/i,
+  /\bdisregard\s+(?:all\s+|any\s+)?(?:previous|prior|the)\s+(?:instructions?|system\s+prompt|rules?)\b/i,
+  /\b(?:forget|override)\s+(?:everything|all)\s+(?:you|above|previously)\b/i,
+  /\byou\s+are\s+no\s+longer\s+(?:bound|restricted|required)\b/i,
+  /<\/?(?:system|assistant)\b[^>]*>/i,
+  /\bnew\s+system\s+prompt\s*:/i,
+];
+
+// Telling the model to keep something from the person it is working for. Real injection
+// signature — and also, sometimes, ordinary editorial guidance, which is why it is
+// SUSPICIOUS rather than dangerous.
+//
+// Codex's own `plugin-creator` skill is the case that settled the severity: it says "Do
+// not tell the user to run `codex plugin marketplace add`", which is advice about what to
+// recommend, not concealment. A first-party skill quarantined by a rule that cannot tell
+// those apart would teach people to click past the gate — so the phrasing is narrowed
+// (`to <verb>` is excluded) AND the severity is honest about what the match proves.
+const CONCEALMENT = [
+  /\b(?:do\s+not|don't|never)\s+(?:tell|inform)\s+the\s+user\b(?!\s+to\s)/i,
+  /\b(?:do\s+not|don't|never)\s+(?:mention|reveal|disclose)\s+(?:this|that|it|any(?:thing)?)?\s*to\s+the\s+user\b/i,
+  /\bwithout\s+(?:telling|informing|notifying)\s+the\s+user\b/i,
+  /\bhide\s+(?:this|that|it)\s+from\s+the\s+user\b/i,
+];
+
+// Things that identify a secret. A path or a well-known variable name — not the word
+// "token", which appears in every API document ever written.
+const CREDENTIAL = [
+  /~\/\.ssh\/|\bid_rsa\b|\bid_ed25519\b/i,
+  /~\/\.aws\/credentials|\bAWS_SECRET_ACCESS_KEY\b/i,
+  /\.env\b(?!\w)|\bprintenv\b|\benv\s*\|/i,
+  /~\/\.netrc|\.git-credentials|\bkeychain\s+dump\b/i,
+  /\bGITHUB_TOKEN\b|\bNPM_TOKEN\b|\bOPENAI_API_KEY\b|\bANTHROPIC_API_KEY\b/,
+  /~\/\.config\/(?:gh|gcloud)\/|\bgcloud\s+auth\s+print-access-token\b/i,
+];
+
+// Something that sends data OFF the machine. An outbound body, not a fetch.
+const SINK = [
+  /\bcurl\b[^\n|]*(?:-d|--data|--data-binary|-F|--form|-T|--upload-file)\b/i,
+  /\bwget\b[^\n|]*--post-(?:data|file)\b/i,
+  /\b(?:nc|netcat|ncat)\b\s+[\w.-]+\s+\d+/i,
+  /\bfetch\s*\([^)]*method\s*:\s*['"]POST/i,
+  /\brequests\.post\s*\(/i,
+  /\|\s*(?:curl|nc|netcat)\b/i,
+  /\bscp\b\s+\S+\s+\S+@/i,
+];
+
+// Irreversible, and never something a skill document needs to demonstrate literally.
+const DESTRUCTIVE = [
+  { re: /\brm\s+-[a-z]*[rR][a-z]*f[a-z]*\s+(?:--no-preserve-root\s+)?(?:\/|~|\$HOME)(?:\/\s|\/?[`'"\s]|$)/, why: 'recursive delete of a root or home directory' },
+  { re: /\bmkfs(?:\.\w+)?\b/, why: 'filesystem format' },
+  { re: /\bdd\s+[^\n]*\bof=\/dev\/(?:sd|nvme|disk)/, why: 'raw write to a block device' },
+  { re: /:\(\)\s*\{\s*:\|:&\s*\}\s*;\s*:/, why: 'fork bomb' },
+  { re: /\bchmod\s+-R\s+777\s+\//, why: 'world-writable root' },
+  { re: /\bhistory\s+-c\b|\bshred\b\s+[^\n]*\.(?:log|history)/, why: 'covering tracks' },
+];
+
+const SUSPECT = [
+  { re: /\b(?:eval|exec)\s*\(\s*(?:atob|base64|Buffer\.from)/i, why: 'executes decoded content' },
+  { re: /\bbase64\s+-d\b[^\n]*\|\s*(?:sh|bash|zsh|python)/i, why: 'pipes decoded content to a shell' },
+  { re: /\bcurl\b[^\n]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b/i, why: 'pipes a download straight into a shell' },
+  { re: /[A-Za-z0-9+/]{280,}={0,2}/, why: 'a large opaque base64 blob' },
+  { re: /\bhttp:\/\/(?!localhost|127\.0\.0\.1|\[::1\])[\w.-]+/i, why: 'sends or fetches over plain HTTP' },
+  { re: /\bsudo\s+(?:-S\s+)?[^\n]*<<</i, why: 'feeds a password to sudo' },
+];
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+const excerpt = (text, index, len = 90) => text.slice(Math.max(0, index - 10), index + len).replace(/\s+/g, ' ').trim();
+
+function find(text, re) {
+  const m = re.exec(text);
+  return m ? { index: m.index, match: m[0] } : null;
+}
+
+/**
+ * Scan one skill.
+ *
+ * @param name    for the finding messages
+ * @param prompt  the SKILL.md body — the thing that becomes a prompt
+ * @param files   declared package paths, e.g. ['references/a.md', 'scripts/run.py']
+ * @param extra   additional text to scan (a reference document's contents, when the caller
+ *                has fetched them). Scanned under the same rules: a skill that points at a
+ *                clean-looking file which itself carries the payload is the obvious dodge.
+ *
+ * -> { verdict, findings: [{ rule, severity, line, excerpt, why }], scanner }
+ */
+export function scanSkill({ name = '', prompt = '', files = [], extra = '' } = {}) {
+  const text = [String(prompt || ''), String(extra || '')].filter(Boolean).join('\n\n');
+  const findings = [];
+  const add = (rule, severity, hit, why) => {
+    findings.push({
+      rule,
+      severity,
+      why,
+      line: hit ? lineOf(text, hit.index) : 0,
+      excerpt: hit ? excerpt(text, hit.index) : '',
+    });
+  };
+
+  if (HIDDEN.test(text)) {
+    // No legitimate reason for a procedure document to contain characters the reader
+    // cannot see but the model can.
+    add('hidden-text', 'dangerous', find(text, HIDDEN), 'contains characters that are invisible to a reader but not to the model');
+  }
+
+  for (const re of OVERRIDE) {
+    const hit = find(text, re);
+    if (hit) { add('instruction-override', 'dangerous', hit, 'tries to override the instructions it is running under'); break; }
+  }
+
+  for (const re of CONCEALMENT) {
+    const hit = find(text, re);
+    if (hit) { add('concealment', 'suspicious', hit, 'asks the model to keep something from the user'); break; }
+  }
+
+  // The combination is the evidence. Either half alone is ordinary documentation.
+  const cred = CREDENTIAL.map((re) => find(text, re)).find(Boolean);
+  const sink = SINK.map((re) => find(text, re)).find(Boolean);
+  if (cred && sink) {
+    add('credential-exfiltration', 'dangerous', cred, `names a credential (${cred.match.trim().slice(0, 40)}) alongside a command that sends data off the machine`);
+  } else if (cred) {
+    add('credential-mention', 'suspicious', cred, 'refers to a credential file or secret variable');
+  } else if (sink) {
+    add('outbound-data', 'suspicious', sink, 'sends data to a remote host');
+  }
+
+  for (const { re, why } of DESTRUCTIVE) {
+    const hit = find(text, re);
+    if (hit) add('destructive-command', 'dangerous', hit, why);
+  }
+
+  for (const { re, why } of SUSPECT) {
+    const hit = find(text, re);
+    if (hit) add('suspicious-pattern', 'suspicious', hit, why);
+  }
+
+  // Scripts are not scanned as prose — they are code, and this is not a code analyser.
+  // Their presence is reported so the reviewer knows execution is on the table at all.
+  const scripts = (Array.isArray(files) ? files : []).filter((f) => String(f).startsWith('scripts/'));
+  if (scripts.length) {
+    findings.push({
+      rule: 'ships-executable',
+      severity: 'suspicious',
+      why: `ships ${scripts.length} executable file${scripts.length === 1 ? '' : 's'} (${scripts.join(', ')}) — these run on your machine, not in the browser`,
+      line: 0,
+      excerpt: '',
+    });
+  }
+
+  const verdict = findings.reduce((worst, f) => (RANK[f.severity] > RANK[worst] ? f.severity : worst), 'clean');
+  return { verdict, findings, scanner: SCANNER_VERSION, name: String(name || '') };
+}
+
+/** Is this verdict allowed to enter the index at all? */
+export function admits(verdict) {
+  return verdict !== 'dangerous';
+}
+
+/** A one-line reason, for a card or a refusal. */
+export function scanSummary(scan) {
+  if (!scan || scan.verdict === 'clean') return '';
+  const worst = (scan.findings || []).filter((f) => f.severity === scan.verdict);
+  const first = worst[0];
+  const more = worst.length > 1 ? ` (+${worst.length - 1} more)` : '';
+  return first ? `${first.why}${more}` : scan.verdict;
+}