aionflare-connect 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIONFLARE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# aionflare-connect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local terminal for AIONFLARE Coder ([ADR-0094](../../docs/adr/0094-coder-cloud-terminal.md), amendment of 2026-11-07). It lets Coder's **Local terminal** open shells on your own computer, in a folder you choose, with your own tools, Git keys and internet.
+
+## Use
+
+1. Install [Node.js](https://nodejs.org) (LTS). Windows and macOS use node-pty's ready-made binaries; on Linux, node-pty is built when installed, which needs Python, `make` and a C++ compiler.
+2. In a normal (not Administrator) terminal, go to your project's folder and run:
+
+   ```
+   npx aionflare-connect
+   ```
+
+3. Open the pairing link it prints, in the browser where you use AIONFLARE, within 10 minutes. Your browser may ask whether aionflare.com may connect to devices on your computer: allow it.
+4. In a Coder project, turn on **Terminal** in the Environment panel (under Code). A terminal opens beside the chat; **+** opens another. Browsers paired before reconnect by themselves whenever the helper is running.
+
+Press **Ctrl+C** to stop it and close every shell. `npx aionflare-connect --forget` forgets every paired browser. `--help` lists the options.
+
+## What it can do
+
+- It listens on this computer only (127.0.0.1), never on your network.
+- It accepts a connection only from the AIONFLARE website, naming this computer's address, with a key it gave that browser when you paired it. Keys are kept as their SHA-256 in `~/.aionflare/connect.json`.
+- It opens up to 3 shells (PowerShell on Windows, your login shell elsewhere), starting in the chosen folder.
+- For a Coder project, it can open your computer's own folder dialog so you choose the app's folder (an existing one, or a new one named after the project). It then works in that folder, and remembers the folders you picked; the website can switch it only to one of those.
+- For Coder's **Copy project here** and **Save to project**, it reads and writes text files only inside the chosen folder, never through links, skipping `node_modules`, `.git` and build folders.
+- It does nothing else. It makes no internet connections and sends nothing to AIONFLARE. Its window shows a line when a browser pairs, connects or opens a shell, never what you type.
+
+A shell has your account's own permissions and can go anywhere your account can, as any terminal can. The chosen folder limits only Coder's file actions. Run only commands you trust.
+
+## Develop
+
+Its rules (`lib/core.mjs`) and its WebSocket (`lib/ws.mjs`) are tested by `tests/connect.test.ts` in this repository. `--dev` also accepts a Workspace served from this computer (`npm run workspace`).

package/bin/aionflare-connect.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// ADR-0094 amendment (owner, 2026-11-07): `npx aionflare-connect [folder]` lets Coder's Local
+// terminal open shells on this computer, in this folder. See README.md.
+import { spawnSync } from 'node:child_process';
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import { join, resolve } from 'node:path';
+import { defaultPort, newCode, version } from '../lib/core.mjs';
+import { startServer } from '../lib/server.mjs';
+
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(name);
+const option = (name) => {
+  const at = args.indexOf(name);
+  return at >= 0 ? args[at + 1] : undefined;
+};
+const say = (line = '') => process.stdout.write(line + '\n');
+
+if (flag('--version')) {
+  say(version);
+  process.exit(0);
+}
+if (flag('--help') || flag('-h')) {
+  say(`aionflare-connect ${version}: a local terminal for AIONFLARE Coder.
+
+Usage: npx aionflare-connect [folder] [options]
+
+  folder           The folder your shells start in and Coder may copy files to and from
+                   (the current folder when left out).
+  --forget         Forget every browser paired with this computer, then stop.
+  --port <n>       Listen on this port (default ${defaultPort}).
+  --allow-admin    Run even as Administrator or root (not recommended).
+  --dev            Also accept a Workspace served from this computer (for AIONFLARE's developers).
+
+It listens on this computer only and accepts only the AIONFLARE website. Press Ctrl+C to stop
+it and close every shell.`);
+  process.exit(0);
+}
+
+const configDir = join(homedir(), '.aionflare');
+const configFile = join(configDir, 'connect.json');
+async function loadConfig() {
+  try {
+    const raw = JSON.parse(await readFile(configFile, 'utf8'));
+    return {
+      port: Number(raw.port) || undefined,
+      devices: Array.isArray(raw.devices) ? raw.devices : [],
+      // Owner (2026-11-07): the folders picked for projects in this computer's folder dialog.
+      folders: Array.isArray(raw.folders) ? raw.folders.filter((f) => typeof f === 'string') : [],
+    };
+  } catch {
+    return { devices: [] };
+  }
+}
+async function saveConfig(config) {
+  await mkdir(configDir, { recursive: true });
+  await writeFile(configFile, JSON.stringify(config, null, 2), { encoding: 'utf8', mode: 0o600 });
+  // Readable by this account only (on Windows the user's profile folder already is).
+  await chmod(configFile, 0o600).catch(() => {});
+}
+
+const config = await loadConfig();
+if (flag('--forget')) {
+  config.devices = [];
+  await saveConfig(config);
+  say('Forgot every paired browser. Pair again with npx aionflare-connect.');
+  process.exit(0);
+}
+
+// Shells have this account's permissions, so an Administrator or root account is refused unless
+// asked for.
+const admin =
+  platform() === 'win32'
+    ? spawnSync('net', ['session'], { stdio: 'ignore', windowsHide: true }).status === 0
+    : process.getuid?.() === 0;
+if (admin && !flag('--allow-admin')) {
+  say('This window runs as Administrator (or root). Shells opened from AIONFLARE would have full');
+  say(
+    'control of this computer, so aionflare-connect will not start. Open a normal window and run',
+  );
+  say('it again, or add --allow-admin if you really need it.');
+  process.exit(1);
+}
+
+const folderArg = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--port');
+const folder = resolve(folderArg ?? process.cwd());
+if (!(await stat(folder).catch(() => null))?.isDirectory()) {
+  say('No folder at ' + folder + '.');
+  process.exit(1);
+}
+const dev = flag('--dev');
+const wanted = Number(option('--port')) || config.port || defaultPort;
+const log = (line) => say(new Date().toLocaleTimeString() + '  ' + line);
+
+let helper;
+let port = wanted;
+for (let attempt = 0; attempt < 10; attempt++, port++) {
+  const candidate = startServer({ folder, port, dev, config, saveConfig, log });
+  try {
+    await candidate.listen();
+    helper = candidate;
+    break;
+  } catch (e) {
+    if (e?.code !== 'EADDRINUSE') throw e;
+  }
+}
+if (!helper) {
+  say('Ports ' + wanted + ' to ' + (wanted + 9) + ' are in use. Try --port with another number.');
+  process.exit(1);
+}
+if (config.port !== port) {
+  config.port = port;
+  await saveConfig(config);
+}
+const code = newCode();
+helper.newPairing(code);
+
+say('');
+say('  aionflare-connect ' + version + ' is running for ' + folder);
+say('');
+if (config.devices.length)
+  say('  Browsers paired before reconnect by themselves: open Terminal in Coder.');
+say('  To pair a browser, open this link in it within 10 minutes:');
+say('');
+say('    https://aionflare.com/chat/#connect=' + port + '.' + code);
+if (dev) say('    http://127.0.0.1:4310/#connect=' + port + '.' + code + '   (--dev)');
+say('');
+say('  Only this computer can connect, and only from the AIONFLARE website.');
+say('  Press Ctrl+C to stop and close every shell.');
+say('');
+
+const stop = () => {
+  log('Stopping.');
+  process.exit(0);
+};
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);

