@volter/teams 0.1.0

package/machine-core.mjs

@@ -0,0 +1,397 @@
+// The machine daemon's neutral core (company RFC 0008 §5, §6): this OS user's
+// machine identity, its account log and bounds, the owner-only local door, the
+// outbound link to a Teams server with admission re-derived from the machine's
+// own synced grants, and the doors other products serve behind it (products.mjs).
+// Everything a stream does is a door registered by name (`registerDoor`); the
+// harness registers its own (machine.mjs). A stream no door claims is refused.
+//
+// It decides nothing on anyone's behalf. Every act is logged.
+import { createServer, connect as netConnect } from 'node:net';
+import { EventEmitter } from 'node:events';
+import { existsSync, mkdirSync, rmSync, chmodSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { WebSocket, createWebSocketStream } from 'ws';
+import { Channel, NODE_PROTOCOL } from './channel.mjs';
+import { holds, admitFromGrants, LOCAL_OPERATOR } from './admission.mjs';
+import { findProduct, DAEMON_KINDS, PRODUCT_MAX_MESSAGE, productProof, sameSecret } from './products.mjs';
+import { loadOrCreateKeyPair, publicKeyId } from './identity.mjs';
+import { teamsHome, paths, writeJson, readLimits, AccountLog, ensureSocketDirectory } from './home.mjs';
+
+export const MACHINE_VERSION = 2;
+const LINK_BACKOFF_MIN_MS = 1_000;
+const LINK_BACKOFF_MAX_MS = 30_000;
+const LINK_PROTOCOL = 'supercode-machine-link.v1';
+/** The capabilities a product door can be told a caller holds; `operate` stays the daemon's. */
+const PRODUCT_CAPS = Object.freeze(['view', 'observe', 'interact', 'control', 'files', 'ports']);
+/** How often a server-forwarded product stream is re-admitted, so a revoked grant stops it. */
+const PRODUCT_READMIT_MS = 15_000;
+/** How long a product has to accept or refuse an open. */
+const PRODUCT_OPEN_TIMEOUT_MS = 10_000;
+/** How long a re-admission waits on the server for fresh grants before deciding from the ones it has. */
+const PRODUCT_REFRESH_TIMEOUT_MS = 5_000;
+
+export class MachineCore extends EventEmitter {
+  /**
+   * `link`: { server, teamId, machineId, credential, incarnationId, configuration } to hold the
+   * server link; `configuration()` resolves the machine's current configuration from the server
+   * (custodian and machine grants). Without it the daemon serves its local door only.
+   */
+  constructor({ home = teamsHome(), floor = null, limits = null, env = process.env, link = null } = {}) {
+    super();
+    this.home = home;
+    this.p = paths(home);
+    // limits.json is read once, here: a daemon's bounds are what it started with.
+    this.limits = { ...readLimits(this.p.limits), ...(limits ?? {}) };
+    // The protocol floor this Machine speaks to: a caller below it is refused, floor named.
+    this.floor = floor ?? this.limits.protocolFloor;
+    this.socketPath = this.p.socket;
+    this.env = env;
+    this.identity = loadOrCreateKeyPair(this.p.machineKey);
+    this.id = publicKeyId(this.identity.publicKeyPem);
+    this.log = new AccountLog(this.p.log, { rotateBytes: this.limits.logRotateBytes, keep: this.limits.logKeep });
+    this.connections = new Map(); // connection index → { channel, admitted, principal, ... }
+    this.nextConnection = 1;
+    this.server = null;
+    this.address = null;
+    this.link = link;
+    this.linkSocket = null;
+    this.linkChannel = null;
+    this.linkBackoff = LINK_BACKOFF_MIN_MS;
+    this.linkTimer = null;
+    // The machine's grants as the server last reported them: id → { id, subject_id, caps, targets, expires_at }.
+    this.linkGrants = new Map();
+    this.custodianId = null;
+    this.stopping = false;
+    this.doors = new Map(); // stream name → (entry, stream, accept, refuse, index) => void
+    this.registerDoor('product', (entry, stream, accept, refuse) => this.#serveProduct(entry, stream, accept, refuse));
+  }
+
+  /** Serve streams named `name` with `door(entry, stream, accept, refuse, index)`. */
+  registerDoor(name, door) {
+    if (this.doors.has(name)) throw new Error(`the ${name} door is already registered`);
+    this.doors.set(name, door);
+  }
+
+  /** Before the local door opens: a product's own setup. */
+  async beforeListen() {}
+  /** After the local door and link close: a product's own teardown. */
+  async afterStop() {}
+  /** A connection closed: a product drops what it routed to it. */
+  connectionClosed(_index) {}
+
+  // ---- lifecycle -----------------------------------------------------------
+
+  async start() {
+    mkdirSync(this.home, { recursive: true, mode: 0o700 });
+    chmodSync(this.home, 0o700);
+    // A daemon already serving this home is found before anything of this one starts.
+    ensureSocketDirectory(this.socketPath);
+    await clearStaleSocket(this.socketPath);
+    await this.beforeListen();
+    this.server = createServer((socket) => this.#accept(socket));
+    await new Promise((resolveListen, reject) => {
+      this.server.once('error', reject);
+      this.server.listen(this.socketPath, () => { this.server.off('error', reject); resolveListen(); });
+    });
+    // Owner-only: the socket is the local door, and whoever opens it is this OS user.
+    chmodSync(this.socketPath, 0o600);
+    this.address = this.socketPath;
+    writeJson(this.p.machine, { pid: process.pid, id: this.id, socket: this.socketPath, startedAt: Date.now(), version: MACHINE_VERSION, protocol: NODE_PROTOCOL, floor: this.floor, server: this.link?.server ?? null });
+    this.emit('listening', this.socketPath);
+    if (this.link) {
+      await this.refreshLinkConfiguration().catch((error) => this.emit('link', { event: 'configuration-failed', error: error.message }));
+      this.#connectLink();
+    }
+    return this.socketPath;
+  }
+
+  async stop() {
+    this.stopping = true;
+    if (this.linkTimer) { clearTimeout(this.linkTimer); this.linkTimer = null; }
+    // A close frame, so the server sees a machine that left rather than one that vanished.
+    try { this.linkSocket?.close(1000, 'machine stopped'); } catch { this.linkSocket?.terminate(); }
+    this.linkSocket = null;
+    await this.beforeClose();
+    for (const { channel } of this.connections.values()) channel.close();
+    this.server?.close();
+    await this.afterStop();
+    rmSync(this.socketPath, { force: true });
+    if (existsSync(this.p.machine)) rmSync(this.p.machine);
+  }
+
+  /** Before the connections close: a product finishes or abandons what is in flight. */
+  async beforeClose() {}
+
+  // ---- the server link ----------------------------------------------------
+
+  /** Re-read the machine's custodian and grants from the server. */
+  async refreshLinkConfiguration() {
+    const configuration = await this.link.configuration();
+    this.custodianId = configuration.custodian_id ?? null;
+    this.linkGrants = new Map((configuration.machine_grants ?? []).map((grant) => [grant.id, grant]));
+    return configuration;
+  }
+
+  /**
+   * One outbound WebSocket to the server, re-dialled with backoff for as long as
+   * the daemon runs. The server opens a stream on it per stream a caller opens.
+   */
+  #connectLink() {
+    if (this.stopping || !this.link) return;
+    const { server, teamId, machineId, credential, incarnationId } = this.link;
+    const url = `${server.replace(/^http/, 'ws')}/api/v1/teams/${encodeURIComponent(teamId)}/machines/${encodeURIComponent(machineId)}/link`;
+    const socket = new WebSocket(url, LINK_PROTOCOL, { headers: { authorization: `Bearer ${credential}`, 'x-teams-incarnation': incarnationId }, maxPayload: 16 * 1024 * 1024 });
+    this.linkSocket = socket;
+    let settled = false;
+    const dropped = (error) => {
+      if (settled) return;
+      settled = true;
+      if (this.linkSocket === socket) { this.linkSocket = null; this.linkChannel = null; }
+      this.emit('link', { event: 'dropped', error: error?.message ?? null });
+      this.#retryLink();
+    };
+    socket.once('open', async () => {
+      try {
+        const channel = (await Channel.connect(createWebSocketStream(socket), { floor: this.floor })).keepAlive();
+        this.linkChannel = channel;
+        this.linkBackoff = LINK_BACKOFF_MIN_MS;
+        channel.on('stream', (stream, accept, refuse) => { void this.#onLinkStream(channel, stream, accept, refuse); });
+        channel.on('close', () => dropped(null));
+        channel.on('error', () => {});
+        this.emit('link', { event: 'up', server });
+      } catch (error) { socket.terminate(); dropped(error); }
+    });
+    socket.once('error', dropped);
+    socket.once('close', () => dropped(null));
+  }
+
+  #retryLink() {
+    if (this.stopping || !this.link || this.linkTimer) return;
+    const delay = this.linkBackoff;
+    this.linkBackoff = Math.min(this.linkBackoff * 2, LINK_BACKOFF_MAX_MS);
+    this.linkTimer = setTimeout(() => { this.linkTimer = null; this.#connectLink(); }, delay);
+    this.linkTimer.unref?.();
+  }
+
+  /** The admission a forwarded stream's claim earns here, refreshing the grants once when the claim names one we have not seen. */
+  async #admitClaim(claim) {
+    const admit = () => admitFromGrants(claim, { custodianId: this.custodianId, grants: this.linkGrants });
+    let admitted = admit();
+    const unknown = (claim?.grants ?? []).some((id) => !this.linkGrants.has(id));
+    const revisions = claim?.revisions && typeof claim.revisions === 'object' ? claim.revisions : null;
+    const stale = revisions ? (claim?.grants ?? []).some((id) => this.linkGrants.get(id)?.revision !== revisions[id]) : false;
+    if (!admitted || unknown || stale) {
+      await this.refreshLinkConfiguration().catch(() => {});
+      admitted = admit();
+    }
+    return admitted;
+  }
+
+  /** A stream the server forwarded for one caller: admitted per stream, from the claim it carries. */
+  async #onLinkStream(channel, stream, accept, refuse) {
+    const claim = stream.params?._admitted ?? null;
+    if (stream.params) delete stream.params._admitted;
+    const admitted = await this.#admitClaim(claim);
+    if (!admitted) {
+      this.log.append({ principal: claim?.principal ?? null, cap: stream.name, target: '*', outcome: 'refused', detail: 'no machine grant' });
+      return refuse('no machine grant for this caller');
+    }
+    const index = this.nextConnection++;
+    const entry = { channel, admitted, principal: claim.principal, verify: () => this.#admitClaim(claim), localAdmission: () => admitFromGrants(claim, { custodianId: this.custodianId, grants: this.linkGrants }) };
+    this.connections.set(index, entry);
+    stream.on('close', () => { this.connections.delete(index); this.connectionClosed(index); });
+    this.log.append({ principal: entry.principal, cap: 'connect', target: '*', outcome: admitted.class, detail: 'server' });
+    this.#routeStream(index, entry, stream, accept, refuse);
+  }
+
+  // ---- connections ---------------------------------------------------------
+
+  /** The local door: whoever opened the owner-only socket is this OS user. */
+  async #accept(socket) {
+    let channel;
+    try {
+      channel = await Channel.accept(socket, { floor: this.floor });
+    } catch (error) {
+      this.log.append({ principal: 'local', cap: 'connect', target: '*', outcome: 'refused', detail: error.message });
+      return;
+    }
+    const index = this.nextConnection++;
+    const entry = { channel, admitted: LOCAL_OPERATOR, principal: 'local' };
+    this.connections.set(index, entry);
+    channel.on('stream', (stream, accept, refuse) => this.#routeStream(index, entry, stream, accept, refuse));
+    channel.on('close', () => { this.connections.delete(index); this.connectionClosed(index); });
+    channel.on('error', () => {});
+  }
+
+  #routeStream(index, entry, stream, accept, refuse) {
+    const door = this.doors.get(stream.name);
+    if (!door) return refuse(`unknown stream ${stream.name}`);
+    return door(entry, stream, accept, refuse, index);
+  }
+
+  /**
+   * A target of a kind another product serves on this machine (`browser-profile:<name>`),
+   * found by that product's receipt (products.mjs). The caller's capabilities on the target
+   * are decided here, before the product hears of the stream; the product is told them and
+   * enforces what each admits on its own kind, and proves it holds the receipt's token before
+   * anything is relayed. `*` reaches a product's kind only for `view`. A server-forwarded
+   * caller is re-admitted from this machine's grants every PRODUCT_READMIT_MS and when a grant
+   * it holds expires, with the grants refreshed from the server at most that often: wider caps
+   * are sent on, and narrower ones close the stream.
+   */
+  async #serveProduct(entry, stream, accept, refuse) {
+    const { principal } = entry;
+    const target = String(stream.params?.target ?? '');
+    const colon = target.indexOf(':');
+    const kind = colon > 0 ? target.slice(0, colon) : '';
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(kind) || !/^[^\x00-\x1f]{1,4096}$/.test(target.slice(colon + 1))) return refuse('target must be <kind>:<name>');
+    if (DAEMON_KINDS.includes(kind)) return refuse(`${kind}: is served by this daemon's own streams`);
+    const capsOn = (admitted) => {
+      if (!admitted) return [];
+      if (admitted.class === 'operator') return [...PRODUCT_CAPS];
+      // A grant on `*` names no kind, so it lists (view) and reaches nothing a product serves.
+      const named = { class: admitted.class, grants: admitted.grants.map((grant) => ({ ...grant, targets: grant.targets.filter((t) => t !== '*') })) };
+      return PRODUCT_CAPS.filter((cap) => holds(named, cap, target) || (cap === 'view' && holds(admitted, 'view', target)));
+    };
+    let caps = capsOn(entry.admitted);
+    // A list of every target of a kind is admitted to anyone holding something on that kind:
+    // the product is told which grants of that kind the caller holds and lists only what they
+    // reach. Those grants travel with the open for this one request, and only for this kind.
+    const listing = target === `${kind}:*` && stream.params?.op === 'list';
+    const kindGrants = listing && entry.admitted?.class !== 'operator'
+      ? (entry.admitted?.grants ?? []).map((grant) => ({ caps: grant.caps, targets: grant.targets.filter((t) => t.startsWith(`${kind}:`) || t === '*') })).filter((grant) => grant.targets.length)
+      : null;
+    if (!caps.length && !(kindGrants && kindGrants.length)) {
+      this.log.append({ principal, cap: 'product', target, outcome: 'refused' });
+      return refuse(`no grant on ${target}`);
+    }
+    const receipt = findProduct(this.home, kind);
+    if (!receipt) {
+      this.log.append({ principal, cap: 'product', target, outcome: 'refused', detail: 'not served' });
+      return refuse(`${kind} is not served on this machine`);
+    }
+    const params = { ...(stream.params ?? {}) };
+    delete params.target;
+    const nonce = randomBytes(16).toString('hex');
+    const upstream = new WebSocket(receipt.endpoint, { maxPayload: PRODUCT_MAX_MESSAGE + 1024 });
+    let proven = false;
+    let accepted = false;
+    let settled = false;
+    let timer = null;
+    const unavailable = `${receipt.name} is unavailable`;
+    const end = () => {
+      settled = true;
+      clearTimeout(opening);
+      clearTimeout(timer);
+      if (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING) upstream.terminate();
+    };
+    const decline = (reason, detail = reason) => {
+      if (settled) return;
+      end();
+      this.log.append({ principal, cap: 'product', target, outcome: 'refused', detail: `${receipt.name}: ${detail}` });
+      refuse(reason);
+    };
+    let finished = false;
+    const finish = (reason, detail = reason) => {
+      if (!accepted) return decline(unavailable, detail);
+      if (finished) return;
+      finished = true;
+      end();
+      this.log.append({ principal, cap: 'product', target, outcome: 'closed', detail });
+      if (!stream.closed) stream.close(reason);
+    };
+    const opening = setTimeout(() => decline(unavailable, 'did not answer'), PRODUCT_OPEN_TIMEOUT_MS);
+    // The caller may leave before the product answers; nothing is then left open.
+    stream.once('close', () => { if (!accepted) { if (!settled) { end(); this.log.append({ principal, cap: 'product', target, outcome: 'abandoned' }); } } else finish('caller closed'); });
+    const readmit = async () => {
+      timer = null;
+      if (stream.closed || !accepted) return;
+      // First from the grants this machine holds, without waiting on the network.
+      if (!capsOn(entry.localAdmission?.()).length) return finish('no live grant');
+      await this.#refreshGrantsAtMost(PRODUCT_READMIT_MS);
+      if (stream.closed) return;
+      const fresh = entry.localAdmission?.() ?? null;
+      const now = capsOn(fresh);
+      // A narrowed grant ends the stream: what the product already enabled under the wider
+      // one (a screencast, a domain's events) must not outlive it. A wider one is passed on.
+      if (!now.length || caps.some((cap) => !now.includes(cap))) return finish('grant narrowed');
+      if (now.length !== caps.length) {
+        this.log.append({ principal, cap: 'product', target, outcome: 'caps widened', detail: now.join(',') });
+        caps = now;
+        if (upstream.readyState === WebSocket.OPEN) upstream.send(JSON.stringify({ type: 'caps', caps }));
+      }
+      entry.admitted = fresh;
+      schedule();
+    };
+    const schedule = () => {
+      if (!entry.localAdmission || stream.closed) return;
+      const expiries = (entry.admitted.grants ?? []).map((grant) => this.linkGrants.get(grant.id)?.expires_at).filter(Number.isFinite);
+      const untilExpiry = expiries.length ? Math.min(...expiries) - Date.now() + 50 : Infinity;
+      timer = setTimeout(() => { readmit().catch(() => finish('re-admission failed')); }, Math.max(50, Math.min(PRODUCT_READMIT_MS, untilExpiry)));
+      timer.unref?.();
+    };
+    // The product proves it holds the receipt's token before it hears who is calling.
+    upstream.on('open', () => upstream.send(JSON.stringify({ type: 'hello', nonce })));
+    upstream.on('message', (data) => {
+      let message;
+      try { message = JSON.parse(String(data)); } catch { return; }
+      if (!accepted) {
+        if (settled) return;
+        if (!proven) {
+          if (message.type !== 'hello' || typeof message.nonce !== 'string' || !sameSecret(message.proof, productProof(receipt.token, 'product', nonce))) return decline(unavailable, 'failed its proof');
+          proven = true;
+          upstream.send(JSON.stringify({ type: 'open', proof: productProof(receipt.token, 'daemon', message.nonce), principal, class: entry.admitted.class, caps, target, params, ...(kindGrants ? { grants: kindGrants } : {}) }));
+          return;
+        }
+        if (message.type === 'accepted') {
+          if (stream.closed) { end(); return; }
+          accepted = true;
+          settled = true;
+          clearTimeout(opening);
+          accept();
+          this.log.append({ principal, cap: 'product', target, outcome: 'opened', detail: `${receipt.name}: ${caps.join(',')}` });
+          if (listing) { /* answered in one message; no re-admission timer for it */ } else schedule();
+          stream.on('data', (text) => {
+            if (upstream.readyState !== WebSocket.OPEN) return;
+            const body = JSON.stringify({ type: 'data', data: String(text) });
+            if (Buffer.byteLength(body) > PRODUCT_MAX_MESSAGE) return finish('message too large');
+            upstream.send(body);
+          });
+        } else {
+          decline(message.type === 'refused' ? String(message.reason ?? 'refused').slice(0, 200) : unavailable);
+        }
+        return;
+      }
+      if (message.type !== 'data' || typeof message.data !== 'string' || stream.closed) return;
+      // Over the channel's frame, one message would drop the machine's whole link; it ends only this stream.
+      if (Buffer.byteLength(message.data) > PRODUCT_MAX_MESSAGE) return finish('message too large');
+      stream.write(message.data);
+    });
+    upstream.on('close', () => finish(`${receipt.name} closed`));
+    upstream.on('error', (error) => { if (!accepted) decline(unavailable, error.code ?? error.message); else finish(`${receipt.name} closed`, error.code ?? error.message); });
+  }
+
+  /** Refresh the synced grants from the server, sharing one in-flight refresh and at most once per `intervalMs`. */
+  #refreshGrantsAtMost(intervalMs) {
+    if (!this.link) return Promise.resolve();
+    if (this.grantRefresh) return this.grantRefresh;
+    if (Date.now() - (this.grantRefreshedAt ?? 0) < intervalMs) return Promise.resolve();
+    const deadline = new Promise((resolve) => { const t = setTimeout(resolve, PRODUCT_REFRESH_TIMEOUT_MS); t.unref?.(); });
+    this.grantRefresh = Promise.race([this.refreshLinkConfiguration().catch(() => {}), deadline])
+      .finally(() => { this.grantRefresh = null; this.grantRefreshedAt = Date.now(); });
+    return this.grantRefresh;
+  }
+
+}
+
+async function clearStaleSocket(path) {
+  if (!existsSync(path)) return;
+  const live = await new Promise((done) => {
+    const probe = netConnect(path);
+    probe.once('connect', () => { probe.destroy(); done(true); });
+    probe.once('error', () => done(false));
+  });
+  if (live) throw Object.assign(new Error(`a machine daemon is already serving ${path}`), { code: 'EADDRINUSE' });
+  rmSync(path, { force: true });
+}
+

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@volter/teams",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./index.mjs",
+    "./channel": "./channel.mjs",
+    "./browser-channel": "./browser-channel.mjs",
+    "./admission": "./admission.mjs",
+    "./identity": "./identity.mjs",
+    "./products": "./products.mjs",
+    "./machine-core": "./machine-core.mjs",
+    "./home": "./home.mjs",
+    "./server/core": "./server/core.mjs",
+    "./server/http": "./server/http.mjs",
+    "./server/auth": "./server/auth.mjs",
+    "./server/machine-link": "./server/machine-link.mjs",
+    "./server/request-json": "./server/request-json.mjs",
+    "./server/identity": "./server/identity.mjs",
+    "./server/events": "./server/events.mjs",
+    "./server/wire": "./server/wire.mjs",
+    "./server/migrations": "./server/migrations/index.mjs",
+    "./client": "./client.mjs"
+  },
+  "files": [
+    "*.mjs",
+    "server",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@volter/identity": "^0.1.0",
+    "ws": "^8.21.0"
+  }
+}

