@chatpanel/events 0.102.0 → 0.103.1

package/search-engines.js

@@ -1,81 +1 @@
-// Search engines as declarations, not as a literal in two files.
-//
-// This one is not speculative. The engine list existed as an array in the search runtime
-// AND as a copy in the settings page, and when a broken engine was removed from one it kept
-// appearing in the other. Two implementations of one list disagree eventually; the only
-// reliable fix is for there to be one list.
-//
-// It is also where the plugin model pays off soonest for a USER: an engine is a name, a URL
-// template, and a way to read the result. That is a thing someone could contribute without
-// touching any code we wrote.
-
-export class SearchEngineError extends Error {
-  constructor(code, message) { super(message); this.name = 'SearchEngineError'; this.code = code; }
-}
-
-export const ENGINE_KINDS = Object.freeze(['serp', 'api']);
-
-/**
- * @param kind    'serp' — an HTML results page to read; 'api' — a service that answers
- *                directly. The distinction is not cosmetic: a SERP can be blocked and
- *                needs a fallback, an API can need a key and must not run without one.
- * @param needsKey the engine sends queries to a third party that requires credentials.
- *                Engines that need a key stay OFF until one exists, because a default that
- *                sends the user's queries somewhere they never chose is not a default.
- */
-export function defineSearchEngine({ id, name, url, kind = 'serp', enabled = false, needsKey = false, retired = false }) {
-  if (!id) throw new SearchEngineError('BAD_ENGINE', 'engine.id required');
-  if (!ENGINE_KINDS.includes(kind)) throw new SearchEngineError('BAD_ENGINE', `engine '${id}': unknown kind '${kind}'`);
-  if (!retired && !url) throw new SearchEngineError('BAD_ENGINE', `engine '${id}': url required`);
-  return Object.freeze({ id, name: name || id, url, kind, enabled, needsKey, retired });
-}
-
-/**
- * Reconcile a user's stored list against the declared engines.
- *
- * The one function both the runtime and the settings page call, so what search uses and
- * what settings shows cannot drift — which is the entire bug this replaces.
- */
-export function reconcileEngines(stored, declared, { hasKey = false } = {}) {
-  const byId = new Map(declared.map((e) => [e.id, e]));
-  const retired = new Set(declared.filter((e) => e.retired).map((e) => e.id));
-
-  let out = (Array.isArray(stored) && stored.length ? stored : declared)
-    .filter((e) => e?.id && !retired.has(e.id))
-    .map((e) => ({ ...(byId.get(e.id) || {}), ...e }));
-
-  // Anything declared but never seen by this user is added, off unless it ships on. A user
-  // who has saved settings once must still receive new engines.
-  for (const d of declared) {
-    if (d.retired || out.some((e) => e.id === d.id)) continue;
-    out.push({ ...d });
-  }
-
-  out = out.map((e) => {
-    const d = byId.get(e.id);
-    if (!d?.needsKey) return e;
-    // "They turned it off" and "it has never been offered" are different states: a key
-    // enables the second, never overrides the first.
-    const known = Array.isArray(stored) && stored.some((s) => s?.id === e.id);
-    const declined = known && stored.find((s) => s.id === e.id)?.enabled === false;
-    return { ...e, enabled: hasKey && !declined };
-  });
-
-  // Never leave the user with nothing usable. Retiring an engine can empty a list that
-  // contained only that engine, and a search feature that silently has no engines is a
-  // worse failure than the one being fixed.
-  if (!out.some((e) => e.enabled !== false && !e.needsKey)) {
-    for (const d of declared) {
-      if (d.retired || d.needsKey) continue;
-      const have = out.find((e) => e.id === d.id);
-      if (have) have.enabled = d.enabled !== false;
-    }
-  }
-  return out;
-}
-
-/** The order to actually try: enabled first (in list order), then the rest as fallbacks. */
-export function attemptOrder(engines) {
-  const live = engines.filter((e) => !e.retired);
-  return [...live.filter((e) => e.enabled !== false), ...live.filter((e) => e.enabled === false)];
-}
+class d extends Error{constructor(r,i){super(i),this.name="SearchEngineError",this.code=r}}const u=Object.freeze(["serp","api"]);function p({id:n,name:r,url:i,kind:o="serp",enabled:f=!1,needsKey:t=!1,retired:e=!1}){if(!n)throw new d("BAD_ENGINE","engine.id required");if(!u.includes(o))throw new d("BAD_ENGINE",`engine '${n}': unknown kind '${o}'`);if(!e&&!i)throw new d("BAD_ENGINE",`engine '${n}': url required`);return Object.freeze({id:n,name:r||n,url:i,kind:o,enabled:f,needsKey:t,retired:e})}function E(n,r,{hasKey:i=!1}={}){const o=new Map(r.map(e=>[e.id,e])),f=new Set(r.filter(e=>e.retired).map(e=>e.id));let t=(Array.isArray(n)&&n.length?n:r).filter(e=>e?.id&&!f.has(e.id)).map(e=>({...o.get(e.id)||{},...e}));for(const e of r)e.retired||t.some(s=>s.id===e.id)||t.push({...e});if(t=t.map(e=>{if(!o.get(e.id)?.needsKey)return e;const l=Array.isArray(n)&&n.some(a=>a?.id===e.id)&&n.find(a=>a.id===e.id)?.enabled===!1;return{...e,enabled:i&&!l}}),!t.some(e=>e.enabled!==!1&&!e.needsKey))for(const e of r){if(e.retired||e.needsKey)continue;const s=t.find(c=>c.id===e.id);s&&(s.enabled=e.enabled!==!1)}return t}function h(n){const r=n.filter(i=>!i.retired);return[...r.filter(i=>i.enabled!==!1),...r.filter(i=>i.enabled===!1)]}export{u as ENGINE_KINDS,d as SearchEngineError,h as attemptOrder,p as defineSearchEngine,E as reconcileEngines};

