openrod 0.0.0 → 0.1.0

package/server/setups.js

@@ -0,0 +1,172 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { randomUUID } from 'node:crypto'
+import { discover, readSkill, publicItem, hash, fail } from './setup-discovery.js'
+import { scopedStateDirectory } from './paths.js'
+
+export const usableSetup = (setup) => ({ ...setup, items: setup.items.filter(i => !i.disabled && !i.issues.length && (i.kind === 'skill' || i.config)) })
+export const SETUP_ID = /^[a-f0-9]{24}$/
+const TTL = 15 * 60_000
+export const MAX_SELECTION = 64 * 1024 * 1024
+// Tokens pin the reviewed snapshot. The browser cannot submit arbitrary paths,
+// executable configuration or replacement skill contents to the save endpoint.
+export function createSetupStore({ home = os.homedir(), dir = path.join(scopedStateDirectory(), 'setups'), now = Date.now, maxSelection = MAX_SELECTION, state = { scans: new Map(), previews: new Map(), edits: Promise.resolve() } } = {}) {
+  const { scans, previews } = state
+  const expire = (map) => { for (const [key, value] of map) if (value.expires < now()) map.delete(key); if (map.size >= 20) throw fail('Too many pending imports. Finish one or wait 15 minutes.', 429) }
+  const token = (map, id) => { const value = map.get(id); if (!value || value.expires < now()) throw fail('This preview expired. Scan and review again.', 409); return value }
+  const filename = (id) => { if (!SETUP_ID.test(id)) throw fail('Setup not found.', 404); return path.join(dir, id + '.json') }
+  async function get(id) { try { const setup = JSON.parse(await fs.readFile(filename(id), 'utf8')); if (hash(JSON.stringify(setup.items)) !== setup.revision) throw fail('Setup integrity check failed.', 409); return setup } catch (e) { if (e.code === 'ENOENT') throw fail('Setup not found.', 404); if (e instanceof SyntaxError) throw fail('Saved Setup is invalid. Restore it or import a new snapshot.', 409); throw e } }
+  const view = (s) => ({ ...s, items: s.items.map(publicItem) })
+  return {
+    get,
+    preview(id) { return token(previews, id) },
+    removeReviewItem(previewToken, itemId) {
+      const preview = token(previews, previewToken)
+      if (!preview.items.some(item => item.id === itemId)) throw fail('Import item not found.', 404)
+      const items = preview.items.filter(item => item.id !== itemId)
+      const credentials = Object.fromEntries(Object.entries(preview.credentials || {}).filter(([id]) => id !== itemId))
+      const review = this.stage(items, credentials)
+      previews.delete(previewToken)
+      return review
+    },
+    stage(items, credentials = {}) {
+      expire(previews)
+      const id = randomUUID(), revision = hash(JSON.stringify(items))
+      previews.set(id, { items, credentials, revision, expires: now() + TTL })
+      return { token: id, revision, items: items.map(publicItem) }
+    },
+    delete(id, revision, beforeDelete = async () => {}) {
+      const edit = state.edits.then(async () => {
+        const setup = await get(id)
+        if (revision !== setup.revision) throw fail('This Setup changed. Refresh the list before deleting it.', 409)
+        // Keep the setup retryable if policy cleanup or coverage validation fails.
+        await beforeDelete(setup)
+        await fs.unlink(filename(id))
+        return { deleted: id }
+      })
+      state.edits = edit.catch(() => {})
+      return edit
+    },
+    deleteItem(id, itemId, revision, beforeWrite = async () => {}) {
+      const edit = state.edits.then(async () => {
+        const setup = await get(id)
+        if (revision !== setup.revision) throw fail('This Setup changed. Close and reopen it before deleting a row.', 409)
+        if (!setup.items.some((item) => item.id === itemId)) throw fail('Setup item not found.', 404)
+        const items = setup.items.filter((item) => item.id !== itemId)
+        const updated = { ...setup, items, revision: hash(JSON.stringify(items)) }
+        const temporary = filename(id) + '.' + randomUUID() + '.tmp'
+        try {
+          await fs.writeFile(temporary, JSON.stringify(updated), { flag: 'wx', mode: 0o600 })
+          await beforeWrite(updated)
+          await fs.rename(temporary, filename(id))
+        } finally { await fs.rm(temporary, { force: true }) }
+        return view(updated)
+      })
+      state.edits = edit.catch(() => {})
+      return edit
+    },
+    async list() { const files = await fs.readdir(dir).catch((e) => { if (e.code === 'ENOENT') return []; throw e }); return Promise.all(files.filter((n) => /^[a-f0-9]{24}\.json$/.test(n)).map(async (n) => view(await get(n.slice(0, -5))))) },
+    async scan(sources) { expire(scans); const result = await discover({ sources, home }); const id = randomUUID(); scans.set(id, { ...result, expires: now() + TTL }); return { token: id, items: result.items.map(publicItem), warnings: result.warnings } },
+    async review(scanToken, ids) {
+      const scan = token(scans, scanToken)
+      if (!Array.isArray(ids) || !ids.length || ids.length > scan.items.length || new Set(ids).size !== ids.length) throw fail('Select one or more unique discovered items.')
+      const selected = ids.map((id) => { const item = scan.items.find((i) => i.id === id); if (!item) throw fail('Unknown discovery item.'); return item })
+      const items = [], credentials = {}
+      let selectionBytes = 2
+      for (const selectedItem of selected) {
+        const { root, _sourceCredentials, ...item } = selectedItem
+        if (_sourceCredentials) { credentials[item.id] = _sourceCredentials; item.sourceCredentialFields = Object.keys(_sourceCredentials) }
+        if (item.kind === 'skill') {
+          try { Object.assign(item, await readSkill(root, home)) } catch (e) { item.issues = [e.status ? e.message : 'Skill could not be read safely.']; item.files = [] }
+        }
+        selectionBytes += Buffer.byteLength(JSON.stringify(item)) + (items.length ? 1 : 0)
+        if (selectionBytes > maxSelection) throw fail(`This selection exceeds ${maxSelection / 1024 / 1024} MB. Select fewer skills and import the rest as a second setup.`)
+        items.push(item)
+      }
+      expire(previews); const id = randomUUID(); const revision = hash(JSON.stringify(items))
+      previews.set(id, { items, credentials, revision, expires: now() + TTL })
+      return { token: id, revision, items: items.map(publicItem) }
+    },
+    async file(previewToken, itemId, filename) {
+      const preview = token(previews, previewToken)
+      const f = preview.items.find((i) => i.id === itemId)?.files?.find((f) => f.path === filename)
+      if (!f) throw fail('Preview file not found.', 404)
+      return f.encoding === 'base64' ? { content: 'ZIP archive · copied as-is, not extracted or executed.\n\n' + (f.archiveEntries || []).map(entry => `${entry.path} · ${entry.bytes} B`).join('\n') } : { content: f.content }
+    },
+    buildSnapshot(source, items) {
+      const edit = state.edits.then(async () => {
+      const current = await get(source.id)
+      if (current.revision !== source.revision) throw fail('Setup changed during preparation. Review it and retry.', 409)
+      const id = hash('quick-setup:' + source.id + ':' + source.revision).slice(0, 24)
+      const setup = { id, name: source.name.slice(0, 65) + ' (prepared)', revision: hash(JSON.stringify(items)), createdAt: new Date(now()).toISOString(), owner: 'local operator', preparedFrom: { id: source.id, revision: source.revision }, items }
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 })
+      try { await fs.writeFile(filename(id), JSON.stringify(setup), { flag: 'wx', mode: 0o600 }) }
+      catch (e) { if (e.code !== 'EEXIST') throw e }
+      return view(await get(id))
+      })
+      state.edits = edit.catch(() => {})
+      return edit
+    },
+    async save(previewToken, name, acknowledged) {
+      if (acknowledged !== true) throw fail('Review the selected files and acknowledge the import.')
+      if (typeof name !== 'string' || !name.trim() || name.length > 80 || /[\x00-\x1f]/.test(name)) throw fail('Enter a Setup name, up to 80 characters.')
+      const preview = token(previews, previewToken)
+      const setup = { id: randomUUID().replaceAll('-', '').slice(0, 24), name: name.trim(), revision: preview.revision, createdAt: new Date(now()).toISOString(), owner: 'local operator', items: preview.items }
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 })
+      await fs.writeFile(filename(setup.id), JSON.stringify(setup), { flag: 'wx', mode: 0o600 })
+      previews.delete(previewToken)
+      return view(setup)
+    },
+  }
+}
+// Keep import tokens and the edit queue across reloads, but always recreate methods.
+const stateKey = Symbol.for('openshell.console.setup-store-contexts.v1')
+const states = globalThis[stateKey] ??= new Map()
+export function getSetupStore() {
+  const dir = path.join(scopedStateDirectory(), 'setups')
+  let state = states.get(dir)
+  if (!state) {
+    state = { scans: new Map(), previews: new Map(), edits: Promise.resolve() }
+    states.set(dir, state)
+  }
+  return createSetupStore({ dir, state })
+}
+export async function resolveSetups(ids = []) {
+  if (!Array.isArray(ids) || ids.length > 8 || new Set(ids).size !== ids.length) throw fail('Choose up to eight unique Setups.')
+  const setupStore = getSetupStore()
+  return Promise.all(ids.map((id) => setupStore.get(id)))
+}
+// Each saved Setup keeps one managed egress policy in step with its items.
+// A policy problem is reported, never undoes the Setup change.
+async function syncEgress(setupStore, id) {
+  try { const { syncSetupPolicy } = await import('./setup-egress.js'); return { egressPolicy: await syncSetupPolicy(await setupStore.get(id)) } }
+  catch (e) { return { egressPolicy: null, egressPolicyError: e.status ? e.message : 'The policy file could not be written.' } }
+}
+export async function setupRoute(method, parts, input) {
+  if (parts[0] !== 'setups') return undefined
+  const setupStore = getSetupStore()
+  if (method === 'GET' && parts.length === 3 && parts[1] === 'preparations') return (await import('./setup-preparation.js')).preparationStatus(parts[2])
+  if (method === 'POST' && parts.length === 4 && parts[1] === 'preparations' && parts[3] === 'cancel') return (await import('./setup-preparation.js')).cancelPreparation(parts[2])
+  if (method === 'POST' && parts.length === 3 && parts[2] === 'prepare-launch') return (await import('./setup-preparation.js')).prepareLaunch(setupStore, parts[1], input)
+  if (method === 'GET' && parts.length === 1) return setupStore.list()
+  if (method === 'POST' && parts.length === 3 && parts[2] === 'prepare') return setupStore.stage((await setupStore.get(parts[1])).items)
+  if (method === 'POST' && parts.length === 3 && parts[2] === 'delete') {
+    return setupStore.delete(parts[1], input.revision, async () => {
+      await (await import('./setup-egress.js')).removeSetupPolicy(parts[1])
+    })
+  }
+  if (method === 'POST' && parts.length === 3 && parts[2] === 'delete-item') {
+    return setupStore.deleteItem(parts[1], input.item, input.revision, async (updated) => {
+      await (await import('./setup-egress.js')).syncSetupPolicy(updated)
+    })
+  }
+  if (method !== 'POST' || parts.length !== 2) return undefined
+  if (parts[1] === 'prepare') return (await import('./setup-preparation.js')).prepareImport(setupStore, input)
+  if (parts[1] === 'scan') return setupStore.scan(input.sources)
+  if (parts[1] === 'review') return setupStore.review(input.token, input.ids)
+  if (parts[1] === 'remove-review-item') return setupStore.removeReviewItem(input.token, input.item)
+  if (parts[1] === 'file') return setupStore.file(input.token, input.item, input.path)
+  if (parts[1] === 'save') { const view = await setupStore.save(input.token, input.name, input.acknowledged); return { ...view, ...(await syncEgress(setupStore, view.id)) } }
+  return undefined
+}

