@volter/teams 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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",

package/server/delegated.mjs

@@ -5,15 +5,26 @@
 // 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.
 //
+// A valid signature is not enough. The workplace decides who in a Room may see or drive a surface, but only the
+// machine's custodian decides what is on offer: a token opens a surface only when the custodian published exactly that
+// pane or folder to this issuer (server/publications.mjs, checked by the channel door in machine-link.mjs). Here, a
+// token is refused outright when it names a wildcard or the whole filesystem, or lives longer than MAX_LIFETIME_S.
+//
 // 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
+import { publishableTarget } from './publications.mjs';
+
 const CAPS = {
   folder: { control: ['files'], view: ['observe'] },
   pane: { control: ['observe', 'control'], view: ['observe'] },
 };
 const KEYS_TTL_MS = 5 * 60 * 1000;
 const SKEW_S = 30;
+// A delegated token lives at most 15 minutes (exp - iat, and exp - now). The viewer asks its page for a fresh one
+// (`delegated-token-needed`) when its channel closes at expiry, so a short life costs a reconnect, not access; and it
+// bounds what one leaked token, or one a workplace signed before its key was rotated out, can still do.
+export const MAX_LIFETIME_S = 15 * 60;
 
 const decoder = new TextDecoder();
 const fromBase64Url = (text) => Uint8Array.from(atob(text.replaceAll('-', '+').replaceAll('_', '/') + '='.repeat((4 - text.length % 4) % 4)), (c) => c.charCodeAt(0));
