@volter/teams 0.2.7 → 0.2.9

package/http-client.mjs

@@ -1,11 +1,24 @@
 const trimOrigin=value=>{const u=new URL(value),loopback=u.hostname==='localhost'||u.hostname==='::1'||u.hostname==='[::1]'||/^127(?:\.\d{1,3}){3}$/.test(u.hostname);if(!['http:','https:'].includes(u.protocol)||u.username||u.password||u.search||u.hash||(u.pathname!==''&&u.pathname!=='/')||(u.protocol==='http:'&&!loopback))throw new TypeError('server must be an HTTPS origin (HTTP is loopback-only)');return u.origin;};
 const randomKey=()=>globalThis.crypto.randomUUID().replaceAll('-','')+globalThis.crypto.randomUUID().replaceAll('-','');
+// The caller a request names to the server (X-Supercode-Caller): the process's command words and the agent session it
+// runs in, so the server can say who spent a credential's allowance. Only lowercase command words are kept (never an
+// argument's value); a browser sends none.
+export function callerName(env=globalThis.process?.env,argv=globalThis.process?.argv){
+  if(!env||!argv)return null;
+  // A header value is ASCII: anything else would make every request throw.
+  if(env.SUPERCODE_CALLER_NAME)return String(env.SUPERCODE_CALLER_NAME).replace(/[^\x20-\x7e]/g,'?').slice(0,120);
+  const script=String(argv[1]??'').split(/[\\/]/).pop().replace(/\.[cm]?js$/,'')||'node',words=[];
+  for(const arg of argv.slice(2)){if(arg.startsWith('-'))continue;if(!/^[a-z][a-z0-9-]{0,30}$/.test(arg)||words.length===2)break;words.push(arg);}
+  const session=env.CLAUDE_CODE_SESSION_ID?`claude-code:${env.CLAUDE_CODE_SESSION_ID.slice(0,8)}`:env.CODEX_SESSION_ID?`codex:${env.CODEX_SESSION_ID.slice(0,8)}`:null;
+  return ([script,...words].join(' ')+(session?` in ${session}`:'')).replace(/[^\x20-\x7e]/g,'?').slice(0,120);
+}
+const CALLER=callerName();
 export class TeamsClient {
   constructor({server,credential,fetch:fetchImpl=(...args)=>globalThis.fetch(...args)}){this.server=trimOrigin(server);this.credential=credential;this.fetch=fetchImpl;if(typeof fetchImpl!=='function')throw new TypeError('fetch is required');}
   async request(method,path,{body,signal,idempotencyKey,ifMatch}={}) {
     const key=idempotencyKey??(method==='GET'?null:randomKey());let delay=250,last;
     for(let attempt=0;attempt<5;attempt++) { try {
-      const response=await this.fetch(this.server+path,{method,signal,redirect:'manual',headers:{Accept:'application/json',Authorization:`Bearer ${this.credential}`,...(body!==undefined?{'Content-Type':'application/json'}:{}),...(key?{'Idempotency-Key':key}:{}),...(ifMatch!==undefined?{'If-Match':String(ifMatch)}:{})},body:body===undefined?undefined:JSON.stringify(body)});
+      const response=await this.fetch(this.server+path,{method,signal,redirect:'manual',headers:{Accept:'application/json',Authorization:`Bearer ${this.credential}`,...(CALLER?{'X-Supercode-Caller':CALLER}:{}),...(body!==undefined?{'Content-Type':'application/json'}:{}),...(key?{'Idempotency-Key':key}:{}),...(ifMatch!==undefined?{'If-Match':String(ifMatch)}:{})},body:body===undefined?undefined:JSON.stringify(body)});
       if(response.type==='opaqueredirect'||(response.status>=300&&response.status<400))throw Object.assign(new Error('cross-origin redirects are refused'),{code:'invalid_request',status:400,retryable:false});
       const value=response.status===204?null:await response.json();if(!response.ok)throw Object.assign(new Error(value?.error?.message??`HTTP ${response.status}`),value?.error,{status:response.status});return value;
     } catch(error) { last=error;if(method!=='GET'||signal?.aborted||!(!error.status||error.retryable)||attempt===4)throw error;await retryWait(delay,signal);delay=Math.min(delay*2,5000); } }

package/package.json

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

@@ -20,7 +20,7 @@ export function createTeamsApi({clock=productionClock,ids=productionIds,publicOr
   if(!Number.isSafeInteger(uploadLimitBytes)||uploadLimitBytes<1||uploadLimitBytes>256*1024*1024)throw new TypeError('uploadLimitBytes must be between 1 and 268435456');
   let store=null,serverId=null,localOrigin=null,harnessRoutes=null;
   const events=new TeamEvents();
-  return {clock,ids,events,publicOrigin,appRootSecret,uploadLimitBytes,rateState:new Map(),openStreams:new Map(),securityEvents:[],
+  return {clock,ids,events,publicOrigin,appRootSecret,uploadLimitBytes,rateState:new Map(),rateSpenders:new Map(),rateReported:new Map(),openStreams:new Map(),securityEvents:[],
     get store(){return store;},get serverId(){return serverId;},get localOrigin(){return localOrigin;},get harnessRoutes(){return harnessRoutes;},
     attach(next){store=next.store??store;if(next.serverId!==undefined)serverId=next.serverId;if(next.localOrigin!==undefined)localOrigin=next.localOrigin;if(next.harnessRoutes!==undefined)harnessRoutes=next.harnessRoutes;},
   };

package/server/events.mjs

@@ -1,3 +1,17 @@
 import { EventEmitter } from 'node:events';
 export class TeamEvents extends EventEmitter { publish(teamId,event){this.emit(`team:${teamId}`,event); if(event.session_id)this.emit(`session:${teamId}:${event.session_id}`,event);} subscribe(key,fn){this.on(key,fn);return()=>this.off(key,fn);} close(){this.emit('shutdown');this.removeAllListeners();} }
 export function writeSse(res,event){const cursor=event.cursor??'';res.write(`id: ${cursor}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);}
+// A stream's backlog cap is met by waiting for the response to flush, never by measuring the server's own unflushed bytes:
+// a Durable Object's SQLite answers as microtasks, so a snapshot written in one turn never lets the response drain, and a
+// 1 MiB backlog checked there cut every reader of a large team as slow (217 Task heads, 1,022 KB, with a reader that only
+// counted). Only a reader that takes nothing for the patience window is slow. Resolves 'ready', 'closed' or 'slow'.
+export const SSE_BACKLOG_BYTES=1048576, SSE_PATIENCE_MS=30000;
+export function sseRoom(res,bytes,{cap=SSE_BACKLOG_BYTES,patienceMs=SSE_PATIENCE_MS}={}){
+  // An event larger than the cap still goes out whole once nothing is waiting: a snapshot of any size completes.
+  if(res.writableLength===0||res.writableLength+bytes<=cap)return Promise.resolve('ready');
+  return new Promise(resolve=>{
+    const done=outcome=>{clearTimeout(timer);res.off('drain',drained);res.off('close',ended);resolve(outcome);};
+    const drained=()=>done('ready'),ended=()=>done('closed'),timer=setTimeout(()=>done('slow'),patienceMs);
+    res.on('drain',drained);res.on('close',ended);
+  });
+}

package/server/http.mjs

@@ -33,7 +33,7 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   // Any page may call with a bearer it holds: the only credential is that header, never a
   // cookie, so a caller's origin admits nothing and a preflight is answered before auth.
   for(const [name,value] of Object.entries(CORS))res.setHeader(name,value);
-  if(req.method==='OPTIONS'){res.writeHead(204,{'Access-Control-Allow-Methods':'GET, POST, PATCH, DELETE','Access-Control-Allow-Headers':'Authorization, Content-Type, Idempotency-Key, If-Match, Last-Event-ID, Range','Access-Control-Max-Age':'86400'});res.end();return;}
+  if(req.method==='OPTIONS'){res.writeHead(204,{'Access-Control-Allow-Methods':'GET, POST, PATCH, DELETE','Access-Control-Allow-Headers':'Authorization, Content-Type, Idempotency-Key, If-Match, Last-Event-ID, Range, X-Supercode-Caller','Access-Control-Max-Age':'86400'});res.end();return;}
   if(api.publicOrigin){const expected=new URL(api.publicOrigin);if(req.headers.host!==expected.host)fail(400,'invalid_request','request Host does not match configured public origin');}
   const url=new URL(req.url,'http://local'); const path=url.pathname;
   // The hosted viewer's files (viewer.mjs): public; the page's delegated token is checked at every door it opens.
@@ -56,7 +56,8 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   if(!auth)fail(401,'authentication_required','authentication required');auth.now=api.clock.nowMs();auth.clock=api.clock;
   const bulk=/\/captures\/[^/]+\/parts\/\d+$/.test(path)||/\/uploads\/[^/]+\/chunks\/\d+$/.test(path);// A machine's own credential syncs its live sessions as they change (a capture is a begin and a commit), so it
   // gets the bulk allowance for ordinary requests too; a person's or a service's stays at 120 a minute.
-  checkRate(api,`credential:${auth.credential_id}:${bulk?'bulk':'ordinary'}`,bulk||auth.kind==='machine'?600:120,bulk||auth.kind==='machine'?60:30);
+  const rateKey=`credential:${auth.credential_id}:${bulk?'bulk':'ordinary'}`;noteSpender(api,rateKey,req,path);
+  try{checkRate(api,rateKey,bulk||auth.kind==='machine'?600:120,bulk||auth.kind==='machine'?60:30);}catch(error){throw spentBy(api,rateKey,auth,error);}
   if(req.method==='GET'&&path==='/api/v1/me'){if(!['user','service'].includes(auth.kind))fail(403,'forbidden','credential kind cannot use this operation');const teams=await api.store.query('SELECT t.id,t.name,t.revision,m.role FROM memberships m JOIN teams t ON t.id=m.team_id WHERE m.principal_id=? AND m.active=1 AND (? IS NULL OR m.team_id=?)',[auth.principal_id,auth.team_id,auth.team_id]);return send(res,200,{server_id:api.serverId,principal:{id:auth.principal_id,kind:auth.principal_kind,display_name:auth.display_name},teams:teams.map(x=>({team:{id:x.id,name:x.name,revision:x.revision},role:x.role}))},requestId);}
   if(req.method==='POST'&&path==='/api/v1/me/identities')return await linkIdentity(api,req,res,auth,requestId);
   if(req.method==='GET'&&path==='/api/v1/teams')return await listTeams(api,res,auth,url,requestId);
@@ -108,6 +109,26 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   if(api.harnessRoutes&&await api.harnessRoutes.team({api,req,res,auth,url,path,sub,requestId}))return;
   fail(404,'not_found','not found');
 }catch(error){const code=error.code??(error instanceof ContractError?'invalid_request':'internal_error');const status=error.status??({invalid_request:400,authentication_required:401,forbidden:403,not_found:404,source_revoked:403,session_deleted:410,request_too_large:413,batch_gap:409,capture_conflict:409,source_paused:409,resync_required:409,revision_mismatch:409,conflict:409,rate_limited:429}[code]??500);if(!res._auditRecord){api.securityEvents.push({at:api.clock.nowMs(),request_id:requestId,status,code,authenticated:Boolean(res._authenticated)});if(api.securityEvents.length>1000)api.securityEvents.shift();}send(res,status,validationFailure(Object.assign(error,{code}),requestId),requestId);}};}
+// Who spent a credential's allowance, as this server saw it: the credential's last minute of requests by route and by
+// the caller each client names (X-Supercode-Caller, a process's command words). A refusal carries it to the caller and
+// writes it to the log (at most every 10 s per credential), so the spender is named, not guessed.
+const ID_SEGMENT=/^(?:[a-z]+_[A-Za-z0-9_]{6,}|[^/]*[:%@][^/]*|[0-9a-f-]{16,}|\d+)$/;
+const routeOf=path=>path.replace(/^\/api\/v1/,'').split('/').map(part=>ID_SEGMENT.test(part)?'*':part).join('/');
+function noteSpender(api,key,req,path){
+  const now=api.clock.nowMs(),list=api.rateSpenders.get(key)??[];while(list.length&&now-list[0].at>60000)list.shift();
+  if(list.length<2000)list.push({at:now,route:`${req.method} ${routeOf(path)}`,caller:String(req.headers['x-supercode-caller']??'unnamed').slice(0,120)});
+  api.rateSpenders.set(key,list);
+  // A credential idle for a minute keeps no tally.
+  if(api.rateSpenders.size>256)for(const [other,entries] of api.rateSpenders)if(!entries.length||now-entries.at(-1).at>60000){api.rateSpenders.delete(other);api.rateReported.delete(other);}
+}
+function spentBy(api,key,auth,error){
+  if(error?.code!=='rate_limited')return error;
+  const now=api.clock.nowMs(),list=(api.rateSpenders.get(key)??[]).filter(entry=>now-entry.at<=60000);
+  const top=field=>Object.entries(list.reduce((counts,entry)=>(counts[entry[field]]=(counts[entry[field]]??0)+1,counts),{})).sort((a,b)=>b[1]-a[1]).slice(0,8).map(([name,count])=>({name,count}));
+  const spent={requests:list.length,by_caller:top('caller'),by_route:top('route')};
+  if(now-(api.rateReported.get(key)??0)>=10000){api.rateReported.set(key,now);console.warn(`rate limited: ${auth.kind} credential ${auth.credential_id} (${auth.principal_id}) made ${list.length} requests in the last minute; by caller ${spent.by_caller.map(x=>`${x.name}=${x.count}`).join(', ')}; by route ${spent.by_route.map(x=>`${x.name}=${x.count}`).join(', ')}`);}
+  error.details={...(error.details??{}),spent_last_minute:spent};return error;
+}
 function checkRate(api,key,perMinute,burst){const now=api.clock.nowMs(),state=api.rateState.get(key)??{tokens:burst,at:now};state.tokens=Math.min(burst,state.tokens+(now-state.at)*(perMinute/60000));state.at=now;if(state.tokens<1)fail(429,'rate_limited','rate limit exceeded',{retry_after_seconds:Math.ceil((1-state.tokens)/(perMinute/60000)/1000)});state.tokens-=1;api.rateState.set(key,state);}
 function redactSecretReplay(path,body){if(body===null||typeof body!=='object')return body;const copy=structuredClone(body);if(path.endsWith('/invitations')&&copy.data)delete copy.data.enrollment_code;if(path.endsWith('/machines')&&copy.data)copy.data.credential=null;if(path.endsWith('/credentials')||path.endsWith('/delegations'))copy.data=null;if((path.endsWith('/apps')||path.endsWith('/secret'))&&copy.data)delete copy.data.secret;if(path.endsWith('/installations')&&copy.data)delete copy.data.code;return copy;}
 

package/server/published-events.mjs

@@ -3,7 +3,7 @@ import { appAuthentication } from './apps.mjs';
 import { isAdmin } from './auth.mjs';
 import { exact } from './request-json.mjs';
 import { canonicalJson } from './wire.mjs';
-import { writeSse } from './events.mjs';
+import { sseRoom, writeSse } from './events.mjs';
 import { APP_EVENTS, PUBLISHABLE_EVENTS, eventReadAction } from './event-catalogue.mjs';
 import { EVENT_DATA_LIMIT } from '../event-limits.mjs';
 
@@ -99,7 +99,7 @@ async function eventStream({api,req,res,auth,url,requestId}){
   let closed=false,running=null,dirty=false;
   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 terminal=(type,reason)=>{if(!closed)writeSse(res,{type,reason,terminal:true});close();};
-  const write=event=>{if(closed)return false;if(res.writableLength+Buffer.byteLength(JSON.stringify(event))>1048576){terminal('resync_required','slow_reader');return false;}writeSse(res,event);return true;};
+  const write=async event=>{if(closed)return false;const room=await sseRoom(res,Buffer.byteLength(JSON.stringify(event)));if(closed||room==='closed')return false;if(room==='slow'){terminal('resync_required','slow_reader');return false;}writeSse(res,event);return true;};
   const readable=async event=>{
     const current=await liveAuth(api,auth);
     if(current.epoch!==auth.epoch)fail(409,'resync_required','authorization changed during event delivery');
@@ -120,21 +120,21 @@ async function eventStream({api,req,res,auth,url,requestId}){
         {kind:'one',sql:'SELECT COALESCE((SELECT max(sequence) FROM org_events WHERE team_id=?),(SELECT pruned_through FROM event_retention WHERE team_id=?),0) last',params:[auth.team_id,auth.team_id]},
         {kind:'query',sql:'SELECT r.sequence FROM event_resources r JOIN org_events e ON e.sequence=r.sequence WHERE r.team_id=? AND (? IS NULL OR r.source_id=?) AND (? IS NULL OR r.resource_kind IN (SELECT value FROM json_each(?)) OR e.kind IN (SELECT value FROM json_each(?))) ORDER BY r.source_id,r.resource_kind,r.resource_id',params:[auth.team_id,query.source,query.source,filterResources,filterResources,filterKinds]},
       ]);
-      cursor=head.last;write({type:'snapshot_begin'});
+      cursor=head.last;if(!await write({type:'snapshot_begin'}))return;
       for(let at=0;at<resources.length;at+=32){
         const sequences=resources.slice(at,at+32).map(row=>row.sequence);
         const rows=await api.store.query('SELECT * FROM org_events WHERE team_id=? AND sequence IN (SELECT value FROM json_each(?)) ORDER BY sequence',[auth.team_id,JSON.stringify(sequences)]);
         if(rows.length!==sequences.length){terminal('resync_required','snapshot_retention');return;}
-        for(const row of rows){const event=eventOf(row);if(await readable(event))if(!write({type:'snapshot_item',sequence:row.sequence,data:event}))return;}
+        for(const row of rows){const event=eventOf(row);if(await readable(event))if(!await write({type:'snapshot_item',sequence:row.sequence,data:event}))return;}
       }
-      write({type:'snapshot_end',cursor:codec.encode(cursor)});
+      if(!await write({type:'snapshot_end',cursor:codec.encode(cursor)}))return;
     }
     for(;;){
       const rows=await api.store.query('SELECT * FROM org_events WHERE team_id=? AND sequence>? AND (? IS NULL OR source_id=?) AND (? IS NULL OR kind IN (SELECT value FROM json_each(?))) ORDER BY sequence LIMIT 128',[auth.team_id,cursor,query.source,query.source,filterKinds,filterKinds]);
-      if(!rows.length){cursor=Math.max(cursor,bounds.last);write({type:'checkpoint',cursor:codec.encode(cursor)});break;}
-      for(const row of rows){if(closed)return;cursor=row.sequence;const event=eventOf(row);if(await readable(event))write({type:'event',sequence:row.sequence,cursor:codec.encode(cursor),data:event});}
+      if(!rows.length){cursor=Math.max(cursor,bounds.last);await write({type:'checkpoint',cursor:codec.encode(cursor)});break;}
+      for(const row of rows){if(closed)return;cursor=row.sequence;const event=eventOf(row);if(await readable(event)&&!await write({type:'event',sequence:row.sequence,cursor:codec.encode(cursor),data:event}))return;}
       // Advance even when the reader was not authorized for a resource; never leak its data.
-      write({type:'checkpoint',cursor:codec.encode(cursor)});if(rows.length<128)break;
+      if(!await write({type:'checkpoint',cursor:codec.encode(cursor)}))return;if(rows.length<128)break;
     }
   };
   const enqueue=()=>{dirty=true;if(running)return running;running=(async()=>{while(dirty&&!closed){dirty=false;await drain();}})().catch(error=>terminal([401,403].includes(error.status)?'access_revoked':'resync_required',error.code??'unavailable')).finally(()=>{running=null;});return running;};
@@ -142,5 +142,5 @@ async function eventStream({api,req,res,auth,url,requestId}){
   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();
-  if(!closed)write({type:'checkpoint',cursor:codec.encode(cursor)});
+  if(!closed)await write({type:'checkpoint',cursor:codec.encode(cursor)});
 }