package/server/ssh-hosts.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
+import { fail, findExecutable, runCli } from './openshell-cli.js'
+import { listSshHosts } from './remote-hosts.js'
+
+const DNS = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/
+const IPV6 = /^(?=(?:[^:]*:){2})[0-9A-Fa-f:]{2,45}$/
+const USER = /^[A-Za-z_][A-Za-z0-9._-]{0,31}$/
+const KEY_TYPE = /^(ssh-ed25519|ecdsa-sha2-nistp(?:256|384|521)|ssh-rsa|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com)$/
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/
+const TOKEN_TTL_MS = 5 * 60_000
+
+// Config values are written between quotes; reject anything that could end the
+// value or start another directive.
+const plain = value => typeof value === 'string' && !/[\0-\x1f\x7f"\\]/.test(value)
+const configQuote = value => `"${value}"`
+
+export const slugify = value => String(value ?? '').toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '')
+
+export const fingerprint = blob => `SHA256:${createHash('sha256').update(Buffer.from(blob, 'base64')).digest('base64').replace(/=+$/, '')}`
+
+// "host" or "user@host" -> { user, host }. Hostnames never start with "-", so
+// they cannot be read as ssh options.
+export function parseTarget(value) {
+  if (typeof value !== 'string') throw fail('Enter a hostname.')
+  const text = value.trim()
+  const at = text.lastIndexOf('@')
+  const user = at < 0 ? null : text.slice(0, at)
+  const host = (at < 0 ? text : text.slice(at + 1)).replace(/^\[(.*)\]$/, '$1')
+  if (user !== null && !USER.test(user)) throw fail('The user name before @ is not valid.')
+  if (!host) throw fail('Enter a hostname.')
+  if (!DNS.test(host) && !IPV6.test(host)) throw fail('The hostname is not valid. Use a name like host.example.com or an IP address.')
+  return { user, host }
+}
+
+export function createSshHostStore({ home = os.homedir(), keyscan, now = Date.now, existingHosts = () => listSshHosts({ homeDirectory: home }) } = {}) {
+  const directory = path.join(home, '.config/openrod')
+  const configFile = path.join(directory, 'ssh_config'), hostsFile = path.join(directory, 'known_hosts'), dataFile = path.join(directory, 'ssh_hosts.json')
+  const pending = new Map()
+  let queue = Promise.resolve()
+  const serial = task => { const result = queue.then(task, task); queue = result.catch(() => {}); return result }
+
+  async function readText(file) {
+    try {
+      const stat = await fs.lstat(file)
+      if (!stat.isFile() || stat.isSymbolicLink()) throw fail(`${path.basename(file)} must be a regular file.`, 409)
+      return await fs.readFile(file, 'utf8')
+    } catch (error) { if (error.code === 'ENOENT') return ''; throw error }
+  }
+  async function writeText(file, text) {
+    await readText(file)
+    const temp = `${file}.${randomUUID()}.tmp`
+    try { await fs.writeFile(temp, text, { mode: 0o600, flag: 'wx' }); await fs.rename(temp, file) } finally { await fs.rm(temp, { force: true }) }
+  }
+  async function load() {
+    const text = await readText(dataFile)
+    if (!text) return []
+    try {
+      const value = JSON.parse(text)
+      return Array.isArray(value) ? value.filter(item => item && typeof item.alias === 'string') : []
+    } catch { throw fail('Saved SSH hosts are unreadable. Remove ~/.config/openrod/ssh_hosts.json to start over.', 409) }
+  }
+
+  const render = hosts => hosts.map(({ alias, host, user, port, identityFile }) => [
+    `Host ${alias}`, `  HostName ${host}`, ...(user ? [`  User ${user}`] : []), ...(port ? [`  Port ${port}`] : []),
+    `  HostKeyAlias ${alias}`, `  UserKnownHostsFile ${configQuote(hostsFile)}`, '  GlobalKnownHostsFile /dev/null',
+    '  CheckHostIP no', '  UpdateHostKeys no',
+    ...(identityFile ? [`  IdentityFile ${configQuote(identityFile)}`, '  IdentitiesOnly yes'] : []),
+    '  PasswordAuthentication no', '  KbdInteractiveAuthentication no',
+  ].join('\n') + '\n').join('\n')
+
+  async function validate(input) {
+    if (!input || typeof input !== 'object') throw fail('Enter the connection details.')
+    const name = typeof input.name === 'string' ? input.name.trim() : ''
+    if (!name || name.length > 60) throw fail('Enter a display name of up to 60 characters.')
+    const alias = slugify(name)
+    if (!alias) throw fail('The display name needs at least one letter or number.')
+    const { user, host } = parseTarget(input.hostname)
+    let port = null
+    if (input.port !== undefined && input.port !== null && String(input.port).trim() !== '') {
+      port = Number(input.port)
+      if (!Number.isInteger(port) || port < 1 || port > 65535) throw fail('The SSH port must be a number from 1 to 65535.')
+    }
+    let identityFile = null
+    if (input.auth === 'identity') {
+      const raw = typeof input.identityFile === 'string' ? input.identityFile.trim() : ''
+      if (!raw) throw fail('Choose the private key file to use.')
+      const resolved = raw === '~' || raw.startsWith('~/') ? path.join(home, raw.slice(1)) : raw
+      if (!path.isAbsolute(resolved) || !plain(resolved)) throw fail('Enter the full path to a private key, for example ~/.ssh/id_ed25519.')
+      if (resolved.endsWith('.pub')) throw fail('That is a public key. Choose the matching private key file.')
+      let stat
+      try { stat = await fs.stat(resolved) } catch { throw fail('That key file does not exist.') }
+      if (!stat.isFile()) throw fail('That path is not a key file.')
+      identityFile = resolved
+    } else if (input.auth !== undefined && input.auth !== 'default') throw fail('Choose how to authenticate.')
+    return { name, alias, host, user, port, identityFile, auth: identityFile ? 'identity' : 'default' }
+  }
+
+  async function assertFree(alias) {
+    if ((await load()).some(item => item.alias === alias)) throw fail(`You already saved a connection called “${alias}”. Choose another name.`, 409)
+    if ((await existingHosts()).some(item => item.name === alias)) throw fail(`“${alias}” is already a host in your SSH configuration. Choose another name.`, 409)
+  }
+
+  async function scanKeys({ host, port }) {
+    const run = keyscan ?? (async args => {
+      const executable = findExecutable('ssh-keyscan')
+      if (!executable) throw fail('The ssh-keyscan tool is missing. Install the OpenSSH client and try again.', 409)
+      return runCli(executable, args, { timeoutMs: 15_000, outputLimit: 64 * 1024 })
+    })
+    const result = await run(['-T', '8', '-t', 'ed25519,ecdsa,rsa', ...(port ? ['-p', String(port)] : []), '--', host])
+    if (result.timedOut) throw fail(`Timed out reaching ${host}. Check the hostname, the port and your network.`, 504)
+    const keys = []
+    for (const line of String(result.stdout).split('\n')) {
+      if (!line || line.startsWith('#')) continue
+      const [, type, blob] = line.trim().split(/\s+/)
+      if (KEY_TYPE.test(type ?? '') && BASE64.test(blob ?? '') && !keys.some(key => key.type === type)) keys.push({ type, blob, fingerprint: fingerprint(blob) })
+    }
+    if (!keys.length) throw fail(`Couldn’t read a host key from ${host}. Check the hostname and port, and that SSH is running there.`, 502)
+    return keys
+  }
+
+  return {
+    directory, configFile, hostsFile,
+    list: async () => (await load()).map(({ alias, name, host, user, port, identityFile }) => ({ alias, name, host, user, port, identityFile })),
+    // Step 1: validate, read the host's keys and hold them until the user confirms.
+    async scan(input) {
+      const value = await validate(input)
+      await assertFree(value.alias)
+      const keys = await scanKeys(value)
+      for (const [token, entry] of pending) if (entry.expires <= now()) pending.delete(token)
+      const token = randomBytes(24).toString('base64url')
+      pending.set(token, { value, keys, expires: now() + TOKEN_TTL_MS })
+      return { token, alias: value.alias, host: value.host, user: value.user, port: value.port, fingerprints: keys.map(({ type, fingerprint }) => ({ type, fingerprint })) }
+    },
+    // Step 2: the user trusted exactly the keys shown in step 1.
+    add: token => serial(async () => {
+      const entry = pending.get(token)
+      if (!entry || entry.expires <= now()) { pending.delete(token); throw fail('This confirmation expired. Start again.', 409) }
+      const { value, keys } = entry
+      await assertFree(value.alias)
+      // The user's ~/.ssh/config is checked and updated before OpenRod's own files,
+      // so a config we cannot edit leaves no half-saved host behind. It is handled
+      // as bytes: it need not be UTF-8 and is kept unchanged after the Include.
+      await fs.mkdir(path.join(home, '.ssh'), { recursive: true, mode: 0o700 })
+      const userConfig = path.join(home, '.ssh/config'), include = `Include ${configQuote(configFile)}`
+      const current = await fs.readFile(userConfig).catch(error => {
+        if (error.code === 'ENOENT') return Buffer.alloc(0)
+        throw fail(`OpenRod can't read ~/.ssh/config (${error.code ?? error.message}).`, 409)
+      })
+      const hasInclude = current.toString('latin1').split('\n').some(line => line.replace(/\r$/, '') === Buffer.from(include).toString('latin1'))
+      if (!hasInclude) {
+        const stat = await fs.lstat(userConfig).catch(error => { if (error.code === 'ENOENT') return null; throw error })
+        if (stat && !stat.isFile()) throw fail(`~/.ssh/config is a symlink or not a regular file, so OpenRod won't edit it. Add this line at the top of the file it points to, then try again: ${include}`, 409)
+      }
+      await fs.mkdir(directory, { recursive: true, mode: 0o700 })
+      const stat = await fs.lstat(directory)
+      if (stat.isSymbolicLink() || !stat.isDirectory()) throw fail('~/.config/openrod must be a regular directory.', 409)
+      await fs.chmod(directory, 0o700)
+      const hosts = [...await load(), { alias: value.alias, name: value.name, host: value.host, user: value.user, port: value.port, identityFile: value.identityFile }]
+      const known = (await readText(hostsFile)).split('\n').filter(line => line && !line.startsWith(`${value.alias} `))
+      // An Include after a Host line would only apply to that Host, so it goes first.
+      // Including a file that does not exist yet is harmless to ssh.
+      if (!hasInclude) await writeText(userConfig, Buffer.concat([Buffer.from(`${include}\n`), current])).catch(error => {
+        throw error.status ? error : fail(`OpenRod can't update ~/.ssh/config (${error.code ?? error.message}). Add this line at its top yourself, then try again: ${include}`, 409)
+      })
+      await writeText(hostsFile, [...known, ...keys.map(key => `${value.alias} ${key.type} ${key.blob}`)].join('\n') + '\n')
+      await writeText(dataFile, JSON.stringify(hosts, null, 2) + '\n')
+      await writeText(configFile, render(hosts))
+      pending.delete(token)
+      return { alias: value.alias, name: value.name }
+    }),
+    remove: alias => serial(async () => {
+      const hosts = await load()
+      if (!hosts.some(item => item.alias === alias)) throw fail('That connection is not saved here.', 404)
+      const rest = hosts.filter(item => item.alias !== alias)
+      await writeText(dataFile, JSON.stringify(rest, null, 2) + '\n')
+      await writeText(configFile, render(rest))
+      await writeText(hostsFile, (await readText(hostsFile)).split('\n').filter(line => line && !line.startsWith(`${alias} `)).map(line => `${line}\n`).join(''))
+      return { alias }
+    }),
+  }
+}

