@abot-ai/socket 0.0.0-stage → 0.1.0

package/src/auth/auth-database.mjs

@@ -0,0 +1,102 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { assertSameDatabaseFile, prepareAuthenticationDatabase } from './auth-storage-path.mjs';
+import { NOTIFICATION_SCHEMA } from '../notifications/notification-schema.mjs';
+import { NOTIFICATION_PREVIEW_SCHEMA } from '../notifications/notification-preview-schema.mjs';
+
+const APPLICATION_ID = 0x41425341;
+const SCHEMA_VERSION = 3;
+
+const SCHEMA = `
+  CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT;
+  CREATE TABLE pairing (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    id TEXT NOT NULL UNIQUE, digest BLOB NOT NULL, salt BLOB NOT NULL,
+    expires_at INTEGER NOT NULL, attempts INTEGER NOT NULL CHECK (attempts BETWEEN 0 AND 5)
+  ) STRICT;
+  CREATE TABLE devices (
+    id TEXT PRIMARY KEY, subject TEXT NOT NULL, device_name TEXT NOT NULL,
+    created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL,
+    token_hash TEXT NOT NULL UNIQUE
+  ) STRICT;
+  CREATE INDEX devices_expiry ON devices(expires_at);
+  CREATE TABLE pairing_attempts (source TEXT NOT NULL, attempted_at INTEGER NOT NULL) STRICT;
+  CREATE INDEX attempts_time ON pairing_attempts(attempted_at);
+  CREATE INDEX attempts_source ON pairing_attempts(source, attempted_at);
+`;
+
+/** One durable store shared by the operator CLI and relay processes. */
+export class AuthDatabase {
+  #connection;
+  #closed = false;
+
+  constructor(stateDirectory) {
+    const prepared = prepareAuthenticationDatabase(stateDirectory);
+    this.#connection = new DatabaseSync(prepared.path);
+    try {
+      assertSameDatabaseFile(stateDirectory, prepared);
+      this.#connection.exec('PRAGMA busy_timeout = 5000; PRAGMA temp_store = MEMORY; PRAGMA foreign_keys = ON;');
+      const mode = this.#connection.prepare('PRAGMA journal_mode').get().journal_mode;
+      if (mode !== 'delete') throw new Error('Authentication database must use DELETE journaling');
+      this.transaction(() => this.#initialize());
+      this.#connection.exec('PRAGMA synchronous = FULL;');
+      assertSameDatabaseFile(stateDirectory, prepared);
+    } catch (error) {
+      this.close();
+      throw error;
+    }
+  }
+
+  prepare(sql) {
+    return this.#connection.prepare(sql);
+  }
+
+  transaction(operation) {
+    this.#connection.exec('BEGIN IMMEDIATE');
+    try {
+      const result = operation();
+      this.#connection.exec('COMMIT');
+      return result;
+    } catch (error) {
+      this.#connection.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  get ownerId() {
+    return this.prepare("SELECT value FROM metadata WHERE key = 'owner_id'").get().value;
+  }
+
+  get tokenSalt() {
+    return this.prepare("SELECT value FROM metadata WHERE key = 'token_salt'").get().value;
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#connection.close();
+  }
+
+  #initialize() {
+    const applicationId = this.prepare('PRAGMA application_id').get().application_id;
+    const version = this.prepare('PRAGMA user_version').get().user_version;
+    if (applicationId === APPLICATION_ID && version === SCHEMA_VERSION) return;
+    if (applicationId === APPLICATION_ID && [1, 2].includes(version)) {
+      if (version === 1) this.#connection.exec(NOTIFICATION_SCHEMA);
+      this.#connection.exec(NOTIFICATION_PREVIEW_SCHEMA);
+      this.#connection.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+      return;
+    }
+    const objects = this.prepare("SELECT name FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%'").all();
+    if (applicationId !== 0 || version !== 0 || objects.length) {
+      throw new Error('Unrecognized authentication database; no changes were made');
+    }
+    this.#connection.exec(SCHEMA);
+    this.#connection.exec(NOTIFICATION_SCHEMA);
+    this.#connection.exec(NOTIFICATION_PREVIEW_SCHEMA);
+    const insert = this.prepare('INSERT INTO metadata(key, value) VALUES (?, ?)');
+    insert.run('owner_id', randomUUID());
+    insert.run('token_salt', randomBytes(32).toString('hex'));
+    this.#connection.exec(`PRAGMA application_id = ${APPLICATION_ID}; PRAGMA user_version = ${SCHEMA_VERSION};`);
+  }
+}

package/src/auth/auth-limits.mjs

@@ -0,0 +1,17 @@
+import { createHash } from 'node:crypto';
+
+export class AuthError extends Error {
+  constructor(code, status) {
+    super(code);
+    this.name = 'AuthError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function sourceKey(sourceId) {
+  if (typeof sourceId !== 'string' || !sourceId || sourceId.length > 128) {
+    throw new AuthError('invalid_request', 400);
+  }
+  return createHash('sha256').update(sourceId).digest('hex');
+}

package/src/auth/auth-pairing.mjs

@@ -0,0 +1,95 @@
+import { randomBytes, randomInt, scryptSync, timingSafeEqual } from 'node:crypto';
+import { AuthError, sourceKey } from './auth-limits.mjs';
+import { issueDeviceSession } from './auth-sessions.mjs';
+
+const PAIRING_MS = 5 * 60 * 1000;
+const MAX_ATTEMPTS = 5;
+const RATE_WINDOW_MS = 15 * 60 * 1000;
+const codeDigest = (code, salt) => scryptSync(code, salt, 32);
+const invalidCode = () => ({ error: new AuthError('invalid_code', 401) });
+
+function hasPairingInput(input) {
+  if (!input || typeof input !== 'object') return false;
+  return !Array.isArray(input);
+}
+
+function hasValidDeviceName(name) {
+  if (typeof name !== 'string' || !name.trim()) return false;
+  if (name.length > 80) return false;
+  return !/[\x00-\x1f\x7f]/.test(name);
+}
+
+function matchesPairingCode(code, pairing) {
+  if (typeof code !== 'string' || !/^\d{6}$/.test(code)) return false;
+  return timingSafeEqual(pairing.digest, codeDigest(code, pairing.salt));
+}
+
+export class AuthPairingStore {
+  constructor({ database, now }) {
+    this.database = database;
+    this.now = now;
+  }
+
+  create() {
+    const pairingId = randomBytes(24).toString('base64url');
+    const code = randomInt(1_000_000).toString().padStart(6, '0');
+    const salt = randomBytes(32);
+    const digest = codeDigest(code, salt);
+    const expiresAt = this.now() + PAIRING_MS;
+    this.database.transaction(() => {
+      this.database.prepare('DELETE FROM pairing').run();
+      this.database.prepare(`INSERT INTO pairing(singleton, id, digest, salt, expires_at, attempts)
+        VALUES (1, ?, ?, ?, ?, 0)`).run(pairingId, digest, salt, expiresAt);
+    });
+    return { pairingId, code, expiresAt };
+  }
+
+  redeem(input, sourceId) {
+    const source = sourceKey(sourceId);
+    const result = this.database.transaction(() => this.#redeemTransaction(input, source));
+    if (result.error) throw result.error;
+    return result;
+  }
+
+  prune() {
+    const time = this.now();
+    this.database.transaction(() => {
+      this.database.prepare('DELETE FROM pairing WHERE expires_at <= ?').run(time);
+      this.database.prepare('DELETE FROM pairing_attempts WHERE attempted_at <= ?').run(time - RATE_WINDOW_MS);
+    });
+  }
+
+  #redeemTransaction(input, source) {
+    const time = this.now();
+    if (!hasPairingInput(input)) return invalidCode();
+    const { deviceName = 'Device' } = input;
+    if (!hasValidDeviceName(deviceName)) return { error: new AuthError('invalid_request', 400) };
+    if (typeof input.pairingId !== 'string' || !/^[A-Za-z0-9_-]{32}$/.test(input.pairingId)) return invalidCode();
+    const pairing = this.database.prepare('SELECT * FROM pairing WHERE id = ? AND expires_at > ?')
+      .get(input.pairingId, time);
+    if (!pairing || pairing.attempts >= MAX_ATTEMPTS) return invalidCode();
+    // Unrelated or unusable challenges must not spend the verification quota.
+    if (!this.#consumeRateLimit(source, time)) return { error: new AuthError('rate_limited', 429) };
+    if (!matchesPairingCode(input.code, pairing)) {
+      this.database.prepare('UPDATE pairing SET attempts = attempts + 1 WHERE id = ?').run(pairing.id);
+      return invalidCode();
+    }
+    let session;
+    try { session = issueDeviceSession(this.database, time, deviceName.trim()); } catch (error) {
+      if (error instanceof AuthError) return { error };
+      throw error;
+    }
+    this.database.prepare('DELETE FROM pairing WHERE id = ?').run(pairing.id);
+    return session;
+  }
+
+  #consumeRateLimit(source, time) {
+    this.database.prepare('DELETE FROM pairing_attempts WHERE attempted_at <= ?').run(time - RATE_WINDOW_MS);
+    const total = this.database.prepare('SELECT count(*) AS count FROM pairing_attempts').get().count;
+    if (total >= 100) return false;
+    const attempts = this.database.prepare('SELECT count(*) AS count FROM pairing_attempts WHERE source = ?').get(source).count;
+    if (attempts >= 20) return false;
+    this.database.prepare('INSERT INTO pairing_attempts(source, attempted_at) VALUES (?, ?)').run(source, time);
+    return true;
+  }
+}

package/src/auth/auth-sessions.mjs

@@ -0,0 +1,119 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { AuthError } from './auth-limits.mjs';
+
+const SESSION_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_SESSIONS = 10;
+const tokenHash = (database, token) => createHash('sha256').update(database.tokenSalt).update(token).digest('hex');
+
+/** Called only inside the pairing transaction, before consuming its challenge. */
+export function issueDeviceSession(database, time, deviceName) {
+  database.prepare('DELETE FROM devices WHERE expires_at <= ?').run(time);
+  const count = database.prepare('SELECT count(*) AS count FROM devices WHERE expires_at > ?').get(time).count;
+  if (count >= MAX_SESSIONS) throw new AuthError('device_limit', 429);
+  const token = randomBytes(32).toString('base64url');
+  const session = { id: randomUUID(), subject: database.ownerId, deviceName };
+  const expiresAt = time + SESSION_MS;
+  database.prepare(`INSERT INTO devices(id, subject, device_name, created_at, expires_at, token_hash)
+    VALUES (?, ?, ?, ?, ?, ?)`).run(session.id, session.subject, deviceName, time, expiresAt, tokenHash(database, token));
+  return { token, expiresAt, session };
+}
+
+function assertDeviceId(id) {
+  if (typeof id !== 'string' || !id || id.length > 64) throw new AuthError('invalid_request', 400);
+}
+
+export class AuthSessionStore {
+  #database;
+  #principals = new WeakSet();
+  #listeners = new Set();
+  #observed = new Set();
+
+  constructor({ database, now }) {
+    this.#database = database;
+    this.now = now;
+    this.#observed = new Set(database.prepare('SELECT id FROM devices').all().map(({ id }) => id));
+  }
+
+  authenticate(token) {
+    this.prune();
+    if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(token)) return null;
+    const record = this.#database.prepare('SELECT id, subject, expires_at FROM devices WHERE token_hash = ? AND expires_at > ?')
+      .get(tokenHash(this.#database, token), this.now());
+    if (!record) return null;
+    const principal = Object.freeze({ sessionId: record.id, subject: record.subject, expiresAt: record.expires_at });
+    this.#principals.add(principal);
+    return principal;
+  }
+
+  list(principal) {
+    this.prune();
+    return this.#database.transaction(() => {
+      this.#assertPrincipal(principal);
+      return this.#records().map((record) => ({ ...record, current: record.id === principal.sessionId }));
+    });
+  }
+
+  listDevices() {
+    this.prune();
+    return this.#records();
+  }
+
+  revoke(principal, id) {
+    this.prune();
+    assertDeviceId(id);
+    const changed = this.#database.transaction(() => {
+      this.#assertPrincipal(principal);
+      return this.#database.prepare('DELETE FROM devices WHERE id = ?').run(id).changes > 0;
+    });
+    if (changed) this.#notifyRemoval(id);
+    return changed;
+  }
+
+  revokeDevice(id) {
+    assertDeviceId(id);
+    const changed = this.#database.prepare('DELETE FROM devices WHERE id = ?').run(id).changes > 0;
+    if (changed) this.#notifyRemoval(id);
+    return changed;
+  }
+
+  subscribeRevocations(listener) {
+    if (typeof listener !== 'function') throw new TypeError('A revocation listener is required');
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  prune() {
+    const active = this.#database.transaction(() => {
+      this.#database.prepare('DELETE FROM devices WHERE expires_at <= ?').run(this.now());
+      return new Set(this.#database.prepare('SELECT id FROM devices').all().map(({ id }) => id));
+    });
+    const removed = [...this.#observed].filter((id) => !active.has(id));
+    this.#observed = active;
+    for (const id of removed) this.#notifyRemoval(id);
+  }
+
+  close() {
+    this.#listeners.clear();
+    this.#observed.clear();
+  }
+
+  #records() {
+    return this.#database.prepare(`SELECT id, device_name AS deviceName, created_at AS createdAt,
+      expires_at AS expiresAt FROM devices WHERE expires_at > ? ORDER BY created_at, id`).all(this.now())
+      .map((record) => ({ ...record }));
+  }
+
+  #assertPrincipal(principal) {
+    if (!principal || !this.#principals.has(principal)) throw new AuthError('unauthorized', 401);
+    const record = this.#database.prepare('SELECT subject FROM devices WHERE id = ? AND expires_at > ?')
+      .get(principal.sessionId, this.now());
+    if (!record || record.subject !== principal.subject) throw new AuthError('unauthorized', 401);
+  }
+
+  #notifyRemoval(id) {
+    this.#observed.delete(id);
+    for (const listener of this.#listeners) {
+      try { listener(id); } catch { /* A listener cannot restore a revoked device. */ }
+    }
+  }
+}

package/src/auth/auth-storage-path.mjs

@@ -0,0 +1,70 @@
+import { constants, closeSync, lstatSync, mkdirSync, openSync, readdirSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, parse, resolve } from 'node:path';
+
+const DATABASE_NAME = 'auth.sqlite3';
+const STATE_FILES = new Set([DATABASE_NAME, `${DATABASE_NAME}-journal`]);
+
+function assertOwnedPrivateEntry(path, stat, mode, directory) {
+  const correctType = directory ? stat.isDirectory() : stat.isFile();
+  if (!correctType || stat.isSymbolicLink()) throw new Error(`Unsafe authentication state entry: ${basename(path)}`);
+  if (typeof process.getuid !== 'function' || stat.uid !== process.getuid()) {
+    throw new Error('Authentication state must belong to the current user');
+  }
+  if ((stat.mode & 0o7777) !== mode) throw new Error(`Authentication state requires mode ${mode.toString(8)}`);
+  if (!directory && stat.nlink !== 1) throw new Error('Authentication state files cannot have multiple links');
+}
+
+function assertDirectoryAncestors(path) {
+  let current = parse(path).root;
+  for (const component of path.slice(current.length).split('/').filter(Boolean)) {
+    current = join(current, component);
+    const stat = lstatSync(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('Authentication state path cannot contain symlinks');
+  }
+}
+
+export function assertPrivateStateDirectory(stateDirectory) {
+  assertDirectoryAncestors(stateDirectory);
+  assertOwnedPrivateEntry(stateDirectory, lstatSync(stateDirectory), 0o700, true);
+  for (const name of readdirSync(stateDirectory)) {
+    if (!STATE_FILES.has(name)) throw new Error(`Unexpected authentication state entry: ${name}`);
+    const path = join(stateDirectory, name);
+    try {
+      assertOwnedPrivateEntry(path, lstatSync(path), 0o600, false);
+    } catch (error) {
+      // Another connection can finish a DELETE-mode transaction during inspection.
+      if (name.endsWith('-journal') && error.code === 'ENOENT') continue;
+      throw error;
+    }
+  }
+}
+
+/** Create only the requested private directory and database, never repair existing paths. */
+export function prepareAuthenticationDatabase(stateDirectory) {
+  if (typeof stateDirectory !== 'string' || !isAbsolute(stateDirectory)) {
+    throw new TypeError('An absolute authentication stateDirectory is required');
+  }
+  if (stateDirectory !== resolve(stateDirectory)) throw new TypeError('Authentication stateDirectory must be canonical');
+  assertDirectoryAncestors(dirname(stateDirectory));
+  try { mkdirSync(stateDirectory, { mode: 0o700 }); } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+  }
+  assertPrivateStateDirectory(stateDirectory);
+  const path = join(stateDirectory, DATABASE_NAME);
+  try {
+    const descriptor = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    closeSync(descriptor);
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+  }
+  assertPrivateStateDirectory(stateDirectory);
+  return { path, stat: lstatSync(path) };
+}
+
+export function assertSameDatabaseFile(stateDirectory, prepared) {
+  assertPrivateStateDirectory(stateDirectory);
+  const stat = lstatSync(prepared.path);
+  if (stat.dev !== prepared.stat.dev || stat.ino !== prepared.stat.ino) {
+    throw new Error('Authentication database changed during opening');
+  }
+}

package/src/auth/auth.mjs

@@ -0,0 +1,45 @@
+import { AuthDatabase } from './auth-database.mjs';
+import { AuthPairingStore } from './auth-pairing.mjs';
+import { AuthSessionStore } from './auth-sessions.mjs';
+
+export { AuthError } from './auth-limits.mjs';
+
+/** Single-owner local pairing; only redemption is exposed by the HTTP API. */
+export class AuthService {
+  #database;
+  #pairing;
+  #sessions;
+  #ownsDatabase;
+
+  constructor({ stateDirectory, database, now = Date.now } = {}) {
+    if (typeof now !== 'function') throw new TypeError('An authentication clock is required');
+    this.#ownsDatabase = database === undefined;
+    this.#database = database ?? new AuthDatabase(stateDirectory);
+    try {
+      this.#pairing = new AuthPairingStore({ database: this.#database, now });
+      this.#sessions = new AuthSessionStore({ database: this.#database, now });
+    } catch (error) {
+      if (this.#ownsDatabase) this.#database.close();
+      throw error;
+    }
+  }
+
+  createPairing() { return this.#pairing.create(); }
+  redeemPairing(input, sourceId) { return this.#pairing.redeem(input, sourceId); }
+  authenticate(token) { return this.#sessions.authenticate(token); }
+  listSessions(principal) { return this.#sessions.list(principal); }
+  revoke(principal, sessionId) { return this.#sessions.revoke(principal, sessionId); }
+  listDevices() { return this.#sessions.listDevices(); }
+  revokeDevice(sessionId) { return this.#sessions.revokeDevice(sessionId); }
+  subscribeRevocations(listener) { return this.#sessions.subscribeRevocations(listener); }
+
+  prune() {
+    this.#pairing.prune();
+    this.#sessions.prune();
+  }
+
+  close() {
+    this.#sessions.close();
+    if (this.#ownsDatabase) this.#database.close();
+  }
+}

package/src/auth/runtime-credentials.mjs

@@ -0,0 +1,39 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+export const digestToken = (token) => createHash('sha256').update(token).digest('hex');
+
+export function validateRuntimeGrants(grants) {
+  if (!Array.isArray(grants) || grants.length < 1 || grants.length > 16) {
+    throw new Error('Configure 1 to 16 runtime grants');
+  }
+  const ids = new Set();
+  const digests = new Set();
+  return grants.map((grant) => {
+    if (!grant || !/^[A-Za-z0-9_.:-]{1,128}$/.test(grant.runtimeId ?? '') ||
+        !/^[a-f0-9]{64}$/.test(grant.tokenSha256 ?? '') ||
+        ids.has(grant.runtimeId) || digests.has(grant.tokenSha256)) {
+      throw new Error('Invalid or duplicate runtime grant');
+    }
+    const allowedModes = grant.allowedModes ?? ['ask'];
+    if (!Array.isArray(allowedModes) || !allowedModes.includes('ask') ||
+        allowedModes.some((mode) => !['ask', 'full_access', 'full_plus'].includes(mode))) {
+      throw new Error('Invalid runtime permission ceiling');
+    }
+    ids.add(grant.runtimeId);
+    digests.add(grant.tokenSha256);
+    return Object.freeze({ runtimeId: grant.runtimeId, tokenSha256: grant.tokenSha256,
+      allowedModes: Object.freeze([...new Set(allowedModes)]) });
+  });
+}
+
+export function resolveRuntimeCredential(authorization, grants) {
+  if (typeof authorization !== 'string' || !/^Bearer [A-Za-z0-9_-]{43,128}$/.test(authorization)) {
+    return null;
+  }
+  const digest = Buffer.from(digestToken(authorization.slice(7)), 'hex');
+  let match = null;
+  for (const grant of grants) {
+    if (timingSafeEqual(digest, Buffer.from(grant.tokenSha256, 'hex'))) match = grant;
+  }
+  return match;
+}

package/src/cli/cli-arguments.mjs

@@ -0,0 +1,23 @@
+const OPTION_NAMES = new Map([
+  ['--output', 'output'], ['--origin', 'origin'],
+  ['--runtime-id', 'runtimeId'], ['--port', 'port'],
+]);
+
+export function parseSetupArguments(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const name = OPTION_NAMES.get(args[index]);
+    if (!name || Object.hasOwn(options, name)) throw new Error('Unknown or duplicate setup option');
+    const value = args[index + 1];
+    if (typeof value !== 'string' || !value || value.startsWith('--')) {
+      throw new Error('Every setup option needs a value');
+    }
+    if (name !== 'port') { options[name] = value; continue; }
+    if (!/^\d{1,5}$/.test(value)) throw new Error('Invalid port');
+    options.port = Number(value);
+  }
+  for (const name of ['output', 'origin', 'runtimeId']) {
+    if (!options[name]) throw new Error('Missing required setup option');
+  }
+  return options;
+}

package/src/cli/cli-entry.mjs

@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { runCli } from './cli.mjs';
+import { resolveCliInvocation } from './cli-environment.mjs';
+import { runSetupWizard } from '../setup/setup-wizard.mjs';
+import { deploymentRuntimePaths, prepareDeployment } from '../deployment/deployment-command.mjs';
+import { loadConfiguration } from '../config/config.mjs';
+import { checkPublicEndpoint } from './doctor.mjs';
+import { startConfiguredServer } from '../main.mjs';
+import { startConfiguredNotificationGateway } from '../notifications/notification-gateway-command.mjs';
+import { startConfiguredReviewPortal } from '../review/review-portal-server.mjs';
+
+async function startForeground(env, out) {
+  const app = await startConfiguredServer(env);
+  out('ABot Socket listening on private loopback behind the configured HTTPS proxy.');
+  const stop = () => { void app.close(); };
+  process.once('SIGTERM', stop);
+  process.once('SIGINT', stop);
+  return 0;
+}
+
+async function interactiveSetup({ input, output, out, homeDirectory, pairingOutput }) {
+  if (!input.isTTY || !output.isTTY) {
+    out('Interactive setup requires a terminal. Use setup --output <new-directory> --origin <https-origin> --runtime-id <id>.');
+    return 2;
+  }
+  const readline = createInterface({ input, output });
+  const abort = new AbortController();
+  readline.once('SIGINT', () => abort.abort());
+  readline.once('close', () => abort.abort());
+  try {
+    return await runSetupWizard({ ask: (prompt) => readline.question(prompt, { signal: abort.signal }),
+      out, homeDirectory, pairingOutput, platform: process.platform, username: userInfo().username, ...deploymentRuntimePaths() });
+  } finally { readline.close(); }
+}
+
+export async function runEntry(args, { env = process.env, input = process.stdin, output = process.stdout,
+  error = console.error, homeDirectory = homedir() } = {}) {
+  const out = (line) => output.write(`${line}\n`);
+  const pairingOutput = { isTTY: output.isTTY === true, columns: output.columns, term: env.TERM };
+  try {
+    const invocation = resolveCliInvocation(args, env, homeDirectory);
+    const { command, args: rest } = invocation;
+    if (command === '--version' && rest.length === 0) {
+      const metadata = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+      out(`ABot Socket ${metadata.version}`);
+      return 0;
+    }
+    if (command === 'setup' && rest.length === 0) return await interactiveSetup({ input, output, out, homeDirectory, pairingOutput });
+    if (command === 'start' && rest.length === 0) return await startForeground(invocation.env, out);
+    if (command === 'review-portal' && rest.length === 0) {
+      const portal = await startConfiguredReviewPortal(invocation.env);
+      out('ABot review portal listening on private loopback behind its separate HTTPS proxy.');
+      const stop = () => { void portal.close(); };
+      process.once('SIGTERM', stop);
+      process.once('SIGINT', stop);
+      return 0;
+    }
+    if (command === 'push-gateway' && rest.length === 0) {
+      const gateway = await startConfiguredNotificationGateway(invocation.env);
+      out('ABot notification gateway listening on private loopback behind the configured HTTPS proxy.');
+      const stop = () => { void gateway.close(); };
+      process.once('SIGTERM', stop);
+      process.once('SIGINT', stop);
+      return 0;
+    }
+    if (command === 'doctor' && rest.length === 0) {
+      const config = loadConfiguration(invocation.env);
+      const report = await checkPublicEndpoint(config.publicOrigin);
+      out(JSON.stringify(report));
+      out('Runtime connectivity is not established by /health; verify it in the paired app.');
+      return report.ok ? 0 : 1;
+    }
+    if (command === 'deployment') {
+      prepareDeployment(rest, { env: invocation.env, out });
+      return 0;
+    }
+    return runCli([command, ...rest], { env: invocation.env, out, error, pairingOutput });
+  } catch {
+    error('Command could not complete. Check arguments, private paths and platform requirements; existing installation files are preserved.');
+    return 1;
+  }
+}

package/src/cli/cli-environment.mjs

@@ -0,0 +1,31 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export function defaultInstallationDirectory(homeDirectory = homedir()) {
+  return join(homeDirectory, '.abot-socket');
+}
+
+/** An explicit CLI config wins; otherwise preserve the existing environment contract. */
+export function resolveCliInvocation(args, env = process.env, homeDirectory = homedir()) {
+  const remaining = [];
+  let explicitConfig;
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] !== '--config') { remaining.push(args[index]); continue; }
+    const value = args[++index];
+    if (explicitConfig !== undefined || typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+      throw new Error('Provide --config once with a file path');
+    }
+    explicitConfig = resolve(value);
+  }
+  if (explicitConfig !== undefined && ['setup', 'review-setup'].includes(remaining[0])) {
+    throw new Error('Setup uses --output for a new installation; --config selects an existing installation');
+  }
+  const selected = { ...env };
+  if (explicitConfig !== undefined) {
+    selected.ABOT_SOCKET_CONFIG = explicitConfig;
+    delete selected.SOCKET_V2_CONFIG;
+  } else if (!selected.ABOT_SOCKET_CONFIG && !selected.SOCKET_V2_CONFIG) {
+    selected.ABOT_SOCKET_CONFIG = join(defaultInstallationDirectory(homeDirectory), 'config.json');
+  }
+  return { command: remaining[0], args: remaining.slice(1), env: selected };
+}

package/src/cli/cli-help.mjs

@@ -0,0 +1,34 @@
+export const USAGE = `ABot Socket — self-hosted relay
+
+abot-socket setup
+  Interactive local setup wizard. Requires a terminal; never configures services automatically.
+abot-socket setup --output <new-directory> --origin <https-origin> --runtime-id <id> [--port 8788]
+abot-socket review-setup --output <new-directory> --origin <socket-https-origin> --runtime-id <id>
+  --review-origin <separate-https-origin> [--port 8788] [--review-port 8789]
+abot-socket review-portal --config <demo-directory/config.json>
+abot-socket start
+abot-socket check-config
+abot-socket doctor
+abot-socket pair
+abot-socket devices
+abot-socket revoke <device-id>
+abot-socket deployment --output <new-directory> --proxy nginx|apache|none [--user <current-user>]
+  [--certificate <absolute-fullchain-path> --private-key <absolute-key-path>]
+
+Use --config <file> with any command except setup and review-setup. Otherwise use ABOT_SOCKET_CONFIG,
+the legacy SOCKET_V2_CONFIG alias, or ~/.abot-socket/config.json.
+
+Setup creates private files and one-time pairing details. Pair replaces only the
+pending pairing. Device credentials remain valid for up to 30 days across restarts.
+Setup and pair show a private QR in a capable terminal; manual details remain available.
+The QR expires after five minutes and can be used once. Piped output stays text/JSON.
+Doctor makes one public HTTPS request to your configured /health endpoint; it does
+not verify a runtime or send authentication credentials. Start runs in foreground.
+Deployment only writes reviewable Linux systemd/proxy files and instructions. It
+does not install packages, obtain certificates, run sudo, or activate a service.
+Runtime secrets belong only on the runtime computer, never in the mobile app.
+Review setup creates a new isolated Socket identity and private review-access.txt;
+it never adds a portal to an existing installation or starts a runtime/service.
+Use a separate demo runtime with synthetic data. Reviewer credentials stay local;
+the protected portal generates fresh standard pairing details when requested.
+`;