@chatpanel/events 0.7.0 → 0.9.0

package/index.js

@@ -44,6 +44,7 @@ export { createKernel, meetDecisions, KernelError, REQUIRED_PLUGINS, ALLOW_ALL }
 export { replay, formatReport, parseJsonl, toJsonl } from './harness.js';
 export { compileQuery, findMatches, matchIndexFor, expandReplacement, replaceMatch, replaceAll, replaceAllInRange, MAX_MATCHES } from './text-search.js';
 export { DATA_SCOPES } from './scopes.js';
+export { SOURCE_TRUST, SkillSourceError, defineSkillSource, createSkillSourceRegistry } from './skill-sources.js';
 export { SKILL_MANIFEST_VERSION, SKILL_CONTEXTS, SKILL_HISTORY_SCOPES, SKILL_MCP_MODES, SKILL_TRUST, SKILL_FILE_KINDS, SKILL_UPCASTERS, SkillManifestError, isSafeSkillPath, originOf, trustOf, skillFiles, needsBridge, declaredAccess, originLabel, sameSkillOrigin, skillIsStale, validateSkill, upcastSkill, upcastSkills, normalizeSkill } from './skill-manifest.js';
 export { SKILL_VARS, SKILL_VAR_NAMES, skillVar, skillVarPattern, parseSkillVars, lintSkillPrompt, suggestSkillVar, substituteSkillVars, skillVarGuidance, SkillVarError } from './skill-vars.js';
 export { outlineOf, parseListItem, continueList, indentSelection, toggleWrap, toggleLinePrefix, toggleTask, toggleLink, docStats, selectionStats } from './markdown-authoring.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.7.0",
+  "version": "0.9.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,8 @@
     "./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",
     "./sources.js": "./sources.js",
@@ -62,6 +64,8 @@
     "scopes.js",
     "search-engines.js",
     "skill-manifest.js",
+    "skill-scan.js",
+    "skill-sources.js",
     "skill-vars.js",
     "sources-retrieval.js",
     "sources.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;
+}

package/skill-sources.js

