@abot-ai/socket 0.0.0-stage → 0.1.0

package/src/review/review-demo-isolation.mjs

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from 'node:fs';
+import { basename, dirname, join, parse, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { assertPrivateStateDirectory, assertSameDatabaseFile } from '../auth/auth-storage-path.mjs';
+import { validateConfiguration } from '../config/config-validation.mjs';
+
+const MAX_PRIVATE_BYTES = 32_768;
+const PORTAL_KEYS = ['version', 'purpose', 'demoId', 'ownerId', 'configSha256',
+  'publicOrigin', 'port', 'username', 'passwordSha256'];
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+
+/** Bind only the demo identity; operators may configure its modes and push later. */
+export function reviewDemoIdentitySha256(config) {
+  const runtimeGrants = config.runtimeGrants.map(({ runtimeId, tokenSha256 }) => ({ runtimeId, tokenSha256 }))
+    .sort((left, right) => left.runtimeId.localeCompare(right.runtimeId));
+  return digest(JSON.stringify({ publicOrigin: config.publicOrigin,
+    stateDirectory: config.stateDirectory, runtimeGrants }));
+}
+
+export function assertReviewEndpointSeparation(socketConfig, publicOrigin, port) {
+  let origin;
+  try { origin = new URL(publicOrigin); } catch { /* Validated below. */ }
+  if (!origin || origin.protocol !== 'https:' || origin.origin !== publicOrigin || origin.username || origin.password) {
+    throw new Error('Review portal requires a canonical HTTPS origin');
+  }
+  if (publicOrigin === socketConfig.publicOrigin) throw new Error('Socket and review origins must differ');
+  if (!Number.isInteger(port) || port < 1024 || port > 65535 || port === socketConfig.port) {
+    throw new Error('Socket and review listener ports must differ and be unprivileged');
+  }
+}
+
+export function assertReviewDemoParentPath(directory) {
+  let current = parse(directory).root;
+  for (const component of directory.slice(current.length).split('/').filter(Boolean)) {
+    current = join(current, component);
+    const entry = lstatSync(current);
+    if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error('Unsafe demo installation path');
+  }
+}
+
+function assertPrivateDemoDirectory(directory) {
+  assertReviewDemoParentPath(directory);
+  const stat = lstatSync(directory);
+  if (typeof process.getuid !== 'function' || stat.uid !== process.getuid() || (stat.mode & 0o7777) !== 0o700) {
+    throw new Error('Demo installation must be private and owned by the current user');
+  }
+}
+
+function readPrivateDemoJson(path) {
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid() ||
+        (stat.mode & 0o7777) !== 0o600 || stat.size > MAX_PRIVATE_BYTES) throw new Error();
+    const bytes = Buffer.alloc(MAX_PRIVATE_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(descriptor, bytes, length, bytes.length - length, null);
+      if (count === 0) break;
+      length += count;
+    }
+    if (length > MAX_PRIVATE_BYTES) throw new Error();
+    return JSON.parse(bytes.toString('utf8', 0, length));
+  } finally { if (descriptor !== undefined) closeSync(descriptor); }
+}
+
+function validatePortalRecord(value, socketConfig) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.keys(value).length !== PORTAL_KEYS.length || Object.keys(value).some(key => !PORTAL_KEYS.includes(key))) {
+    throw new Error('Invalid review portal configuration');
+  }
+  if (value.version !== 1 || value.purpose !== 'review-demo' || value.username !== 'reviewer' ||
+      typeof value.demoId !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(value.demoId) ||
+      typeof value.ownerId !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value.ownerId)) {
+    throw new Error('Invalid review demo identity');
+  }
+  for (const key of ['configSha256', 'passwordSha256']) {
+    if (typeof value[key] !== 'string' || !/^[a-f0-9]{64}$/.test(value[key])) throw new Error('Invalid review credential binding');
+  }
+  assertReviewEndpointSeparation(socketConfig, value.publicOrigin, value.port);
+  if (value.configSha256 !== reviewDemoIdentitySha256(socketConfig)) throw new Error('Demo socket identity changed');
+}
+
+function assertMarkedDemoDatabase(stateDirectory, portal) {
+  assertPrivateStateDirectory(stateDirectory);
+  const path = join(stateDirectory, 'auth.sqlite3');
+  const prepared = { path, stat: lstatSync(path) };
+  // Never instantiate AuthDatabase here: it can initialize or migrate state.
+  const database = new DatabaseSync(path, { readOnly: true });
+  try {
+    assertSameDatabaseFile(stateDirectory, prepared);
+    if (database.prepare('PRAGMA application_id').get().application_id !== 0x41425341) throw new Error();
+    const read = database.prepare('SELECT value FROM metadata WHERE key = ?');
+    if (read.get('review_demo_id')?.value !== portal.demoId || read.get('owner_id')?.value !== portal.ownerId) {
+      throw new Error('State does not belong to this review demo');
+    }
+    assertSameDatabaseFile(stateDirectory, prepared);
+  } finally { database.close(); }
+}
+
+function selectedDemoConfiguration(env) {
+  const primary = env.ABOT_SOCKET_CONFIG;
+  const legacy = env.SOCKET_V2_CONFIG;
+  if (primary && legacy && primary !== legacy) throw new Error('Conflicting demo configuration paths');
+  const value = primary || legacy;
+  if (typeof value !== 'string' || !value.trim() || value.length > 4096 || /[\x00-\x1f\x7f]/.test(value)) {
+    throw new Error('Choose a private demo config.json');
+  }
+  const path = resolve(value);
+  if (basename(path) !== 'config.json') throw new Error('Choose the demo config.json');
+  return path;
+}
+
+/** Separate-process gate: fixed siblings and existing marked state only. */
+export function loadReviewDemoConfiguration(env = {}) {
+  try {
+    const configPath = selectedDemoConfiguration(env);
+    const directory = dirname(configPath);
+    assertPrivateDemoDirectory(directory);
+    const socketConfig = validateConfiguration(readPrivateDemoJson(configPath));
+    if (socketConfig.stateDirectory !== './state') throw new Error('Demo state must remain its fixed sibling');
+    const portal = readPrivateDemoJson(join(directory, 'review-portal.json'));
+    validatePortalRecord(portal, socketConfig);
+    const stateDirectory = join(directory, 'state');
+    assertMarkedDemoDatabase(stateDirectory, portal);
+    return Object.freeze({ ...portal, socketOrigin: socketConfig.publicOrigin, stateDirectory });
+  } catch {
+    throw new Error('Review portal requires a private marked demo installation with matching socket and state identities');
+  }
+}

