@abot-ai/socket 0.0.0-stage → 0.2.0

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;
+}

package/src/setup/setup.mjs

@@ -0,0 +1,42 @@
+import { randomBytes } from 'node:crypto';
+import { resolve, join } from 'node:path';
+import { digestToken } from '../auth/runtime-credentials.mjs';
+import { validateConfiguration } from '../config/config-validation.mjs';
+import { writePrivateInstallation } from './setup-files.mjs';
+import { AuthService } from '../auth/auth.mjs';
+
+export function prepareInstallation(options) {
+  const runtimeToken = randomBytes(32).toString('base64url');
+  const config = validateConfiguration({
+    publicOrigin: options.origin,
+    port: options.port ?? 8788,
+    stateDirectory: './state',
+    runtimeGrants: [{ runtimeId: options.runtimeId, tokenSha256: digestToken(runtimeToken),
+      allowedModes: ['ask'] }],
+  });
+  const bridge = new URL('/agent-bridge', config.publicOrigin);
+  bridge.protocol = 'wss:';
+  return {
+    config,
+    runtimeConnection: { runtimeId: config.runtimeGrants[0].runtimeId,
+      agentBridgeUrl: bridge.href, runtimeToken },
+  };
+}
+
+// Local operator only. No files, accounts, servers, or mail are modified elsewhere.
+export function createInstallation(options) {
+  if (typeof options.output !== 'string' || !options.output.trim()) {
+    throw new Error('Choose a new private output directory');
+  }
+  const bundle = prepareInstallation(options);
+  const directory = resolve(options.output);
+  writePrivateInstallation(directory, bundle);
+  // A failed state initialization leaves the private installation intact for
+  // operator diagnosis; a later `pair` command can issue its first pairing.
+  const auth = new AuthService({ stateDirectory: join(directory, 'state') });
+  let pairing;
+  try { pairing = auth.createPairing(); } finally { auth.close(); }
+  return { directory, configPath: join(directory, 'config.json'),
+    runtimeConnectionPath: join(directory, 'runtime-connection.json'),
+    pairing: { serverUrl: bundle.config.publicOrigin, ...pairing } };
+}

package/src/transport/http-api.mjs

@@ -0,0 +1,32 @@
+import { bearerToken, jsonResponse, readJson } from './transport-limits.mjs';
+import { clientCapabilities } from '../cli/client-capabilities.mjs';
+import { handleNotificationHttp } from '../notifications/notification-http.mjs';
+
+export async function handleHttpApi(req, res, { auth, runtimeGrants, relay, sourceId, notifications, ownership }) {
+  const path = req.url;
+  if (req.method === 'GET' && path === '/health') return jsonResponse(res, 200, { ok: true, version: 2 });
+  if (req.method === 'POST' && path === '/v2/pairing/redeem') {
+    return jsonResponse(res, 200, auth.redeemPairing(await readJson(req), sourceId));
+  }
+  const principal = auth.authenticate(bearerToken(req));
+  if (!principal) return jsonResponse(res, 401, { error: 'unauthorized' });
+  if (notifications && await handleNotificationHttp(req, res, { principal, notifications, runtimeGrants })) return;
+  if (req.method === 'GET' && path === '/v2/auth/sessions') {
+    return jsonResponse(res, 200, { sessions: auth.listSessions(principal) });
+  }
+  if (req.method === 'POST' && path === '/v2/auth/logout') {
+    auth.revoke(principal, principal.sessionId);
+    return jsonResponse(res, 200, { ok: true });
+  }
+  if (req.method === 'DELETE' && /^\/v2\/auth\/sessions\/[A-Za-z0-9_-]{16,128}$/.test(path)) {
+    return jsonResponse(res, 200, { revoked: auth.revoke(principal, path.split('/').at(-1)) });
+  }
+  if (req.method === 'GET' && path === '/v2/runtimes') {
+    const snapshots = relay.runtimeSnapshot(runtimeGrants.map((grant) => grant.runtimeId));
+    return jsonResponse(res, 200, { runtimes: runtimeGrants.map(({ runtimeId, allowedModes }, index) => ({
+      ...snapshots[index], runtimeId, allowedModes,
+      capabilities: clientCapabilities({ ownership, runtime: snapshots[index] }),
+    })) });
+  }
+  return jsonResponse(res, 404, { error: 'not_found' });
+}

package/src/transport/server.mjs