@@ -0,0 +1,162 @@
+// skill-sources.js — where skills can come from, as a contract instead of a panel.
+//
+// The instinct when adding "browse a skills hub" is to build the panel the MCP registry
+// bar was built as: one file that knows one API. That is how `history-rag.js` came to
+// hand-write three loaders, and how adding a fourth meant editing four files. The places
+// skills come from are already several — a local bridge, skills.sh, GitHub taps, a site
+// publishing /.well-known/skills, and whatever appears next — and they differ only in how
+// three functions are implemented.
+//
+// So a source is a registration. Register one and browsing, searching and installing gain
+// it at once, because each consumes the registry rather than a list.
+//
+// A SOURCE IS A CAPABILITY. `reads` is the declared access statement (P10) and `trust` is
+// the level everything it produces inherits — a source cannot promote its own skills, and
+// nothing fetched is ever `built-in`.
+//
+// ISOLATION IS THE POINT. One hub being down, slow, or returning garbage must cost that
+// hub's section of the results and nothing else. A registry whose failure mode is "no
+// skills anywhere" would be worse than the hardcoded list it replaced.
+//
+// WHAT IS SHARED IS THE CONTRACT, NOT THE SOURCE. Searching is pure orchestration and
+// lives here; the fetch a real source performs needs a platform — the extension's
+// `secureFetch`, the bridge's Node http, a mobile client's own stack — and is injected at
+// registration, the same split `adapters.js` makes for execution.
+
+import { DATA_SCOPES } from './scopes.js';
+
+export class SkillSourceError extends Error {
+  constructor(code, message) { super(message); this.name = 'SkillSourceError'; this.code = code; }
+}
+
+/**
+ * Trust a source confers on everything it produces. There is no `built-in` here on
+ * purpose: only skills compiled into the product are ours, and no registration can claim
+ * that. `local` is a source on this machine (the bridge's store); `community` is anything
+ * off the network.
+ */
+export const SOURCE_TRUST = Object.freeze(['local', 'community']);
+
+/**
+ * Declare a source.
+ *
+ * @param id       stable id; also the `origin.source` stamped on everything it yields
+ * @param label    human name, for the picker and for provenance
+ * @param trust    'local' | 'community' — inherited, never self-assigned per skill
+ * @param reads    declared access, e.g. ['net'] for a hub, [] for the local bridge
+ * @param list     ({ query, cursor }) -> { items, nextCursor? }. `items` are RECORDS
+ *                 (name + description + files), never bodies — level 0 of the ladder
+ * @param read     (id) -> a full record including its prompt. Level 1
+ * @param readFile (id, path) -> { path, text }. Level 2, optional: a source with no
+ *                 packages simply omits it
+ * @param available () -> boolean|Promise<boolean>. A source that cannot answer right now
+ *                 (bridge down, no network) is ABSENT rather than broken — the difference
+ *                 between "nothing here" and an error the user must interpret
+ */
+export function defineSkillSource({
+  id, label, trust = 'community', reads = [], list, read, readFile = null, available = null,
+}) {
+  if (!id || typeof id !== 'string') throw new SkillSourceError('BAD_SOURCE', 'source.id required');
+  if (!SOURCE_TRUST.includes(trust)) {
+    throw new SkillSourceError('BAD_SOURCE', `source '${id}': trust must be one of ${SOURCE_TRUST}`);
+  }
+  if (!Array.isArray(reads) || !reads.every((r) => DATA_SCOPES.includes(r))) {
+    throw new SkillSourceError('BAD_SOURCE', `source '${id}': reads must be within ${DATA_SCOPES}`);
+  }
+  if (typeof list !== 'function') throw new SkillSourceError('BAD_SOURCE', `source '${id}': list() required`);
+  if (typeof read !== 'function') throw new SkillSourceError('BAD_SOURCE', `source '${id}': read() required`);
+  return Object.freeze({
+    id,
+    label: label || id,
+    trust,
+    reads: Object.freeze([...reads]),
+    list,
+    read,
+    readFile: typeof readFile === 'function' ? readFile : null,
+    available: typeof available === 'function' ? available : () => true,
+  });
+}
+
+/** The registry a host binds sources into. Insertion-ordered, so results are stable. */
+export function createSkillSourceRegistry() {
+  const sources = new Map();
+  return {
+    /** Register a source. Returns its remover, so registration is revertible (P15). */
+    add(source) {
+      if (sources.has(source.id)) throw new SkillSourceError('DUPLICATE', `source '${source.id}' already registered`);
+      sources.set(source.id, source);
+      return () => sources.delete(source.id);
+    },
+
+    list() { return [...sources.values()]; },
+    get(id) { return sources.get(id) || null; },
+    has(id) { return sources.has(id); },
+
+    /**
+     * Ask every available source at once.
+     *
+     * Returns one section PER SOURCE rather than a merged list: a merged list would have
+     * to rank across hubs that share no scoring, and it would hide which source an entry
+     * came from at exactly the moment that matters. A source that throws yields an
+     * `error` section and never rejects the call.
+     */
+    async search({ query = '', cursor = '', only = null } = {}) {
+      const wanted = [...sources.values()].filter((s) => !only || only.includes(s.id));
+      return Promise.all(wanted.map(async (source) => {
+        try {
+          if (!(await source.available())) return { source: source.id, label: source.label, items: [], absent: true };
+          const page = (await source.list({ query, cursor })) || {};
+          const items = Array.isArray(page.items) ? page.items : [];
+          return {
+            source: source.id,
+            label: source.label,
+            trust: source.trust,
+            // Provenance is stamped HERE, from the registration — a source that could
+            // label its own results could label them as something more trusted.
+            items: items.map((skill) => stampOrigin(skill, source)),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+          };
+        } catch (e) {
+          return { source: source.id, label: source.label, items: [], error: String(e?.message || e) };
+        }
+      }));
+    },
+
+    /** One skill, body included, with provenance stamped the same way. */
+    async read(sourceId, skillId) {
+      const source = sources.get(sourceId);
+      if (!source) throw new SkillSourceError('UNKNOWN_SOURCE', `no source '${sourceId}'`);
+      const skill = await source.read(skillId);
+      return skill ? stampOrigin(skill, source) : null;
+    },
+
+    async readFile(sourceId, skillId, path) {
+      const source = sources.get(sourceId);
+      if (!source) throw new SkillSourceError('UNKNOWN_SOURCE', `no source '${sourceId}'`);
+      if (!source.readFile) throw new SkillSourceError('NO_FILES', `source '${sourceId}' has no package files`);
+      return source.readFile(skillId, path);
+    },
+  };
+}
+
+/**
+ * Stamp where a record came from, overriding whatever it claimed.
+ *
+ * A skill arriving from a source does not get to say which source it came from, or that
+ * it is ours: `builtin` is cleared here, and `trustOf()` then derives `community` from the
+ * presence of an origin. The record's own `origin.hash` survives — that is the content
+ * identity the scanner and the update check compare against, and only the fetcher knows it.
+ */
+function stampOrigin(skill, source) {
+  if (!skill || typeof skill !== 'object') return skill;
+  const claimed = skill.origin && typeof skill.origin === 'object' ? skill.origin : {};
+  return {
+    ...skill,
+    builtin: false,
+    origin: {
+      ...claimed,
+      source: source.id,
+      id: String(claimed.id || skill.id || ''),
+    },
+  };
+}