@abot-ai/socket 0.0.0-stage → 0.2.0

package/src/relay/relay.mjs

@@ -0,0 +1,222 @@
+import { randomUUID } from 'node:crypto';
+import { normalizeClientCommand, expectedResponseType } from '../protocol/protocol.mjs';
+import { createRelayClient, admitRelayCommand } from './relay-client-admission.mjs';
+import { RelayCorrelations } from './relay-correlations.mjs';
+import { RelayRequests } from './relay-requests.mjs';
+import { RelayApprovals } from './relay-approvals.mjs';
+import { isApprovalCommand } from '../protocol/approval-protocol.mjs';
+import { assertSparkChatSupported } from '../protocol/spark-chat-protocol.mjs';
+import { RelaySessionMutations, isSessionMutation } from './relay-session-mutations.mjs';
+import { isBoundedRuntimeFrame, isRelayId, parseRuntimeRegistration,
+  validateRuntimeGrant, relayError } from './relay-runtime-registration.mjs';
+
+export class Relay {
+  constructor({ now = Date.now, send, close, observeRequest, ownership, isClientAuthorized = () => true }) {
+    this.now = now;
+    this.send = send;
+    this.close = close;
+    this.ownership = ownership;
+    this.clients = new Map();
+    this.runtimes = new Map();
+    this.runtimePeers = new Map();
+    this.requests = new RelayRequests({ now, ownership, observe: observeRequest,
+      event: (client, runtimeId, body) => this.deliver(client, { type: 'relay.event', runtimeId, body }),
+      unknown: (client, record) => this.error(client.peer, undefined, record.runtime.runtimeId,
+        'outcome_unknown', { requestId: record.requestId }),
+    });
+    this.correlations = new RelayCorrelations({ now,
+      respond: (entry, body) => this.deliver(entry.client, { type: 'relay.response', id: entry.id,
+        runtimeId: entry.runtime.runtimeId, body }),
+      unknown: entry => this.error(entry.client.peer, entry.id, entry.runtime.runtimeId, 'outcome_unknown'),
+    });
+    this.approvals = new RelayApprovals({ ownership, requests: this.requests, correlations: this.correlations,
+      transmit: (peer, body) => this.transmit(peer, body),
+      connected: client => this.clients.get(client.peer) === client && isClientAuthorized(client),
+      currentRuntime: runtime => this.runtimes.get(runtime.runtimeId) === runtime && runtime.registered,
+      assertSessionAvailable: (runtime, sessionId) => this.sessionMutations.assertNoPending(runtime, sessionId),
+      respond: (client, runtime, id, body) => this.deliver(client, { type: 'relay.response', id,
+        runtimeId: runtime.runtimeId, body }),
+      error: (client, runtime, id, code) => this.error(client.peer, id, runtime.runtimeId, code),
+    });
+    this.sessionMutations = new RelaySessionMutations({ now, correlations: this.correlations,
+      requests: this.requests, ownership, transmit: (peer, body) => this.transmit(peer, body),
+      connected: client => this.clients.get(client.peer) === client,
+      error: (operation, code) => this.error(operation.client.peer, operation.id, operation.runtime.runtimeId, code),
+      respond: (operation, body) => this.deliver(operation.client, { type: 'relay.response',
+        id: operation.id, runtimeId: operation.runtime.runtimeId, body }),
+    });
+  }
+
+  transmit(peer, body) {
+    try { return this.send(peer, body) === true; } catch { return false; }
+  }
+
+  terminate(peer, reason) {
+    this.disconnect(peer);
+    try { this.close(peer, 1008, reason); } catch { /* State is already detached. */ }
+  }
+
+  deliver(client, body) {
+    if (this.clients.get(client.peer) !== client) return false;
+    if (this.transmit(client.peer, body)) return true;
+    this.terminate(client.peer, 'transport_unavailable');
+    return false;
+  }
+
+  error(peer, id, runtimeId, code, body) {
+    const client = this.clients.get(peer);
+    if (!client) return;
+    this.deliver(client, { type: 'relay.error', ...(isRelayId(id) ? { id } : {}),
+      ...(isRelayId(runtimeId) ? { runtimeId } : {}), code, ...(body ? { body } : {}) });
+  }
+
+  attachRuntime(peer, grant) {
+    this.prune();
+    if (this.runtimePeers.has(peer) || this.clients.has(peer)) return false;
+    try {
+      const identity = validateRuntimeGrant(grant);
+      if (this.runtimes.has(identity.runtimeId) || this.runtimes.size >= 32) return false;
+      const runtime = { ...identity, peer, generation: randomUUID(), registered: false,
+        registerBy: this.now() + 5_000, features: [], modelCatalog: null };
+      this.runtimePeers.set(peer, runtime);
+      this.runtimes.set(runtime.runtimeId, runtime);
+      return true;
+    } catch { return false; }
+  }
+
+  attachClient(peer, identity) {
+    this.prune();
+    if (this.clients.has(peer) || this.runtimePeers.has(peer) || this.clients.size >= 128) return false;
+    try {
+      this.clients.set(peer, createRelayClient(peer, identity, this.now()));
+      return true;
+    } catch { return false; }
+  }
+
+  runtimeSnapshot(allowedRuntimeIds) {
+    if (!Array.isArray(allowedRuntimeIds) || allowedRuntimeIds.length > 32) return [];
+    return [...new Set(allowedRuntimeIds.filter(isRelayId))].map(runtimeId => {
+      const runtime = this.runtimes.get(runtimeId);
+      const online = runtime?.registered === true;
+      return { runtimeId, online,
+        modelCatalog: online ? structuredClone(runtime.modelCatalog) : null,
+        features: online ? [...runtime.features] : [] };
+    });
+  }
+
+  register(runtime, body) {
+    if (runtime.registered) throw relayError('duplicate_registration');
+    const registration = parseRuntimeRegistration(body, runtime.runtimeId);
+    Object.assign(runtime, registration, { registered: true });
+    const reply = { type: 'registered', agentId: runtime.runtimeId, ok: true,
+      modelCatalog: { accepted: true, source: runtime.modelCatalog ? 'runtime' : 'legacy' },
+      features: runtime.features };
+    if (!this.transmit(runtime.peer, reply)) this.terminate(runtime.peer, 'transport_unavailable');
+  }
+
+  runtimeMessage(peer, body) {
+    this.prune();
+    const runtime = this.runtimePeers.get(peer);
+    if (!runtime || this.runtimes.get(runtime.runtimeId) !== runtime) return;
+    if (!isBoundedRuntimeFrame(body)) return this.terminate(peer, 'invalid_runtime_frame');
+    try {
+      if (body.type === 'register') return this.register(runtime, body);
+      if (!runtime.registered) return this.terminate(peer, 'registration_required');
+      if (this.correlations.receive(runtime, body)) return;
+      this.requests.receive(runtime, body);
+    } catch (error) {
+      this.terminate(peer, error.code ?? 'invalid_runtime_frame');
+    }
+  }
+
+  clientMessage(peer, message) {
+    this.prune();
+    const client = this.clients.get(peer);
+    if (!client) return;
+    try {
+      admitRelayCommand(client, message, this.now());
+      const runtime = this.runtimes.get(message.runtimeId);
+      if (!runtime?.registered) throw relayError('runtime_offline');
+      const command = normalizeClientCommand(message.body, runtime.allowedModes);
+      this.dispatch(client, runtime, message.id, command);
+    } catch (error) {
+      this.error(peer, message?.id, message?.runtimeId, error.code ?? 'invalid_command');
+    }
+  }
+
+  acknowledge(client, runtime, id, body) {
+    this.deliver(client, { type: 'relay.ack', id, runtimeId: runtime.runtimeId, body });
+  }
+
+  dispatch(client, runtime, id, command) {
+    assertSparkChatSupported(command, runtime);
+    if (isSessionMutation(command.type)) {
+      this.approvals.adoption.assertNoPendingSession(runtime, command.sessionId);
+      return this.sessionMutations.dispatch(client, runtime, id, command);
+    }
+    if (['run_request', 'attachment.upload.request'].includes(command.type) || isApprovalCommand(command.type)) {
+      this.sessionMutations.assertNoPending(runtime, command.sessionId);
+    }
+    if (command.type === 'run_request') return this.dispatchRun(client, runtime, id, command);
+    if (isApprovalCommand(command.type)) return this.approvals.dispatch(client, runtime, id, command);
+    if (command.type === 'subscribe_request') {
+      this.requests.subscribe(client, runtime, command.requestId);
+      return this.acknowledge(client, runtime, id, { requestId: command.requestId, status: 'subscribed' });
+    }
+    if (command.type === 'tool_approval_response') return this.dispatchApproval(client, runtime, id, command);
+    if (command.type === 'steer_request') return this.dispatchSteering(client, runtime, id, command);
+    const expectedType = expectedResponseType(command.type);
+    if (!expectedType) throw relayError('unsupported_command');
+    const entry = this.correlations.create(client, runtime, id, command, expectedType);
+    const frame = { ...command, correlationId: entry.correlationId };
+    if (!this.transmit(runtime.peer, frame)) this.correlations.fail(entry);
+  }
+
+  dispatchRun(client, runtime, id, command) {
+    this.approvals.adoption.assertNoPendingRequest(runtime, command.requestId);
+    const record = this.requests.create(client, runtime, command);
+    if (!this.transmit(runtime.peer, command)) {
+      this.requests.markUnknown(record, false);
+      return this.error(client.peer, id, runtime.runtimeId, 'outcome_unknown');
+    }
+    this.acknowledge(client, runtime, id, { requestId: command.requestId, status: 'dispatched' });
+  }
+
+  dispatchApproval(client, runtime, id, command) {
+    this.requests.consumeApproval(client, runtime, command);
+    if (!this.transmit(runtime.peer, command)) return this.error(client.peer, id, runtime.runtimeId, 'outcome_unknown');
+    this.acknowledge(client, runtime, id, { approvalId: command.approvalId, status: 'dispatched' });
+  }
+
+  dispatchSteering(client, runtime, id, command) {
+    this.requests.owned(client, runtime, command.requestId, true);
+    const entry = this.correlations.create(client, runtime, id, command, 'steer_ack');
+    try { this.requests.reserveSteering(client, runtime, command); }
+    catch (error) { this.correlations.remove(entry); throw error; }
+    if (!this.transmit(runtime.peer, command)) this.correlations.fail(entry);
+  }
+
+  disconnect(peer) {
+    const client = this.clients.get(peer);
+    if (client) {
+      this.clients.delete(peer);
+      this.requests.disconnectClient(client);
+      this.correlations.disconnectClient(client);
+    }
+    const runtime = this.runtimePeers.get(peer);
+    if (!runtime) return;
+    this.runtimePeers.delete(peer);
+    if (this.runtimes.get(runtime.runtimeId) === runtime) this.runtimes.delete(runtime.runtimeId);
+    this.correlations.disconnectRuntime(runtime);
+    this.requests.disconnectRuntime(runtime);
+  }
+
+  prune() {
+    for (const runtime of this.runtimePeers.values()) {
+      if (!runtime.registered && runtime.registerBy <= this.now()) this.terminate(runtime.peer, 'registration_timeout');
+    }
+    this.correlations.prune();
+    this.requests.prune();
+    this.ownership?.prune();
+  }
+}

