Python
"""Join-acceptor: the controller half of remote homes, as one mountable module.
Deliberately self-contained (remote-home-design.md, owner ruling 2026-08-24):
the desktop sidecar mounts this next to its own routes; the future cloud
service imports THIS module and adds multi-tenant auth — never an extraction
project. It owns:
- arming + single-use enrollment tokens (10-minute TTL, in-memory: a
restart disarms, which is the safe default),
- the machines registry (durable) and the live socket map (presence),
- the `/ws/machine` endpoint (hello → challenge → auth → welcome),
- the proxy prefix `/v1/machines/{mid}/p/<path>` that makes a remote home
literally "a different base URL" for the GUI.
Auth model: the REST surface rides the sidecar-token middleware like every
other /v1 route (GUI-only). The machine WebSocket is the one surface remote
boxes reach, and it authenticates with the enrollment token (first contact)
or an ed25519 challenge-response (every reconnect) — never the sidecar token,
which must not leave this machine.
"""
from __future__ import annotations
import asyncio
import inspect
import json
import re
import secrets as pysecrets
import time
from typing import Any, Optional
from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect
from fastapi.responses import JSONResponse, PlainTextResponse, Response
from . import channel as ch
from .audit import AuditLog, NullAuditLog
from .identity import seal_b64, verify_b64, verify_seal_attestation
from .provision import LocalProvisioner, Provisioner
from .stores import Ephemera, InMemoryEphemera, Registry
TOKEN_TTL_SECONDS = 600.0
_CHALLENGE_BYTES = 32
# Device-authorization flow (`openworker join`): the box asks, the user
# approves in the controller UI, approval mints the one join token.
DEVICE_TTL_SECONDS = 900.0
DEVICE_POLL_SECONDS = 5
# TTL-leased Ephemera backends (Redis) get a heartbeat from each live machine
# connection, so a crashed acceptor node frees its identities by expiry.
LEASE_REFRESH_SECONDS = 30.0
# No lookalike characters — the user reads this code off a terminal.
_USER_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"
# The one proxied path whose successful responses feed the transcript cache.
_TRANSCRIPT_PATH = re.compile(r"v1/sessions/([^/]+)/messages")
# How long a proxied call waits for a just-woken sandbox to dial back in.
WAKE_WAIT_SECONDS = 45.0
# Proxied hops must not forward controller-side auth or hop-by-hop headers.
_PROXY_SKIP_RESPONSE_HEADERS = {
"content-length",
"transfer-encoding",
"connection",
"content-encoding",
}
class _LiveMachine:
def __init__(self, machine_id: str, name: str, rpc: ch.RpcClient) -> None:
self.machine_id = machine_id
self.name = name
self.rpc = rpc
self.connected_at = time.time()
# Bridged WebSocket streams: stream id -> the GUI-facing socket.
self.streams: dict[str, WebSocket] = {}
self.stream_counter = 0
class RemoteAcceptor:
def __init__(self, registry: Registry, ephemera: Optional[Ephemera] = None) -> None:
self.registry = registry
self.ephemera: Ephemera = ephemera or InMemoryEphemera()
self._live: dict[str, _LiveMachine] = {} # machine_id -> live channel
# -- arming ---------------------------------------------------------------
def arm(
self,
bound_fingerprint: str = "",
org_id: str = "",
actor: str = "",
provenance: Optional[dict[str, str]] = None,
) -> tuple[str, float]:
"""Mint one single-use enrollment token; arming is per-token, not a
mode. A bound token enrolls only the machine identity it was approved
for (the device flow binds; the Add-a-machine card does not). The
token carries the org the enrollment lands in — that is how a brand-new
machine inherits its tenant — and, for a managed sandbox, the
provenance {"kind", "ref"} stamped on the row it enrolls."""
token = pysecrets.token_urlsafe(24)
expiry = time.time() + TOKEN_TTL_SECONDS
self.ephemera.add_token(token, expiry, bound_fingerprint, org_id, actor, provenance)
return token, expiry
def disarm(self) -> None:
self.ephemera.clear_tokens()
def consume_token(self, token: str) -> Optional[dict[str, Any]]:
"""None = invalid/expired; else {"fingerprint": binding or "", "org_id": …}."""
return self.ephemera.consume_token(token)
@property
def armed(self) -> bool:
return self.ephemera.has_tokens()
# -- presence -------------------------------------------------------------
def live(self, machine_id: str) -> Optional[_LiveMachine]:
return self._live.get(machine_id)
def machines(self, org_id: Optional[str] = None) -> list[dict[str, Any]]:
rows = []
for row in self.registry.list(org_id):
live = self._live.get(row["id"])
rows.append(
{
"id": row["id"],
"name": row["name"],
"fingerprint": _fingerprint(row["pubkey"]),
"app_version": row.get("app_version") or "",
# Fleet under the org: who armed/approved the enrollment.
"enrolled_by": row.get("enrolled_by") or "",
# "" = the user's own machine; "fly" = a managed sandbox
# (spec §Fly sandboxes) — the dashboard shows the difference.
"provenance": row.get("provenance") or "",
"provenance_ref": row.get("provenance_ref") or "",
"created_at": row["created_at"],
"last_seen": row["last_seen"],
"connected": live is not None,
# Public halves only. The sealing key lets a BROWSER seal
# deploys to this machine (OPE-149); its fingerprint is
# what the user checks against `openworker machine status`.
"seal_pubkey": row.get("seal_pubkey") or "",
"seal_fingerprint": (
_fingerprint(row["seal_pubkey"])
if row.get("seal_pubkey")
else ""
),
}
)
return rows
def attach(self, machine_id: str, name: str, pubkey: str, rpc: ch.RpcClient) -> None:
"""Caller holds the clone-trap lease for pubkey (acquired pre-enroll)."""
self._live[machine_id] = _LiveMachine(machine_id, name, rpc)
async def push_policy(self, machine_id: str, policy: dict[str, Any]) -> tuple[int, dict[str, Any]]:
"""Hand a live machine its (changed) org policy; (status, body) from the
box. Offline machines get it on their next welcome."""
live = self.live(machine_id)
if live is None:
return 503, {"error": "machine offline"}
status, body, _ = await live.rpc.request_frame({"type": "policy", "policy": policy})
try:
parsed = json.loads(body.decode() or "{}")
except (ValueError, AttributeError):
parsed = {}
return status, parsed
async def detach(self, machine_id: str, pubkey: str) -> None:
live = self._live.pop(machine_id, None)
self.ephemera.release_lease(pubkey)
if live is not None:
live.rpc.close()
for gui_ws in list(live.streams.values()):
try:
await gui_ws.close(code=1001) # machine went away
except Exception:
pass
live.streams.clear()
self.registry.touch(machine_id)
def _fingerprint(pubkey_b64: str) -> str:
import base64
import hashlib
try:
raw = base64.b64decode(pubkey_b64.encode("ascii"))
except Exception:
return ""
return hashlib.sha256(raw).hexdigest()[:16]
def mount_acceptor(
app: FastAPI,
registry: Registry,
*,
ws_authenticated=None,
origin_allowed=None,
api_token: str = "",
wallet=None,
ephemera: Optional[Ephemera] = None,
provisioner: Optional[Provisioner] = None,
audit: Optional[AuditLog] = None,
tenant_resolver=None,
deploy_allowed=None,
approval_url: str = "",
policy_for=None,
audit_sink=None,
policy_status=None,
machine_activity=None,
machine_wake=None,
) -> RemoteAcceptor:
"""`ws_authenticated` is the sidecar's GUI WebSocket auth check — passed in
because it lives in create_app's closure and guards the GUI-facing bridged
socket exactly like /ws/session. The machine-facing socket never uses it.
`wallet` is the desktop's SecretStore — the keys wallet the deploy
endpoints read from (values resolved server-side; the GUI sends NAMES).
`registry`/`ephemera` are the control-plane stores (stores.py) — desktop
passes SQLite/nothing, cloud passes Postgres/Redis implementations.
`tenant_resolver` makes the mount multi-tenant: called with the incoming
Request (or the GUI-facing WebSocket) it returns {"org_id": …, "actor": …}
for an authenticated caller or None (→ 401). Every control-plane endpoint
is then row-scoped to the caller's org, tokens carry the org so machines
enroll into it, and the pending-grants LISTING disappears (approval is by
typed code only — a listing would show other tenants' machines). Omitted
(the desktop), everything runs in the single org ""."""
acceptor = RemoteAcceptor(registry, ephemera)
app.state.remote_acceptor = acceptor
provisioner = provisioner or LocalProvisioner(acceptor)
# Managed sandboxes (spec §Fly sandboxes, lifecycle): `machine_activity(
# machine_id)` is told about every proxied call and bridged socket so the
# control plane can idle-stop a sandbox nobody is using; `machine_wake(
# machine_id) -> bool` is asked when a caller reaches an OFFLINE machine —
# True means "it is a sandbox and I started it", and the proxy then waits
# for the box to dial back in before answering. Desktop passes neither.
def _touch(machine_id: str) -> None:
if machine_activity is not None:
try:
machine_activity(machine_id)
except Exception:
pass
async def _live_or_wake(machine_id: str):
live = acceptor.live(machine_id)
if live is not None or machine_wake is None:
return live
try:
woke = await machine_wake(machine_id)
except Exception:
woke = False
if not woke:
return None
deadline = time.monotonic() + WAKE_WAIT_SECONDS
while time.monotonic() < deadline:
live = acceptor.live(machine_id)
if live is not None:
return live
await asyncio.sleep(0.5)
return None
audit = audit or NullAuditLog()
multi_tenant = tenant_resolver is not None
_desktop_tenant = {"org_id": "", "actor": ""}
async def _tenant(conn) -> Optional[dict[str, Any]]:
"""Resolve the caller's tenant from a Request or WebSocket; None = 401.
The resolver may be sync or async (a hosted one awaits its IdP)."""
if tenant_resolver is None:
return _desktop_tenant
result = tenant_resolver(conn)
if inspect.isawaitable(result):
result = await result
return result
_unauthorized = JSONResponse({"error": "unauthorized"}, status_code=401)
def _org_machine(machine_id: str, tenant: dict[str, Any]):
"""Fetch a machine the caller is allowed to touch, or None. A row in
another org is a 404, indistinguishable from not existing at all."""
row = registry.by_id(machine_id)
if row is None or (row.get("org_id") or "") != tenant["org_id"]:
return None
return row
@app.get("/j/{token}")
async def join_hint(token: str) -> PlainTextResponse:
# Informational only, and deliberately constant: it must not confirm
# whether a token is valid to an unauthenticated caller.
return PlainTextResponse(
"This is an OpenWorker join URL. On the machine you want to add, run:\n"
" openworker join <this URL> [--name=my-box]\n"
)
@app.post("/v1/remote/arm")
async def arm(request: Request) -> Any:
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
token, expiry = acceptor.arm(org_id=tenant["org_id"], actor=tenant.get("actor", ""))
base = str(request.base_url).rstrip("/")
return {
"join_url": f"{base}/j/{token}",
"expires_at": expiry,
"ttl_seconds": TOKEN_TTL_SECONDS,
}
@app.delete("/v1/remote/arm")
async def disarm(request: Request) -> Any:
if await _tenant(request) is None:
return _unauthorized
# Disarm clears ALL tokens; on multi-tenant this is coarse but safe
# (tokens are 10-minute, single-use — worst case someone re-arms).
acceptor.disarm()
return {"armed": False}
# -- device-authorization flow (`openworker join`) --------------------
# start/poll are machine-facing and tokenless (like /j/ and /ws/machine);
# listing and approve/deny ride the GUI's sidecar-token middleware. The
# approval MINTS the one join token, bound to the requesting identity —
# auth join is a third path to the same enrollment primitive, never a
# second primitive.
@app.post("/v1/remote/device/start")
async def device_start(request: Request) -> dict[str, Any]:
try:
body = await request.json()
except Exception:
body = {}
device_code = pysecrets.token_urlsafe(24)
user_code = "-".join(
"".join(pysecrets.choice(_USER_CODE_ALPHABET) for _ in range(4))
for _ in range(2)
)
acceptor.ephemera.put_grant(
{
"device_code": device_code,
"user_code": user_code,
"name": str(body.get("name") or "machine")[:64],
"fingerprint": str(body.get("fingerprint") or "")[:64],
"status": "pending",
"join_url": "",
"created_at": time.time(),
"expires_at": time.time() + DEVICE_TTL_SECONDS,
}
)
return {
"device_code": device_code,
"user_code": user_code,
"interval": DEVICE_POLL_SECONDS,
"expires_in": DEVICE_TTL_SECONDS,
# A deployment that serves the SPA hands out a clickable approval
# deep link (the joiner prints it); desktop has no approval web
# page, so the hint is the instruction there.
"verification_url": (
approval_url.format(code=user_code) if approval_url else ""
),
"verification_hint": "Approve in the OpenWorker app: Settings → Machines",
}
@app.post("/v1/remote/device/poll")
async def device_poll(request: Request) -> dict[str, Any]:
try:
body = await request.json()
except Exception:
body = {}
grant = acceptor.ephemera.grant_by_device_code(str(body.get("device_code") or ""))
if grant is None:
return {"status": "expired"}
if grant["status"] == "approved":
# Single-shot delivery: the join URL leaves the store with this reply.
acceptor.ephemera.remove_grant(grant["device_code"])
return {"status": "approved", "join_url": grant["join_url"]}
if grant["status"] == "denied":
acceptor.ephemera.remove_grant(grant["device_code"])
return {"status": "denied"}
return {"status": "pending", "interval": DEVICE_POLL_SECONDS}
@app.get("/v1/remote/device")
async def device_requests(request: Request) -> Any:
if await _tenant(request) is None:
return _unauthorized
if multi_tenant:
# Pending grants belong to no org until approved; listing them
# would show every tenant's machine names and fingerprints.
# Multi-tenant approval is by typed code only (GitHub-style).
return JSONResponse({"error": "approval is by code"}, status_code=404)
pending = [
{
"user_code": g["user_code"],
"name": g["name"],
"fingerprint": g["fingerprint"],
"created_at": g["created_at"],
"expires_at": g["expires_at"],
}
for g in acceptor.ephemera.list_grants()
if g["status"] == "pending"
]
return {"requests": sorted(pending, key=lambda g: g["created_at"])}
@app.get("/v1/remote/device/{user_code}")
async def device_detail(user_code: str, request: Request) -> Any:
"""What the approval surface shows before the user confirms: the
machine's claimed name + fingerprint. Knowing the code IS the
capability (short-lived, high-entropy, single grant)."""
if await _tenant(request) is None:
return _unauthorized
grant = acceptor.ephemera.grant_by_user_code(user_code)
if grant is None or grant["status"] != "pending":
return JSONResponse({"error": "unknown or expired code"}, status_code=404)
return {
"user_code": grant["user_code"],
"name": grant["name"],
"fingerprint": grant["fingerprint"],
"expires_at": grant["expires_at"],
}
@app.post("/v1/remote/device/{user_code}/approve")
async def device_approve(user_code: str, request: Request) -> Response:
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
grant = acceptor.ephemera.grant_by_user_code(user_code)
if grant is None or grant["status"] != "pending":
return JSONResponse({"error": "unknown or expired code"}, status_code=404)
# Approval CLAIMS the grant into the approver's org: the minted token
# carries it, so the machine enrolls as that tenant's.
minted = provisioner.mint_token(
{
"fingerprint": grant["fingerprint"],
"org_id": tenant["org_id"],
"actor": tenant.get("actor", ""),
}
)
base = str(request.base_url).rstrip("/")
acceptor.ephemera.update_grant(
grant["device_code"],
status="approved",
join_url=f"{base}/j/{minted['token']}",
)
audit.emit(
"update",
entity_type="device_grant",
entity_name=grant["name"],
detail={"decision": "approved", "fingerprint": grant["fingerprint"]},
actor=tenant["actor"],
org_id=tenant["org_id"],
)
return JSONResponse({"ok": True})
@app.post("/v1/remote/device/{user_code}/deny")
async def device_deny(user_code: str, request: Request) -> Response:
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
grant = acceptor.ephemera.grant_by_user_code(user_code)
if grant is None or grant["status"] != "pending":
return JSONResponse({"error": "unknown or expired code"}, status_code=404)
acceptor.ephemera.update_grant(grant["device_code"], status="denied")
audit.emit(
"update",
entity_type="device_grant",
entity_name=grant["name"],
detail={"decision": "denied", "fingerprint": grant["fingerprint"]},
actor=tenant["actor"],
org_id=tenant["org_id"],
)
return JSONResponse({"ok": True})
@app.get("/v1/machines")
async def list_machines(request: Request) -> Any:
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
return {
"machines": acceptor.machines(tenant["org_id"]),
"armed": acceptor.armed,
}
@app.patch("/v1/machines/{machine_id}")
async def rename_machine(machine_id: str, request: Request):
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
if _org_machine(machine_id, tenant) is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
payload = await request.json()
name = str(payload.get("name", "")).strip()
if not name:
return JSONResponse({"error": "name required"}, status_code=400)
try:
row = registry.rename(machine_id, name)
except ValueError as exc:
return JSONResponse({"error": str(exc)}, status_code=409)
if row is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
live = acceptor.live(machine_id)
if live is not None:
live.name = row["name"]
return {"machine": {"id": row["id"], "name": row["name"]}}
@app.delete("/v1/machines/{machine_id}")
async def remove_machine(machine_id: str, request: Request):
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
row = _org_machine(machine_id, tenant)
if row is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
live = acceptor.live(machine_id)
if live is not None:
return JSONResponse(
{"error": "machine is connected; it must leave (or go offline) first"},
status_code=409,
)
if not registry.remove(machine_id):
return JSONResponse({"error": "unknown machine"}, status_code=404)
audit.emit(
"delete",
entity_type="machine",
entity_name=row["name"],
entity_uid=machine_id,
actor=tenant["actor"],
org_id=tenant["org_id"],
)
return {"removed": machine_id}
@app.get("/v1/wallet")
async def wallet_profiles(request: Request):
"""Wallet contents by NAME AND TYPE only — never values. Feeds the
enrollment card's "provision with my defaults" and the chips UIs."""
if await _tenant(request) is None:
return _unauthorized
if wallet is None:
return {"profiles": []}
return {"profiles": wallet.status()}
@app.get("/v1/machines/{machine_id}/secrets")
async def machine_secrets(machine_id: str, request: Request):
"""The deployments ledger + staleness: which wallet profiles this
machine holds, and whether the wallet's value changed since (hash
comparison — values never flow back)."""
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
if _org_machine(machine_id, tenant) is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
rows = []
for row in registry.deploys(machine_id):
current = _wallet_hash(wallet, row["profile"])
rows.append(
{
"profile": row["profile"],
"deployed_at": row["deployed_at"],
# stale: wallet value changed since deploy (rotate = deploy
# again — owner ruling: no third verb). missing: profile no
# longer in the wallet at all. A wallet-less deployment
# (browser-sealed deploys) has no reference to compare —
# both fields honestly read false there.
"stale": current is not None and current != row["value_hash"],
"missing_from_wallet": wallet is not None and current is None,
}
)
return {"secrets": rows}
@app.post("/v1/machines/{machine_id}/secrets")
async def deploy_secrets(machine_id: str, request: Request):
"""Key deploy, two sources, one frame:
- Wallet path (`{"profiles": [names]}`): the GUI sends NAMES; the
controller resolves values from its own SecretStore, seals them to
the machine's pinned sealing key, and pushes.
- Sealed path (`{"sealed_b64": …, "profiles": [names]}`, OPE-149):
the BROWSER already sealed the payload to that same pinned key;
this endpoint is a blind relay — it never sees plaintext, needs no
wallet, and records only names in the ledger and audit trail.
Either way, deploy = copy — the box owns its copy.
"""
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
known = _org_machine(machine_id, tenant)
if known is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
# Org-level policy checkpoint (OPE-150): the embedder may refuse key
# pushes per tenant. Enforced HERE at the relay — hiding a button is
# cosmetics; this refusal is what a security review tests. The denial
# itself is an audit event (who tried, which org said no).
if deploy_allowed is not None and not deploy_allowed(tenant):
audit.emit(
"create",
entity_type="secret_deploy",
entity_name="(refused)",
entity_uid=machine_id,
detail={"denied": "key_push_disabled"},
success=False,
actor=tenant["actor"],
org_id=tenant["org_id"],
)
return JSONResponse(
{
"error": "key_push_disabled",
"message": "key pushes are turned off for this org.",
},
status_code=403,
)
payload = await request.json()
sealed_b64 = str(payload.get("sealed_b64") or "")
if wallet is None and not sealed_b64:
return JSONResponse({"error": "no wallet configured"}, status_code=500)
live = acceptor.live(machine_id)
if live is None:
return JSONResponse({"error": "machine offline"}, status_code=503)
seal_pubkey = known.get("seal_pubkey") or ""
if not seal_pubkey:
return JSONResponse(
{
"error": "machine has no pinned sealing key yet — "
"reconnect it once on current code, then retry"
},
status_code=409,
)
names = [str(n) for n in (payload.get("profiles") or []) if str(n).strip()]
if not names:
return JSONResponse({"error": "profiles required"}, status_code=400)
if sealed_b64:
sealed = sealed_b64
# Ledger hashes come from the client (it alone saw the values);
# they only ever drive the staleness display, never a decision.
hashes = payload.get("hashes") or {}
ledger = {
name: str(hashes.get(name) or "browser-sealed") for name in names
}
else:
profiles: dict[str, Any] = {}
for name in names:
data = wallet.get(name) # resolved: refs to desktop-only env vars
if data is None: # would silently break on the box
return JSONResponse(
{"error": f"profile '{name}' not in the wallet"},
status_code=400,
)
profiles[name] = data
sealed = seal_b64(seal_pubkey, json.dumps({"profiles": profiles}).encode())
ledger = {name: _hash_profile(data) for name, data in profiles.items()}
try:
status, body, _ = await live.rpc.request_frame(
{"type": "secret_deploy", "sealed_b64": sealed}
)
except (asyncio.TimeoutError, ConnectionError):
return JSONResponse({"error": "machine unreachable"}, status_code=503)
if status != 200:
detail = _safe_json(body)
return JSONResponse(
{"error": detail.get("error", "deploy failed")}, status_code=502
)
for name, value_hash in ledger.items():
registry.record_deploy(machine_id, name, value_hash)
audit.emit(
"create",
entity_type="secret_deploy",
entity_name=name, # profile NAME — values never reach the log
entity_uid=machine_id,
detail={
"machine": known["name"],
**({"source": "browser-sealed"} if sealed_b64 else {}),
},
actor=tenant["actor"],
org_id=tenant["org_id"],
)
return {"ok": True, "deployed": sorted(names)}
@app.post("/v1/machines/{machine_id}/connectors/{name}/connect-sealed")
async def connector_connect_sealed(machine_id: str, name: str, request: Request):
"""Remote manual connect: the client sealed the connector FIELDS to
this machine's pinned key; we relay ciphertext and the box runs its
own connect (validation included). A credential push, so the same
org policy checkpoint as key deploys applies."""
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
known = _org_machine(machine_id, tenant)
if known is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
if deploy_allowed is not None and not deploy_allowed(tenant):
audit.emit(
"create",
entity_type="connector_connect",
entity_name=name,
entity_uid=machine_id,
detail={"denied": "key_push_disabled"},
success=False,
actor=tenant["actor"],
org_id=tenant["org_id"],
)
return JSONResponse(
{
"error": "key_push_disabled",
"message": "key pushes are turned off for this org.",
},
status_code=403,
)
live = acceptor.live(machine_id)
if live is None:
return JSONResponse({"error": "machine offline"}, status_code=503)
payload = await request.json()
sealed = str(payload.get("sealed_b64") or "")
if not sealed:
return JSONResponse({"error": "sealed_b64 required"}, status_code=400)
try:
status, body, _ = await live.rpc.request_frame(
{
"type": "connector_connect_sealed",
"connector": name,
"sealed_b64": sealed,
}
)
except (asyncio.TimeoutError, ConnectionError):
return JSONResponse({"error": "machine unreachable"}, status_code=503)
detail = _safe_json(body)
audit.emit(
"create",
entity_type="connector_connect",
entity_name=name, # connector NAME — fields never reach the log
entity_uid=machine_id,
detail={"machine": known["name"], "source": "browser-sealed"},
success=status == 200 and bool(detail.get("ok")),
actor=tenant["actor"],
org_id=tenant["org_id"],
)
return JSONResponse(detail, status_code=status if status != 200 else 200)
@app.post("/v1/machines/{machine_id}/connectors/{name}/managed-grant-sealed")
async def managed_grant_sealed(machine_id: str, name: str, request: Request):
"""Browser connect-direct (spec §Cloud-dashboard connect-direct): the
dashboard tab sealed a broker OAuth result to this machine's pinned
key; we relay ciphertext and the box stores it through its own
routine. A credential push — the org's key-push checkpoint applies."""
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
known = _org_machine(machine_id, tenant)
if known is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
if deploy_allowed is not None and not deploy_allowed(tenant):
audit.emit(
"create", entity_type="managed_grant", entity_name=name, entity_uid=machine_id,
detail={"denied": "key_push_disabled"}, success=False,
actor=tenant["actor"], org_id=tenant["org_id"],
)
return JSONResponse(
{"error": "key_push_disabled", "message": "key pushes are turned off for this org."},
status_code=403,
)
live = await _live_or_wake(machine_id)
if live is None:
return JSONResponse({"error": "machine offline"}, status_code=503)
payload = await request.json()
sealed = str(payload.get("sealed_b64") or "")
if not sealed:
return JSONResponse({"error": "sealed_b64 required"}, status_code=400)
try:
status, body, _ = await live.rpc.request_frame(
{"type": "managed_grant_sealed", "connector": name, "sealed_b64": sealed}
)
except (asyncio.TimeoutError, ConnectionError):
return JSONResponse({"error": "machine unreachable"}, status_code=503)
detail = _safe_json(body)
audit.emit(
"create", entity_type="managed_grant", entity_name=name, entity_uid=machine_id,
detail={"machine": known["name"], "source": "browser-sealed"},
success=status == 200 and bool(detail.get("ok")),
actor=tenant["actor"], org_id=tenant["org_id"],
)
return JSONResponse(detail, status_code=status if status != 200 else 200)
@app.delete("/v1/machines/{machine_id}/secrets")
async def revoke_secrets(machine_id: str, request: Request):
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
if _org_machine(machine_id, tenant) is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
live = acceptor.live(machine_id)
if live is None:
# An offline box can't be scrubbed; keeping the ledger row is the
# honest state ("this machine still holds that key").
return JSONResponse({"error": "machine offline"}, status_code=503)
payload = await request.json()
names = [str(n) for n in (payload.get("profiles") or []) if str(n).strip()]
if not names:
return JSONResponse({"error": "profiles required"}, status_code=400)
try:
status, body, _ = await live.rpc.request_frame(
{"type": "secret_revoke", "profiles": names}
)
except (asyncio.TimeoutError, ConnectionError):
return JSONResponse({"error": "machine unreachable"}, status_code=503)
if status != 200:
detail = _safe_json(body)
return JSONResponse(
{"error": detail.get("error", "revoke failed")}, status_code=502
)
for name in names:
registry.remove_deploy(machine_id, name)
audit.emit(
"delete",
entity_type="secret_deploy",
entity_name=name,
entity_uid=machine_id,
actor=tenant["actor"],
org_id=tenant["org_id"],
)
return {"ok": True, "revoked": names}
def _cached_rollup(machine_id: str, query: str):
"""An offline machine's last answer to this same rollup request, labelled with when it
was fetched (TD3-6). Only the same period, grouping and coworker count (P3B-3). The
desktop never adds it to the live totals without that label."""
found = registry.last_rollup(machine_id, query)
if found is None:
return None
try:
body = json.loads(found["payload"])
except ValueError:
return None
body["cached"] = {"as_of": int(found["updated_at"] * 1000), "query": found["query"]}
return JSONResponse(body, status_code=200)
@app.api_route(
"/v1/machines/{machine_id}/p/{path:path}",
methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
)
async def proxy(machine_id: str, path: str, request: Request):
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
known = _org_machine(machine_id, tenant)
if known is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
_touch(machine_id)
live = await _live_or_wake(machine_id)
rollup = request.method == "GET" and path == "v1/observability/rollup"
if live is None:
cached = _cached_rollup(machine_id, request.url.query) if rollup else None
return cached or JSONResponse({"error": "machine offline"}, status_code=503)
target = "/" + path
if request.url.query:
target += "?" + request.url.query
body = await request.body()
try:
status, payload, content_type = await live.rpc.request(
request.method,
target,
body=body or None,
content_type=request.headers.get("content-type"),
# Session actor (spec §Fleet under the org): the box records WHO
# is acting, from the login the controller verified — never from a
# header the caller could set.
actor=str(tenant.get("actor") or ""),
)
except asyncio.TimeoutError:
return JSONResponse({"error": "machine timed out"}, status_code=504)
except ConnectionError:
cached = _cached_rollup(machine_id, request.url.query) if rollup else None
return cached or JSONResponse({"error": "machine disconnected"}, status_code=503)
# Phase 3 (E28): each machine's last answer per Usage request, for when it is off.
if rollup and status == 200:
try:
registry.save_rollup(machine_id, request.url.query, payload.decode("utf-8"))
except Exception:
pass
# Tier-2 snapshot: every successful unfiltered session-list fetch doubles
# as the offline fallback (greyed, never vanished). Metadata only.
if (
request.method == "GET"
and path == "v1/sessions"
and not request.url.query
and status == 200
):
try:
registry.save_sessions_snapshot(machine_id, payload.decode("utf-8"))
except Exception:
pass
# Desktop transcript cache (cache-on-view): a transcript fetched while
# connected stays readable read-only while the box is offline.
transcript_match = _TRANSCRIPT_PATH.fullmatch(path)
if request.method == "GET" and transcript_match and status == 200:
try:
registry.save_transcript(
machine_id, transcript_match.group(1), payload.decode("utf-8")
)
except Exception:
pass
return Response(content=payload, status_code=status, media_type=content_type)
@app.get("/v1/machines/{machine_id}/sessions/{session_id}/messages")
async def machine_transcript(machine_id: str, session_id: str, request: Request):
"""The controller's view of one remote transcript: live (proxied, and
re-cached) while the machine is connected; the last synced copy —
read-only by construction — while it is offline."""
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
if _org_machine(machine_id, tenant) is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
live = acceptor.live(machine_id)
if live is not None:
try:
status, payload, _ = await live.rpc.request(
"GET", f"/v1/sessions/{session_id}/messages"
)
if status == 200:
text = payload.decode("utf-8")
registry.save_transcript(machine_id, session_id, text)
data = json.loads(text)
return {"messages": data.get("messages", []), "live": True}
except (asyncio.TimeoutError, ConnectionError, ValueError):
pass # fall through to the cache
cached = registry.transcript(machine_id, session_id)
if cached is None:
return {"messages": [], "live": False, "cached": False}
try:
data = json.loads(cached)
except ValueError:
return {"messages": [], "live": False, "cached": False}
return {"messages": data.get("messages", []), "live": False, "cached": True}
@app.get("/v1/machines/{machine_id}/sessions")
async def machine_sessions(machine_id: str, request: Request):
"""The controller's view of one machine's sessions: live (proxied) while
the machine is connected, the last-known snapshot while it is offline."""
tenant = await _tenant(request)
if tenant is None:
return _unauthorized
if _org_machine(machine_id, tenant) is None:
return JSONResponse({"error": "unknown machine"}, status_code=404)
live = acceptor.live(machine_id)
if live is not None:
try:
status, payload, _ = await live.rpc.request("GET", "/v1/sessions")
if status == 200:
registry.save_sessions_snapshot(
machine_id, payload.decode("utf-8")
)
data = json.loads(payload.decode("utf-8"))
return {"sessions": data.get("sessions", []), "live": True}
except (asyncio.TimeoutError, ConnectionError, ValueError):
pass # fall through to the snapshot
snapshot = registry.sessions_snapshot(machine_id)
if snapshot is None:
return {"sessions": [], "live": False}
try:
data = json.loads(snapshot)
except ValueError:
return {"sessions": [], "live": False}
return {"sessions": data.get("sessions", []), "live": False}
@app.websocket("/ws/machine")
async def ws_machine(ws: WebSocket) -> None:
# Never sidecar-token-authenticated: boxes can't (and must not) hold that
# token. A browser can't pass the challenge without the private key, but
# reject browser origins outright anyway.
origin = ws.headers.get("origin")
if origin is not None:
await ws.close(code=1008)
return
await ws.accept()
machine_id = pubkey = ""
attached = leased = False
heartbeat_task: Optional[asyncio.Task] = None
try:
hello = json.loads(await ws.receive_text())
if hello.get("type") != "hello":
await _reject(ws, "bad-handshake")
return
if int(hello.get("protocol_version", -1)) != ch.PROTOCOL_VERSION:
# P1 stance: strict equality. The friendly error IS the feature.
await _reject(
ws,
"protocol-mismatch",
f"controller speaks protocol {ch.PROTOCOL_VERSION}, "
f"machine spoke {hello.get('protocol_version')} — "
"update the older side",
)
return
pubkey = str(hello.get("pubkey", ""))
if not pubkey:
await _reject(ws, "bad-handshake", "missing pubkey")
return
known = registry.by_pubkey(pubkey)
token = str(hello.get("token") or "")
grant_org = ""
grant_actor = ""
grant_provenance: dict[str, str] = {}
if known is None:
binding = acceptor.consume_token(token)
if binding is None:
await _reject(
ws,
"not-enrolled",
"unknown machine and no valid enrollment token — arm the "
"controller and join with a fresh URL",
)
return
if binding["fingerprint"] and binding["fingerprint"] != _fingerprint(
pubkey
):
# A device-flow token names the identity the user approved;
# any other machine presenting it burns it and gets nothing.
await _reject(
ws,
"wrong-machine",
"this join token was approved for a different machine "
"identity — request approval again from this machine",
)
return
grant_org = binding["org_id"]
grant_actor = str(binding.get("actor") or "")
grant_provenance = dict(binding.get("provenance") or {})
# Both paths prove possession of the private key.
nonce = pysecrets.token_bytes(_CHALLENGE_BYTES)
await ws.send_text(
json.dumps({"type": "challenge", "nonce": ch.encode_body(nonce)})
)
auth = json.loads(await ws.receive_text())
if auth.get("type") != "auth" or not verify_b64(
pubkey, nonce, str(auth.get("signature", ""))
):
await _reject(ws, "bad-signature")
return
if not acceptor.ephemera.acquire_lease(pubkey):
# Clone trap: one concurrent connection per identity. A copied
# state dir must not silently become a second "same" machine.
await _reject(
ws,
"already-connected",
"a machine with this identity is already connected",
)
return
leased = True
app_version = str(hello.get("app_version", ""))
seal_pubkey = str(hello.get("seal_pubkey", ""))
# The challenge only proves the identity key; the sealing key is
# pinned only if that same identity key signed it. Without this a
# middlebox could swap in its own key and read wallet deploys.
if seal_pubkey and not verify_seal_attestation(
pubkey, seal_pubkey, str(hello.get("seal_sig", ""))
):
await _reject(
ws,
"bad-seal-attestation",
"sealing key is not signed by this machine's identity key",
)
return
if known is None:
known = registry.enroll(
str(hello.get("name") or "machine"),
pubkey,
app_version,
seal_pubkey,
org_id=grant_org,
enrolled_by=grant_actor,
provenance=str(grant_provenance.get("kind") or ""),
provenance_ref=str(grant_provenance.get("ref") or ""),
)
audit.emit(
"create",
entity_type="machine",
entity_name=known["name"],
entity_uid=known["id"],
detail={
"fingerprint": _fingerprint(pubkey),
**({"provenance": grant_provenance["kind"]} if grant_provenance.get("kind") else {}),
},
org_id=grant_org,
)
elif seal_pubkey and not known.get("seal_pubkey"):
# Backfill: a box enrolled before the sealing key pins it on its
# next reconnect. Sound over untrusted transports because the
# attestation above ties it to the challenged identity key.
registry.set_seal_pubkey(known["id"], seal_pubkey)
machine_id = known["id"]
registry.touch(machine_id, app_version)
rpc = ch.RpcClient(ws.send_text)
acceptor.attach(machine_id, known["name"], pubkey, rpc)
attached = True
# Heartbeat for TTL-leased backends: the lease outlives the node
# only by its TTL, never forever.
refresh = getattr(acceptor.ephemera, "refresh_lease", None)
if refresh is not None:
async def _heartbeat() -> None:
while True:
await asyncio.sleep(LEASE_REFRESH_SECONDS)
refresh(pubkey)
heartbeat_task = asyncio.create_task(_heartbeat())
welcome: dict[str, Any] = {
"type": "welcome",
"machine_id": machine_id,
"name": known["name"],
}
# Org policy rides the welcome (spec §Audit export): hosted controllers
# supply `policy_for(machine_id, known)`; the desktop supplies nothing
# and the box keeps whatever record it already holds.
if policy_for is not None:
try:
policy = policy_for(machine_id, known)
if asyncio.iscoroutine(policy):
policy = await policy
except Exception:
policy = None
if isinstance(policy, dict):
welcome["policy"] = policy
if policy.get("org_id"):
welcome["org_id"] = str(policy["org_id"])
await ws.send_text(json.dumps(welcome))
live = acceptor.live(machine_id)
while True:
frame = json.loads(await ws.receive_text())
kind = frame.get("type")
if kind == "rpc_result":
rpc.resolve(frame)
elif kind == "policy_check":
# The box reports the version it holds (spec §Versioned org
# policy). Record it — status is what the machine SAYS — then
# answer with the newer document or "current".
reported = _int(frame.get("version"))
_record(policy_status, machine_id, known, reported, "checked")
doc = None
if policy_for is not None:
try:
doc = policy_for(machine_id, known)
if asyncio.iscoroutine(doc):
doc = await doc
except Exception:
doc = None
current = _int((doc or {}).get("version")) if isinstance(doc, dict) else 0
if isinstance(doc, dict) and (current > reported or (current == 0 and reported == 0)):
async def _send_newer(doc=doc, current=current):
try:
status, body, _ = await rpc.request_frame(
{"type": "policy", "policy": doc}
)
parsed = _safe_json(body)
ok = status == 200 and bool(parsed.get("ok"))
_record(
policy_status,
machine_id,
known,
_int(parsed.get("version")) if ok else reported,
"applied" if ok and parsed.get("applied") else ("ignored" if ok else "failed"),
)
except (asyncio.TimeoutError, ConnectionError):
_record(policy_status, machine_id, known, reported, "unreachable")
asyncio.create_task(_send_newer())
else:
await ws.send_text(
json.dumps({"type": "policy_current", "version": reported})
)
elif kind == "audit":
# Box-originated audit batch (cloud sink). Accepted only where a
# sink exists; a controller without one says so and the box backs
# off instead of dropping rows.
events = frame.get("events")
accepted = False
if audit_sink is not None and isinstance(events, list):
try:
res = audit_sink(machine_id, known, events)
if asyncio.iscoroutine(res):
res = await res
accepted = bool(res)
except Exception:
accepted = False
await ws.send_text(
json.dumps(
{
"type": "audit_ack",
"id": str(frame.get("id")),
"accepted": accepted,
"count": len(events) if isinstance(events, list) else 0,
}
)
)
elif kind == "ws_msg" and live is not None:
gui_ws = live.streams.get(str(frame.get("stream")))
if gui_ws is not None:
try:
await gui_ws.send_text(str(frame.get("text", "")))
except Exception:
pass # GUI went away; its handler sends ws_close
elif kind == "ws_close" and live is not None:
gui_ws = live.streams.pop(str(frame.get("stream")), None)
if gui_ws is not None:
try:
await gui_ws.close()
except Exception:
pass
except (WebSocketDisconnect, json.JSONDecodeError, KeyError, ValueError):
pass
finally:
if heartbeat_task is not None:
heartbeat_task.cancel()
if attached:
await acceptor.detach(machine_id, pubkey) # releases the lease
elif leased:
# Rejected between lease and attach (e.g. bad seal attestation):
# free the identity or the real box could never reconnect.
acceptor.ephemera.release_lease(pubkey)
@app.websocket("/ws/machines/{machine_id}/p/{path:path}")
async def ws_bridge(ws: WebSocket, machine_id: str, path: str) -> None:
"""GUI side of a bridged session socket: `/ws/machines/{mid}/p/ws/session/{sid}`
behaves exactly like the box's own `/ws/session/{sid}` — the remote home is
literally a different base URL. Sidecar-token + Origin gated like /ws/session."""
if ws_authenticated is not None and not ws_authenticated(ws):
await ws.close(code=1008)
return
if origin_allowed is not None and not origin_allowed(ws.headers.get("origin")):
await ws.close(code=1008)
return
tenant = await _tenant(ws)
if tenant is None:
await ws.close(code=1008)
return
if _org_machine(machine_id, tenant) is None:
await ws.close(code=1008) # not this tenant's machine (or unknown)
return
_touch(machine_id)
live = await _live_or_wake(machine_id)
if live is None:
await ws.close(code=1013) # machine offline: try again later
return
# Select "openworker" whenever the client OFFERED subprotocols: a
# browser treats an unanswered offer as a failed handshake and closes
# 1006 the moment the socket opens (python clients are lenient, which
# hid this until the first real browser hit the hosted tier — the
# api_token gate here only ever covered the desktop deployment).
offered = {
part.strip()
for part in ws.headers.get("sec-websocket-protocol", "").split(",")
if part.strip()
}
await ws.accept(subprotocol="openworker" if "openworker" in offered else None)
live.stream_counter += 1
stream_id = f"s{live.stream_counter}"
live.streams[stream_id] = ws
target = "/" + path
query = ws.scope.get("query_string", b"").decode()
if query:
target += "?" + query
try:
await live.rpc.send_frame(
{
"type": "ws_open",
"stream": stream_id,
"path": target,
"actor": str(tenant.get("actor") or ""),
}
)
while True:
text = await ws.receive_text()
await live.rpc.send_frame(
{"type": "ws_msg", "stream": stream_id, "text": text}
)
except (WebSocketDisconnect, ConnectionError):
pass
finally:
if live.streams.pop(stream_id, None) is not None:
try:
await live.rpc.send_frame({"type": "ws_close", "stream": stream_id})
except Exception:
pass
return acceptor
async def _reject(ws: WebSocket, reason: str, detail: Optional[str] = None) -> None:
try:
await ws.send_text(json.dumps(ch.reject_frame(reason, detail)))
await ws.close(code=1008)
except Exception:
pass
def _hash_profile(data: Any) -> str:
import hashlib
return hashlib.sha256(
json.dumps(data, sort_keys=True, separators=(",", ":")).encode()
).hexdigest()
def _wallet_hash(wallet, profile: str) -> Optional[str]:
if wallet is None:
return None
try:
data = wallet.get(profile)
except Exception:
return None
return None if data is None else _hash_profile(data)
def _int(value: Any) -> int:
try:
return max(0, int(value or 0))
except (TypeError, ValueError):
return 0
def _record(policy_status, machine_id: str, known: dict[str, Any], version: int, outcome: str) -> None:
"""Best-effort status hook: (machine_id, known, version, outcome) where
outcome ∈ checked | applied | ignored | failed | unreachable."""
if policy_status is None:
return
try:
policy_status(machine_id, known, version, outcome)
except Exception:
pass
def _safe_json(body: bytes) -> dict[str, Any]:
try:
value = json.loads(body.decode("utf-8"))
return value if isinstance(value, dict) else {}
except Exception:
return {}