package/lib/core.mjs

@@ -0,0 +1,178 @@
+// ADR-0094 amendment (owner, 2026-11-07): aionflare-connect's rules, kept apart from its server so
+// they can be tested on their own: who may connect, the pairing secrets, and which files in the
+// chosen folder Coder may read and write.
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { lstat, mkdir, readdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+export const version = '0.2.0';
+// The messages the Workspace and the helper exchange; raised when they change incompatibly.
+export const protocol = 1;
+export const defaultPort = 47613;
+// Up to 3 shells at once (ADR-0094 amendment).
+export const maxShells = 3;
+// A pairing code lasts 10 minutes.
+export const codeMs = 10 * 60_000;
+
+// Only the AIONFLARE website, or with --dev a Workspace served from this computer.
+const siteOrigins = ['https://aionflare.com', 'https://www.aionflare.com'];
+export function originAllowed(origin, dev = false) {
+  if (typeof origin !== 'string') return false;
+  if (siteOrigins.includes(origin)) return true;
+  return dev && /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d{1,5})?$/.test(origin);
+}
+// The Host header must name this computer and the helper's port: a page that points another host
+// name at 127.0.0.1 (DNS rebinding) is refused.
+export function hostAllowed(host, port) {
+  if (typeof host !== 'string') return false;
+  const h = host.toLowerCase();
+  return h === '127.0.0.1:' + port || h === 'localhost:' + port || h === '[::1]:' + port;
+}
+
+// A device key (256 bits) and a pairing code (128 bits); only their SHA-256 is kept.
+export const newKey = () => randomBytes(32).toString('base64url');
+export const newCode = () => randomBytes(16).toString('base64url');
+export const newDeviceId = () => randomBytes(6).toString('hex');
+export const hashSecret = (secret) => createHash('sha256').update(String(secret)).digest('hex');
+export function sameHash(a, b) {
+  const hex = /^[0-9a-f]{64}$/;
+  if (typeof a !== 'string' || typeof b !== 'string' || !hex.test(a) || !hex.test(b)) return false;
+  return timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+}
+
+// Coder's own rules for a project file (packages/tools/src/coder.ts): a safe relative path of
+// letters, digits, `.`, `_`, `-` and `/`, at most six folders deep and 120 characters, with no `..`.
+export const fileLimits = { path: 120, fileChars: 100_000, files: 60, projectBytes: 2_000_000 };
+export function coderPath(value) {
+  if (typeof value !== 'string') return null;
+  const path = value
+    .trim()
+    .replace(/^\.?\/+/, '')
+    .replace(/\\/g, '/');
+  if (!path || path.length > fileLimits.path) return null;
+  if (!/^[A-Za-z0-9._/-]+$/.test(path)) return null;
+  const parts = path.split('/');
+  if (parts.length > 7 || parts.some((p) => !p || p === '.' || p === '..')) return null;
+  return path;
+}
+// Folders that stay in the folder and are never sent to a project: packages, Git, build output and
+// caches (ADR-0094, sections 1 and 4).
+export const excludedFolders = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  '.cache',
+  '.turbo',
+  '.parcel-cache',
+  '.vercel',
+  '__pycache__',
+  '.venv',
+  'venv',
+]);
+const excludedFiles = new Set(['.DS_Store', 'Thumbs.db']);
+
+const inside = (root, full) =>
+  full === root || full.startsWith(root.endsWith(sep) ? root : root + sep);
+
+// The chosen folder's files Coder may take: text files under Coder's limits, walked without
+// following links, skipping the excluded folders. What is skipped is named, with its reason.
+export async function listFiles(root) {
+  const files = [];
+  const skipped = [];
+  let seen = 0;
+  async function walk(dir, depth) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (++seen > 5000) return;
+      const full = join(dir, entry.name);
+      const rel = relative(root, full).split(sep).join('/');
+      if (entry.isSymbolicLink()) {
+        skipped.push({ path: rel, reason: 'link' });
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (excludedFolders.has(entry.name)) continue;
+        if (depth >= 6) {
+          skipped.push({ path: rel + '/', reason: 'too deep' });
+          continue;
+        }
+        await walk(full, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || excludedFiles.has(entry.name)) continue;
+      if (!coderPath(rel)) {
+        skipped.push({ path: rel, reason: 'name' });
+        continue;
+      }
+      const info = await lstat(full).catch(() => null);
+      if (!info) continue;
+      if (info.size > fileLimits.fileChars * 4) {
+        skipped.push({ path: rel, reason: 'too large' });
+        continue;
+      }
+      files.push({ path: rel, bytes: info.size });
+    }
+  }
+  await walk(root, 0);
+  return { files, skipped };
+}
+
+// A file inside the folder, for reading or writing: a Coder path, resolved within the folder, and
+// not reached through a link (the folder's real path is compared with each file's).
+export async function resolveInside(root, value, forWrite = false) {
+  const path = coderPath(value);
+  if (!path) return null;
+  const realRoot = await realpath(root);
+  const full = resolve(realRoot, ...path.split('/'));
+  if (!inside(realRoot, full) || full === realRoot) return null;
+  const existing = await lstat(full).catch(() => null);
+  if (existing && (existing.isSymbolicLink() || !existing.isFile())) return null;
+  if (forWrite) {
+    // Each folder on the way is created inside the folder, never through a link.
+    let dir = realRoot;
+    for (const part of path.split('/').slice(0, -1)) {
+      dir = join(dir, part);
+      const info = await lstat(dir).catch(() => null);
+      if (info && (info.isSymbolicLink() || !info.isDirectory())) return null;
+      if (!info) await mkdir(dir);
+    }
+    const realDir = await realpath(dirname(full));
+    if (!inside(realRoot, realDir)) return null;
+  } else {
+    if (!existing) return null;
+    const real = await realpath(full);
+    if (!inside(realRoot, real)) return null;
+  }
+  return { path, full };
+}
+
+// A text file's content, or why it cannot be taken.
+export async function readText(root, value) {
+  const at = await resolveInside(root, value);
+  if (!at) return { path: String(value), reason: 'not allowed' };
+  const data = await readFile(at.full);
+  if (data.includes(0)) return { path: at.path, reason: 'not text' };
+  const content = new TextDecoder('utf-8', { fatal: false }).decode(data);
+  if (content.includes('�')) return { path: at.path, reason: 'not text' };
+  if (content.length > fileLimits.fileChars) return { path: at.path, reason: 'too large' };
+  return { path: at.path, content };
+}
+export async function writeText(root, value, content) {
+  if (typeof content !== 'string' || content.length > fileLimits.fileChars)
+    return { path: String(value), reason: 'too large' };
+  const at = await resolveInside(root, value, true);
+  if (!at) return { path: String(value), reason: 'not allowed' };
+  await writeFile(at.full, content, 'utf8');
+  return { path: at.path };
+}