package/src/review/review-demo-setup.mjs

@@ -0,0 +1,97 @@
+import { createHash, randomBytes } from 'node:crypto';
+import * as filesystem from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { AuthDatabase } from '../auth/auth-database.mjs';
+import { prepareInstallation } from '../setup/setup.mjs';
+import { writePrivateInstallation } from '../setup/setup-files.mjs';
+import { assertReviewDemoParentPath, assertReviewEndpointSeparation, reviewDemoIdentitySha256 } from './review-demo-isolation.mjs';
+
+const OPTIONS = new Map([['--output', 'output'], ['--origin', 'origin'], ['--runtime-id', 'runtimeId'],
+  ['--review-origin', 'reviewOrigin'], ['--port', 'port'], ['--review-port', 'reviewPort']]);
+
+export function parseReviewDemoArguments(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const name = OPTIONS.get(args[index]);
+    const value = args[index + 1];
+    if (!name || Object.hasOwn(options, name) || typeof value !== 'string' || !value || value.startsWith('--')) {
+      throw new Error('Provide each review setup option once with a value');
+    }
+    if (name === 'port' || name === 'reviewPort') {
+      if (!/^\d{1,5}$/.test(value)) throw new Error('Invalid review listener port');
+      options[name] = Number(value);
+      continue;
+    }
+    options[name] = value;
+  }
+  for (const name of ['output', 'origin', 'runtimeId', 'reviewOrigin']) {
+    if (!options[name]) throw new Error('Missing required review setup option');
+  }
+  return options;
+}
+
+function writePrivateReviewFile(path, content, created, io) {
+  const descriptor = io.openSync(path, 'wx', 0o600);
+  created.push(path);
+  try { io.writeFileSync(descriptor, content); io.fsyncSync(descriptor); }
+  finally { io.closeSync(descriptor); }
+}
+
+function removeOwnedFailedDemo(directory, created, stateCreated, io) {
+  const failures = [];
+  for (const path of created.reverse()) {
+    try { io.unlinkSync(path); } catch (error) { failures.push(error); }
+  }
+  if (stateCreated) {
+    const state = join(directory, 'state');
+    for (const name of ['auth.sqlite3-journal', 'auth.sqlite3']) {
+      try { io.unlinkSync(join(state, name)); } catch (error) { if (error.code !== 'ENOENT') failures.push(error); }
+    }
+    try { io.rmdirSync(state); } catch (error) { failures.push(error); }
+  }
+  try { io.rmdirSync(directory); } catch (error) { failures.push(error); }
+  return failures;
+}
+
+/** Local file preparation only; no existing installation, services or runtime is reused. */
+export function createReviewDemoInstallation(options, { io = filesystem } = {}) {
+  if (typeof options.output !== 'string' || !options.output.trim()) throw new Error('Choose a new private demo directory');
+  const bundle = prepareInstallation(options);
+  const port = options.reviewPort ?? 8789;
+  assertReviewEndpointSeparation(bundle.config, options.reviewOrigin, port);
+  const directory = resolve(options.output);
+  assertReviewDemoParentPath(dirname(directory));
+  writePrivateInstallation(directory, bundle, io);
+  const created = [join(directory, 'config.json'), join(directory, 'runtime-connection.json')];
+  let stateCreated = false;
+  try {
+    const stateDirectory = join(directory, 'state');
+    io.mkdirSync(stateDirectory, { mode: 0o700 });
+    stateCreated = true;
+    const database = new AuthDatabase(stateDirectory);
+    const demoId = randomBytes(32).toString('base64url');
+    let ownerId;
+    try {
+      ownerId = database.ownerId;
+      database.transaction(() => database.prepare('INSERT INTO metadata(key, value) VALUES (?, ?)')
+        .run('review_demo_id', demoId));
+    } finally { database.close(); }
+    const password = randomBytes(32).toString('base64url');
+    const portal = { version: 1, purpose: 'review-demo', demoId, ownerId,
+      configSha256: reviewDemoIdentitySha256(bundle.config), publicOrigin: options.reviewOrigin,
+      port, username: 'reviewer', passwordSha256: createHash('sha256').update(password).digest('hex') };
+    writePrivateReviewFile(join(directory, 'review-portal.json'), `${JSON.stringify(portal, null, 2)}\n`, created, io);
+    writePrivateReviewFile(join(directory, 'review-access.txt'),
+      `ABot isolated review demo\nPortal: ${portal.publicOrigin}/review\nUsername: reviewer\nPassword: ${password}\n\n` +
+      'Keep these reviewer credentials private. The portal issues normal single-use 5-minute pairing details.\n' +
+      'The demo runtime must use separate storage and synthetic data; this setup does not create or isolate a runtime.\n', created, io);
+    return { directory, configPath: join(directory, 'config.json'),
+      runtimeConnectionPath: join(directory, 'runtime-connection.json'),
+      reviewConfigurationPath: join(directory, 'review-portal.json'),
+      reviewAccessPath: join(directory, 'review-access.txt') };
+  } catch (error) {
+    const failures = removeOwnedFailedDemo(directory, created, stateCreated, io);
+    if (failures.length) throw new AggregateError([error, ...failures], 'Review setup failed and owned cleanup was incomplete');
+    throw error;
+  }
+}