package/src/relay/request-ownership-schema.mjs

@@ -0,0 +1,18 @@
+/** Routing identity only. Approval authority and execution state belong to the runtime. */
+export const REQUEST_OWNERSHIP_SCHEMA = `
+  CREATE TABLE request_ownership (
+    runtime_id TEXT NOT NULL CHECK(length(runtime_id) BETWEEN 1 AND 128),
+    request_id TEXT NOT NULL CHECK(length(request_id) BETWEEN 1 AND 128),
+    session_id TEXT NOT NULL CHECK(length(session_id) BETWEEN 1 AND 128),
+    subject TEXT NOT NULL CHECK(length(subject) BETWEEN 1 AND 320),
+    device_id TEXT NOT NULL CHECK(length(device_id) BETWEEN 1 AND 256),
+    status TEXT NOT NULL CHECK(status IN ('open', 'terminal')),
+    created_at INTEGER NOT NULL CHECK(created_at >= 0),
+    terminal_at INTEGER,
+    PRIMARY KEY(runtime_id, request_id),
+    CHECK((status = 'open' AND terminal_at IS NULL)
+      OR (status = 'terminal' AND terminal_at IS NOT NULL AND terminal_at >= 0))
+  ) STRICT;
+  CREATE INDEX request_ownership_session ON request_ownership(runtime_id, session_id);
+  CREATE INDEX request_ownership_terminal ON request_ownership(terminal_at) WHERE status = 'terminal';
+`;

