openrod 0.1.2 → 0.1.3

package/src/lib/analytics.js

@@ -0,0 +1,334 @@
+// Explicit, anonymous PostHog capture. No SDK, autocapture, queue, retry, or logs.
+// This module is also imported by Node-side libraries: never touch the browser
+// until the authorized local UI configures it.
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i
+export const USAGE_KEY = 'openrod.usage.v1'
+const ID_KEY = 'openrod.usage-id.v1'
+const SESSION_KEY = 'openrod.usage-session.v1'
+const TERMINAL_KEY = 'openrod.terminal-flows.v1'
+const choices = (...values) => value => values.includes(value) ? value : undefined
+const uuid = value => typeof value === 'string' && UUID.test(value) ? value : undefined
+const number = value => Number.isFinite(value) && value >= 0 ? Math.min(Math.round(value), 86400000) : undefined
+const boolean = value => typeof value === 'boolean' ? value : undefined
+const view = choices('sandboxes', 'activity', 'groups', 'egress', 'ingress', 'secrets', 'templates', 'setups', 'connections', 'terminal')
+const flow = choices('gateway_connection', 'sandbox_creation', 'session_launch')
+const location = choices('local', 'ssh', 'cloud', 'unknown')
+const errorCategory = choices('docker_missing', 'docker_unavailable', 'openshell_missing', 'gateway_unavailable', 'ssh_auth', 'host_key', 'runtime_missing', 'image_build', 'credentials_missing', 'setup_import', 'policy', 'file_seed', 'timeout', 'connection_lost', 'unknown')
+const flowFields = { flow, flow_id: uuid, attempt: number, location_type: location, launch_target: choices('browser', 'terminal', 'vscode', 'cursor') }
+const text = value => typeof value === 'string' ? value.trim().slice(0, 2000) : undefined
+const agentIds = value => Array.isArray(value) ? [...new Set(value.filter(id => ['claude', 'codex', 'cursor', 'pi', 'antigravity', 'opencode', 'aider', 'copilot', 'kiro', 'droid'].includes(id)))].slice(0, 12) : undefined
+const configFields = { creation_mode: choices('quick', 'template'), file_source: choices('empty', 'folder', 'repo'), agent_ids: agentIds, setup_count: number, provider_count: number, group_count: number }
+const EVENTS = {
+  console_opened: { gateway_state: choices('available', 'setup_required', 'unavailable'), first_observed_visit: boolean, connection_method: choices('automatic', 'manual', 'existing', 'unknown') },
+  view_opened: { previous_view: view },
+  flow_started: { ...flowFields, ...configFields },
+  flow_step_changed: { ...flowFields, step: choices('location', 'configuration', 'validation', 'host_selection', 'connecting', 'needs_docker', 'needs_runtime', 'preparing_tools', 'building_image', 'creating', 'requesting'), state: choices('entered', 'blocked'), error_category: errorCategory },
+  flow_finished: { ...flowFields, ...configFields, outcome: choices('connected', 'created', 'live', 'handoff_requested', 'failed', 'cancelled'), duration_ms: number, start_observed: boolean, error_category: errorCategory },
+  sandbox_ready: { flow_id: uuid, duration_ms: number, location_type: location },
+  feature_used: { feature: choices('template', 'setup', 'network', 'group', 'activity', 'files', 'sandbox'), action: choices('built', 'imported', 'activated', 'rule_saved', 'membership_saved', 'filter_applied', 'exported', 'uploaded', 'started', 'stopped', 'deleted'), count: number, location_type: location },
+  feedback_submitted: { prompt: choices('general'), category: choices('general'), text, feedback_only: boolean },
+}
+
+export function sanitizeEvent(event, properties = {}) {
+  if (!Object.hasOwn(EVENTS, event)) return null
+  const safe = {}
+  for (const [key, validate] of Object.entries({ view, ...EVENTS[event] })) {
+    const value = validate(properties[key])
+    if (value !== undefined) safe[key] = value
+  }
+  return safe
+}
+
+// Only the category leaves the browser. Messages can contain private hosts or
+// paths, so they are matched here against OpenRod's own wording and dropped.
+const ERROR_PATTERNS = [
+  [/host key/i, 'host_key'],
+  [/permission denied|publickey|authentication failed/i, 'ssh_auth'],
+  [/docker (engine )?is missing|docker isn.t installed|install docker/i, 'docker_missing'],
+  [/docker isn.t running|docker daemon|reach docker|docker.*not available/i, 'docker_unavailable'],
+  [/openshell (cli )?is not installed|openshell isn.t installed/i, 'openshell_missing'],
+  [/runtime (image|package)|sandbox runtime/i, 'runtime_missing'],
+  [/timed out/i, 'timeout'],
+  [/gateway/i, 'gateway_unavailable'],
+]
+export function classifyAnalyticsError(error) {
+  if (error?.name === 'TimeoutError' || error?.status === 504) return 'timeout'
+  if (error?.code === 'GATEWAY_DOCKER_MISMATCH') return 'docker_unavailable'
+  const message = typeof error?.message === 'string' ? error.message : ''
+  for (const [pattern, category] of ERROR_PATTERNS) if (pattern.test(message)) return category
+  if (error?.name === 'TypeError') return 'connection_lost'
+  if (error?.status === 502 || error?.status === 503) return 'gateway_unavailable'
+  return 'unknown'
+}
+
+export function createAnalytics({ getStorage = () => window.localStorage, getLocation = () => window.location.href,
+  randomUUID = () => crypto.randomUUID(), now = () => Date.now(), fetch: send = (...args) => fetch(...args),
+  setTimer = setTimeout, clearTimer = clearTimeout,
+  replaceLocation = url => window.history.replaceState(window.history.state, '', url),
+  config = typeof __OPENROD_ANALYTICS__ === 'undefined' ? {} : __OPENROD_ANALYTICS__,
+} = {}) {
+  let authorized = false, runtimeEnabled = false, storageFailed = false, currentView, lastView, opened = false, firstVisit
+  const destination = config.host === 'https://eu.i.posthog.com' ? 'EU' : 'US'
+  let state = Object.freeze({ available: false, sharing: null, destination })
+  const listeners = new Set(), pending = new Map(), finished = new Set(), steps = new Map(), templates = new Map()
+  let recent = [], generation = 0
+  const storage = () => getStorage()
+  const safe = (operation, fallback) => { try { return operation() } catch { return fallback } }
+  function halt() {
+    generation++
+    for (const [controller, timer] of pending) { controller.abort(); clearTimer(timer) }
+    pending.clear(); finished.clear(); steps.clear(); templates.clear(); recent = []
+    opened = false; lastView = undefined; firstVisit = undefined
+  }
+  function cleanLocation() {
+    const url = new URL(getLocation())
+    return !url.searchParams.has('token') && !url.searchParams.has('handoff') && !/^#local-(connect|return)=/.test(url.hash)
+      && !(config.environment === 'development' && url.searchParams.has('fleet'))
+  }
+  function available() {
+    return safe(() => authorized && runtimeEnabled && !storageFailed && config.enabled === true && /^phc_[a-zA-Z0-9]+$/.test(config.projectToken ?? '')
+      && ['https://us.i.posthog.com', 'https://eu.i.posthog.com'].includes(config.host) && cleanLocation(), false)
+  }
+  function refresh() {
+    safe(() => {
+      let sharing = null
+      try {
+        const value = storage().getItem(USAGE_KEY); sharing = value === 'yes' ? true : value === 'no' ? false : null
+      }
+      catch { storageFailed = true; halt() }
+      if (sharing !== true && state.sharing === true) halt()
+      const next = { available: available(), sharing, destination }
+      if (Object.keys(next).some(key => next[key] !== state[key])) {
+        state = Object.freeze(next)
+        for (const notify of listeners) safe(notify)
+      }
+    })
+  }
+  function configure({ enabled = false, mode = 'local' } = {}) {
+    safe(() => { authorized = mode === 'local'; runtimeEnabled = enabled; if (!authorized || !enabled) halt(); refresh() })
+  }
+  function setSharing(value) {
+    safe(() => {
+      try {
+        storage().setItem(USAGE_KEY, value ? 'yes' : 'no')
+        if (!value) {
+          for (const key of [ID_KEY, SESSION_KEY, TERMINAL_KEY]) storage().removeItem(key)
+          halt()
+        }
+      } catch { storageFailed = true; halt() }
+      refresh()
+    })
+  }
+  function identity() {
+    const store = storage()
+    let id = uuid(store.getItem(ID_KEY)), session
+    const first = !id
+    firstVisit ??= first
+    if (!id) { id = randomUUID(); store.setItem(ID_KEY, id) }
+    try { session = JSON.parse(store.getItem(SESSION_KEY)) } catch { /* invalid old state */ }
+    if (!uuid(session?.id) || !Number.isFinite(session?.at) || now() - session.at > 1800000) session = { id: randomUUID() }
+    store.setItem(SESSION_KEY, JSON.stringify({ id: session.id, at: now() }))
+    return { id, session: session.id, first: firstVisit }
+  }
+  function capture(event, properties = {}, { explicitFeedback = false } = {}) {
+    return safe(() => {
+      refresh()
+      if (!state.available || (state.sharing !== true && !(explicitFeedback && event === 'feedback_submitted'))) return false
+      const sanitized = sanitizeEvent(event, properties)
+      if (!sanitized) return false
+      // Recheck the stored preference before every request, including in other tabs.
+      const regular = state.sharing === true
+      let who
+      try { who = regular ? identity() : { id: randomUUID() } } catch { storageFailed = true; halt(); refresh(); return false }
+      recent = recent.filter(at => now() - at < 60000)
+      if (pending.size >= 6 || recent.length >= 120) return false
+      const controller = new AbortController()
+      const timer = setTimer(() => { controller.abort(); pending.delete(controller) }, 3000)
+      pending.set(controller, timer); recent.push(now())
+      const payload = {
+        api_key: config.projectToken, event, distinct_id: who.id, timestamp: new Date(now()).toISOString(),
+        properties: { schema_version: 1, app_version: config.version, environment: config.environment,
+          // Feedback sent with sharing off carries only what the user typed.
+          ...(regular && who.session ? { $session_id: who.session } : {}),
+          ...(regular && currentView ? { view: currentView } : {}),
+          // Opted-in usage gets PostHog's approximate location (country, city);
+          // the project discards the IP itself. Feedback-only events get neither.
+          ...sanitized, $process_person_profile: false, ...(regular ? {} : { $geoip_disable: true }),
+          ...(event === 'console_opened' ? { first_observed_visit: who.first } : {}),
+          ...(explicitFeedback ? { feedback_only: !regular } : {}),
+        },
+      }
+      const done = () => { clearTimer(timer); pending.delete(controller) }
+      if (event === 'console_opened') firstVisit = false
+      try {
+        Promise.resolve(send(`${config.host}/i/v0/e/`, { method: 'POST', headers: { 'content-type': 'text/plain' },
+          body: JSON.stringify(payload), signal: controller.signal, credentials: 'omit', referrerPolicy: 'no-referrer',
+          // Survives the reload that follows a local gateway connection.
+          cache: 'no-store', redirect: 'error', keepalive: true,
+        })).then(done, done)
+      } catch { done() }
+      return true // Attempted, never a delivery acknowledgement.
+    }, false)
+  }
+  function observeConsole(connection) {
+    safe(() => {
+      if (opened || !['live', 'setup-required', 'gateway-down'].includes(connection)) return
+      if (capture('console_opened', { gateway_state: connection === 'live' ? 'available' : connection === 'setup-required' ? 'setup_required' : 'unavailable', connection_method: 'existing' })) opened = true
+    })
+  }
+  function observeView(next) {
+    safe(() => { currentView = view(next); if (currentView && currentView !== lastView && capture('view_opened', { previous_view: lastView })) lastView = currentView })
+  }
+  function startFlow(kind, properties = {}, previous = null) {
+    return safe(() => {
+      refresh()
+      if (!state.available || state.sharing !== true || !flow(kind)) return null
+      const installationId = identity().id
+      if (previous?.generation !== generation || previous?.installationId !== installationId || previous?.flow !== kind) previous = null
+      // Only a failed attempt, or the exploration before the first submit,
+      // continues. Anything still running is superseded by this new flow.
+      if (previous && previous.outcome !== 'failed' && previous.started !== null) {
+        if (!previous.outcome) finishFlow(previous, 'cancelled')
+        previous = null
+      }
+      const item = { generation, installationId, id: previous?.id ?? randomUUID(), flow: kind, attempt: (previous?.attempt ?? 0) + 1, started: now(), properties: sanitizeEvent('flow_started', properties) }
+      capture('flow_started', { ...item.properties, flow: kind, flow_id: item.id, attempt: item.attempt })
+      step(item, kind === 'session_launch' ? 'requesting' : kind === 'gateway_connection' ? 'connecting' : 'preparing_tools')
+      return item
+    }, null)
+  }
+  function exploreFlow(kind, properties = {}) {
+    return safe(() => {
+      refresh(); if (!state.available || state.sharing !== true || !flow(kind)) return null
+      return { generation, installationId: identity().id, id: randomUUID(), flow: kind, attempt: 0, started: null, properties: sanitizeEvent('flow_started', properties) }
+    }, null)
+  }
+  // Also bind to the stored identity: a suspended tab can miss the brief
+  // opt-out state if sharing is turned off and back on before it resumes.
+  const activeFlow = item => item && item.generation === generation && state.available && state.sharing === true
+    && uuid(item.installationId) && item.installationId === storage().getItem(ID_KEY)
+  const fields = item => ({ ...item.properties, flow: item.flow, flow_id: item.id, attempt: item.attempt })
+  function step(item, next, phaseState = 'entered', category) {
+    safe(() => {
+      refresh(); if (!activeFlow(item)) return
+      const key = `${item.id}:${item.attempt}`, value = `${next}:${phaseState}:${category}`
+      if (steps.get(key) === value) return
+      if (steps.size >= 100) steps.delete(steps.keys().next().value)
+      steps.set(key, value)
+      capture('flow_step_changed', { ...fields(item), step: next, state: phaseState, error_category: category })
+    })
+  }
+  function finishFlow(item, outcome, category) {
+    safe(() => {
+      refresh(); if (!activeFlow(item)) return
+      const key = `${item.id}:${item.attempt}`
+      if (finished.has(key)) return
+      if (finished.size >= 200) finished.delete(finished.values().next().value)
+      finished.add(key); steps.delete(key)
+      item.outcome = outcome
+      capture('flow_finished', { ...fields(item), outcome, start_observed: item.started !== null, duration_ms: item.started === null ? undefined : now() - item.started, error_category: category })
+    })
+  }
+  function ready(item) {
+    safe(() => {
+      refresh(); if (!activeFlow(item)) return
+      const key = `${item.id}:ready`
+      if (finished.has(key)) return
+      if (finished.size >= 200) finished.delete(finished.values().next().value)
+      finished.add(key)
+      capture('sandbox_ready', { flow_id: item.id, duration_ms: now() - item.started, location_type: item.properties.location_type })
+    })
+  }
+  function submitFeedback(properties) {
+    return capture('feedback_submitted', properties, { explicitFeedback: true })
+  }
+  // Only safe correlation metadata is stored, never a name, command, or host.
+  function terminalClick(event, properties = {}) {
+    safe(() => {
+      const item = startFlow('session_launch', { ...properties, launch_target: 'browser' })
+      refresh(); if (!activeFlow(item)) return
+      const url = new URL(event.currentTarget.href)
+      const [path, query = ''] = url.hash.split('?')
+      const params = new URLSearchParams(query); params.set('analyticsFlow', item.id)
+      url.hash = `${path}?${params}`
+      try {
+        const saved = readTerminalFlows()
+        saved.push(item); storage().setItem(TERMINAL_KEY, JSON.stringify(saved.slice(-20)))
+        event.currentTarget.href = url.href
+      } catch { /* Losing correlation cannot affect the link. */ }
+    })
+  }
+  // A restored flow is consumed, so a reload or a copied link starts a new one.
+  function forgetTerminalFlow(saved, id) {
+    try { storage().setItem(TERMINAL_KEY, JSON.stringify(saved.filter(item => item.id !== id))) } catch { /* stale state */ }
+    safe(() => {
+      const url = new URL(getLocation())
+      const [path, query = ''] = url.hash.split('?')
+      const params = new URLSearchParams(query); params.delete('analyticsFlow')
+      url.hash = params.toString() ? `${path}?${params}` : path
+      replaceLocation(url.href)
+    })
+  }
+  function readTerminalFlows() {
+    let values = []
+    try { values = JSON.parse(storage().getItem(TERMINAL_KEY) || '[]') } catch { /* stale state */ }
+    return Array.isArray(values) ? values.filter(item => uuid(item.id) && item.flow === 'session_launch' && Number.isFinite(item.started) && now() - item.started < 1800000).slice(-20) : []
+  }
+  function terminalFlow(properties, previous) {
+    return safe(() => {
+      refresh(); if (!state.available || state.sharing !== true) return null
+      if (previous) return startFlow('session_launch', properties, previous)
+      const id = new URLSearchParams(new URL(getLocation()).hash.split('?')[1]).get('analyticsFlow')
+      const installationId = identity().id
+      const saved = readTerminalFlows(), restored = saved.find(item => item.id === id && item.installationId === installationId)
+      if (id) forgetTerminalFlow(saved, id)
+      if (!restored) return startFlow('session_launch', { ...properties, launch_target: 'browser' })
+      return { generation, installationId, id: restored.id, flow: 'session_launch', attempt: number(restored.attempt) ?? 1, started: restored.started, properties: sanitizeEvent('flow_started', restored.properties) }
+    }, null)
+  }
+  function templateStarted(record, owner) {
+    safe(() => {
+      refresh(); if (!state.available || state.sharing !== true) return
+      if (record.status === 'ready') { capture('feature_used', { feature: 'template', action: 'built', location_type: analyticsLocation(owner) }); return }
+      if (record.status !== 'building') return
+      if (templates.size >= 100) templates.delete(templates.keys().next().value)
+      templates.set(JSON.stringify([owner?.context, record.name]), { installationId: identity().id, startedAt: record.startedAt, at: now(), location_type: analyticsLocation(owner) })
+    })
+  }
+  function observeTemplates(records) {
+    safe(() => {
+      for (const record of records) {
+        const key = JSON.stringify([record.location?.context, record.name]), tracked = templates.get(key)
+        if (!tracked) continue
+        if (tracked.installationId !== storage().getItem(ID_KEY) || now() - tracked.at > 1800000) { templates.delete(key); continue }
+        // A finished template record has no build start time; a different
+        // start time means a newer build replaced the tracked one.
+        if ((record.startedAt && record.startedAt !== tracked.startedAt) || record.location?.connected === false) continue
+        if (record.status === 'ready') { templates.delete(key); capture('feature_used', { feature: 'template', action: 'built', location_type: tracked.location_type }) }
+        else if (record.status === 'failed') templates.delete(key)
+      }
+    })
+  }
+  return { configure, setSharing, refresh, capture, observeConsole, observeView, startFlow, exploreFlow, step, finishFlow, ready, templateStarted, observeTemplates,
+    submitFeedback, terminalClick, terminalFlow,
+    subscribe: listener => { listeners.add(listener); return () => listeners.delete(listener) }, getSnapshot: () => state,
+    stop: () => { authorized = false; halt(); refresh() },
+  }
+}
+
+export const analytics = createAnalytics()
+export const analyticsLocation = value => value?.target === 'cloud' ? 'cloud' : value?.remote ? 'ssh' : 'local'
+
+// Capture successful product mutations at the shared API boundary. Only fixed
+// method/path patterns select events; no path, response, or request body is sent.
+export function analyticsFeatureRequest(suffix, method) {
+  if (method === 'GET' || method === undefined) return
+  const rules = [
+    [/^\/setups\/save$/, 'setup', 'imported'], [/^\/setups\/[^/]+\/enable$/, 'setup', 'activated'],
+    [/^\/egress\/policies$/, 'network', 'rule_saved'], [/^\/org\/members$/, 'group', 'membership_saved'],
+    [/^\/files\/[^/]+\/uploads\/[^/]+\/commit$/, 'files', 'uploaded'],
+    [/^\/sandboxes\/[^/]+\/start$/, 'sandbox', 'started'], [/^\/sandboxes\/[^/]+\/stop$/, 'sandbox', 'stopped'], [/^\/sandboxes\/[^/]+\/delete$/, 'sandbox', 'deleted'],
+  ]
+  const rule = rules.find(([pattern]) => pattern.test(suffix))
+  if (rule) analytics.capture('feature_used', { feature: rule[1], action: rule[2] })
+}