package/src/review/review-portal-access.mjs

@@ -0,0 +1,64 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { WindowLimiter } from '../transport/transport-limits.mjs';
+
+const CSRF_MS = 10 * 60 * 1000;
+
+function matchesReviewerAuthorization(value, username, passwordSha256) {
+  if (typeof value !== 'string' || value.length > 512) return false;
+  const match = /^Basic ([A-Za-z0-9+/]+={0,2})$/.exec(value);
+  if (!match) return false;
+  const bytes = Buffer.from(match[1], 'base64');
+  if (bytes.toString('base64') !== match[1]) return false;
+  const decoded = bytes.toString('utf8');
+  const separator = decoded.indexOf(':');
+  if (separator < 0 || decoded.slice(0, separator) !== username) return false;
+  const password = decoded.slice(separator + 1);
+  if (!/^[A-Za-z0-9_-]{43}$/.test(password)) return false;
+  const digest = createHash('sha256').update(password).digest();
+  return timingSafeEqual(digest, Buffer.from(passwordSha256, 'hex'));
+}
+
+/** Browser access grants pairing issuance only, never a runtime or device token. */
+export class ReviewPortalAccess {
+  constructor({ username, passwordSha256, now = Date.now }) {
+    if (username !== 'reviewer' || !/^[a-f0-9]{64}$/.test(passwordSha256 ?? '')) {
+      throw new Error('Invalid reviewer access configuration');
+    }
+    this.username = username;
+    this.passwordSha256 = passwordSha256;
+    this.now = now;
+    this.csrfKey = randomBytes(32);
+    this.failedSources = new WindowLimiter({ limit: 10, windowMs: 900_000, now });
+    this.failedTotal = new WindowLimiter({ limit: 200, windowMs: 900_000, capacity: 1, now });
+    this.pairSources = new WindowLimiter({ limit: 5, windowMs: 60_000, now });
+    this.pairTotal = new WindowLimiter({ limit: 20, windowMs: 60_000, capacity: 1, now });
+  }
+
+  authenticate(authorization, sourceId) {
+    if (matchesReviewerAuthorization(authorization, this.username, this.passwordSha256)) return 200;
+    if (!this.failedSources.allow(sourceId)) return 429;
+    if (!this.failedTotal.allow('failures')) return 429;
+    return 401;
+  }
+
+  createCsrf() {
+    const value = `${this.now()}.${randomBytes(16).toString('base64url')}`;
+    return `${value}.${createHmac('sha256', this.csrfKey).update(value).digest('base64url')}`;
+  }
+
+  acceptsCsrf(token) {
+    if (typeof token !== 'string' || token.length > 128) return false;
+    const match = /^(\d{1,16})\.([A-Za-z0-9_-]{22})\.([A-Za-z0-9_-]{43})$/.exec(token);
+    if (!match) return false;
+    const issuedAt = Number(match[1]);
+    if (!Number.isSafeInteger(issuedAt) || issuedAt > this.now()) return false;
+    if (this.now() - issuedAt >= CSRF_MS) return false;
+    const expected = createHmac('sha256', this.csrfKey).update(`${match[1]}.${match[2]}`).digest('base64url');
+    return timingSafeEqual(Buffer.from(match[3]), Buffer.from(expected));
+  }
+
+  allowPairing(sourceId) {
+    if (!this.pairSources.allow(sourceId)) return false;
+    return this.pairTotal.allow('pairings');
+  }
+}