package/products.mjs

@@ -0,0 +1,157 @@
+// Products served behind the daemon (RFC 0008 §1, §5). A product that serves
+// its own kind of target on this machine (Volter Browsers: `browser-profile:`)
+// writes a receipt into <teams home>/products/, the way a hosted runtime writes
+// the receipt the frontend door finds:
+//
+//   products/<name>.json   { name, kinds: [<kind>...], endpoint: 'ws://127.0.0.1:<port>/<path>', token, pid, startedAt }
+//
+// The daemon admits a `product` stream against the caller's grants BEFORE the
+// product hears of it, then dials the endpoint named in the newest live receipt.
+// The token never crosses the wire; each side proves it holds it, the product
+// first, so a process that took over a dead product's port learns nothing:
+//
+//   → { type: 'hello', nonce: n1 }
+//   ← { type: 'hello', proof: HMAC(token, 'product|' + n1), nonce: n2 }
+//   → { type: 'open', proof: HMAC(token, 'daemon|' + n2), principal, class, caps, target, params }
+//   ← { type: 'accepted' }  or  { type: 'refused', reason }
+//
+// then each text message is relayed both ways as { type: 'data', data }. `caps`
+// are the capabilities the caller holds on `target`, re-derived by the daemon; a
+// product enforces what each capability admits on its own kind and trusts
+// nothing else a caller sends. The daemon sends `{ type: 'caps', caps }` when a
+// re-admission widens them, and closes the stream when it narrows them.
+//
+// One request differs: a list of every target of a kind (`<kind>:*` with params.op
+// 'list') is admitted to a caller holding any grant on that kind, so `caps` may be
+// empty, and the open carries `grants`, the caller's grants of that kind ({caps,
+// targets}), for the product to list only what they cover. A product refuses empty
+// caps on any other request.
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes, createHmac, timingSafeEqual } from 'node:crypto';
+
+/** Kinds the daemon serves itself (the harness); a receipt can never claim them. */
+export const DAEMON_KINDS = Object.freeze(['pane', 'runtime', 'root', 'port']);
+const KIND = /^[a-z][a-z0-9-]{0,31}$/;
+
+export const productsDir = (home) => join(home, 'products');
+
+/** The largest message, in bytes, relayed either way: below the machine channel's 8 MiB frame, leaving room for its envelope. */
+export const PRODUCT_MAX_MESSAGE = 8 * 1024 * 1024 - 64 * 1024;
+
+/** One side's proof that it holds the receipt's token: HMAC-SHA256(token, role|nonce), hex. */
+export const productProof = (token, role, nonce) => createHmac('sha256', token).update(`${role}|${nonce}`).digest('hex');
+
+/** Constant-time comparison of two strings. */
+export function sameSecret(a, b) {
+  const x = Buffer.from(String(a ?? '')), y = Buffer.from(String(b ?? ''));
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+
+function validReceipt(receipt) {
+  if (!receipt || typeof receipt !== 'object') return false;
+  if (typeof receipt.name !== 'string' || !KIND.test(receipt.name)) return false;
+  if (!Array.isArray(receipt.kinds) || !receipt.kinds.length) return false;
+  if (receipt.kinds.some((kind) => typeof kind !== 'string' || !KIND.test(kind) || DAEMON_KINDS.includes(kind))) return false;
+  if (typeof receipt.token !== 'string' || receipt.token.length < 32) return false;
+  let url;
+  try { url = new URL(receipt.endpoint); } catch { return false; }
+  // Loopback only: the token must never leave this machine.
+  return url.protocol === 'ws:' && (url.hostname === '127.0.0.1' || url.hostname === '[::1]');
+}
+
+/** The newest live receipt of a product serving `kind` on this machine, or null. */
+export function findProduct(home, kind) {
+  let names;
+  try { names = readdirSync(productsDir(home)); } catch { return null; }
+  let best = null;
+  for (const file of names) {
+    if (!file.endsWith('.json')) continue;
+    let receipt;
+    try { receipt = JSON.parse(readFileSync(join(productsDir(home), file), 'utf8')); } catch { continue; }
+    if (`${receipt?.name}.json` !== file) continue;
+    if (!validReceipt(receipt) || !receipt.kinds.includes(kind) || !alive(receipt.pid)) continue;
+    if (!best || (receipt.startedAt ?? 0) > (best.startedAt ?? 0)) best = receipt;
+  }
+  return best;
+}
+
+/**
+ * Serve `kinds` behind this machine's daemon: listen on loopback, write the
+ * receipt, and hand each admitted open to `onOpen({ principal, class, caps,
+ * grants, target, params, send, close, onMessage, onCaps, onClose })`; `grants` is
+ * set on a kind's list only. Return a string
+ * from `onOpen` to refuse with that reason. Returns `{ close() }`, which removes
+ * the receipt.
+ */
+export async function serveProduct({ home, name, kinds, onOpen }) {
+  if (typeof name !== 'string' || !KIND.test(name)) throw new Error('a product name is lowercase letters, digits and dashes');
+  if (!Array.isArray(kinds) || !kinds.length || kinds.some((kind) => typeof kind !== 'string' || !KIND.test(kind))) throw new Error('kinds are lowercase letters, digits and dashes');
+  const claimed = kinds.filter((kind) => DAEMON_KINDS.includes(kind));
+  if (claimed.length) throw new Error(`${claimed.join(', ')} are served by the daemon itself`);
+  const { WebSocketServer } = await import('ws');
+  const token = randomBytes(32).toString('hex');
+  const path = `/${randomBytes(8).toString('hex')}`;
+  const server = new WebSocketServer({ host: '127.0.0.1', port: 0, path, maxPayload: PRODUCT_MAX_MESSAGE + 1024 });
+  await new Promise((resolve, reject) => { server.once('listening', resolve); server.once('error', reject); });
+  server.on('connection', (socket) => {
+    const listeners = { message: new Set(), caps: new Set(), close: new Set() };
+    let phase = 'hello';
+    let challenge = null;
+    // A connection that never proves itself is dropped.
+    const deadline = setTimeout(() => { if (phase !== 'open') socket.terminate(); }, 10_000);
+    socket.on('error', () => socket.terminate());
+    socket.on('message', async (data) => {
+      let message;
+      try { message = JSON.parse(String(data)); } catch { message = null; }
+      if (phase === 'hello') {
+        if (message?.type !== 'hello' || typeof message.nonce !== 'string') { socket.terminate(); return; }
+        challenge = randomBytes(16).toString('hex');
+        phase = 'proving';
+        socket.send(JSON.stringify({ type: 'hello', proof: productProof(token, 'product', message.nonce), nonce: challenge }));
+        return;
+      }
+      if (phase === 'proving') {
+        if (message?.type !== 'open' || !sameSecret(message.proof, productProof(token, 'daemon', challenge))) { socket.terminate(); return; }
+        phase = 'opening';
+        clearTimeout(deadline);
+        const session = {
+          principal: message.principal, class: message.class, caps: message.caps, target: message.target, params: message.params ?? {},
+          grants: Array.isArray(message.grants) ? message.grants : [],
+          send: (text) => { if (socket.readyState === socket.OPEN) socket.send(JSON.stringify({ type: 'data', data: text })); },
+          close: (reason) => socket.close(1000, String(reason ?? '').slice(0, 120)),
+          onMessage: (fn) => listeners.message.add(fn),
+          onCaps: (fn) => listeners.caps.add(fn),
+          onClose: (fn) => listeners.close.add(fn),
+        };
+        let refusal;
+        try { refusal = await onOpen(session); } catch { refusal = 'the product could not open this target'; }
+        if (typeof refusal === 'string') { socket.send(JSON.stringify({ type: 'refused', reason: refusal })); socket.close(1000); return; }
+        phase = 'open';
+        socket.send(JSON.stringify({ type: 'accepted' }));
+        return;
+      }
+      if (phase !== 'open') return;
+      if (message?.type === 'data' && typeof message.data === 'string') for (const fn of listeners.message) fn(message.data);
+      else if (message?.type === 'caps' && Array.isArray(message.caps)) for (const fn of listeners.caps) fn(message.caps);
+    });
+    socket.on('close', () => { clearTimeout(deadline); for (const fn of listeners.close) fn(); });
+  });
+  const dir = productsDir(home);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const file = join(dir, `${name}.json`);
+  const receipt = { name, kinds, endpoint: `ws://127.0.0.1:${server.address().port}${path}`, token, pid: process.pid, startedAt: Date.now() };
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(receipt), { mode: 0o600 });
+  renameSync(temp, file);
+  return {
+    receipt: { name, kinds, endpoint: receipt.endpoint },
+    close: () => { rmSync(file, { force: true }); for (const client of server.clients) client.terminate(); server.close(); },
+  };
+}

