@abot-ai/socket 0.0.0-stage → 0.1.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,31 @@
+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 }) {
+  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(),
+    })) });
+  }
+  return jsonResponse(res, 404, { error: 'not_found' });
+}

package/src/transport/server.mjs

@@ -0,0 +1,165 @@
+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 { 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 notifications;
+  try {
+    auth = new AuthService({ 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, 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 });
+    } 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() });
+  };
+
+  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(); });
+      });
+    }),
+  };
+}

package/src/transport/transport-limits.mjs

@@ -0,0 +1,85 @@
+export class WindowLimiter {
+  constructor({ limit, windowMs, capacity = 1024, now = Date.now }) {
+    this.limit = limit;
+    this.windowMs = windowMs;
+    this.capacity = capacity;
+    this.now = now;
+    this.entries = new Map();
+  }
+  allow(key) {
+    this.prune();
+    const entry = this.entries.get(key);
+    if (entry) {
+      if (entry.count >= this.limit) return false;
+      entry.count += 1;
+      return true;
+    }
+    if (this.entries.size >= this.capacity) return false;
+    this.entries.set(key, { count: 1, until: this.now() + this.windowMs });
+    return true;
+  }
+  prune() {
+    const now = this.now();
+    for (const [key, value] of this.entries) if (value.until <= now) this.entries.delete(key);
+  }
+}
+
+export function bearerToken(req) {
+  const value = req.headers.authorization;
+  return typeof value === 'string' && /^Bearer [A-Za-z0-9_-]{43,128}$/.test(value)
+    ? value.slice(7) : '';
+}
+
+export function sameAuthority(req, origin) {
+  if (req.headers.host !== origin.host) return false;
+  return req.headers.origin === undefined || req.headers.origin === origin.origin;
+}
+
+// Listener is loopback-only. The local reverse proxy MUST strip/overwrite this
+// header using its verified client address, never copy arbitrary forwarded input.
+export function trustedClientAddress(req) {
+  if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(req.socket.remoteAddress)) return null;
+  const address = req.headers['x-socket-client-ip'];
+  return typeof address === 'string' && isIP(address) ? address : null;
+}
+
+export function jsonResponse(res, status, body) {
+  const encoded = JSON.stringify(body);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'pragma': 'no-cache',
+    'x-content-type-options': 'nosniff',
+    'content-security-policy': "default-src 'none'; frame-ancestors 'none'",
+    'referrer-policy': 'no-referrer',
+    'content-length': Buffer.byteLength(encoded),
+  });
+  res.end(encoded);
+}
+
+export async function readJson(req, maxBytes = 4096) {
+  if ((req.headers['content-type'] ?? '').split(';')[0].trim() !== 'application/json') {
+    throw Object.assign(new Error('invalid_content_type'), { code: 'invalid_content_type', status: 415 });
+  }
+  const declared = req.headers['content-length'];
+  if (declared !== undefined && (!/^\d+$/.test(declared) || Number(declared) > maxBytes)) {
+    throw Object.assign(new Error('payload_too_large'), { code: 'payload_too_large', status: 413 });
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > maxBytes) {
+      throw Object.assign(new Error('payload_too_large'), { code: 'payload_too_large', status: 413 });
+    }
+    chunks.push(chunk);
+  }
+  try {
+    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!value || Array.isArray(value) || typeof value !== 'object') throw new Error();
+    return value;
+  } catch {
+    throw Object.assign(new Error('invalid_json'), { code: 'invalid_json', status: 400 });
+  }
+}
+import { isIP } from 'node:net';