package/src/review/review-portal-form.mjs

@@ -0,0 +1,24 @@
+function formError(code, status) {
+  return Object.assign(new Error(code), { code, status });
+}
+
+export async function readReviewPairingForm(req) {
+  const contentType = (req.headers['content-type'] ?? '').split(';')[0].trim();
+  if (contentType !== 'application/x-www-form-urlencoded') throw formError('invalid_content_type', 415);
+  const length = req.headers['content-length'];
+  if (length !== undefined && (!/^\d+$/.test(length) || Number(length) > 4096)) {
+    throw formError('payload_too_large', 413);
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 4096) throw formError('payload_too_large', 413);
+    chunks.push(chunk);
+  }
+  const form = new URLSearchParams(Buffer.concat(chunks).toString('utf8'));
+  if ([...form.keys()].some(key => key !== 'csrf') || form.getAll('csrf').length !== 1) {
+    throw formError('invalid_form', 400);
+  }
+  return form.get('csrf');
+}

package/src/review/review-portal-page.mjs

@@ -0,0 +1,68 @@
+import qrcode from 'qrcode-generator';
+import { pairingQrPayload } from '../pairing/pairing-qr-payload.mjs';
+
+const escapeHtml = value => String(value).replace(/[&<>"']/g, char =>
+  ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]);
+
+const STYLES = `
+:root{color-scheme:light dark;font-family:system-ui,-apple-system,sans-serif;background:#0b0b0b;color:#eee}
+*{box-sizing:border-box}body{margin:0}main{max-width:860px;margin:auto;padding:32px 24px 56px}
+header{display:flex;align-items:center;gap:12px;margin-bottom:52px;font-size:14px;color:#aaa}
+.brand{font-size:25px;font-weight:800;letter-spacing:-3px;color:#baf4e0;padding-right:4px}
+h1{font-size:clamp(30px,5vw,42px);letter-spacing:-1px;line-height:1.15;margin:0 0 16px}
+p,li{line-height:1.65;color:#bbb}p{max-width:65ch}h2{font-size:18px;margin:0 0 14px}
+.panel{margin-top:28px;padding:24px;border:1px solid #303030;border-radius:18px;background:#141414}
+.pairing{display:grid;grid-template-columns:minmax(180px,240px) minmax(0,1fr);align-items:start;gap:28px}
+.qr{background:white;color:black;padding:10px;border-radius:12px}.qr svg{display:block;width:100%;height:auto}
+dl{margin:0}dt{font-size:12px;color:#aaa;margin-top:18px}dt:first-child{margin-top:0}
+dd{margin:5px 0 0;font:14px ui-monospace,monospace;overflow-wrap:anywhere;user-select:all}
+#pairing-code{font-size:28px;letter-spacing:5px}button{font:inherit;font-weight:600;border:0;border-radius:12px;
+padding:14px 20px;background:#baf4e0;color:#10251e;cursor:pointer;margin-top:18px}
+button:focus-visible,a:focus-visible{outline:3px solid #8fbaef;outline-offset:4px}a{color:#baf4e0}
+.note{font-size:14px;color:#aaa}.error{color:#ffb9ad}.expiry{font-size:13px;color:#ccc}
+footer{margin-top:40px;border-top:1px solid #303030;padding-top:20px;color:#888;font-size:13px}
+@media(max-width:560px){main{padding:24px 18px}.pairing{grid-template-columns:1fr}.qr{max-width:280px;margin:auto}}
+@media(prefers-color-scheme:light){:root{background:#f7f7f7;color:#161616}.panel{background:white;border-color:#ddd}
+p,li{color:#505050}header,.note,dt,footer{color:#666}.brand,a{color:#13664c}.expiry{color:#555}.error{color:#9f2618}}
+`;
+
+function renderPairingDetails(pairing) {
+  if (!pairing) return '';
+  const qr = qrcode(0, 'M');
+  qr.addData(pairingQrPayload(pairing), 'Byte');
+  qr.make();
+  return `<section class="panel" aria-labelledby="pairing-title">
+<h2 id="pairing-title">Your temporary pairing details</h2>
+<div class="pairing"><div class="qr" role="img" aria-label="ABot pairing QR code">
+${qr.createSvgTag({ cellSize: 4, margin: 16, scalable: true })}</div><dl>
+<dt>One-time code</dt><dd id="pairing-code">${escapeHtml(pairing.code)}</dd>
+<dt>Server URL</dt><dd id="pairing-server-url">${escapeHtml(pairing.serverUrl)}</dd>
+<dt>Temporary pairing key</dt><dd id="pairing-id">${escapeHtml(pairing.pairingId)}</dd>
+</dl></div><p class="expiry">Use once before ${escapeHtml(new Date(pairing.expiresAt).toUTCString())}.
+After five minutes, generate new details.</p><span id="pairing-expires-at" hidden>${pairing.expiresAt}</span></section>`;
+}
+
+export function renderReviewPage({ socketOrigin, csrf, nonce, pairing, error }) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>ABot — Review workspace</title>
+<style nonce="${escapeHtml(nonce)}">${STYLES}</style></head><body><main>
+<header><span class="brand" aria-label="ABot">AB</span><span>Review workspace</span></header>
+<h1>Pair your app.<br>Explore ABot.</h1>
+<p>This access page connects the regular ABot app to a dedicated demonstration workspace.
+Only use demonstration data in this environment.</p>
+${error ? `<p class="error" role="alert">${escapeHtml(error)}</p>` : ''}
+${renderPairingDetails(pairing)}
+<section class="panel"><h2>${pairing ? 'Need another pairing?' : 'Get started'}</h2>
+<ol><li>Open ABot and unlock it with your device authentication.</li>
+<li>Choose <strong>Scan pairing code</strong> and scan the QR from another screen.
+On one device, choose <strong>Enter details manually</strong> and use the code, server URL and key above.</li>
+<li>Confirm <strong>${escapeHtml(socketOrigin)}</strong>, then choose the review computer.</li></ol>
+${csrf ? `<form method="post" action="/review/pair"><input type="hidden" name="csrf" value="${escapeHtml(csrf)}">
+<button type="submit">${pairing ? 'Generate new pairing details' : 'Generate pairing details'}</button></form>`
+    : '<p><a href="/review">Return to the review page</a> to continue.</p>'}
+<p class="note">Generating new details replaces any unused QR. Already paired devices stay connected.
+Keep the details private. This page never needs your device passcode.</p></section>
+<footer>If the review computer is offline or a feature is unavailable, contact the developer using
+the contact details in App Store Connect. This page does not confirm runtime or model availability.</footer>
+</main></body></html>`;
+}

package/src/review/review-portal-server.mjs

@@ -0,0 +1,105 @@
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { AuthService } from '../auth/auth.mjs';
+import { sameAuthority, trustedClientAddress } from '../transport/transport-limits.mjs';
+import { ReviewPortalAccess } from './review-portal-access.mjs';
+import { readReviewPairingForm } from './review-portal-form.mjs';
+import { renderReviewPage } from './review-portal-page.mjs';
+import { loadReviewDemoConfiguration } from './review-demo-isolation.mjs';
+
+function requirePortalOrigin(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'https:' || url.origin !== value) throw new Error('Canonical HTTPS origin required');
+  return url;
+}
+
+function acceptsPortalTransport(req, origin) {
+  if (!sameAuthority(req, origin)) return false;
+  return req.headers['x-forwarded-proto'] === 'https';
+}
+
+function acceptsPairingSubmissionOrigin(req, origin) {
+  if (req.headers.origin !== origin.origin) return false;
+  const site = req.headers['sec-fetch-site'];
+  return site === undefined || site === 'same-origin';
+}
+
+function sendPortalPage(res, status, details, headers = {}) {
+  const nonce = randomBytes(18).toString('base64url');
+  const page = renderReviewPage({ ...details, nonce });
+  res.writeHead(status, {
+    'content-type': 'text/html; charset=utf-8', 'content-length': Buffer.byteLength(page),
+    'cache-control': 'no-store, private', pragma: 'no-cache',
+    'content-security-policy': `default-src 'none'; style-src 'nonce-${nonce}'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'`,
+    'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff',
+    'x-frame-options': 'DENY', 'x-robots-tag': 'noindex, nofollow, noarchive',
+    'permissions-policy': 'camera=(), microphone=(), geolocation=()', ...headers,
+  });
+  res.end(page);
+}
+
+/** Internal constructor; the CLI must load and verify a fresh demo installation first. */
+export function createReviewPortalServer({ publicOrigin, socketOrigin, username, passwordSha256,
+  stateDirectory, now = Date.now }) {
+  const origin = requirePortalOrigin(publicOrigin);
+  requirePortalOrigin(socketOrigin);
+  if (publicOrigin === socketOrigin) throw new Error('A distinct review origin is required');
+  const access = new ReviewPortalAccess({ username, passwordSha256, now });
+  const auth = new AuthService({ stateDirectory, now });
+  const send = (res, status, details = {}, headers) => sendPortalPage(res, status,
+    { socketOrigin, csrf: '', ...details }, headers);
+  const server = createServer(async (req, res) => {
+    try {
+      if (!acceptsPortalTransport(req, origin)) return send(res, 403, { error: 'Request not allowed.' });
+      const source = trustedClientAddress(req);
+      if (!source) return send(res, 403, { error: 'Request not allowed.' });
+      if (!['/review', '/review/pair'].includes(req.url)) return send(res, 404, { error: 'Page not found.' });
+      const status = access.authenticate(req.headers.authorization, source);
+      if (status === 401) return send(res, 401, { error: 'Use the review access details supplied by the developer.' },
+        { 'www-authenticate': 'Basic realm="ABot review workspace", charset="UTF-8"' });
+      if (status === 429) return send(res, 429, { error: 'Too many attempts. Try again later.' }, { 'retry-after': '900' });
+      if (req.method === 'GET' && req.url === '/review') return send(res, 200, { csrf: access.createCsrf() });
+      if (req.method !== 'POST' || req.url !== '/review/pair') {
+        return send(res, 405, { error: 'Method not allowed.' });
+      }
+      if (!acceptsPairingSubmissionOrigin(req, origin)) return send(res, 403, { error: 'Open the review page to continue.' });
+      const csrf = await readReviewPairingForm(req);
+      if (!access.acceptsCsrf(csrf)) return send(res, 403, { error: 'Reload the review page and try again.' });
+      if (!access.allowPairing(source)) {
+        return send(res, 429, { error: 'Please wait a minute before generating more pairing details.' }, { 'retry-after': '60' });
+      }
+      const pairing = { serverUrl: socketOrigin, ...auth.createPairing() };
+      return send(res, 200, { csrf: access.createCsrf(), pairing });
+    } catch (error) {
+      const status = [400, 413, 415].includes(error.status) ? error.status : 500;
+      if (!res.headersSent && !res.destroyed) send(res, status, { error: 'Unable to process this request. Reload the review page or contact the developer.' });
+    }
+  });
+  server.requestTimeout = 15_000;
+  server.headersTimeout = 5_000;
+  server.keepAliveTimeout = 5_000;
+  server.maxHeadersCount = 32;
+  server.maxConnections = 32;
+  server.on('upgrade', (_req, socket) => socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n'));
+  let stopped = false;
+  return {
+    listen: (port = 8789) => new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, '127.0.0.1', () => { server.off('error', reject); resolve(server.address()); });
+    }),
+    close: () => new Promise(resolve => {
+      if (stopped) { resolve(); return; }
+      stopped = true;
+      server.closeAllConnections();
+      server.close(() => { auth.close(); resolve(); });
+    }),
+  };
+}
+
+export async function startConfiguredReviewPortal(env = process.env) {
+  const config = loadReviewDemoConfiguration(env);
+  const portal = createReviewPortalServer(config);
+  try { await portal.listen(config.port); }
+  catch (error) { await portal.close(); throw error; }
+  return portal;
+}