@@ -0,0 +1,175 @@
+import { createServer as createHttpServer } from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import { WebSocketServer, WebSocket } from 'ws';
+import { AuthService } from '../auth/auth.mjs';
+import { Relay } from '../relay/relay.mjs';
+import { RequestOwnershipStore } from '../relay/request-ownership-store.mjs';
+import { handleHttpApi } from './http-api.mjs';
+import { WindowLimiter, sameAuthority, jsonResponse, bearerToken, trustedClientAddress } from './transport-limits.mjs';
+import { resolveRuntimeCredential, validateRuntimeGrants } from '../auth/runtime-credentials.mjs';
+import { clientCapabilities } from '../cli/client-capabilities.mjs';
+import { AuthDatabase } from '../auth/auth-database.mjs';
+import { NotificationService } from '../notifications/notification-service.mjs';
+import { createNotificationDelivery } from '../notifications/notification-delivery.mjs';
+
+const MAX_FRAME = 16 * 1024 * 1024;
+const MAX_BUFFER = 32 * 1024 * 1024;
+const MAX_CONNECTIONS = 32;
+
+export function createSocketServer({ stateDirectory, runtimeGrants: grants,
+  publicOrigin, tls, now = Date.now, notifications: notificationConfig, notificationDelivery }) {
+  const origin = new URL(publicOrigin);
+  if (origin.protocol !== 'https:' || origin.origin !== publicOrigin) throw new Error('HTTPS origin required');
+  const runtimeGrants = validateRuntimeGrants(grants);
+  const database = new AuthDatabase(stateDirectory);
+  let auth;
+  let ownership;
+  let notifications;
+  try {
+    auth = new AuthService({ database, now });
+    ownership = new RequestOwnershipStore({ database, now });
+    notifications = new NotificationService({ database, now,
+      delivery: notificationDelivery ?? createNotificationDelivery(notificationConfig?.delivery ?? { type: 'disabled' }) });
+  } catch (error) {
+    auth?.close(); database.close(); throw error;
+  }
+  const peers = new Map();
+  const upgrades = new WindowLimiter({ limit: 30, windowMs: 60_000, now });
+  const requests = new WindowLimiter({ limit: 120, windowMs: 60_000, now });
+  const close = (peer, code = 1008, reason = 'Access denied') => {
+    if (peer.readyState === WebSocket.OPEN) peer.close(code, reason);
+    else peer.terminate();
+  };
+  const send = (peer, payload) => {
+    const context = peers.get(peer);
+    if (context?.role === 'client' && !auth.authenticate(context.token)) {
+      close(peer); return false;
+    }
+    if (peer.readyState !== WebSocket.OPEN) return false;
+    let encoded;
+    try { encoded = JSON.stringify(payload); } catch { return false; }
+    if (Buffer.byteLength(encoded) > MAX_FRAME || peer.bufferedAmount + Buffer.byteLength(encoded) > MAX_BUFFER) {
+      close(peer, 1013, 'Receiver capacity exceeded'); return false;
+    }
+    peer.send(encoded, (error) => { if (error) peer.terminate(); });
+    return true;
+  };
+  const relay = new Relay({ now, send, close, ownership,
+    isClientAuthorized: client => {
+      const context = peers.get(client.peer);
+      if (context?.role !== 'client') return false;
+      const principal = auth.authenticate(context.token);
+      return principal?.subject === client.subject && principal.sessionId === client.sessionId;
+    },
+    observeRequest: (identity, body) => notifications.observe(identity, body) });
+  const authorityAccepted = (req) => sameAuthority(req, origin) &&
+    (Boolean(req.socket.encrypted) || req.headers['x-forwarded-proto'] === 'https');
+  const handler = async (req, res) => {
+    try {
+      if (!authorityAccepted(req)) return jsonResponse(res, 403, { error: 'forbidden' });
+      const sourceId = trustedClientAddress(req);
+      if (!sourceId) return jsonResponse(res, 403, { error: 'untrusted_proxy' });
+      if (!requests.allow(sourceId)) return jsonResponse(res, 429, { error: 'rate_limited' });
+      await handleHttpApi(req, res, { auth, runtimeGrants, relay, sourceId, notifications, ownership });
+    } catch (error) {
+      const status = [400, 401, 403, 404, 409, 413, 415, 429, 503].includes(error.status) ? error.status : 500;
+      const code = status === 500 ? 'internal_error' :
+        (/^[a-z_]{1,64}$/.test(error.code ?? '') ? error.code : 'request_failed');
+      if (!res.headersSent && !res.destroyed) jsonResponse(res, status, { error: code });
+    }
+  };
+  const server = tls ? createHttpsServer(tls, handler) : createHttpServer(handler);
+  server.requestTimeout = 15_000;
+  server.headersTimeout = 5_000;
+  server.keepAliveTimeout = 5_000;
+  server.maxHeadersCount = 32;
+  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME,
+    perMessageDeflate: false, clientTracking: true });
+  const reject = (socket, status = 401) => socket.end(
+    `HTTP/1.1 ${status} Rejected\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+
+  const acceptClient = (peer, context, token) => {
+    const principal = auth.authenticate(token);
+    if (!principal) { close(peer); return; }
+    context.role = 'client'; context.token = token; context.sessionId = principal.sessionId;
+    const admitted = relay.attachClient(peer, { ...principal,
+      allowedRuntimeIds: runtimeGrants.map((grant) => grant.runtimeId) });
+    if (admitted === false) { close(peer, 1013, 'Capacity exceeded'); return; }
+    send(peer, { type: 'authenticated', sessionId: principal.sessionId, expiresAt: principal.expiresAt,
+      capabilities: clientCapabilities({ ownership }) });
+  };
+
+  server.on('upgrade', (req, socket, head) => {
+    socket.on('error', () => socket.destroy());
+    if (!authorityAccepted(req)) return reject(socket, 403);
+    const sourceId = trustedClientAddress(req);
+    if (!sourceId) return reject(socket, 403);
+    if (peers.size >= MAX_CONNECTIONS || !upgrades.allow(sourceId)) {
+      return reject(socket, 429);
+    }
+    const isRuntime = req.url === '/agent-bridge';
+    if (!isRuntime && req.url !== '/v2/realtime') return reject(socket, 404);
+    const grant = isRuntime ? resolveRuntimeCredential(req.headers.authorization, runtimeGrants) : null;
+    if (isRuntime && !grant) return reject(socket);
+    const clientToken = isRuntime ? '' : bearerToken(req);
+    if (!isRuntime && !auth.authenticate(clientToken)) return reject(socket);
+    wss.handleUpgrade(req, socket, head, (peer) => {
+      const context = { role: isRuntime ? 'runtime' : 'client', alive: true };
+      peers.set(peer, context);
+      peer.on('error', () => peer.terminate());
+      peer.on('close', () => { relay.disconnect(peer); peers.delete(peer); });
+      peer.on('pong', () => { context.alive = true; });
+      if (grant && relay.attachRuntime(peer, grant) === false) close(peer, 1008, 'Runtime unavailable');
+      if (!isRuntime) acceptClient(peer, context, clientToken);
+      peer.on('message', (data, binary) => {
+        if (binary) { close(peer, 1008, 'Text messages required'); return; }
+        let message;
+        try { message = JSON.parse(data.toString('utf8')); } catch { close(peer); return; }
+        if (!message || Array.isArray(message) || typeof message !== 'object') { close(peer); return; }
+        try {
+          if (context.role === 'runtime') { relay.runtimeMessage(peer, message); return; }
+          if (!auth.authenticate(context.token)) { close(peer); return; }
+          relay.clientMessage(peer, message);
+        } catch { close(peer, 1008, 'Invalid message'); }
+      });
+    });
+  });
+
+  const unsubscribe = auth.subscribeRevocations((sessionId) => {
+    notifications.revoke(sessionId);
+    for (const [peer, context] of peers) if (context.sessionId === sessionId) close(peer);
+  });
+  const sweep = setInterval(() => {
+    auth.prune(); relay.prune(); upgrades.prune(); requests.prune();
+    for (const [peer, context] of peers) {
+      if (context.role === 'client' && !auth.authenticate(context.token)) close(peer);
+    }
+  }, 1_000);
+  sweep.unref();
+  const heartbeat = setInterval(() => {
+    for (const [peer, context] of peers) {
+      if (!context.alive) { peer.terminate(); continue; }
+      context.alive = false;
+      if (peer.readyState === WebSocket.OPEN) peer.ping();
+    }
+  }, 30_000);
+  heartbeat.unref();
+  notifications.start();
+  let stopped = false;
+  return {
+    listen: (port = 8788) => new Promise((resolve, rejectListen) => {
+      server.once('error', rejectListen);
+      server.listen(port, '127.0.0.1', () => { server.off('error', rejectListen); resolve(server.address()); });
+    }),
+    close: () => new Promise((resolve) => {
+      if (stopped) { resolve(); return; }
+      stopped = true;
+      clearInterval(sweep); clearInterval(heartbeat); unsubscribe();
+      for (const peer of peers.keys()) peer.terminate();
+      wss.close(); server.closeAllConnections();
+      server.close(() => {
+        void notifications.close().finally(() => { auth.close(); database.close(); resolve(); });
+      });
+    }),
+  };
+}