ispyx 0.0.0-stage → 1.0.0

package/src/core/motion.js

@@ -0,0 +1,57 @@
+// Human-like pointer paths: a curved cubic Bezier with a smooth (minimum-jerk) speed profile.
+const lerp = (a, b, t) => a + (b - a) * t;
+const between = (rand, lo, hi) => lo + (hi - lo) * rand();
+
+/** Slow start, fast middle, slow arrival. t in 0..1 -> progress in 0..1. */
+export const ease = (t) => t * t * t * (10 + t * (-15 + 6 * t));
+
+/** Returns point(t) for a gently curved path from `from` to `to`. The bend side and size are random. */
+export function curvedPath(from, to, rand = Math.random) {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const dist = Math.hypot(dx, dy);
+  if (dist < 1) return () => ({ x: to.x, y: to.y });
+  const nx = -dy / dist; // unit normal
+  const ny = dx / dist;
+  const side = rand() < 0.5 ? -1 : 1;
+  const bend1 = side * dist * between(rand, 0.08, 0.22);
+  const bend2 = side * dist * between(rand, 0.0, 0.14);
+  const c1 = { x: from.x + dx * 0.3 + nx * bend1, y: from.y + dy * 0.3 + ny * bend1 };
+  const c2 = { x: from.x + dx * 0.72 + nx * bend2, y: from.y + dy * 0.72 + ny * bend2 };
+  return (t) => {
+    const u = 1 - t;
+    const a = u * u * u, b = 3 * u * u * t, c = 3 * u * t * t, d = t * t * t;
+    return {
+      x: a * from.x + b * c1.x + c * c2.x + d * to.x,
+      y: a * from.y + b * c1.y + c * c2.y + d * to.y,
+    };
+  };
+}
+
+/** Random travel time in milliseconds, 300..1000 by default. */
+export const randomDuration = (min = 300, max = 1000, rand = Math.random) => Math.round(between(rand, min, max));
+
+/**
+ * Per-character pauses (ms) for human-paced typing: random between min and max, a little longer after
+ * spaces and punctuation, now and then a short "thinking" pause. If the total would exceed capMs the
+ * pauses are scaled down so long texts still finish (use the clipboard for really long text).
+ */
+export const MIN_TYPE_WAIT_MS = 8; // apps drop or repeat characters when they arrive faster than this
+
+/**
+ * Pause (ms) after each character. `speed` divides every wait (2 = twice as fast, 0.5 = twice as slow);
+ * 0 = a fixed minimum wait after every character. The cap applies after speed; no wait is ever under 8 ms.
+ */
+export function typingDelays(text, { min = 60, max = 200, capMs = 60000, speed = 1 } = {}, rand = Math.random) {
+  const chars = [...text];
+  if (!(speed > 0)) return chars.map(() => MIN_TYPE_WAIT_MS);
+  const d = chars.map((ch, i) => {
+    let ms = between(rand, min, max);
+    if (/[\s.,;:!?]/.test(ch)) ms *= between(rand, 1.2, 1.8);
+    if (i > 0 && rand() < 0.03) ms += between(rand, 250, 600);
+    return ms / speed;
+  });
+  const total = d.reduce((a, b) => a + b, 0);
+  const k = total > capMs ? capMs / total : 1;
+  return d.map((ms) => Math.max(MIN_TYPE_WAIT_MS, Math.round(ms * k)));
+}

package/src/core/panel/README.md