package/src/setup/setup-files.mjs

@@ -0,0 +1,37 @@
+import * as filesystem from 'node:fs';
+import { join } from 'node:path';
+
+function removeFailedInstallation(directory, created, io) {
+  const failures = [];
+  for (const path of created.reverse()) {
+    try { io.unlinkSync(path); } catch (error) { failures.push(error); }
+  }
+  try { io.rmdirSync(directory); } catch (error) { failures.push(error); }
+  return failures;
+}
+
+export function writePrivateInstallation(directory, bundle, io = filesystem) {
+  // Serialize before creating anything. Names are fixed, never caller-supplied paths.
+  const files = [
+    ['config.json', JSON.stringify(bundle.config, null, 2)],
+    ['runtime-connection.json', JSON.stringify(bundle.runtimeConnection, null, 2)],
+  ];
+  // Exclusive/non-recursive: existing directories and symlinks are not reused.
+  io.mkdirSync(directory, { mode: 0o700 });
+  const created = [];
+  try {
+    for (const [name, content] of files) {
+      const path = join(directory, name);
+      const descriptor = io.openSync(path, 'wx', 0o600);
+      created.push(path); // Own the file even if a later write fails partially.
+      try { io.writeFileSync(descriptor, `${content}\n`); }
+      finally { io.closeSync(descriptor); }
+    }
+  } catch (error) {
+    const failures = removeFailedInstallation(directory, created, io);
+    if (failures.length) {
+      throw new AggregateError([error, ...failures], 'Setup write failed and cleanup was incomplete');
+    }
+    throw error;
+  }
+}

