@volter/teams 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# `@volter/teams`
+
+Volter Teams, the neutral team plane (company RFC 0008): what any product needs to be
+reached by a team, with no harness in it.
+
+- **The machine daemon's core** (`machine-core.mjs`): this OS user's machine identity and
+  hash-chained account log, the owner-only local door, one outbound link to a Teams
+  server with every stream admitted from the machine's own synced grants, and product
+  doors. A product builds on `MachineCore` and registers its own doors by stream name;
+  the harness does (`@volter-ai-dev/supercode-teams`, `machine.mjs`).
+- **Products behind the daemon** (`products.mjs`): a product serving its own kind of
+  target writes a receipt; the daemon admits the caller, both sides prove the receipt's
+  token without sending it, and messages are relayed.
+- **Admission** (`admission.mjs`): grants of capabilities on targets, `<kind>:*`
+  wildcards, `*` for operate and view only.
+- **The Teams server's neutral routes** (`server/`): identity and sign-in, teams,
+  members, groups, credentials, invitations, machines, enrollment and machine grants,
+  the machine link, and the migration chain. The harness's routes attach through
+  `api.harnessRoutes`.
+
+This package is private: nothing is published while nothing is open-sourced.

package/admission.mjs

@@ -0,0 +1,62 @@
+// What a caller may do on this machine. `admitted` is { class, grants } where
+// class is 'operator' (the OS user through the local door, or a holder of an
+// `operate` machine grant through the server) or 'participant', and grants are
+// { id, caps, targets } rows from the caller's machine grants (design §11).
+//
+// Targets: `<kind>:<name>` for the kinds a product serves on this machine
+// (the harness: `pane:<contextKey>`, `runtime:<id>`, `root:<path>`, `port:<pane>/<n>`),
+// `<kind>:*` for every target of one kind, or `*` (operate and view only).
+// `root:<path>` covers the path and everything under it.
+
+export function targetsCover(patterns, target) {
+  for (const pattern of patterns) {
+    if (pattern === '*') return true;
+    if (pattern === target) return true;
+    if (pattern.endsWith(':*') && pattern.length > 2 && target.startsWith(pattern.slice(0, -1))) return true;
+    if (pattern.startsWith('root:') && target.startsWith('root:')) {
+      const base = pattern.slice(5).replace(/\/+$/, '');
+      const path = target.slice(5);
+      if (path === base || path.startsWith(base + '/')) return true;
+    }
+  }
+  return false;
+}
+
+/** Does the admitted caller hold `cap` on `target`? Operators hold everything. */
+export function holds(admitted, cap, target) {
+  if (!admitted) return false;
+  if (admitted.class === 'operator') return true;
+  return admitted.grants.some((g) => g.caps.includes(cap) && targetsCover(g.targets, target));
+}
+
+/** Does the caller hold `observe` on any pane (a named pane, `pane:*`, or the whole machine)? */
+export function observesPanes(admitted) {
+  if (!admitted) return false;
+  if (admitted.class === 'operator') return true;
+  return admitted.grants.some((g) => g.caps.includes('observe') && g.targets.some((t) => t === '*' || t.startsWith('pane:')));
+}
+
+/** The OS user on its own machine, through the owner-only local door. */
+export const LOCAL_OPERATOR = Object.freeze({ class: 'operator', grants: Object.freeze([]) });
+
+/**
+ * The admission a server-forwarded stream carries, re-derived from this
+ * machine's own copy of its grants: the claim only names grant ids and the
+ * principal; the capabilities come from the synced rows. Expired, unknown or
+ * other-subject grants admit nothing.
+ */
+export function admitFromGrants(claim, { custodianId, grants, now = Date.now() }) {
+  if (!claim || typeof claim.principal !== 'string') return null;
+  if (claim.custodian === true) return claim.principal === custodianId ? LOCAL_OPERATOR : null;
+  const held = [];
+  for (const id of Array.isArray(claim.grants) ? claim.grants : []) {
+    const grant = grants.get(id);
+    if (!grant || grant.expires_at <= now) continue;
+    const subjects = new Set([claim.principal, ...(Array.isArray(claim.groups) ? claim.groups : [])]);
+    if (!subjects.has(grant.subject_id)) continue;
+    held.push({ id: grant.id, caps: grant.caps, targets: grant.targets });
+  }
+  if (!held.length) return null;
+  if (held.some((grant) => grant.caps.includes('operate'))) return { class: 'operator', grants: held };
+  return { class: 'participant', grants: held };
+}

