openrod 0.0.0 → 0.1.0

package/server/cli.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { createServer } from 'node:http'
+import fs from 'node:fs/promises'
+import { createReadStream } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { spawn } from 'node:child_process'
+import { parseArgs } from 'node:util'
+
+const HELP = `Usage: openrod [--host 127.0.0.1] [--port 4600] [--open | --no-open]
+
+Serve OpenRod locally for local sandboxes or configured SSH hosts.
+Open the printed link: it carries a secret that changes on every start.
+
+  --host <host>  Loopback only: 127.0.0.1, localhost, or ::1
+  --port <port>  HTTP port from 1 to 65535 (default: 4600)
+  --open         Open the console in your default browser
+  --no-open      Do not open a browser (default)
+  --help, -h     Show this help
+  --version, -v  Show the installed version
+
+Mutable data: OPENSHELL_CONSOLE_DATA_DIR, or
+  $XDG_STATE_HOME/openshell-console (~/.local/state/openshell-console).
+Requires Node.js >=22.13.0. SSH hosts need local OpenSSH and OpenSSL,
+plus a running Docker Engine on the remote Linux host. A missing local
+gateway executable is downloaded and checksum-verified on supported platforms.
+`
+
+export function parseOptions(args = process.argv.slice(2)) {
+  const { values } = parseArgs({ args, options: {
+    host: { type: 'string', default: '127.0.0.1' },
+    port: { type: 'string', default: '4600' },
+    open: { type: 'boolean' }, 'no-open': { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+  } })
+  if (!['127.0.0.1', 'localhost', '::1'].includes(values.host)) throw new Error('--host must be a loopback address: 127.0.0.1, localhost, or ::1.')
+  if (!/^\d+$/.test(values.port) || Number(values.port) < 1 || Number(values.port) > 65535) throw new Error('--port must be an integer from 1 to 65535.')
+  if (values.open && values['no-open']) throw new Error('Choose either --open or --no-open, not both.')
+  return { host: values.host, port: Number(values.port), open: Boolean(values.open), help: Boolean(values.help), version: Boolean(values.version) }
+}
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.avif': 'image/avif', '.ico': 'image/x-icon',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf', '.txt': 'text/plain; charset=utf-8',
+  '.wasm': 'application/wasm', '.map': 'application/json; charset=utf-8',
+}
+
+export function staticMiddleware(directory) {
+  return async (req, res) => {
+    if (!['GET', 'HEAD'].includes(req.method)) { res.writeHead(405, { Allow: 'GET, HEAD' }).end(); return }
+    let pathname
+    try { pathname = decodeURIComponent((req.url ?? '/').split('?', 1)[0]) }
+    catch { res.writeHead(400).end(); return }
+    if (!pathname.startsWith('/') || pathname.includes('\\') || pathname.includes('\0') || pathname.split('/').some((part) => part.startsWith('.'))) {
+      res.writeHead(400).end(); return
+    }
+    const resolveFile = async (relative) => {
+      const file = await fs.realpath(path.join(directory, relative))
+      if (!file.startsWith(`${directory}${path.sep}`)) return null
+      const stat = await fs.stat(file)
+      return stat.isFile() ? { file, stat } : null
+    }
+    let entry
+    try { entry = await resolveFile(pathname === '/' ? 'index.html' : pathname.slice(1)) }
+    catch (error) { if (!['ENOENT', 'ENOTDIR'].includes(error.code)) throw error }
+    if (!entry && !path.extname(pathname) && !pathname.startsWith('/assets/') && (req.headers.accept ?? '').includes('text/html')) entry = await resolveFile('index.html')
+    if (!entry) { res.writeHead(404).end(); return }
+    const { file, stat } = entry
+    const etag = `W/"${stat.size.toString(16)}-${Math.trunc(stat.mtimeMs).toString(16)}"`
+    const immutable = /^\/assets\/[^/]+-[\w-]{8,}\.[a-z\d]+$/i.test(pathname)
+    const headers = {
+      'Content-Type': TYPES[path.extname(file).toLowerCase()] || 'application/octet-stream',
+      'Cache-Control': immutable ? 'public, max-age=31536000, immutable' : 'no-cache',
+      'X-Content-Type-Options': 'nosniff', ETag: etag,
+    }
+    if (req.headers['if-none-match'] === etag) { res.writeHead(304, headers).end(); return }
+    res.writeHead(200, { ...headers, 'Content-Length': stat.size })
+    if (req.method === 'HEAD') { res.end(); return }
+    const stream = createReadStream(file)
+    stream.on('error', (error) => res.destroy(error))
+    res.on('close', () => stream.destroy())
+    stream.pipe(res)
+  }
+}
+
+function openBrowser(url, logger) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url]
+  const child = spawn(command, args, { stdio: 'ignore', detached: true })
+  child.once('error', (error) => logger.warn(`Could not open a browser: ${error.message}. Open ${url} manually.`))
+  child.once('exit', (code) => { if (code) logger.warn(`Browser opener exited with status ${code}. Open ${url} manually.`) })
+  child.unref()
+}
+
+export async function startConsole(options = parseOptions([]), logger = console) {
+  const { host, port } = parseOptions(['--host', options.host ?? '127.0.0.1', '--port', String(options.port ?? 4600)])
+  let directory
+  try {
+    directory = await fs.realpath(path.resolve(import.meta.dirname, '../dist'))
+    await fs.access(path.join(directory, 'index.html'))
+  } catch { throw new Error('Built frontend is missing. Run npm run build from the source checkout before starting or packaging the console.') }
+  const { createOpenShellApi, isLocalApiRequest } = await import('./api.js')
+  const { createLaunchToken, tokenUrl } = await import('./launch-token.js')
+  const token = createLaunchToken()
+  const serveStatic = staticMiddleware(directory)
+  const connections = new Set()
+  let api
+  const server = createServer((req, res) => {
+    if (!isLocalApiRequest(req)) { res.writeHead(403).end(); return }
+    const failed = (error) => {
+      logger.error(`Request failed: ${error.message}`)
+      if (res.headersSent) res.destroy(error)
+      else res.writeHead(500, { 'Content-Type': 'text/plain' }).end('Request failed')
+    }
+    Promise.resolve(api.middleware(req, res, () => serveStatic(req, res))).catch(failed)
+  })
+  server.on('connection', (socket) => { connections.add(socket); socket.once('close', () => connections.delete(socket)) })
+  // Bind before starting collectors, so a port collision has no side effects.
+  await new Promise((resolve, reject) => {
+    const error = (error) => {
+      if (error.code === 'EADDRINUSE') reject(new Error(`Port ${port} is already in use on ${host}. Stop the other console or choose --port <port>.`))
+      else reject(error)
+    }
+    server.once('error', error)
+    server.listen(port, host === 'localhost' ? '127.0.0.1' : host, () => { server.off('error', error); resolve() })
+  })
+  try { api = createOpenShellApi({ httpServer: server, logger, token }) }
+  catch (error) { server.close(); throw error }
+  server.on('upgrade', (req, socket) => { if ((req.url ?? '').split('?', 1)[0] !== '/api/os/terminal') socket.destroy() })
+  let closing
+  const close = () => {
+    if (closing) return closing
+    closing = (async () => {
+      const apiClosed = api.close()
+      const timer = setTimeout(() => { for (const socket of connections) socket.destroy() }, 5000)
+      timer.unref()
+      try { await Promise.all([apiClosed, new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()))]) }
+      finally { clearTimeout(timer) }
+    })()
+    return closing
+  }
+  // The link carries this launch's secret; it changes on every restart.
+  const url = tokenUrl(host, port, token)
+  logger.info(`OpenRod console (open this link): ${url}`)
+  if (options.open) openBrowser(url, logger)
+  return { server, url, close }
+}
+
+async function main() {
+  const options = parseOptions()
+  if (options.help) { process.stdout.write(HELP); return }
+  if (options.version) { console.log(JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf8')).version); return }
+  const runtime = await startConsole(options)
+  let stopping = false
+  const shutdown = () => {
+    if (stopping) return
+    stopping = true
+    runtime.close().catch((error) => { console.error(`Shutdown failed: ${error.message}`); process.exitCode = 1 })
+  }
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(await fs.realpath(process.argv[1])).href) {
+  main().catch((error) => { console.error(`openrod: ${error.message}`); process.exitCode = 1 })
+}

package/server/cloud-connections.js

@@ -0,0 +1,56 @@
+import {createHash,randomBytes} from 'node:crypto'
+const digest=value=>createHash('sha256').update(value).digest('hex')
+const fail=(message,status=401)=>Object.assign(Error(message),{status})
+const TOKEN=/^[a-f0-9]{64}\.[a-f0-9]{64}$/
+const NONCE=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
+export function validateLocalConnection(value={}) {
+ let url
+ try{url=new URL(value.origin)}catch{throw fail('Invalid local connection',400)}
+ if(url.origin!==value.origin||url.protocol!=='http:'||!['localhost','127.0.0.1','[::1]'].includes(url.hostname)||!url.port||Number(url.port)<1||Number(url.port)>65535||!NONCE.test(value.nonce??'')||!/^[a-f0-9]{64}$/.test(value.challenge??''))throw fail('Invalid local connection',400)
+ return {origin:value.origin,nonce:value.nonce,challenge:value.challenge}
+}
+export function createCloudConnections(db,auth,{org,now=Date.now,isSessionRevoked=()=>false}={}) {
+ const records=db.collection('localConnections')
+ const refFor=token=>{if(typeof token!=='string'||!TOKEN.test(token))throw fail('Cloud connection expired. Reconnect local OpenRod.');return records.doc(token.split('.')[0])}
+ async function identity(row){
+  if(!row||row.revoked||row.expires<=now()||isSessionRevoked(row.sessionHash))throw fail('Cloud connection expired. Reconnect local OpenRod.')
+  const user=await auth.getUser(row.uid)
+  if(user.uid!==row.uid||user.disabled||!user.emailVerified||!user.providerData?.some(p=>p.providerId==='google.com'))throw fail('Google account unavailable',403)
+  return {uid:user.uid,email:user.email,org,role:'member',expires:row.expires}
+ }
+ return {
+  async authorize(owner,input,sessionHash){
+   const bound=validateLocalConnection(input)
+   if(!owner?.uid||!Number.isFinite(owner.expires)||owner.expires<=now()||!/^[a-f0-9]{64}$/.test(sessionHash??''))throw fail('Sign in to connect local OpenRod')
+   const id=digest(owner.uid),code=`${id}.${randomBytes(32).toString('hex')}`
+   const pending={...bound,uid:owner.uid,sessionHash,codeHash:digest(code),codeExpires:Math.min(owner.expires,now()+300000),expires:Math.min(owner.expires,now()+3600000),used:false,revoked:false}
+   // An unredeemed browser sign-in must not replace a working local grant.
+   // Keep the active record until verifier and account checks both succeed.
+   await db.runTransaction(async tx=>{const ref=records.doc(id),snap=await tx.get(ref);tx.set(ref,{...(snap.exists?snap.data():{expires:pending.expires}),pending})})
+   return code
+  },
+  async redeem(code,verifier,nonce){
+   const ref=refFor(code),token=`${ref.id}.${randomBytes(32).toString('hex')}`
+   if(typeof verifier!=='string'||verifier.length>256)throw fail('Invalid local connection verifier')
+   const user=await db.runTransaction(async tx=>{
+    const snap=await tx.get(ref),stored=snap.exists?snap.data():null
+    // Accept pre-upgrade pending codes as well as the nested pending format.
+    const row=stored?.pending??stored
+    if(!row||row.used||row.revoked||row.codeExpires<=now()||row.codeHash!==digest(code)||row.challenge!==digest(verifier)||row.nonce!==nonce)throw fail('Local sign-in code expired or already used')
+    const user=await identity(row)
+    tx.set(ref,{...row,used:true,codeHash:null,challenge:null,grantHash:digest(token)})
+    return user
+   })
+   return {token,expires:user.expires,user:{uid:user.uid,email:user.email}}
+  },
+  async authenticate(token){
+   const snap=await refFor(token).get(),row=snap.exists?snap.data():null
+   if(!row?.used||row.grantHash!==digest(token))throw fail('Cloud connection expired. Reconnect local OpenRod.')
+   return identity(row)
+  },
+  async revoke(token){
+   const ref=refFor(token)
+   await db.runTransaction(async tx=>{const snap=await tx.get(ref),row=snap.exists?snap.data():null;if(row?.grantHash===digest(token))tx.update(ref,{revoked:true})})
+  },
+ }
+}

package/server/cloud-origin.js

@@ -0,0 +1,11 @@
+// Cloud is unavailable unless OPENROD_CLOUD_ORIGIN names an HTTPS origin; local endpoints then refuse before contacting any cloud service.
+export const CLOUD_SOON = 'Cloud is coming soon.'
+export function cloudOrigin(env = process.env) {
+  const value = env.OPENROD_CLOUD_ORIGIN?.trim()
+  if (!value) return null
+  let url
+  try { url = new URL(value) } catch { throw Error('OPENROD_CLOUD_ORIGIN must be an HTTPS origin without a path') }
+  if (url.protocol !== 'https:' || url.origin !== value || url.username || url.password) throw Error('OPENROD_CLOUD_ORIGIN must be an HTTPS origin without a path')
+  return value
+}
+export const cloudUnavailable = () => Object.assign(new Error(CLOUD_SOON), { status: 409 })

package/server/cloud-proxy.js

@@ -0,0 +1,122 @@
+import http from 'node:http'
+import fs from 'node:fs'
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import { identityContext, requestPath } from './security.js'
+import {readJson,safeWorkspaceTarget} from './remote-http.js'
+import { signWorkerRequest } from './worker-auth.js'
+const fail=(message,status=503)=>Object.assign(Error(message),{status})
+const json=(res,status,value)=>{res.writeHead(status,{'Content-Type':'application/json','Cache-Control':'no-store'});res.end(JSON.stringify(value))}
+const hash=value=>createHash('sha256').update(value).digest('hex')
+export function createHandoffs(db,now=()=>Date.now()) {
+ return {
+  async issue(identity,name){const token=`${name}.${randomBytes(32).toString('hex')}`;await db.collection('handoffs').doc(name).set({uid:identity.uid,hash:hash(token),expires:Math.min(identity.expires,now()+300000),used:false});return token},
+  async consume(token){
+   if(typeof token!=='string'||!/^openrod-user-[a-f0-9]{24}\.[a-f0-9]{64}$/.test(token))throw fail('Invalid cloud transfer ticket',401)
+   return db.runTransaction(async tx=>{const ref=db.collection('handoffs').doc(token.split('.')[0]),s=await tx.get(ref),r=s.exists?s.data():null;if(!r||r.used||r.expires<=now()||r.hash!==hash(token))throw fail('Cloud transfer ticket expired or already used',401);tx.update(ref,{used:true});return r.uid})
+  },
+ }
+}
+export function proxyWorker(req,res,record,identity,config,{target=req.url,maxBytes=36*1024*1024}={}) {
+ const headers={host:config.host,origin:config.origin,'x-openshell-console':'1','x-openrod-worker-auth':signWorkerRequest(record.key,identity,{method:req.method,url:target})}
+ for(const key of ['content-type','content-length','accept','range','x-openshell-context','x-openshell-location'])if(req.headers[key])headers[key]=req.headers[key]
+ return new Promise(resolve=>{
+  const upstream=http.request({hostname:record.address,port:record.port??4600,path:target,method:req.method,headers},response=>{
+   const safe={...response.headers};delete safe['set-cookie'];delete safe['connection'];delete safe['transfer-encoding']
+   res.writeHead(response.statusCode,safe);response.pipe(res);response.once('end',resolve);response.once('error',()=>{res.destroy();resolve()})
+  })
+  upstream.setTimeout(35*60000,()=>upstream.destroy())
+  let bytes=0
+  req.on('data',chunk=>{bytes+=chunk.length;if(bytes>maxBytes){upstream.destroy();if(!res.headersSent)json(res,413,{error:'Transfer exceeds the upload limit'});else res.destroy()}})
+  upstream.once('error',()=>{if(!res.headersSent)json(res,503,{error:'Your cloud machine is unavailable. Try again shortly.'});else res.destroy();resolve()})
+  res.once('close',()=>upstream.destroy());req.pipe(upstream)
+ })
+}
+export function proxyWorkerSocket(req,socket,head,record,identity,config,{target=req.url}={}) {
+ const upstream=http.request({hostname:record.address,port:record.port??4600,path:target,method:'GET',headers:{host:config.host,origin:config.origin,upgrade:'websocket',connection:'Upgrade','sec-websocket-key':req.headers['sec-websocket-key'],'sec-websocket-version':req.headers['sec-websocket-version'],'x-openrod-worker-auth':signWorkerRequest(record.key,identity,{method:'GET',url:target})}})
+ upstream.once('upgrade',(response,remote,remoteHead)=>{
+  socket.write(`HTTP/1.1 101 Switching Protocols\r\n${Object.entries(response.headers).map(([k,v])=>`${k}: ${v}`).join('\r\n')}\r\n\r\n`)
+  if(remoteHead.length)socket.write(remoteHead);if(head.length)remote.write(head)
+  socket.pipe(remote);remote.pipe(socket);socket.once('close',()=>remote.destroy());remote.once('close',()=>socket.destroy());remote.once('error',()=>socket.destroy());socket.once('error',()=>remote.destroy())
+ })
+ upstream.once('response',()=>socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'))
+ upstream.once('error',()=>socket.destroy());socket.once('close',()=>upstream.destroy());upstream.end()
+}
+export function cloudRouter(security,machines,handoffs,auth,{artifact=process.env.OPENROD_WORKER_ARTIFACT,connections,connectionCheckMs=60000}={}) {
+ async function publicRoutes(req,res,next) {
+  try {
+   const pathname=requestPath(req)
+   if(pathname==='/internal/worker-artifact') {
+    if(req.method!=='GET')throw fail('Not found',404)
+    const record=await machines.store.byName(req.headers['x-openrod-worker'])
+    const supplied=req.headers.authorization?.replace(/^Bearer /,'')??''
+    if(!record||supplied.length!==record.key.length||!timingSafeEqual(Buffer.from(supplied),Buffer.from(record.key))||!artifact)throw fail('Not found',404)
+    res.writeHead(200,{'Content-Type':'application/gzip','Cache-Control':'no-store'});const file=fs.createReadStream(artifact);file.on('error',()=>res.destroy());res.once('close',()=>file.destroy());file.pipe(res);return
+   }
+   if(connections && pathname.startsWith('/api/cloud/local-connect/') && pathname!=='/api/cloud/local-connect/authorize') {
+    if(req.headers.host!==security.config.host||(req.headers.origin&&req.headers.origin!==security.config.origin)||(req.headers['sec-fetch-site']&&!['same-origin','none'].includes(req.headers['sec-fetch-site'])))throw fail('Request rejected',403)
+    if(pathname==='/api/cloud/local-connect/exchange'&&req.method==='POST'){
+     const body=await readJson(req);return json(res,200,await connections.redeem(body.code,body.verifier,body.nonce))
+    }
+    const token=req.headers.authorization?.replace(/^Bearer /,'')
+    let identity;try{identity=await connections.authenticate(token)}catch(error){if(error.status===403)throw fail('Cloud connection unavailable. Sign in again.',401);throw error}
+    if(pathname==='/api/cloud/local-connect/revoke'&&req.method==='POST'){await readJson(req);await connections.revoke(token);return json(res,200,{ok:true})}
+    if(pathname==='/api/cloud/local-connect/identity'&&req.method==='GET')return json(res,200,{user:{uid:identity.uid,email:identity.email},expires:identity.expires})
+    if(pathname==='/api/cloud/local-connect/inventory'&&req.method==='GET'){
+     const record=await machines.store.get(identity.uid)
+     if(record&&record.uid!==identity.uid)throw fail('Machine ownership mismatch',403)
+     if(!record||record.state!=='ready'||!record.address)return json(res,200,{sandboxes:[],templates:[],locations:[],machine:{status:record?.state??'none',error:record?.error??null}})
+     watchConnection(token,res,identity)
+     return await proxyWorker(req,res,record,identity,security.config,{target:'/api/os/inventory'})
+    }
+    if(pathname==='/api/cloud/local-connect/machine'&&req.method==='GET')return json(res,200,await machines.status(identity))
+    if(pathname.startsWith('/api/cloud/local-connect/os/')&&['GET','POST'].includes(req.method)){
+     const target=safeWorkspaceTarget(req.url,'/api/cloud/local-connect/os')
+     if(req.method!=='GET'&&req.headers['x-openshell-console']!=='1')throw fail('Request rejected',403)
+     watchConnection(token,res,identity)
+     return await proxyWorker(req,res,await machines.target(identity),identity,security.config,{target})
+    }
+    throw fail('Not found',404)
+   }
+   if(pathname==='/api/cloud/import') {
+    if(req.method!=='POST'||req.headers['content-type']!=='application/json')throw fail('Invalid cloud transfer',400)
+    const uid=await handoffs.consume(req.headers.authorization?.replace(/^Bearer /,''))
+    const user=await auth.getUser(uid)
+    if(user.disabled||!user.emailVerified||!user.providerData?.some(p=>p.providerId==='google.com'))throw fail('Account unavailable',403)
+    const identity={uid,email:user.email,org:security.config.org,role:'member',expires:Date.now()+3600000}
+    return await proxyWorker(req,res,await machines.target(identity),identity,security.config,{target:'/api/os/cloud-import'})
+   }
+   next()
+  }catch(error){json(res,error.status??503,{error:error.status?error.message:'Cloud service unavailable. Try again shortly.'})}
+ }
+ async function protectedRoutes(req,res,next) {
+  try {
+   const identity=identityContext.getStore(),pathname=requestPath(req)
+   if(connections&&pathname==='/api/cloud/local-connect/authorize'&&req.method==='POST'){const body=await readJson(req);return json(res,200,{code:await connections.authorize(identity,body,security.sessionHash(req))})}
+   if(pathname==='/api/cloud/machine'&&req.method==='GET')return json(res,200,await machines.status(identity))
+   if(pathname==='/api/cloud/handoff'&&req.method==='POST'){
+    if(req.headers['x-openshell-console']!=='1')throw fail('Request rejected',403)
+    const record=await machines.target(identity);return json(res,200,{ticket:await handoffs.issue(identity,record.name)})
+   }
+   if(pathname.startsWith('/api/os/'))return await proxyWorker(req,res,await machines.target(identity),identity,security.config)
+   next()
+  }catch(error){json(res,error.status??503,{error:error.status?error.message:'Cloud service unavailable. Try again shortly.'})}
+ }
+ function watchConnection(token,target,identity){
+  const expiry=setTimeout(()=>target.destroy(),Math.max(1,identity.expires-Date.now())),check=setInterval(()=>connections.authenticate(token).catch(()=>target.destroy()),connectionCheckMs)
+  expiry.unref?.();check.unref?.();target.once('close',()=>{clearTimeout(expiry);clearInterval(check)})
+ }
+ return {publicRoutes,protectedRoutes,upgrade:async(req,socket,head)=>{
+  try{
+   const pathname=requestPath(req)
+   if(connections&&pathname.startsWith('/api/cloud/local-connect/os/')){
+    if(req.headers.host!==security.config.host||req.headers.origin!==security.config.origin)throw fail('Request rejected',403)
+    const target=safeWorkspaceTarget(req.url,'/api/cloud/local-connect/os')
+    if(!['/api/os/terminal','/api/os/ssh'].includes(target.split('?')[0]))throw fail('Not found',404)
+    const token=req.headers.authorization?.replace(/^Bearer /,''),identity=await connections.authenticate(token)
+    watchConnection(token,socket,identity);proxyWorkerSocket(req,socket,head,await machines.target(identity),identity,security.config,{target});return
+   }
+   if(pathname!=='/api/os/terminal')return
+   const identity=await security.authenticate(req);security.watch(req,socket,identity);proxyWorkerSocket(req,socket,head,await machines.target(identity),identity,security.config)
+  }catch{socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')}
+ }}
+}

package/server/cloud-ssh-proxy.cjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict'
+// OpenSSH invokes this helper locally. Grants remain inside OpenRod's local server;
+// this process obtains only a single-use, account-scoped SSH stream ticket.
+const { WebSocket, createWebSocketStream } = require('ws')
+
+function validate(options) {
+  const url = new URL(options.origin)
+  if (url.protocol !== 'http:' || !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || url.origin !== options.origin || url.username || url.password || !/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(options.sandbox ?? '') || !/^[a-f0-9]{16}$/.test(options.owner ?? '')) throw Error('Invalid local OpenRod SSH target')
+  if (options.context !== undefined) {
+    let context
+    try { context = JSON.parse(options.context) } catch { throw Error('Invalid OpenRod SSH workspace') }
+    if (!Array.isArray(context) || context.length !== 2 || !context.every(value => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(value))) throw Error('Invalid OpenRod SSH workspace')
+  }
+  return options
+}
+function parseProxyArgs(args) {
+  const options = {}
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i]
+    if (!['--origin', '--sandbox', '--owner', '--context'].includes(flag) || !args[i + 1] || Object.hasOwn(options, flag.slice(2))) throw Error('Invalid OpenRod SSH proxy arguments')
+    options[flag.slice(2)] = args[i + 1]
+  }
+  return validate(options)
+}
+async function runProxy(options, { input = process.stdin, output = process.stdout, fetchRequest = fetch, signal } = {}) {
+  validate(options)
+  const response = await fetchRequest(`${options.origin}/api/remote/os/sandboxes/${options.sandbox}/ssh-ticket`, {
+    method: 'POST', headers: { 'x-openrod-local-owner': options.owner, Origin: options.origin, 'content-type': 'application/json', 'x-openshell-console': '1' },
+    body: JSON.stringify({ owner: options.owner, ...(options.context ? { context: options.context } : {}) }), redirect: 'error', signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30000)]) : AbortSignal.timeout(30000),
+  })
+  if (!response.ok) throw Error(`Local OpenRod SSH authorization failed (${response.status}). Reconnect to OpenRod Cloud.`)
+  const body = await response.json()
+  if (typeof body.ticket !== 'string' || !/^[A-Za-z0-9-]{1,100}$/.test(body.ticket)) throw Error('Invalid SSH ticket from local OpenRod')
+  const url = new URL('/api/remote/os/ssh', options.origin); url.protocol = 'ws:'; url.searchParams.set('ticket', body.ticket); url.searchParams.set('owner', options.owner)
+  if (options.context) url.searchParams.set('context', options.context)
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url, { origin: options.origin, handshakeTimeout: 30000, maxPayload: 1024 * 1024 })
+    let stream, settled = false
+    const abort = () => { ws.terminate(); finish(Error('OpenRod SSH connection canceled')) }
+    const finish = error => {
+      if (settled) return; settled = true
+      signal?.removeEventListener('abort', abort)
+      input.off('error', inputError); output.off('error', outputError)
+      if (stream) { input.unpipe(stream); stream.unpipe(output); stream.destroy() }
+      if (error) { ws.terminate(); reject(error) } else resolve()
+    }
+    const inputError = () => finish(Error('SSH input closed unexpectedly'))
+    const outputError = () => finish(Error('SSH output closed unexpectedly'))
+    input.on('error', inputError); output.on('error', outputError)
+    signal?.addEventListener('abort', abort, { once: true })
+    if (signal?.aborted) return abort()
+    ws.once('open', () => {
+      stream = createWebSocketStream(ws)
+      stream.on('error', () => finish(Error('OpenRod SSH stream disconnected')))
+      stream.pipe(output, { end: false }); input.pipe(stream)
+    })
+    ws.on('message', (_data, binary) => { if (!binary) finish(Error('Invalid SSH stream frame')) })
+    ws.once('error', () => finish(Error('Could not connect to the OpenRod SSH stream. Reconnect to OpenRod Cloud.')))
+    ws.once('close', code => {
+      const error = [1000, 1005].includes(code) ? undefined : Error('OpenRod SSH connection ended. Reconnect to OpenRod Cloud.')
+      if (error || !stream || stream.readableEnded) finish(error)
+      else stream.once('end', () => finish())
+    })
+  })
+}
+module.exports = { parseProxyArgs, runProxy }
+if (require.main === module) {
+  const abort = new AbortController()
+  process.once('SIGINT', () => abort.abort()); process.once('SIGTERM', () => abort.abort())
+  Promise.resolve().then(() => runProxy(parseProxyArgs(process.argv.slice(2)), { signal: abort.signal }))
+    .catch(error => { process.stderr.write(`OpenRod SSH: ${error.message}\n`); process.exitCode = 1 })
+}