package/src/setup/setup-questions.mjs

@@ -0,0 +1,62 @@
+import { existsSync, lstatSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { defaultInstallationDirectory } from '../cli/cli-environment.mjs';
+import { validateConfiguration } from '../config/config-validation.mjs';
+
+const fixtureGrant = [{ runtimeId: 'workstation', tokenSha256: '0'.repeat(64) }];
+
+export async function askValidated(ask, out, prompt, fallback, validate) {
+  while (true) {
+    const suffix = fallback ? ` [${fallback}]` : '';
+    const answer = (await ask(`${prompt}${suffix}: `)).trim() || fallback;
+    try { return validate(answer); }
+    catch { out(`Invalid ${prompt.toLowerCase()}. Please try again.`); }
+  }
+}
+
+export function validateSetupDirectory(value) {
+  if (!value || /[\x00-\x1f\x7f]/.test(value)) throw new Error('Choose an output directory');
+  const path = resolve(value);
+  if (existsSync(path)) throw new Error('The output directory must be new');
+  const parent = lstatSync(dirname(path));
+  if (!parent.isDirectory() || parent.isSymbolicLink()) throw new Error('The parent must be an existing directory');
+  return path;
+}
+
+function validateAnswer(field, value) {
+  const baseline = { publicOrigin: 'https://socket.example.invalid', stateDirectory: './state', runtimeGrants: fixtureGrant };
+  const candidate = field === 'runtimeId'
+    ? { ...baseline, runtimeGrants: [{ ...fixtureGrant[0], runtimeId: value }] }
+    : { ...baseline, [field]: value };
+  validateConfiguration(candidate);
+  return value;
+}
+
+export async function collectSetupAnswers({ ask, out, homeDirectory }) {
+  const output = await askValidated(ask, out, 'New private installation directory',
+    defaultInstallationDirectory(homeDirectory), validateSetupDirectory);
+  const origin = await askValidated(ask, out, 'HTTPS server origin', '', (value) => validateAnswer('publicOrigin', value));
+  const runtimeId = await askValidated(ask, out, 'Runtime identifier', 'workstation', (value) => validateAnswer('runtimeId', value));
+  const port = await askValidated(ask, out, 'Local listener port', '8788', (value) => {
+    if (!/^\d{4,5}$/.test(value)) throw new Error('Invalid port');
+    return validateAnswer('port', Number(value));
+  });
+  return { output, origin, runtimeId, port };
+}
+
+export async function collectProxyAnswers({ ask, out }) {
+  const proxy = await askValidated(ask, out, 'HTTPS proxy (nginx, apache, or none for existing setup)', 'none', (value) => {
+    if (!['nginx', 'apache', 'none'].includes(value)) throw new Error('Unknown proxy');
+    return value;
+  });
+  if (proxy === 'none') return { proxy };
+  out('The following paths refer to your existing TLS certificate and key; their contents are never copied.');
+  const certificatePath = await askValidated(ask, out, 'Full-chain certificate path', '', validateCertificatePath);
+  const keyPath = await askValidated(ask, out, 'TLS private key path', '', validateCertificatePath);
+  return { proxy, certificatePath, keyPath };
+}
+
+function validateCertificatePath(value) {
+  if (!isAbsolute(value) || /[\x00-\x1f\x7f]/.test(value)) throw new Error('An absolute path is required');
+  return value;
+}

package/src/setup/setup-wizard.mjs

@@ -0,0 +1,50 @@
+import { join } from 'node:path';
+import { createInstallation, prepareInstallation } from './setup.mjs';
+import { collectSetupAnswers, collectProxyAnswers } from './setup-questions.mjs';
+import { renderDeploymentPlan, writeDeploymentPlan } from '../deployment/deployment-plan.mjs';
+import { printInstallation } from '../cli/cli-output.mjs';
+import { checkPublicEndpoint } from '../cli/doctor.mjs';
+
+const confirmed = (value) => /^(y|yes)$/i.test(value.trim());
+
+/** Every OS integration is prepared as files; only an explicit doctor answer contacts HTTPS. */
+export async function runSetupWizard({ ask, out, homeDirectory, platform, username, nodePath, entryPath,
+  pairingOutput = {},
+  create = createInstallation, render = renderDeploymentPlan, writePlan = writeDeploymentPlan,
+  checkEndpoint = checkPublicEndpoint }) {
+  out('ABot Socket setup — prepare a private installation on your own server.');
+  out('This wizard writes local files. It does not install dependencies, alter DNS/TLS, or activate services.');
+  const options = await collectSetupAnswers({ ask, out, homeDirectory });
+  let deployment;
+  if (platform === 'linux' && username !== 'root') {
+    const proxy = await collectProxyAnswers({ ask, out });
+    deployment = { ...proxy, platform, username, nodePath, entryPath,
+      configPath: join(options.output, 'config.json'), config: prepareInstallation(options).config,
+      output: join(options.output, 'deployment') };
+    render(deployment); // Reject unsafe deployment values before creating private state.
+  } else {
+    out('Linux service files require setup as an unprivileged Linux user. Foreground operation is available separately.');
+  }
+  out(`Installation: ${JSON.stringify(options.output)}`);
+  out(`Server: ${options.origin}; runtime: ${options.runtimeId}; listener: 127.0.0.1:${options.port}`);
+  out(deployment ? 'A reviewable systemd/proxy plan will also be written, without activating it.' : 'No service or proxy files will be written.');
+  if (!confirmed(await ask('Create these files? [y/N]: '))) {
+    out('Setup cancelled; no installation files were created.');
+    return 0;
+  }
+  const result = create(options);
+  printInstallation(result, out, pairingOutput);
+  if (deployment) {
+    writePlan(deployment);
+    out(`Review the deployment instructions in ${JSON.stringify(deployment.output)} before applying them.`);
+  }
+  out('The relay is not started by setup. Connect its runtime using the private runtime-connection.json details.');
+  out('After the service and HTTPS are ready, use abot-socket doctor, then abot-socket pair for fresh details.');
+  if (confirmed(await ask('Check the public HTTPS endpoint now? [y/N]: '))) {
+    const report = await checkEndpoint(options.origin);
+    out(report.ok ? 'HTTPS relay health check passed.' : `HTTPS relay check: ${report.code}.`);
+    out('Runtime connectivity is verified after pairing in the app; it was not tested by this health check.');
+    return report.ok ? 0 : 1;
+  }
+  return 0;
+}