@abot-ai/socket 0.0.0-stage → 0.1.0

package/src/cli/cli-output.mjs

@@ -0,0 +1,35 @@
+import { renderPairingQr } from '../pairing/pairing-qr.mjs';
+
+function canDisplayPairingQr({ isTTY, term }) {
+  return isTTY === true && term !== 'dumb';
+}
+
+function printTerminalPairing(pairing, out, { columns, renderQr = renderPairingQr }) {
+  try {
+    const qr = renderQr(pairing, { columns });
+    if (!qr) {
+      out('The terminal is too narrow for this QR. Widen it and run pair again, or use the details below.');
+      return;
+    }
+    out('Scan this QR inside ABot, then confirm your server address. Keep it private.');
+    out(qr);
+  } catch {
+    // Rendering cannot replace an issued challenge or hide the manual path.
+    out('QR display is unavailable. Use the same pairing details below.');
+  }
+}
+
+export function printPairing(pairing, out = console.log, options = {}) {
+  if (canDisplayPairingQr(options)) printTerminalPairing(pairing, out, options);
+  out('Pair your app: enter the 6-digit code, then the server URL and temporary pairing key.');
+  out(JSON.stringify(pairing, null, 2));
+  out('One use, valid for 5 minutes. If needed, run abot-socket pair again for fresh details.');
+}
+
+export function printInstallation(result, out = console.log, options = {}) {
+  out(`Created private installation files in ${JSON.stringify(result.directory)}`);
+  out('Keep runtime-connection.json private and transfer it only to its runtime computer.');
+  out(`Configuration: ${JSON.stringify(result.configPath)}`);
+  out('For a custom location, pass --config <that-file> to future commands.');
+  printPairing(result.pairing, out, options);
+}

package/src/cli/cli.mjs