package/lib/folders.mjs

@@ -0,0 +1,108 @@
+// Owner (2026-11-07): the app's folder for a Coder project, chosen by the member in their own
+// computer's folder dialog (Windows Explorer, macOS Finder, or zenity on Linux): an existing folder,
+// or a new one named after the project inside the folder they pick. The website never names a path:
+// only folders picked here (or the one the helper started in) are used, and they are remembered in
+// the helper's settings so a project finds its folder again.
+import { spawn } from 'node:child_process';
+import { mkdir, stat } from 'node:fs/promises';
+import { platform } from 'node:os';
+import { join, resolve } from 'node:path';
+
+// A new folder's name: the project's name with only letters, digits, spaces, dots, dashes and
+// underscores (60 at most).
+export function folderName(name) {
+  const clean = String(name ?? '')
+    .replace(/[^A-Za-z0-9 ._-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^[.\s]+|[.\s]+$/g, '')
+    .slice(0, 60);
+  return clean || 'Coder project';
+}
+
+function run(file, args, env = {}) {
+  return new Promise((done) => {
+    const child = spawn(file, args, {
+      env: { ...process.env, ...env },
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: false,
+    });
+    let out = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.on('error', () => done(null));
+    child.on('close', (code) => done(code === 0 ? out.trim() : null));
+    // A dialog left open is closed after 5 minutes.
+    setTimeout(() => child.kill(), 5 * 60_000);
+  });
+}
+
+// The folder dialog of this computer, its title passed as an environment variable (never as code).
+// Null when the member cancels or the computer has no dialog.
+export async function pickFolder(title) {
+  const env = { AIONFLARE_DIALOG_TITLE: String(title).slice(0, 120) };
+  const os = platform();
+  if (os === 'win32')
+    return run(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-STA',
+        '-Command',
+        'Add-Type -AssemblyName System.Windows.Forms;' +
+          '$d = New-Object System.Windows.Forms.FolderBrowserDialog;' +
+          '$d.Description = $env:AIONFLARE_DIALOG_TITLE;' +
+          '$d.UseDescriptionForTitle = $true;' +
+          '$d.ShowNewFolderButton = $true;' +
+          '$top = New-Object System.Windows.Forms.Form -Property @{TopMost = $true};' +
+          "if ($d.ShowDialog($top) -eq 'OK') { [Console]::Out.Write($d.SelectedPath) }",
+      ],
+      env,
+    );
+  if (os === 'darwin')
+    return run(
+      'osascript',
+      [
+        '-e',
+        'set t to system attribute "AIONFLARE_DIALOG_TITLE"',
+        '-e',
+        'POSIX path of (choose folder with prompt t)',
+      ],
+      env,
+    );
+  return (
+    (await run('zenity', [
+      '--file-selection',
+      '--directory',
+      '--title',
+      env.AIONFLARE_DIALOG_TITLE,
+    ])) ??
+    run('kdialog', [
+      '--getexistingdirectory',
+      process.env.HOME ?? '/',
+      '--title',
+      env.AIONFLARE_DIALOG_TITLE,
+    ])
+  );
+}
+
+// "open": the folder picked. "create": a new folder named after the project inside the folder
+// picked (a number added when the name is taken). Null when cancelled.
+export async function chooseFolder(mode, name) {
+  const picked = await pickFolder(
+    mode === 'create'
+      ? 'AIONFLARE Coder: choose where to create the folder for ' + folderName(name)
+      : 'AIONFLARE Coder: choose the folder of ' + folderName(name),
+  );
+  if (!picked) return null;
+  const base = resolve(picked.replace(/[\r\n]+$/g, ''));
+  if (!(await stat(base).catch(() => null))?.isDirectory()) return null;
+  if (mode !== 'create') return base;
+  const wanted = folderName(name);
+  for (let n = 1; n < 100; n++) {
+    const target = join(base, n === 1 ? wanted : wanted + ' ' + n);
+    if (await stat(target).catch(() => null)) continue;
+    await mkdir(target);
+    return target;
+  }
+  return null;
+}

