@volter/teams 0.2.43 → 0.2.45

package/browser-channel.d.ts

@@ -15,6 +15,12 @@ export interface BrowserStream extends ChannelEvents {
   close(reason?: string | null): void;
 }
 
+/** The node's request/reply doors over an admitted stream. */
+export class StreamRpc {
+  constructor(stream: BrowserStream);
+  call<T = unknown>(method: string, params?: Record<string, unknown>, options?: { timeoutMs?: number }): Promise<T>;
+}
+
 /** A browser's channel to one machine, through its Teams server. Events: `hello` (the machine's greeting), `close`. */
 export declare class BrowserChannel implements ChannelEvents {
   constructor(socket: WebSocket);

package/browser-channel.mjs

@@ -3,6 +3,7 @@
 // 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.
+export { StreamRpc } from './stream-rpc.mjs';
 const PROTOCOL = 'supercode-machine/1';
 const NODE_PROTOCOL = 2;
 const CHANNEL_PROTOCOL = 'supercode-machine-channel.v1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.2.43",
+  "version": "0.2.45",
   "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/redact.mjs

@@ -134,23 +134,29 @@ const anyKeyword = new RegExp([...new Set(RULES.flatMap((rule) => rule.keywords)
 const CUSTODY_LOOK_MS = 30_000;
 let custodyCache = null, custodyStamp = null, custodyLookedAt = 0;
 const stampOf = (file) => { try { const s = statSync(file); return `${s.ino}:${s.size}:${s.mtimeMs}`; } catch { return '-'; } };
-function custodyFiles(env) {
+const custodyUnreadable=()=>Object.assign(new Error('a declared custody file or its registry could not be read; capture transfer refused'),{code:'custody_unreadable'});
+function custodyFiles(env, fresh) {
   const home = env.SUPERCODE_HOME || join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode');
   let files = String(env.SUPERCODE_CUSTODY_FILES ?? '').split(delimiter).filter(Boolean);
-  try { files = files.concat(JSON.parse(readFileSync(join(home, 'custody.json'), 'utf8')).files ?? []); } catch { /* none named */ }
+  try {
+    const named=JSON.parse(readFileSync(join(home, 'custody.json'), 'utf8')).files??[];
+    if(fresh&&(!Array.isArray(named)||named.some(file=>typeof file!=='string')))throw custodyUnreadable();
+    files=files.concat(named);
+  } catch(error) { if(fresh&&error?.code!=='ENOENT')throw custodyUnreadable(); }
   return { files, stamp: [join(home, 'custody.json'), ...files].map(stampOf).join('|') };
 }
-/** Each custody value (at least 8 characters) with the variable that holds it, longest first. */
-export function custodyValues(env = process.env) {
+/** Each custody value (at least 8 characters) with the variable that holds it, longest first. `fresh` bypasses both
+ * the interval and stat memo and refuses unreadable declared files or a malformed/unreadable registry. */
+export function custodyValues(env = process.env, { fresh = false } = {}) {
   const now = Date.now();
-  if (custodyCache && now - custodyLookedAt < CUSTODY_LOOK_MS) return custodyCache;
+  if (!fresh && custodyCache && now - custodyLookedAt < CUSTODY_LOOK_MS) return custodyCache;
   custodyLookedAt = now;
-  const { files, stamp } = custodyFiles(env);
-  if (custodyCache && stamp === custodyStamp) return custodyCache;
+  const { files, stamp } = custodyFiles(env, fresh);
+  if (!fresh && custodyCache && stamp === custodyStamp) return custodyCache;
   custodyStamp = stamp;
   const values = new Map();
   for (const file of files) {
-    let text = ''; try { if (existsSync(file)) text = readFileSync(file, 'utf8'); } catch { continue; }
+    let text = ''; try { if (fresh||existsSync(file)) text = readFileSync(file, 'utf8'); } catch { if(fresh)throw custodyUnreadable();continue; }
     for (const line of text.split('\n')) {
       const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
       if (!m) continue;
@@ -169,10 +175,10 @@ export function custodyValues(env = process.env) {
 let custodyBasis = null;
 /** What a redaction was made under (the rule set and the custody values), as a digest: text found clean under one
  * basis is clean under it again, and needs another look only when it changes. */
-export function redactionBasis(env = process.env) { custodyValues(env); return custodyBasis; }
+export function redactionBasis(env = process.env, options) { custodyValues(env, options); return custodyBasis; }
 /** One custody observation and its basis, for a batch that must not change policy between its values. */
-export function redactionSnapshot(env = process.env) {
-  const values = custodyValues(env);
+export function redactionSnapshot(env = process.env, options) {
+  const values = custodyValues(env, options);
   return { values, basis: custodyBasis };
 }
 

package/server/apps.mjs

@@ -15,7 +15,7 @@ export const APP_ACTIONS = Object.freeze([
   'teams.read', 'members.read', 'members.write', 'groups.read', 'groups.write',
   'sessions.read', 'sessions.write', 'sessions.control', 'sessions.access',
   'machines.read', 'machines.control', 'machines.write', 'machines.access', 'sources.read', 'sources.write',
-  'identity.login', 'delegation.surfaces', 'delegation.sessions', 'delegation.notices',
+  'identity.login', 'delegation.surfaces', 'delegation.sessions', 'delegation.notices', 'delegation.machines',
   'events.read', 'events.publish',
 ]);
 const TOKEN_MS = 90 * 86400000, CODE_MS = 10 * 60000, DELEGATION_MS = 15 * 60000;

package/server/delegated.mjs

@@ -109,6 +109,19 @@ export async function delegatedSessionOf(api, token) {
   return { installationId:claims.installation_id, installedAt:claims.installed_at, roomContext, conversation: claims.conversation, expiresAt: claims.exp * 1000, issuer: claims.iss, name, room: claims.room, scope: claims.scope, sessionRef: session.id, subject: claims.sub, teamId: session.team };
 }
 
+/**
+ * Who a workplace's principal is, to work on a machine its custodian granted them (RH2's machine token: a rented machine,
+ * RH2 RFC 0017 §4), or null: { subject, issuer, teamId, machineId, expiresAt }. It grants nothing itself: the channel
+ * opens only on a live `operate` grant the machine's custodian gave that delegated principal (machine-link.mjs).
+ */
+export async function delegatedMachineOf(api, token) {
+  const claims = await verifiedClaims(api, token, 'delegation.machines');
+  if (!claims || claims.scope !== 'operate' || typeof claims.machine?.team !== 'string' || typeof claims.machine?.id !== 'string') return null;
+  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;
+  return { installationId: claims.installation_id, installedAt: claims.installed_at, expiresAt: claims.exp * 1000, issuer: claims.iss, machineId: claims.machine.id, subject: claims.sub, teamId: claims.machine.team };
+}
+
 /** A signed Room lifecycle notice. This scope grants no transcript read or user-turn control. */
 export async function delegatedRoomNoticeOf(api, token) {
   const c = await verifiedClaims(api, token, 'delegation.notices');
@@ -135,7 +148,7 @@ async function verifiedClaims(api, token, action) {
     // Only installed issuer origins may select keys; an untrusted claim never triggers a fetch.
     // Cache by issuer as well as kid so staging cannot reuse a production key identifier.
     const claims = json(body);
-    const teamId=claims.surface?.config?.team??claims.session?.team;
+    const teamId=claims.surface?.config?.team??claims.session?.team??claims.machine?.team;
     if(typeof teamId!=='string'||claims.aud!==api.publicOrigin)return null;
     const installation=await installedIssuer(api,claims.iss,action,teamId);if(!installation||!Number.isFinite(claims.iat)||claims.iat<Math.floor(installation.created_at/1000))return null;
     const key = await issuerKey(api, claims.iss, header.kid);

package/server/machine-link.mjs

@@ -1,4 +1,4 @@
-import { appAuthentication } from './apps.mjs';
+import { appAuthentication, installedIssuer } from './apps.mjs';
 // Machine doors through the server (design §11).
 //
 //   GET  /api/v1/teams/{team}/machines/{id}/link     the machine's one outbound link
@@ -22,7 +22,7 @@ import { machineGrantProblem } from '../admission.mjs';
 import { lineSplitter } from '../lines.mjs';
 import { APP_LINEAGE, APP_LINEAGE_REVOKED, bearer } from './auth.mjs';
 import { AGENT_ACTIVE } from './agent-authority.mjs';
-import { delegatedAccessOf, delegatedPrincipal, delegatedSessionOf, looksDelegated, surfaceCaps } from './delegated.mjs';
+import { delegatedAccessOf, delegatedMachineOf, delegatedPrincipal, delegatedSessionOf, looksDelegated, surfaceCaps } from './delegated.mjs';
 import { delegatedGrantIssuer, publicationFor } from './publications.mjs';
 
 const LINK_PROTOCOL = 'supercode-machine-link.v1';
@@ -83,7 +83,12 @@ export async function agentMachineClaim(api, auth, machineId) {
 /** What the caller may claim on the machine right now, or null (indistinguishable from no machine). */
 async function claimFor(api, auth, machineId) {
   if (auth.agent_credential) return agentMachineClaim(api, auth, machineId);
-  if(auth.installation_id&&auth.kind!=='delegated'&&!await appAuthentication(api,auth))return null;
+  if(auth.installation_id&&auth.kind!=='delegated'&&auth.kind!=='delegated-machine'&&!await appAuthentication(api,auth))return null;
+  // A workplace principal on a machine its custodian granted them: exactly that grant, while it lasts.
+  if (auth.kind === 'delegated-machine') {
+    const row = await api.store.one('SELECT id, revision FROM machine_grants WHERE team_id=? AND machine_id=? AND id=? AND subject_id=? AND expires_at>?', [auth.team_id, machineId, auth.grant_id, auth.principal_id, api.clock.nowMs()]);
+    return row ? { principal: auth.principal_id, groups: [], grants: [row.id], revisions: { [row.id]: row.revision } } : null;
+  }
   if (auth.kind === 'delegated') {
     const row = await api.store.one(`SELECT g.id,g.revision FROM machine_grants g JOIN app_installations i ON i.id=g.app_installation_id JOIN apps a ON a.id=i.app_id
       JOIN memberships installer ON installer.team_id=i.team_id AND installer.principal_id=i.installer_id
@@ -183,8 +188,12 @@ export async function machineGrantRoute({ api, req, res, auth, machineId, grantI
     const body = await parseJson(req); exact(body, ['subject_id', 'caps', 'targets', 'expires_at']);
     const now = api.clock.nowMs();
     const subject = typeof body.subject_id === 'string' ? await api.store.one(`SELECT p.kind FROM memberships m JOIN principals p ON p.id=m.principal_id WHERE m.team_id=? AND m.principal_id=? AND m.active=1 UNION ALL SELECT 'group' kind FROM groups_table WHERE team_id=? AND id=?`, [auth.team_id, body.subject_id, auth.team_id, body.subject_id]) : null;
-    if (!subject) fail(400, 'invalid_request', 'subject must be an active member, service account or group of this team');
-    const problem = machineGrantProblem({ ...body, created_at: now }, { agent: subject.kind === 'agent', lifetime: true, now });
+    // A workplace's principal (a run's agent that rented the machine, RH2 RFC 0017 §4), named as the workplace names it to
+    // this server: only a workplace this team installed to name principals on machines (`delegation.machines`).
+    const delegated = !subject && typeof body.subject_id === 'string' ? /^delegated:([^:]+):(.+)$/.exec(body.subject_id) : null;
+    const workplace = delegated ? (await installedIssuer(api, `https://${delegated[1]}`, 'delegation.machines', auth.team_id)) ?? (await installedIssuer(api, `http://${delegated[1]}`, 'delegation.machines', auth.team_id)) : null;
+    if (!subject && !workplace) fail(400, 'invalid_request', 'subject must be an active member, service account or group of this team, or a principal of a workplace it installed for machines');
+    const problem = machineGrantProblem({ ...body, created_at: now }, { agent: subject?.kind === 'agent', lifetime: true, now });
     if (problem) fail(400, 'invalid_request', problem);
     const id = api.ids.next('grant');
     const row = { id, machine_id: machineId, subject_id: body.subject_id, caps: body.caps, targets: body.targets, issuer_id: auth.principal_id, created_at: now, expires_at: body.expires_at, revision: 1 };
@@ -267,7 +276,7 @@ const ACCESS_ENDED = { status: 403, code: 'access_revoked', message: 'the workpl
 
 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) return await delegatedMachineChannel(api, teamId, machineId, token);
   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' };
@@ -294,6 +303,27 @@ async function delegatedChannel(api, teamId, machineId, token) {
   return { door: 'channel', teamId, machineId, auth: { kind: 'delegated', installation_id:access.installationId, team_id: teamId, principal_id: principal, group_ids: [], grant_id: id, grant_issuer: issuer, expires_at: access.expiresAt, issuer: access.issuer, token } };
 }
 
+/**
+ * A workplace principal on a machine its custodian granted them (a rented machine, RH2 RFC 0017 §4: "`operate` on a
+ * machine in the seller's supercode Team, granted to the run agent's RH2-issued identity"). The token only says who they
+ * are; what they may do is the custodian's own grant to that delegated principal (`delegated:<issuer host>:<subject>`),
+ * for as long as it lasts, and the workplace is asked whether it still admits them before the open and while the channel
+ * lives. No such grant is no machine.
+ */
+async function delegatedMachineChannel(api, teamId, machineId, token) {
+  const access = await delegatedMachineOf(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 principal = delegatedPrincipal(access);
+  const grant = await api.store.one(`SELECT g.id, g.expires_at FROM machine_grants g JOIN machines m ON m.team_id=g.team_id AND m.id=g.machine_id AND m.revoked_at IS NULL
+      WHERE g.team_id=? AND g.machine_id=? AND g.subject_id=? AND g.expires_at>? AND g.issuer_id NOT LIKE 'delegated:%' ORDER BY g.expires_at DESC LIMIT 1`, [teamId, machineId, principal, api.clock.nowMs()]);
+  if (!grant) return { status: 404, code: 'not_found', message: 'machine not found' };
+  try { await api.store.guardedTransaction([installedGuard(access, 'delegation.machines')], []); }
+  catch (error) { if (error.code === 'not_found') return { status: 404, code: 'not_found', message: 'machine not found' }; throw error; }
+  if (await delegatedStillAdmits({ issuer: access.issuer, token }) === false) return ACCESS_ENDED;
+  return { door: 'channel', teamId, machineId, auth: { kind: 'delegated-machine', installation_id: access.installationId, team_id: teamId, principal_id: principal, group_ids: [], grant_id: grant.id, expires_at: Number(grant.expires_at), issuer: access.issuer, token } };
+}
+
 /**
  * A session-view token's channel (RH2 ADR 0008): the member's own browser types a turn into one session its owner
  * bound to the token's Room and Conversation. Both scopes can observe its mail; only `control` can interact with that
@@ -536,7 +566,7 @@ async function acceptChannel(api, auth, machineId, duplex, closeSocket) {
   };
   channels(api).add(entry);
   // A delegated channel ends when its token does; the viewer reopens it with a fresh one.
-  const expiry = (auth.kind === 'delegated'||auth.agent_credential||(auth.installation_id&&auth.expires_at-api.clock.nowMs()<=2147483647)) ? setTimeout(() => entry.close('token_expired'), Math.max(0, auth.expires_at - api.clock.nowMs())) : null;
+  const expiry = (auth.kind === 'delegated'||auth.kind === 'delegated-machine'||auth.agent_credential||(auth.installation_id&&auth.expires_at-api.clock.nowMs()<=2147483647)) ? setTimeout(() => entry.close('token_expired'), Math.min(2147483647, Math.max(0, auth.expires_at - api.clock.nowMs()))) : null;
   const armGrantExpiry = claim => {
     if (!Number.isSafeInteger(claim.expires_at) || claim.expires_at >= grantDeadline) return;
     grantDeadline = claim.expires_at;
@@ -550,9 +580,10 @@ async function acceptChannel(api, auth, machineId, duplex, closeSocket) {
     .catch(() => entry.close('access_unknown')), 5000) : null;
   // It also ends when the workplace stops admitting the access the token was issued for (a binding revoked, a Task
   // closed, a contract ended): an act already under way ends with its access, and the grant goes with it.
-  const recheck = auth.kind === 'delegated' && auth.token ? setInterval(() => void delegatedStillAdmits(auth).then(async (live) => {
+  const recheck = (auth.kind === 'delegated' || auth.kind === 'delegated-machine') && auth.token ? setInterval(() => void delegatedStillAdmits(auth).then(async (live) => {
     if (live !== false) return;
-    await api.store.transaction([{ sql: 'DELETE FROM machine_grants WHERE team_id=? AND id=?', params: [auth.team_id, auth.grant_id] }]).catch(() => {});
+    // A delegated grant goes with its access; a custodian's own grant (a rented machine's) is the custodian's to revoke.
+    if (auth.kind === 'delegated') await api.store.transaction([{ sql: 'DELETE FROM machine_grants WHERE team_id=? AND id=?', params: [auth.team_id, auth.grant_id] }]).catch(() => {});
     entry.close('access_revoked');
   }), DELEGATED_RECHECK_MS) : null;
   channel.on('error', () => {});

package/session-follow.mjs

@@ -167,10 +167,13 @@ const automationImage = seed => `https://brand.volter.ai/bot/svg?seed=${encodeUR
  * A Room member's words, without the envelope Teams types ahead of them into the session ('[Room "<name>" ("room_…");
  * sender "<name>" ("prn_…")] ' then the words). Only that exact quote is taken off, and only when the sender it names is
  * the principal recorded as typing the turn; any other text, a forged or quoted envelope included, is shown as typed.
+ * A member who typed through their Room's delegated token is recorded as `delegated:<issuer host>:<principal>`
+ * (delegatedPrincipal), which is that same sender.
  */
 function roomWords(text, principal) {
   const m = /^\s*\[Room "(?:[^"\\]|\\.)*" \("room_[A-Za-z0-9]+"\); sender "(?:[^"\\]|\\.)*" \("(prn_[A-Za-z0-9]+)"\)\]\s*/.exec(String(text ?? ''));
-  return m && principal && m[1] === principal ? String(text).slice(m[0].length) : text;
+  const typist = typeof principal === 'string' && principal.startsWith('delegated:') ? principal.slice(principal.lastIndexOf(':') + 1) : principal;
+  return m && typist && m[1] === typist ? String(text).slice(m[0].length) : text;
 }
 
 export function withPeople(transcript, messages, { agentName = null, sessionId = '', personImage: person = personImage, agentImage: agent = agentImage, locale = [] } = {}) {