@@ -0,0 +1,70 @@
+# Panel
+
+The Ispyx window: one page, `page.html`, used on both platforms.
+
+- Windows: served on loopback by `index.js` and shown in an Edge `--app` window.
+- macOS: loaded in a WKWebView by the app, no server.
+
+The page is a single self-contained file (inline CSS and JS, no CDN, no external hosts, only relative URLs). It follows the macOS status window: icon, headline, light/dark, green accent, about 480px wide.
+
+## Host contract
+
+The page talks to its host only through:
+
+```js
+window.ispyx = {
+  getState(): Promise<State>,
+  action(name: string, value?: any): Promise<any>,
+}
+```
+
+If `window.ispyx` is undefined when the page script runs, the page installs a fetch-based one: `getState` is `GET api/state`, `action` is `POST api/action` with `{name, value}` (relative URLs). macOS injects its own `window.ispyx` before the page script runs. The page polls `getState()` every second (the Windows server closes itself when polling stops).
+
+Icon: `<img src="icon.png">` and `<link rel="icon" href="icon.png">`, relative. The Windows server serves `/icon.png`; the macOS host must resolve `icon.png` next to the page.
+
+### State
+
+Only `version` and `platform` are required. Every other key is optional and the page hides the section whose data is absent.
+
+```
+{ version, platform: 'win32' | 'darwin', pid, uptimeMs, clients,
+  recent: [{ time, tool, summary }],          // time = epoch ms
+  stopLabel,                                  // e.g. "Esc x3" or "⌥ Option + Esc"
+  effectsEnabled, passwordSet, denylist: [],
+  autostart: boolean, autostartLabel?,        // label defaults by platform
+  permissions: [{ id: 'accessibility' | 'screen-recording', title, detail, granted }],
+  connect: { claudeCodeCommand, desktopConfigJson, desktopConfigPath } }
+```
+
+Sections, top to bottom: header (icon, headline, status, version/uptime/pid), Permissions (`permissions`), Connect to your AI app (`connect`; "Show Config File" only with `desktopConfigPath`), usage note (uses `stopLabel`), General (`autostart`, `effectsEnabled`), Activity (`clients`, `recent`), Safety (`passwordSet`, `denylist`), footer button: Quit on `win32`, Close on `darwin`. The headline reads "Ispyx needs your permission" while any permission is not granted.
+
+### Actions
+
+| name | value | notes |
+|---|---|---|
+| `quit` | none | Windows footer button (after a confirm) |
+| `close` | none | macOS footer button; closes the window. The Windows server accepts and ignores it |
+| `setAutostart` | boolean | |
+| `setEffects` | boolean | |
+| `openLog` | none | Windows footer link |
+| `requestPermission` | permission id | "Allow" |
+| `openPermissionSettings` | permission id | "Open Settings" |
+| `showConfigFile` | none | reveal `desktopConfigPath` (or its folder) |
+| `copy` | text | clipboard fallback; the page tries `navigator.clipboard` first |
+
+## Windows server (`index.js`)
+
+```js
+import { startPanel } from './panel/index.js';
+const panel = await startPanel({ getState, actions }); // { url, token, port, close() }
+```
+
+- `actions` is the host's object. The whitelist above is explicit; a name is callable only if `actions` defines it (except `close`, which is a no-op). `copy`, `requestPermission`, `openPermissionSettings` need a string value (permission ids are checked against `accessibility` / `screen-recording`).
+- `resident.js` `getState()` adds `connect` on Windows (`claude mcp add ispyx --scope user -- ispyx mcp`, the `mcpServers` JSON, `%APPDATA%\Claude\claude_desktop_config.json`); its `showConfigFile` opens Explorer on the file or its folder.
+- Any `password`/`passwordHash` field in state is stripped.
+
+Security: bound to 127.0.0.1 on a random port; random 128-bit token. `panel.url` carries `?t=<token>` once; the server answers with an HttpOnly, SameSite=Strict cookie and redirects to `/`. Every request needs that cookie and a Host of `127.0.0.1:<port>` or `localhost:<port>` (DNS-rebinding guard). POSTs additionally need a same-origin `Origin` and `application/json`. No CORS headers, `Cache-Control: no-store`, CSP `default-src 'self'`. Only `page.html` and the icon are served, so no path traversal.
+
+Endpoints: `GET /`, `GET /icon.png`, `GET /api/state`, `POST /api/action {name, value}`.
+
+Test: `npm run panel-test`.

package/src/core/panel/index.js