package/lib/server.mjs

@@ -0,0 +1,301 @@
+// ADR-0094 amendment (owner, 2026-11-07): the helper's server. It listens on this computer only
+// (127.0.0.1), accepts a WebSocket from the AIONFLARE website alone, pairs a browser with a
+// one-time code, and then opens the member's own shells and reads and writes files in the chosen
+// folder. It never connects out and logs no commands, output or file contents.
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { basename } from 'node:path';
+import { platform } from 'node:os';
+import {
+  codeMs,
+  fileLimits,
+  hashSecret,
+  hostAllowed,
+  listFiles,
+  maxShells,
+  newDeviceId,
+  newKey,
+  originAllowed,
+  protocol,
+  readText,
+  sameHash,
+  version,
+  writeText,
+} from './core.mjs';
+import { FrameReader, acceptKey, encodeFrame } from './ws.mjs';
+import { chooseFolder } from './folders.mjs';
+
+const require = createRequire(import.meta.url);
+// A message can carry a whole project (2 MB of text, written as JSON).
+const messageLimit = 8 * 1024 * 1024;
+
+function shellFor() {
+  if (platform() === 'win32')
+    return { file: 'powershell.exe', args: ['-NoLogo'], name: 'PowerShell' };
+  const file = process.env.SHELL || '/bin/bash';
+  return { file, args: ['-l'], name: basename(file) };
+}
+
+export function startServer({ folder: startFolder, port, dev, config, saveConfig, log }) {
+  // Owner (2026-11-07): the folder the helper works in: where it started, or one the member picked
+  // in their computer's folder dialog for a project (remembered in config.folders, the last 20).
+  let folder = startFolder;
+  const approved = () => [startFolder, ...(config.folders ?? [])];
+  const pty = require('node-pty');
+  const shell = shellFor();
+  // One pairing code each time the helper starts.
+  let pairing = { hash: '', expires: 0 };
+  let failures = 0;
+  let lockedUntil = 0;
+  let shells = 0;
+  const info = () => ({
+    t: 'ready',
+    version,
+    protocol,
+    platform: platform(),
+    shell: shell.name,
+    folder,
+    folder_name: basename(folder),
+    max_shells: maxShells,
+    features: ['choose', 'use'],
+    limits: fileLimits,
+  });
+
+  const server = createServer((req, res) => {
+    // Only the WebSocket is served; nothing for other pages to read.
+    res.writeHead(426, { 'Content-Type': 'text/plain', 'Cache-Control': 'no-store' });
+    res.end('aionflare-connect accepts the AIONFLARE Workspace only.');
+  });
+  server.on('upgrade', (req, socket) => {
+    const refuse = (status) => {
+      socket.end('HTTP/1.1 ' + status + '\r\nConnection: close\r\n\r\n');
+      socket.destroy();
+    };
+    const key = req.headers['sec-websocket-key'];
+    if (
+      !hostAllowed(req.headers.host, port) ||
+      !originAllowed(req.headers.origin, dev) ||
+      String(req.headers.upgrade).toLowerCase() !== 'websocket' ||
+      req.headers['sec-websocket-version'] !== '13' ||
+      typeof key !== 'string' ||
+      !/^[A-Za-z0-9+/]{22}==$/.test(key)
+    )
+      return refuse('403 Forbidden');
+    socket.write(
+      'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
+        'Sec-WebSocket-Accept: ' +
+        acceptKey(key) +
+        '\r\n\r\n',
+    );
+    connection(socket);
+  });
+
+  function connection(socket) {
+    let authed = null;
+    let closed = false;
+    const mine = new Map();
+    const send = (message) => {
+      if (!closed) socket.write(encodeFrame(0x1, JSON.stringify(message)));
+    };
+    const close = () => {
+      if (closed) return;
+      closed = true;
+      for (const term of mine.values()) term.kill();
+      mine.clear();
+      try {
+        socket.end(encodeFrame(0x8));
+      } catch {
+        /* already gone */
+      }
+      socket.destroy();
+      if (authed) log('Browser disconnected.');
+    };
+    // A browser that does not pair or sign in within 10 seconds is disconnected.
+    const signIn = setTimeout(() => !authed && close(), 10_000);
+    const reader = new FrameReader({
+      limit: messageLimit,
+      onText: (text) => {
+        let message;
+        try {
+          message = JSON.parse(text);
+        } catch {
+          return close();
+        }
+        handle(message).catch(() => send({ t: 'error', message: 'The helper could not do that.' }));
+      },
+      onClose: close,
+      onPing: (data) => socket.write(encodeFrame(0xa, data)),
+      onError: close,
+    });
+    socket.on('data', (chunk) => reader.push(chunk));
+    socket.on('close', close);
+    socket.on('error', close);
+
+    async function handle(m) {
+      if (!m || typeof m !== 'object') return close();
+      if (!authed) {
+        if (Date.now() < lockedUntil) {
+          send({ t: 'denied', reason: 'locked' });
+          return close();
+        }
+        if (m.t === 'pair' && typeof m.code === 'string') {
+          if (Date.now() > pairing.expires || !sameHash(hashSecret(m.code), pairing.hash))
+            return deny('code');
+          // The code is used once.
+          pairing = { hash: '', expires: 0 };
+          const id = newDeviceId();
+          const deviceKey = newKey();
+          config.devices = [
+            ...(config.devices ?? []).slice(-9),
+            { id, key_hash: hashSecret(deviceKey), paired_at: new Date().toISOString() },
+          ];
+          await saveConfig(config);
+          authed = id;
+          clearTimeout(signIn);
+          log('Paired a browser (' + id + ').');
+          return send({ ...info(), t: 'paired', device_id: id, key: deviceKey });
+        }
+        if (m.t === 'auth' && typeof m.device_id === 'string' && typeof m.key === 'string') {
+          const device = (config.devices ?? []).find((d) => d.id === m.device_id);
+          if (!device || !sameHash(hashSecret(m.key), device.key_hash)) return deny('key');
+          authed = device.id;
+          failures = 0;
+          clearTimeout(signIn);
+          log('Browser connected (' + device.id + ').');
+          return send(info());
+        }
+        return deny('first');
+      }
+      const reply = (extra) => send({ t: 'res', rid: m.rid, ...extra });
+      switch (m.t) {
+        case 'open': {
+          if (shells >= maxShells)
+            return send({ t: 'error', id: m.id, message: 'Up to 3 shells at once.' });
+          const id = String(m.id ?? '').slice(0, 40);
+          if (!id || mine.has(id)) return;
+          const term = pty.spawn(shell.file, shell.args, {
+            name: 'xterm-256color',
+            cols: clamp(m.cols, 20, 400, 80),
+            rows: clamp(m.rows, 5, 200, 24),
+            cwd: folder,
+            env: { ...process.env, AIONFLARE_TERMINAL: '1' },
+          });
+          shells++;
+          mine.set(id, term);
+          log('Shell opened (' + shells + ' of ' + maxShells + ').');
+          term.onData((data) => send({ t: 'out', id, d: data }));
+          term.onExit(({ exitCode }) => {
+            mine.delete(id);
+            shells = Math.max(0, shells - 1);
+            log('Shell closed.');
+            send({ t: 'exit', id, code: exitCode });
+          });
+          return send({ t: 'opened', id, shell: shell.name });
+        }
+        case 'in':
+          if (typeof m.d === 'string') mine.get(m.id)?.write(m.d.slice(0, 65536));
+          return;
+        case 'size':
+          mine.get(m.id)?.resize(clamp(m.cols, 20, 400, 80), clamp(m.rows, 5, 200, 24));
+          return;
+        case 'kill':
+          mine.get(m.id)?.kill();
+          return;
+        case 'list':
+          return reply(await listFiles(folder));
+        case 'read': {
+          const paths = Array.isArray(m.paths) ? m.paths.slice(0, 300) : [];
+          const out = [];
+          for (const p of paths)
+            out.push(
+              await readText(folder, p).catch(() => ({ path: String(p), reason: 'unreadable' })),
+            );
+          return reply({
+            files: out.filter((f) => 'content' in f),
+            skipped: out.filter((f) => !('content' in f)),
+          });
+        }
+        case 'write': {
+          const files = Array.isArray(m.files) ? m.files.slice(0, 300) : [];
+          const out = [];
+          for (const f of files)
+            out.push(
+              await writeText(folder, f?.path, f?.content).catch(() => ({
+                path: String(f?.path),
+                reason: 'unwritable',
+              })),
+            );
+          log('Coder wrote ' + out.filter((f) => !f.reason).length + ' files.');
+          return reply({
+            written: out.filter((f) => !f.reason).length,
+            skipped: out.filter((f) => f.reason),
+          });
+        }
+        // Owner (2026-11-07): a project's folder, picked in this computer's own folder dialog
+        // (an existing one, or a new one named after the project); then the helper works there.
+        case 'choose': {
+          const picked = await chooseFolder(m.mode === 'create' ? 'create' : 'open', m.name);
+          if (!picked) return reply({ cancelled: true });
+          config.folders = [...(config.folders ?? []).filter((f) => f !== picked), picked].slice(
+            -20,
+          );
+          await saveConfig(config);
+          folder = picked;
+          log('Working in ' + folder + '.');
+          return reply({ folder, folder_name: basename(folder) });
+        }
+        // A folder picked before (or the one the helper started in), by its full path.
+        case 'use': {
+          const wanted = String(m.folder ?? '');
+          if (!approved().includes(wanted) || !(await isFolder(wanted)))
+            return reply({ refused: true });
+          folder = wanted;
+          return reply({ folder, folder_name: basename(folder) });
+        }
+        case 'forget': {
+          config.devices = (config.devices ?? []).filter((d) => d.id !== authed);
+          await saveConfig(config);
+          log('A browser forgot this computer (' + authed + ').');
+          send({ t: 'forgotten' });
+          return close();
+        }
+        default:
+          return;
+      }
+    }
+    function deny(reason) {
+      // Ten wrong codes or keys lock pairing and sign-in for a minute.
+      if (++failures >= 10) {
+        lockedUntil = Date.now() + 60_000;
+        failures = 0;
+      }
+      send({ t: 'denied', reason });
+      close();
+    }
+  }
+
+  return {
+    server,
+    newPairing(code) {
+      pairing = { hash: hashSecret(code), expires: Date.now() + codeMs };
+    },
+    listen() {
+      return new Promise((ok, fail) => {
+        server.once('error', fail);
+        server.listen(port, '127.0.0.1', () => {
+          server.off('error', fail);
+          ok();
+        });
+      });
+    },
+  };
+}
+
+async function isFolder(path) {
+  const { stat } = await import('node:fs/promises');
+  return !!(await stat(path).catch(() => null))?.isDirectory();
+}
+function clamp(value, min, max, fallback) {
+  const n = Math.floor(Number(value));
+  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
+}