@@ -0,0 +1,58 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInstallation } from '../setup/setup.mjs';
+import { parseSetupArguments } from './cli-arguments.mjs';
+import { loadConfiguration } from '../config/config.mjs';
+import { AuthService } from '../auth/auth.mjs';
+import { USAGE } from './cli-help.mjs';
+import { printInstallation, printPairing } from './cli-output.mjs';
+import { createReviewDemoInstallation, parseReviewDemoArguments } from '../review/review-demo-setup.mjs';
+
+export function runCli(args, { env = process.env, out = console.log, error = console.error, pairingOutput = {} } = {}) {
+  const [command, ...rest] = args;
+  if (!command || command === '--help' || command === 'help') { out(USAGE); return 0; }
+  try {
+    if (command === 'review-setup') {
+      const result = createReviewDemoInstallation(parseReviewDemoArguments(rest));
+      out(`Created isolated review demo files in ${JSON.stringify(result.directory)}.`);
+      out(`Socket and portal configuration: ${JSON.stringify(result.configPath)}`);
+      out(`Private reviewer credentials: ${JSON.stringify(result.reviewAccessPath)}`);
+      out(`Demo runtime connection: ${JSON.stringify(result.runtimeConnectionPath)}`);
+      out('No service or runtime was started. Use a separate runtime workspace containing only synthetic data.');
+      return 0;
+    }
+    if (command === 'setup') {
+      const result = createInstallation(parseSetupArguments(rest));
+      printInstallation(result, out, pairingOutput);
+      return 0;
+    }
+    if (command === 'check-config' && rest.length === 0) {
+      loadConfiguration(env);
+      out('Configuration is valid locally. HTTPS, state storage and runtime reachability were not tested.');
+      return 0;
+    }
+    if (['pair', 'devices'].includes(command) && rest.length === 0 ||
+        command === 'revoke' && rest.length === 1 && /^[A-Za-z0-9_-]{16,128}$/.test(rest[0])) {
+      const config = loadConfiguration(env);
+      const auth = new AuthService({ stateDirectory: config.stateDirectory });
+      try {
+        if (command === 'pair') printPairing({ serverUrl: config.publicOrigin, ...auth.createPairing() }, out, pairingOutput);
+        if (command === 'devices') out(JSON.stringify({ devices: auth.listDevices() }, null, 2));
+        if (command === 'revoke') out(JSON.stringify({ revoked: auth.revokeDevice(rest[0]) }));
+      } finally { auth.close(); }
+      return 0;
+    }
+    error('Unknown command or arguments. Run with --help.');
+    return 2;
+  } catch {
+    // Never echo provider, filesystem or parser error values into operator logs.
+    error(command === 'setup'
+      ? 'Setup failed. Check arguments and private output/state permissions. If installation files exist, use pair to retry without overwriting them.'
+      : 'Command failed. Check the private configuration, state permissions, HTTPS origin and runtime grants.');
+    return 1;
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  process.exitCode = runCli(process.argv.slice(2));
+}

package/src/cli/client-capabilities.mjs

@@ -0,0 +1,4 @@
+/** Socket-owned API support; runtime identity/features remain separately scoped. */
+export function clientCapabilities() {
+  return { cancel: false, durableApprovals: false, sessionMutation: true, notifications: true };
+}

package/src/cli/doctor.mjs

@@ -0,0 +1,106 @@
+import { request as httpsRequest } from 'node:https';
+
+const MAX_BODY_BYTES = 4096;
+const MAX_ORIGIN_LENGTH = 2048;
+const DEADLINE_MS = 5000;
+
+function parseDoctorOrigin(value) {
+  if (typeof value !== 'string' || value.length > MAX_ORIGIN_LENGTH) {
+    throw new TypeError('Doctor requires a canonical HTTPS origin');
+  }
+  let origin;
+  try { origin = new URL(value); } catch {
+    throw new TypeError('Doctor requires a canonical HTTPS origin');
+  }
+  if (origin.protocol !== 'https:' || origin.origin !== value) {
+    throw new TypeError('Doctor requires a canonical HTTPS origin');
+  }
+  return origin;
+}
+
+function hasOversizedDeclaredBody(response) {
+  const length = response.headers['content-length'];
+  if (length === undefined) return false;
+  if (typeof length !== 'string' || !/^\d+$/.test(length)) return true;
+  return Number(length) > MAX_BODY_BYTES;
+}
+
+function isRelayHealthResponse(chunks) {
+  try {
+    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!value || Array.isArray(value) || typeof value !== 'object') return false;
+    return value.ok === true && value.version === 2;
+  } catch { return false; }
+}
+
+/** Explicit public TLS check only. It never authenticates or probes a runtime. */
+export async function checkPublicEndpoint(publicOrigin, {
+  requestImpl = httpsRequest, timeoutMs = DEADLINE_MS,
+} = {}) {
+  const origin = parseDoctorOrigin(publicOrigin);
+  if (typeof requestImpl !== 'function') throw new TypeError('An HTTPS request function is required');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > DEADLINE_MS) {
+    throw new TypeError('Doctor deadline must be between 1 and 5000 milliseconds');
+  }
+  return new Promise((resolve) => {
+    let request;
+    let response;
+    let settled = false;
+    let bytes = 0;
+    const chunks = [];
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      if (response) {
+        response.off('data', receiveData);
+        response.off('end', receiveEnd);
+        response.destroy();
+      }
+      request?.destroy();
+      resolve({ ok: code === 'reachable', code, runtimeVerified: false });
+    };
+    const receiveData = (chunk) => {
+      if (settled) return;
+      if (!Buffer.isBuffer(chunk)) { finish('unexpected_response'); return; }
+      bytes += chunk.length;
+      if (bytes > MAX_BODY_BYTES) { finish('unexpected_response'); return; }
+      chunks.push(chunk);
+    };
+    const receiveEnd = () => {
+      if (response.complete === false) { finish('unexpected_response'); return; }
+      finish(isRelayHealthResponse(chunks) ? 'reachable' : 'unexpected_response');
+    };
+    const deadline = setTimeout(() => finish('timeout'), timeoutMs);
+    const receiveResponse = (incoming) => {
+      response = incoming;
+      response.on('error', () => finish('https_unavailable'));
+      response.on('aborted', () => finish('https_unavailable'));
+      if (settled) { response.destroy(); return; }
+      if (response.statusCode >= 300 && response.statusCode < 400) {
+        finish('redirect_rejected'); return;
+      }
+      if (response.statusCode !== 200) { finish('unexpected_response'); return; }
+      const contentType = response.headers['content-type'];
+      if (typeof contentType !== 'string' || contentType.split(';')[0].trim().toLowerCase() !== 'application/json') {
+        finish('unexpected_response'); return;
+      }
+      if (hasOversizedDeclaredBody(response)) { finish('unexpected_response'); return; }
+      response.on('data', receiveData);
+      response.once('end', receiveEnd);
+    };
+    try {
+      request = requestImpl(new URL('/health', origin), {
+        method: 'GET', headers: { Accept: 'application/json' },
+        rejectUnauthorized: true, agent: false, maxHeaderSize: 8192,
+      }, receiveResponse);
+      request.on('error', () => finish('https_unavailable'));
+      request.on('upgrade', (_incoming, socket) => {
+        socket.destroy();
+        finish('unexpected_response');
+      });
+      if (settled) { request.destroy(); return; }
+      request.end();
+    } catch { finish('https_unavailable'); }
+  });
+}

