@volter/teams 0.1.52 → 0.1.54

package/machine-core.mjs

@@ -75,6 +75,8 @@ export class MachineCore extends EventEmitter {
 
   /** Before the local door opens: a product's own setup. */
   async beforeListen() {}
+  /** The socket is published; product workers may now use its local doors. */
+  async afterListen() {}
   /** 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. */
@@ -94,6 +96,7 @@ export class MachineCore extends EventEmitter {
       await this.afterStop().catch(() => {});
       throw error;
     }
+    await this.afterListen();
     if (this.link) {
       await this.refreshLinkConfiguration().catch((error) => this.emit('link', { event: 'configuration-failed', error: error.message }));
       this.#connectLink();
@@ -435,14 +438,22 @@ export class MachineCore extends EventEmitter {
 const SOCKET_WATCH_MS = 5_000;
 
 async function clearStaleSocket(path) {
-  // A named pipe has no file to leave behind: only a live daemon holds its name.
-  if (!isNamedPipe(path) && !existsSync(path)) return;
-  const live = await new Promise((done) => {
+  // Only a refused connection proves stale. A timeout or permission failure
+  // does not authorize deleting a potentially live daemon's socket.
+  let inode;
+  if (!isNamedPipe(path)) {
+    try { inode = statSync(path).ino; } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  }
+  const live = await new Promise((done, reject) => {
     const probe = netConnect(path);
-    probe.once('connect', () => { probe.destroy(); done(true); });
-    probe.once('error', () => done(false));
+    const finish = (error, value) => { probe.destroy(); error ? reject(error) : done(value); };
+    probe.setTimeout(1000, () => finish(Object.assign(new Error(`machine socket did not answer: ${path}`), { code: 'ETIMEDOUT' })));
+    probe.once('connect', () => finish(null, true));
+    probe.once('error', error => ['ECONNREFUSED', 'ENOENT'].includes(error.code) ? finish(null, false) : finish(error));
   });
   if (live) throw Object.assign(new Error(`a machine daemon is already serving ${path}`), { code: 'EADDRINUSE' });
-  if (!isNamedPipe(path)) rmSync(path, { force: true });
+  if (!isNamedPipe(path)) {
+    try { if (statSync(path).ino === inode) rmSync(path); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "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/core.mjs

@@ -1,3 +1,4 @@
+import { reconcileMachinePresence } from './machine-events.mjs';
 // The Teams server, independent of its host. `createTeamsApi` builds the API
 // object every route and door reads; a host attaches a store (`api.attach`),
 // bootstraps the server identity once, serves requests through http.mjs's
@@ -58,6 +59,7 @@ export async function bootstrapServer(api,{initTeam,bootstrap}){
 
 /** Expire cursors, idempotency records, staged captures and uploads, and old journal rows. */
 export async function maintain(api){const now=api.clock.nowMs();
+  await reconcileMachinePresence(api);
   // Replay records expire after a day; keeping them forever can fill the object and stop heartbeats.
   // Delete them before any retention step that may update a surviving version.
   const expired=await api.store.query('SELECT rowid FROM idempotency WHERE expires_at<=? LIMIT 1000',[now]);

package/server/delegated.mjs

@@ -106,6 +106,22 @@ export async function delegatedSessionOf(api, token) {
   return { 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 };
 }
 
+/** 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);
+  if (!c || c.scope !== 'room-notice' || !c.session || c.sub !== c.session.agent) return null;
+  const n = c.notice;
+  if (![c.room, c.conversation, c.session.team, c.session.id, c.session.harness].every(v => typeof v === 'string' && v.length > 0 && v.length <= 256)) return null;
+  if (!n || !['joined', 'member-joined', 'member-left', 'left'].includes(n.kind)
+      || typeof n.id !== 'string' || !/^[a-zA-Z0-9:_-]{1,200}$/.test(n.id)
+      || typeof n.text !== 'string' || !n.text.trim() || n.text.length > 16000) return null;
+  const now = Math.floor(api.clock.nowMs() / 1000);
+  if (!Number.isFinite(c.iat) || c.exp - c.iat > SESSION_TOKEN_MAX_S || c.exp - now > SESSION_TOKEN_MAX_S) return null;
+  return { conversation: c.conversation, expiresAt: c.exp * 1000, issuer: c.iss, room: c.room,
+    roomName: typeof c.roomName === 'string' ? c.roomName.slice(0, 120) : c.room,
+    sessionRef: c.session.id, harness: c.session.harness, subject: c.sub, teamId: c.session.team, notice: n };
+}
+
 /** 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;

package/server/http.mjs

@@ -1,3 +1,4 @@
+import { machineEventStream } from './machine-events.mjs';
 import { randomBytes } from 'node:crypto';
 import { bearer, hashToken, canManage, isAdmin, makeToken } from './auth.mjs';
 import { ContractError, canonicalJson, validationFailure, cursorHash, cursorToken, sha256 } from './wire.mjs';
@@ -48,7 +49,7 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   if(auth.kind==='user'&&auth.team_id===null){const membership=await api.store.one('SELECT role,active FROM memberships WHERE team_id=? AND principal_id=?',[teamId,auth.principal_id]);if(!membership?.active)fail(401,'authentication_required','authentication required');auth.role=membership.role;auth.active=membership.active;auth.team_id=teamId;auth.group_ids=(await api.store.query('SELECT group_id FROM group_members WHERE team_id=? AND principal_id=?',[teamId,auth.principal_id])).map(x=>x.group_id);}else if(auth.team_id!==teamId||!auth.active)fail(401,'authentication_required','authentication required');
   if(req.method!=='GET')res._auditRecord={teamId:auth.team_id,actorId:auth.principal_id,operation:`${req.method} ${path}`};
   if(['machine','ingest'].includes(auth.kind)){
-    const machineDoor=auth.kind==='machine'&&(/^\/machines\/[^/]+\/configuration$/.test(sub)||sub===`/machines/${auth.machine_id}/heartbeat`||sub.startsWith(`/machines/${auth.machine_id}/effects`)||new RegExp(`^/machines/${auth.machine_id}/attachments/[^/]+(?:/frames)?$`).test(sub));
+    const machineDoor=auth.kind==='machine'&&(sub==='/machines/events'||/^\/machines\/[^/]+\/configuration$/.test(sub)||sub===`/machines/${auth.machine_id}/heartbeat`||sub.startsWith(`/machines/${auth.machine_id}/effects`)||new RegExp(`^/machines/${auth.machine_id}/attachments/[^/]+(?:/frames)?$`).test(sub));
     const sourceDoor=sub.startsWith(`/sources/${auth.source_id}/captures`)||sub.startsWith(`/sources/${auth.source_id}/uploads`);
     if(!machineDoor&&!sourceDoor)fail(403,'forbidden','credential kind cannot use this operation');
   }
@@ -66,6 +67,7 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   if(req.method==='DELETE'&&(m=/^\/groups\/([^/]+)$/.exec(sub)))return await groupRoute(api,req,res,auth,m[1],null,url,requestId);
   if((req.method==='PUT'||req.method==='DELETE')&&(m=/^\/groups\/([^/]+)\/members\/([^/]+)$/.exec(sub)))return await groupRoute(api,req,res,auth,m[1],m[2],url,requestId);
   if(req.method==='POST'&&sub==='/machines')return await enroll(api,req,res,auth,requestId);
+  if(req.method==='GET'&&sub==='/machines/events')return await machineEventStream({api,req,res,auth,url,requestId,fail});
   if(req.method==='GET'&&sub==='/machines')return await machineAdminRoute(api,req,res,auth,null,false,requestId);
   if(req.method==='GET'&&(m=/^\/machines\/([^/]+)$/.exec(sub)))return await machineAdminRoute(api,req,res,auth,m[1],false,requestId);
   if(req.method==='GET'&&(m=/^\/machines\/([^/]+)\/roots$/.exec(sub)))return await machineAdminRoute(api,req,res,auth,m[1],true,requestId);

package/server/machine-events.mjs

@@ -0,0 +1,73 @@
+// A retained transition log, shared by mailbox subscriptions and board supervision.
+import { writeSse } from './events.mjs';
+
+export function machineTransition(api, team, machine, linked) {
+  // Serialize the read/change/event across asynchronous store calls. A replaced
+  // link remains linked; only the current link's close records a departure.
+  const next = (api.machineTransitionWork ?? Promise.resolve()).then(async () => {
+    const row = await api.store.one('SELECT name,revoked_at FROM machines WHERE team_id=? AND id=?', [team, machine]);
+    if (!row) return;
+    const present = linked ?? api.machineLinks?.has(`${team}\0${machine}`);
+    const value = present && row.revoked_at == null ? 1 : 0;
+    const before = await api.store.one('SELECT linked FROM machine_presence WHERE team_id=? AND machine_id=?', [team, machine]);
+    if (before?.linked === value) return;
+    const at = api.clock.nowMs();
+    await api.store.transaction([
+      { sql: 'INSERT INTO machine_presence VALUES (?,?,?,?,?) ON CONFLICT(team_id,machine_id) DO UPDATE SET name=excluded.name,linked=excluded.linked,changed_at=excluded.changed_at', params: [team,machine,row.name,value,at] },
+      { sql: 'INSERT INTO machine_presence_events(team_id,machine_id,name,linked,created_at) VALUES (?,?,?,?,?)', params: [team,machine,row.name,value,at] },
+    ]);
+    api.events.publish(team, { type: 'machine_transition' });
+  });
+  api.machineTransitionWork = next.catch(error => { console.error(`machine transition ${machine}: ${error.message}`); });
+  return next;
+}
+
+export async function reconcileMachinePresence(api) {
+  await api.machineTransitionWork;
+  for(const id of api.machineLinks?.keys()??[]){const [team,machine]=id.split('\0');await machineTransition(api,team,machine,null);}
+  const rows = await api.store.query('SELECT team_id,machine_id FROM machine_presence WHERE linked=1');
+  for (const row of rows) if (!api.machineLinks?.has(`${row.team_id}\0${row.machine_id}`)) await machineTransition(api,row.team_id,row.machine_id,null);
+  const before=api.clock.nowMs()-7*86400000;
+  await api.store.transaction([
+    {sql:'INSERT INTO machine_presence_cursors SELECT team_id,MAX(sequence) FROM machine_presence_events WHERE created_at<? GROUP BY team_id ON CONFLICT(team_id) DO UPDATE SET pruned_through=MAX(pruned_through,excluded.pruned_through)',params:[before]},
+    {sql:'DELETE FROM machine_presence_events WHERE created_at<?',params:[before]},
+  ]);
+}
+
+export async function machineEventStream({api,req,res,auth,url,requestId,fail}) {
+  const after = url.searchParams.get('after') ?? req.headers['last-event-id'];
+  if (after != null && (!/^\d+$/.test(after) || !Number.isSafeInteger(Number(after)))) fail(400,'invalid_request','after must be a machine event cursor');
+  const count = api.openStreams.get(auth.credential_id) ?? 0;
+  if (count >= 10) fail(429,'rate_limited','too many open streams');
+  api.openStreams.set(auth.credential_id,count+1);
+  let closed=false, cursor=after==null?null:Number(after), work=Promise.resolve();
+  const close=()=>{ if(closed)return;closed=true;clearInterval(timer);unsubscribe();req.off('close',close);api.events.off('shutdown',close);api.openStreams.set(auth.credential_id,Math.max(0,(api.openStreams.get(auth.credential_id)??1)-1));res.end(); };
+  const write=event=>{if(closed)return;if(res.writableLength>1024*1024){close();return;}writeSse(res,event);};
+  const drain=async()=>{
+    if(closed)return;
+    const credential=await api.store.one('SELECT 1 ok FROM credentials c JOIN memberships m ON m.team_id=? AND m.principal_id=c.principal_id WHERE c.id=? AND c.revoked_at IS NULL AND (c.expires_at IS NULL OR c.expires_at>?) AND m.active=1',[auth.team_id,auth.credential_id,api.clock.nowMs()]);
+    if(!credential){write({type:'access_revoked'});close();return;}
+    await api.machineTransitionWork;
+    const bounds=await api.store.one('SELECT COALESCE((SELECT MAX(sequence) FROM machine_presence_events WHERE team_id=?),(SELECT pruned_through FROM machine_presence_cursors WHERE team_id=?),0) last,COALESCE((SELECT pruned_through FROM machine_presence_cursors WHERE team_id=?),0) floor',[auth.team_id,auth.team_id,auth.team_id]);
+    if(cursor===null || cursor>(bounds.last??0) || cursor<bounds.floor) {
+      const snapshot=await api.store.snapshot([
+        {kind:'one',sql:'SELECT COALESCE((SELECT MAX(sequence) FROM machine_presence_events WHERE team_id=?),(SELECT pruned_through FROM machine_presence_cursors WHERE team_id=?),0) cursor',params:[auth.team_id,auth.team_id]},
+        {kind:'query',sql:'SELECT m.id,m.name,COALESCE(p.linked,0) linked,p.changed_at FROM machines m LEFT JOIN machine_presence p ON p.team_id=m.team_id AND p.machine_id=m.id WHERE m.team_id=? AND m.revoked_at IS NULL ORDER BY m.id',params:[auth.team_id]},
+      ]);
+      const reset=cursor!==null;cursor=snapshot[0].cursor??0;
+      write({type:'machine_snapshot',cursor:String(cursor),reset,items:snapshot[1]});
+    }
+    for (;;) {
+      const rows=await api.store.query('SELECT * FROM machine_presence_events WHERE team_id=? AND sequence>? ORDER BY sequence LIMIT 256',[auth.team_id,cursor]);
+      for(const row of rows){cursor=row.sequence;write({type:row.linked?'machine_linked':'machine_unlinked',cursor:String(cursor),machine_id:row.machine_id,name:row.name,at:row.created_at});}
+      if(rows.length<256||closed)break;
+    }
+  };
+  const enqueue=()=>{work=work.then(drain).catch(error=>{console.error(`machine events: ${error.message}`);close();});return work;};
+  const unsubscribe=api.events.subscribe(`team:${auth.team_id}`,event=>{if(['machine_transition','authorization_changed'].includes(event.type))void enqueue();});
+  const timer=setInterval(()=>{void enqueue().then(()=>{if(!closed)res.write(': heartbeat\n\n');});},15000);timer.unref?.();
+  req.once('close',close);api.events.once('shutdown',close);
+  res.writeHead(200,{'Content-Type':'text/event-stream','Cache-Control':'no-store','X-Request-ID':requestId});
+  await enqueue();
+  write({type:'machine_ready',cursor:String(cursor)});
+}

package/server/machine-link.mjs

@@ -14,6 +14,7 @@
 // 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 { machineTransition } from './machine-events.mjs';
 import { randomUUID } from 'node:crypto';
 import { Channel } from '../channel.mjs';
 import { bearer } from './auth.mjs';
@@ -298,9 +299,12 @@ async function acceptLink(api, teamId, machineId, duplex, closeSocket) {
   const link = { channel, close: (reason) => closeSocket(reason) };
   links(api).set(id, link);
   previous?.close('replaced');
+  void machineTransition(api,teamId,machineId,true).catch(() => {});
   channel.on('error', () => {});
   channel.on('close', () => {
-    if (links(api).get(id) === link) links(api).delete(id);
+    if (links(api).get(id) !== link) return;
+    links(api).delete(id);
+    void machineTransition(api,teamId,machineId,false).catch(() => {});
     // A caller's open streams ride this link; they end with it, and the caller reopens.
     for (const entry of channels(api)) if (entry.teamId === teamId && entry.machineId === machineId) entry.dropStreams('machine_offline');
   });
@@ -372,3 +376,40 @@ async function acceptChannel(api, auth, machineId, duplex, closeSocket) {
     upstream.on('close', (reason) => { open.delete(pair); if (!stream.closed) stream.close(reason); });
   });
 }
+
+/** Deliver only signed lifecycle text to an exact owner-bound session, through durable native mail.
+ * The native --id receipt survives reconnects and server restarts; retry never invents a new id.
+ */
+export async function deliverSessionRoomNotice(api, access) {
+  const target = await boundSessionTarget(api, access.teamId, access);
+  if (!target || target.harness !== access.harness) throw Object.assign(new Error('session not found'), { status: 404, code: 'not_found' });
+  const machine = await api.store.one('SELECT name FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', [access.teamId, target.machineId]);
+  if (!machine) throw Object.assign(new Error('machine not found'), { status: 404, code: 'not_found' });
+  const machineName = String(machine.name).split('.')[0].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+  const to = `sc:${machineName}:${target.harness}:${target.nativeId}`;
+  const identity = JSON.stringify([access.issuer, access.room, access.conversation, target.sessionId, access.notice.id]);
+  const digest = [...new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(identity)))].map(v => v.toString(16).padStart(2, '0')).join('');
+  const pending = api.roomNoticeDeliveries ??= new Map();
+  if (pending.has(digest)) return pending.get(digest);
+  const delivery = (async () => {
+    const id = api.ids.next('grant'), principal = delegatedPrincipal(access), now = api.clock.nowMs();
+    await api.store.transaction([{ sql: 'INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at) VALUES (?,?,?,?,?,?,?,?,?)',
+      params: [access.teamId, id, target.machineId, principal, JSON.stringify(['mail']), JSON.stringify([`mail:${to}`]), `delegated:room-notice:${digest}`, now, access.expiresAt] }]);
+    try {
+      const link = await linkWithin(api, key(access.teamId, target.machineId), LINK_WAIT_MS);
+      if (!link) throw new Error('machine offline; Room notice remains pending');
+      const stream = await link.channel.open('mail', { _admitted: { principal, groups: [], grants: [id], revisions: { [id]: 1 } },
+        request: { op: 'send', from: `sc:${machineName}:operator:room-${digest.slice(0, 24)}`, from_name: `Room ${access.roomName}`,
+          to, body: access.notice.text, id: `room-notice:${digest}`, queue: false } });
+      return await new Promise((resolve, reject) => {
+        let text = '';
+        const timeout = setTimeout(() => { stream.close('timeout'); reject(new Error('Room notice delivery not confirmed')); }, 15000);
+        stream.on('data', bytes => { text += new TextDecoder().decode(bytes); });
+        stream.on('close', () => { clearTimeout(timeout); try { const result = JSON.parse(text); if (result.code !== 0) throw new Error(result.text ?? 'Room notice refused'); resolve({ delivered: true, noticeId: access.notice.id }); } catch (error) { reject(error); } });
+        stream.on('error', error => { clearTimeout(timeout); reject(error); });
+      });
+    } finally { await api.store.transaction([{ sql: 'DELETE FROM machine_grants WHERE team_id=? AND id=?', params: [access.teamId, id] }]); }
+  })();
+  pending.set(digest, delivery);
+  try { return await delivery; } finally { pending.delete(digest); }
+}

package/server/migrations/010.mjs

@@ -0,0 +1,14 @@
+export default `
+CREATE TABLE machine_presence (
+  team_id TEXT NOT NULL, machine_id TEXT NOT NULL, name TEXT NOT NULL,
+  linked INTEGER NOT NULL, changed_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,machine_id)
+);
+CREATE TABLE machine_presence_events (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT, team_id TEXT NOT NULL,
+  machine_id TEXT NOT NULL, name TEXT NOT NULL, linked INTEGER NOT NULL,
+  created_at INTEGER NOT NULL
+);
+CREATE TABLE machine_presence_cursors (team_id TEXT PRIMARY KEY, pruned_through INTEGER NOT NULL);
+CREATE INDEX machine_presence_events_team ON machine_presence_events(team_id,sequence);
+`;

package/server/migrations/index.mjs

@@ -8,7 +8,8 @@ import m006 from './006.mjs';
 import m007 from './007.mjs';
 import m008 from './008.mjs';
 import m009 from './009.mjs';
-export const MIGRATIONS = [m001, m002, m003, m004, m005, m006, m007, m008, m009];
+import m010 from './010.mjs';
+export const MIGRATIONS = [m001, m002, m003, m004, m005, m006, m007, m008, m009, m010];
 /** A message row's `until_revision` while its session's current version still holds it (schema 9). */
 export const OPEN_REVISION = Number.MAX_SAFE_INTEGER;
 /** SQL: message row `m` belongs to the version at revision ?1 (bind the revision twice). */