@volter/supercode-teams 0.2.28 → 0.2.29

package/README.md

@@ -49,15 +49,28 @@ A workplace can open one pane or one folder for someone who is not a member of t
 server started with `--delegated-issuer ORIGIN` (the Worker's `DELEGATED_ISSUER`) trusts short-lived
 tokens that issuer signs (Ed25519, keys at `ORIGIN/.well-known/jwks.json`, audience this server's
 public origin), each naming a pane (`pane:<key>`) or a folder (`root:/path`) on one machine of one
-team, and `view` or `control`. The hosted viewer at `/view#token=…` opens it; the server turns the
-token into a machine grant on exactly that target (a pane: `observe`, and `control` to type; a
-folder: `observe` to read, `files` to change) that expires with the token, and closes the channel
-then. A page embedding the viewer sends it a fresh token by `postMessage({ type: 'delegated-token',
-token })`, which the viewer asks for with `delegated-token-needed`.
-
-`teams publish` puts a pane or a folder of the connected machine (or `--machine NAME`) into a
-workplace Room as a Surface, through the workplace's own door with a session token of yours;
-`teams unpublish SURFACE` retires it:
+team, and `view` or `control`. A token opens only a surface the machine's custodian **published** on
+this server (the machine's publications, `/machines/{id}/publications`): the same team, machine and
+exact target, published to that workplace and to the Room the token names, by the machine's current
+custodian while still an active member of the team. A token naming no Room, or one for
+anything else, for a wildcard (`pane:*`) or for the whole filesystem (`root:/`) opens nothing, and a
+token must carry `iat` and live at most 15 minutes (`exp - iat` and `exp - now`). The hosted viewer
+at `/view#token=…` opens it; the server turns the token into a machine grant on exactly that target
+(a pane: `observe`, and `control` to type; a folder: `observe` to read, `files` to change) that
+expires with the token, and closes the channel then. A page embedding the viewer sends it a fresh
+token by `postMessage({ type: 'delegated-token', token })`, which the viewer asks for with
+`delegated-token-needed`.
+
+`teams publish` records the surface on this server (only the machine's custodian can), then puts
+the pane or folder of the connected machine (or `--machine NAME`) into a workplace Room as a
+Surface, through the workplace's own door with a session token of yours; if the workplace refuses,
+the record is withdrawn. `teams unpublish SURFACE` (the surface key or the publication id)
+deletes this server's record first, on whichever of your machines holds it, which deletes the
+grants minted on it and closes their channels at once, then retires it in the workplace. It fails
+when this server holds no such record, unless `--workplace-only`; `--record-only` deletes the
+record here without a workplace call or token. Removing a member likewise ends every delegated
+grant on the surfaces they published. A surface published before this server kept records opens nothing until its custodian
+records it with `teams publish … --record-only` (no workplace call, no workplace token):
 
 ```sh
 supercode teams publish pane <ctx> --room room_… --workplace https://pilot.runhuman.com --organization acme --token-stdin

package/bin/workspace/args.mjs

@@ -1,7 +1,7 @@
 const BOOLEANS = new Set([
   'json', 'help', 'live', 'saved', 'watch', 'paginate', 'token-stdin',
   'invite-stdin', 'include-children', 'rotate', 'install', 'force',
-  'take-control', 'dry-run', 'volter', 'foreground', 'no-connect',
+  'take-control', 'dry-run', 'volter', 'foreground', 'no-connect', 'record-only', 'workplace-only',
 ]);
 
 const VALUES = new Set([

package/bin/workspace.mjs

@@ -575,8 +575,10 @@ async function machinesCommand(sub, { flags, rest, output, client, context, team
     const machine = reference.startsWith('mach_') ? reference : await resolveName((await team.machines.list()).items, reference, item => item.name, item => item.id, 'machine');
     const machineBase = teamPath(context, `/machines/${machine}/access`), liveBase = teamPath(context, `/machines/${machine}/grants`);
     if (action === 'list') {
-      const [machineGrants, liveGrants] = await Promise.all([client.request('GET', machineBase), client.request('GET', liveBase)]);
-      return output({ version: 1, context: scope(context), data: { machine_grants: machineGrants.items, live_grants: liveGrants.items } });
+      // A team owner or admin manages a machine's grants; its live session grants are its custodian's alone, so
+      // for anyone else that half is not found and the machine grants still answer.
+      const [machineGrants, liveGrants] = await Promise.all([client.request('GET', machineBase), client.request('GET', liveBase).catch(error => { if (error.code === 'not_found') return null; throw error; })]);
+      return output({ version: 1, context: scope(context), data: { machine_grants: machineGrants.items, live_grants: liveGrants?.items ?? null } });
     }
     if (action === 'revoke') {
       if (!flags.grant) usage('--grant is required');
@@ -745,40 +747,77 @@ async function connectorCommand(verb, { flags, rest, output, client, context, te
 /**
  * PUBLISH: one pane or folder of a machine of this team, put into a workplace Room as a Surface (RH2's Surface
  * door). The workplace decides who in the Room may see or drive it and signs them delegated tokens; this server
- * admits those if it was started with that workplace as its delegated issuer (server/delegated.mjs). The machine is
- * the one `teams connect` enrolled here, or `--machine NAME`. The workplace credential is a session token, from
- * --token-stdin or WORKPLACE_TOKEN. `unpublish SURFACE` retires it.
+ * admits those if it was started with that workplace as its delegated issuer (server/delegated.mjs), and only for a
+ * surface its custodian published: so `publish` first records the surface on this server (the machine's
+ * publications, server/publications.mjs), then puts it into the workplace, and withdraws the record if the workplace
+ * refuses. `--record-only` records it here without touching the workplace (a surface put there before this server kept
+ * records). The machine is the one `teams connect` enrolled here, or `--machine NAME`. The workplace credential is a
+ * session token, from --token-stdin or WORKPLACE_TOKEN. `unpublish SURFACE` (the surface key, or the publication id)
+ * deletes this server's record first, on whichever of the caller's machines holds it (every token for it stops working
+ * at once), then retires it in the workplace; it fails when this server holds no such record, unless
+ * `--workplace-only`. `unpublish --record-only` deletes the record here and leaves the workplace alone.
  */
-async function publishCommand(verb, sub, { flags, rest, output, context, team, home, env }) {
-  only(flags, ['json', 'help', 'context', 'room', 'workplace', 'organization', 'name', 'key', 'machine', 'token_stdin']);
-  if (!flags.room || !flags.workplace || !flags.organization) usage(`teams ${verb} needs --room ROOM --workplace ORIGIN --organization ORG`);
+async function publishCommand(verb, sub, { flags, rest, output, context, team, client, home, env }) {
+  only(flags, ['json', 'help', 'context', 'room', 'workplace', 'organization', 'name', 'key', 'machine', 'token_stdin', 'record_only', 'workplace_only']);
+  const recordOnly = Boolean(flags.record_only);
+  if (!flags.room || !flags.workplace || (!recordOnly && !flags.organization)) usage(`teams ${verb} needs --room ROOM --workplace ORIGIN --organization ORG`);
   const workplace = new URL(flags.workplace).origin;
-  const token = flags.token_stdin ? readFileSync(0, 'utf8').trim() : env.WORKPLACE_TOKEN;
-  if (!token) usage('the workplace credential comes from --token-stdin or WORKPLACE_TOKEN');
+  const token = recordOnly ? null : flags.token_stdin ? readFileSync(0, 'utf8').trim() : env.WORKPLACE_TOKEN;
+  if (!recordOnly && !token) usage('the workplace credential comes from --token-stdin or WORKPLACE_TOKEN');
+  const machine = flags.machine
+    ? resolveName((await team.machines.list()).items ?? [], flags.machine, item => item.name, item => item.id, 'machine')
+    : new WorkspaceContexts(home).connector(context.server_id, context.team_id).read()?.machine?.id;
+  if (!machine && verb === 'publish') usage('this machine is not connected to the team: run teams connect, or name --machine');
+  const publicationsOf = (id) => teamPath(context, `/machines/${encodeURIComponent(id)}/publications`);
+  const publications = machine ? publicationsOf(machine) : null;
+  const recorded = async () => (await client.request('GET', publications)).items ?? [];
   const roomPath = `${workplace}/api/v3/rooms/${encodeURIComponent(flags.room)}/surfaces`;
-  let url, body;
+  const workplaceCall = async (url, body) => {
+    const response = await fetch(url, { body: JSON.stringify(body), headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', origin: workplace, 'x-rh2-organization': String(flags.organization) }, method: 'POST' });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) throw Object.assign(new Error(payload?.error?.message ?? `the workplace answered ${response.status}`), { code: response.status === 403 || response.status === 404 ? 'forbidden' : response.status === 401 ? 'authentication_required' : 'invalid_request' });
+    return payload;
+  };
   if (verb === 'unpublish') {
-    requireArgs([sub, ...rest].filter(Boolean), 1, 1, 'teams unpublish SURFACE --room ROOM --workplace ORIGIN --organization ORG');
-    url = `${roomPath}/${encodeURIComponent(sub)}/retire`; body = {};
-  } else {
-    if (sub !== 'pane' && sub !== 'root') usage('teams publish pane CONTEXT_KEY|root PATH --room ROOM --workplace ORIGIN --organization ORG [--name NAME] [--key KEY] [--machine NAME]');
-    requireArgs(rest, 1, 1, `teams publish ${sub}`);
-    const machine = flags.machine
-      ? resolveName((await team.machines.list()).items ?? [], flags.machine, item => item.name, item => item.id, 'machine')
-      : new WorkspaceContexts(home).connector(context.server_id, context.team_id).read()?.machine?.id;
-    if (!machine) usage('this machine is not connected to the team: run teams connect, or name --machine');
-    // A folder on this machine is its real path; on another machine, the path as given there.
-    const target = sub === 'pane' ? `pane:${rest[0]}` : `root:${flags.machine ? rest[0] : realpathSync(resolve(rest[0]))}`;
-    if (sub === 'root' && !target.startsWith('root:/')) usage('a folder on another machine is named by its absolute path');
-    const label = sub === 'pane' ? rest[0] : basename(target.slice(5)) || 'root';
-    const key = flags.key ?? `${sub === 'pane' ? 'pane' : 'folder'}-${label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || createHash('sha256').update(target).digest('hex').slice(0, 8)}`;
-    url = roomPath;
-    body = { config: { machine, target, team: context.team_id, teamsUrl: new URL(context.origin).origin }, key, kind: sub === 'pane' ? 'pane' : 'folder', name: flags.name ?? label };
-  }
-  const response = await fetch(url, { body: JSON.stringify(body), headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', origin: workplace, 'x-rh2-organization': String(flags.organization) }, method: 'POST' });
-  const payload = await response.json().catch(() => null);
-  if (!response.ok) throw Object.assign(new Error(payload?.error?.message ?? `the workplace answered ${response.status}`), { code: response.status === 403 || response.status === 404 ? 'forbidden' : response.status === 401 ? 'authentication_required' : 'invalid_request' });
-  return output({ version: 1, context: scope(context), data: payload?.data ?? null });
+    requireArgs([sub, ...rest].filter(Boolean), 1, 1, 'teams unpublish SURFACE --room ROOM --workplace ORIGIN --organization ORG [--machine NAME] [--record-only|--workplace-only]');
+    // This server's record goes first: the moment it does, no delegated token opens the surface, whatever the workplace
+    // does next. Named --machine, only that machine; otherwise every machine of the team this caller may read the
+    // publications of (its own; all of them for an admin).
+    const machineIds = flags.machine ? [machine] : ((await team.machines.list()).items ?? []).map(item => item.id);
+    const matching = [];
+    for (const id of machineIds) {
+      let items;
+      try { items = (await client.request('GET', publicationsOf(id))).items ?? []; } catch (error) { if (flags.machine || !['forbidden', 'not_found'].includes(error?.code)) throw error; continue; }
+      for (const item of items) if (item.workplace === workplace && item.room === flags.room && (item.surface_key === sub || item.id === sub)) matching.push(item);
+    }
+    if (new Set(matching.map(item => item.machine_id)).size > 1) usage(`${sub} is published from more than one machine: name the publication id, or --machine`);
+    if (!matching.length && !flags.workplace_only) throw Object.assign(new Error(`this server holds no publication ${sub} for that Room and workplace (name the publication id, or --machine; --workplace-only retires it in the workplace alone)`), { code: 'not_found' });
+    for (const item of matching) await client.request('DELETE', `${publicationsOf(item.machine_id)}/${encodeURIComponent(item.id)}`);
+    if (recordOnly) return output({ version: 1, context: scope(context), data: { revoked: matching.map(item => item.id) } });
+    const payload = await workplaceCall(`${roomPath}/${encodeURIComponent(sub)}/retire`, {});
+    return output({ version: 1, context: scope(context), data: { ...(payload?.data && typeof payload.data === 'object' ? payload.data : {}), revoked: matching.map(item => item.id) } });
+  }
+  if (sub !== 'pane' && sub !== 'root') usage('teams publish pane CONTEXT_KEY|root PATH --room ROOM --workplace ORIGIN --organization ORG [--name NAME] [--key KEY] [--machine NAME] [--record-only]');
+  requireArgs(rest, 1, 1, `teams publish ${sub}`);
+  // A folder on this machine is its real path; on another machine, the path as given there.
+  const target = sub === 'pane' ? `pane:${rest[0]}` : `root:${flags.machine ? rest[0] : realpathSync(resolve(rest[0]))}`;
+  if (sub === 'root' && !target.startsWith('root:/')) usage('a folder on another machine is named by its absolute path');
+  if (sub === 'root' && target === 'root:/') usage('publish a folder, not the whole filesystem');
+  const label = sub === 'pane' ? rest[0] : basename(target.slice(5)) || 'root';
+  const key = flags.key ?? `${sub === 'pane' ? 'pane' : 'folder'}-${label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || createHash('sha256').update(target).digest('hex').slice(0, 8)}`;
+  const kind = sub === 'pane' ? 'pane' : 'folder';
+  const existed = (await recorded()).some(item => item.target === target && item.workplace === workplace && item.room === flags.room);
+  const publication = (await client.request('POST', publications, { body: { kind, target, workplace, room: flags.room, surface_key: key } })).data;
+  if (recordOnly) return output({ version: 1, context: scope(context), data: { publication } });
+  let payload;
+  try {
+    payload = await workplaceCall(roomPath, { config: { machine, target, team: context.team_id, teamsUrl: new URL(context.origin).origin }, key, kind, name: flags.name ?? label });
+  } catch (error) {
+    // Nothing is left published here that the workplace does not show.
+    if (!existed) await client.request('DELETE', `${publications}/${encodeURIComponent(publication.id)}`).catch(() => {});
+    throw error;
+  }
+  return output({ version: 1, context: scope(context), data: payload?.data && typeof payload.data === 'object' ? { ...payload.data, publication } : { surface: payload?.data ?? null, publication } });
 }
 
 async function listQuery(flags, { client, context, team }) {
@@ -874,8 +913,8 @@ function printHelp() {
   login [ORIGIN] [--team TEAM] [--as CONTEXT] [--token-stdin|--invite-stdin]   (Volter sign-in in the browser by default)
   identity link
   server start [--volter-issuer ORIGIN] [--delegated-issuer ORIGIN]
-  publish pane|root TARGET --room ROOM --workplace ORIGIN --organization ORG [--name] [--key] [--machine] [--token-stdin]
-  unpublish SURFACE --room ROOM --workplace ORIGIN --organization ORG [--token-stdin]
+  publish pane|root TARGET --room ROOM --workplace ORIGIN --organization ORG [--name] [--key] [--machine] [--token-stdin] [--record-only]
+  unpublish SURFACE --room ROOM --workplace ORIGIN --organization ORG [--machine] [--token-stdin] [--record-only|--workplace-only]
   connect|disconnect|status
   members invite|list|remove|role
   groups list|create|remove|add-member|remove-member

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-teams",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "type": "module",
   "description": "A machine daemon serving this machine's doors, and a local or remote Teams server for shared session discovery, OpenTelemetry ingestion and access to enrolled machines.",
   "license": "MIT",
@@ -53,9 +53,7 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "typecheck:teams": "tsc --noEmit -p test/tsconfig.json"
-  },
+  "scripts": {},
   "dependencies": {
     "@homebridge/node-pty-prebuilt-multiarch": "^0.14.1",
     "@volter/supercode-frontend": "^0.2.2",