@@ -0,0 +1,144 @@
+// Local "Open" panel: a tiny loopback-only HTTP server serving one page that shows
+// resident status and flips a few settings. Zero deps (node:http).
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const PAGE = fileURLToPath(new URL('./page.html', import.meta.url));
+const COOKIE = 'ispyx_panel';
+// Explicit whitelist; an action is also callable only if the host's `actions` object defines it.
+const ACTIONS = ['quit', 'setAutostart', 'setEffects', 'openLog', 'copy', 'close', 'requestPermission', 'openPermissionSettings', 'showConfigFile', 'clearRecent', 'addDeny', 'removeDeny', 'setPassword', 'setAuthRequired'];
+const BOOL_ACTIONS = new Set(['setAutostart', 'setEffects']);
+const STRING_ACTIONS = new Set(['copy', 'requestPermission', 'openPermissionSettings', 'addDeny']); // value must be a short string
+// value is an object of short strings (and a boolean for setAuthRequired.on)
+const OBJECT_ACTIONS = { setPassword: ['current', 'next'], setAuthRequired: ['current'], removeDeny: ['name', 'current'] };
+const objectOk = (name, v) => {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return false;
+  if (name === 'setAuthRequired' && typeof v.on !== 'boolean') return false;
+  return OBJECT_ACTIONS[name].every((k) => v[k] === undefined || (typeof v[k] === 'string' && v[k].length <= 200));
+};
+const PERMISSION_IDS = new Set(['accessibility', 'screen-recording']);
+
+function safeEq(a, b) {
+  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+}
+
+function parseCookies(h) {
+  const out = {};
+  for (const part of String(h || '').split(';')) {
+    const i = part.indexOf('=');
+    if (i > 0) out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+  }
+  return out;
+}
+
+export async function startPanel({ getState, actions, port = 0 }) {
+  const token = crypto.randomBytes(16).toString('hex'); // 128 bit
+  let boundPort = 0;
+  const hostOk = (h) => h === `127.0.0.1:${boundPort}` || h === `localhost:${boundPort}`;
+  const authed = (req, url) => {
+    if (safeEq(parseCookies(req.headers.cookie)[COOKIE] || '', token)) return true;
+    return false;
+  };
+
+  const send = (res, code, body, type = 'application/json; charset=utf-8', extra = {}) => {
+    res.writeHead(code, {
+      'Content-Type': type,
+      'Cache-Control': 'no-store',
+      'Content-Security-Policy': "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'",
+      'X-Content-Type-Options': 'nosniff',
+      'Referrer-Policy': 'no-referrer',
+      ...extra,
+    });
+    res.end(typeof body === 'string' || Buffer.isBuffer(body) ? body : JSON.stringify(body));
+  };
+  const deny = (res, code = 403, msg = 'forbidden') => send(res, code, { error: msg });
+
+  const readJson = (req) => new Promise((resolve, reject) => {
+    let size = 0; const chunks = [];
+    req.on('data', (c) => { size += c.length; if (size > 4096) { reject(new Error('too large')); req.destroy(); } else chunks.push(c); });
+    req.on('end', () => { try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || 'null')); } catch (e) { reject(e); } });
+    req.on('error', reject);
+  });
+
+  let iconPng = null;
+  const server = http.createServer(async (req, res) => {
+    try {
+      if (!hostOk(req.headers.host)) return deny(res);
+      const url = new URL(req.url, `http://127.0.0.1:${boundPort}`);
+
+      // First load: ?t=<token> sets the cookie, then redirects to a clean URL.
+      if (req.method === 'GET' && url.pathname === '/' && url.searchParams.has('t')) {
+        if (!safeEq(url.searchParams.get('t'), token)) return deny(res);
+        return send(res, 302, '', 'text/plain', {
+          Location: '/',
+          'Set-Cookie': `${COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`,
+        });
+      }
+      if (!authed(req, url)) return deny(res);
+
+      if (req.method === 'GET' && url.pathname === '/') {
+        return send(res, 200, await readFile(PAGE), 'text/html; charset=utf-8');
+      }
+      if (req.method === 'GET' && url.pathname === '/icon.png') { // the app icon, same as the tray and the macOS app
+        iconPng ??= (async () => {
+          const [{ renderIcon }, { encodePng }] = await Promise.all([import('../../effects/appicon.js'), import('../image.js')]);
+          return encodePng(renderIcon(128, { tight: true }), 128, 128);
+        })();
+        return send(res, 200, await iconPng, 'image/png');
+      }
+      if (req.method === 'GET' && url.pathname === '/api/state') {
+        const s = { ...(await getState()) };
+        delete s.password; delete s.passwordHash; // never expose
+        s.passwordSet = !!s.passwordSet;
+        return send(res, 200, s);
+      }
+      if (req.method === 'POST' && url.pathname === '/api/action') {
+        if (req.headers.origin !== `http://${req.headers.host}`) return deny(res);
+        if (!/^application\/json\b/i.test(req.headers['content-type'] || '')) return deny(res, 415, 'json only');
+        let body;
+        try { body = await readJson(req); } catch { return deny(res, 400, 'bad json'); }
+        const name = body && body.name;
+        if (typeof name !== 'string' || !ACTIONS.includes(name) || (name !== 'close' && typeof actions?.[name] !== 'function')) {
+          return deny(res, 400, 'unknown action');
+        }
+        if (BOOL_ACTIONS.has(name) && typeof body.value !== 'boolean') return deny(res, 400, 'boolean value required');
+        if (STRING_ACTIONS.has(name) && (typeof body.value !== 'string' || body.value.length > 3000)) return deny(res, 400, 'string value required');
+        if (OBJECT_ACTIONS[name] && !objectOk(name, body.value)) return deny(res, 400, 'bad value');
+        if ((name === 'requestPermission' || name === 'openPermissionSettings') && !PERMISSION_IDS.has(body.value)) return deny(res, 400, 'unknown permission');
+        if (name === 'close') return send(res, 200, { ok: true }); // macOS-only; nothing to close here
+        // Reply first for quit, since it may tear this server down.
+        if (name === 'quit') {
+          send(res, 200, { ok: true });
+          setTimeout(() => { Promise.resolve().then(() => actions.quit()).catch(() => {}); }, 50);
+          return;
+        }
+        await actions[name](BOOL_ACTIONS.has(name) || STRING_ACTIONS.has(name) || OBJECT_ACTIONS[name] ? body.value : undefined);
+        return send(res, 200, { ok: true });
+      }
+      return deny(res, 404, 'not found');
+    } catch (e) {
+      if (!res.headersSent && e && e.expose) send(res, 400, { error: String(e.message).slice(0, 200) }); // a refusal meant for the person at the panel
+      else if (!res.headersSent) send(res, 500, { error: 'internal error' });
+      else res.end();
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', resolve);
+  });
+  boundPort = server.address().port;
+
+  return {
+    url: `http://127.0.0.1:${boundPort}/?t=${token}`,
+    token,
+    port: boundPort,
+    close: () => new Promise((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections?.();
+    }),
+  };
+}