package/src/lib/api.js

@@ -2,6 +2,7 @@
 // holds the gateway certificate, so nothing here carries a credential.
 
 import { computeApiPath, currentComputeTarget, currentCloudOwner } from './compute-target.js'
+import { analyticsFeatureRequest } from './analytics.js'
 
 // The local server answers 401 with this code until the browser opens the
 // tokened link that `openrod` prints; the app then shows how to get back in.
@@ -15,7 +16,10 @@ export function createApi(target, signal, locationContext = null, boundOwner = c
   const requestSignal = extra => signal && extra ? AbortSignal.any([signal, extra]) : signal ?? extra
   async function loadContext() {
     signal?.throwIfAborted()
-    const response = await fetch(path('/context'), { signal, headers: selected() === 'cloud' && owner ? { 'x-openrod-local-owner': owner } : undefined })
+    const response = await fetch(path('/context'), { signal, headers: {
+      ...(selected() === 'cloud' && owner ? { 'x-openrod-local-owner': owner } : {}),
+      ...(locationContext ? { 'x-openshell-context': locationContext, 'x-openshell-location': '1' } : {}),
+    } })
     const context = await response.json()
     signal?.throwIfAborted()
     if (context.code === LINK_REQUIRED) window.dispatchEvent(new Event(LINK_REQUIRED))
@@ -52,7 +56,8 @@ export function createApi(target, signal, locationContext = null, boundOwner = c
     currentSignal?.throwIfAborted()
     if (payload.code === LINK_REQUIRED) window.dispatchEvent(new Event(LINK_REQUIRED))
     else if (response.status === 401 || payload.code === 'CLOUD_OWNER_CHANGED') window.dispatchEvent(new Event('openrod-session-expired'))
-    if (!response.ok) throw Object.assign(new Error(payload.error ?? `Request failed (${response.status})`), { code: payload.code, sandboxes: payload.sandboxes, fix: payload.fix })
+    if (!response.ok) throw Object.assign(new Error(payload.error ?? `Request failed (${response.status})`), { status: response.status, code: payload.code, sandboxes: payload.sandboxes, fix: payload.fix })
+    analyticsFeatureRequest(suffix, method)
     return payload
   }
   return {
@@ -65,17 +70,29 @@ export function createApi(target, signal, locationContext = null, boundOwner = c
     inventory: extraSignal => request('/inventory', { signal: extraSignal, scoped: false }),
     context: loadContext,
     contextKey,
+    capabilities: () => request('/capabilities', { scoped: false }),
+    importCapabilities: () => request('/resource-imports/capabilities'),
+    exportResources: body => request('/resource-imports/export', { method: 'POST', body }),
+    planImport: body => request('/resource-imports/plan', { method: 'POST', body }),
+    importJobs: () => request('/resource-imports'),
+    importJob: id => request(`/resource-imports/${encodeURIComponent(id)}`),
+    executeImport: id => request(`/resource-imports/${encodeURIComponent(id)}/execute`, { method: 'POST', body: { acknowledged: true } }),
+    retryImport: id => request(`/resource-imports/${encodeURIComponent(id)}/retry`, { method: 'POST', body: { acknowledged: true } }),
+    cancelImport: id => request(`/resource-imports/${encodeURIComponent(id)}/cancel`, { method: 'POST', body: {} }),
     connections: extraSignal => request('/connections', { signal: extraSignal, scoped: false }),
     connectionJob: (id, extraSignal) => request(`/connections/jobs/${encodeURIComponent(id)}`, { signal: extraSignal, scoped: false }),
-    connect: body => request('/connections/connect', { method: 'POST', body }),
-    installConnectionDocker: id => request(`/connections/jobs/${encodeURIComponent(id)}/docker`, { method: 'POST', body: { approve: true } }),
-    installConnectionRuntime: id => request(`/connections/jobs/${encodeURIComponent(id)}/install`, { method: 'POST', body: { method: 'download' } }),
-    uploadConnectionPackage: (id, file) => request(`/connections/jobs/${encodeURIComponent(id)}/package`, { method: 'POST', body: file, raw: true }),
-    scanSshHost: body => request('/connections/hosts/scan', { method: 'POST', body }),
-    addSshHost: token => request('/connections/hosts', { method: 'POST', body: { token } }),
-    removeSshHost: alias => request('/connections/hosts/remove', { method: 'POST', body: { alias } }),
-    forgetRemote: () => request('/connections/forget', { method: 'POST', body: {} }),
-    disconnectRemote: () => request('/connections/disconnect', { method: 'POST', body: {} }),
+    // These manage console connections, so an offline working location must
+    // never gate reconnecting, forgetting, or selecting a different gateway.
+    connect: body => request('/connections/connect', { method: 'POST', body, scoped: false }),
+    installConnectionDocker: id => request(`/connections/jobs/${encodeURIComponent(id)}/docker`, { method: 'POST', body: { approve: true }, scoped: false }),
+    installConnectionRuntime: id => request(`/connections/jobs/${encodeURIComponent(id)}/install`, { method: 'POST', body: { method: 'download' }, scoped: false }),
+    uploadConnectionPackage: (id, file) => request(`/connections/jobs/${encodeURIComponent(id)}/package`, { method: 'POST', body: file, raw: true, scoped: false }),
+    scanSshHost: body => request('/connections/hosts/scan', { method: 'POST', body, scoped: false }),
+    addSshHost: token => request('/connections/hosts', { method: 'POST', body: { token }, scoped: false }),
+    removeSshHost: alias => request('/connections/hosts/remove', { method: 'POST', body: { alias }, scoped: false }),
+    restoreSshHost: host => request('/connections/hosts/restore', { method: 'POST', body: { host }, scoped: false }),
+    forgetRemote: () => request('/connections/forget', { method: 'POST', body: {}, scoped: false }),
+    disconnectRemote: () => request('/connections/disconnect', { method: 'POST', body: {}, scoped: false }),
     syncLocalCatalog: () => request('/local-catalog', { method: 'POST', body: {} }),
     gatewayDocker: (fresh = false) => request(`/gateway-docker${fresh ? '?fresh=1' : ''}`, { scoped: false }),
     connectGatewayDocker: (seen = [], confirm = true) => request('/gateway-docker/connect', { method: 'POST', body: { confirm, seen }, scoped: false }),

package/src/lib/cloud-sign-in-error.js

@@ -0,0 +1,13 @@
+const messages = {
+  'auth/network-request-failed': 'Couldn’t reach Google. Check your connection and try again.',
+  'auth/popup-closed-by-user': 'Sign-in cancelled.',
+  'auth/cancelled-popup-request': 'Sign-in cancelled.',
+  'auth/popup-blocked': 'Allow popups, then try again.',
+  'auth/unauthorized-domain': 'Sign-in isn’t configured for this address. Contact your administrator.',
+  'auth/user-disabled': 'This account is disabled. Contact your administrator.',
+  'auth/too-many-requests': 'Too many attempts. Try again shortly.',
+}
+
+export function cloudSignInError(reason) {
+  return messages[reason?.code] || 'Couldn’t sign in. Try again.'
+}

package/src/lib/cloud-transfer.js

@@ -10,7 +10,7 @@ export function cloudHandoffUrl(origin, nonce, cloud = CLOUD_ORIGIN) {
 export function isCloudReadyMessage(event, popup, nonce, cloud = CLOUD_ORIGIN) {
   return Boolean(cloud && popup && event.source === popup && event.origin === cloud
     && event.data?.type === 'openrod-cloud-ready' && event.data.nonce === nonce
-    && typeof event.data.ticket === 'string' && /^openrod-user-[a-f0-9]{24}\.[a-f0-9]{64}$/.test(event.data.ticket))
+    && typeof event.data.ticket === 'string' && /^[a-z][a-z0-9-]{0,62}\.[a-f0-9]{64}$/.test(event.data.ticket))
 }
 
 export const LOCAL_ORIGIN = 'http://127.0.0.1:4600'

package/src/lib/combined-activity.js

@@ -0,0 +1,95 @@
+import { activityRow, filterActivity, SEVERITY_RANK } from './activity-inventory.js'
+import { locationLabel, resourceKey } from './locations.js'
+
+// Each source pages in activity-store's ORDER BY, so the merge must use that exact
+// order or page boundaries skip and repeat events. Keep these keys in step with it.
+const SORTABLE = new Set(['time', 'sandbox', 'scope', 'sandboxId', 'agent', 'category', 'severity', 'logLevel', 'direction', 'verdict', 'outcome', 'process', 'action', 'destination', 'policy', 'session', 'correlation', 'why'])
+// SQLite's BINARY collation compares UTF-8 bytes (code point order), not UTF-16 units.
+const binary = (a, b) => { let i = 0; while (i < a.length && i < b.length && a[i] === b[i]) i++; return i < a.length && i < b.length ? a.codePointAt(i) - b.codePointAt(i) : a.length - b.length }
+// json_extract yields NULL, a number (booleans as 0/1) or text, ordered in that sequence.
+const sqlValue = value => typeof value === 'boolean' ? Number(value) : typeof value === 'number' ? (Number.isFinite(value) ? value : null) : value == null ? null : typeof value === 'object' ? JSON.stringify(value) : String(value)
+const typeRank = value => value === null ? 0 : typeof value === 'number' ? 1 : 2
+const compareSql = (a, b) => typeRank(a) - typeRank(b) || (typeof a === 'number' ? a - b : typeof a === 'string' ? binary(a, b) : 0)
+const severityRank = value => { const name = String(value ?? '').replace(/[a-z]+/g, letters => letters.toUpperCase()); return Object.hasOwn(SEVERITY_RANK, name) ? SEVERITY_RANK[name] : -1 }
+export function serverSort(rows, sort) {
+  const key = SORTABLE.has(sort?.key) ? sort.key : 'time', direction = sort?.direction === 'asc' ? 1 : -1
+  const value = row => key === 'time' ? (Number.isFinite(row.timestamp) ? row.timestamp : 0) : key === 'severity' ? severityRank(row.values.severity) : sqlValue(row.values[key])
+  return rows.map(row => [value(row), row]).sort(([av, a], [bv, b]) => direction * compareSql(av, bv) || binary(String(a.event.originalId ?? a.event.id ?? ''), String(b.event.originalId ?? b.event.id ?? '')) || binary(a.key, b.key)).map(([, row]) => row)
+}
+
+// Page each source at its own snapshot, then merge. Names and event ids are
+// only unique within a source; mutation plans retain that source throughout.
+export function combinedActivityApi(base, getLocations, apiFor) {
+  const cache = new Map(), plans = new Map()
+  let sequence = 0
+  return {
+    ...base,
+    async activity(options = {}) {
+      const { offset = 0, limit = 50, snapshot = {}, exportAll, ...query } = options
+      const now = query.now ?? Date.now()
+      const {now: queryNow, ...filters} = query
+      const key = JSON.stringify(filters)
+      const locations = getLocations(), unavailable = []
+      const entries = await Promise.all(locations.map(async (location, index) => {
+        const identity = location.id ?? location.context
+        const cacheKey = `${identity}:${key}`
+        // An export must be complete, so it never substitutes a cached page.
+        const prior = exportAll ? null : cache.get(cacheKey)
+        if (!location.connected) { unavailable[index] = {label: locationLabel(location), offline: true}; return prior ? {...prior, total:prior.events.length, events: prior.events.map(event => ({...event, location}))} : null }
+        try {
+          const events = []; let result, sourceOffset = 0, sourceSnapshot = snapshot?.[identity]
+          const needed = exportAll ? Infinity : offset + limit
+          do {
+            result = await apiFor(location).activity({...query, now, offset: sourceOffset, limit: Math.min(1000, needed - sourceOffset), ...(sourceSnapshot != null ? {snapshot: sourceSnapshot} : {})})
+            sourceSnapshot = result.snapshot
+            events.push(...result.events.map(event => ({...event, originalId: event.id, id: resourceKey({id: event.id, location}), location})))
+            sourceOffset += result.events.length
+          } while (sourceOffset < needed && sourceOffset < result.total && result.events.length)
+          const entry = {...result, events, identity, snapshot: sourceSnapshot}
+          if (!exportAll) cache.set(cacheKey, entry)
+          return entry
+        } catch (error) {
+          unavailable[index] = {label: locationLabel(location), error: error.message}
+          if (prior) return {...prior, total:prior.events.length, events: prior.events.map(event => ({...event, location: {...location, connected: false}}))}
+          return {error}
+        }
+      }))
+      const available = entries.filter(entry => entry && !entry.error)
+      if (!available.length && entries.some(entry => entry?.error)) throw entries.find(entry => entry?.error).error
+      // filterActivity only filters here; serverSort sets the order.
+      const merged = serverSort(filterActivity(available.flatMap(entry => entry.events).map(activityRow), {...query, now, sort: {key: 'time'}}), query.sort).map(row => row.event)
+      const total = available.reduce((sum, entry) => sum + entry.total, 0)
+      return {events: exportAll ? merged : merged.slice(offset, offset + limit), total, now,
+        snapshot: Object.fromEntries(available.map(entry => [entry.identity, entry.snapshot])),
+        sandboxes: [...new Set(available.flatMap(entry => entry.sandboxes ?? []))], agents: [...new Set(available.flatMap(entry => entry.agents ?? []))],
+        nextOffset: offset + limit < total ? offset + limit : null, unavailable: unavailable.filter(Boolean)}
+    },
+    async previewActivityDeletion({mode, ids = [], query}) {
+      const locations = getLocations()
+      const owners = locations.filter(location => mode !== 'selected' || ids.some(id => { try {return JSON.parse(id)[0][0] === (location.target ?? 'local') && JSON.parse(id)[0][1] === location.context} catch {return false} }))
+      if (mode === 'selected' && owners.some(location => !location.connected)) throw new Error('Reconnect the source of the selected logs before deleting them.')
+      const entries = []
+      for (const location of owners.filter(location => location.connected)) {
+        const originalIds = ids.filter(id => {try {const [owner] = JSON.parse(id);return owner[0] === (location.target ?? 'local') && owner[1] === location.context} catch {return false}}).map(id => JSON.parse(id)[1])
+        const plan = await apiFor(location).previewActivityDeletion({mode, ...(mode === 'selected' ? {ids: originalIds} : {}), query})
+        entries.push({location, plan})
+      }
+      const token = `combined:${++sequence}`
+      plans.set(token, {entries, deleted: 0})
+      return {token, mode, count: entries.reduce((sum, entry) => sum + entry.plan.count, 0), expiresAt: entries.length ? Math.min(...entries.map(entry => entry.plan.expiresAt)) : Date.now(),
+        sources: entries.map(entry => ({label: locationLabel(entry.location), count: entry.plan.count})), skipped: owners.filter(location => !location.connected).map(locationLabel)}
+    },
+    async deleteActivity(token) {
+      const plan = plans.get(token)
+      if (!plan) throw new Error('Review the log deletion again.')
+      // Remove successful entries so retrying a partial failure never repeats it.
+      while (plan.entries.length) {
+        const entry = plan.entries[0]
+        const result = await apiFor(entry.location).deleteActivity(entry.plan.token)
+        plan.deleted += result.deleted; plan.entries.shift()
+      }
+      plans.delete(token)
+      return {deleted: plan.deleted}
+    },
+  }
+}

package/src/lib/connection-host.js

@@ -0,0 +1,6 @@
+// Opening a specific connection must never redirect the user to another host.
+export function connectionHost(connections, initialHost, chosenHost) {
+  const pending = connections.job && ['working', 'needs-install', 'needs-docker'].includes(connections.job.status) ? connections.job : null
+  const host = chosenHost ?? initialHost ?? pending?.host ?? connections.active?.host ?? connections.hosts[0]?.name ?? ''
+  return { host, job: pending?.host === host ? pending : null }
+}

package/src/lib/egress-inventory.js

@@ -0,0 +1,63 @@
+import { sourceOf,hostOf,isIp,portOf } from './policy-sources.js'
+import { blockPatterns,hostMatches } from './egress.js'
+import { resourceKey } from './locations.js'
+
+export function egressRows(sandboxes, events, org) {
+    const dest = new Map()
+    const allowedBy = new Map()
+    const perSandbox = new Map()
+    for (const s of sandboxes) {
+      const hosts = new Set()
+      const counts = {}
+      for (const r of s.rules) {
+        const src = sourceOf(r.key)
+        counts[src] = (counts[src] ?? 0) + 1
+        for (const e of r.endpoints) {
+          if (e.blocked) continue
+          hosts.add(e.host)
+          const d = dest.get(e.host) ?? { host: e.host, sources: new Set(), access: new Set(), ports: new Set(), sandboxes: new Set(), grants: [], hits: 0, hitsBySandbox: new Map() }
+          d.sources.add(src); d.access.add(e.access); e.ports.forEach((p) => d.ports.add(p)); d.sandboxes.add(s.name)
+          let grant = d.grants.find((g) => g.sandbox === s.name && g.key === r.key)
+          if (!grant) {
+            grant = { sandbox: s.name, key: r.key, source: src, access: [], ports: [] }
+            d.grants.push(grant)
+          }
+          grant.access.push(e.access)
+          grant.ports.push(...e.ports)
+          dest.set(e.host, d)
+        }
+      }
+      allowedBy.set(s.name, hosts)
+      perSandbox.set(s.name, { counts, blocked: 0 })
+    }
+    const block = new Map()
+    for (const e of events) {
+      if (e.kind !== "audit" || !e.verdict) continue
+      const host = hostOf(e.destination)
+      if (!host || isIp(host)) continue
+      if (e.verdict === "allowed") { const d = dest.get(host); if (d) { d.hits += 1; d.hitsBySandbox.set(e.sandbox, (d.hitsBySandbox.get(e.sandbox) ?? 0) + 1) }; continue }
+      if (e.verdict !== "denied" || allowedBy.get(e.sandbox)?.has(host)) continue
+      const b = block.get(host) ?? { host, port: portOf(e.destination), sandboxes: new Set(), attempts: 0, programs: new Set(), lastAt: null }
+      b.attempts += 1; b.sandboxes.add(e.sandbox)
+      if (e.binary) b.programs.add(e.binary)
+      if (e.at && (!b.lastAt || e.at > b.lastAt)) b.lastAt = e.at
+      block.set(host, b)
+      const p = perSandbox.get(e.sandbox); if (p) p.blocked += 1
+    }
+    // Hosts a block already decides are not waiting for anyone.
+    const decided = blockPatterns([...(org?.org?.blocked ?? []), ...(org?.policies ?? []).filter((p) => p.action === "block").flatMap((p) => p.destinations)])
+    return {
+      destinations: [...dest.values()].sort((a, b) => b.sandboxes.size - a.sandboxes.size || b.hits - a.hits || a.host.localeCompare(b.host)),
+      blocked: [...block.values()].filter((b) => !decided.some((pattern) => hostMatches(pattern, b.host))).sort((a, b) => b.sandboxes.size - a.sandboxes.size || b.attempts - a.attempts),
+      perSandbox,
+    }
+}
+
+export function combinedEgressInventory(sources) {
+  const inventories=sources.map(source=>({location:source.location,...egressRows(source.data?.fleetPolicy?.sandboxes ?? [],source.data?.activity?.events ?? [],source.data?.org)}))
+  return {
+    destinations:inventories.flatMap(source=>source.destinations.map(row=>({...row,location:source.location}))),
+    blocked:inventories.flatMap(source=>source.blocked.map(row=>({...row,location:source.location}))),
+    perSandbox:new Map(inventories.flatMap(source=>[...source.perSandbox].map(([name,row])=>[resourceKey({name,location:source.location}),row]))),
+  }
+}