package/server/auth.mjs

@@ -0,0 +1,13 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+export const hashToken = token => createHash('sha256').update(token).digest('hex');
+export function makeToken(credentialId, bytes = randomBytes(32)) { return `sct_${credentialId}.${Buffer.from(bytes).toString('base64url')}`; }
+export function tokenMatches(token, digest) { const actual = Buffer.from(hashToken(token)); const expected = Buffer.from(String(digest)); return actual.length === expected.length && timingSafeEqual(actual, expected); }
+export function bearer(header) { const match = /^Bearer ([^\s]+)$/.exec(header ?? ''); return match?.[1] ?? null; }
+export function canRead(auth, session, grants = []) {
+  if (!auth || !['user','service'].includes(auth.kind) || !auth.active || session.deleted_at != null) return false;
+  if (session.visibility === 'team' || session.custodian_id === auth.principal_id) return true;
+  const now = auth.now;
+  return grants.some(g => (g.subject_id === auth.principal_id || auth.group_ids?.includes(g.subject_id)) && (g.expires_at == null || g.expires_at > now));
+}
+export function canManage(auth, session, grants = []) { if (!auth?.active || !['user','service'].includes(auth.kind) || auth.role === 'viewer') return false; return session.custodian_id === auth.principal_id || grants.some(g => g.role === 'manager' && (g.subject_id === auth.principal_id || auth.group_ids?.includes(g.subject_id)) && (g.expires_at == null || g.expires_at > auth.now)); }
+export const isAdmin = auth => auth?.active && ['user','service'].includes(auth.kind) && (auth.role === 'owner' || auth.role === 'admin');