package/src/config/config-validation.mjs

@@ -0,0 +1,41 @@
+import { validateRuntimeGrants } from '../auth/runtime-credentials.mjs';
+import { validateNotificationDeliveryConfiguration } from '../notifications/notification-delivery.mjs';
+
+function isCanonicalHttpsOrigin(value) {
+  if (typeof value !== 'string') return false;
+  try {
+    const origin = new URL(value);
+    return origin.protocol === 'https:' && origin.origin === value;
+  } catch { return false; }
+}
+
+/** Pure preflight: no listener, credentials or state are created here. */
+export function validateConfiguration(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('Invalid configuration');
+  }
+  if (!isCanonicalHttpsOrigin(config.publicOrigin)) {
+    throw new Error('Configure a canonical HTTPS publicOrigin');
+  }
+  const port = config.port ?? 8788;
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new Error('Invalid listener port');
+  }
+  if (typeof config.stateDirectory !== 'string' || !config.stateDirectory.trim() ||
+      config.stateDirectory.length > 4096 || /[\x00-\x1f\x7f]/.test(config.stateDirectory)) {
+    throw new Error('Configure a private stateDirectory');
+  }
+  if (Object.hasOwn(config, 'mail') || Object.hasOwn(config, 'allowedEmail')) {
+    throw new Error('Email configuration is unsupported; create a pairing installation');
+  }
+  const notifications = config.notifications ?? {};
+  if (!notifications || typeof notifications !== 'object' || Array.isArray(notifications) ||
+      Object.keys(notifications).some(key => key !== 'delivery')) {
+    throw new Error('Invalid notification configuration');
+  }
+  return {
+    publicOrigin: config.publicOrigin, port, stateDirectory: config.stateDirectory,
+    runtimeGrants: validateRuntimeGrants(config.runtimeGrants),
+    notifications: { delivery: validateNotificationDeliveryConfiguration(notifications.delivery) },
+  };
+}

package/src/config/config.mjs

