@abot-ai/socket 0.0.0-stage → 0.2.0

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.
+`;

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,14 @@
+import { supportsSparkChat } from '../protocol/spark-chat-protocol.mjs';
+
+/** Socket-owned API support; runtime identity/features remain separately scoped. */
+export function clientCapabilities({ ownership, runtime } = {}) {
+  return { cancel: false, durableApprovals: supportsDurableApprovals(ownership, runtime),
+    sessionMutation: true, notifications: true, sparkChat: supportsSparkChat(runtime) };
+}
+
+function supportsDurableApprovals(ownership, runtime) {
+  if (!ownership) return false;
+  if (runtime === undefined) return true;
+  if (runtime.online !== true) return false;
+  return Array.isArray(runtime.features) && runtime.features.includes('request_approvals_v1');
+}

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