package/server/ssh.js

@@ -0,0 +1,153 @@
+import { execFile, spawn } from 'node:child_process'
+import { rmSync } from 'node:fs'
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { connectionPlan, nativeSshCommand, persistentSessionArgv, persistentTerminals } from '../src/lib/sandbox-session.js'
+import { CONFIG_DIR, gateway, sandboxView } from './gateway.js'
+import { fail, openshellBinary, reasonFrom, runOpenShell, shellQuote, sshBinary } from './openshell-cli.js'
+
+const NAME = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/
+const MODES = new Set(['ssh', 'exec', 'attach'])
+
+async function loadContext(name) {
+  const { client, target, workspace, workspaceScope } = await gateway()
+  const sandbox = sandboxView((await client.raw.getSandbox({ name, workspaceScope })).sandbox)
+  return { sandbox, target, workspace }
+}
+
+export function connectionView(sandbox, target, {
+  env = process.env,
+  platform = process.platform,
+  workspace = sandbox.workspace || 'default',
+} = {}) {
+  const cli = openshellBinary(env)
+  const ssh = sshBinary(env)
+  const terminalSupported = platform === 'darwin' || platform === 'linux'
+  const executable = cli ?? env.OPENSHELL_BIN ?? 'openshell'
+  const ready = sandbox.phase === 'ready'
+  const configHome = env.XDG_CONFIG_HOME ?? path.dirname(CONFIG_DIR)
+  const modes = ready ? {
+    ssh: connectionPlan(sandbox, { gateway: target.name, workspace, executable, configHome, remote: persistentTerminals(target, sandbox), ssh: ssh ?? 'ssh', mode: 'ssh' }),
+    exec: connectionPlan(sandbox, { gateway: target.name, workspace, executable, configHome, remote: persistentTerminals(target, sandbox) }),
+    ...(sandbox.tty ? { attach: connectionPlan(sandbox, { gateway: target.name, workspace, executable, configHome, mode: 'attach' }) } : {}),
+  } : {}
+  return {
+    ready,
+    gateway: { name: target.name, endpoint: target.endpoint, remote: target.remote, workspace },
+    cliInstalled: Boolean(cli),
+    sshInstalled: Boolean(ssh),
+    terminalSupported,
+    canOpenTerminal: ready && Boolean(cli) && Boolean(ssh) && terminalSupported,
+    alias: `openshell-${sandbox.name}.${workspace}`,
+    defaultMode: 'ssh',
+    modes,
+  }
+}
+
+export function launchNativeTerminal(command, {
+  platform = process.platform,
+  exec = execFile,
+  spawnProcess = spawn,
+  onFailure,
+} = {}) {
+  if (platform === 'darwin') {
+    const escaped = command.replace(/[\\"]/g, '\\$&')
+    const script = `tell application "Terminal" to do script "${escaped}"`
+    return new Promise((resolve, reject) => exec('osascript', ['-e', script, '-e', 'tell application "Terminal" to activate'], { timeout: 10_000 },
+      (error) => error
+        ? reject(fail('Could not open Terminal. Allow the console to control Terminal in System Settings → Privacy & Security → Automation.', 502))
+        : resolve()))
+  }
+  if (platform === 'linux') {
+    return new Promise((resolve, reject) => {
+      const child = spawnProcess('x-terminal-emulator', ['-e', 'sh', '-c', command], { detached: true, shell: false, stdio: 'ignore' })
+      child.once('error', () => reject(fail('No terminal emulator found. Copy the command instead.', 501)))
+      child.once('exit', (code) => { if (code !== 0) onFailure?.() })
+      child.once('spawn', () => { child.unref(); resolve() })
+    })
+  }
+  throw fail('Opening a terminal is supported on macOS and Linux only.', 501)
+}
+
+function requireReady(sandbox) {
+  if (sandbox.phase !== 'ready') throw fail('This sandbox is not running.', 409)
+}
+
+async function generateConfig(name, target, workspace, dependencies) {
+  const result = await (dependencies.runOpenShell ?? runOpenShell)(['sandbox', 'ssh-config', name], {
+    gateway: target.name,
+    workspace,
+    timeoutMs: 15_000,
+    outputLimit: 128 * 1024,
+    env: dependencies.env,
+  })
+  if (result.timedOut) throw fail('Generating SSH config timed out.', 504)
+  if (result.outputExceeded) throw fail('The generated SSH config is too large.', 502)
+  if (result.code !== 0) throw fail(reasonFrom(`${result.stderr}${result.stdout}`), 502)
+  const config = result.stdout.trim()
+  if (!config) throw fail('The openshell CLI returned an empty SSH config.', 502)
+  return `${config}\n`
+}
+
+async function openDirectSsh(sandbox, target, workspace, dependencies) {
+  const config = await generateConfig(sandbox.name, target, workspace, dependencies)
+  const directory = await mkdtemp(path.join(dependencies.tempDirectory ?? os.tmpdir(), 'openshell-ssh-'))
+  try {
+    await chmod(directory, 0o700)
+    await writeFile(path.join(directory, 'config'), config, { mode: 0o600, flag: 'wx' })
+    const command = nativeSshCommand({
+      alias: `openshell-${sandbox.name}.${workspace}`,
+      ssh: sshBinary(dependencies.env),
+      directory,
+      configHome: dependencies.env?.XDG_CONFIG_HOME ?? path.dirname(CONFIG_DIR),
+      remoteArgv: persistentTerminals(target, sandbox) ? persistentSessionArgv('shell') : null,
+    })
+    await (dependencies.launchTerminal ?? launchNativeTerminal)(command, {
+      ...dependencies,
+      // Some Linux emulators spawn successfully, then fail before running sh.
+      onFailure: () => rmSync(directory, { recursive: true, force: true }),
+    })
+  } catch (error) {
+    await rm(directory, { recursive: true, force: true })
+    throw error
+  }
+}
+
+export async function sshRoute(method, parts, input, dependencies = {}) {
+  if (parts[0] !== 'sandboxes' || parts.length !== 3 || !NAME.test(parts[1] ?? '')) return undefined
+  const [, name, action] = parts
+  if (!['ssh', 'ssh-open', 'ssh-config'].includes(action)) return undefined
+
+  const context = dependencies.loadSandbox
+    ? { sandbox: await dependencies.loadSandbox(name), target: dependencies.target }
+    : await (dependencies.loadContext ?? loadContext)(name)
+  const { sandbox, target, workspace = sandbox.workspace || 'default' } = context
+
+  if (method === 'GET' && action === 'ssh') return connectionView(sandbox, target, { ...dependencies, workspace })
+  if (method !== 'POST') return undefined
+  requireReady(sandbox)
+
+  if (action === 'ssh-open') {
+    const mode = String(input?.mode ?? 'ssh')
+    if (!MODES.has(mode)) throw fail('Unknown connection mode.')
+    const view = connectionView(sandbox, target, { ...dependencies, workspace })
+    const plan = view.modes[mode]
+    if (!plan) throw fail('This sandbox has no canonical TTY session to attach.', 409)
+    if (!view.cliInstalled) throw fail('The openshell CLI is not installed on this machine.', 409)
+    if (!view.sshInstalled) throw fail('OpenSSH is not installed on this machine.', 409)
+    if (!view.terminalSupported) throw fail('Opening a terminal is supported on macOS and Linux only.', 501)
+    if (mode === 'ssh') await openDirectSsh(sandbox, target, workspace, dependencies)
+    else await (dependencies.launchTerminal ?? launchNativeTerminal)(plan.command, dependencies)
+    return { ok: true, mode }
+  }
+
+  if (action === 'ssh-config') {
+    const config = await generateConfig(name, target, workspace, dependencies)
+    const alias = `openshell-${sandbox.name}.${workspace}`
+    const configHome = dependencies.env?.XDG_CONFIG_HOME ?? path.dirname(CONFIG_DIR)
+    return { config, alias, command: `env ${shellQuote(`XDG_CONFIG_HOME=${configHome}`)} ssh ${shellQuote(alias)}` }
+  }
+
+  return undefined
+}

package/server/start.js

@@ -0,0 +1,71 @@
+import {createCloudConnections} from './cloud-connections.js'
+import { firebaseMachines, MACHINE_DATABASE } from './machines.js'
+import { createHandoffs, cloudRouter } from './cloud-proxy.js'
+import http from 'node:http'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import fs from 'node:fs'
+import connect from 'connect'
+import serveStatic from 'serve-static'
+import { createSessionRevocations } from './session-revocations.js'
+import { openshellApi } from './api.js'
+import { cloudConfig, createSecurity, firebaseAuth, requestPath } from './security.js'
+
+export async function createConsoleServer({ config = cloudConfig(), auth, machines, handoffs, connections, dist = path.resolve(import.meta.dirname, '../dist') } = {}) {
+  if (!fs.existsSync(path.join(dist, 'index.html'))) throw Error('Build the UI with npm run build before starting the server')
+  const revocations = config.mode === 'cloud' ? createSessionRevocations(path.resolve(import.meta.dirname, '../.state/sessions.sqlite')) : undefined
+  auth ??= config.mode === 'cloud' ? await firebaseAuth(config) : undefined
+  const security = createSecurity(config, auth, revocations)
+  const app = connect()
+  const server = http.createServer(app)
+  app.use((req, res, next) => {
+    res.setHeader('X-Content-Type-Options', 'nosniff')
+    res.setHeader('Referrer-Policy', 'no-referrer')
+    res.setHeader('X-Frame-Options', 'DENY')
+    if (config.mode === 'cloud') {
+      res.setHeader('Strict-Transport-Security', 'max-age=31536000')
+      res.setHeader('Cross-Origin-Opener-Policy', new URL(req.url, 'http://local').searchParams.get('handoff') === '1' ? 'unsafe-none' : 'same-origin-allow-popups')
+      res.setHeader('Content-Security-Policy', `default-src 'self'; script-src 'self' https://apis.google.com; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data:; connect-src 'self' wss://${new URL(config.origin).host} https://identitytoolkit.googleapis.com https://securetoken.googleapis.com https://www.googleapis.com https://${config.firebase.authDomain}; frame-src https://${config.firebase.authDomain}; object-src 'none'; base-uri 'self'; frame-ancestors 'none'`)
+    }
+    next()
+  })
+  if (config.mode === 'cloud') {
+    if (!handoffs || !connections) {
+      const {getApps} = await import('firebase-admin/app'), {getFirestore} = await import('firebase-admin/firestore')
+      const db=getFirestore(getApps()[0], MACHINE_DATABASE)
+      handoffs ??= createHandoffs(db)
+      connections ??= createCloudConnections(db,auth,{org:config.org,isSessionRevoked:security.isSessionRevoked})
+    }
+    const routes = cloudRouter(security, machines ?? await firebaseMachines(config), handoffs, auth, {connections})
+    app.use(routes.publicRoutes)
+    app.use(security.middleware)
+    app.use(routes.protectedRoutes)
+    server.on('upgrade', routes.upgrade)
+  } else openshellApi(security).configureServer({ middlewares: app, httpServer: server, config: { logger: { info: console.info } } })
+  app.use('/healthz', (req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('ready') })
+  const upgradePaths = config.mode === 'cloud'
+    ? ['/api/os/terminal', '/api/cloud/local-connect/os/terminal', '/api/cloud/local-connect/os/ssh']
+    : config.mode === 'local' ? ['/api/os/terminal', '/api/os/ssh', '/api/remote/os/terminal', '/api/remote/os/ssh'] : ['/api/os/terminal', '/api/os/ssh']
+  server.on('upgrade', (req, socket) => {
+    try { if (!upgradePaths.includes(requestPath(req))) socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n') }
+    catch { /* The API upgrade handler rejects malformed targets. */ }
+  })
+  app.use(serveStatic(dist, { index: 'index.html', dotfiles: 'deny', maxAge: 0 }))
+  app.use((req, res) => { res.writeHead(404); res.end('Not found') })
+  server.once('close', () => revocations?.close())
+  server.requestTimeout = 35 * 60000
+  server.headersTimeout = 15000
+  return server
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const server = await createConsoleServer()
+    const port = Number(process.env.OPENROD_PORT ?? 4600)
+    if (!Number.isInteger(port) || port < 1024 || port > 65535) throw Error('OPENROD_PORT must be between 1024 and 65535')
+    const address = process.env.OPENROD_MODE === 'worker' ? '0.0.0.0' : '127.0.0.1'
+    // Local mode prints only the tokened link (from the API plugin); a bare URL would just hit the token wall.
+    const mode = process.env.OPENROD_MODE ?? 'local'
+    server.listen(port, address, () => { if (mode !== 'local') console.info(`OpenRod ${mode} console listening on ${address}:${port}`) })
+    for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => { server.closeAllConnections(); server.close(() => process.exit(0)); setTimeout(() => process.exit(1), 5000).unref() })
+  } catch (error) { console.error(error.message); process.exitCode = 1 }
+}