@volter/teams 0.1.0 → 0.1.1

package/client.mjs

@@ -53,53 +53,7 @@ export async function openRemoteMachine({ origin, teamId, machineId, token }, {
 }
 
 /** Request/reply over a stream that carries JSON lines with `id`. */
-export class StreamRpc {
-  constructor(stream) {
-    this.stream = stream;
-    this.next = 1;
-    this.pending = new Map();
-    this.buffer = '';
-    stream.on('data', (chunk) => {
-      this.buffer += chunk;
-      let index;
-      while ((index = this.buffer.indexOf('\n')) >= 0) {
-        const line = this.buffer.slice(0, index);
-        this.buffer = this.buffer.slice(index + 1);
-        if (!line) continue;
-        const message = JSON.parse(line);
-        const waiter = this.pending.get(message.id);
-        if (!waiter) continue;
-        this.pending.delete(message.id);
-        if (message.error) waiter.reject(Object.assign(new Error(message.error.message ?? String(message.error)), { code: message.error.code }));
-        else waiter.resolve(message.result);
-      }
-    });
-    stream.on('close', (reason) => {
-      for (const waiter of this.pending.values()) waiter.reject(new Error(`stream closed: ${reason ?? 'peer'}`));
-      this.pending.clear();
-    });
-  }
-  /**
-   * One request. Bounded: a door that never answers becomes an error naming the
-   * method (default 60 s; the node's own per-door bound is 30 s), never a hang.
-   */
-  call(method, params = {}, { timeoutMs = 60_000 } = {}) {
-    const id = this.next++;
-    this.stream.write(JSON.stringify({ id, method, params }) + '\n');
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        if (!this.pending.has(id)) return;
-        this.pending.delete(id);
-        reject(Object.assign(new Error(`${method} did not answer within ${timeoutMs} ms`), { code: 504 }));
-      }, timeoutMs);
-      timer.unref?.();
-      this.pending.set(id, {
-        resolve: (value) => { clearTimeout(timer); resolve(value); },
-        reject: (error) => { clearTimeout(timer); reject(error); },
-      });
-    });
-  }
-}
+export { StreamRpc } from './stream-rpc.mjs';
 
 /**
  * A harness's own execution server on the channel's machine, as the local address its client takes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Volter Teams, the neutral team plane: machine identity and daemon core, the local door and server link, admission from machine grants, product doors, and the Teams server's neutral routes (company RFC 0008).",
   "license": "MIT",
@@ -22,11 +22,15 @@
     "./server/events": "./server/events.mjs",
     "./server/wire": "./server/wire.mjs",
     "./server/migrations": "./server/migrations/index.mjs",
-    "./client": "./client.mjs"
+    "./client": "./client.mjs",
+    "./stream-rpc": "./stream-rpc.mjs",
+    "./server/delegated": "./server/delegated.mjs",
+    "./server/viewer": "./server/viewer.mjs"
   },
   "files": [
     "*.mjs",
     "server",
+    "viewer",
     "README.md"
   ],
   "engines": {

package/server/core.mjs

@@ -13,15 +13,18 @@ const productionIds={next(kind){return `${prefix[kind]??kind}_${randomBytes(16).
 const productionClock={nowMs:()=>Date.now()};
 export { productionIds, productionClock };
 
-export function createTeamsApi({clock=productionClock,ids=productionIds,publicOrigin=null,identityIssuer=null,uploadLimitBytes=256*1024*1024}={}) {
+export function createTeamsApi({clock=productionClock,ids=productionIds,publicOrigin=null,identityIssuer=null,delegatedIssuer=null,uploadLimitBytes=256*1024*1024}={}) {
   // An identity service people may sign in with (protocol P02 federation); its tokens name this server's public origin.
   identityIssuer=normalizePublicOrigin(identityIssuer);
   if(identityIssuer&&!publicOrigin)throw new TypeError('an identity issuer needs the public origin its tokens name');
+  // A workplace whose delegated tokens admit a caller to one pane or folder (server/delegated.mjs); they name this origin too.
+  delegatedIssuer=normalizePublicOrigin(delegatedIssuer);
+  if(delegatedIssuer&&!publicOrigin)throw new TypeError('a delegated issuer needs the public origin its tokens name');
   if(typeof clock?.nowMs!=='function'||typeof ids?.next!=='function')throw new TypeError('clock.nowMs and ids.next are required');
   if(!Number.isSafeInteger(uploadLimitBytes)||uploadLimitBytes<1||uploadLimitBytes>256*1024*1024)throw new TypeError('uploadLimitBytes must be between 1 and 268435456');
   let store=null,serverId=null,localOrigin=null,harnessRoutes=null;
   const events=new TeamEvents();
-  return {clock,ids,events,publicOrigin,identityIssuer,uploadLimitBytes,rateState:new Map(),openStreams:new Map(),securityEvents:[],
+  return {clock,ids,events,publicOrigin,identityIssuer,delegatedIssuer,uploadLimitBytes,rateState:new Map(),openStreams:new Map(),securityEvents:[],
     get store(){return store;},get serverId(){return serverId;},get localOrigin(){return localOrigin;},get harnessRoutes(){return harnessRoutes;},
     attach(next){store=next.store??store;if(next.serverId!==undefined)serverId=next.serverId;if(next.localOrigin!==undefined)localOrigin=next.localOrigin;if(next.harnessRoutes!==undefined)harnessRoutes=next.harnessRoutes;},
   };

package/server/delegated.mjs

@@ -0,0 +1,80 @@
+// Delegated access (RH2 RFC 0013, panes and folders): a workplace that decides who may see or drive a pane or a
+// folder signs a short-lived token saying so, and this server admits exactly that, as it admits a machine grant.
+// The workplace is an issuer this server is configured to trust (`delegatedIssuer`, its origin); its keys are at
+// `<issuer>/.well-known/jwks.json` (Ed25519, EdDSA). A token names the principal, the Surface (its kind, and in its
+// config this server's team, the machine and the target) and `view` or `control`; its audience is this server's
+// public origin. Verified with WebCrypto, so the same code runs in Node and in a Worker.
+//
+// What a Surface grants on the machine, in the daemon's own caps (sdk/volter-teams/admission.mjs):
+//   pane   view: observe the pane            control: observe it and type into it
+//   folder view: list and read under the root control: every file door under the root
+const CAPS = {
+  folder: { control: ['files'], view: ['observe'] },
+  pane: { control: ['observe', 'control'], view: ['observe'] },
+};
+const KEYS_TTL_MS = 5 * 60 * 1000;
+const SKEW_S = 30;
+
+const decoder = new TextDecoder();
+const fromBase64Url = (text) => Uint8Array.from(atob(text.replaceAll('-', '+').replaceAll('_', '/') + '='.repeat((4 - text.length % 4) % 4)), (c) => c.charCodeAt(0));
+const json = (part) => JSON.parse(decoder.decode(fromBase64Url(part)));
+
+/** A token shaped like a JWT (three base64url parts) — a Teams credential never is. */
+export function looksDelegated(token) {
+  return typeof token === 'string' && /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token);
+}
+
+async function issuerKey(api, kid) {
+  const cache = api.delegatedKeys ??= { at: -Infinity, keys: new Map() };
+  const age = api.clock.nowMs() - cache.at;
+  // The set is re-read when it is old, or when it lacks the kid and was last read over a minute ago (a key rotated
+  // in); so a forged kid drives at most one fetch a minute.
+  if (age >= KEYS_TTL_MS || (!cache.keys.has(kid) && age > 60 * 1000)) {
+    const response = await fetch(`${api.delegatedIssuer}/.well-known/jwks.json`, { headers: { accept: 'application/json' } });
+    if (!response.ok) throw new Error(`the issuer's keys did not load (${response.status})`);
+    const { keys } = await response.json();
+    const loaded = new Map();
+    for (const jwk of Array.isArray(keys) ? keys : []) {
+      if (jwk?.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.kid !== 'string' || typeof jwk.x !== 'string') continue;
+      loaded.set(jwk.kid, await crypto.subtle.importKey('jwk', { crv: 'Ed25519', kty: 'OKP', x: jwk.x }, { name: 'Ed25519' }, false, ['verify']));
+    }
+    cache.keys = loaded;
+    cache.at = api.clock.nowMs();
+  }
+  return cache.keys.get(kid) ?? null;
+}
+
+/**
+ * What a delegated token admits, or null when it is not one this server trusts: { subject, issuer, teamId, machineId,
+ * target, caps, expiresAt, scope, kind }. Anything unverifiable, expired, for another audience or naming no machine
+ * target is null, and the caller refuses it exactly as an unknown credential.
+ */
+export async function delegatedAccessOf(api, token) {
+  if (!api.delegatedIssuer || !api.publicOrigin || !looksDelegated(token)) return null;
+  try {
+    const [head, body, signature] = token.split('.');
+    const header = json(head);
+    if (header.alg !== 'EdDSA' || typeof header.kid !== 'string') return null;
+    const key = await issuerKey(api, header.kid);
+    if (!key) return null;
+    const signed = new TextEncoder().encode(`${head}.${body}`);
+    if (!await crypto.subtle.verify({ name: 'Ed25519' }, key, fromBase64Url(signature), signed)) return null;
+    const claims = json(body);
+    const now = Math.floor(api.clock.nowMs() / 1000);
+    if (claims.iss !== api.delegatedIssuer || claims.aud !== api.publicOrigin) return null;
+    if (typeof claims.exp !== 'number' || claims.exp <= now - SKEW_S || (typeof claims.nbf === 'number' && claims.nbf > now + SKEW_S)) return null;
+    if (typeof claims.sub !== 'string' || !claims.sub) return null;
+    const surface = claims.surface;
+    const caps = CAPS[surface?.kind]?.[claims.scope];
+    const config = surface?.config ?? {};
+    if (!caps || typeof config.team !== 'string' || typeof config.machine !== 'string' || typeof config.target !== 'string') return null;
+    const target = surface.kind === 'pane' ? (config.target.startsWith('pane:') ? config.target : null) : (config.target.startsWith('root:/') ? config.target : null);
+    if (!target) return null;
+    return { caps, expiresAt: claims.exp * 1000, issuer: claims.iss, kind: surface.kind, machineId: config.machine, scope: claims.scope, subject: claims.sub, target, teamId: config.team };
+  } catch {
+    return null;
+  }
+}
+
+/** The delegated caller's principal on this server: the issuer's subject, never a member of any team. */
+export const delegatedPrincipal = (access) => `delegated:${new URL(access.issuer).host}:${access.subject}`;