package/browser-channel.mjs

@@ -0,0 +1,157 @@
+// The machine channel from a browser: the framing and streams of channel.mjs
+// (a hello each way, then u32-length JSON envelopes { ch, t, ... }) over a
+// browser WebSocket, with no Node built-ins. A browser cannot set headers on a
+// WebSocket, so the caller's bearer rides as a `bearer.<token>` subprotocol
+// beside the door's own; the server never echoes it back.
+const PROTOCOL = 'supercode-machine/1';
+const NODE_PROTOCOL = 2;
+const CHANNEL_PROTOCOL = 'supercode-machine-channel.v1';
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+class Emitter {
+  #listeners = new Map();
+  on(event, listener) { (this.#listeners.get(event) ?? this.#listeners.set(event, new Set()).get(event)).add(listener); return this; }
+  once(event, listener) { const wrapped = (...args) => { this.off(event, wrapped); listener(...args); }; return this.on(event, wrapped); }
+  off(event, listener) { this.#listeners.get(event)?.delete(listener); return this; }
+  listenerCount(event) { return this.#listeners.get(event)?.size ?? 0; }
+  emit(event, ...args) { for (const listener of [...(this.#listeners.get(event) ?? [])]) listener(...args); }
+}
+
+function frame(value) {
+  const body = encoder.encode(JSON.stringify(value));
+  const out = new Uint8Array(4 + body.length);
+  new DataView(out.buffer).setUint32(0, body.length);
+  out.set(body, 4);
+  return out;
+}
+
+class BrowserStream extends Emitter {
+  constructor(channel, id, name) { super(); this.channel = channel; this.id = id; this.name = name; this.closed = false; }
+  write(data) { if (this.closed) throw new Error(`stream ${this.name}#${this.id} is closed`); this.channel.send({ ch: this.id, t: 'data', d: data }); }
+  close(reason) { if (this.closed) return; this.closed = true; this.channel.send({ ch: this.id, t: 'close', reason: reason ?? null }); this.channel.streams.delete(this.id); this.emit('close', reason ?? null); }
+  // A peer that answers at once speaks before `open()`'s awaiter attaches: hold 'data' and
+  // 'close' until a listener for either is attached, then release them in order (channel.mjs).
+  on(event, listener) {
+    super.on(event, listener);
+    if (event === 'data') this.dataListening = true;
+    if (this.held && (event === 'data' || event === 'close')) {
+      const held = this.held; this.held = null;
+      queueMicrotask(() => { for (const [e, v] of held) this.emit(e, v); });
+    }
+    return this;
+  }
+  deliver(event, value) {
+    // As channel.mjs: a close someone listens for goes out after whatever is held; otherwise
+    // events wait until a 'data' or 'close' listener is attached.
+    if (event === 'close' && this.listenerCount('close') > 0) {
+      const held = this.held ?? []; this.held = null;
+      for (const [e, v] of held) this.emit(e, v);
+      this.emit('close', value);
+      return;
+    }
+    if (!this.held && this.dataListening) { this.emit(event, value); return; }
+    (this.held ??= []).push([event, value]);
+  }
+}
+
+export class BrowserChannel extends Emitter {
+  constructor(socket) {
+    super();
+    this.socket = socket;
+    this.streams = new Map();
+    this.next = 1;
+    this.closed = false;
+    this.buffer = new Uint8Array(0);
+    this.hello = null;
+    socket.binaryType = 'arraybuffer';
+    socket.addEventListener('message', (event) => this.#receive(new Uint8Array(event.data)));
+    socket.addEventListener('close', (event) => {
+      this.closed = true;
+      // The server names why it closed a channel (a revoked grant, the machine gone); pass it on.
+      const reason = event?.reason || 'connection closed';
+      for (const stream of this.streams.values()) { stream.closed = true; stream.deliver('close', reason); }
+      this.streams.clear();
+      this.emit('close');
+    });
+    this.ping = setInterval(() => { if (!this.closed && this.hello) this.send({ ch: 0, t: 'ping' }); }, 30_000);
+    this.once('close', () => clearInterval(this.ping));
+  }
+
+  send(envelope) { if (!this.closed && this.socket.readyState === 1) this.socket.send(frame(envelope)); }
+
+  #receive(bytes) {
+    const joined = new Uint8Array(this.buffer.length + bytes.length);
+    joined.set(this.buffer); joined.set(bytes, this.buffer.length);
+    this.buffer = joined;
+    while (this.buffer.length >= 4) {
+      const length = new DataView(this.buffer.buffer, this.buffer.byteOffset).getUint32(0);
+      if (this.buffer.length < 4 + length) return;
+      const value = JSON.parse(decoder.decode(this.buffer.subarray(4, 4 + length)));
+      this.buffer = this.buffer.slice(4 + length);
+      if (!this.hello) { this.hello = value; this.emit('hello', value); continue; }
+      this.#envelope(value);
+    }
+  }
+
+  #envelope(envelope) {
+    const stream = this.streams.get(envelope.ch);
+    if (envelope.t === 'opened') stream?.emit('opened');
+    else if (envelope.t === 'data') stream?.deliver('data', envelope.d);
+    else if (envelope.t === 'close' && stream) { stream.closed = true; this.streams.delete(envelope.ch); stream.deliver('close', envelope.reason ?? null); }
+    else if (envelope.t === 'ping') this.send({ ch: 0, t: 'pong' });
+  }
+
+  /** Open a named stream; resolves once the machine accepts it, rejects with its refusal. */
+  open(name, params = {}) {
+    const id = this.next; this.next += 2;
+    const stream = new BrowserStream(this, id, name);
+    this.streams.set(id, stream);
+    return new Promise((resolve, reject) => {
+      // The refusal listener leaves once the stream opens, so a close after that is the caller's.
+      const refused = (reason) => reject(new Error(`${name} refused: ${reason ?? 'closed'}`));
+      stream.on('close', refused);
+      stream.once('opened', () => { stream.off('close', refused); resolve(stream); });
+      this.send({ ch: id, t: 'open', name, params });
+    });
+  }
+
+  close() { this.socket.close(1000, 'closed'); }
+}
+
+/**
+ * Machine `machineId` of team `teamId` on the Teams server at `origin`, reached with the
+ * caller's own `token`. `WebSocketImpl` defaults to the browser's WebSocket.
+ */
+export function openBrowserMachine({ origin, teamId, machineId, token }, { WebSocketImpl = globalThis.WebSocket } = {}) {
+  const url = `${String(origin).replace(/^http/, 'ws')}/api/v1/teams/${encodeURIComponent(teamId)}/machines/${encodeURIComponent(machineId)}/channel`;
+  const socket = new WebSocketImpl(url, [CHANNEL_PROTOCOL, `bearer.${token}`]);
+  const channel = new BrowserChannel(socket);
+  return new Promise((resolve, reject) => {
+    socket.addEventListener('open', () => socket.send(frame({ p: PROTOCOL, nv: NODE_PROTOCOL })), { once: true });
+    channel.once('hello', (hello) => (hello.error ? reject(new Error(hello.error)) : resolve(channel)));
+    socket.addEventListener('error', () => reject(new Error(`could not reach machine ${machineId} through ${origin}`)), { once: true });
+    socket.addEventListener('close', () => reject(new Error('the server closed the machine channel')), { once: true });
+  });
+}
+
+/** A pane's terminal stream: 'data' (text), 'hello', 'notice', 'close'; write(text), resize(cols, rows), close(). */
+export async function attachBrowserPane(channel, { pane, mode = 'observe', cols = 120, rows = 40 }) {
+  const stream = await channel.open('terminal', { pane, mode, cols, rows });
+  const pane$ = new Emitter();
+  stream.on('data', (chunk) => {
+    const text = decoder.decode(Uint8Array.from(atob(chunk), (c) => c.charCodeAt(0)));
+    let message = null;
+    try { message = JSON.parse(text); } catch { /* raw bytes */ }
+    if (message && typeof message.data === 'string') pane$.emit('data', message.data);
+    else if (message?.type === 'hello') pane$.emit('hello', message);
+    else if (message?.type === 'error') pane$.emit('error-message', message.message);
+    else if (message?.type === 'notice') pane$.emit('notice', message.message);
+    else pane$.emit('data', text);
+  });
+  stream.on('close', (reason) => pane$.emit('close', reason));
+  pane$.write = (text) => stream.write(JSON.stringify({ input: text }));
+  pane$.resize = (c, r) => stream.write(JSON.stringify({ resize: { cols: c, rows: r } }));
+  pane$.close = () => stream.close();
+  return pane$;
+}

package/channel.mjs

@@ -0,0 +1,319 @@
+// The machine channel: named streams multiplexed over one ordered byte stream.
+//
+//   hello    one plaintext frame each way: { p, nv } names the framing and the
+//            door vocabulary; a peer below the other's floor is refused with the
+//            floor named, so an old caller learns what to upgrade to.
+//   framing  u32 length | JSON envelope { ch, t, ... }, t in open | opened | data | close | ping | pong.
+//   streams  opened by name ("harness", "terminal", "node", "frontend", "port",
+//            "watch"); data is a string (a JSON line or base64 bytes); the
+//            acceptor decides per stream whether the caller may open it.
+//
+// It carries no identity of its own. The local door is an owner-only Unix
+// socket, so the OS user is the caller; the remote door is the Teams server,
+// which authenticates the caller and names its machine grant on each stream it
+// forwards over the machine's link (TLS on the wire).
+import { EventEmitter } from 'node:events';
+
+const PROTOCOL = 'supercode-machine/1';
+/** The door vocabulary version. It grows; the framing under PROTOCOL never changes. */
+export const NODE_PROTOCOL = 2;
+const MAX_FRAME = 8 * 1024 * 1024;
+
+/** Reads u32-length-prefixed frames from a socket. */
+function frameReader(socket, onFrame, onError) {
+  let buffer = Buffer.alloc(0);
+  socket.on('data', (chunk) => {
+    buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+    while (buffer.length >= 4) {
+      const length = buffer.readUInt32BE(0);
+      if (length > MAX_FRAME) {
+        onError(new Error(`frame of ${length} bytes exceeds the ${MAX_FRAME}-byte limit`));
+        socket.destroy();
+        return;
+      }
+      if (buffer.length < 4 + length) return;
+      const frame = buffer.subarray(4, 4 + length);
+      buffer = buffer.subarray(4 + length);
+      try {
+        onFrame(frame);
+      } catch (error) {
+        onError(error);
+        socket.destroy();
+        return;
+      }
+    }
+  });
+}
+
+function writeFrame(socket, bytes) {
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(bytes.length, 0);
+  socket.write(Buffer.concat([header, bytes]));
+}
+
+const HANDSHAKE_TIMEOUT_MS = 15_000;
+
+/**
+ * Read exactly one plaintext hello frame. The socket is PAUSED before any
+ * remainder is unshifted, so bytes that arrived in the same read as this frame
+ * (the peer's next hello frame, or its first sealed frame) wait for the
+ * next reader instead of being emitted to nobody; every reader resumes it.
+ * Bounded: a peer that opens a socket and says nothing is refused after
+ * HANDSHAKE_TIMEOUT_MS, so it cannot hold a slot for free.
+ */
+function readOneFrame(socket, timeoutMs = HANDSHAKE_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    let buffer = Buffer.alloc(0);
+    const timer = setTimeout(() => { cleanup(); reject(new Error(`hello frame did not arrive within ${timeoutMs} ms`)); socket.destroy(); }, timeoutMs);
+    const onData = (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length < 4) return;
+      const length = buffer.readUInt32BE(0);
+      if (length > 64 * 1024) {
+        cleanup();
+        reject(new Error('hello frame too large'));
+        socket.destroy();
+        return;
+      }
+      if (buffer.length < 4 + length) return;
+      cleanup();
+      const frame = buffer.subarray(4, 4 + length);
+      const rest = buffer.subarray(4 + length);
+      socket.pause();
+      if (rest.length) socket.unshift(rest);
+      resolve(frame);
+    };
+    const onError = (error) => { cleanup(); reject(error); };
+    const onClose = () => { cleanup(); reject(new Error('socket closed during handshake')); };
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.off('data', onData);
+      socket.off('error', onError);
+      socket.off('close', onClose);
+    };
+    socket.on('data', onData);
+    socket.on('error', onError);
+    socket.on('close', onClose);
+    socket.resume();
+  });
+}
+
+/**
+ * Refuse a peer before any key is derived, in the clear, naming the reason
+ * (a floor, a rate limit, no grant). It is one plaintext hello frame the
+ * initiator reads in place of the reply, so a refusal is a sentence rather
+ * than a closed socket.
+ */
+export function refuseHandshake(socket, message) {
+  try { writeFrame(socket, Buffer.from(JSON.stringify({ p: PROTOCOL, nv: NODE_PROTOCOL, error: message }))); } catch { /* peer already gone */ }
+  socket.destroy();
+}
+
+/**
+ * A multiplexed stream over the channel. `write(data)` sends a string; 'data'
+ * events deliver strings; 'close' when the peer or we close it.
+ */
+export class ChannelStream extends EventEmitter {
+  constructor(channel, id, name, params) {
+    super();
+    this.channel = channel;
+    this.id = id;
+    this.name = name;
+    this.params = params;
+    this.closed = false;
+  }
+  write(data) {
+    if (this.closed) throw new Error(`stream ${this.name}#${this.id} is closed`);
+    this.channel._send({ ch: this.id, t: 'data', d: data });
+  }
+  close(reason) {
+    if (this.closed) return;
+    this.closed = true;
+    this.channel._send({ ch: this.id, t: 'close', reason: reason ?? null });
+    this.channel._streams.delete(this.id);
+    this.emit('close', reason ?? null);
+  }
+  /**
+   * Deliver a peer's 'data' or 'close'. A stream is handed to its opener through a promise,
+   * so a peer that answers at once (its data in the same read as 'opened') would otherwise
+   * speak before the opener has attached a listener. Until a 'data' or 'close' listener is
+   * attached, events are held, and released in order on the microtask after it is.
+   */
+  _deliver(event, value) {
+    // A close someone listens for is never held behind data: what is held goes out first
+    // (to its listeners, or to none), then the close.
+    if (event === 'close' && this.listenerCount('close') > 0) {
+      const held = this._held ?? [];
+      this._held = null;
+      if (this._release) { this.off('newListener', this._release); this._release = null; }
+      for (const [e, v] of held) this.emit(e, v);
+      this.emit('close', value);
+      return;
+    }
+    if (!this._held && this.listenerCount('data') > 0) {
+      this.emit(event, value);
+      return;
+    }
+    if (!this._held) {
+      this._held = [];
+      const release = (name) => {
+        if (name !== 'data' && name !== 'close') return;
+        this.off('newListener', release);
+        this._release = null;
+        queueMicrotask(() => { const held = this._held ?? []; this._held = null; for (const [e, v] of held) this.emit(e, v); });
+      };
+      this._release = release;
+      this.on('newListener', release);
+    }
+    this._held.push([event, value]);
+  }
+}
+
+export class Channel extends EventEmitter {
+  /** @private use Channel.connect / Channel.accept */
+  constructor(socket, { peer, initiator }) {
+    super();
+    this.socket = socket;
+    this.peer = peer;
+    this._send = (envelope) => {
+      if (this.socket.destroyed) return;
+      writeFrame(socket, Buffer.from(JSON.stringify(envelope)));
+    };
+    this._streams = new Map();
+    this._nextStream = initiator ? 1 : 2;
+    this.closed = false;
+    frameReader(
+      socket,
+      (frame) => this._onEnvelope(JSON.parse(frame.toString('utf8'))),
+      (error) => this.emit('error', error),
+    );
+    // The hello left the socket paused with any early frames unshifted; our reader is on now.
+    socket.resume();
+    // A peer that ended its side has closed the channel: end ours now rather than
+    // hold a half-open socket until a transport timeout (5 s over a WebSocket).
+    socket.on('end', () => { if (!socket.destroyed) socket.destroy(); });
+    socket.on('close', () => {
+      this.closed = true;
+      for (const stream of this._streams.values()) {
+        stream.closed = true;
+        stream._deliver('close', 'connection closed');
+      }
+      this._streams.clear();
+      this.emit('close');
+    });
+    socket.on('error', (error) => this.emit('error', error));
+  }
+
+  _onEnvelope(envelope) {
+    if (envelope.t === 'open') {
+      const stream = new ChannelStream(this, envelope.ch, envelope.name, envelope.params ?? {});
+      this._streams.set(envelope.ch, stream);
+      let settled = false;
+      const accept = () => {
+        if (settled) return;
+        settled = true;
+        this._send({ ch: envelope.ch, t: 'opened' });
+      };
+      const refuse = (reason) => {
+        if (settled) return;
+        settled = true;
+        this._streams.delete(envelope.ch);
+        this._send({ ch: envelope.ch, t: 'close', reason: reason ?? 'refused' });
+      };
+      // An acceptor may decide asynchronously; only a channel with no acceptor at all refuses here.
+      if (this.listenerCount('stream') === 0) return refuse('no acceptor');
+      this.emit('stream', stream, accept, refuse);
+      return;
+    }
+    const stream = this._streams.get(envelope.ch);
+    if (envelope.t === 'opened') {
+      stream?.emit('opened');
+      return;
+    }
+    if (envelope.t === 'data') {
+      stream?._deliver('data', envelope.d);
+      return;
+    }
+    if (envelope.t === 'close') {
+      if (!stream) return;
+      stream.closed = true;
+      this._streams.delete(envelope.ch);
+      stream._deliver('close', envelope.reason ?? null);
+      return;
+    }
+    if (envelope.t === 'ping') {
+      this._send({ ch: 0, t: 'pong' });
+    }
+  }
+
+  /**
+   * Send a ping every `intervalMs` while the channel lives. A relay in front of a WebSocket
+   * (Cloudflare's among them) closes a connection that carries nothing for long enough.
+   */
+  keepAlive(intervalMs = 30_000) {
+    const timer = setInterval(() => { if (!this.closed) this._send({ ch: 0, t: 'ping' }); }, intervalMs);
+    timer.unref?.();
+    this.once('close', () => clearInterval(timer));
+    return this;
+  }
+
+  /** Open a named stream; resolves once the peer accepts it, rejects if refused. */
+  open(name, params = {}) {
+    // A closed connection refuses at once rather than waiting out the handshake bound.
+    if (this.closed) return Promise.reject(new Error(`${name} refused: connection closed`));
+    const id = this._nextStream;
+    this._nextStream += 2;
+    const stream = new ChannelStream(this, id, name, params);
+    this._streams.set(id, stream);
+    return new Promise((resolve, reject) => {
+      // Bounded: an acceptor that never answers is a refusal with a reason, not a hang.
+      const timer = setTimeout(() => {
+        stream.off('opened', onOpened); stream.off('close', onClosed);
+        this._streams.delete(id);
+        reject(new Error(`${name} did not open within ${HANDSHAKE_TIMEOUT_MS} ms`));
+      }, HANDSHAKE_TIMEOUT_MS);
+      timer.unref?.();
+      const onOpened = () => { clearTimeout(timer); stream.off('close', onClosed); resolve(stream); };
+      const onClosed = (reason) => { clearTimeout(timer); stream.off('opened', onOpened); reject(new Error(`${name} refused: ${reason ?? 'closed'}`)); };
+      stream.once('opened', onOpened);
+      stream.once('close', onClosed);
+      this._send({ ch: id, t: 'open', name, params });
+    });
+  }
+
+  close() {
+    this.socket.end();
+  }
+
+  /** The side that dialled: sends its hello, reads the answer. */
+  static async connect(socket, { floor = 1 } = {}) {
+    writeFrame(socket, Buffer.from(JSON.stringify({ p: PROTOCOL, nv: NODE_PROTOCOL })));
+    const reply = JSON.parse((await readOneFrame(socket)).toString('utf8'));
+    if (reply.error) { socket.destroy(); throw new Error(reply.error); }
+    if (reply.p !== PROTOCOL) { socket.destroy(); throw new Error(`peer speaks ${reply.p}, not ${PROTOCOL}`); }
+    const version = Number.isInteger(reply.nv) ? reply.nv : 0;
+    if (version < floor) {
+      socket.destroy();
+      throw new Error(`machine speaks node protocol ${version}; this caller's floor is ${floor}`);
+    }
+    return new Channel(socket, { peer: { nv: version }, initiator: true });
+  }
+
+  /** The side that listened: reads the caller's hello, answers or refuses with its floor. */
+  static async accept(socket, { floor = 1 } = {}) {
+    const hello = JSON.parse((await readOneFrame(socket)).toString('utf8'));
+    if (hello.p !== PROTOCOL) {
+      const message = `peer speaks ${hello.p}, not ${PROTOCOL}`;
+      refuseHandshake(socket, message);
+      throw new Error(message);
+    }
+    const version = Number.isInteger(hello.nv) ? hello.nv : 0;
+    if (version < floor) {
+      const message = `caller speaks node protocol ${version}; this machine's floor is ${floor}`;
+      refuseHandshake(socket, message);
+      throw new Error(message);
+    }
+    writeFrame(socket, Buffer.from(JSON.stringify({ p: PROTOCOL, nv: NODE_PROTOCOL })));
+    return new Channel(socket, { peer: { nv: version }, initiator: false });
+  }
+}

package/client.mjs

@@ -0,0 +1,119 @@
+// The caller's side of Volter Teams: open a machine's channel through its local door
+// (the daemon's owner-only socket in its home) or its remote door (a Teams server, which
+// forwards the channel to the enrolled machine's link after checking the caller's
+// grants), and speak request/reply over a stream. The local door needs Node builtins
+// only; `ws` loads when a remote door is first opened.
+import { connect as netConnect } from 'node:net';
+import { EventEmitter } from 'node:events';
+import { Channel } from './channel.mjs';
+
+/** The local door: the daemon serving `socketPath` (its home's `machine.sock`). */
+export async function openLocalMachine(socketPath, { timeoutMs = 10_000, floor = 2 } = {}) {
+  const socket = await new Promise((resolve, reject) => {
+    const connection = netConnect(socketPath);
+    const timer = setTimeout(() => { connection.destroy(); reject(new Error(`connect to ${socketPath} timed out`)); }, timeoutMs);
+    connection.once('connect', () => { clearTimeout(timer); resolve(connection); });
+    connection.once('error', (error) => {
+      clearTimeout(timer);
+      reject(error.code === 'ENOENT' || error.code === 'ECONNREFUSED'
+        ? Object.assign(new Error(`no machine daemon is serving ${socketPath}; run \`supercode teams machine start\``), { code: 'machine_offline' })
+        : error);
+    });
+  });
+  return Channel.connect(socket, { floor });
+}
+
+/**
+ * The remote door: machine `machineId` of team `teamId` on the Teams server at
+ * `origin`, authenticated with the caller's own credential. The server refuses
+ * a caller holding no grant on that machine exactly as it refuses one naming a
+ * machine that does not exist.
+ */
+export async function openRemoteMachine({ origin, teamId, machineId, token }, { timeoutMs = 15_000, floor = 2 } = {}) {
+  // Imported here so a caller of the local door alone needs nothing beyond Node builtins.
+  const { WebSocket, createWebSocketStream } = await import('ws');
+  const url = `${String(origin).replace(/^http/, 'ws')}/api/v1/teams/${encodeURIComponent(teamId)}/machines/${encodeURIComponent(machineId)}/channel`;
+  const socket = new WebSocket(url, 'supercode-machine-channel.v1', { headers: { authorization: `Bearer ${token}` }, maxPayload: 16 * 1024 * 1024 });
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => { socket.terminate(); reject(new Error(`connect to ${origin} timed out`)); }, timeoutMs);
+    socket.once('open', () => { clearTimeout(timer); resolve(); });
+    socket.once('unexpected-response', (_request, response) => {
+      clearTimeout(timer);
+      let body = '';
+      response.on('data', (chunk) => { body += chunk; });
+      response.on('end', () => {
+        let error = null;
+        try { error = JSON.parse(body).error; } catch { /* not JSON */ }
+        reject(Object.assign(new Error(error?.message ?? `server answered ${response.statusCode}`), { code: error?.code ?? 'unavailable', status: response.statusCode }));
+      });
+    });
+    socket.once('error', (error) => { clearTimeout(timer); reject(error); });
+  });
+  return (await Channel.connect(createWebSocketStream(socket), { floor })).keepAlive();
+}
+
+/** 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); },
+      });
+    });
+  }
+}
+
+/**
+ * A harness's own execution server on the channel's machine, as the local address its client takes
+ * (execution-doors.mjs; Codex's `CODEX_EXEC_SERVER_URL`). `channel` is a machine channel, or a function
+ * that opens one for each connection. Each websocket connection opens one
+ * `exec-server` stream, whose job on the machine is that connection's server: a frame is one line of
+ * its JSON-RPC both ways, the stream carrying the bytes in base64 as `exec` does. Loopback only.
+ */
+
+/**
+ * A request a browser made for a web page. Browsers send Sec-Fetch-Site and Sec-Fetch-Dest on
+ * every request to a loopback address, and Origin on cross-origin ones; Node's fetch sends only
+ * Sec-Fetch-Mode, so that one is no signal.
+ */
+export function fromWebPage(req) {
+  return req.headers.origin !== undefined || req.headers['sec-fetch-site'] !== undefined || req.headers['sec-fetch-dest'] !== undefined;
+}