package/lib/ws.mjs

@@ -0,0 +1,87 @@
+// ADR-0094 amendment: a small WebSocket server side (RFC 6455), so the helper depends on nothing but
+// node-pty. Text messages only; the browser's frames are masked, the helper's are not.
+import { createHash } from 'node:crypto';
+
+const guid = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+export const acceptKey = (key) =>
+  createHash('sha1')
+    .update(key + guid)
+    .digest('base64');
+
+// One frame to send: FIN set, unmasked, with its length in 7, 16 or 64 bits.
+export function encodeFrame(opcode, payload = Buffer.alloc(0)) {
+  const body = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), 'utf8');
+  const n = body.length;
+  const head =
+    n < 126
+      ? Buffer.from([0x80 | opcode, n])
+      : n < 65536
+        ? Buffer.from([0x80 | opcode, 126, n >> 8, n & 255])
+        : (() => {
+            const h = Buffer.alloc(10);
+            h[0] = 0x80 | opcode;
+            h[1] = 127;
+            h.writeBigUInt64BE(BigInt(n), 2);
+            return h;
+          })();
+  return Buffer.concat([head, body]);
+}
+
+// Reads the browser's frames as bytes arrive and reports whole messages. Unmasked frames, binary
+// messages and anything over the size limit end the connection.
+export class FrameReader {
+  #buffer = Buffer.alloc(0);
+  #parts = [];
+  #size = 0;
+  constructor({ limit, onText, onClose, onPing, onError }) {
+    Object.assign(this, { limit, onText, onClose, onPing, onError });
+  }
+  push(chunk) {
+    this.#buffer = Buffer.concat([this.#buffer, chunk]);
+    for (;;) {
+      const b = this.#buffer;
+      if (b.length < 2) return;
+      const fin = (b[0] & 0x80) !== 0;
+      const opcode = b[0] & 0x0f;
+      const masked = (b[1] & 0x80) !== 0;
+      let length = b[1] & 0x7f;
+      let at = 2;
+      if (length === 126) {
+        if (b.length < 4) return;
+        length = b.readUInt16BE(2);
+        at = 4;
+      } else if (length === 127) {
+        if (b.length < 10) return;
+        const big = b.readBigUInt64BE(2);
+        if (big > BigInt(this.limit)) return this.onError('too large');
+        length = Number(big);
+        at = 10;
+      }
+      if (!masked) return this.onError('unmasked');
+      if (length > this.limit) return this.onError('too large');
+      if (b.length < at + 4 + length) return;
+      const mask = b.subarray(at, at + 4);
+      const payload = Buffer.from(b.subarray(at + 4, at + 4 + length));
+      for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+      this.#buffer = b.subarray(at + 4 + length);
+      if (opcode === 0x8) return this.onClose();
+      if (opcode === 0x9) {
+        this.onPing(payload);
+        continue;
+      }
+      if (opcode === 0xa) continue;
+      if (opcode === 0x2) return this.onError('binary');
+      if (opcode !== 0x1 && opcode !== 0x0) return this.onError('opcode');
+      if ((opcode === 0x1) === this.#parts.length > 0) return this.onError('fragments');
+      this.#size += payload.length;
+      if (this.#size > this.limit) return this.onError('too large');
+      this.#parts.push(payload);
+      if (fin) {
+        const text = Buffer.concat(this.#parts).toString('utf8');
+        this.#parts = [];
+        this.#size = 0;
+        this.onText(text);
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "aionflare-connect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A local terminal for AIONFLARE Coder: open shells on your own computer from the Workspace.",
+  "type": "module",
+  "bin": {
+    "aionflare-connect": "bin/aionflare-connect.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "node-pty": "1.1.0"
+  },
+  "license": "MIT",
+  "homepage": "https://aionflare.com"
+}