package/server/http.mjs

@@ -4,6 +4,7 @@ import { ContractError, canonicalJson, validationFailure, cursorHash, cursorToke
 import { machineGrantRoute, machineGrantRows, closeMachineChannels, closeChannelsFor } from './machine-link.mjs';
 import { exact, parseJson as parseRequestJson } from './request-json.mjs';
 import { identityOf } from './identity.mjs';
+import { serveViewer } from './viewer.mjs';
 
 class HttpError extends Error { constructor(status,code,message,details=null){super(message);this.status=status;this.code=code;this.details=details;} }
 const fail=(status,code,message,details)=>{throw new HttpError(status,code,message,details)};
@@ -24,6 +25,8 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   if(req.method==='OPTIONS'){res.writeHead(204,{'Access-Control-Allow-Methods':'GET, POST, PATCH, DELETE','Access-Control-Allow-Headers':'Authorization, Content-Type, Idempotency-Key, If-Match, Last-Event-ID, Range','Access-Control-Max-Age':'86400'});res.end();return;}
   if(api.publicOrigin){const expected=new URL(api.publicOrigin);if(req.headers.host!==expected.host)fail(400,'invalid_request','request Host does not match configured public origin');}
   const url=new URL(req.url,'http://local'); const path=url.pathname;
+  // The hosted viewer's files (viewer.mjs): public; the page's delegated token is checked at every door it opens.
+  if(req.method==='GET'&&(path==='/view'||path.startsWith('/view/'))&&await serveViewer(res,path))return;
   if(api.harnessRoutes&&await api.harnessRoutes.preAuth({api,req,res,path,requestId}))return;
   const auth=await authenticate(api,bearer(req.headers.authorization));res._authenticated=Boolean(auth);
   if(api.harnessRoutes&&await api.harnessRoutes.authed({api,req,res,auth,path,requestId}))return;

package/server/machine-link.mjs

@@ -10,8 +10,12 @@
 // that moment; the machine re-derives the admission from its own synced copy
 // of the grants and checks each door against it. A caller with no grant on a
 // machine is refused exactly as a machine that does not exist is.
+//
+// A delegated caller (./delegated.mjs) holds no Teams credential: its verified token becomes one machine grant on
+// exactly the target and caps it names, expiring with the token, and its channel closes then.
 import { Channel } from '../channel.mjs';
 import { bearer } from './auth.mjs';
+import { delegatedAccessOf, delegatedPrincipal, looksDelegated } from './delegated.mjs';
 
 const LINK_PROTOCOL = 'supercode-machine-link.v1';
 const CHANNEL_PROTOCOL = 'supercode-machine-channel.v1';
@@ -37,6 +41,10 @@ export async function machineGrantRows(api, teamId, machineId) {
 
 /** What the caller may claim on the machine right now, or null (indistinguishable from no machine). */
 async function claimFor(api, auth, machineId) {
+  if (auth.kind === 'delegated') {
+    const row = await api.store.one('SELECT id, revision FROM machine_grants WHERE team_id=? AND machine_id=? AND id=? AND expires_at>?', [auth.team_id, machineId, auth.grant_id, api.clock.nowMs()]);
+    return row ? { principal: auth.principal_id, groups: [], grants: [row.id], revisions: { [row.id]: row.revision } } : null;
+  }
   const machine = await api.store.one('SELECT custodian_id FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', [auth.team_id, machineId]);
   if (!machine) return null;
   const membership = await api.store.one('SELECT active FROM memberships WHERE team_id=? AND principal_id=?', [auth.team_id, auth.principal_id]);
@@ -133,7 +141,9 @@ export async function authorizeMachineUpgrade(api, { authenticate, url, headers
   const match = /^\/api\/v1\/teams\/([^/]+)\/machines\/([^/]+)\/(link|channel)$/.exec(new URL(url, 'http://local').pathname);
   if (!match) return { status: 404, code: 'not_found', message: 'not found' };
   const [, teamId, machineId, door] = match;
-  const auth = await authenticate(api, bearerFrom(headers));
+  const presented = bearerFrom(headers);
+  if (door === 'channel' && api.delegatedIssuer && looksDelegated(presented)) return await delegatedChannel(api, teamId, machineId, presented);
+  const auth = await authenticate(api, presented);
   if (!auth) return { status: 401, code: 'authentication_required', message: 'authentication required' };
   if (door === 'link') {
     if (auth.kind !== 'machine' || auth.team_id !== teamId || auth.machine_id !== machineId) return { status: 403, code: 'forbidden', message: 'exact machine credential required' };
@@ -151,6 +161,22 @@ export async function authorizeMachineUpgrade(api, { authenticate, url, headers
   return { door, teamId, machineId, auth };
 }
 
+/** A delegated token's channel: its grant, minted now on exactly what the token names, or the same refusal as no machine. */
+async function delegatedChannel(api, teamId, machineId, token) {
+  const access = await delegatedAccessOf(api, token);
+  if (!access) return { status: 401, code: 'authentication_required', message: 'authentication required' };
+  if (access.teamId !== teamId || access.machineId !== machineId) return { status: 404, code: 'not_found', message: 'machine not found' };
+  const machine = await api.store.one('SELECT 1 ok FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', [teamId, machineId]);
+  if (!machine) return { status: 404, code: 'not_found', message: 'machine not found' };
+  const now = api.clock.nowMs(), id = api.ids.next('grant'), principal = delegatedPrincipal(access);
+  await api.store.transaction([
+    // Delegated grants live as long as their tokens; the expired ones go as new ones come.
+    { sql: "DELETE FROM machine_grants WHERE team_id=? AND issuer_id LIKE 'delegated:%' AND expires_at<=?", params: [teamId, now] },
+    { sql: 'INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at) VALUES (?,?,?,?,?,?,?,?,?)', params: [teamId, id, machineId, principal, JSON.stringify(access.caps), JSON.stringify([access.target]), `delegated:${new URL(access.issuer).host}`, now, access.expiresAt] },
+  ]);
+  return { door: 'channel', teamId, machineId, auth: { kind: 'delegated', team_id: teamId, principal_id: principal, group_ids: [], grant_id: id, expires_at: access.expiresAt } };
+}
+
 /**
  * A caller's bearer: the Authorization header, or, for a browser (which cannot set headers on
  * a WebSocket), a `bearer.<token>` entry in Sec-WebSocket-Protocol beside the door's protocol.
@@ -203,8 +229,10 @@ async function acceptChannel(api, auth, machineId, duplex, closeSocket) {
     dropStreams: (reason) => { for (const pair of open) pair.close(reason); },
   };
   channels(api).add(entry);
+  // A delegated channel ends when its token does; the viewer reopens it with a fresh one.
+  const expiry = auth.kind === 'delegated' ? setTimeout(() => entry.close('token_expired'), Math.max(0, auth.expires_at - api.clock.nowMs())) : null;
   channel.on('error', () => {});
-  channel.on('close', () => { channels(api).delete(entry); entry.dropStreams('caller closed'); });
+  channel.on('close', () => { if (expiry) clearTimeout(expiry); channels(api).delete(entry); entry.dropStreams('caller closed'); });
   channel.on('stream', async (stream, accept, refuse) => {
     const claim = await claimFor(api, auth, machineId).catch(() => null);
     if (!claim) return refuse('no machine grant for this caller');

package/server/viewer.mjs

@@ -0,0 +1,37 @@
+// The hosted viewer's files (../viewer): the page, its script, and the two browser modules it imports, served at
+// /view without a credential — the page holds its delegated token in memory and every door it opens checks it. The
+// Node host reads them from this package; a Worker, which has no files, bundles them as text and sets them here
+// (worker/index.mjs), as it does the OTLP schemas.
+const FILES = {
+  '/view': ['viewer/index.html', 'text/html; charset=utf-8'],
+  '/view/': ['viewer/index.html', 'text/html; charset=utf-8'],
+  '/view/viewer.mjs': ['viewer/viewer.mjs', 'text/javascript; charset=utf-8'],
+  '/view/channel.mjs': ['browser-channel.mjs', 'text/javascript; charset=utf-8'],
+  '/view/stream-rpc.mjs': ['stream-rpc.mjs', 'text/javascript; charset=utf-8'],
+};
+let bundled = null;
+
+/** The Worker's copy of the files, keyed by their path in this package. */
+export function setViewerSources(sources) { bundled = sources; }
+
+async function source(file) {
+  if (bundled) return bundled[file] ?? null;
+  const { readFile } = await import('node:fs/promises');
+  return readFile(new URL(`../${file}`, import.meta.url), 'utf8');
+}
+
+/** Answer a viewer path, or return false for any other. */
+export async function serveViewer(res, path) {
+  const entry = FILES[path];
+  if (!entry) return false;
+  const body = await source(entry[0]);
+  if (body === null) return false;
+  res.writeHead(200, {
+    'Content-Type': entry[1],
+    'Cache-Control': 'no-cache',
+    'Referrer-Policy': 'no-referrer',
+    'X-Content-Type-Options': 'nosniff',
+  });
+  res.end(body);
+  return true;
+}

package/stream-rpc.mjs

@@ -0,0 +1,50 @@
+// Request and reply over one stream: a line of JSON { id, method, params } out, a line { id, result | error } back.
+// No Node built-ins, so a browser page (the hosted viewer) uses it on a browser channel's stream as the CLI does on
+// a Node one.
+export class StreamRpc {
+  constructor(stream) {
+    this.stream = stream;
+    this.next = 1;
+    this.pending = new Map();
+    this.buffer = '';
+    stream.on('data', (chunk) => {
+      this.buffer += chunk;
+      let index;
+      while ((index = this.buffer.indexOf('\n')) >= 0) {
+        const line = this.buffer.slice(0, index);
+        this.buffer = this.buffer.slice(index + 1);
+        if (!line) continue;
+        const message = JSON.parse(line);
+        const waiter = this.pending.get(message.id);
+        if (!waiter) continue;
+        this.pending.delete(message.id);
+        if (message.error) waiter.reject(Object.assign(new Error(message.error.message ?? String(message.error)), { code: message.error.code }));
+        else waiter.resolve(message.result);
+      }
+    });
+    stream.on('close', (reason) => {
+      for (const waiter of this.pending.values()) waiter.reject(new Error(`stream closed: ${reason ?? 'peer'}`));
+      this.pending.clear();
+    });
+  }
+  /**
+   * One request. Bounded: a door that never answers becomes an error naming the
+   * method (default 60 s; the node's own per-door bound is 30 s), never a hang.
+   */
+  call(method, params = {}, { timeoutMs = 60_000 } = {}) {
+    const id = this.next++;
+    this.stream.write(JSON.stringify({ id, method, params }) + '\n');
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (!this.pending.has(id)) return;
+        this.pending.delete(id);
+        reject(Object.assign(new Error(`${method} did not answer within ${timeoutMs} ms`), { code: 504 }));
+      }, timeoutMs);
+      timer.unref?.();
+      this.pending.set(id, {
+        resolve: (value) => { clearTimeout(timer); resolve(value); },
+        reject: (error) => { clearTimeout(timer); reject(error); },
+      });
+    });
+  }
+}

package/viewer/index.html

@@ -0,0 +1,56 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>Viewer</title>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/css/xterm.css">
+<style>
+  :root { color-scheme: dark; --bg: #0b0d10; --panel: #13161b; --line: #262b33; --text: #e6e8eb; --muted: #8b939e; --accent: #7aa2f7; }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; background: var(--bg); color: var(--text); font: 13px/1.4 ui-sans-serif, system-ui, -apple-system, sans-serif; }
+  body { display: flex; flex-direction: column; }
+  header { display: flex; align-items: center; gap: 8px; padding: 6px 10px; border-bottom: 1px solid var(--line); background: var(--panel); min-height: 32px; }
+  header .target { font-family: ui-monospace, Menlo, monospace; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  header .scope { margin-left: auto; font-size: 11px; padding: 1px 6px; border: 1px solid var(--line); border-radius: 4px; color: var(--muted); }
+  #status { padding: 4px 10px; color: var(--muted); font-size: 12px; border-bottom: 1px solid var(--line); }
+  #status:empty { display: none; }
+  main { flex: 1; min-height: 0; display: flex; }
+  #terminal { flex: 1; min-width: 0; padding: 4px; }
+  #folder { flex: 1; min-width: 0; display: none; }
+  #folder.open { display: flex; }
+  #entries { width: 280px; flex: none; border-right: 1px solid var(--line); overflow: auto; }
+  #entries .crumbs { padding: 6px 10px; border-bottom: 1px solid var(--line); font-family: ui-monospace, Menlo, monospace; color: var(--muted); word-break: break-all; }
+  #entries button.entry { display: block; width: 100%; text-align: left; padding: 4px 10px; border: 0; background: none; color: var(--text); font: inherit; cursor: pointer; }
+  #entries button.entry:hover, #entries button.entry.selected { background: #1b2028; }
+  #entries button.entry.directory { color: var(--accent); }
+  #file { flex: 1; min-width: 0; display: flex; flex-direction: column; }
+  #file .bar { display: flex; gap: 8px; align-items: center; padding: 6px 10px; border-bottom: 1px solid var(--line); min-height: 36px; }
+  #file .bar .name { font-family: ui-monospace, Menlo, monospace; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  #file .bar .actions { margin-left: auto; display: flex; gap: 6px; }
+  #file textarea { flex: 1; resize: none; border: 0; outline: none; padding: 10px; background: var(--bg); color: var(--text); font: 12px/1.5 ui-monospace, Menlo, monospace; }
+  button.action, label.action { font: inherit; font-size: 12px; padding: 3px 10px; border-radius: 4px; border: 1px solid var(--line); background: var(--panel); color: var(--text); cursor: pointer; }
+  button.action:disabled { opacity: .5; cursor: default; }
+  label.action input { display: none; }
+  [hidden] { display: none !important; }
+</style>
+</head>
+<body>
+<header><span class="target" id="target"></span><span class="scope" id="scope"></span></header>
+<div id="status"></div>
+<main>
+  <div id="terminal" hidden></div>
+  <div id="folder">
+    <nav id="entries"><div class="crumbs" id="crumbs"></div><div id="list"></div></nav>
+    <section id="file">
+      <div class="bar"><span class="name" id="file-name"></span>
+        <span class="actions"><label class="action" id="upload" hidden>Upload<input type="file" id="upload-input" multiple></label><button class="action" id="save" hidden disabled>Save</button></span>
+      </div>
+      <textarea id="content" spellcheck="false" readonly></textarea>
+    </section>
+  </div>
+</main>
+<script type="module" src="/view/viewer.mjs"></script>
+</body>
+</html>

package/viewer/viewer.mjs

@@ -0,0 +1,171 @@
+// THE HOSTED VIEWER: one pane or one folder of an enrolled machine, opened with a delegated token a workplace signed
+// (server/delegated.mjs). The token arrives in the URL fragment (never sent to a server as a query) or by
+// postMessage from the page embedding this one, which sends a fresh one before the last expires; it is held in memory
+// only. The server verifies it and admits exactly its target and scope; what this page reads from it is only for
+// showing where it is.
+import { attachBrowserPane, openBrowserMachine } from './channel.mjs';
+import { StreamRpc } from './stream-rpc.mjs';
+
+const $ = (id) => document.getElementById(id);
+const decoder = new TextDecoder();
+const status = (text) => { $('status').textContent = text; };
+
+let token = new URLSearchParams(location.hash.slice(1)).get('token');
+history.replaceState(null, '', location.pathname);
+let waiting = null;
+
+const embedded = window.parent !== window;
+const ask = (type) => { if (embedded) window.parent.postMessage({ type }, '*'); };
+window.addEventListener('message', (event) => {
+  if (event.data?.type !== 'delegated-token' || typeof event.data.token !== 'string') return;
+  token = event.data.token;
+  if (waiting) { const resume = waiting; waiting = null; resume(); }
+});
+
+function claimsOf(value) {
+  const part = value.split('.')[1] ?? '';
+  return JSON.parse(decoder.decode(Uint8Array.from(atob(part.replaceAll('-', '+').replaceAll('_', '/') + '='.repeat((4 - part.length % 4) % 4)), (c) => c.charCodeAt(0))));
+}
+
+/** The next token: the one held if it has a minute left, otherwise one the embedding page sends when asked. */
+async function freshToken() {
+  const left = token ? claimsOf(token).exp * 1000 - Date.now() : 0;
+  if (left > 60_000) return token;
+  if (!embedded) throw new Error('this link has expired; open it again from the workplace');
+  status('Waiting for access…');
+  await new Promise((resolve) => { waiting = resolve; ask('delegated-token-needed'); });
+  return token;
+}
+
+async function main() {
+  if (!token) { status('No access token. Open this from the workplace.'); return; }
+  const claims = claimsOf(token);
+  const surface = claims.surface ?? {};
+  const config = surface.config ?? {};
+  const control = claims.scope === 'control';
+  $('target').textContent = `${surface.key ?? ''} · ${config.target ?? ''}`;
+  $('scope').textContent = control ? 'control' : 'view only';
+  document.title = `${surface.key ?? 'Viewer'} · ${surface.kind ?? ''}`;
+  const connect = async () => openBrowserMachine({ origin: location.origin, teamId: config.team, machineId: config.machine, token: await freshToken() });
+  if (surface.kind === 'pane') await showPane(connect, String(config.target).slice('pane:'.length), control);
+  else if (surface.kind === 'folder') await showFolder(connect, String(config.target).slice('root:'.length), control);
+  else status(`This viewer does not show ${surface.kind ?? 'that'}.`);
+  ask('viewer-ready');
+}
+
+async function showPane(connect, key, control) {
+  const [{ Terminal }, { FitAddon }] = await Promise.all([
+    import('https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/+esm'),
+    import('https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/+esm'),
+  ]);
+  const element = $('terminal');
+  element.hidden = false;
+  const terminal = new Terminal({ cursorBlink: control, disableStdin: !control, fontFamily: 'ui-monospace, Menlo, monospace', fontSize: 13, scrollback: 5000, theme: { background: '#0b0d10' } });
+  const fit = new FitAddon();
+  terminal.loadAddon(fit);
+  terminal.open(element);
+  fit.fit();
+  let pane = null;
+  // Only a controller sizes the pane; an observer sees it at the size its controller keeps.
+  new ResizeObserver(() => { fit.fit(); if (control) pane?.resize(terminal.cols, terminal.rows); }).observe(element);
+  if (control) terminal.onData((data) => pane?.write(data));
+  const attach = async () => {
+    status('Connecting…');
+    const channel = await connect();
+    pane = await attachBrowserPane(channel, { pane: key, mode: control ? 'control' : 'observe', cols: terminal.cols, rows: terminal.rows });
+    status('');
+    pane.on('data', (data) => terminal.write(data));
+    pane.on('notice', (message) => status(message));
+    pane.on('error-message', (message) => status(message));
+    pane.on('close', (reason) => {
+      pane = null;
+      channel.close();
+      // The server ends a channel when its token does: reopen with a fresh one. Any other close is shown and stays.
+      if (!/token_expired/.test(String(reason))) { status(`Disconnected: ${reason ?? 'closed'}`); return; }
+      status('Reconnecting…');
+      attach().catch((error) => status(error.message));
+    });
+  };
+  await attach();
+}
+
+async function showFolder(connect, root, control) {
+  $('folder').classList.add('open');
+  const base = root.replace(/\/+$/, '') || '/';
+  let rpc = null;
+  let path = base;
+  let open = null;
+  // One node stream, reopened (with a fresh token) when the server has closed it, as it does when a token expires.
+  const call = async (method, params) => {
+    for (let attempt = 0; ; attempt += 1) {
+      if (!rpc) {
+        const channel = await connect();
+        rpc = new StreamRpc(await channel.open('node'));
+      }
+      try {
+        return await rpc.call(method, params, { timeoutMs: 30_000 });
+      } catch (error) {
+        if (!rpc.stream.closed || attempt > 0) throw error;
+        rpc = null;
+      }
+    }
+  };
+  const join = (dir, name) => `${dir.replace(/\/+$/, '')}/${name}`;
+  const list = async (dir) => {
+    status('');
+    const entries = await call('files.list', { path: dir });
+    path = dir;
+    $('crumbs').textContent = dir;
+    const listing = $('list');
+    listing.replaceChildren();
+    if (dir !== base) listing.append(entryButton('..', 'directory', () => list(dir.replace(/\/[^/]+\/?$/, '') || base)));
+    entries.sort((a, b) => (a.kind === 'directory') === (b.kind === 'directory') ? a.name.localeCompare(b.name) : a.kind === 'directory' ? -1 : 1);
+    for (const entry of entries) {
+      const target = join(dir, entry.name);
+      listing.append(entryButton(entry.name, entry.kind, () => (entry.kind === 'directory' ? list(target) : read(target))));
+    }
+  };
+  const read = async (file) => {
+    const { bytes, read: size } = await call('files.read', { path: file, length: 1024 * 1024 });
+    const raw = Uint8Array.from(atob(bytes), (c) => c.charCodeAt(0));
+    const text = decoder.decode(raw);
+    const binary = /\u0000/.test(text);
+    open = file;
+    $('file-name').textContent = file;
+    $('content').value = binary ? `(${size} bytes, not text)` : text;
+    $('content').readOnly = !control || binary;
+    $('save').hidden = !control || binary;
+    $('save').disabled = true;
+    for (const button of document.querySelectorAll('#list button.entry')) button.classList.toggle('selected', button.dataset.path === file);
+  };
+  const entryButton = (name, kind, onClick) => {
+    const button = document.createElement('button');
+    button.className = `entry ${kind}`;
+    button.textContent = kind === 'directory' ? `${name}/` : name;
+    button.dataset.path = join(path, name);
+    button.addEventListener('click', () => onClick().catch((error) => status(error.message)));
+    return button;
+  };
+  const toBase64 = (bytes) => { let text = ''; for (const byte of bytes) text += String.fromCharCode(byte); return btoa(text); };
+  if (control) {
+    $('upload').hidden = false;
+    $('content').addEventListener('input', () => { $('save').disabled = false; });
+    $('save').addEventListener('click', async () => {
+      if (!open) return;
+      await call('files.write', { path: open, bytes: toBase64(new TextEncoder().encode($('content').value)), truncate: true }).catch((error) => status(error.message));
+      $('save').disabled = true;
+      status(`Saved ${open}`);
+    });
+    $('upload-input').addEventListener('change', async (event) => {
+      for (const file of event.target.files) {
+        await call('files.write', { path: join(path, file.name), bytes: toBase64(new Uint8Array(await file.arrayBuffer())), truncate: true }).catch((error) => status(error.message));
+      }
+      event.target.value = '';
+      await list(path);
+      status('Uploaded');
+    });
+  }
+  await list(base);
+}
+
+main().catch((error) => status(error.message));