package/skill-manifest.js

@@ -1,330 +1 @@
-// skill-manifest.js — what a skill IS, for every client that stores or runs one.
-//
-// A skill was a settings record: a prompt plus a few dropdowns, normalized by whichever
-// client happened to save it. That was survivable while every skill was hand-written by
-// the person running it. It stops being survivable the moment a skill can ARRIVE from
-// somewhere — a hub, a repo, another agent's skill directory — because the questions
-// change from "what does this prompt say" to "where did it come from, what may it reach,
-// and has anything checked it".
-//
-// So this module owns the record. Not the storage (a platform question), not the UI (a
-// platform question), not the fetching (F6 S3) — the shape, its evolution, and the two
-// derivations no client may compute for itself:
-//
-//   • TRUST IS DERIVED, NEVER DECLARED. A skill cannot say it is trusted. `trustOf()`
-//     reads provenance: shipped by us -> 'built-in', fetched -> 'community', neither ->
-//     'user'. A stored `trust` field is stripped on normalize, and `builtin` is forced
-//     false whenever an origin is present — otherwise "trusted" would be a string an
-//     importer sets.
-//   • DECLARED ACCESS IS COMPUTED FROM THE RECORD. Everything a skill can reach is
-//     readable before it runs, which is what makes load-time approval possible (P10).
-//     If a reviewer's summary were assembled by the install screen, the install screen
-//     would be the security boundary.
-//
-// Versioning follows the log's discipline: additive only, absence means the previous
-// default, and the upcast chain exists from the start so adding v3 does not mean
-// rewriting every reader.
-
-import { DATA_SCOPES } from './scopes.js';
-
-export class SkillManifestError extends Error {
-  constructor(code, message) { super(message); this.name = 'SkillManifestError'; this.code = code; }
-}
-
-/** Schema version of the RECORD. Distinct from `version`, which is the author's semver. */
-export const SKILL_MANIFEST_VERSION = 2;
-
-export const SKILL_CONTEXTS = Object.freeze(['auto', 'page', 'selection', 'tabs', 'none']);
-export const SKILL_HISTORY_SCOPES = Object.freeze(['none', 'chats', 'meetings', 'all']);
-export const SKILL_MCP_MODES = Object.freeze(['none', 'selected', 'default']);
-
-/**
- * Derived, never stored. 'community' is deliberately the level for a skill fetched from
- * a vendor repo with a famous name — only what we ship went through our review.
- */
-export const SKILL_TRUST = Object.freeze(['built-in', 'user', 'community']);
-
-/**
- * The directories a package may carry, matching the agentskills.io layout. `scripts` is
- * the tier-3 one: it cannot run in a browser extension and must not be offered as if it
- * could (see `needsBridge`).
- */
-export const SKILL_FILE_KINDS = Object.freeze(['references', 'scripts', 'assets', 'templates', 'examples']);
-
-const str = (v) => typeof v === 'string' && v.length > 0;
-
-// A slash command is typed by a human and matched case-insensitively against a stored
-// string; anything outside this grammar either cannot be typed or collides with the
-// leading-slash parse.
-const COMMAND = /^[a-z0-9][a-z0-9_-]*$/;
-
-/**
- * A file path inside a package directory.
- *
- * The check is a security boundary, not tidiness: these strings become filesystem paths
- * in the bridge's skill store, and a package is authored by a stranger. Rejected are
- * absolute paths, any `..` segment, backslashes (a Windows separator that a POSIX
- * `split('/')` would not see as one), leading/trailing whitespace and control characters.
- * Allowing one of them is a directory-traversal write on someone's machine.
- */
-export function isSafeSkillPath(p) {
-  if (!str(p) || p.length > 255) return false;
-  if (p !== p.trim()) return false;
-  if (p.includes('\\')) return false;
-  // eslint-disable-next-line no-control-regex
-  if (/[\u0000-\u001f\u007f]/.test(p)) return false;
-  if (p.startsWith('/') || /^[a-z]:/i.test(p)) return false;
-  const parts = p.split('/');
-  if (parts.some((seg) => seg === '' || seg === '.' || seg === '..')) return false;
-  return true;
-}
-
-/** Did this skill come from somewhere, or did the user write it? */
-export function originOf(skill) {
-  const o = skill?.origin;
-  return o && typeof o === 'object' && str(o.source) && str(o.id) ? o : null;
-}
-
-/**
- * Derived from provenance, never read from the record. A skill that arrived from outside
- * is 'community' whoever published it; 'built-in' means we shipped it.
- */
-export function trustOf(skill) {
-  if (originOf(skill)) return 'community';
-  return skill?.builtin ? 'built-in' : 'user';
-}
-
-/** The files a package carries, per directory, already filtered to safe paths. */
-export function skillFiles(skill) {
-  const files = skill?.files;
-  const out = {};
-  if (!files || typeof files !== 'object') return out;
-  for (const kind of SKILL_FILE_KINDS) {
-    const list = Array.isArray(files[kind]) ? files[kind].filter(isSafeSkillPath) : [];
-    if (list.length) out[kind] = [...new Set(list)];
-  }
-  return out;
-}
-
-/**
- * True when running this skill fully needs a host that can execute code — i.e. the
- * bridge. The extension may still store, show and run the PROMPT half; what it may not
- * do is pretend the scripts ran.
- */
-export function needsBridge(skill) {
-  return (skillFiles(skill).scripts || []).length > 0;
-}
-
-/**
- * Everything this skill can reach, computed from the record. This is what an install
- * review, the Plugins lens and an admin export all read — one derivation, so the three
- * cannot disagree about what was approved.
- */
-export function declaredAccess(skill = {}) {
-  const files = skillFiles(skill);
-  const mcpMode = SKILL_MCP_MODES.includes(skill.mcpMode) ? skill.mcpMode : 'none';
-  const context = SKILL_CONTEXTS.includes(skill.context) ? skill.context : 'auto';
-  const history = SKILL_HISTORY_SCOPES.includes(skill.historyContext) ? skill.historyContext : 'none';
-  const reads = new Set(Array.isArray(skill.reads) ? skill.reads.filter((r) => DATA_SCOPES.includes(r)) : []);
-  // The dropdowns ARE access statements; a record that declared `reads` separately from
-  // them could claim less than it takes.
-  if (context !== 'none') reads.add('page');
-  if (history === 'chats' || history === 'all') reads.add('chats');
-  if (history === 'meetings' || history === 'all') reads.add('meetings');
-  return {
-    trust: trustOf(skill),
-    reads: [...reads].sort(),
-    page: context,
-    history,
-    mcp: mcpMode,
-    mcpServerIds: mcpMode === 'selected' && Array.isArray(skill.mcpServerIds) ? [...skill.mcpServerIds] : [],
-    sources: Array.isArray(skill.sources) ? [...new Set(skill.sources.filter(str))].sort() : [],
-    surfaces: Array.isArray(skill.surfaces) ? [...new Set(skill.surfaces.filter(str))].sort() : [],
-    scripts: files.scripts || [],
-    needsBridge: needsBridge(skill),
-    meeting: !!skill.meeting,
-  };
-}
-
-/** Human label for where a skill came from, for the surfaces that must show provenance. */
-export function originLabel(skill) {
-  const o = originOf(skill);
-  if (!o) return trustOf(skill) === 'built-in' ? 'Built-in' : 'Written here';
-  return o.id.length > 48 ? `${o.source} · …${o.id.slice(-40)}` : `${o.source} · ${o.id}`;
-}
-
-/** Two records describing the same upstream skill — for update checks and dedupe. */
-export function sameSkillOrigin(a, b) {
-  const x = originOf(a);
-  const y = originOf(b);
-  return !!x && !!y && x.source === y.source && x.id === y.id;
-}
-
-/**
- * Has upstream changed since this was installed? `null` when unanswerable (no origin, or
- * nothing was hashed) — which callers must treat as "do not claim it is current" rather
- * than as "up to date".
- */
-export function skillIsStale(skill, upstreamHash) {
-  const o = originOf(skill);
-  if (!o || !str(o.hash) || !str(upstreamHash)) return null;
-  return o.hash !== upstreamHash;
-}
-
-/**
- * Validate a skill DECLARATION — the static surface approved before anything runs.
- * Throws on the first problem, like `validateCapability`.
- */
-export function validateSkill(skill) {
-  if (!skill || typeof skill !== 'object') throw new SkillManifestError('SHAPE', 'skill must be an object');
-  if (!str(skill.id)) throw new SkillManifestError('SHAPE', 'skill.id required');
-  if (!str(skill.name)) throw new SkillManifestError('SHAPE', `skill '${skill.id}': name required`);
-  if (skill.prompt != null && typeof skill.prompt !== 'string') {
-    throw new SkillManifestError('SHAPE', `skill '${skill.id}': prompt must be a string`);
-  }
-  if (skill.command != null && skill.command !== '' && !COMMAND.test(String(skill.command))) {
-    throw new SkillManifestError('SHAPE', `skill '${skill.id}': command must match ${COMMAND}`);
-  }
-  for (const [field, allowed] of [
-    ['context', SKILL_CONTEXTS], ['historyContext', SKILL_HISTORY_SCOPES], ['mcpMode', SKILL_MCP_MODES],
-  ]) {
-    if (skill[field] != null && !allowed.includes(skill[field])) {
-      throw new SkillManifestError('SHAPE', `skill '${skill.id}': ${field} must be one of ${allowed}`);
-    }
-  }
-  if (skill.reads != null) {
-    if (!Array.isArray(skill.reads) || !skill.reads.every((r) => DATA_SCOPES.includes(r))) {
-      throw new SkillManifestError('SHAPE', `skill '${skill.id}': reads must be within ${DATA_SCOPES}`);
-    }
-  }
-  for (const field of ['sources', 'surfaces']) {
-    if (skill[field] != null && (!Array.isArray(skill[field]) || !skill[field].every(str))) {
-      throw new SkillManifestError('SHAPE', `skill '${skill.id}': ${field} must be an array of ids`);
-    }
-  }
-  if (skill.origin != null) {
-    const o = skill.origin;
-    if (typeof o !== 'object') throw new SkillManifestError('SHAPE', `skill '${skill.id}': origin must be an object`);
-    // Without a source and an id it cannot be re-fetched or compared, which is the whole
-    // reason the field exists; a half-origin is worse than none because it looks answered.
-    if (!str(o.source) || !str(o.id)) {
-      throw new SkillManifestError('ORIGIN', `skill '${skill.id}': origin needs both source and id`);
-    }
-  }
-  if (skill.files != null) {
-    if (typeof skill.files !== 'object') throw new SkillManifestError('SHAPE', `skill '${skill.id}': files must be an object`);
-    for (const kind of Object.keys(skill.files)) {
-      if (!SKILL_FILE_KINDS.includes(kind)) {
-        throw new SkillManifestError('FILES', `skill '${skill.id}': unknown file kind '${kind}'`);
-      }
-      const list = skill.files[kind];
-      if (!Array.isArray(list) || !list.every(str)) {
-        throw new SkillManifestError('FILES', `skill '${skill.id}': files.${kind} must be an array of paths`);
-      }
-      const bad = list.find((p) => !isSafeSkillPath(p));
-      if (bad) throw new SkillManifestError('PATH', `skill '${skill.id}': unsafe path in files.${kind}: ${JSON.stringify(bad)}`);
-    }
-  }
-  // Files without an origin means someone hand-wrote a package record; that is allowed,
-  // but scripts without an origin cannot be scanned against anything, and an unscannable
-  // script is exactly what the admission gate exists to refuse.
-  if (!originOf(skill) && (skill.files?.scripts || []).length) {
-    throw new SkillManifestError('ORIGIN', `skill '${skill.id}': scripts require an origin to be scannable`);
-  }
-  return skill;
-}
-
-/**
- * v(n) -> v(n+1). Each MUST be total: it may not throw for any record of its version.
- *
- * v1 -> v2 stamps the version and nothing else, on purpose. Every field F6 adds is
- * absence-means-the-old-default, so there is nothing to fill in — the same discipline as
- * storing which plugins are DISABLED rather than the full state, so a field added later
- * needs no migration.
- */
-export const SKILL_UPCASTERS = Object.freeze({
-  1: (s) => ({ ...s, v: SKILL_MANIFEST_VERSION }),
-});
-
-/** Carry a stored skill forward to the current schema. Pure; never mutates the input. */
-export function upcastSkill(stored) {
-  if (!stored || typeof stored !== 'object') throw new SkillManifestError('SHAPE', 'skill must be an object');
-  // A record written before the version existed is v1 by definition.
-  let s = typeof stored.v === 'number' ? stored : { ...stored, v: 1 };
-  let guard = 0;
-  while (s.v < SKILL_MANIFEST_VERSION) {
-    const step = SKILL_UPCASTERS[s.v];
-    if (!step) throw new SkillManifestError('UPCAST', `no upcaster from v${s.v}`);
-    s = step(s);
-    if (++guard > 64) throw new SkillManifestError('UPCAST', 'upcaster chain did not terminate');
-  }
-  if (s.v > SKILL_MANIFEST_VERSION) {
-    throw new SkillManifestError('UPCAST', `skill is v${s.v}; this reader only knows v${SKILL_MANIFEST_VERSION}`);
-  }
-  return s;
-}
-
-export function upcastSkills(stored) {
-  return (Array.isArray(stored) ? stored : []).map(upcastSkill);
-}
-
-/**
- * Coerce a record into the canonical shape a writer stores. Total and forgiving — this
- * runs on save, where throwing would cost a user their edit; `validateSkill` is the
- * strict gate, used where a record ARRIVES.
- *
- * The security-relevant coercions are the ones that cannot be left to a caller:
- * `trust` is never persisted, `builtin` cannot survive an origin, and an unsafe file
- * path is dropped rather than stored and rejected later.
- */
-export function normalizeSkill(skill) {
-  if (!skill || typeof skill !== 'object') return skill;
-  const out = { ...upcastSkill(skill) };
-
-  // Skills predate the enabled flag — absence means enabled.
-  out.enabled = out.enabled !== false;
-
-  const mode = String(out.mcpMode || 'none').toLowerCase();
-  out.mcpMode = SKILL_MCP_MODES.includes(mode) ? mode : 'none';
-  const ids = Array.isArray(out.mcpServerIds) ? out.mcpServerIds : [];
-  out.mcpServerIds = out.mcpMode === 'selected'
-    ? [...new Set(ids.map((id) => String(id || '').trim()).filter(Boolean))]
-    : [];
-
-  // Derived, never stored: a record that could assert its own trust would make every
-  // check downstream a formality.
-  delete out.trust;
-
-  const origin = originOf(out);
-  if (origin) {
-    out.builtin = false; // "we shipped it" is not something an import may claim
-    out.origin = {
-      source: origin.source,
-      id: origin.id,
-      ...(str(origin.url) ? { url: origin.url } : {}),
-      ...(str(origin.hash) ? { hash: origin.hash } : {}),
-      ...(origin.scanned && typeof origin.scanned === 'object' ? { scanned: { ...origin.scanned } } : {}),
-    };
-  } else if (out.origin != null) {
-    delete out.origin; // a half-origin looks answered and is not
-  }
-
-  if (out.reads != null) {
-    out.reads = [...new Set((Array.isArray(out.reads) ? out.reads : []).filter((r) => DATA_SCOPES.includes(r)))].sort();
-  }
-  for (const field of ['sources', 'surfaces']) {
-    if (out[field] != null) {
-      out[field] = [...new Set((Array.isArray(out[field]) ? out[field] : []).filter(str))];
-    }
-  }
-
-  if (out.files != null) {
-    const files = skillFiles(out);
-    if (Object.keys(files).length) out.files = files;
-    else delete out.files;
-  }
-
-  if (out.version != null && !str(out.version)) delete out.version;
-
-  return out;
-}
+import{DATA_SCOPES as a}from"./scopes.js";class o extends Error{constructor(t,r){super(r),this.name="SkillManifestError",this.code=t}}const u=2,S=Object.freeze(["auto","page","selection","tabs","none"]),l=Object.freeze(["none","chats","meetings","all"]),d=Object.freeze(["none","selected","default"]),I=Object.freeze(["built-in","user","community"]),m=Object.freeze(["references","scripts","assets","templates","examples"]),s=e=>typeof e=="string"&&e.length>0,h=/^[a-z0-9][a-z0-9_-]*$/;function w(e){return!(!s(e)||e.length>255||e!==e.trim()||e.includes("\\")||/[\u0000-\u001f\u007f]/.test(e)||e.startsWith("/")||/^[a-z]:/i.test(e)||e.split("/").some(r=>r===""||r==="."||r===".."))}function f(e){const t=e?.origin;return t&&typeof t=="object"&&s(t.source)&&s(t.id)?t:null}function y(e){return f(e)?"community":e?.builtin?"built-in":"user"}function p(e){const t=e?.files,r={};if(!t||typeof t!="object")return r;for(const i of m){const n=Array.isArray(t[i])?t[i].filter(w):[];n.length&&(r[i]=[...new Set(n)])}return r}function g(e){return(p(e).scripts||[]).length>0}function E(e={}){const t=p(e),r=d.includes(e.mcpMode)?e.mcpMode:"none",i=S.includes(e.context)?e.context:"auto",n=l.includes(e.historyContext)?e.historyContext:"none",c=new Set(Array.isArray(e.reads)?e.reads.filter(b=>a.includes(b)):[]);return i!=="none"&&c.add("page"),(n==="chats"||n==="all")&&c.add("chats"),(n==="meetings"||n==="all")&&c.add("meetings"),{trust:y(e),reads:[...c].sort(),page:i,history:n,mcp:r,mcpServerIds:r==="selected"&&Array.isArray(e.mcpServerIds)?[...e.mcpServerIds]:[],sources:Array.isArray(e.sources)?[...new Set(e.sources.filter(s))].sort():[],surfaces:Array.isArray(e.surfaces)?[...new Set(e.surfaces.filter(s))].sort():[],scripts:t.scripts||[],needsBridge:g(e),meeting:!!e.meeting}}function v(e){const t=f(e);return t?t.id.length>48?`${t.source} · …${t.id.slice(-40)}`:`${t.source} · ${t.id}`:y(e)==="built-in"?"Built-in":"Written here"}function O(e,t){const r=f(e),i=f(t);return!!r&&!!i&&r.source===i.source&&r.id===i.id}function j(e,t){const r=f(e);return!r||!s(r.hash)||!s(t)?null:r.hash!==t}function P(e){if(!e||typeof e!="object")throw new o("SHAPE","skill must be an object");if(!s(e.id))throw new o("SHAPE","skill.id required");if(!s(e.name))throw new o("SHAPE",`skill '${e.id}': name required`);if(e.prompt!=null&&typeof e.prompt!="string")throw new o("SHAPE",`skill '${e.id}': prompt must be a string`);if(e.command!=null&&e.command!==""&&!h.test(String(e.command)))throw new o("SHAPE",`skill '${e.id}': command must match ${h}`);for(const[t,r]of[["context",S],["historyContext",l],["mcpMode",d]])if(e[t]!=null&&!r.includes(e[t]))throw new o("SHAPE",`skill '${e.id}': ${t} must be one of ${r}`);if(e.reads!=null&&(!Array.isArray(e.reads)||!e.reads.every(t=>a.includes(t))))throw new o("SHAPE",`skill '${e.id}': reads must be within ${a}`);for(const t of["sources","surfaces"])if(e[t]!=null&&(!Array.isArray(e[t])||!e[t].every(s)))throw new o("SHAPE",`skill '${e.id}': ${t} must be an array of ids`);if(e.origin!=null){const t=e.origin;if(typeof t!="object")throw new o("SHAPE",`skill '${e.id}': origin must be an object`);if(!s(t.source)||!s(t.id))throw new o("ORIGIN",`skill '${e.id}': origin needs both source and id`)}if(e.files!=null){if(typeof e.files!="object")throw new o("SHAPE",`skill '${e.id}': files must be an object`);for(const t of Object.keys(e.files)){if(!m.includes(t))throw new o("FILES",`skill '${e.id}': unknown file kind '${t}'`);const r=e.files[t];if(!Array.isArray(r)||!r.every(s))throw new o("FILES",`skill '${e.id}': files.${t} must be an array of paths`);const i=r.find(n=>!w(n));if(i)throw new o("PATH",`skill '${e.id}': unsafe path in files.${t}: ${JSON.stringify(i)}`)}}if(!f(e)&&(e.files?.scripts||[]).length)throw new o("ORIGIN",`skill '${e.id}': scripts require an origin to be scannable`);return e}const x=Object.freeze({1:e=>({...e,v:u})});function A(e){if(!e||typeof e!="object")throw new o("SHAPE","skill must be an object");let t=typeof e.v=="number"?e:{...e,v:1},r=0;for(;t.v<u;){const i=x[t.v];if(!i)throw new o("UPCAST",`no upcaster from v${t.v}`);if(t=i(t),++r>64)throw new o("UPCAST","upcaster chain did not terminate")}if(t.v>u)throw new o("UPCAST",`skill is v${t.v}; this reader only knows v${u}`);return t}function L(e){return(Array.isArray(e)?e:[]).map(A)}function M(e){if(!e||typeof e!="object")return e;const t={...A(e)};t.enabled=t.enabled!==!1;const r=String(t.mcpMode||"none").toLowerCase();t.mcpMode=d.includes(r)?r:"none";const i=Array.isArray(t.mcpServerIds)?t.mcpServerIds:[];t.mcpServerIds=t.mcpMode==="selected"?[...new Set(i.map(c=>String(c||"").trim()).filter(Boolean))]:[],delete t.trust;const n=f(t);n?(t.builtin=!1,t.origin={source:n.source,id:n.id,...s(n.url)?{url:n.url}:{},...s(n.hash)?{hash:n.hash}:{},...n.scanned&&typeof n.scanned=="object"?{scanned:{...n.scanned}}:{}}):t.origin!=null&&delete t.origin,t.reads!=null&&(t.reads=[...new Set((Array.isArray(t.reads)?t.reads:[]).filter(c=>a.includes(c)))].sort());for(const c of["sources","surfaces"])t[c]!=null&&(t[c]=[...new Set((Array.isArray(t[c])?t[c]:[]).filter(s))]);if(t.files!=null){const c=p(t);Object.keys(c).length?t.files=c:delete t.files}return t.version!=null&&!s(t.version)&&delete t.version,t}export{S as SKILL_CONTEXTS,m as SKILL_FILE_KINDS,l as SKILL_HISTORY_SCOPES,u as SKILL_MANIFEST_VERSION,d as SKILL_MCP_MODES,I as SKILL_TRUST,x as SKILL_UPCASTERS,o as SkillManifestError,E as declaredAccess,w as isSafeSkillPath,g as needsBridge,M as normalizeSkill,v as originLabel,f as originOf,O as sameSkillOrigin,p as skillFiles,j as skillIsStale,y as trustOf,A as upcastSkill,L as upcastSkills,P as validateSkill};