@@ -0,0 +1,57 @@
+import { openSync, closeSync, fstatSync, readSync, constants } from 'node:fs';
+import { validateConfiguration } from './config-validation.mjs';
+import { dirname, resolve } from 'node:path';
+
+const MAX_CONFIG_BYTES = 32_768;
+
+function selectEnvironmentValue(env, primary, legacy) {
+  const preferred = env[primary];
+  const fallback = env[legacy];
+  if (preferred && fallback && preferred !== fallback) {
+    throw new Error(`Conflicting ${primary} and ${legacy} settings`);
+  }
+  const value = preferred || fallback;
+  if (value !== undefined && typeof value !== 'string') {
+    throw new Error(`Invalid ${primary} setting`);
+  }
+  return value;
+}
+
+function isPrivateConfigurationFile(stat) {
+  if (!stat.isFile()) return false;
+  if (stat.size > MAX_CONFIG_BYTES) return false;
+  return (stat.mode & 0o077) === 0;
+}
+
+export function readPrivateConfiguration(path) {
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!isPrivateConfigurationFile(fstatSync(descriptor))) throw new Error();
+    const buffer = Buffer.alloc(MAX_CONFIG_BYTES + 1);
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const count = readSync(descriptor, buffer, bytes, buffer.length - bytes, null);
+      if (count === 0) break;
+      bytes += count;
+    }
+    if (bytes > MAX_CONFIG_BYTES) throw new Error();
+    return JSON.parse(buffer.toString('utf8', 0, bytes));
+  } catch {
+    // Filesystem and JSON errors may contain paths or configuration values.
+    throw new Error('Configuration must be a small private file with mode 0600 and valid JSON');
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+export function loadConfiguration(env = process.env) {
+  const path = selectEnvironmentValue(env, 'ABOT_SOCKET_CONFIG', 'SOCKET_V2_CONFIG');
+  if (!path) throw new Error('Set ABOT_SOCKET_CONFIG to a private JSON configuration file');
+  const config = validateConfiguration(readPrivateConfiguration(path));
+  const delivery = config.notifications.delivery;
+  if (delivery.type === 'fcm') {
+    delivery.serviceAccountFile = resolve(dirname(resolve(path)), delivery.serviceAccountFile);
+  }
+  return { ...config, stateDirectory: resolve(dirname(resolve(path)), config.stateDirectory) };
+}

package/src/deployment/deployment-command.mjs

@@ -0,0 +1,42 @@
+import { realpathSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { loadConfiguration } from '../config/config.mjs';
+import { writeDeploymentPlan } from './deployment-plan.mjs';
+
+const flags = new Map([['--output', 'output'], ['--proxy', 'proxy'], ['--user', 'username'],
+  ['--certificate', 'certificatePath'], ['--private-key', 'keyPath']]);
+
+export function parseDeploymentArguments(args) {
+  const result = {};
+  for (let i = 0; i < args.length; i += 2) {
+    const name = flags.get(args[i]);
+    const value = args[i + 1];
+    if (!name || Object.hasOwn(result, name) || !value || value.startsWith('--')) {
+      throw new Error('Invalid deployment options');
+    }
+    result[name] = value;
+  }
+  if (!result.output || !result.proxy) throw new Error('Deployment requires output and proxy selection');
+  result.output = resolve(result.output);
+  return result;
+}
+
+export function deploymentRuntimePaths() {
+  return { nodePath: realpathSync(process.execPath),
+    entryPath: fileURLToPath(new URL('../../bin/abot-socket.mjs', import.meta.url)) };
+}
+
+export function prepareDeployment(args, { env, out, platform = process.platform, username = userInfo().username }) {
+  const options = parseDeploymentArguments(args);
+  if (options.username && options.username !== username) {
+    throw new Error('Generate deployment files as the installation owner');
+  }
+  const config = loadConfiguration(env);
+  const output = writeDeploymentPlan({ ...options, ...deploymentRuntimePaths(), config,
+    configPath: resolve(env.ABOT_SOCKET_CONFIG || env.SOCKET_V2_CONFIG), platform, username });
+  out(`Deployment files prepared in ${JSON.stringify(options.output)}. Review the instructions before applying them.`);
+  out('No service, certificate, proxy configuration or package was installed.');
+  return output;
+}

package/src/deployment/deployment-input.mjs

@@ -0,0 +1,76 @@
+import { posix } from 'node:path';
+import { validateConfiguration } from '../config/config-validation.mjs';
+
+function requireLinuxPlatform(platform) {
+  if (platform !== 'linux') throw new Error('Deployment plans target Linux with systemd only');
+}
+
+function requireServiceUsername(username) {
+  if (typeof username !== 'string' || !/^[a-z_][a-z0-9_-]{0,31}$/.test(username)) {
+    throw new Error('Choose an unprivileged Linux service username');
+  }
+  if (username === 'root') throw new Error('The relay service must not run as root');
+  return username;
+}
+
+function requireDeploymentPath(value, label) {
+  // Spaces and percent signs are handled by each target syntax. Other shell,
+  // proxy-variable and control characters are deliberately unsupported.
+  if (typeof value !== 'string' || value.length > 4096 ||
+      !/^\/[A-Za-z0-9_./ %+-]+$/.test(value) || value === '/' ||
+      posix.normalize(value) !== value || value.endsWith('/')) {
+    throw new Error(`${label} requires an absolute normalized path containing letters, numbers, spaces, . _ - + or %`);
+  }
+  return value;
+}
+
+function requireProxyHost(origin) {
+  const labels = origin.hostname.split('.');
+  if (origin.hostname.length > 253 || labels.length < 2 ||
+      labels.some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))) {
+    throw new Error('HTTPS deployment requires a canonical DNS hostname');
+  }
+  if (labels.every((label) => /^\d+$/.test(label))) {
+    throw new Error('HTTPS deployment requires a DNS hostname, not an IP address');
+  }
+}
+
+function requireHttpsListenerPort(origin, relayPort) {
+  const port = origin.port ? Number(origin.port) : 443;
+  if (port < 1 || port > 65535) throw new Error('HTTPS requires a valid listener port');
+  if (port === relayPort) throw new Error('HTTPS and the private relay require different listener ports');
+  return port;
+}
+
+function requirePersistentServicePath(path) {
+  const temporaryRoots = ['/tmp', '/var/tmp', '/private/tmp', '/private/var/tmp'];
+  if (temporaryRoots.some((root) => path === root || path.startsWith(`${root}/`))) {
+    throw new Error('The system service requires persistent paths outside temporary storage');
+  }
+}
+
+export function validateDeploymentInput(options) {
+  requireLinuxPlatform(options.platform ?? 'linux');
+  const config = validateConfiguration(options.config);
+  const origin = new URL(config.publicOrigin);
+  requireProxyHost(origin);
+  const proxy = options.proxy ?? 'nginx';
+  if (!['nginx', 'apache', 'none'].includes(proxy)) throw new Error('Choose nginx, apache or none for the HTTPS plan');
+  const configPath = requireDeploymentPath(options.configPath, 'Configuration');
+  const statePath = requireDeploymentPath(posix.resolve(posix.dirname(configPath), config.stateDirectory), 'State directory');
+  const nodePath = requireDeploymentPath(options.nodePath, 'Node executable');
+  const entryPath = requireDeploymentPath(options.entryPath, 'Installed command');
+  for (const path of [configPath, statePath, nodePath, entryPath]) requirePersistentServicePath(path);
+  if (entryPath.includes('/_npx/')) throw new Error('Install the package persistently before preparing a service');
+  return {
+    config, configPath, statePath, nodePath, entryPath, proxy,
+    username: requireServiceUsername(options.username),
+    certificatePath: proxy === 'none' ? undefined : requireDeploymentPath(options.certificatePath, 'TLS certificate'),
+    keyPath: proxy === 'none' ? undefined : requireDeploymentPath(options.keyPath, 'TLS private key'),
+    hostname: origin.hostname, authority: origin.host,
+    httpsPort: requireHttpsListenerPort(origin, config.port),
+  };
+}
+
+export const systemdQuoted = (value) => `"${value.replaceAll('%', '%%')}"`;
+export const proxyQuoted = (value) => `"${value}"`;