@@ -45,11 +56,51 @@ async function issuerKey(api, kid) {
 }
 
 /**
- * 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.
+ * What a delegated token claims, or null when it is not one this server trusts: { subject, issuer, teamId, machineId,
+ * target, room, caps, expiresAt, scope, kind }; it admits nothing until matched to a publication (publicationFor).
+ * Anything unverifiable, expired, too long-lived, for another audience or naming no exact machine target is null,
+ * and the caller refuses it exactly as an unknown credential.
  */
 export async function delegatedAccessOf(api, token) {
+  const claims = await verifiedClaims(api, token);
+  if (!claims) return null;
+  // Short-lived by construction: an issued-at, not in the future, and no more than MAX_LIFETIME_S to its expiry.
+  const now = Math.floor(api.clock.nowMs() / 1000);
+  if (typeof claims.iat !== 'number' || claims.iat > now + SKEW_S || claims.exp - claims.iat > MAX_LIFETIME_S || claims.exp - now > MAX_LIFETIME_S + SKEW_S) 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;
+  // One exact pane or one folder below the root: never `pane:*`, `root:/`, or anything a publication could not name.
+  if (!publishableTarget(surface.kind, config.target)) return null;
+  // Every publication is into one Room, so a token must name the Room it opens the surface in.
+  const room = surface.room ?? claims.room ?? null;
+  if (typeof room !== 'string' || !room) return null;
+  return { caps, expiresAt: claims.exp * 1000, issuer: claims.iss, kind: surface.kind, machineId: config.machine, room, scope: claims.scope, subject: claims.sub, target: config.target, teamId: config.team };
+}
+
+/** Longest a session-view token may live, whatever it says: the workplace mints them for minutes. */
+const SESSION_TOKEN_MAX_S = 15 * 60;
+
+/**
+ * What a session-view token admits (RH2 ADR 0008), or null: { subject, issuer, teamId, sessionRef, room, conversation,
+ * scope, expiresAt }. It names one session (by its id or the harness's own) of one team, and the Room and Conversation
+ * viewing it; the server admits it only for a session its owner bound to that Room and Conversation.
+ */
+export async function delegatedSessionOf(api, token) {
+  const claims = await verifiedClaims(api, token);
+  if (!claims) return null;
+  const session = claims.session;
+  if (!session || typeof session.team !== 'string' || typeof session.id !== 'string' || !session.id) return null;
+  if (typeof claims.room !== 'string' || !claims.room || typeof claims.conversation !== 'string' || !claims.conversation) return null;
+  if (!['view', 'control'].includes(claims.scope)) return null;
+  const now = Math.floor(api.clock.nowMs() / 1000);
+  if (claims.exp - now > SESSION_TOKEN_MAX_S || (typeof claims.iat === 'number' && claims.exp - claims.iat > SESSION_TOKEN_MAX_S)) return null;
+  return { conversation: claims.conversation, expiresAt: claims.exp * 1000, issuer: claims.iss, room: claims.room, scope: claims.scope, sessionRef: session.id, subject: claims.sub, teamId: session.team };
+}
+
+/** A token's claims when it is one this server trusts: signed by the issuer's key, for this server, in its lifetime. */
+async function verifiedClaims(api, token) {
   if (!api.delegatedIssuer || !api.publicOrigin || !looksDelegated(token)) return null;
   try {
     const [head, body, signature] = token.split('.');
@@ -64,13 +115,7 @@ export async function delegatedAccessOf(api, token) {
     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 };
+    return claims;
   } catch {
     return null;
   }

package/server/http.mjs

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { bearer, hashToken, canManage, isAdmin, makeToken } from './auth.mjs';
 import { ContractError, canonicalJson, validationFailure, cursorHash, cursorToken, sha256 } from './wire.mjs';
 import { machineGrantRoute, machineGrantRows, closeMachineChannels, closeChannelsFor } from './machine-link.mjs';
+import { publicationRoute, publisherRevocation } from './publications.mjs';
 import { exact, parseJson as parseRequestJson } from './request-json.mjs';
 import { identityOf } from './identity.mjs';
 import { serveViewer } from './viewer.mjs';
@@ -69,6 +70,7 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   if(req.method==='DELETE'&&(m=/^\/machines\/([^/]+)$/.exec(sub)))return await revokeMachine(api,req,res,auth,m[1],requestId);
   if(req.method==='POST'&&(m=/^\/machines\/([^/]+)\/heartbeat$/.exec(sub)))return await heartbeat(api,req,res,auth,m[1],requestId);
   if(req.method==='GET'&&(m=/^\/machines\/([^/]+)\/configuration$/.exec(sub)))return await machineConfiguration(api,res,auth,m[1],requestId);
+  if((m=/^\/machines\/([^/]+)\/publications(?:\/([^/]+))?$/.exec(sub)))return await publicationRoute({api,req,res,auth,machineId:m[1],publicationId:m[2],url,requestId,parseJson,exact,fail,send,result,guardedMutation});
   if((m=/^\/machines\/([^/]+)\/access(?:\/([^/]+))?$/.exec(sub)))return await machineGrantRoute({api,req,res,auth,machineId:m[1],grantId:m[2],url,requestId,parseJson,exact,fail,send,result,guardedMutation,requireRevision});
   if(req.method==='POST'&&sub==='/sources')return await createSource(api,req,res,auth,requestId);
   if(req.method==='GET'&&sub==='/sources')return await listSources(api,res,auth,url,requestId);
@@ -135,7 +137,7 @@ async function createInvitation(api,req,res,auth,requestId){if(!isAdmin(auth))fa
 async function acceptInvite(api,res,body,requestId){exact(body,['enrollment_code','access_token']);
   // Accepted with an identity service's token, the new member is linked to it from the start.
   const person=body.access_token===undefined?null:await identityOf(api,body.access_token);if(body.access_token!==undefined&&!person)fail(401,'authentication_required','the identity token did not verify');const digest=hashToken(body.enrollment_code??'');const inv=await api.store.one('SELECT i.*,p.display_name,t.name team_name,t.revision team_revision FROM invitations i JOIN principals p ON p.id=i.principal_id JOIN teams t ON t.id=i.team_id WHERE i.secret_hash=?',[digest]),now=api.clock.nowMs();if(!inv||inv.consumed_at!=null||inv.revoked_at!=null||inv.expires_at<=now)fail(401,'authentication_required','invalid invitation');const cid=api.ids.next('credential'),token=makeToken(cid);await api.store.guardedTransaction([{sql:'SELECT 1 ok FROM invitations WHERE id=? AND consumed_at IS NULL AND revoked_at IS NULL AND expires_at>?',params:[inv.id,now],code:'authentication_required',status:401,message:'invalid invitation'}],[{sql:'UPDATE invitations SET consumed_at=? WHERE id=?',params:[now,inv.id]},{sql:'INSERT INTO memberships(team_id,principal_id,role) VALUES (?,?,?)',params:[inv.team_id,inv.principal_id,inv.role]},...(person?[{sql:'INSERT INTO principal_identities(issuer,subject,principal_id,linked_at) VALUES (?,?,?,?)',params:[person.issuer,person.subject,inv.principal_id,now]}]:[]),{sql:'INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,?,?,?,?)',params:[cid,hashToken(token),inv.principal_id,'user',null,now+2592000000,now]},{sql:'UPDATE teams SET auth_epoch=auth_epoch+1 WHERE id=?',params:[inv.team_id]}]);send(res,201,{principal:{id:inv.principal_id,kind:'user',display_name:inv.display_name},credential:{token,kind:'user',expires_at:now+2592000000},team:{id:inv.team_id,name:inv.team_name,revision:inv.team_revision}},requestId);}
-async function removeMember(api,req,res,auth,pid,requestId){if(!isAdmin(auth))fail(403,'forbidden','forbidden');const target=await api.store.one('SELECT * FROM memberships WHERE team_id=? AND principal_id=? AND active=1',[auth.team_id,pid]);if(!target)fail(404,'not_found','not found');requireRevision(req,target.revision,'membership');if(target.role==='owner'&&auth.role!=='owner')fail(403,'forbidden','only owners may remove owners');const now=api.clock.nowMs(),guards=[...authGuards(auth,now),{sql:"SELECT 1 ok FROM memberships WHERE team_id=? AND principal_id=? AND active=1 AND revision=? AND (role!='owner' OR (SELECT count(*) FROM memberships WHERE team_id=? AND role='owner' AND active=1)>1)",params:[auth.team_id,pid,target.revision,auth.team_id],code:'conflict',status:409,message:'membership changed or last owner would be removed'}],statements=[{sql:'UPDATE memberships SET active=0,revision=revision+1 WHERE team_id=? AND principal_id=?',params:[auth.team_id,pid]},{sql:'UPDATE credentials SET revoked_at=? WHERE team_id=? AND principal_id=?',params:[now,auth.team_id,pid]},{sql:"UPDATE sources SET state='paused',revision=revision+1 WHERE team_id=? AND custodian_id=? AND state='active'",params:[auth.team_id,pid]},{sql:'UPDATE teams SET auth_epoch=auth_epoch+1 WHERE id=?',params:[auth.team_id]}];await guardedMutation(api,res,auth,guards,statements,{status:204,body:null,targetId:pid});api.events.publish(auth.team_id,{type:'authorization_changed',principal_id:pid});closeChannelsFor(api,auth.team_id,{principalId:pid,reason:'membership_removed'});send(res,204,null,requestId);}
+async function removeMember(api,req,res,auth,pid,requestId){if(!isAdmin(auth))fail(403,'forbidden','forbidden');const target=await api.store.one('SELECT * FROM memberships WHERE team_id=? AND principal_id=? AND active=1',[auth.team_id,pid]);if(!target)fail(404,'not_found','not found');requireRevision(req,target.revision,'membership');if(target.role==='owner'&&auth.role!=='owner')fail(403,'forbidden','only owners may remove owners');const published=publisherRevocation(api,auth.team_id,pid),now=api.clock.nowMs(),guards=[...authGuards(auth,now),{sql:"SELECT 1 ok FROM memberships WHERE team_id=? AND principal_id=? AND active=1 AND revision=? AND (role!='owner' OR (SELECT count(*) FROM memberships WHERE team_id=? AND role='owner' AND active=1)>1)",params:[auth.team_id,pid,target.revision,auth.team_id],code:'conflict',status:409,message:'membership changed or last owner would be removed'}],statements=[{sql:'UPDATE memberships SET active=0,revision=revision+1 WHERE team_id=? AND principal_id=?',params:[auth.team_id,pid]},{sql:'UPDATE credentials SET revoked_at=? WHERE team_id=? AND principal_id=?',params:[now,auth.team_id,pid]},{sql:"UPDATE sources SET state='paused',revision=revision+1 WHERE team_id=? AND custodian_id=? AND state='active'",params:[auth.team_id,pid]},{sql:'UPDATE teams SET auth_epoch=auth_epoch+1 WHERE id=?',params:[auth.team_id]},published.statement];await guardedMutation(api,res,auth,guards,statements,{status:204,body:null,targetId:pid});api.events.publish(auth.team_id,{type:'authorization_changed',principal_id:pid});closeChannelsFor(api,auth.team_id,{principalId:pid,reason:'membership_removed'});await published.closeChannels();send(res,204,null,requestId);}
 /** Federation (P02): a verified identity token is a member's sign-in, answered with the same 30-day credential an invitation gives. */
 async function identityLogin(api,res,body,requestId){
   exact(body,['access_token','team_id']);if(body.team_id!==undefined&&typeof body.team_id!=='string')fail(400,'invalid_request','team_id must be a string');

package/server/machine-link.mjs

@@ -11,11 +11,13 @@
 // 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.
+// A delegated caller (./delegated.mjs) holds no Teams credential: its verified token, when it names exactly a surface
+// the machine's custodian published to that workplace (./publications.mjs), becomes one machine grant on that target
+// and the caps the token names, expiring with the token; its channel closes then, or when the surface is unpublished.
 import { Channel } from '../channel.mjs';
 import { bearer } from './auth.mjs';
 import { delegatedAccessOf, delegatedPrincipal, looksDelegated } from './delegated.mjs';
+import { delegatedGrantIssuer, publicationFor } from './publications.mjs';
 
 const LINK_PROTOCOL = 'supercode-machine-link.v1';
 const CHANNEL_PROTOCOL = 'supercode-machine-channel.v1';
@@ -172,20 +174,46 @@ 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. */
+/**
+ * A delegated token's channel: its grant, minted now on exactly the published surface the token names, or the same
+ * refusal as no machine. A token for a surface nobody published here (or one since unpublished) opens nothing.
+ */
 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 } };
+  const publication = await publicationFor(api, access);
+  if (!publication) return { status: 404, code: 'not_found', message: 'machine not found' };
+  const now = api.clock.nowMs(), id = api.ids.next('grant'), principal = delegatedPrincipal(access), issuer = delegatedGrantIssuer(access.issuer, publication.id);
+  try {
+    // The publication, and its publisher's standing, must still hold as the grant is written: an unpublish or a
+    // member removal racing this open wins.
+    await api.store.guardedTransaction([
+      { sql: 'SELECT 1 ok FROM machine_publications p JOIN machines m ON m.team_id=p.team_id AND m.id=p.machine_id AND m.custodian_id=p.publisher_id JOIN memberships mem ON mem.team_id=p.team_id AND mem.principal_id=p.publisher_id AND mem.active=1 WHERE p.team_id=? AND p.id=?', params: [teamId, publication.id], code: 'not_found', status: 404, message: 'machine not found' },
+      { sql: 'SELECT 1 ok FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', params: [teamId, machineId], code: 'not_found', status: 404, message: 'machine not found' },
+    ], [
+      // 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([publication.target]), issuer, now, access.expiresAt] },
+    ]);
+  } catch (error) {
+    if (error.code === 'not_found') return { status: 404, code: 'not_found', message: 'machine not found' };
+    throw error;
+  }
+  return { door: 'channel', teamId, machineId, auth: { kind: 'delegated', team_id: teamId, principal_id: principal, group_ids: [], grant_id: id, grant_issuer: issuer, expires_at: access.expiresAt } };
+}
+
+/** Close every delegated channel whose grant came from one publication (issuer from delegatedGrantIssuer): it was unpublished. */
+export function closeDelegatedChannels(api, teamId, machineId, grantIssuer, reason = 'unpublished') {
+  let closed = 0;
+  for (const entry of channels(api)) {
+    if (entry.teamId !== teamId || entry.machineId !== machineId || entry.grantIssuer !== grantIssuer) continue;
+    entry.close(reason);
+    closed += 1;
+  }
+  return closed;
 }
 
 /**
@@ -235,7 +263,7 @@ async function acceptChannel(api, auth, machineId, duplex, closeSocket) {
   } catch { closeSocket('refused'); return; }
   const open = new Set();
   const entry = {
-    teamId: auth.team_id, machineId, principal: auth.principal_id, claim: null,
+    teamId: auth.team_id, machineId, principal: auth.principal_id, claim: null, grantIssuer: auth.grant_issuer ?? null,
     close: (reason) => closeSocket(reason),
     dropStreams: (reason) => { for (const pair of open) pair.close(reason); },
   };

package/server/migrations/005.mjs

@@ -0,0 +1,11 @@
+// Schema migration 005 (SQLite DDL), applied in order by store-core migrate().
+export default `-- Schema 5: a session's owner lets one workplace Room's Conversation view it (a session
+-- view, RH2 ADR 0008). A token that workplace signs for that Room and Conversation reads
+-- the session; nothing else reaches it through the token.
+CREATE TABLE session_view_bindings (
+  team_id TEXT NOT NULL, session_id TEXT NOT NULL, issuer TEXT NOT NULL, room TEXT NOT NULL,
+  conversation TEXT NOT NULL, bound_by TEXT NOT NULL, created_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id, session_id, issuer, room, conversation),
+  FOREIGN KEY(team_id, session_id) REFERENCES sessions(team_id, id)
+) STRICT;
+`;

package/server/migrations/006.mjs

@@ -0,0 +1,17 @@
+// Schema migration 006 (SQLite DDL), applied in order by store-core migrate().
+export default `-- Schema 6: published surfaces (delegated access, server/publications.mjs). A machine's
+-- custodian publishes one pane or one folder of it into one workplace Room; a delegated token
+-- that workplace signs opens exactly a surface published here, and nothing else. Unpublishing
+-- deletes the row, the delegated grants minted on it, and closes their channels.
+CREATE TABLE machine_publications (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, machine_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('pane','folder')), target TEXT NOT NULL,
+  workplace TEXT NOT NULL, room TEXT NOT NULL, surface_key TEXT,
+  publisher_id TEXT NOT NULL, created_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,id), UNIQUE(team_id,machine_id,target,workplace,room)
+) STRICT;
+CREATE INDEX machine_publications_target ON machine_publications(team_id,machine_id,target,workplace);
+-- Delegated grants minted before publications (issuer delegated:<host>, any target, any lifetime) go: each
+-- grant now names its publication (delegated:<host>/<publication id>).
+DELETE FROM machine_grants WHERE issuer_id LIKE 'delegated:%' AND instr(issuer_id,'/')=0;
+`;

package/server/migrations/index.mjs

@@ -3,4 +3,6 @@ import m001 from './001.mjs';
 import m002 from './002.mjs';
 import m003 from './003.mjs';
 import m004 from './004.mjs';
-export const MIGRATIONS = [m001, m002, m003, m004];
+import m005 from './005.mjs';
+import m006 from './006.mjs';
+export const MIGRATIONS = [m001, m002, m003, m004, m005, m006];

package/server/publications.mjs

@@ -0,0 +1,107 @@
+// Published surfaces: what a delegated token (./delegated.mjs) may open.
+//
+//   /api/v1/teams/{team}/machines/{id}/publications[/{publication}]   list, publish, unpublish
+//
+// A workplace signs delegated tokens, but it is not the authority over a machine: the machine's custodian is. So a
+// token opens a pane or a folder only when the custodian published exactly that surface here, to that workplace
+// (the token's issuer) and, when the token names one, that Room. `teams publish` records the surface here before it
+// puts it into the workplace; `teams unpublish` deletes it here first, which also deletes every delegated grant minted
+// on it and closes their channels, so a token the workplace already signed stops working at once.
+import { closeDelegatedChannels } from './machine-link.mjs';
+
+/** The one target a surface may name: an exact pane, or an exact, normalized, non-root absolute folder. Never a wildcard. */
+export function publishableTarget(kind, target) {
+  if (typeof target !== 'string' || target.length > 4101 || /[\x00-\x1f*]/.test(target)) return false;
+  if (kind === 'pane') return /^pane:\S{1,1024}$/.test(target);
+  if (kind === 'folder') {
+    if (!target.startsWith('root:/') || target === 'root:/' || target.endsWith('/')) return false;
+    return target.slice(6).split('/').every((segment) => segment && segment !== '.' && segment !== '..');
+  }
+  return false;
+}
+
+const originOf = (text) => { try { const url = new URL(text); return (url.protocol === 'https:' || url.protocol === 'http:') && url.origin === text ? text : null; } catch { return null; } };
+const json = (row) => ({ id: row.id, machine_id: row.machine_id, kind: row.kind, target: row.target, workplace: row.workplace, room: row.room, surface_key: row.surface_key, publisher_id: row.publisher_id, created_at: row.created_at });
+/** The grant issuer a delegated grant minted on one publication carries, so unpublishing finds exactly those grants. */
+export const delegatedGrantIssuer = (issuer, publicationId) => `delegated:${new URL(issuer).host}/${publicationId}`;
+
+/**
+ * What removing a member withdraws from the surfaces they published (the rows stay, inert: publicationFor admits none
+ * while the publisher is not an active member): a statement, for the removal's own transaction, deleting the delegated
+ * grants minted on any of their publications, one published a moment ago included; and closeChannels(), to call once
+ * the removal is committed, closing those grants' live channels.
+ */
+export const publisherRevocation = (api, teamId, principalId) => ({
+  statement: { sql: "DELETE FROM machine_grants WHERE team_id=? AND issuer_id LIKE 'delegated:%/%' AND substr(issuer_id, instr(issuer_id,'/')+1) IN (SELECT id FROM machine_publications WHERE team_id=? AND publisher_id=?)", params: [teamId, teamId, principalId] },
+  closeChannels: async () => {
+    const rows = await api.store.query('SELECT id, machine_id, workplace FROM machine_publications WHERE team_id=? AND publisher_id=?', [teamId, principalId]);
+    for (const row of rows) closeDelegatedChannels(api, teamId, row.machine_id, delegatedGrantIssuer(row.workplace, row.id), 'membership_removed');
+  },
+});
+
+/**
+ * The publication a verified delegated access (delegatedAccessOf) opens, or null: same team, machine, surface kind and
+ * exact target, published to the token's issuer and to the token's Room, by the machine's current custodian while
+ * still an active member of the team (a publication does not outlive its publisher's standing).
+ */
+export async function publicationFor(api, access) {
+  if (typeof access.room !== 'string' || !access.room) return null;
+  return await api.store.one(
+    'SELECT p.* FROM machine_publications p JOIN machines m ON m.team_id=p.team_id AND m.id=p.machine_id AND m.revoked_at IS NULL AND m.custodian_id=p.publisher_id JOIN memberships mem ON mem.team_id=p.team_id AND mem.principal_id=p.publisher_id AND mem.active=1 WHERE p.team_id=? AND p.machine_id=? AND p.kind=? AND p.target=? AND p.workplace=? AND p.room=? ORDER BY p.id LIMIT 1',
+    [access.teamId, access.machineId, access.kind, access.target, access.issuer, access.room],
+  ) ?? null;
+}
+
+export async function publicationRoute({ api, req, res, auth, machineId, publicationId, url, requestId, parseJson, exact, fail, send, result, guardedMutation }) {
+  if (!['user', 'service'].includes(auth.kind)) fail(403, 'forbidden', 'user or service credential required');
+  const machine = await api.store.one('SELECT * FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', [auth.team_id, machineId]);
+  const custodian = machine?.custodian_id === auth.principal_id;
+  const admin = auth.active && (auth.role === 'owner' || auth.role === 'admin');
+  // Publishing opens the machine to people outside the team: only its custodian does it. An admin may see and withdraw.
+  if (!machine || (!custodian && !admin)) fail(404, 'not_found', 'machine not found');
+  const context = { server_id: api.serverId, team_id: auth.team_id, principal_id: auth.principal_id };
+  if (req.method === 'GET') {
+    if (publicationId) {
+      const row = await api.store.one('SELECT * FROM machine_publications WHERE team_id=? AND machine_id=? AND id=?', [auth.team_id, machineId, publicationId]);
+      if (!row) fail(404, 'not_found', 'publication not found');
+      return send(res, 200, result(api, auth, json(row)), requestId);
+    }
+    if ([...url.searchParams].length) fail(400, 'invalid_request', 'publications take no query parameters');
+    const rows = await api.store.query('SELECT * FROM machine_publications WHERE team_id=? AND machine_id=? ORDER BY id', [auth.team_id, machineId]);
+    return send(res, 200, { version: 1, context, items: rows.map(json), next_cursor: null }, requestId);
+  }
+  if (req.method === 'POST' && !publicationId) {
+    if (!custodian) fail(403, 'forbidden', "only the machine's custodian publishes its panes and folders");
+    const body = await parseJson(req); exact(body, ['kind', 'target', 'workplace', 'room', 'surface_key']);
+    if (body.kind !== 'pane' && body.kind !== 'folder') fail(400, 'invalid_request', 'kind must be pane or folder');
+    if (!publishableTarget(body.kind, body.target)) fail(400, 'invalid_request', body.kind === 'pane' ? 'target must be one pane, pane:<key> (no wildcard)' : 'target must be one absolute folder, root:/path (not root:/, no wildcard, normalized)');
+    const workplace = typeof body.workplace === 'string' ? originOf(body.workplace) : null;
+    if (!workplace) fail(400, 'invalid_request', 'workplace must be an origin (https://host)');
+    if (workplace !== api.delegatedIssuer) fail(400, 'invalid_request', `this server does not trust ${workplace} as a delegated issuer`);
+    if (typeof body.room !== 'string' || !body.room || body.room.length > 256) fail(400, 'invalid_request', 'room must name the workplace Room');
+    if (body.surface_key !== undefined && (typeof body.surface_key !== 'string' || !body.surface_key || body.surface_key.length > 256)) fail(400, 'invalid_request', 'surface_key must be a non-empty string');
+    const existing = await api.store.one('SELECT * FROM machine_publications WHERE team_id=? AND machine_id=? AND target=? AND workplace=? AND room=?', [auth.team_id, machineId, body.target, workplace, body.room]);
+    // Publishing the same surface again answers the record already there.
+    if (existing && existing.kind === body.kind) return send(res, 200, result(api, auth, json(existing)), requestId);
+    if (existing) fail(409, 'conflict', 'that target is already published as another kind');
+    const now = api.clock.nowMs(), id = api.ids.next('publication');
+    const row = { id, machine_id: machineId, kind: body.kind, target: body.target, workplace, room: body.room, surface_key: body.surface_key ?? null, publisher_id: auth.principal_id, created_at: now };
+    const response = result(api, auth, json(row));
+    await guardedMutation(api, res, auth, [{ sql: 'SELECT 1 ok FROM machines WHERE team_id=? AND id=? AND custodian_id=? AND revoked_at IS NULL', params: [auth.team_id, machineId, auth.principal_id], code: 'not_found', status: 404, message: 'machine not found' }], [
+      { sql: 'INSERT INTO machine_publications(team_id,id,machine_id,kind,target,workplace,room,surface_key,publisher_id,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)', params: [auth.team_id, id, machineId, row.kind, row.target, row.workplace, row.room, row.surface_key, row.publisher_id, now] },
+    ], { status: 201, body: response, targetId: id });
+    return send(res, 201, response, requestId);
+  }
+  if (req.method === 'DELETE' && publicationId) {
+    const row = await api.store.one('SELECT * FROM machine_publications WHERE team_id=? AND machine_id=? AND id=?', [auth.team_id, machineId, publicationId]);
+    if (!row) fail(404, 'not_found', 'publication not found');
+    const issuer = delegatedGrantIssuer(row.workplace, row.id);
+    await guardedMutation(api, res, auth, [], [
+      { sql: 'DELETE FROM machine_publications WHERE team_id=? AND id=?', params: [auth.team_id, row.id] },
+      { sql: 'DELETE FROM machine_grants WHERE team_id=? AND machine_id=? AND issuer_id=?', params: [auth.team_id, machineId, issuer] },
+    ], { status: 204, body: null, targetId: row.id });
+    closeDelegatedChannels(api, auth.team_id, machineId, issuer);
+    return send(res, 204, null, requestId);
+  }
+  fail(405, 'not_found', 'method not allowed');
+}