package/server/cloud-ssh.js

@@ -0,0 +1,135 @@
+import { randomUUID } from 'node:crypto'
+import { STATUS_CODES } from 'node:http'
+import { createServer } from 'node:net'
+import { spawn } from 'node:child_process'
+import { WebSocketServer, createWebSocketStream } from 'ws'
+import { contextKey, gateway, sandboxView } from './gateway.js'
+import { identityContext } from './security.js'
+import { fail, runCli } from './openshell-cli.js'
+
+const NAME = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/
+export const SSH_PATH = '/api/os/ssh'
+const TTL = 60_000
+const proxyArgs = plan => ['ssh-proxy', '--gateway-name', plan.target.name, '--name', plan.name, '--workspace', plan.workspace]
+
+export function validateHostKeys(keys) {
+  if (!Array.isArray(keys) || !keys.length || keys.length > 8) throw fail('No verified SSH host key is available.', 502)
+  return [...new Set(keys.map(key => {
+    if (typeof key !== 'string' || key.length > 8192 || !/^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(?:256|384|521)) [A-Za-z0-9+/]+={0,2}$/.test(key)) throw fail('Invalid SSH host key.', 502)
+    const [type, encoded] = key.split(' '), bytes = Buffer.from(encoded, 'base64')
+    if (bytes.length < 16 || bytes.readUInt32BE(0) !== type.length || bytes.subarray(4, 4 + type.length).toString() !== type) throw fail('Invalid SSH host key.', 502)
+    return key
+  }))]
+}
+
+export function createSshTickets({ now = Date.now, ttl = TTL } = {}) {
+  const values = new Map()
+  return {
+    issue(plan) {
+      const ticket = randomUUID(), expires = Math.min(now() + ttl, plan.sessionExpires)
+      values.set(ticket, { ...plan, expires })
+      setTimeout(() => values.delete(ticket), ttl).unref?.()
+      return ticket
+    },
+    claim(ticket, principal) {
+      const plan = values.get(ticket); values.delete(ticket)
+      return plan && plan.expires > now() && plan.principal === principal ? plan : null
+    },
+    expires(ticket) { return values.get(ticket)?.expires },
+  }
+}
+const tickets = createSshTickets()
+
+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 }
+}
+
+function stopProxy(child) {
+  try {
+    if (child.pid && process.platform !== 'win32') process.kill(-child.pid, 'SIGTERM')
+    else child.kill('SIGTERM')
+  } catch {}
+  const hardKill = setTimeout(() => {
+    try { if (child.pid && process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL'); else child.kill('SIGKILL') } catch {}
+  }, 1000)
+  hardKill.unref?.()
+  child.once('close', () => clearTimeout(hardKill))
+}
+
+// ssh-proxy authenticates the gateway with the worker's own mTLS bundle. A
+// loopback-only keyscan through that trusted stream obtains the actual SSH key
+// (OpenShell terminates SSH, so sandbox /etc/ssh keys are not authoritative).
+export async function discoverHostKeys({ sandbox, target, workspace }, dependencies = {}) {
+  const spawnProcess = dependencies.spawnProcess ?? spawn
+  const peers = new Set(), children = new Set()
+  const server = createServer(socket => {
+    peers.add(socket)
+    const child = spawnProcess('/usr/bin/openshell', proxyArgs({ name: sandbox.name, target, workspace }), { shell: false, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] })
+    children.add(child); child.stderr.resume()
+    child.on('error', () => socket.destroy()); child.stdin.on('error', () => socket.destroy()); child.stdout.on('error', () => socket.destroy())
+    socket.on('error', () => {}); socket.pipe(child.stdin); child.stdout.pipe(socket)
+    socket.once('close', () => { peers.delete(socket); stopProxy(child) })
+    child.once('close', () => { children.delete(child); socket.destroy() })
+  })
+  try {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve) })
+    const result = await (dependencies.runCli ?? runCli)('/usr/bin/ssh-keyscan', ['-T', '5', '-p', String(server.address().port), '127.0.0.1'], { timeoutMs: 10_000, outputLimit: 64 * 1024 })
+    if (result.timedOut || result.outputExceeded || result.code !== 0) throw fail('Could not verify the sandbox SSH host key.', 502)
+    return validateHostKeys(result.stdout.split('\n').filter(line => line && !line.startsWith('#')).map(line => line.trim().split(/\s+/).slice(1, 3).join(' ')))
+  } finally {
+    for (const socket of peers) socket.destroy()
+    for (const child of children) stopProxy(child)
+    if (server.listening) await new Promise(resolve => server.close(resolve))
+  }
+}
+
+export async function cloudSshRoute(method, parts, input, dependencies = {}) {
+  if (method !== 'POST' || parts[0] !== 'sandboxes' || parts.length !== 3 || parts[2] !== 'ssh-ticket' || !NAME.test(parts[1] ?? '')) return undefined
+  const principal = dependencies.principal ?? identityContext.getStore()
+  if (!principal?.uid || !Number.isFinite(principal.expires) || principal.expires <= (dependencies.now ?? Date.now)()) throw fail('Authenticated SSH owner required.', 403)
+  const context = await (dependencies.loadContext ?? loadContext)(parts[1])
+  if (context.sandbox.phase !== 'ready') throw fail('This sandbox is not running.', 409)
+  const hostKeys = validateHostKeys(await (dependencies.hostKeys ?? discoverHostKeys)(context))
+  const store = dependencies.tickets ?? tickets
+  const plan = { name: context.sandbox.name, target: context.target, gateway: context.target.name, workspace: context.workspace, principal: principal.uid, sessionExpires: principal.expires }
+  const ticket = store.issue(plan)
+  return { ticket, expires: store.expires(ticket), hostKeys, user: 'sandbox', context: contextKey(plan) }
+}
+
+const wss = new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024 })
+function refuse(socket, status) { socket.end(`HTTP/1.1 ${status} ${STATUS_CODES[status]}\r\nConnection: close\r\n\r\n`) }
+export function cloudSshUpgrade(req, socket, head, isAllowed, principal, dependencies = {}) {
+  const url = new URL(req.url ?? '/', 'http://local')
+  if (url.pathname !== SSH_PATH) return false
+  if (!isAllowed(req)) { refuse(socket, 403); return true }
+  const uid = typeof principal === 'string' ? principal : principal?.uid
+  const plan = (dependencies.tickets ?? tickets).claim(url.searchParams.get('ticket'), uid)
+  if (!plan || !uid) { refuse(socket, 403); return true }
+  const requestedContext = url.searchParams.get('context')
+  if (!(dependencies.allowContext ?? (() => true))(plan) || (requestedContext != null && requestedContext !== contextKey(plan))) { refuse(socket, 409); return true }
+  wss.handleUpgrade(req, socket, head, ws => {
+    let child
+    try { child = (dependencies.spawnProcess ?? spawn)('/usr/bin/openshell', proxyArgs(plan), { shell: false, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] }) }
+    catch { ws.close(1011); return }
+    // stream APIs preserve binary bytes and propagate backpressure in both
+    // directions. SSH control/errors never share this binary stream.
+    const stream = createWebSocketStream(ws, { encoding: null })
+    let cleaned = false
+    const expiry = setTimeout(() => { ws.close(1008, 'Cloud authorization expired'); cleanup() }, Math.max(1, Math.min(plan.sessionExpires, principal?.expires ?? Infinity) - Date.now()))
+    expiry.unref?.()
+    const cleanup = () => { if (cleaned) return; cleaned = true; clearTimeout(expiry); stopProxy(child); stream.destroy() }
+    child.stderr.resume()
+    child.on('error', () => ws.close(1011)); child.stdin.on('error', () => ws.close(1011)); child.stdout.on('error', () => ws.close(1011))
+    child.once('close', code => {
+      // stdout.pipe(stream) finishes all queued writes before its finalizer
+      // closes the WebSocket. Closing here would discard the writable queue.
+      if (code !== 0) { if (ws.readyState === ws.OPEN) ws.close(1011); cleanup() }
+    })
+    stream.on('error', cleanup); ws.on('error', cleanup); ws.once('close', cleanup)
+    stream.pipe(child.stdin); child.stdout.pipe(stream)
+    ws.on('message', (_data, binary) => { if (!binary) ws.close(1003, 'Binary SSH frames required') })
+  })
+  return true
+}