@atlassian/chippy 0.0.0-stage → 0.0.1-beta.2

package/lib/mcp-skill/scripts/format-probe-result.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/* eslint-disable */
+
+const mode = process.argv[2] || 'text';
+let input = '';
+
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+
+process.stdin.on('end', () => {
+  const payload = JSON.parse(input);
+  if (mode === 'json') {
+    process.stdout.write(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (!payload?.ok || !payload?.result?.ok) {
+    process.stdout.write(JSON.stringify(payload, null, 2));
+    return;
+  }
+  const result = payload.result;
+  const text = String(result.text || '');
+  if (mode === 'complexity') {
+    const lines = text.split('\n');
+    const start = lines.indexOf('complexity:');
+    const end = lines.indexOf('structure:');
+    if (start >= 0) {
+      const until = end > start ? end : lines.length;
+      process.stdout.write(lines.slice(start, until).join('\n'));
+      return;
+    }
+  }
+  process.stdout.write(text || JSON.stringify(payload, null, 2));
+});

package/lib/mcp-skill/scripts/helper-access.js

@@ -0,0 +1,158 @@
+/* eslint-disable */
+// Access control for the Chippy helper.
+//
+// The helper can run scripts in connected pages, so its command API must not
+// be reachable from arbitrary websites or other hosts. Three checks apply:
+//   1. The helper binds to loopback by default. A wider bind (for example
+//      0.0.0.0 for a remote dev environment or container) is opt-in.
+//   2. When bound to loopback, the Host header must name a loopback host. This
+//      blocks DNS-rebinding pages that resolve their own name to 127.0.0.1.
+//   3. Protected routes require the X-Chippy-Token header. CORS does not allow
+//      that header, so a cross-origin page cannot send it.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const TOKEN_HEADER = 'x-chippy-token';
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+
+// Routes that pages load without credentials: health, injected bundles, and
+// the page WebSocket.
+const PUBLIC_GET_PATHS = new Set([
+  '',
+  '/health',
+  '/inject.js',
+  '/inject.mjs',
+  '/avalanche.es.js',
+  '/avalanche.iife.js',
+  '/avalanche.es.js.map',
+  '/avalanche.iife.js.map',
+  '/devtools-hook-shim.js',
+  '/startup-handoff.js',
+  '/ws',
+]);
+
+// Routes the published browser extension calls from its service worker. The
+// extension sends no token, so these stay open to extension origins and
+// non-browser clients on every bind. They list pages and read or arm capture;
+// they do not run page code.
+const EXTENSION_ROUTES = new Set(['GET /api/pages', 'GET /api/avalanche-arm', 'POST /api/avalanche-arm']);
+
+function stateDirectory(env = process.env) {
+  return env.CHIPPY_STATE_DIR || path.join(os.homedir(), '.chippy');
+}
+
+function resolveTokenFile(port, env = process.env) {
+  return path.join(stateDirectory(env), `helper-${port}.token`);
+}
+
+function readHelperToken(port, env = process.env) {
+  if (env.CHIPPY_HELPER_TOKEN) return env.CHIPPY_HELPER_TOKEN;
+  try {
+    return fs.readFileSync(resolveTokenFile(port, env), 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function createHelperToken(env = process.env) {
+  return env.CHIPPY_HELPER_TOKEN || crypto.randomBytes(32).toString('hex');
+}
+
+// Call only after the server is listening, so a helper that lost the port
+// race cannot replace the running helper's token.
+function writeHelperToken(port, token, env = process.env) {
+  if (env.CHIPPY_HELPER_TOKEN) return null;
+  const file = resolveTokenFile(port, env);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, `${token}\n`, { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+  return file;
+}
+
+function isLoopbackBind(host) {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+
+function hostnameOf(hostHeader) {
+  if (!hostHeader) return '';
+  const value = String(hostHeader).toLowerCase();
+  if (value.startsWith('[')) return value.slice(0, value.indexOf(']') + 1);
+  return value.split(':')[0];
+}
+
+function allowedHosts(env = process.env) {
+  const extra = (env.CHIPPY_HELPER_ALLOWED_HOSTS || '')
+    .split(',')
+    .map((h) => h.trim().toLowerCase())
+    .filter(Boolean);
+  return new Set([...LOOPBACK_HOSTS, ...extra]);
+}
+
+function isAllowedHost(hostHeader, env = process.env) {
+  return allowedHosts(env).has(hostnameOf(hostHeader));
+}
+
+// Returns 'public', 'extension', or 'protected'. `route` is the path after the
+// Chippy prefix, or null for proxied application paths.
+function classifyRoute(method, route) {
+  if (route === null) return 'public';
+  if (method === 'OPTIONS') return 'public';
+  if (method === 'GET' && PUBLIC_GET_PATHS.has(route)) return 'public';
+  if (EXTENSION_ROUTES.has(`${method} ${route}`)) return 'extension';
+  return 'protected';
+}
+
+function isExtensionOrigin(origin) {
+  return typeof origin === 'string' && /^(chrome|moz)-extension:\/\//.test(origin);
+}
+
+function originOf(value) {
+  try { return new URL(value).origin; } catch { return null; }
+}
+
+// A page may ask whether its own origin is armed (the Storybook addon does this
+// at preview start). It may not list other origins or look up client ids.
+function isSelfArmLookup(method, route, origin, query) {
+  if (method !== 'GET' || route !== '/api/avalanche-arm' || !query || typeof origin !== 'string') return false;
+  if (query.get('clientId')) return false;
+  const asked = query.get('origin');
+  return !!asked && originOf(asked) === origin;
+}
+
+function tokensMatch(expected, received) {
+  if (typeof received !== 'string' || !expected) return false;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(received);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+// Returns null when the request may proceed, otherwise { status, error }.
+// `query` is the request's URLSearchParams.
+function authorizeRequest({ method, route, headers, token, loopback, query = null, env = process.env }) {
+  if (loopback && !isAllowedHost(headers.host, env)) {
+    return { status: 403, error: 'Host header is not a loopback host; set CHIPPY_HELPER_ALLOWED_HOSTS to allow it' };
+  }
+  const kind = classifyRoute(method, route);
+  if (kind === 'public') return null;
+  if (tokensMatch(token, headers[TOKEN_HEADER])) return null;
+  if (kind === 'extension') {
+    const origin = headers.origin;
+    if (origin === undefined || isExtensionOrigin(origin)) return null;
+    if (isSelfArmLookup(method, route, origin, query)) return null;
+  }
+  return { status: 401, error: 'Missing or invalid X-Chippy-Token header' };
+}
+
+module.exports = {
+  TOKEN_HEADER,
+  authorizeRequest,
+  classifyRoute,
+  createHelperToken,
+  isAllowedHost,
+  isLoopbackBind,
+  readHelperToken,
+  resolveTokenFile,
+  writeHelperToken,
+};

package/lib/mcp-skill/scripts/helper-proxy.js

@@ -0,0 +1,87 @@
+/* eslint-disable */
+// Pure helpers for the helper's proxy mode: where to forward requests, and how
+// to put Chippy into the proxied HTML document.
+
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+
+function isLoopbackHostname(hostname) {
+  const name = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  return LOOPBACK_HOSTNAMES.has(name) || /^127(?:\.\d{1,3}){3}$/.test(name) || name.endsWith('.localhost');
+}
+
+// The proxy forwards only to this machine. Dev servers bind `localhost`,
+// `127.0.0.1`, or `::1` depending on the tool and platform (Vite on macOS binds
+// `::1`), so the original page URL decides the loopback name when it names one.
+// `localhost` is the default because it resolves to both address families.
+function resolveProxyTarget(targetPort, originalUrl) {
+  const port = Number(targetPort);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`Invalid target port: ${targetPort}`);
+  let hostname = 'localhost';
+  if (originalUrl) {
+    let parsed;
+    try { parsed = new URL(String(originalUrl)); } catch { throw new Error(`Invalid originalUrl: ${originalUrl}`); }
+    const named = parsed.hostname.replace(/^\[|\]$/g, '');
+    if (!isLoopbackHostname(named)) {
+      throw new Error(`Proxy targets must be on this machine; originalUrl host ${parsed.hostname} is not a loopback name`);
+    }
+    hostname = named;
+  }
+  const hostHeader = `${hostname.includes(':') ? `[${hostname}]` : hostname}:${port}`;
+  return { hostname, port, hostHeader };
+}
+
+// Options for http.request. `autoSelectFamily` tries every address `localhost`
+// resolves to, so a server listening on only one family is still reached.
+function upstreamRequestOptions(target, req, headers) {
+  return {
+    host: target.hostname,
+    port: target.port,
+    path: req.url,
+    method: req.method,
+    headers,
+    autoSelectFamily: true,
+  };
+}
+
+const HEAD_OPEN = /<head(?:\s[^>]*)?>/i;
+const HTML_OPEN = /<html(?:\s[^>]*)?>/i;
+const DOCTYPE = /^\s*<!doctype[^>]*>/i;
+
+// Classic scripts at the start of <head> run before the document's module
+// scripts, so the DevTools hook exists when react-dom evaluates.
+function insertAtHeadStart(html, markup) {
+  for (const pattern of [HEAD_OPEN, HTML_OPEN, DOCTYPE]) {
+    const match = pattern.exec(html);
+    if (match) {
+      const at = match.index + match[0].length;
+      return `${html.slice(0, at)}\n${markup}\n${html.slice(at)}`;
+    }
+  }
+  return `${markup}\n${html}`;
+}
+
+function insertAtBodyEnd(html, markup) {
+  const lower = html.toLowerCase();
+  for (const tag of ['</body>', '</html>']) {
+    const i = lower.lastIndexOf(tag);
+    if (i >= 0) return `${html.slice(0, i)}${markup}\n${html.slice(i)}`;
+  }
+  return `${html}\n${markup}`;
+}
+
+// `earlyScripts` are helper-relative script paths that must run before page
+// code; `bridgeBundle` is inline markup that connects the page to the helper.
+function injectProxyDocument(html, { earlyScripts = [], bridgeBundle = '' } = {}) {
+  const early = earlyScripts
+    .map((src) => `<script data-chippy-proxy-early="true" src="${src}"></script>`)
+    .join('\n');
+  const withEarly = early ? insertAtHeadStart(html, early) : html;
+  return bridgeBundle ? insertAtBodyEnd(withEarly, bridgeBundle) : withEarly;
+}
+
+module.exports = {
+  injectProxyDocument,
+  isLoopbackHostname,
+  resolveProxyTarget,
+  upstreamRequestOptions,
+};

package/lib/mcp-skill/scripts/page-socket-trust.js

@@ -0,0 +1,81 @@
+/* eslint-disable */
+// Page WebSocket identity checks for the Chippy helper.
+//
+// Any page in the browser can open the page WebSocket, because the pages
+// Chippy inspects run on arbitrary origins. What a page cannot forge is the
+// Origin header its browser sends with the WebSocket handshake. These checks
+// bind a socket's claims to that origin:
+//   1. The page URL a socket reports must belong to its handshake origin, so a
+//      page cannot appear to the agent as another site.
+//   2. A client id belongs to the origin that first claimed it. A reload of the
+//      same page may reuse its id; a page on another origin may not take it
+//      over, even after the original socket closed.
+// A socket without an Origin header is a non-browser client on this machine;
+// such a client can already read the helper token, so its origin is `null`
+// and it is held to the same id binding as any other origin.
+
+const MAX_BOUND_CLIENT_IDS = 2000;
+
+function handshakeOrigin(headers) {
+  const origin = headers && headers.origin;
+  return typeof origin === 'string' && origin ? origin : null;
+}
+
+function urlOrigin(value) {
+  try { return new URL(value).origin; } catch { return null; }
+}
+
+// Returns null when the page URL is consistent with the socket, otherwise an error.
+function checkPageUrl(socketOrigin, pageUrl) {
+  if (socketOrigin === null || pageUrl == null || pageUrl === '') return null;
+  const claimed = urlOrigin(String(pageUrl));
+  if (claimed === socketOrigin) return null;
+  return `page URL ${JSON.stringify(String(pageUrl))} does not belong to the WebSocket origin ${socketOrigin}`;
+}
+
+function pageUrlsOf(msg) {
+  const urls = [];
+  if (msg && msg.page && msg.page.url != null) urls.push(msg.page.url);
+  if (msg && msg.snapshot && msg.snapshot.page && msg.snapshot.page.url != null) urls.push(msg.snapshot.page.url);
+  return urls;
+}
+
+function createClientIdBindings({ max = MAX_BOUND_CLIENT_IDS } = {}) {
+  const owners = new Map();
+
+  function bind(clientId, origin) {
+    owners.delete(clientId);
+    owners.set(clientId, origin);
+    while (owners.size > max) owners.delete(owners.keys().next().value);
+  }
+
+  // Returns null and records the binding when `origin` may use `clientId`.
+  function claim(clientId, origin) {
+    if (owners.has(clientId) && owners.get(clientId) !== origin) {
+      return `client id ${JSON.stringify(clientId)} belongs to another origin`;
+    }
+    bind(clientId, origin);
+    return null;
+  }
+
+  return { claim, ownerOf: (clientId) => (owners.has(clientId) ? owners.get(clientId) : undefined) };
+}
+
+// Returns null when `msg` may be applied to a socket from `socketOrigin`
+// currently registered as `currentClientId`, otherwise an error string.
+function checkPageMessage({ bindings, socketOrigin, currentClientId, msg }) {
+  for (const url of pageUrlsOf(msg)) {
+    const error = checkPageUrl(socketOrigin, url);
+    if (error) return error;
+  }
+  const requested = msg && msg.clientId ? String(msg.clientId) : null;
+  if (requested && requested !== currentClientId) return bindings.claim(requested, socketOrigin);
+  return null;
+}
+
+module.exports = {
+  checkPageMessage,
+  checkPageUrl,
+  createClientIdBindings,
+  handshakeOrigin,
+};

package/lib/mcp-skill/scripts/probe-annotation-channel.js

@@ -0,0 +1,116 @@
+/* eslint-disable */
+
+const DIRECT_PROBE_IDS = new Set(['1', '2']);
+
+function normalizedAnnotation(marker) {
+  return {
+    intent: marker?.intent ?? null,
+    comment: typeof marker?.comment === 'string' ? marker.comment : '',
+  };
+}
+
+function annotationChanged(previousMarker, nextMarker) {
+  const previous = normalizedAnnotation(previousMarker);
+  const next = normalizedAnnotation(nextMarker);
+  return previous.intent !== next.intent || previous.comment !== next.comment;
+}
+
+function createProbeAnnotationChannel({ maxEvents = 50, serializeMarker = (marker) => marker } = {}) {
+  const queues = new Map();
+  const waiters = new Map();
+  let sequence = 0;
+
+  function getQueue(clientId) {
+    if (!queues.has(clientId)) queues.set(clientId, []);
+    return queues.get(clientId);
+  }
+
+  function getWaiters(clientId) {
+    if (!waiters.has(clientId)) waiters.set(clientId, []);
+    return waiters.get(clientId);
+  }
+
+  function deliver(clientId, event) {
+    const waiting = getWaiters(clientId);
+    while (waiting.length) {
+      const waiter = waiting.shift();
+      if (waiter.settled) continue;
+      waiter.finish(event);
+      return;
+    }
+    const queue = getQueue(clientId);
+    queue.push(event);
+    while (queue.length > maxEvents) queue.shift();
+  }
+
+  function publish({ clientId, at, page, integration, previousSnapshot, snapshot }) {
+    const previousMarkers = previousSnapshot?.markers || {};
+    const nextMarkers = snapshot?.markers || {};
+    const directIds = Object.keys(nextMarkers).filter((id) => DIRECT_PROBE_IDS.has(id));
+    const changedProbeIds = directIds.filter((id) => annotationChanged(previousMarkers[id], nextMarkers[id]));
+    const annotatedProbeIds = directIds.filter((id) => {
+      const annotation = normalizedAnnotation(nextMarkers[id]);
+      return annotation.intent !== null || annotation.comment.length > 0;
+    });
+    const selectedProbeIds = changedProbeIds.length
+      ? changedProbeIds
+      : (annotatedProbeIds.length ? annotatedProbeIds : directIds);
+
+    const event = {
+      eventId: `probe-annotation:${++sequence}`,
+      sequence,
+      at,
+      clientId,
+      reason: 'marker-annotation-change',
+      page: page || null,
+      integration: integration || null,
+      changedProbeIds,
+      annotations: selectedProbeIds.map((probeId) => ({
+        probeId,
+        ...normalizedAnnotation(nextMarkers[probeId]),
+        marker: serializeMarker(nextMarkers[probeId]),
+      })),
+    };
+    deliver(clientId, event);
+    return event;
+  }
+
+  function wait(clientId, timeoutMs) {
+    const queue = getQueue(clientId);
+    if (queue.length) {
+      return { promise: Promise.resolve(queue.shift()), cancel() {} };
+    }
+
+    let waiter;
+    const promise = new Promise((resolve) => {
+      waiter = {
+        settled: false,
+        timer: null,
+        finish(event) {
+          if (this.settled) return;
+          this.settled = true;
+          clearTimeout(this.timer);
+          const waiting = waiters.get(clientId);
+          const index = waiting?.indexOf(this) ?? -1;
+          if (index >= 0) waiting.splice(index, 1);
+          if (waiting?.length === 0) waiters.delete(clientId);
+          resolve(event);
+        },
+      };
+      waiter.timer = setTimeout(() => waiter.finish(null), timeoutMs);
+      getWaiters(clientId).push(waiter);
+    });
+
+    return {
+      promise,
+      cancel() {
+        if (!waiter || waiter.settled) return;
+        waiter.finish(null);
+      },
+    };
+  }
+
+  return { publish, wait };
+}
+
+module.exports = { createProbeAnnotationChannel };