package/src/relay/request-ownership-store.mjs

@@ -0,0 +1,115 @@
+import { isRelayId, relayError } from './relay-runtime-registration.mjs';
+
+const MAX_OWNERSHIP_RECORDS = 512;
+const TERMINAL_RETENTION_MS = 12 * 60 * 60 * 1000;
+const SELECT_RECORD = `SELECT runtime_id AS runtimeId, session_id AS sessionId,
+  request_id AS requestId, subject, device_id AS deviceId, status,
+  created_at AS createdAt, terminal_at AS terminalAt FROM request_ownership`;
+
+function assertRequestIdentity(runtimeId, requestId) {
+  if (!isRelayId(runtimeId)) throw relayError('invalid_request_identity');
+  if (!isRelayId(requestId)) throw relayError('invalid_request_identity');
+}
+
+function assertOwnershipIdentity(identity, ownerId) {
+  if (!identity || typeof identity !== 'object') throw relayError('invalid_request_identity');
+  assertRequestIdentity(identity.runtimeId, identity.requestId);
+  if (!isRelayId(identity.sessionId)) throw relayError('invalid_request_identity');
+  if (identity.subject !== ownerId) throw relayError('invalid_request_identity');
+  if (typeof identity.deviceId !== 'string') throw relayError('invalid_request_identity');
+  if (!identity.deviceId.trim() || identity.deviceId.length > 256) throw relayError('invalid_request_identity');
+}
+
+/** Durable owner binding, never an approval cache or a queue for replaying runs. */
+export class RequestOwnershipStore {
+  constructor({ database, now = Date.now }) {
+    if (typeof database?.prepare !== 'function' || typeof database?.transaction !== 'function') {
+      throw new TypeError('An authentication database is required');
+    }
+    if (typeof now !== 'function') throw new TypeError('An ownership clock is required');
+    this.database = database;
+    this.now = now;
+  }
+
+  create(identity) {
+    assertOwnershipIdentity(identity, this.database.ownerId);
+    const time = this.#time();
+    return this.database.transaction(() => {
+      if (this.get(identity.runtimeId, identity.requestId)) throw relayError('request_id_conflict');
+      return this.#insert(identity, time, false);
+    });
+  }
+
+  isOwnerSubject(subject) {
+    return subject === this.database.ownerId;
+  }
+
+  /** The relay must first verify the exact canonical request on the authorized runtime. */
+  adopt(identity, terminal = false) {
+    assertOwnershipIdentity(identity, this.database.ownerId);
+    if (typeof terminal !== 'boolean') throw relayError('invalid_request_identity');
+    const time = this.#time();
+    return this.database.transaction(() => {
+      const existing = this.get(identity.runtimeId, identity.requestId);
+      if (!existing) return this.#insert(identity, time, terminal);
+      if (existing.subject !== identity.subject) throw relayError('request_not_owned');
+      if (existing.sessionId !== identity.sessionId) throw relayError('request_not_owned');
+      return existing;
+    });
+  }
+
+  get(runtimeId, requestId) {
+    assertRequestIdentity(runtimeId, requestId);
+    const record = this.database.prepare(`${SELECT_RECORD} WHERE runtime_id = ? AND request_id = ?`)
+      .get(runtimeId, requestId);
+    return record ? { ...record } : null;
+  }
+
+  listSession(runtimeId, sessionId) {
+    if (!isRelayId(runtimeId) || !isRelayId(sessionId)) throw relayError('invalid_request_identity');
+    return this.database.prepare(`${SELECT_RECORD} WHERE runtime_id = ? AND session_id = ?
+      ORDER BY created_at, request_id LIMIT ?`)
+      .all(runtimeId, sessionId, MAX_OWNERSHIP_RECORDS).map(record => ({ ...record }));
+  }
+
+  markTerminal(runtimeId, requestId) {
+    assertRequestIdentity(runtimeId, requestId);
+    return this.database.prepare(`UPDATE request_ownership SET status = 'terminal', terminal_at = ?
+      WHERE runtime_id = ? AND request_id = ? AND status = 'open'`)
+      .run(this.#time(), runtimeId, requestId).changes > 0;
+  }
+
+  /** The caller must have confirmed deletion of the complete canonical session. */
+  retireSession(runtimeId, sessionId) {
+    if (!isRelayId(runtimeId) || !isRelayId(sessionId)) throw relayError('invalid_request_identity');
+    return this.database.prepare('DELETE FROM request_ownership WHERE runtime_id = ? AND session_id = ?')
+      .run(runtimeId, sessionId).changes;
+  }
+
+  prune() {
+    return this.#deleteExpired(this.#time());
+  }
+
+  #insert(identity, time, terminal) {
+    this.#deleteExpired(time);
+    const count = this.database.prepare('SELECT count(*) AS count FROM request_ownership').get().count;
+    if (count >= MAX_OWNERSHIP_RECORDS) throw relayError('request_capacity');
+    this.database.prepare(`INSERT INTO request_ownership
+      (runtime_id, request_id, session_id, subject, device_id, status, created_at, terminal_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(identity.runtimeId, identity.requestId, identity.sessionId, identity.subject, identity.deviceId,
+        terminal ? 'terminal' : 'open', time, terminal ? time : null);
+    return this.get(identity.runtimeId, identity.requestId);
+  }
+
+  #deleteExpired(time) {
+    return this.database.prepare("DELETE FROM request_ownership WHERE status = 'terminal' AND terminal_at <= ?")
+      .run(time - TERMINAL_RETENTION_MS).changes;
+  }
+
+  #time() {
+    const time = this.now();
+    if (!Number.isSafeInteger(time) || time < 0) throw new TypeError('Invalid ownership clock');
+    return time;
+  }
+}

package/src/review/review-demo-isolation.mjs

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from 'node:fs';
+import { basename, dirname, join, parse, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { assertPrivateStateDirectory, assertSameDatabaseFile } from '../auth/auth-storage-path.mjs';
+import { validateConfiguration } from '../config/config-validation.mjs';
+
+const MAX_PRIVATE_BYTES = 32_768;
+const PORTAL_KEYS = ['version', 'purpose', 'demoId', 'ownerId', 'configSha256',
+  'publicOrigin', 'port', 'username', 'passwordSha256'];
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+
+/** Bind only the demo identity; operators may configure its modes and push later. */
+export function reviewDemoIdentitySha256(config) {
+  const runtimeGrants = config.runtimeGrants.map(({ runtimeId, tokenSha256 }) => ({ runtimeId, tokenSha256 }))
+    .sort((left, right) => left.runtimeId.localeCompare(right.runtimeId));
+  return digest(JSON.stringify({ publicOrigin: config.publicOrigin,
+    stateDirectory: config.stateDirectory, runtimeGrants }));
+}
+
+export function assertReviewEndpointSeparation(socketConfig, publicOrigin, port) {
+  let origin;
+  try { origin = new URL(publicOrigin); } catch { /* Validated below. */ }
+  if (!origin || origin.protocol !== 'https:' || origin.origin !== publicOrigin || origin.username || origin.password) {
+    throw new Error('Review portal requires a canonical HTTPS origin');
+  }
+  if (publicOrigin === socketConfig.publicOrigin) throw new Error('Socket and review origins must differ');
+  if (!Number.isInteger(port) || port < 1024 || port > 65535 || port === socketConfig.port) {
+    throw new Error('Socket and review listener ports must differ and be unprivileged');
+  }
+}
+
+export function assertReviewDemoParentPath(directory) {
+  let current = parse(directory).root;
+  for (const component of directory.slice(current.length).split('/').filter(Boolean)) {
+    current = join(current, component);
+    const entry = lstatSync(current);
+    if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error('Unsafe demo installation path');
+  }
+}
+
+function assertPrivateDemoDirectory(directory) {
+  assertReviewDemoParentPath(directory);
+  const stat = lstatSync(directory);
+  if (typeof process.getuid !== 'function' || stat.uid !== process.getuid() || (stat.mode & 0o7777) !== 0o700) {
+    throw new Error('Demo installation must be private and owned by the current user');
+  }
+}
+
+function readPrivateDemoJson(path) {
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid() ||
+        (stat.mode & 0o7777) !== 0o600 || stat.size > MAX_PRIVATE_BYTES) throw new Error();
+    const bytes = Buffer.alloc(MAX_PRIVATE_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(descriptor, bytes, length, bytes.length - length, null);
+      if (count === 0) break;
+      length += count;
+    }
+    if (length > MAX_PRIVATE_BYTES) throw new Error();
+    return JSON.parse(bytes.toString('utf8', 0, length));
+  } finally { if (descriptor !== undefined) closeSync(descriptor); }
+}
+
+function validatePortalRecord(value, socketConfig) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.keys(value).length !== PORTAL_KEYS.length || Object.keys(value).some(key => !PORTAL_KEYS.includes(key))) {
+    throw new Error('Invalid review portal configuration');
+  }
+  if (value.version !== 1 || value.purpose !== 'review-demo' || value.username !== 'reviewer' ||
+      typeof value.demoId !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(value.demoId) ||
+      typeof value.ownerId !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value.ownerId)) {
+    throw new Error('Invalid review demo identity');
+  }
+  for (const key of ['configSha256', 'passwordSha256']) {
+    if (typeof value[key] !== 'string' || !/^[a-f0-9]{64}$/.test(value[key])) throw new Error('Invalid review credential binding');
+  }
+  assertReviewEndpointSeparation(socketConfig, value.publicOrigin, value.port);
+  if (value.configSha256 !== reviewDemoIdentitySha256(socketConfig)) throw new Error('Demo socket identity changed');
+}
+
+function assertMarkedDemoDatabase(stateDirectory, portal) {
+  assertPrivateStateDirectory(stateDirectory);
+  const path = join(stateDirectory, 'auth.sqlite3');
+  const prepared = { path, stat: lstatSync(path) };
+  // Never instantiate AuthDatabase here: it can initialize or migrate state.
+  const database = new DatabaseSync(path, { readOnly: true });
+  try {
+    assertSameDatabaseFile(stateDirectory, prepared);
+    if (database.prepare('PRAGMA application_id').get().application_id !== 0x41425341) throw new Error();
+    const read = database.prepare('SELECT value FROM metadata WHERE key = ?');
+    if (read.get('review_demo_id')?.value !== portal.demoId || read.get('owner_id')?.value !== portal.ownerId) {
+      throw new Error('State does not belong to this review demo');
+    }
+    assertSameDatabaseFile(stateDirectory, prepared);
+  } finally { database.close(); }
+}
+
+function selectedDemoConfiguration(env) {
+  const primary = env.ABOT_SOCKET_CONFIG;
+  const legacy = env.SOCKET_V2_CONFIG;
+  if (primary && legacy && primary !== legacy) throw new Error('Conflicting demo configuration paths');
+  const value = primary || legacy;
+  if (typeof value !== 'string' || !value.trim() || value.length > 4096 || /[\x00-\x1f\x7f]/.test(value)) {
+    throw new Error('Choose a private demo config.json');
+  }
+  const path = resolve(value);
+  if (basename(path) !== 'config.json') throw new Error('Choose the demo config.json');
+  return path;
+}
+
+/** Separate-process gate: fixed siblings and existing marked state only. */
+export function loadReviewDemoConfiguration(env = {}) {
+  try {
+    const configPath = selectedDemoConfiguration(env);
+    const directory = dirname(configPath);
+    assertPrivateDemoDirectory(directory);
+    const socketConfig = validateConfiguration(readPrivateDemoJson(configPath));
+    if (socketConfig.stateDirectory !== './state') throw new Error('Demo state must remain its fixed sibling');
+    const portal = readPrivateDemoJson(join(directory, 'review-portal.json'));
+    validatePortalRecord(portal, socketConfig);
+    const stateDirectory = join(directory, 'state');
+    assertMarkedDemoDatabase(stateDirectory, portal);
+    return Object.freeze({ ...portal, socketOrigin: socketConfig.publicOrigin, stateDirectory });
+  } catch {
+    throw new Error('Review portal requires a private marked demo installation with matching socket and state identities');
+  }
+}

package/src/review/review-demo-setup.mjs

@@ -0,0 +1,97 @@
+import { createHash, randomBytes } from 'node:crypto';
+import * as filesystem from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { AuthDatabase } from '../auth/auth-database.mjs';
+import { prepareInstallation } from '../setup/setup.mjs';
+import { writePrivateInstallation } from '../setup/setup-files.mjs';
+import { assertReviewDemoParentPath, assertReviewEndpointSeparation, reviewDemoIdentitySha256 } from './review-demo-isolation.mjs';
+
+const OPTIONS = new Map([['--output', 'output'], ['--origin', 'origin'], ['--runtime-id', 'runtimeId'],
+  ['--review-origin', 'reviewOrigin'], ['--port', 'port'], ['--review-port', 'reviewPort']]);
+
+export function parseReviewDemoArguments(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const name = OPTIONS.get(args[index]);
+    const value = args[index + 1];
+    if (!name || Object.hasOwn(options, name) || typeof value !== 'string' || !value || value.startsWith('--')) {
+      throw new Error('Provide each review setup option once with a value');
+    }
+    if (name === 'port' || name === 'reviewPort') {
+      if (!/^\d{1,5}$/.test(value)) throw new Error('Invalid review listener port');
+      options[name] = Number(value);
+      continue;
+    }
+    options[name] = value;
+  }
+  for (const name of ['output', 'origin', 'runtimeId', 'reviewOrigin']) {
+    if (!options[name]) throw new Error('Missing required review setup option');
+  }
+  return options;
+}
+
+function writePrivateReviewFile(path, content, created, io) {
+  const descriptor = io.openSync(path, 'wx', 0o600);
+  created.push(path);
+  try { io.writeFileSync(descriptor, content); io.fsyncSync(descriptor); }
+  finally { io.closeSync(descriptor); }
+}
+
+function removeOwnedFailedDemo(directory, created, stateCreated, io) {
+  const failures = [];
+  for (const path of created.reverse()) {
+    try { io.unlinkSync(path); } catch (error) { failures.push(error); }
+  }
+  if (stateCreated) {
+    const state = join(directory, 'state');
+    for (const name of ['auth.sqlite3-journal', 'auth.sqlite3']) {
+      try { io.unlinkSync(join(state, name)); } catch (error) { if (error.code !== 'ENOENT') failures.push(error); }
+    }
+    try { io.rmdirSync(state); } catch (error) { failures.push(error); }
+  }
+  try { io.rmdirSync(directory); } catch (error) { failures.push(error); }
+  return failures;
+}
+
+/** Local file preparation only; no existing installation, services or runtime is reused. */
+export function createReviewDemoInstallation(options, { io = filesystem } = {}) {
+  if (typeof options.output !== 'string' || !options.output.trim()) throw new Error('Choose a new private demo directory');
+  const bundle = prepareInstallation(options);
+  const port = options.reviewPort ?? 8789;
+  assertReviewEndpointSeparation(bundle.config, options.reviewOrigin, port);
+  const directory = resolve(options.output);
+  assertReviewDemoParentPath(dirname(directory));
+  writePrivateInstallation(directory, bundle, io);
+  const created = [join(directory, 'config.json'), join(directory, 'runtime-connection.json')];
+  let stateCreated = false;
+  try {
+    const stateDirectory = join(directory, 'state');
+    io.mkdirSync(stateDirectory, { mode: 0o700 });
+    stateCreated = true;
+    const database = new AuthDatabase(stateDirectory);
+    const demoId = randomBytes(32).toString('base64url');
+    let ownerId;
+    try {
+      ownerId = database.ownerId;
+      database.transaction(() => database.prepare('INSERT INTO metadata(key, value) VALUES (?, ?)')
+        .run('review_demo_id', demoId));
+    } finally { database.close(); }
+    const password = randomBytes(32).toString('base64url');
+    const portal = { version: 1, purpose: 'review-demo', demoId, ownerId,
+      configSha256: reviewDemoIdentitySha256(bundle.config), publicOrigin: options.reviewOrigin,
+      port, username: 'reviewer', passwordSha256: createHash('sha256').update(password).digest('hex') };
+    writePrivateReviewFile(join(directory, 'review-portal.json'), `${JSON.stringify(portal, null, 2)}\n`, created, io);
+    writePrivateReviewFile(join(directory, 'review-access.txt'),
+      `ABot isolated review demo\nPortal: ${portal.publicOrigin}/review\nUsername: reviewer\nPassword: ${password}\n\n` +
+      'Keep these reviewer credentials private. The portal issues normal single-use 5-minute pairing details.\n' +
+      'The demo runtime must use separate storage and synthetic data; this setup does not create or isolate a runtime.\n', created, io);
+    return { directory, configPath: join(directory, 'config.json'),
+      runtimeConnectionPath: join(directory, 'runtime-connection.json'),
+      reviewConfigurationPath: join(directory, 'review-portal.json'),
+      reviewAccessPath: join(directory, 'review-access.txt') };
+  } catch (error) {
+    const failures = removeOwnedFailedDemo(directory, created, stateCreated, io);
+    if (failures.length) throw new AggregateError([error, ...failures], 'Review setup failed and owned cleanup was incomplete');
+    throw error;
+  }
+}

package/src/review/review-portal-access.mjs

@@ -0,0 +1,64 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { WindowLimiter } from '../transport/transport-limits.mjs';
+
+const CSRF_MS = 10 * 60 * 1000;
+
+function matchesReviewerAuthorization(value, username, passwordSha256) {
+  if (typeof value !== 'string' || value.length > 512) return false;
+  const match = /^Basic ([A-Za-z0-9+/]+={0,2})$/.exec(value);
+  if (!match) return false;
+  const bytes = Buffer.from(match[1], 'base64');
+  if (bytes.toString('base64') !== match[1]) return false;
+  const decoded = bytes.toString('utf8');
+  const separator = decoded.indexOf(':');
+  if (separator < 0 || decoded.slice(0, separator) !== username) return false;
+  const password = decoded.slice(separator + 1);
+  if (!/^[A-Za-z0-9_-]{43}$/.test(password)) return false;
+  const digest = createHash('sha256').update(password).digest();
+  return timingSafeEqual(digest, Buffer.from(passwordSha256, 'hex'));
+}
+
+/** Browser access grants pairing issuance only, never a runtime or device token. */
+export class ReviewPortalAccess {
+  constructor({ username, passwordSha256, now = Date.now }) {
+    if (username !== 'reviewer' || !/^[a-f0-9]{64}$/.test(passwordSha256 ?? '')) {
+      throw new Error('Invalid reviewer access configuration');
+    }
+    this.username = username;
+    this.passwordSha256 = passwordSha256;
+    this.now = now;
+    this.csrfKey = randomBytes(32);
+    this.failedSources = new WindowLimiter({ limit: 10, windowMs: 900_000, now });
+    this.failedTotal = new WindowLimiter({ limit: 200, windowMs: 900_000, capacity: 1, now });
+    this.pairSources = new WindowLimiter({ limit: 5, windowMs: 60_000, now });
+    this.pairTotal = new WindowLimiter({ limit: 20, windowMs: 60_000, capacity: 1, now });
+  }
+
+  authenticate(authorization, sourceId) {
+    if (matchesReviewerAuthorization(authorization, this.username, this.passwordSha256)) return 200;
+    if (!this.failedSources.allow(sourceId)) return 429;
+    if (!this.failedTotal.allow('failures')) return 429;
+    return 401;
+  }
+
+  createCsrf() {
+    const value = `${this.now()}.${randomBytes(16).toString('base64url')}`;
+    return `${value}.${createHmac('sha256', this.csrfKey).update(value).digest('base64url')}`;
+  }
+
+  acceptsCsrf(token) {
+    if (typeof token !== 'string' || token.length > 128) return false;
+    const match = /^(\d{1,16})\.([A-Za-z0-9_-]{22})\.([A-Za-z0-9_-]{43})$/.exec(token);
+    if (!match) return false;
+    const issuedAt = Number(match[1]);
+    if (!Number.isSafeInteger(issuedAt) || issuedAt > this.now()) return false;
+    if (this.now() - issuedAt >= CSRF_MS) return false;
+    const expected = createHmac('sha256', this.csrfKey).update(`${match[1]}.${match[2]}`).digest('base64url');
+    return timingSafeEqual(Buffer.from(match[3]), Buffer.from(expected));
+  }
+
+  allowPairing(sourceId) {
+    if (!this.pairSources.allow(sourceId)) return false;
+    return this.pairTotal.allow('pairings');
+  }
+}