package/skill-scan.js

@@ -1,210 +1,4 @@
-// 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.
+class A extends Error{constructor(t,o){super(o),this.name="SkillScanError",this.code=t}}const g=1,_=Object.freeze(["clean","suspicious","dangerous"]),f={clean:0,suspicious:1,dangerous:2},p=/[​-‏‪-‮⁠-⁤⁦-⁩\u{e0000}-\u{e007f}]/u,y=[/\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],v=[/\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],w=[/~\/\.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],E=[/\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],S=[{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"}],x=[{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"}],k=(s,t)=>s.slice(0,t).split(`
+`).length,N=(s,t,o=90)=>s.slice(Math.max(0,t-10),t+o).replace(/\s+/g," ").trim();function c(s,t){const o=t.exec(s);return o?{index:o.index,match:o[0]}:null}function C({name:s="",prompt:t="",files:o=[],extra:u=""}={}){const i=[String(t||""),String(u||"")].filter(Boolean).join(`
 
-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;
-}
+`),b=[],a=(e,r,n,m)=>{b.push({rule:e,severity:r,why:m,line:n?k(i,n.index):0,excerpt:n?N(i,n.index):""})};p.test(i)&&a("hidden-text","dangerous",c(i,p),"contains characters that are invisible to a reader but not to the model");for(const e of y){const r=c(i,e);if(r){a("instruction-override","dangerous",r,"tries to override the instructions it is running under");break}}for(const e of v){const r=c(i,e);if(r){a("concealment","suspicious",r,"asks the model to keep something from the user");break}}const d=w.map(e=>c(i,e)).find(Boolean),h=E.map(e=>c(i,e)).find(Boolean);d&&h?a("credential-exfiltration","dangerous",d,`names a credential (${d.match.trim().slice(0,40)}) alongside a command that sends data off the machine`):d?a("credential-mention","suspicious",d,"refers to a credential file or secret variable"):h&&a("outbound-data","suspicious",h,"sends data to a remote host");for(const{re:e,why:r}of S){const n=c(i,e);n&&a("destructive-command","dangerous",n,r)}for(const{re:e,why:r}of x){const n=c(i,e);n&&a("suspicious-pattern","suspicious",n,r)}const l=(Array.isArray(o)?o:[]).filter(e=>String(e).startsWith("scripts/"));return l.length&&b.push({rule:"ships-executable",severity:"suspicious",why:`ships ${l.length} executable file${l.length===1?"":"s"} (${l.join(", ")}) — these run on your machine, not in the browser`,line:0,excerpt:""}),{verdict:b.reduce((e,r)=>f[r.severity]>f[e]?r.severity:e,"clean"),findings:b,scanner:g,name:String(s||"")}}function I(s){return s!=="dangerous"}function R(s){if(!s||s.verdict==="clean")return"";const t=(s.findings||[]).filter(i=>i.severity===s.verdict),o=t[0],u=t.length>1?` (+${t.length-1} more)`:"";return o?`${o.why}${u}`:s.verdict}export{g as SCANNER_VERSION,_ as SCAN_VERDICTS,A as SkillScanError,I as admits,C as scanSkill,R as scanSummary};