package/src/deployment/deployment-plan.mjs

@@ -0,0 +1,62 @@
+import * as fs from 'node:fs';
+import { join, resolve } from 'node:path';
+import { validateDeploymentInput } from './deployment-input.mjs';
+import { deploymentCommands, renderApacheProxy, renderNginxProxy, renderSystemdService } from './deployment-templates.mjs';
+
+export function renderDeploymentPlan(options) {
+  const input = validateDeploymentInput(options);
+  const notes = [
+    'This is a reviewable Linux deployment plan. No service, proxy, certificate or system setting has been changed.',
+    'Run the listed commands manually from the generated directory, one at a time; stop if any command fails.',
+    'Inspect existing destination files before copying; these sample commands are for a new installation, not an automatic update.',
+    `The existing unprivileged service user must be ${input.username} and must own the private configuration and state directory.`,
+    'The service user needs execute/read access to the installed Node and package paths. Do not use an npx cache path.',
+    'State must already exist with mode 0700, and its database/configuration files must remain 0600. Persistent writes are limited to that directory.',
+    'TLS certificate/key files, DNS and firewall access must be configured separately. This plan never requests or copies a private key.',
+    'Use a local direct HTTPS proxy. CDN or additional proxy chains require a separately reviewed trusted-client-IP policy.',
+    'Keep request bodies, pairing details and Authorization headers out of proxy logs; review inherited logging settings.',
+    'Regenerate the plan if the Node executable, package installation or private configuration location changes.',
+    'After service and HTTPS checks pass, run the pairing command for fresh credentials; these files contain no pairing code.',
+  ];
+  if (input.proxy === 'apache') notes.push(
+    'The Apache command paths target Debian/Ubuntu. Other distributions require their local module/site and service commands.',
+    'Apache requires version 2.4.47+ and an existing Listen directive for the HTTPS port; do not add a duplicate listener.',
+  );
+  if (input.proxy === 'none') notes.push(
+    'No proxy configuration was generated. Your existing HTTPS proxy must satisfy the documented Host, trusted-IP and WebSocket forwarding contract.',
+  );
+  const commands = deploymentCommands(input.proxy);
+  const files = {
+    'abot-socket.service': renderSystemdService(input),
+    'DEPLOYMENT.txt': [...notes, '', 'Review and run individually:', ...commands, ''].join('\n'),
+  };
+  if (input.proxy === 'nginx') files['nginx.conf'] = renderNginxProxy(input);
+  if (input.proxy === 'apache') files['apache.conf'] = renderApacheProxy(input);
+  return { files, notes, commands };
+}
+
+/** Only writes a new operator-selected directory. Never executes plan commands. */
+export function writeDeploymentPlan({ output, ...options }, io = fs) {
+  if (typeof output !== 'string' || !output.trim()) throw new Error('Choose a new deployment output directory');
+  const plan = renderDeploymentPlan(options);
+  const directory = resolve(output);
+  io.mkdirSync(directory, { mode: 0o700 });
+  const created = [];
+  try {
+    for (const [name, content] of Object.entries(plan.files)) {
+      const path = join(directory, name);
+      const descriptor = io.openSync(path, 'wx', 0o600);
+      created.push(path);
+      try { io.writeFileSync(descriptor, content); } finally { io.closeSync(descriptor); }
+    }
+  } catch (error) {
+    const failures = [];
+    for (const path of created.reverse()) {
+      try { io.unlinkSync(path); } catch (failure) { failures.push(failure); }
+    }
+    try { io.rmdirSync(directory); } catch (failure) { failures.push(failure); }
+    if (failures.length) throw new AggregateError([error, ...failures], 'Deployment write failed and cleanup was incomplete');
+    throw error;
+  }
+  return { directory, ...plan };
+}

