openrod 0.1.2 → 0.1.3

package/dist/index.html

@@ -5,10 +5,10 @@
     <link rel="icon" type="image/png" href="/favicon.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#ffffff" />
-    <meta name="description" content="OpenShell control plane - sandboxes, approvals and live activity" />
+    <meta name="description" content="OpenRod — sandboxes, templates, and activity." />
     <title>OpenRod</title>
-    <script type="module" crossorigin src="/assets/index-DoKK2G9s.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-89TNohi_.css">
+    <script type="module" crossorigin src="/assets/index-DBqg9X9x.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-HZ0q_FBv.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openrod",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A local console for OpenShell gateways, sandboxes, and activity.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/OpenRod/OpenRod#readme",
@@ -71,9 +71,11 @@
     "@vitejs/plugin-react": "^4.3.4",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
+    "canvas-confetti": "^1.9.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cn": "^0.2.5",
+    "firebase": "12.19.0",
     "lucide-react": "^0.577.0",
     "motion": "^13.2.0",
     "next-themes": "^0.4.6",
@@ -88,5 +90,10 @@
   },
   "engines": {
     "node": ">=22.13.0"
+  },
+  "overrides": {
+    "@firebase/firestore": {
+      "@grpc/grpc-js": "1.14.5"
+    }
   }
 }

package/server/announcements.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { stateDirectory } from './paths.js'
+
+// Lives outside the npm package and browser origin, so npx upgrades, ports,
+// and browser changes do not replay the announcement for this OS user. While
+// cloud is unavailable it stays unclaimed for the release that offers it.
+export async function claimCloudAnnouncement({ directory = stateDirectory(), user = 'local', available = true } = {}) {
+  if (!available) return { show: false }
+  const owner = createHash('sha256').update(user).digest('hex')
+  const folder = path.join(directory, 'announcements', owner)
+  await fs.mkdir(folder, { recursive: true, mode: 0o700 })
+  try {
+    const file = await fs.open(path.join(folder, 'cloud-v1.seen'), 'wx', 0o600)
+    await file.close()
+    return { show: true }
+  } catch (error) {
+    if (error.code === 'EEXIST') return { show: false }
+    throw error
+  }
+}

package/server/api.js

@@ -1,9 +1,12 @@
 import {createLocalCloudNative} from './local-cloud-native.js'
+import { claimCloudAnnouncement } from './announcements.js'
 import {cloudSshRoute,cloudSshUpgrade} from './cloud-ssh.js'
 import {createLocalCloud} from './local-cloud.js'
 import { cloudOrigin, CLOUD_SOON } from './cloud-origin.js'
 import { setupTargetsFor, validateSetupTargets } from '../shared/setup-targets.js'
 import { localTransfer, importTransfer, exportTransfer } from './cloud-transfer.js'
+import { resourceImportRoute } from './resource-imports.js'
+import { consoleCapabilities } from './capabilities.js'
 import path from 'node:path'
 import { Readable } from 'node:stream'
 import { scopedStateDirectory, stateDirectory } from './paths.js'
@@ -39,7 +42,7 @@ import { filesRoute, planSeed, receiveUpload, serveDownload, startSeed } from '.
 // header alone is not proof of a local caller when Vite is bound to a LAN
 // address, so check the socket, the Host and the browser's own origin claims.
 export { isLocalApiRequest } from './security.js'
-import { createSecurity, releaseConfig, assertCloudOperation, requestPath } from './security.js'
+import { createSecurity, releaseConfig, assertCloudOperation, requestPath, identityContext } from './security.js'
 import { createLaunchToken, createTokenGate, tokenUrl } from './launch-token.js'
 
 // A mutation must also carry a JSON body and a custom header, which a
@@ -54,14 +57,20 @@ function isMutation(req, security) {
 const NAME = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/
 const IMAGE = /^[\w./:@-]{1,256}$/
 
-async function body(req, limit = 65536) {
-  let raw = ''
+export async function readRequestBody(req, limit = 65536) {
+  const chunks = []
+  let bytes = 0
   for await (const chunk of req) {
-    raw += chunk
-    if (Buffer.byteLength(raw) > limit) throw Object.assign(new Error('Request too large'), { status: 413 })
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    bytes += buffer.length
+    if (bytes > limit) throw Object.assign(new Error('Request too large'), { status: 413 })
+    chunks.push(buffer)
   }
-  return raw ? JSON.parse(raw) : {}
+  if (!bytes) return {}
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))) }
+  catch { throw Object.assign(new Error('Invalid JSON request'), { status: 400 }) }
 }