package/src/deployment/deployment-templates.mjs

@@ -0,0 +1,109 @@
+import { posix } from 'node:path';
+import { proxyQuoted, systemdQuoted } from './deployment-input.mjs';
+
+export function renderSystemdService(input) {
+  return `[Unit]
+Description=ABot Socket relay
+After=network.target
+
+[Service]
+Type=simple
+User=${input.username}
+WorkingDirectory=${systemdQuoted(posix.dirname(input.configPath))}
+ExecStart=${systemdQuoted(input.nodePath)} ${systemdQuoted(input.entryPath)} start --config ${systemdQuoted(input.configPath)}
+Restart=on-failure
+RestartSec=5s
+UMask=0077
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ReadWritePaths=${systemdQuoted(input.statePath)}
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+export function renderNginxProxy(input) {
+  return `# Include inside nginx's http context. Existing TLS files are required.
+# Review global real_ip/CDN configuration before using this direct-proxy plan.
+server {
+    listen ${input.httpsPort} ssl;
+    server_name ${input.hostname};
+    ssl_certificate ${proxyQuoted(input.certificatePath)};
+    ssl_certificate_key ${proxyQuoted(input.keyPath)};
+    ssl_protocols TLSv1.2 TLSv1.3;
+    client_max_body_size 4k;
+    client_body_timeout 15s;
+    access_log off;
+
+    location / {
+        proxy_pass http://127.0.0.1:${input.config.port};
+        proxy_http_version 1.1;
+        # Preserve the real authority, including any explicit port. The relay
+        # rejects an unknown Host; never replace it with a configured constant.
+        proxy_set_header Host $http_host;
+        proxy_set_header Origin $http_origin;
+        proxy_set_header Authorization $http_authorization;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Socket-Client-IP $remote_addr;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 90s;
+        proxy_send_timeout 90s;
+        proxy_buffering off;
+    }
+}
+`;
+}
+
+export function renderApacheProxy(input) {
+  return `# Apache 2.4.47+; enable ssl, headers, proxy and proxy_http modules.
+# Add a matching Listen directive only if this HTTPS port is not already active.
+# This direct-proxy plan uses the actual connection peer, not forwarded headers.
+<VirtualHost *:${input.httpsPort}>
+    ServerName ${input.authority}
+    SSLEngine on
+    SSLCertificateFile ${proxyQuoted(input.certificatePath)}
+    SSLCertificateKeyFile ${proxyQuoted(input.keyPath)}
+    SSLProtocol -all +TLSv1.2 +TLSv1.3
+    ProxyRequests Off
+    ProxyPreserveHost On
+    ProxyTimeout 90
+    LimitRequestBody 4096
+
+    RequestHeader unset X-Forwarded-Proto
+    RequestHeader set X-Forwarded-Proto "https"
+    RequestHeader unset X-Socket-Client-IP
+    RequestHeader set X-Socket-Client-IP "expr=%{CONN_REMOTE_ADDR}"
+    # Host, Authorization and Origin are forwarded unchanged. Unknown Host
+    # values reach the relay unchanged and are rejected by its authority check.
+    ProxyPass "/" "http://127.0.0.1:${input.config.port}/" upgrade=websocket connectiontimeout=5 timeout=90
+    ProxyPassReverse "/" "http://127.0.0.1:${input.config.port}/"
+</VirtualHost>
+`;
+}
+
+export function deploymentCommands(proxy) {
+  const commands = [
+    'sudo install -m 0644 -- ./abot-socket.service /etc/systemd/system/abot-socket.service',
+    'sudo systemctl daemon-reload',
+    'sudo systemctl enable --now abot-socket.service',
+  ];
+  if (proxy === 'none') return commands;
+  if (proxy === 'nginx') return [...commands,
+    'sudo install -m 0644 -- ./nginx.conf /etc/nginx/conf.d/abot-socket.conf',
+    'sudo nginx -t',
+    'sudo systemctl reload nginx',
+  ];
+  return [...commands,
+    'sudo install -m 0644 -- ./apache.conf /etc/apache2/sites-available/abot-socket.conf',
+    'sudo a2enmod ssl headers proxy proxy_http',
+    'sudo a2ensite abot-socket.conf',
+    'sudo apachectl configtest',
+    'sudo systemctl reload apache2',
+  ];
+}

package/src/main.mjs

@@ -0,0 +1,26 @@
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { loadConfiguration } from './config/config.mjs';
+import { createSocketServer } from './transport/server.mjs';
+
+export async function startConfiguredServer(env = process.env) {
+  const config = loadConfiguration(env);
+  const app = createSocketServer(config);
+  try { await app.listen(config.port); }
+  catch (error) { await app.close(); throw error; }
+  return app;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  try {
+    const app = await startConfiguredServer();
+    console.log('ABot Socket listening on loopback behind the configured HTTPS reverse proxy.');
+    const stop = () => { void app.close(); };
+    process.once('SIGTERM', stop);
+    process.once('SIGINT', stop);
+  } catch {
+    // Configuration/provider errors can contain secrets; never print them here.
+    console.error('ABot Socket could not start. Check private configuration, state permissions and listener availability.');
+    process.exitCode = 1;
+  }
+}