+const body = readRequestBody
 
 function send(res, status, payload) {
   res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' })
@@ -146,7 +155,8 @@ export async function createSandbox(input, { sessionOverride = false } = {}) {
   // A built template's agents get their sign-in and model destinations from
   // the reviewed table in shared/agent-access.js, never from the recipe.
   let agentRules = []
-  if (saved?.managed) { try { agentRules = agentAccessRules(saved.recipe) } catch (error) { throw fail(error.message) } }
+  if (input.connectors?.length && !saved?.managed) throw fail('Connectors need a template built in OpenRod.')
+  if (saved?.managed) { try { agentRules = agentAccessRules(saved.recipe, { connectors: input.connectors ?? [] }) } catch (error) { throw fail(error.message) } }
   if (saved) {
     const start = sessionOverride && input.session !== undefined ? String(input.session) : saved.recipe.command.trim()
     let selectedSession
@@ -354,7 +364,7 @@ export function createOpenShellApi({ httpServer, logger = console, security = cr
     onReuse: () => logger.warn('The link OpenRod opened in your browser was used a second time. If that wasn’t you, another program may have opened the console first: stop OpenRod with Ctrl+C and start it again.'),
   }) : null
   const runtimes = new Map(), streams = new Set(), sockets = new Set(), pending = new Set(), responses = new Set()
-  const localCloud = security.config.mode === 'local' ? createLocalCloud({ native: createLocalCloudNative() }) : null
+  const localCloud = security.config.mode === 'local' ? createLocalCloud({ native: createLocalCloudNative({ token }) }) : null
   const cloudOff = security.config.mode === 'local' && !cloudOrigin()
   const initialContext = contextSelection()
   const initialKey = contextKey(initialContext)
@@ -512,6 +522,12 @@ export function createOpenShellApi({ httpServer, logger = console, security = cr
           if (explicitLocation && security.config.mode === 'local') owner = await inventory.resolve(requestedContext)
           else if (requestedContext != null && requestedContext !== contextKey() && !(req.method === 'GET' && parts[0] === 'connections')) return send(res, 409, { error: 'Console context changed. Reload before continuing.' })
           return await runWithContext(owner, async () => {
+          if (req.method === 'GET' && parts.length === 1 && parts[0] === 'capabilities') return send(res, 200, consoleCapabilities(security.config.mode))
+          if (parts.length === 2 && parts[0] === 'announcements' && parts[1] === 'cloud') {
+            if (!isMutation(req, security)) return send(res, 403, { error: 'Request rejected' })
+            await body(req)
+            return send(res, 200, await claimCloudAnnouncement({ user: identityContext.getStore()?.uid ?? 'local', available: !cloudOff }))
+          }
           // Connection discovery is available before any gateway is selected.
           // Job reads remain available after that job changes the context.
           if (parts[0] === 'connections') {
@@ -529,11 +545,18 @@ export function createOpenShellApi({ httpServer, logger = console, security = cr
             const input = await body(req)
             if (parts.length === 2 && parts[1] === 'connect') return send(res, 200, remoteConnections.begin(input))
             if (parts.length === 3 && parts[1] === 'hosts' && parts[2] === 'scan') return send(res, 200, await sshHosts.scan(input))
-            if (parts.length === 2 && parts[1] === 'hosts') return send(res, 201, await sshHosts.add(input.token))
+            if (parts.length === 2 && parts[1] === 'hosts') {
+              const saved = await sshHosts.add(input.token)
+              await remoteConnections.unforgetHost(saved.alias)
+              return send(res, 201, saved)
+            }
+            if (parts.length === 3 && parts[1] === 'hosts' && parts[2] === 'restore') return send(res, 200, await remoteConnections.restoreHost(input.host))
             if (parts.length === 3 && parts[1] === 'hosts' && parts[2] === 'remove') {
               const current = (await remoteConnections.overview()).active
               if (current?.host === input.alias && ['connected', 'connecting'].includes(current.status)) throw fail('Disconnect from this machine before removing it.', 409)
-              return send(res, 200, await sshHosts.remove(input.alias))
+              const removed = await sshHosts.remove(input.alias)
+              await remoteConnections.unforgetHost(removed.alias)
+              return send(res, 200, removed)
             }
             if (parts.length === 2 && parts[1] === 'disconnect') return send(res, 200, await remoteConnections.disconnect())
             if (parts.length === 2 && parts[1] === 'forget') {
@@ -596,7 +619,23 @@ export function createOpenShellApi({ httpServer, logger = console, security = cr
             if (remote?.gateway === contextSelection().gateway) await inventory.resolve(contextKey())
           }
           const { store, delivery, hub } = runtimeFor(contextSelection())
+          const importOptions = {
+            sourceKind: security.config.mode === 'local' ? undefined : 'cloud',
+            activityStore: store,
+            onEvent: ({ action, job }) => store.ingest({
+              id: randomUUID(), sandbox: '', at: new Date().toISOString(), kind: 'event', category: 'EVENT',
+              source: 'openrod-import', action, severity: job.status === 'failed' || job.status === 'partial' ? 'WARN' : 'INFO',
+              outcome: job.status === 'completed' ? 'success' : job.status === 'failed' ? 'failure' : undefined,
+              actor: identityContext.getStore()?.email ?? 'Local operator', correlationId: job.id,
+              message: `${action}: ${job.counts.completed}/${job.counts.total} resources completed`,
+              original: { jobId: job.id, source: job.source, destination: job.destination, counts: job.counts },
+            }, contextKey()),
+          }
           if (req.method === 'GET') {
+            if (parts[0] === 'resource-imports') {
+              const result = await resourceImportRoute('GET', parts, undefined, importOptions)
+              return send(res, result === undefined ? 404 : 200, result ?? { error: 'Not found' })
+            }
             if (parts[0] === 'stream') {
               res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' })
               res.write(': connected\n\n')
@@ -651,8 +690,12 @@ export function createOpenShellApi({ httpServer, logger = console, security = cr
           }
           if (!isMutation(req, security)) return send(res, 403, { error: 'Request rejected' })
           if (parts[0] === 'cloud-import' && ['worker', 'local'].includes(security.config.mode)) return send(res, 200, await importTransfer(req, { createSandbox: input => createSandbox(input, { sessionOverride: true }) }))
-          const input = await body(req, ['image-templates', 'activity'].includes(parts[0]) ? 512 * 1024 : parts[0] === 'setups' ? 128 * 1024 : 65536)
+          const input = await body(req, parts[0] === 'resource-imports' ? 8 * 1024 * 1024 : ['image-templates', 'activity'].includes(parts[0]) ? 512 * 1024 : parts[0] === 'setups' ? 128 * 1024 : 65536)
           assertCloudOperation(parts, input)
+          if (parts[0] === 'resource-imports') {
+            const result = await resourceImportRoute('POST', parts, input, importOptions)
+            return send(res, result === undefined ? 404 : 200, result ?? { error: 'Not found' })
+          }
           if (parts[0] === 'cloud-transfer' && security.config.mode === 'local') return send(res, 200, await localTransfer(input))
           if (parts[0] === 'activity' && parts.length === 2) {
             if (parts[1] === 'delete-preview') return send(res, 200, store.previewDeletion(input))

package/server/capabilities.js

@@ -0,0 +1,13 @@
+import { CLOUD_TRANSFER_LIMIT, CLOUD_TRANSFER_BODY_LIMIT } from './cloud-transfer.js'
+
+// Explicit support, rather than environment names, drives available UI actions.
+export function consoleCapabilities(mode = 'local') {
+  const cloud = mode !== 'local'
+  return {
+    version: 1,
+    mode,
+    resources: Object.fromEntries(['sandboxes', 'templates', 'setups', 'network', 'groups', 'secrets', 'activity'].map(type => [type, { read: true, manage: true }])),
+    features: { terminal: true, files: true, templateBuilds: true, localFolders: !cloud, publicIngress: !cloud, resourceImports: true },
+    workspaceTransfer: { supported: true, maxBytes: CLOUD_TRANSFER_LIMIT, maxFiles: 2000, maxRequestBytes: CLOUD_TRANSFER_BODY_LIMIT, preservesSource: true, credentials: false, runningProcesses: false },
+  }
+}

package/server/cli.js

@@ -121,7 +121,21 @@ function openBrowser(url, logger) {
   child.unref()
 }
 
+// The API authenticates these upgrades. The CLI must not destroy a cloud
+// relay socket after that asynchronous handler has accepted responsibility.
+export function rejectUnsupportedUpgrade(req, socket) {
+  const pathname = (req.url ?? '').split('?', 1)[0]
+  if (!['/api/os/terminal', '/api/os/ssh', '/api/remote/os/terminal', '/api/remote/os/ssh'].includes(pathname)) socket.destroy()
+}
+
+// The openrod command is the loopback console guarded by its launch token.
+// Cloud and worker deployments start server/start.js instead.
+function assertLocalMode() {
+  if ((process.env.OPENROD_MODE ?? 'local') !== 'local') throw new Error('openrod runs the local console. Unset OPENROD_MODE, or start cloud and worker deployments with server/start.js.')
+}
+
 export async function startConsole(options = parseOptions([]), logger = console) {
+  assertLocalMode()
   const { host, port } = parseOptions(['--host', options.host ?? '127.0.0.1', '--port', String(options.port ?? 4600)])
   let directory
   try {
@@ -129,6 +143,7 @@ export async function startConsole(options = parseOptions([]), logger = console)
     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 { createSecurity } = await import('./security.js')
   const { createLaunchToken, tokenUrl } = await import('./launch-token.js')
   const token = createLaunchToken()
   const serveStatic = staticMiddleware(directory)
@@ -153,9 +168,9 @@ export async function startConsole(options = parseOptions([]), logger = console)
     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 }) }
+  try { api = createOpenShellApi({ httpServer: server, logger, token, security: createSecurity({ mode: 'local' }) }) }
   catch (error) { server.close(); throw error }
-  server.on('upgrade', (req, socket) => { if ((req.url ?? '').split('?', 1)[0] !== '/api/os/terminal') socket.destroy() })
+  server.on('upgrade', rejectUnsupportedUpgrade)
   let closing
   const close = () => {
     if (closing) return closing
@@ -184,6 +199,7 @@ async function main() {
   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 }
   if (!nodeSupported()) throw new Error(`OpenRod needs Node.js 22.13 or newer, and this is ${process.versions.node}. Install a current release from https://nodejs.org, then run it again.`)
+  assertLocalMode()
   quietSqliteWarning()
   // Before the console starts, so the browser opens on a usable local gateway.
   try {

package/server/cloud-deployment.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto'
+
+// Infrastructure identities can outlive product naming. Configure an existing
+// fleet explicitly rather than renaming records or allocating replacement VMs.
+export function workerPrefix(value = 'openrod-user') {
+  if (!/^[a-z][a-z0-9-]{0,30}$/.test(value)) throw Error('Invalid OPENROD_WORKER_PREFIX')
+  return value
+}
+export function workerOwnerHash(uid) {
+  if (typeof uid !== 'string' || !uid || uid.length > 128) throw Object.assign(Error('Invalid account'), { status: 400 })
+  return createHash('sha256').update(uid).digest('hex').slice(0, 24)
+}
+// A fleet provisioned before OpenRod signs requests with its own header names.
+// Its operator supplies their prefix; the source names only OpenRod's headers.
+export function legacyHeaderPrefix(value) {
+  if (!/^x-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value ?? '') || value === 'x-openrod') throw Error('OPENROD_WORKER_PROTOCOL=legacy requires OPENROD_LEGACY_HEADER_PREFIX, the earlier header prefix such as x-acme')
+  return value
+}
+export function workerProtocol(value = 'current', env = process.env) {
+  if (!['current', 'legacy'].includes(value)) throw Error('OPENROD_WORKER_PROTOCOL must be current or legacy')
+  if (value === 'legacy') legacyHeaderPrefix(env.OPENROD_LEGACY_HEADER_PREFIX)
+  return value
+}
+export const workerAuthHeader = (protocol, env = process.env) => protocol === 'legacy' ? `${legacyHeaderPrefix(env.OPENROD_LEGACY_HEADER_PREFIX)}-worker-auth` : 'x-openrod-worker-auth'
+export const workerNameHeader = (protocol, env = process.env) => protocol === 'legacy' ? `${legacyHeaderPrefix(env.OPENROD_LEGACY_HEADER_PREFIX)}-worker` : 'x-openrod-worker'
+export function ownerLabel(value = 'openrod_owner') {
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(value)) throw Error('Invalid OPENROD_WORKER_OWNER_LABEL')
+  return value
+}

package/server/cloud-proxy.js

@@ -4,20 +4,22 @@ 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'
+import { workerPrefix, workerAuthHeader, workerNameHeader } from './cloud-deployment.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()) {
+export function createHandoffs(db,now=()=>Date.now(),prefix='openrod-user') {
+ const ticketPattern=new RegExp(`^${workerPrefix(prefix)}-[a-f0-9]{24}\\.[a-f0-9]{64}$`)
  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)
+   if(typeof token!=='string'||!ticketPattern.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})}
+ const headers={host:config.host,origin:config.origin,'x-openshell-console':'1',[workerAuthHeader(record.workerProtocol??config.workerProtocol)]: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=>{
@@ -32,7 +34,7 @@ export function proxyWorker(req,res,record,identity,config,{target=req.url,maxBy
  })
 }
 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})}})
+ 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'],[workerAuthHeader(record.workerProtocol??config.workerProtocol)]: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)
@@ -47,7 +49,7 @@ export function cloudRouter(security,machines,handoffs,auth,{artifact=process.en
    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 record=await machines.store.byName(req.headers['x-openrod-worker']??(security.config.workerProtocol==='legacy'?req.headers[workerNameHeader('legacy')]:undefined))
     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
@@ -69,11 +71,15 @@ export function cloudRouter(security,machines,handoffs,auth,{artifact=process.en
      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==='/api/cloud/local-connect/machine'&&req.method==='POST'){
+     if(req.headers['x-openshell-console']!=='1')throw fail('Request rejected',403)
+     await readJson(req);return json(res,200,await machines.prepare(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})
+     return await proxyWorker(req,res,await machines.target(identity,{provision:req.method!=='GET'}),identity,security.config,{target})
     }
     throw fail('Not found',404)
    }
@@ -93,11 +99,15 @@ export function cloudRouter(security,machines,handoffs,auth,{artifact=process.en
    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/machine'&&req.method==='POST'){
+    if(req.headers['x-openshell-console']!=='1')throw fail('Request rejected',403)
+    await readJson(req);return json(res,200,await machines.prepare(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)
+   if(pathname.startsWith('/api/os/'))return await proxyWorker(req,res,await machines.target(identity,{provision:req.method!=='GET'}),identity,security.config)
    next()
   }catch(error){json(res,error.status??503,{error:error.status?error.message:'Cloud service unavailable. Try again shortly.'})}
  }
@@ -113,10 +123,10 @@ export function cloudRouter(security,machines,handoffs,auth,{artifact=process.en
     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
+    watchConnection(token,socket,identity);proxyWorkerSocket(req,socket,head,await machines.target(identity,{provision:false}),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)
+   const identity=await security.authenticate(req);security.watch(req,socket,identity);proxyWorkerSocket(req,socket,head,await machines.target(identity,{provision:false}),identity,security.config)
   }catch{socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')}
  }}
 }

package/server/cloud-runtime.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { createCompute, workerDeploymentConfig } from './compute.js'
+import { createMachineStore, createMachineManager, workerReady } from './machines.js'
+import { createCloudConnections } from './cloud-connections.js'
+import { createHandoffs } from './cloud-proxy.js'
+import { workerPrefix, ownerLabel } from './cloud-deployment.js'
+
+// Keep the Admin SDK outside the local npm package and worker installation.
+// Only the explicitly selected cloud control plane ever loads it.
+async function loadCloudAdmin() {
+  const require = createRequire(new URL('../../deploy/gcp/runtime/package.json', import.meta.url))
+  try {
+    return { ...require('firebase-admin/app'), ...require('firebase-admin/auth'), ...require('firebase-admin/firestore') }
+  } catch (error) {
+    if (error.code === 'MODULE_NOT_FOUND') throw Error('Cloud runtime dependencies are missing. Run npm ci --prefix deploy/gcp/runtime from the repository root.')
+    throw error
+  }
+}
+
+export function cloudRuntimeConfig(config, env = process.env) {
+  if (config.mode !== 'cloud') throw Error('Cloud runtime requires cloud mode')
+  const maxMachines = Number(env.OPENROD_MAX_MACHINES ?? 10)
+  if (!Number.isInteger(maxMachines) || maxMachines < 1 || maxMachines > 100) throw Error('OPENROD_MAX_MACHINES must be between 1 and 100')
+  const databaseId = env.OPENROD_FIRESTORE_DATABASE ?? 'openrod-cloud'
+  if (!/^[a-z][a-z0-9-]{2,61}[a-z0-9]$/.test(databaseId)) throw Error('Invalid OPENROD_FIRESTORE_DATABASE')
+  const artifact = env.OPENROD_WORKER_ARTIFACT
+  if (!artifact || !path.isAbsolute(artifact)) throw Error('OPENROD_WORKER_ARTIFACT must identify the reviewed worker artifact by absolute path')
+  const prefix = workerPrefix(env.OPENROD_WORKER_PREFIX), label = ownerLabel(env.OPENROD_WORKER_OWNER_LABEL)
+  if (env.OPENROD_PROVISIONING_ENABLED !== undefined && !['true', 'false'].includes(env.OPENROD_PROVISIONING_ENABLED)) throw Error('OPENROD_PROVISIONING_ENABLED must be true or false')
+  return { maxMachines, databaseId, artifact, prefix, ownerLabel: label, allowProvisioning: env.OPENROD_PROVISIONING_ENABLED !== 'false', deployment: workerDeploymentConfig(config, env) }
+}
+
+export async function verifyWorkerArtifact(filename, expectedHash) {
+  if (!fs.statSync(filename).isFile()) throw Error('Worker artifact must be a regular file')
+  const digest = createHash('sha256')
+  for await (const chunk of fs.createReadStream(filename)) digest.update(chunk)
+  if (digest.digest('hex') !== expectedHash) throw Error('Worker artifact checksum does not match OPENROD_WORKER_ARTIFACT_SHA256')
+}
+
+export async function createCloudRuntime(config, { env = process.env, revocations, loadAdmin = loadCloudAdmin, computeFactory = createCompute } = {}) {
+  const settings = cloudRuntimeConfig(config, env)
+  await verifyWorkerArtifact(settings.artifact, settings.deployment.artifactHash)
+  const admin = await loadAdmin()
+  const credential = admin.applicationDefault()
+  const app = admin.initializeApp({ projectId: config.firebase.projectId, credential }, `openrod-${randomUUID()}`)
+  let db, closed = false
+  const close = async () => {
+    if (closed) return
+    closed = true
+    try { await db?.terminate() } finally { await admin.deleteApp(app) }
+  }
+  try {
+    const auth = admin.getAuth(app)
+    db = admin.getFirestore(app, settings.databaseId)
+    // Fail startup before advertising readiness if ADC or registry IAM is broken.
+    // This is read-only and never reserves a fleet slot or creates a VM.
+    await credential.getAccessToken()
+    await db.collection('control').doc('fleet').get()
+    const compute = await computeFactory(config, credential, { env })
+    const store = createMachineStore(db, { maxMachines: settings.maxMachines, prefix: settings.prefix })
+    const machines = createMachineManager(store, compute, { ownerLabel: settings.ownerLabel, allowProvisioning: settings.allowProvisioning, ready: (record, address) => workerReady(record, address, { host: config.host, protocol: record.workerProtocol ?? config.workerProtocol }) })
+    const handoffs = createHandoffs(db, Date.now, settings.prefix)
+    const connections = createCloudConnections(db, auth, { org: config.org, isSessionRevoked: hash => revocations?.hasDigest(hash) ?? false })
+    return { auth, machines, handoffs, connections, artifact: settings.artifact, close, async ready() { await db.collection('control').doc('fleet').get(); return true } }
+  } catch (error) {
+    await close().catch(() => {})
+    throw error
+  }
+}

package/server/cloud-ssh-proxy.cjs

@@ -2,6 +2,7 @@
 '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 fs = require('node:fs/promises')
 const { WebSocket, createWebSocketStream } = require('ws')
 
 function validate(options) {
@@ -18,24 +19,41 @@ 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')
+    if (!['--origin', '--sandbox', '--owner', '--context', '--auth-file'].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)
+  let cookie
+  if (options['auth-file']) {
+    try {
+      const file = await fs.open(options['auth-file'], require('node:fs').constants.O_RDONLY | require('node:fs').constants.O_NOFOLLOW)
+      try {
+        const stat = await file.stat()
+        if (!stat.isFile() || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid()) || stat.size > 4096) throw Error('Invalid credential file')
+        const auth = JSON.parse(await file.readFile('utf8'))
+        if (auth.origin !== options.origin || typeof auth.cookie !== 'string' || !/^openrod_token_[0-9]+=[A-Za-z0-9_-]{32,256}$/.test(auth.cookie)) throw Error('Invalid credential')
+        cookie = auth.cookie
+      } finally { await file.close() }
+    } catch { throw Error('Local OpenRod SSH credentials are unavailable. Open the sandbox from OpenRod again.') }
+  }
   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' },
+    method: 'POST', headers: { ...(cookie ? { Cookie: cookie } : {}), '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.`)
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}))
+    if (error.code === 'CONSOLE_TOKEN_REQUIRED') throw Error('Local OpenRod console authorization expired. Open the sandbox from OpenRod again.')
+    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 })
+    const ws = new WebSocket(url, { origin: options.origin, headers: cookie ? { Cookie: cookie } : {}, handshakeTimeout: 30000, maxPayload: 1024 * 1024 })
     let stream, settled = false
     const abort = () => { ws.terminate(); finish(Error('OpenRod SSH connection canceled')) }
     const finish = error => {

package/server/cloud-transfer.js

@@ -135,7 +135,7 @@ export async function exportTransfer(input, options = {}) {
 export async function localTransfer(input, options = {}) {
   const origin = options.origin ?? cloudOrigin()
   if (!origin) throw cloudUnavailable()
-  if (typeof input?.ticket !== 'string' || !/^openrod-user-[a-f0-9]{24}\.[a-f0-9]{64}$/.test(input.ticket)) throw fail('Invalid cloud transfer request.')
+  if (typeof input?.ticket !== 'string' || !/^[a-z][a-z0-9-]{0,62}\.[a-f0-9]{64}$/.test(input.ticket)) throw fail('Invalid cloud transfer request.')
   const { bundle, warning } = await exportTransfer(input, options)
   if (input.destinationGroups !== undefined) {
     try { bundle.destinationGroups = groupIds(input.destinationGroups) } catch (error) { throw fail(error.message) }

package/server/compute.js

@@ -1,21 +1,32 @@
 import fs from 'node:fs'
 import path from 'node:path'
-export async function createCompute(config, credential) {
- const project=config.firebase.projectId,zone=process.env.OPENROD_WORKER_ZONE??'us-east1-b',subnet=process.env.OPENROD_WORKER_SUBNET
- const artifactOrigin=process.env.OPENROD_WORKER_ARTIFACT_ORIGIN,artifactHash=process.env.OPENROD_WORKER_ARTIFACT_SHA256
+import { legacyHeaderPrefix, ownerLabel, workerOwnerHash } from './cloud-deployment.js'
+export function workerDeploymentConfig(config, env=process.env) {
+ const project=config.firebase.projectId,zone=env.OPENROD_WORKER_ZONE??'us-east1-b',subnet=env.OPENROD_WORKER_SUBNET
+ const artifactOrigin=env.OPENROD_WORKER_ARTIFACT_ORIGIN,artifactHash=env.OPENROD_WORKER_ARTIFACT_SHA256
  if(!/^[a-z0-9-]+$/.test(zone)||!subnet?.startsWith(`projects/${project}/regions/`)||!/^http:\/\/10\.80\.0\.\d{1,3}:8080$/.test(artifactOrigin??'')||!/^[a-f0-9]{64}$/.test(artifactHash??''))throw Error('Worker deployment configuration is incomplete')
+ const url=new URL(artifactOrigin)
+ if(Number(url.hostname.split('.').at(-1))>254||Number(url.hostname.split('.').at(-1))<1)throw Error('Invalid worker artifact address')
+ const region=zone.replace(/-[a-z]$/,'')
+ if(!new RegExp(`^projects/${project}/regions/${region}/subnetworks/[a-z][a-z0-9-]{0,62}$`).test(subnet))throw Error('Worker subnet must belong to the configured project and zone region')
+ const networkTag=env.OPENROD_WORKER_NETWORK_TAG??'openrod-user-worker',label=ownerLabel(env.OPENROD_WORKER_OWNER_LABEL)
+ if(!/^[a-z][a-z0-9-]{0,62}$/.test(networkTag))throw Error('Invalid OPENROD_WORKER_NETWORK_TAG')
+ return {project,zone,subnet,artifactOrigin,artifactHash,networkTag,ownerLabel:label}
+}
+export async function createCompute(config, credential, {env=process.env, requestFetch=fetch}={}) {
+ const {project,zone,subnet,artifactOrigin,artifactHash,networkTag,ownerLabel}=workerDeploymentConfig(config,env)
  const source=fs.readFileSync(path.resolve(import.meta.dirname,'../../deploy/gcp/worker-startup.sh'),'utf8')
  const base=`https://compute.googleapis.com/compute/v1/projects/${project}/zones/${zone}`
  async function request(method,url,body) {
   const token=await credential.getAccessToken()
-  const response=await fetch(url,{method,headers:{Authorization:`Bearer ${token.access_token}`,'Content-Type':'application/json'},body:body?JSON.stringify(body):undefined,signal:AbortSignal.timeout(30000)})
-  if(response.status===404)return null
+  const response=await requestFetch(url,{method,headers:{Authorization:`Bearer ${token.access_token}`,'Content-Type':'application/json'},body:body?JSON.stringify(body):undefined,signal:AbortSignal.timeout(30000)})
+  if(response.status===404&&method==='GET')return null
   const value=await response.json()
   if(!response.ok || value.error){const e=Error(value.error?.message??value.error?.errors?.[0]?.message??'Compute request failed');e.code=response.status;throw e}
   return value
  }
  return {get:name=>request('GET',`${base}/instances/${name}`),async create(record){
-  const settings=Buffer.from(JSON.stringify({key:record.key,uid:record.uid,origin:config.origin,artifactOrigin,artifactHash,name:record.name})).toString('base64')
+  const settings=Buffer.from(JSON.stringify({key:record.key,uid:record.uid,origin:config.origin,artifactOrigin,artifactHash,name:record.name,workerProtocol:config.workerProtocol??'current',...(config.workerProtocol==='legacy'?{legacyHeaderPrefix:legacyHeaderPrefix(env.OPENROD_LEGACY_HEADER_PREFIX)}:{})})).toString('base64')
   const script=Buffer.from(source.replace('__OPENROD_WORKER_SETTINGS__',settings)).toString('base64')
   const startup=`#!/usr/bin/env bash
 set -euo pipefail
@@ -41,7 +52,7 @@ UNIT
 systemctl daemon-reload
 systemctl enable --now openrod-worker-bootstrap
 `
-  const body={name:record.name,machineType:`zones/${zone}/machineTypes/e2-standard-2`,labels:{application:'openrod',managed_by:'openrod-console',openrod_owner:record.name.slice(9)},tags:{items:['openrod-user-worker']},serviceAccounts:[],canIpForward:false,
+  const body={name:record.name,machineType:`zones/${zone}/machineTypes/e2-standard-2`,labels:{application:'openrod',managed_by:'openrod-console',[ownerLabel]:workerOwnerHash(record.uid)},tags:{items:[networkTag]},serviceAccounts:[],canIpForward:false,
    disks:[{boot:true,autoDelete:true,initializeParams:{sourceImage:'projects/ubuntu-os-cloud/global/images/family/ubuntu-2404-lts-amd64',diskSizeGb:'30',diskType:`zones/${zone}/diskTypes/pd-balanced`}},{boot:false,autoDelete:false,deviceName:'openrod-state',initializeParams:{diskName:`${record.name}-state`,diskSizeGb:'100',diskType:`zones/${zone}/diskTypes/pd-balanced`}}],
    networkInterfaces:[{subnetwork:subnet,stackType:'IPV4_ONLY'}],metadata:{items:[{key:'enable-oslogin',value:'TRUE'},{key:'block-project-ssh-keys',value:'TRUE'},{key:'disable-legacy-endpoints',value:'TRUE'},{key:'startup-script',value:startup}]},shieldedInstanceConfig:{enableSecureBoot:true,enableVtpm:true,enableIntegrityMonitoring:true}}
   try{return await request('POST',`${base}/instances?requestId=${record.requestId}`,body)}catch(error){if(error.code!==409)throw error;return request('GET',`${base}/instances/${record.name}`)}

package/server/image-templates.js

@@ -91,6 +91,23 @@ export async function localEngine({ execute = run } = {}) {
 async function deploymentEngine(target) {
   return target.remote ? remoteImageEngine(target, { execute: run }) : localEngine()
 }
+// Cache fast path only when the gateway's actual Docker engine is established.
+// Inspect the pinned image; never run a container or pull an image for this probe.
+export async function preparationImageRuntime(target, reference, { execute = run, guard = gatewayDocker } = {}) {
+  if (!target) return null
+  let engine
+  if (target.remote) engine = await remoteImageEngine(target, { execute })
+  else {
+    const status = await guard?.status({ fresh: true })
+    if (status?.state !== 'ok' || status.gateway !== target.name || !status.driver?.engineId || status.driver.engineId !== status.build?.engineId) return null
+    engine = await localEngine({ execute })
+    if (engine.engineId !== status.driver.engineId) return null
+  }
+  const info = await inspect(reference, engine, { execute })
+  const node = info.Config?.Env?.find(value => value.startsWith('NODE_VERSION='))?.slice('NODE_VERSION='.length)
+  if (!/^22\.\d+\.\d+$/.test(node ?? '') || !['amd64', 'arm64'].includes(info.Architecture)) return null
+  return { node, arch: info.Architecture === 'amd64' ? 'x64' : 'arm64', platform: 'linux', libc: 'glibc' }
+}
 async function inspect(reference, engine, { execute = run, job, architecture = engine.architecture } = {}) {
   const image = JSON.parse(await execute(['image', 'inspect', reference], { engine, job }))[0]
   if (image.Os !== 'linux') throw fail('Choose a Linux container image.')