@volter/teams 0.1.82 → 0.1.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.1.82",
+  "version": "0.1.84",
   "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",
@@ -23,6 +23,7 @@
     "./server/core": "./server/core.mjs",
     "./server/identity-orgs": "./server/identity-orgs.mjs",
     "./server/http": "./server/http.mjs",
+    "./server/apps": "./server/apps.mjs",
     "./server/auth": "./server/auth.mjs",
     "./server/machine-link": "./server/machine-link.mjs",
     "./server/request-json": "./server/request-json.mjs",

package/server/apps.mjs

@@ -0,0 +1,359 @@
+// Consent, OAuth-style one-time exchange, attenuation and durable Standard Webhooks.
+// This module imports no product adapter. Applications keep their configuration/id maps.
+import { randomBytes, createHash, createCipheriv, createDecipheriv, createHmac } from 'node:crypto';
+import { hashToken, makeToken, isAdmin, canRead, canManage, appGrantAllows, APP_LINEAGE_REVOKED } from './auth.mjs';
+import { exact } from './request-json.mjs';
+import { closeAppChannels, closeMachineChannels } from './machine-link.mjs';
+
+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',
+]);
+export const APP_EVENTS = Object.freeze(['app.registered', 'app.installed', 'app.uninstalled']);
+const TOKEN_MS = 90 * 86400000, CODE_MS = 10 * 60000, DELEGATION_MS = 15 * 60000;
+const error = (status, code, message) => { throw Object.assign(new Error(message), { status, code }); };
+const statement = (sql, ...params) => ({ sql, params });
+const guard = (sql, params, message = 'application authorization changed') => ({ sql, params, status: 403, code: 'forbidden', message });
+const parse = JSON.parse;
+const keyBytes = api => {
+  if (!api.appRootSecret) error(503, 'unavailable', 'the Teams root secret is required for app secret custody');
+  return createHash('sha256').update(`Teams app custody v1\0${api.appRootSecret}`).digest();
+};
+function seal(api, secret, id) {
+  const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', keyBytes(api), iv);
+  cipher.setAAD(Buffer.from(id));
+  const encrypted = Buffer.concat([cipher.update(secret, 'utf8'), cipher.final()]);
+  return [iv, cipher.getAuthTag(), encrypted].map(part => part.toString('base64url')).join('.');
+}
+function unseal(api, secret, id) {
+  const [iv, tag, ciphertext] = secret.split('.').map(part => Buffer.from(part, 'base64url'));
+  const cipher = createDecipheriv('aes-256-gcm', keyBytes(api), iv);
+  cipher.setAAD(Buffer.from(id)); cipher.setAuthTag(tag);
+  return Buffer.concat([cipher.update(ciphertext), cipher.final()]).toString('utf8');
+}
+function text(value, name, max = 256) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max || /[\x00-\x1f]/.test(value)) error(400, 'invalid_request', `${name} must be a nonempty string of at most ${max} characters`);
+  return value;
+}
+function secureUrl(value, name, originOnly = false) {
+  text(value, name, 2048);
+  let url; try { url = new URL(value); } catch { error(400, 'invalid_request', `${name} must be an HTTPS URL`); }
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) || url.username || url.password || url.hash || (originOnly && value !== url.origin)) error(400, 'invalid_request', `${name} must be HTTPS (HTTP is loopback-only)${originOnly ? ' and an exact origin' : ''}`);
+  return value;
+}
+function list(value, name, allowed, max = 40) {
+  if (!Array.isArray(value) || value.length > max || value.some(item => typeof item !== 'string' || !allowed.includes(item)) || new Set(value).size !== value.length) error(400, 'invalid_request', `${name} must be a distinct list from the app catalogue`);
+  return value;
+}
+const appJson = row => ({ id: row.id, team_id: row.team_id, principal_id: row.principal_id, name: row.name, description: row.description, actions: parse(row.actions_json), event_kinds: parse(row.events_json), redirect_urls: parse(row.redirect_urls_json), webhook_url: row.webhook_url, issuer: row.issuer, state: row.state, created_at: row.created_at });
+const installJson = row => ({ id: row.id, app_id: row.app_id, team_id: row.team_id, principal_id: row.principal_id, installer_id: row.installer_id, actions: parse(row.actions_json), state: row.state, created_at: row.created_at, uninstalled_at: row.uninstalled_at });
+const admin = auth => {
+  if (!isAdmin(auth) || auth.installation_id) error(403, 'forbidden', 'an organization admin must consent to app changes');
+};
+function adminGuards(auth, now) {
+  return [guard('SELECT 1 FROM credentials WHERE id=? AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>?)', [auth.credential_id, now]), guard("SELECT 1 FROM memberships WHERE team_id=? AND principal_id=? AND active=1 AND role IN ('owner','admin')", [auth.team_id, auth.principal_id])];
+}
+function sessionAuthorityGuard(source,teamId,id,manage,now){
+  return guard(`SELECT 1 FROM sessions s JOIN memberships m ON m.team_id=s.team_id AND m.principal_id=?
+    WHERE s.team_id=? AND s.id=? AND s.deleted_at IS NULL AND m.active=1 AND (?=0 OR m.role!='viewer')
+    AND ((?=0 AND s.visibility='team') OR s.custodian_id=? OR EXISTS (SELECT 1 FROM session_grants g
+      WHERE g.team_id=s.team_id AND g.session_id=s.id AND (?=0 OR g.role='manager') AND (g.expires_at IS NULL OR g.expires_at>?)
+      AND ((g.subject_kind='principal' AND g.subject_id=?) OR (g.subject_kind='group' AND EXISTS
+        (SELECT 1 FROM group_members gm WHERE gm.team_id=s.team_id AND gm.principal_id=? AND gm.group_id=g.subject_id)))))`,
+    [source.principal_id,teamId,id,manage?1:0,manage?1:0,source.principal_id,manage?1:0,now,source.principal_id,source.principal_id]);
+}
+
+/** Restrict every ordinary door, including replay, before the existing resource evaluator. Unknown doors fail closed. */
+export function appRouteAction(method, sub) {
+  if (method === 'GET' && (sub === '' || sub === '/me' || sub === '/capabilities' || sub === '/teams')) return 'teams.read';
+  if (/^\/members(?:\/[^/]+)?$/.test(sub)) return method === 'GET' ? 'members.read' : 'members.write';
+  if (/^\/groups(?:\/[^/]+(?:\/members\/[^/]+)?)?$/.test(sub)) return method === 'GET' ? 'groups.read' : 'groups.write';
+  if (/^\/sessions\/[^/]+\/(access|view-bindings)(?:\/[^/]+)?$/.test(sub)) return 'sessions.access';
+  if(method==='GET'&&/^\/sessions(?:\/(?:search|events|[^/]+(?:\/(?:messages|events|artifacts\/[^/]+))?))?$/.test(sub))return 'sessions.read';
+  if(['PATCH','DELETE'].includes(method)&&/^\/sessions\/[^/]+$/.test(sub))return 'sessions.write';
+  if(method==='GET'&&/^\/machines(?:\/(?:events|[^/]+(?:\/roots)?))?$/.test(sub))return 'machines.read';
+  if(/^\/machines\/[^/]+\/(?:access|grants|publications)(?:\/[^/]+)?$/.test(sub))return 'machines.access';
+  if((method==='POST'&&sub==='/machines')||(method==='DELETE'&&/^\/machines\/[^/]+$/.test(sub)))return 'machines.write';
+  if (/^\/sources(?:\/[^/]+(?:\/config)?)?$/.test(sub)) return method === 'GET' ? 'sources.read' : 'sources.write';
+  return null;
+}
+export function enforceAppScope(auth, method, sub) {
+  if (!auth?.installation_id) return;
+  const action = appRouteAction(method, sub);
+  if (!action || !auth.app_actions.includes(action)) error(403, 'forbidden', 'this operation is outside the consented app token scopes');
+  if(auth.app_grants!=null){
+    auth.app_operation_action=action;
+    const session=/^\/sessions\/([^/]+)/.exec(sub);
+    // Collections filter through the same fence; other resource families have no passed grant.
+    if(action==='teams.read')return;
+    if(!action.startsWith('sessions.')||(!session&&!['/sessions','/sessions/search','/sessions/events'].includes(sub)))error(403,'forbidden','this operation is outside the delegated resource grants');
+    if(session&&!['search','events'].includes(session[1])&&!appGrantAllows(auth,'session',decodeURIComponent(session[1]),action))error(404,'not_found','session not found');
+  }
+}
+/** Atomic mutation rechecks; parent credentials cannot survive revocation through a child. */
+export function appAuthGuards(auth, now) {
+  const installation=auth?.installation_id??auth?.identity_installation_id;if(!installation)return [];
+  const checks=[guard(`SELECT 1 FROM app_installations i JOIN apps a ON a.id=i.app_id JOIN memberships m ON m.team_id=i.team_id AND m.principal_id=i.principal_id JOIN memberships installer ON installer.team_id=i.team_id AND installer.principal_id=i.installer_id
+    WHERE i.id=? AND i.team_id=? AND i.state='active' AND a.state='active' AND m.active=1 AND installer.active=1 AND installer.role IN ('owner','admin')`, [installation, auth.team_id]),
+    guard(`SELECT 1 WHERE NOT EXISTS (${APP_LINEAGE_REVOKED})`, [auth.credential_id, now])];
+  if(auth.app_grants!=null){
+    checks.push(guard('SELECT 1 FROM teams WHERE id=? AND auth_epoch=?',[auth.team_id,auth.app_auth_epoch]),...appAuthGuards(auth.app_grant_source,now));
+    for(const grant of auth.app_grants){
+      const source=auth.app_grant_source,manage=grant.actions.some(a=>a!=='sessions.read');
+      checks.push(sessionAuthorityGuard(source,auth.team_id,grant.id,manage,now));
+    }
+  }
+  return checks;
+}
+export async function appAuthentication(api, auth, depth=0) {
+  if (!auth) return null;
+  if(depth>16)return null;
+  const row = await api.store.one(`SELECT ac.*,i.team_id,i.principal_id,i.role,i.state,a.state app_state,installer.active installer_active,installer.role installer_role
+    FROM app_credentials ac JOIN app_installations i ON i.id=ac.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 WHERE ac.credential_id=?`, [auth.credential_id]);
+  if (!row) {
+    const identity=await api.store.one(`SELECT i.id,i.state,a.state app_state,m.active,m.role FROM identity_app_credentials c JOIN app_installations i ON i.id=c.installation_id JOIN apps a ON a.id=i.app_id JOIN memberships m ON m.team_id=i.team_id AND m.principal_id=i.installer_id WHERE c.credential_id=?`,[auth.credential_id]);
+    if(identity){if(identity.state!=='active'||identity.app_state!=='active'||!identity.active||!['owner','admin'].includes(identity.role))return null;auth.identity_installation_id=identity.id;}
+    return auth;
+  }
+  if (!auth.active || row.state !== 'active' || row.app_state !== 'active' || !row.installer_active || !['owner','admin'].includes(row.installer_role) || row.team_id !== auth.team_id || (row.subject_principal_id??row.principal_id) !== auth.principal_id) return null;
+  const revoked = await api.store.one(APP_LINEAGE_REVOKED, [auth.credential_id, api.clock.nowMs()]);
+  if (revoked) return null;
+  const ranks=['viewer','member','admin','owner'];auth.role=ranks[Math.min(ranks.indexOf(auth.role),ranks.indexOf(row.role))];
+  Object.assign(auth, { installation_id: row.installation_id, app_actions: parse(row.actions_json), act: parse(row.actor_json), app_grants:parse(row.grants_json) });
+  if(auth.app_grants!==null){
+    const epoch=await api.store.one('SELECT auth_epoch FROM teams WHERE id=?',[auth.team_id]);auth.app_auth_epoch=epoch.auth_epoch;
+    const source=await credentialAuthority(api,row.subject_credential_id??row.parent_id,auth.team_id,depth+1);
+    if(!source)return null;
+    auth.app_grant_source=source;
+    const held=[];
+    for(const grant of auth.app_grants){
+      try{await api.store.authorizedSession({teamId:auth.team_id,principalId:source.principal_id,credentialId:source.credential_id,ref:grant.id,now:api.clock.nowMs()});}catch{continue;}
+      const session=await api.store.one('SELECT * FROM sessions WHERE team_id=? AND id=?',[auth.team_id,grant.id]);
+      if(!session||session.deleted_at!=null)continue;
+      const grants=await api.store.query('SELECT * FROM session_grants WHERE team_id=? AND session_id=?',[auth.team_id,grant.id]);
+      held.push({...grant,actions:grant.actions.filter(action=>appGrantAllows(source,'session',grant.id,action)&&(action==='sessions.read'||canManage(source,session,grants)))});
+    }
+    auth.app_grants=held;
+  }
+  return auth;
+}
+async function credentialAuthority(api,id,teamId,depth=0){
+  const now=api.clock.nowMs();
+  const auth=await api.store.one(`SELECT c.id credential_id,c.kind,c.principal_id,c.expires_at,m.team_id,m.role,m.active FROM credentials c JOIN memberships m ON m.principal_id=c.principal_id AND m.team_id=? WHERE c.id=? AND c.kind IN ('user','service') AND (c.team_id IS NULL OR c.team_id=?) AND c.revoked_at IS NULL AND (c.expires_at IS NULL OR c.expires_at>?)`,[teamId,id,teamId,now]);
+  if(!auth?.active)return null;
+  auth.now=now;auth.group_ids=(await api.store.query('SELECT group_id FROM group_members WHERE team_id=? AND principal_id=?',[teamId,auth.principal_id])).map(r=>r.group_id);
+  return appAuthentication(api,auth,depth);
+}
+/** Exact issuer trust is an active, consented installation, scoped to its organization. */
+export async function installedIssuer(api, issuer, action, teamId = null) {
+  return await api.store.one(`SELECT i.id,i.team_id,i.principal_id,i.created_at FROM app_installations i JOIN apps a ON a.id=i.app_id JOIN memberships m ON m.team_id=i.team_id AND m.principal_id=i.principal_id JOIN memberships installer ON installer.team_id=i.team_id AND installer.principal_id=i.installer_id
+    WHERE a.issuer=? AND a.state='active' AND i.state='active' AND m.active=1 AND installer.active=1 AND installer.role IN ('owner','admin') AND (? IS NULL OR i.team_id=?) AND EXISTS (SELECT 1 FROM json_each(i.actions_json) WHERE value=?) LIMIT 1`, [issuer, teamId, teamId, action]);
+}
+
+/** Fan-out is durable and transactionally committed with the source mutation. C2 adds resource events. */
+export async function appEventStatements(api, teamId, kind, data, addedDestination = null) {
+  const now = api.clock.nowMs(), eventId = api.ids.next('event');
+  const destinations = await api.store.query(`SELECT i.id FROM app_installations i JOIN apps a ON a.id=i.app_id WHERE i.team_id=? AND i.state='active' AND a.state='active' AND a.webhook_url IS NOT NULL AND EXISTS (SELECT 1 FROM json_each(a.events_json) WHERE value=?)`, [teamId, kind]);
+  if(addedDestination&&!destinations.some(row=>row.id===addedDestination))destinations.push({id:addedDestination});
+  const body = JSON.stringify({ id: eventId, type: kind, team_id: teamId, created_at: now, data });
+  return destinations.map(row => statement("INSERT INTO app_webhook_deliveries(id,installation_id,event_id,body,state,next_at,created_at) SELECT ?,?,?,?,'pending',?,? WHERE EXISTS (SELECT 1 FROM app_installations WHERE id=? AND state='active')", api.ids.next('delivery'), row.id, eventId, body, now, now, row.id));
+}
+
+export async function appPreAuth({ api, req, res, path, requestId, parseJson, send }) {
+  if (req.method !== 'POST' || path !== '/api/v1/apps/token') return false;
+  const body = await parseJson(req); exact(body, ['app_id', 'app_secret', 'code', 'redirect_url']);
+  for (const field of ['app_id','app_secret','code','redirect_url']) text(body[field], field, 2048);
+  const now = api.clock.nowMs();
+  const code = await api.store.one(`SELECT c.*,i.*,a.secret_hash FROM app_install_codes c JOIN app_installations i ON i.id=c.installation_id JOIN apps a ON a.id=i.app_id
+    WHERE c.code_hash=? AND i.app_id=? AND a.secret_hash=? AND c.redirect_url=? AND c.consumed_at IS NULL AND c.expires_at>? AND i.state='active' AND a.state='active'`, [hashToken(body.code), body.app_id, hashToken(body.app_secret), body.redirect_url, now]);
+  if (!code) error(401, 'authentication_required', 'invalid or consumed app installation code');
+  const signingSecret=unseal(api,code.signing_secret,code.installation_id);
+  const cid = api.ids.next('credential'), token = makeToken(cid), expiresAt = now + TOKEN_MS;
+  await api.store.guardedTransaction([
+    guard(`SELECT 1 FROM app_install_codes c JOIN app_installations i ON i.id=c.installation_id JOIN apps a ON a.id=i.app_id JOIN memberships m ON m.team_id=i.team_id AND m.principal_id=i.installer_id
+      WHERE c.code_hash=? AND c.consumed_at IS NULL AND c.expires_at>? AND i.state='active' AND a.state='active' AND a.secret_hash=? AND m.active=1 AND m.role IN ('owner','admin')`, [hashToken(body.code), now, hashToken(body.app_secret)]),
+  ], [statement('UPDATE app_install_codes SET consumed_at=? WHERE code_hash=?', now, hashToken(body.code)),
+    statement('INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,\'service\',?,?,?)', cid, hashToken(token), code.principal_id, code.team_id, expiresAt, now),
+    statement('INSERT INTO app_credentials(credential_id,installation_id,actions_json,actor_json) VALUES (?,?,?,?)', cid, code.installation_id, code.actions_json, '[]')]);
+  // No bearer or signing secret enters a replay record, audit payload or URL.
+  send(res, 201, { version: 1, installation: installJson({ ...code, id: code.installation_id }), credential: { token, kind: 'service', expires_at: expiresAt, actions: parse(code.actions_json), subject: code.principal_id, act: [] }, webhook_secret: signingSecret }, requestId);
+  return true;
+}
+
+export async function appRoute(ctx) {
+  const { api, req, res, auth, sub, requestId, parseJson, send, result, guardedMutation } = ctx;
+  if (!sub.startsWith('/apps') && !sub.startsWith('/app-installations')) return false;
+  // Attenuation is the one app-owned credential door; it grants no admin power.
+  const delegation = /^\/app-installations\/([^/]+)\/delegations$/.exec(sub);
+  if (delegation && req.method === 'POST') {
+    if (auth.installation_id !== delegation[1]) error(403, 'forbidden', 'only this installation may delegate its own token');
+    const body = await parseJson(req); exact(body, ['actions','actor','expires_in_ms','principal_id','grants','subject_token']);
+    const actions = list(body.actions, 'actions', auth.app_actions);
+    const actor = text(body.actor, 'actor');
+    const duration = body.expires_in_ms ?? DELEGATION_MS;
+    if (!Number.isSafeInteger(duration) || duration < 1000 || duration > DELEGATION_MS || auth.act.length >= 16) error(400, 'invalid_request', 'delegation is limited to fifteen minutes and sixteen actors');
+    const parent = await api.store.one('SELECT expires_at FROM credentials WHERE id=?', [auth.credential_id]);
+    const now=api.clock.nowMs(),epoch=await api.store.one('SELECT auth_epoch FROM teams WHERE id=?',[auth.team_id]);
+    const subject=body.principal_id==null?auth.principal_id:text(body.principal_id,'principal_id');
+    let grants=body.grants===undefined?(auth.app_grants?.map(g=>({...g,actions:g.actions.filter(a=>actions.includes(a))}))??null):body.grants,source=auth,sourceId=null;
+    if(auth.app_grants!=null&&grants===null)error(403,'forbidden','a descendant cannot remove its resource fence');
+    if(body.subject_token!=null){
+      if(body.principal_id==null)error(400,'invalid_request','subject_token requires principal_id');
+      text(body.subject_token,'subject_token',4096);
+      const credential=await api.store.one('SELECT id FROM credentials WHERE token_hash=?',[hashToken(body.subject_token)]);
+      source=credential?await credentialAuthority(api,credential.id,auth.team_id):null;
+      if(!source||source.principal_id!==subject)error(403,'forbidden','subject_token must prove the named active principal in this organization');
+      sourceId=source.credential_id;
+    }
+    if(body.principal_id!=null&&(!Array.isArray(grants)||!grants.length))error(400,'invalid_request','an existing principal requires explicit resource grants');
+    const targetMembership=await api.store.one('SELECT role,active FROM memberships WHERE team_id=? AND principal_id=?',[auth.team_id,subject]);
+    if(!targetMembership?.active)error(404,'not_found','principal not found');
+    const target={kind:'service',principal_id:subject,active:1,role:targetMembership.role,now,group_ids:(await api.store.query('SELECT group_id FROM group_members WHERE team_id=? AND principal_id=?',[auth.team_id,subject])).map(r=>r.group_id)};
+    if(grants!==null){
+      if(!Array.isArray(grants)||grants.length>100||actions.some(a=>a!=='teams.read'&&!['sessions.read','sessions.write','sessions.access'].includes(a)))error(400,'invalid_request','resource delegation accepts at most 100 session grants and session/Teams metadata actions');
+      const seen=new Set();
+      for(const g of grants){
+        exact(g,['kind','id','actions']);text(g.id,'grant.id');
+        if(g.kind!=='session'||seen.has(g.id))error(400,'invalid_request','grant must name a distinct local session');seen.add(g.id);
+        list(g.actions,'grant.actions',actions);
+        if(!g.actions.includes('sessions.read')||g.actions.some(a=>!['sessions.read','sessions.write','sessions.access'].includes(a)))error(400,'invalid_request','a session grant requires sessions.read and may add write/access');
+        for(const action of g.actions)if(!appGrantAllows(auth,'session',g.id,action)||!appGrantAllows(source,'session',g.id,action)||(source.app_actions&&!source.app_actions.includes(action)))error(403,'forbidden','delegation cannot widen its parent or subject grants');
+        const session=await api.store.one('SELECT * FROM sessions WHERE team_id=? AND id=? AND deleted_at IS NULL',[auth.team_id,g.id]);
+        if(!session)error(404,'not_found','session not found');
+        await api.store.authorizedSession({teamId:auth.team_id,principalId:source.principal_id,credentialId:source.credential_id,ref:g.id,now});
+        const acl=await api.store.query('SELECT * FROM session_grants WHERE team_id=? AND session_id=?',[auth.team_id,g.id]);
+        if(!canRead(target,session,acl)||g.actions.some(a=>a!=='sessions.read'&&(!canManage(source,session,acl)||!canManage(target,session,acl))))error(403,'forbidden','grants must be held by both the source and the represented principal');
+      }
+    }
+    const expiresAt=Math.min(now+duration,parent.expires_at??Infinity,source.expires_at??Infinity),cid=api.ids.next('credential'),token=makeToken(cid),act=[...auth.act,actor];
+    const response=result(api,auth,{token,kind:'service',expires_at:expiresAt,actions,subject,act,grants});
+    const boundaryNow=api.clock.nowMs(),checks=[...appAuthGuards(auth,boundaryNow),...appAuthGuards(source,boundaryNow),guard('SELECT 1 FROM teams WHERE id=? AND auth_epoch=?',[auth.team_id,epoch.auth_epoch]),guard('SELECT 1 FROM memberships WHERE team_id=? AND principal_id=? AND active=1 AND role=?',[auth.team_id,subject,targetMembership.role]),guard('SELECT 1 FROM credentials WHERE id=? AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>?)',[source.credential_id,boundaryNow])];
+    for(const grant of grants??[]){const manage=grant.actions.some(a=>a!=='sessions.read');checks.push(sessionAuthorityGuard(source,auth.team_id,grant.id,manage,boundaryNow),sessionAuthorityGuard(target,auth.team_id,grant.id,manage,boundaryNow));}
+    await guardedMutation(api,res,auth,checks,[statement('INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,\'service\',?,?,?)',cid,hashToken(token),subject,auth.team_id,expiresAt,now),statement('INSERT INTO app_credentials(credential_id,installation_id,parent_id,actions_json,actor_json,subject_principal_id,subject_credential_id,grants_json) VALUES (?,?,?,?,?,?,?,?)',cid,auth.installation_id,auth.credential_id,JSON.stringify(actions),JSON.stringify(act),subject,sourceId,JSON.stringify(grants))],{status:201,body:response,targetId:cid});
+    send(res, 201, response, requestId); return true;
+  }
+  admin(auth);
+  if (req.method === 'GET' && sub === '/apps/catalogue') {
+    send(res, 200, result(api, auth, { actions: APP_ACTIONS, event_kinds: APP_EVENTS }), requestId); return true;
+  }
+  if (req.method === 'GET' && sub === '/apps') {
+    send(res, 200, { version: 1, context:{server_id:api.serverId,team_id:auth.team_id,principal_id:auth.principal_id}, items: (await api.store.query("SELECT * FROM apps WHERE state='active' ORDER BY id LIMIT 1000")).map(appJson), next_cursor: null }, requestId); return true;
+  }
+  let match = /^\/apps\/([^/]+)$/.exec(sub);
+  if (match && req.method === 'GET') {
+    const app = await api.store.one("SELECT * FROM apps WHERE id=? AND state='active'", [match[1]]);
+    if (!app) error(404, 'not_found', 'app not found');
+    send(res, 200, result(api, auth, appJson(app)), requestId); return true;
+  }
+  if(match&&req.method==='DELETE'){
+    const app=await api.store.one("SELECT * FROM apps WHERE id=? AND team_id=? AND state='active'",[match[1],auth.team_id]);
+    if(!app)error(404,'not_found','app not found');
+    const now=api.clock.nowMs();
+    const grants=await api.store.query('SELECT g.id,g.team_id,g.machine_id FROM machine_grants g JOIN app_installations i ON i.id=g.app_installation_id WHERE i.app_id=?',[app.id]);
+    await guardedMutation(api,res,auth,[...adminGuards(auth,now),guard("SELECT 1 FROM apps WHERE id=? AND team_id=? AND state='active'",[app.id,auth.team_id]),guard('SELECT 1 WHERE NOT EXISTS (SELECT 1 FROM machine_grants g JOIN app_installations i ON i.id=g.app_installation_id WHERE i.app_id=? AND g.id NOT IN (SELECT value FROM json_each(?)))',[app.id,JSON.stringify(grants.map(g=>g.id))])],[
+      statement("UPDATE apps SET state='retired',secret_hash='' WHERE id=?",app.id),
+      statement("UPDATE app_installations SET state='uninstalled',uninstalled_at=?,signing_secret='' WHERE app_id=?",now,app.id),
+      statement('UPDATE credentials SET revoked_at=? WHERE id IN (SELECT ac.credential_id FROM app_credentials ac JOIN app_installations i ON i.id=ac.installation_id WHERE i.app_id=? UNION SELECT c.credential_id FROM identity_app_credentials c JOIN app_installations i ON i.id=c.installation_id WHERE i.app_id=?)',now,app.id,app.id),
+      statement('UPDATE memberships SET active=0,revision=revision+1 WHERE (team_id,principal_id) IN (SELECT team_id,principal_id FROM app_installations WHERE app_id=?)',app.id),
+      statement('DELETE FROM app_install_codes WHERE installation_id IN (SELECT id FROM app_installations WHERE app_id=?)',app.id),
+      statement('DELETE FROM machine_grants WHERE app_installation_id IN (SELECT id FROM app_installations WHERE app_id=?)',app.id),
+      statement("UPDATE app_webhook_deliveries SET state='cancelled',lease_until=NULL WHERE state='pending' AND installation_id IN (SELECT id FROM app_installations WHERE app_id=?)",app.id),
+      statement('UPDATE teams SET auth_epoch=auth_epoch+1 WHERE id IN (SELECT team_id FROM app_installations WHERE app_id=?)',app.id),
+    ],{status:204,body:null,targetId:app.id});
+    const installs=await api.store.query('SELECT * FROM app_installations WHERE app_id=?',[app.id]);
+    for(const install of installs){closeAppChannels(api,install.id,'app_deregistered');api.events.publish(install.team_id,{type:'authorization_changed',installation_id:install.id});}
+    for(const grant of grants)closeMachineChannels(api,grant.team_id,grant.machine_id,{grantId:grant.id,reason:'app_deregistered'});
+    send(res,204,null,requestId);return true;
+  }
+  if (req.method === 'POST' && sub === '/apps') {
+    const body = await parseJson(req); exact(body, ['name','description','actions','event_kinds','redirect_urls','webhook_url','issuer']);
+    const name = text(body.name, 'name', 80), description = body.description ?? '';
+    if (typeof description !== 'string' || description.length > 2000) error(400, 'invalid_request', 'description must be at most 2000 characters');
+    const actions = list(body.actions, 'actions', APP_ACTIONS), events = list(body.event_kinds ?? [], 'event_kinds', APP_EVENTS);
+    if (!actions.length || !Array.isArray(body.redirect_urls) || !body.redirect_urls.length || body.redirect_urls.length > 10 || new Set(body.redirect_urls).size !== body.redirect_urls.length) error(400, 'invalid_request', 'actions and one to ten distinct redirect URLs are required');
+    const redirects = body.redirect_urls.map(value => secureUrl(value, 'redirect_url'));
+    const webhook = body.webhook_url == null ? null : secureUrl(body.webhook_url, 'webhook_url');
+    if (events.length && !webhook) error(400, 'invalid_request', 'event subscriptions require a webhook URL');
+    const issuer = body.issuer == null ? null : secureUrl(body.issuer, 'issuer', true);
+    if (actions.some(action => action.startsWith('delegation.') || action === 'identity.login') && !issuer) error(400, 'invalid_request', 'identity and delegation actions require an issuer');
+    const now = api.clock.nowMs(), id = api.ids.next('app'), principal = api.ids.next('service'), secret = `sca_${randomBytes(32).toString('base64url')}`;
+    const app = { id, team_id: auth.team_id, principal_id: principal, name, description, actions_json: JSON.stringify(actions), events_json: JSON.stringify(events), redirect_urls_json: JSON.stringify(redirects), webhook_url: webhook, issuer, state: 'active', created_at: now };
+    const response = result(api, auth, { ...appJson(app), secret });
+    await guardedMutation(api, res, auth, adminGuards(auth, now), [statement("INSERT INTO principals(id,kind,display_name) VALUES (?,'service',?)", principal, name), statement('INSERT INTO apps(id,team_id,principal_id,name,description,actions_json,events_json,redirect_urls_json,webhook_url,issuer,secret_hash,state,created_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,\'active\',?)', id, auth.team_id, principal, name, description, app.actions_json, app.events_json, app.redirect_urls_json, webhook, issuer, hashToken(secret), now), ...await appEventStatements(api, auth.team_id, 'app.registered', appJson(app))], { status: 201, body: response, targetId: id });
+    send(res, 201, response, requestId); return true;
+  }
+  match = /^\/apps\/([^/]+)\/secret$/.exec(sub);
+  if(match&&req.method==='POST') {
+    const body=await parseJson(req);exact(body,[]);
+    const now=api.clock.nowMs(),secret=`sca_${randomBytes(32).toString('base64url')}`;
+    const response=result(api,auth,{id:match[1],secret});
+    await guardedMutation(api,res,auth,[...adminGuards(auth,now),guard("SELECT 1 FROM apps WHERE id=? AND team_id=? AND state='active'",[match[1],auth.team_id],'app not found')],[statement('UPDATE apps SET secret_hash=? WHERE id=?',hashToken(secret),match[1])],{status:200,body:response,targetId:match[1]});
+    send(res,200,response,requestId);return true;
+  }
+  match = /^\/apps\/([^/]+)\/installations$/.exec(sub);
+  if (match && req.method === 'POST') {
+    const body = await parseJson(req); exact(body, ['redirect_url','state','actions']);
+    const app = await api.store.one("SELECT * FROM apps WHERE id=? AND state='active'", [match[1]]);
+    if (!app) error(404, 'not_found', 'app not found');
+    if (!parse(app.redirect_urls_json).includes(body.redirect_url)) error(400, 'invalid_request', 'redirect_url must exactly match a registered URL');
+    const state = text(body.state, 'state', 512), actions = list(body.actions ?? parse(app.actions_json), 'actions', parse(app.actions_json));
+    const existing = await api.store.one('SELECT * FROM app_installations WHERE app_id=? AND team_id=?', [app.id, auth.team_id]);
+    if (existing?.state === 'active') error(409, 'conflict', 'app is already installed; uninstall before re-consenting');
+    const now = api.clock.nowMs(), id = existing?.id ?? api.ids.next('installation'), principal = existing?.principal_id ?? api.ids.next('service');
+    const signingSecret = `whsec_${randomBytes(32).toString('base64')}`, sealed = seal(api, signingSecret, id), code = `sci_${randomBytes(32).toString('base64url')}`;
+    const role = actions.some(action => /^(members|groups|sources)\.write$/.test(action)) ? 'admin' : actions.some(action => action.endsWith('.write') || action.endsWith('.control') || action.endsWith('.access')) ? 'member' : 'viewer';
+    const install = { id, app_id: app.id, team_id: auth.team_id, principal_id: principal, installer_id: auth.principal_id, actions_json: JSON.stringify(actions), role, state: 'active', created_at: now, uninstalled_at: null };
+    const response = result(api, auth, { installation: installJson(install), code, state, redirect_url: body.redirect_url, expires_at: now + CODE_MS });
+    const statements = existing ? [statement('UPDATE memberships SET active=1,role=?,revision=revision+1 WHERE team_id=? AND principal_id=?', role, auth.team_id, principal), statement("UPDATE app_installations SET installer_id=?,actions_json=?,role=?,state='active',signing_secret=?,created_at=?,uninstalled_at=NULL WHERE id=?", auth.principal_id, install.actions_json, role, sealed, now, id)] : [statement("INSERT INTO principals(id,kind,display_name) VALUES (?,'service',?)", principal, app.name), statement('INSERT INTO memberships(team_id,principal_id,role) VALUES (?,?,?)', auth.team_id, principal, role), statement("INSERT INTO app_installations(id,app_id,team_id,principal_id,installer_id,actions_json,role,state,signing_secret,created_at) VALUES (?,?,?,?,?,?,?,'active',?,?)", id, app.id, auth.team_id, principal, auth.principal_id, install.actions_json, role, sealed, now)];
+    await guardedMutation(api, res, auth, [...adminGuards(auth, now), guard("SELECT 1 FROM apps WHERE id=? AND state='active' AND actions_json=? AND redirect_urls_json=?", [app.id, app.actions_json, app.redirect_urls_json]), ...(existing ? [guard("SELECT 1 FROM app_installations WHERE id=? AND state='uninstalled'", [id])] : [])], [...statements, statement('DELETE FROM app_install_codes WHERE installation_id=?', id), statement('INSERT INTO app_install_codes(code_hash,installation_id,redirect_url,expires_at) VALUES (?,?,?,?)', hashToken(code), id, body.redirect_url, now + CODE_MS), ...await appEventStatements(api, auth.team_id, 'app.installed', installJson(install), app.webhook_url&&parse(app.events_json).includes('app.installed')?id:null)], { status: 201, body: response, targetId: id });
+    send(res, 201, response, requestId); return true;
+  }
+  if (sub === '/app-installations' && req.method === 'GET') {
+    send(res, 200, { version: 1, context:{server_id:api.serverId,team_id:auth.team_id,principal_id:auth.principal_id}, items: (await api.store.query('SELECT * FROM app_installations WHERE team_id=? ORDER BY id LIMIT 1000', [auth.team_id])).map(installJson), next_cursor: null }, requestId); return true;
+  }
+  match = /^\/app-installations\/([^/]+)$/.exec(sub);
+  if (match && (req.method === 'GET' || req.method === 'DELETE')) {
+    const install = await api.store.one('SELECT * FROM app_installations WHERE id=? AND team_id=?', [match[1], auth.team_id]);
+    if (!install) error(404, 'not_found', 'installation not found');
+    if (req.method === 'GET') { send(res, 200, result(api, auth, installJson(install)), requestId); return true; }
+    const now = api.clock.nowMs();
+    const grants=await api.store.query('SELECT id,machine_id FROM machine_grants WHERE app_installation_id=?',[install.id]);
+    await guardedMutation(api, res, auth, [...adminGuards(auth, now),guard('SELECT 1 WHERE NOT EXISTS (SELECT 1 FROM machine_grants WHERE app_installation_id=? AND id NOT IN (SELECT value FROM json_each(?)))',[install.id,JSON.stringify(grants.map(g=>g.id))])], [statement("UPDATE app_installations SET state='uninstalled',uninstalled_at=?,signing_secret='' WHERE id=?", now, install.id), statement('UPDATE credentials SET revoked_at=? WHERE id IN (SELECT credential_id FROM app_credentials WHERE installation_id=? UNION SELECT credential_id FROM identity_app_credentials WHERE installation_id=?)', now, install.id, install.id), statement('UPDATE memberships SET active=0,revision=revision+1 WHERE team_id=? AND principal_id=?', auth.team_id, install.principal_id), statement('DELETE FROM app_install_codes WHERE installation_id=?', install.id), statement('DELETE FROM machine_grants WHERE app_installation_id=?',install.id), statement("UPDATE app_webhook_deliveries SET state='cancelled',lease_until=NULL WHERE installation_id=? AND state='pending'", install.id), statement('UPDATE teams SET auth_epoch=auth_epoch+1 WHERE id=?', auth.team_id), ...await appEventStatements(api, auth.team_id, 'app.uninstalled', installJson({ ...install, state: 'uninstalled', uninstalled_at: now }))], { status: 204, body: null, targetId: install.id });
+    closeAppChannels(api,install.id,'app_uninstalled');
+    for(const grant of grants)closeMachineChannels(api,auth.team_id,grant.machine_id,{grantId:grant.id,reason:'app_uninstalled'});
+    api.events.publish(auth.team_id, { type: 'authorization_changed', installation_id:install.id });
+    send(res, 204, null, requestId); return true;
+  }
+  error(404, 'not_found', 'app operation not found');
+}
+
+/** Standard Webhooks: stable delivery id across retries, timestamp refreshed and HMAC over exact body bytes. */
+export async function deliverAppWebhooks(api) {
+  const due = await api.store.query("SELECT id FROM app_webhook_deliveries WHERE state='pending' AND next_at<=? AND (lease_until IS NULL OR lease_until<=?) ORDER BY next_at,id LIMIT 10", [api.clock.nowMs(), api.clock.nowMs()]);
+  for (const { id } of due) {
+    const now = api.clock.nowMs(), lease = now + 30000;
+    try {
+      await api.store.guardedTransaction([guard("SELECT 1 FROM app_webhook_deliveries WHERE id=? AND state='pending' AND (lease_until IS NULL OR lease_until<=?)", [id, now])], [statement('UPDATE app_webhook_deliveries SET lease_until=?,attempts=attempts+1 WHERE id=?', lease, id)]);
+    } catch (e) { if (e.code === 'forbidden') continue; throw e; }
+    const row = await api.store.one(`SELECT d.*,i.signing_secret,i.state installation_state,a.webhook_url,a.state app_state,m.active,installer.active installer_active,installer.role installer_role
+      FROM app_webhook_deliveries d JOIN app_installations i ON i.id=d.installation_id JOIN apps a ON a.id=i.app_id JOIN memberships m ON m.team_id=i.team_id AND m.principal_id=i.principal_id JOIN memberships installer ON installer.team_id=i.team_id AND installer.principal_id=i.installer_id WHERE d.id=?`, [id]);
+    let status = null, delivered = false;
+    if (row.state !== 'pending' || row.installation_state !== 'active' || row.app_state !== 'active' || !row.active || !row.installer_active || !['owner','admin'].includes(row.installer_role)) {
+      await api.store.transaction([statement("UPDATE app_webhook_deliveries SET state='cancelled',lease_until=NULL WHERE id=?", id)]); continue;
+    }
+    try {
+      const secret = unseal(api, row.signing_secret, row.installation_id), timestamp = String(Math.floor(api.clock.nowMs() / 1000));
+      const signature = createHmac('sha256', Buffer.from(secret.slice(6), 'base64')).update(`${id}.${timestamp}.${row.body}`).digest('base64');
+      const response = await fetch(row.webhook_url, { method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(10000), headers: { 'content-type': 'application/json', 'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': `v1,${signature}` }, body: row.body });
+      status = response.status; delivered = status >= 200 && status < 300;
+      await response.body?.cancel();
+    } catch { /* transport/custody failures are retryable; never log secrets, response bodies or credential URLs */ }
+    const state = delivered ? 'delivered' : row.attempts >= 8 ? 'failed' : 'pending';
+    await api.store.transaction([statement("UPDATE app_webhook_deliveries SET state=?,last_status=?,lease_until=NULL,next_at=? WHERE id=? AND lease_until=? AND state='pending'", state, status, api.clock.nowMs() + Math.min(3600000, 1000 * 2 ** row.attempts), id, lease)]);
+  }
+  await api.store.transaction([statement('DELETE FROM app_install_codes WHERE expires_at<=?', api.clock.nowMs()), statement("DELETE FROM app_webhook_deliveries WHERE state!='pending' AND created_at<?", api.clock.nowMs() - 7 * 86400000)]);
+  return due.length >= 10;
+}

package/server/auth.mjs

@@ -3,11 +3,34 @@ export const hashToken = token => createHash('sha256').update(token).digest('hex
 export function makeToken(credentialId, bytes = randomBytes(32)) { return `sct_${credentialId}.${Buffer.from(bytes).toString('base64url')}`; }
 export function tokenMatches(token, digest) { const actual = Buffer.from(hashToken(token)); const expected = Buffer.from(String(digest)); return actual.length === expected.length && timingSafeEqual(actual, expected); }
 export function bearer(header) { const match = /^Bearer ([^\s]+)$/.exec(header ?? ''); return match?.[1] ?? null; }
+/** An absent fence is a root app token; [] grants nothing. Never infer authority from a named actor. */
+export function appGrantAllows(auth, kind, id, action) {
+  return auth?.app_grants == null || auth.app_grants.some(g => g.kind === kind && g.id === id && g.actions.includes(action));
+}
+/** Both app parent and the credential that passed a represented principal's grants stay live. */
+export const APP_LINEAGE = `WITH RECURSIVE lineage(id) AS (
+  SELECT ? UNION SELECT ac.parent_id FROM app_credentials ac JOIN lineage l ON ac.credential_id=l.id WHERE ac.parent_id IS NOT NULL
+  UNION SELECT ac.subject_credential_id FROM app_credentials ac JOIN lineage l ON ac.credential_id=l.id WHERE ac.subject_credential_id IS NOT NULL
+)`;
+export const APP_LINEAGE_REVOKED = `${APP_LINEAGE}
+  SELECT 1 FROM lineage l JOIN credentials c ON c.id=l.id
+  LEFT JOIN memberships m ON m.team_id=c.team_id AND m.principal_id=c.principal_id
+  LEFT JOIN app_credentials ac ON ac.credential_id=c.id
+  LEFT JOIN identity_app_credentials ic ON ic.credential_id=c.id
+  LEFT JOIN app_installations i ON i.id=COALESCE(ac.installation_id,ic.installation_id)
+  LEFT JOIN apps a ON a.id=i.app_id
+  LEFT JOIN memberships installer ON installer.team_id=i.team_id AND installer.principal_id=i.installer_id
+  LEFT JOIN memberships service ON service.team_id=i.team_id AND service.principal_id=i.principal_id
+  WHERE c.revoked_at IS NOT NULL OR (c.expires_at IS NOT NULL AND c.expires_at<=?)
+    OR (c.team_id IS NOT NULL AND COALESCE(m.active,0)!=1)
+    OR (i.id IS NOT NULL AND (i.state!='active' OR a.state!='active' OR COALESCE(installer.active,0)!=1
+      OR installer.role NOT IN ('owner','admin') OR COALESCE(service.active,0)!=1)) LIMIT 1`;
 export function canRead(auth, session, grants = []) {
   if (!auth || !['user','service'].includes(auth.kind) || !auth.active || session.deleted_at != null) return false;
+  if (!appGrantAllows(auth, 'session', session.id, 'sessions.read')) return false;
   if (session.visibility === 'team' || session.custodian_id === auth.principal_id) return true;
   const now = auth.now;
   return grants.some(g => (g.subject_id === auth.principal_id || auth.group_ids?.includes(g.subject_id)) && (g.expires_at == null || g.expires_at > now));
 }
-export function canManage(auth, session, grants = []) { if (!auth?.active || !['user','service'].includes(auth.kind) || auth.role === 'viewer') return false; return session.custodian_id === auth.principal_id || grants.some(g => g.role === 'manager' && (g.subject_id === auth.principal_id || auth.group_ids?.includes(g.subject_id)) && (g.expires_at == null || g.expires_at > auth.now)); }
-export const isAdmin = auth => auth?.active && ['user','service'].includes(auth.kind) && (auth.role === 'owner' || auth.role === 'admin');
+export function canManage(auth, session, grants = []) { if (!auth?.active || !['user','service'].includes(auth.kind) || auth.role === 'viewer' || (auth.app_grants != null && !auth.app_grants.some(g=>g.kind==='session'&&g.id===session.id&&(auth.app_operation_action?g.actions.includes(auth.app_operation_action):g.actions.some(a=>a==='sessions.write'||a==='sessions.access'))))) return false; return session.custodian_id === auth.principal_id || grants.some(g => g.role === 'manager' && (g.subject_id === auth.principal_id || auth.group_ids?.includes(g.subject_id)) && (g.expires_at == null || g.expires_at > auth.now)); }
+export const isAdmin = auth => auth?.active && auth.app_grants == null && ['user','service'].includes(auth.kind) && (auth.role === 'owner' || auth.role === 'admin');

package/server/core.mjs

@@ -1,3 +1,4 @@
+import { deliverAppWebhooks } from './apps.mjs';
 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`),
@@ -14,22 +15,13 @@ const productionIds={next(kind){return `${prefix[kind]??kind}_${randomBytes(16).
 const productionClock={nowMs:()=>Date.now()};
 export { productionIds, productionClock };
 
-export function createTeamsApi({clock=productionClock,ids=productionIds,publicOrigin=null,identityIssuer=null,identityOrganizations=null,delegatedIssuer=null,delegatedIssuers=[],uploadLimitBytes=256*1024*1024}={}) {
-  // An identity service people may sign in with (protocol P02 federation); its tokens name this server's public origin.
-  identityIssuer=normalizePublicOrigin(identityIssuer);
-  if(identityIssuer&&!publicOrigin)throw new TypeError('an identity issuer needs the public origin its tokens name');
-  // A workplace whose delegated tokens admit a caller to one pane or folder (server/delegated.mjs); they name this origin too.
-  delegatedIssuer=normalizePublicOrigin(delegatedIssuer);
-  if(!Array.isArray(delegatedIssuers)||delegatedIssuers.some(origin=>typeof origin!=='string'||!origin.trim()))throw new TypeError('delegatedIssuers must be an array of origins');
-  delegatedIssuers=Object.freeze([...new Set([delegatedIssuer,...delegatedIssuers.map(normalizePublicOrigin)].filter(Boolean))]);
-  if(delegatedIssuers.length&&!publicOrigin)throw new TypeError('a delegated issuer needs the public origin its tokens name');
+export function createTeamsApi({clock=productionClock,ids=productionIds,publicOrigin=null,appRootSecret=null,identityOrganizations=null,uploadLimitBytes=256*1024*1024}={}) {
   if(typeof clock?.nowMs!=='function'||typeof ids?.next!=='function')throw new TypeError('clock.nowMs and ids.next are required');
   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();
   // Teams linked to organizations the identity service keeps for this server (identity-orgs.mjs).
-  if(identityOrganizations&&!identityIssuer)throw new TypeError('organizations need the identity issuer that keeps them');
-  return {clock,ids,events,publicOrigin,identityIssuer,identityOrganizations,delegatedIssuer,delegatedIssuers,uploadLimitBytes,rateState:new Map(),openStreams:new Map(),securityEvents:[],
+  return {clock,ids,events,publicOrigin,appRootSecret,identityOrganizations,uploadLimitBytes,rateState: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;},
   };
@@ -121,7 +113,8 @@ export async function maintain(api){const now=api.clock.nowMs();
   // Presence reconciliation can INSERT. Never put it ahead of the deletes
   // that make room when the database is full.
   await reconcileMachinePresence(api);
-  const result={pruned_versions:stale.length,pruned_parts:parts.length,pruned_idempotency:expired.length,pruned_uploads:orphaned.length,pruned_blobs:unusedBlobs.length,backlog:unusedBlobs.length>=50||orphaned.length>=10||expired.length>=1000||stale.length>=VERSION_PRUNE_BATCH||parts.length>=PART_PRUNE_BATCH};
+  const webhookBacklog=await deliverAppWebhooks(api);
+  const result={pruned_versions:stale.length,pruned_parts:parts.length,pruned_idempotency:expired.length,pruned_uploads:orphaned.length,pruned_blobs:unusedBlobs.length,backlog:webhookBacklog||unusedBlobs.length>=50||orphaned.length>=10||expired.length>=1000||stale.length>=VERSION_PRUNE_BATCH||parts.length>=PART_PRUNE_BATCH};
   if(result.pruned_versions||result.pruned_parts||result.pruned_idempotency||result.pruned_uploads)console.log(`maintain: pruned ${result.pruned_uploads} unreachable bundles, ${result.pruned_idempotency} expired replay records, ${result.pruned_parts} parts, ${result.pruned_versions} versions${result.backlog?' (backlog)':''}`);
   return result;}
 /** Session versions `maintain` removes per run: small enough for one Durable Object alarm; a backlog runs again in seconds. */

package/server/delegated.mjs

@@ -1,6 +1,7 @@
+import { installedIssuer } from './apps.mjs';
 // Delegated access (RH2 RFC 0013, panes and folders): a workplace that decides who may see or drive a pane or a
 // folder signs a short-lived token saying so, and this server admits exactly that, as it admits a machine grant.
-// The workplace is an issuer this server is configured to trust (`delegatedIssuers`, exact origins); its keys are at
+// The workplace issuer is trusted through an admin-consented app installation; its keys are at
 // `<issuer>/.well-known/jwks.json` (Ed25519, EdDSA). A token names the principal, the Surface (its kind, and in its
 // 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.
@@ -67,7 +68,7 @@ async function issuerKey(api, issuer, kid) {
  * and the caller refuses it exactly as an unknown credential.
  */
 export async function delegatedAccessOf(api, token) {
-  const claims = await verifiedClaims(api, token);
+  const claims = await verifiedClaims(api, token, 'delegation.surfaces');
   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);
@@ -81,7 +82,7 @@ export async function delegatedAccessOf(api, token) {
   // 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 };
+  return { installationId:claims.installation_id, installedAt:claims.installed_at, 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. */
@@ -93,7 +94,7 @@ const SESSION_TOKEN_MAX_S = 15 * 60;
  * 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);
+  const claims = await verifiedClaims(api, token, 'delegation.sessions');
   if (!claims) return null;
   const session = claims.session;
   if (!session || typeof session.team !== 'string' || typeof session.id !== 'string' || !session.id) return null;
@@ -105,12 +106,12 @@ export async function delegatedSessionOf(api, token) {
   // from what the browser sends.
   const name = typeof claims.name === 'string' && claims.name.trim() ? claims.name.trim().slice(0, 80) : null;
   const roomContext = claims.roomContext === false ? null : { id: claims.room, name: typeof claims.roomName === 'string' ? claims.roomName.slice(0, 120) : claims.room, sender: claims.sub };
-  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 };
+  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 };
 }
 
 /** 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);
+  const c = await verifiedClaims(api, token, 'delegation.notices');
   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;
@@ -119,22 +120,24 @@ export async function delegatedRoomNoticeOf(api, token) {
       || 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,
+  return { installationId:c.installation_id, installedAt:c.installed_at, 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.delegatedIssuers.length || !api.publicOrigin || !looksDelegated(token)) return null;
+async function verifiedClaims(api, token, action) {
+  if (!api.publicOrigin || !looksDelegated(token)) return null;
   try {
     const [head, body, signature] = token.split('.');
     const header = json(head);
     if (header.alg !== 'EdDSA' || typeof header.kid !== 'string') return null;
-    // Only configured origins may select keys; an untrusted claim never triggers a fetch.
+    // 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);
-    if (!api.delegatedIssuers.includes(claims.iss) || claims.aud !== api.publicOrigin) return null;
+    const teamId=claims.surface?.config?.team??claims.session?.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);
     if (!key) return null;
     const signed = new TextEncoder().encode(`${head}.${body}`);
@@ -142,7 +145,7 @@ async function verifiedClaims(api, token) {
     const now = Math.floor(api.clock.nowMs() / 1000);
     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;
-    return claims;
+    return {...claims, installation_id:installation.id,installed_at:installation.created_at};
   } catch {
     return null;
   }

package/server/http.mjs

@@ -1,3 +1,4 @@
+import { appRoute, appPreAuth, appAuthentication, enforceAppScope, appAuthGuards, installedIssuer } from './apps.mjs';
 import { machineEventStream } from './machine-events.mjs';
 import { randomBytes } from 'node:crypto';
 import { bearer, hashToken, canManage, isAdmin, makeToken } from './auth.mjs';
@@ -13,10 +14,10 @@ class HttpError extends Error { constructor(status,code,message,details=null){su
 const fail=(status,code,message,details)=>{throw new HttpError(status,code,message,details)};
 const parseJson=req=>parseRequestJson(req,fail);
 const result=(api,auth,data)=>({version:1,context:{server_id:api.serverId,team_id:auth.team_id,principal_id:auth.principal_id},data});
-function sideEffectStatements(api,res,status,body,now,targetId=null,journal=false){const statements=[];if(status<400&&res._idempotencyRecord){const record=res._idempotencyRecord,safe=redactSecretReplay(record.path,body);statements.push({sql:'INSERT INTO idempotency(team_id,principal_id,route,key,request_digest,response_status,response_json,expires_at) VALUES (?,?,?,?,?,?,?,?)',params:[record.teamId,record.principalId,record.route,record.key,record.requestDigest,status,journal?{$journalJsonValue:safe}:JSON.stringify(safe),now+86400000]});}if(res._auditRecord){const record=res._auditRecord;statements.push({sql:'INSERT INTO audit(team_id,id,actor_id,operation,target_id,outcome,revision,created_at) VALUES (?,?,?,?,?,?,?,?)',params:[record.teamId,api.ids.next('audit'),record.actorId,record.operation,targetId,status<400?'allowed':'denied',journal?{$journalRevision:true}:null,now]});}return statements;}
+function sideEffectStatements(api,res,status,body,now,targetId=null,journal=false){const statements=[];if(status<400&&res._idempotencyRecord){const record=res._idempotencyRecord,safe=redactSecretReplay(record.path,body);statements.push({sql:'INSERT INTO idempotency(team_id,principal_id,route,key,request_digest,response_status,response_json,expires_at) VALUES (?,?,?,?,?,?,?,?)',params:[record.teamId,record.principalId,record.route,record.key,record.requestDigest,status,journal?{$journalJsonValue:safe}:JSON.stringify(safe),now+86400000]});}if(res._auditRecord){const record=res._auditRecord;statements.push({sql:'INSERT INTO audit(team_id,id,actor_id,operation,target_id,outcome,revision,created_at,actor_json) VALUES (?,?,?,?,?,?,?,?,?)',params:[record.teamId,api.ids.next('audit'),record.actorId,record.operation,targetId,status<400?'allowed':'denied',journal?{$journalRevision:true}:null,now,JSON.stringify(record.act??[])]});}return statements;}
 async function persistSideEffects(api,res,status,body){const statements=sideEffectStatements(api,res,status,body,api.clock.nowMs());if(statements.length)await api.store.transaction(statements);}
 function send(res,status,body,requestId,headers={}){const deliver=()=>{res.writeHead(status,{'Content-Type':'application/json; charset=utf-8','Cache-Control':'no-store','X-Request-ID':requestId,...headers});res.end(body===null?'':JSON.stringify(body));};if(!res._sideEffectsCommitted&&res._api&&(res._idempotencyRecord||res._auditRecord))return persistSideEffects(res._api,res,status,body).then(deliver);deliver();}
-async function guardedMutation(api,res,auth,guards,statements,{status,body,targetId=null,journal=false}){const now=api.clock.nowMs(),all=[...statements,...sideEffectStatements(api,res,status,body,now,targetId,journal)],result=journal?await api.store.journalTransaction(auth.team_id,guards,all):await api.store.guardedTransaction(guards,all);res._sideEffectsCommitted=true;return result;}
+async function guardedMutation(api,res,auth,guards,statements,{status,body,targetId=null,journal=false}){const now=api.clock.nowMs(),all=[...statements,...sideEffectStatements(api,res,status,body,now,targetId,journal)],result=journal?await api.store.journalTransaction(auth.team_id,[...guards,...appAuthGuards(auth,now)],all):await api.store.guardedTransaction([...guards,...appAuthGuards(auth,now)],all);res._sideEffectsCommitted=true;return result;}
 const requireRevision=(req,current,label='resource')=>{const expected=Number(String(req.headers['if-match']??'').replaceAll('"',''));if(!Number.isSafeInteger(expected))fail(400,'invalid_request','If-Match is required');if(expected!==current)fail(409,'revision_mismatch',`${label} revision changed`);return expected;};
 const CORS={'Access-Control-Allow-Origin':'*','Access-Control-Expose-Headers':'ETag, X-Request-ID, Content-Range'};
 const esc=(x)=>String(x).replace(/[\\%_]/g,'\\$&');
@@ -30,8 +31,11 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   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.
   if(req.method==='GET'&&(path==='/view'||path.startsWith('/view/'))&&await serveViewer(res,path))return;
+  if(path==='/api/v1/apps/token')checkRate(api,`app-exchange:${req.socket.remoteAddress}`,10,5);
+  if(await appPreAuth({api,req,res,path,requestId,parseJson,send}))return;
   if(api.harnessRoutes&&await api.harnessRoutes.preAuth({api,req,res,path,requestId}))return;
   const auth=await authenticate(api,bearer(req.headers.authorization));res._authenticated=Boolean(auth);
+  if(auth?.installation_id){const scoped=/^\/api\/v1\/teams\/([^/]+)(\/.*)?$/.exec(path);if(scoped&&scoped[1]!==auth.team_id)fail(403,'forbidden','app token belongs to another organization');const target=scoped?.[2]??path.replace(/^\/api\/v1/,'');if(target===`/app-installations/${auth.installation_id}/delegations`&&req.method==='POST'){}else enforceAppScope(auth,req.method,target);}
   if(api.harnessRoutes&&await api.harnessRoutes.authed({api,req,res,auth,path,requestId}))return;
   if(req.method==='POST'&&path==='/api/v1/invitations/accept'){checkRate(api,`login:${req.socket.remoteAddress}`,10,5);const body=await parseJson(req);return await acceptInvite(api,res,body,requestId);}
   if(req.method==='POST'&&path==='/api/v1/login/volter'){checkRate(api,`login:${req.socket.remoteAddress}`,10,5);const body=await parseJson(req);return await identityLogin(api,res,body,requestId);}
@@ -42,12 +46,12 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   checkRate(api,`credential:${auth.credential_id}:${bulk?'bulk':'ordinary'}`,bulk||auth.kind==='machine'?600:120,bulk||auth.kind==='machine'?60:30);
   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/capabilities')return send(res,200,{version:1,server_id:api.serverId,protocol:'teams.v1',operations:['catalog','search','read','follow','access','ingest'],auth_modes:['token','invitation',...(api.identityIssuer?['volter']:[])],...(api.identityIssuer?{identity:{issuer:api.identityIssuer,audience:api.publicOrigin}}:{})},requestId);
+  if(req.method==='GET'&&path==='/api/v1/capabilities')return send(res,200,{version:1,server_id:api.serverId,protocol:'teams.v1',operations:['catalog','search','read','follow','access','ingest'],auth_modes:['token','invitation','installed-app'],app_token_exchange:'/api/v1/apps/token'},requestId);
   if(req.method==='GET'&&path==='/api/v1/teams')return await listTeams(api,res,auth,url,requestId);
   if(req.method==='POST'&&path==='/api/v1/teams')return await createTeam(api,req,res,auth,path,requestId);
   const match=/^\/api\/v1\/teams\/([^/]+)(\/.*)?$/.exec(path);if(!match)fail(404,'not_found','not found');const teamId=match[1],sub=match[2]??'';
   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(req.method!=='GET')res._auditRecord={teamId:auth.team_id,actorId:auth.principal_id,act:auth.act??[],operation:`${req.method} ${path}`};
   if(['machine','ingest'].includes(auth.kind)){
     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`);
@@ -56,6 +60,7 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   let m;if(api.harnessRoutes&&await api.harnessRoutes.beforeIdempotency({api,req,res,auth,url,path,sub,requestId}))return;
   const intrinsicPart=req.method==='PUT'&&(/\/captures\/[^/]+\/parts\/\d+$/.test(sub)||/\/uploads\/[^/]+\/chunks\/\d+$/.test(sub)),intrinsicReplay=intrinsicPart||(req.method==='POST'&&(/^\/sources\/[^/]+\/captures$/.test(sub)||/\/captures\/[^/]+\/commit$/.test(sub)||/\/effects\/[^/]+\/(?:claim|result)$/.test(sub)));
   if(['POST','PATCH','DELETE'].includes(req.method)&&!intrinsicPart){const key=req.headers['idempotency-key'];if(typeof key!=='string'||key.length<16||key.length>128||!/^[\x20-\x7e]+$/.test(key))fail(400,'invalid_request','Idempotency-Key must be 16..128 printable ASCII characters');if(!intrinsicReplay){const body=req.method==='DELETE'?null:await parseJson(req),route=`${req.method} ${path}`,requestDigest=sha256(canonicalJson({method:req.method,path,if_match:req.headers['if-match']??null,body})),old=await api.store.one('SELECT * FROM idempotency WHERE team_id=? AND principal_id=? AND route=? AND key=? AND expires_at>?',[auth.team_id,auth.principal_id,route,key,api.clock.nowMs()]);if(old){if(old.request_digest!==requestDigest)fail(409,'idempotency_conflict','idempotency key was reused with a different request');await authorizeReplay(api,auth,req.method,sub,body);return send(res,old.response_status,JSON.parse(old.response_json),requestId);}res._idempotencyRecord={teamId:auth.team_id,principalId:auth.principal_id,route,key,requestDigest,path};}}
+  if(await appRoute({api,req,res,auth,sub,requestId,parseJson,send,result,guardedMutation}))return;
   if(req.method==='POST'&&sub==='/invitations')return await createInvitation(api,req,res,auth,requestId);
   if(req.method==='POST'&&sub==='/credentials')return await createCredential(api,req,res,auth,requestId);
   if(req.method==='DELETE'&&(m=/^\/credentials\/([^/]+)$/.exec(sub)))return await revokeCredential(api,req,res,auth,m[1],requestId);
@@ -85,11 +90,12 @@ export function createHttpHandler(api){return async(req,res)=>{const requestId=a
   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);}};}
 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'))copy.data=null;return copy;}
+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;}
 
 async function authorizeReplay(api,auth,method,sub,body){
   const now=api.clock.nowMs();
   let match;
+  if(sub.startsWith('/apps')||sub.startsWith('/app-installations')){if(auth.installation_id&&sub===`/app-installations/${auth.installation_id}/delegations`&&method==='POST')return;if(!isAdmin(auth)||auth.installation_id)fail(403,'forbidden','application admin authorization changed');return;}
   if((match=/^\/sources\/([^/]+)\/captures$/.exec(sub))){const source=await api.store.one('SELECT state,machine_id,visibility FROM sources WHERE team_id=? AND id=?',[auth.team_id,match[1]]);if(!source||source.state!=='active'||auth.source_id!==match[1])fail(403,'forbidden','source authorization changed');if(auth.kind==='machine'){const rule=await api.store.one("SELECT 1 ok FROM machines m JOIN sync_rules r ON r.team_id=m.team_id AND r.machine_id=m.id WHERE m.team_id=? AND m.id=? AND m.revoked_at IS NULL AND r.id=? AND r.source_id=? AND r.state='active' AND r.revision=? AND r.visibility=?",[auth.team_id,auth.machine_id,body?.rule_id,match[1],body?.rule_revision,body?.visibility]);if(!rule)fail(403,'forbidden','sync rule authorization changed');}else if(auth.kind!=='ingest'||body?.visibility!==source.visibility)fail(403,'forbidden','source policy changed');return;}
   if((match=/^\/machines\/([^/]+)\/heartbeat$/.exec(sub))&&auth.kind==='machine'){const machine=await api.store.one('SELECT 1 ok FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL',[auth.team_id,match[1]]);if(!machine||auth.machine_id!==match[1])fail(403,'forbidden','machine authorization changed');return;}
   if(!['user','service'].includes(auth.kind))fail(403,'forbidden','credential kind cannot replay this operation');
@@ -105,7 +111,7 @@ async function authorizeReplay(api,auth,method,sub,body){
   if(sub==='/correlations'&&method==='POST'){if(auth.role==='viewer')fail(403,'forbidden','correlation authorization changed');return;}
 }
 
-export async function authenticate(api,token){if(!token)return null;const digest=hashToken(token);const auth=await api.store.one(`SELECT c.id credential_id,c.kind,c.team_id,c.source_id,c.machine_id,c.principal_id,p.kind principal_kind,p.display_name,m.role,m.active FROM credentials c JOIN principals p ON p.id=c.principal_id LEFT JOIN memberships m ON m.team_id=c.team_id AND m.principal_id=c.principal_id WHERE c.token_hash=? AND c.revoked_at IS NULL AND (c.expires_at IS NULL OR c.expires_at>?)`,[digest,api.clock.nowMs()]);if(auth?.team_id)auth.group_ids=(await api.store.query('SELECT group_id FROM group_members WHERE team_id=? AND principal_id=?',[auth.team_id,auth.principal_id])).map(x=>x.group_id);return auth;}
+export async function authenticate(api,token){if(!token)return null;const digest=hashToken(token);const auth=await api.store.one(`SELECT c.id credential_id,c.expires_at,c.kind,c.team_id,c.source_id,c.machine_id,c.principal_id,p.kind principal_kind,p.display_name,m.role,m.active FROM credentials c JOIN principals p ON p.id=c.principal_id LEFT JOIN memberships m ON m.team_id=c.team_id AND m.principal_id=c.principal_id WHERE c.token_hash=? AND c.revoked_at IS NULL AND (c.expires_at IS NULL OR c.expires_at>?)`,[digest,api.clock.nowMs()]);if(auth?.team_id)auth.group_ids=(await api.store.query('SELECT group_id FROM group_members WHERE team_id=? AND principal_id=?',[auth.team_id,auth.principal_id])).map(x=>x.group_id);return await appAuthentication(api,auth);}
 async function grants(api,team,id){return api.store.query('SELECT * FROM session_grants WHERE team_id=? AND session_id=?',[team,id]);}
 const authGuards=(auth,_admissionNow)=>{
   const now=auth.clock?.nowMs()??_admissionNow;
@@ -131,7 +137,7 @@ async function createTeam(api,req,res,auth,path,requestId){
 }
 async function createCredential(api,req,res,auth,requestId){
   if(auth.kind!=='user')fail(403,'forbidden','only users may issue credentials');const body=await parseJson(req);exact(body,['kind','expires_in_ms']);const maxExpiry=body.kind==='service'?7776000000:2592000000;if(!['user','service'].includes(body.kind)||!Number.isSafeInteger(body.expires_in_ms)||body.expires_in_ms<1||body.expires_in_ms>maxExpiry)fail(400,'invalid_request','invalid credential request');
-  const id=api.ids.next('credential'),token=makeToken(id),now=api.clock.nowMs(),expiresAt=now+body.expires_in_ms,response=result(api,auth,{token,kind:body.kind,expires_at:expiresAt});await guardedMutation(api,res,auth,authGuards(auth,now),[{sql:'INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,?,?,?,?)',params:[id,hashToken(token),auth.principal_id,body.kind,body.kind==='user'?null:auth.team_id,expiresAt,now]}],{status:201,body:response,targetId:id});send(res,201,response,requestId);
+  const id=api.ids.next('credential'),token=makeToken(id),now=api.clock.nowMs(),expiresAt=now+body.expires_in_ms,response=result(api,auth,{token,kind:body.kind,expires_at:expiresAt});await guardedMutation(api,res,auth,authGuards(auth,now),[{sql:'INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,?,?,?,?)',params:[id,hashToken(token),auth.principal_id,body.kind,body.kind==='user'&&!auth.identity_installation_id?null:auth.team_id,expiresAt,now]},...(auth.identity_installation_id?[{sql:'INSERT INTO identity_app_credentials(credential_id,installation_id) VALUES (?,?)',params:[id,auth.identity_installation_id]}]:[])],{status:201,body:response,targetId:id});send(res,201,response,requestId);
 }
 async function revokeCredential(api,req,res,auth,id,requestId){
   if(!['user','service'].includes(auth.kind))fail(403,'forbidden','credential kind cannot use this operation');const credential=await api.store.one('SELECT * FROM credentials WHERE id=? AND revoked_at IS NULL',[id]);if(!credential)fail(404,'not_found','not found');const globalUser=credential.kind==='user'&&credential.team_id===null;if(globalUser?credential.principal_id!==auth.principal_id:credential.team_id!==auth.team_id||credential.principal_id!==auth.principal_id&&!isAdmin(auth))fail(404,'not_found','not found');
@@ -140,7 +146,7 @@ async function revokeCredential(api,req,res,auth,id,requestId){
 async function createInvitation(api,req,res,auth,requestId){if(!isAdmin(auth))fail(403,'forbidden','forbidden');const body=await parseJson(req);exact(body,['display_name','role','expires_in_ms']);if(!['admin','member','viewer'].includes(body.role)||!Number.isSafeInteger(body.expires_in_ms)||body.expires_in_ms<1||body.expires_in_ms>604800000)fail(400,'invalid_request','invalid invitation');const pid=api.ids.next('user'),iid=api.ids.next('invitation'),secret=`sci_${iid}.${randomBytes(32).toString('base64url')}`,now=api.clock.nowMs(),exp=now+body.expires_in_ms,response=result(api,auth,{id:iid,role:body.role,expires_at:exp,enrollment_code:secret});await guardedMutation(api,res,auth,authGuards(auth,now),[{sql:'INSERT INTO principals(id,kind,display_name) VALUES (?,?,?)',params:[pid,'user',body.display_name]},{sql:'INSERT INTO invitations(team_id,id,principal_id,secret_hash,role,expires_at) VALUES (?,?,?,?,?,?)',params:[auth.team_id,iid,pid,hashToken(secret),body.role,exp]}],{status:201,body:response,targetId:iid});send(res,201,response,requestId);}
 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);}
+  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 installation=person?await installedIssuer(api,person.issuer,'identity.login',inv.team_id):null;if(person&&!installation)fail(401,'authentication_required','identity app is not installed in the invitation organization');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'},...(installation?[{sql:"SELECT 1 FROM app_installations WHERE id=? AND state='active'",params:[installation.id],code:'authentication_required',status:401,message:'identity app was uninstalled'}]:[])],[{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',installation?inv.team_id:null,now+2592000000,now]},...(installation?[{sql:'INSERT INTO identity_app_credentials(credential_id,installation_id) VALUES (?,?)',params:[cid,installation.id]}]:[]),{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 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){
@@ -155,8 +161,9 @@ async function identityLogin(api,res,body,requestId){
   // with no invitation (identity-orgs.mjs): they join as members, exactly as an accepted invitation would add them.
   if(!row)row=await joinThroughOrganization(api,person,body.team_id)&&await memberRow();
   if(!row)fail(401,'authentication_required','no member of this team is linked to that identity; accept an invitation with it, or link it while signed in');
+  const installation=await installedIssuer(api,person.issuer,'identity.login',row.team_id);if(!installation)fail(401,'authentication_required','identity app is not installed in this organization');
   const now=api.clock.nowMs(),cid=api.ids.next('credential'),token=makeToken(cid);
-  await api.store.transaction([{sql:'INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,?,?,?,?)',params:[cid,hashToken(token),row.principal_id,'user',null,now+2592000000,now]}]);
+  await api.store.guardedTransaction([{sql:"SELECT 1 FROM app_installations i JOIN apps a ON a.id=i.app_id WHERE i.id=? AND i.state='active' AND a.state='active'",params:[installation.id],code:'authentication_required',status:401,message:'identity app was uninstalled'}],[{sql:'INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,?,?,?,?)',params:[cid,hashToken(token),row.principal_id,'user',row.team_id,now+2592000000,now]},{sql:'INSERT INTO identity_app_credentials(credential_id,installation_id) VALUES (?,?)',params:[cid,installation.id]}]);
   send(res,201,{principal:{id:row.principal_id,kind:'user',display_name:row.display_name},credential:{token,kind:'user',expires_at:now+2592000000},team:{id:row.team_id,name:row.team_name,revision:row.team_revision}},requestId);
 }
 /** The one team a signed-in person belongs to, as a member or through a linked organization. */
@@ -174,12 +181,13 @@ async function teamsOfPerson(api,person){
   const ever=new Set((await api.store.query('SELECT m.team_id FROM principal_identities i JOIN memberships m ON m.principal_id=i.principal_id WHERE i.issuer=? AND i.subject=?',[person.issuer,person.subject])).map(row=>row.team_id));
   const linked=[];
   // An organization the door cannot answer for offers no team: the teams the person is a member of still list.
-  for(const team of await api.store.query('SELECT id,name FROM teams ORDER BY name',[])){if(ever.has(team.id))continue;const slug=linkedOrganization(api,team);if(slug&&await inOrganization(api,person.subject,slug).catch(()=>false))linked.push(team);}
+  for(const team of await api.store.query('SELECT id,name FROM teams ORDER BY name',[])){if(ever.has(team.id)||!await installedIssuer(api,person.issuer,'identity.login',team.id))continue;const slug=linkedOrganization(api,team);if(slug&&await inOrganization({...api,identityIssuer:person.issuer},person.subject,slug).catch(()=>false))linked.push(team);}
   return {member,linked};
 }
 /** The teams a signed-in person is an active member of, with their role. */
-function teamsOfMember(api,person){
-  return api.store.query('SELECT t.id,t.name,m.role FROM principal_identities i JOIN memberships m ON m.principal_id=i.principal_id AND m.active=1 JOIN teams t ON t.id=m.team_id WHERE i.issuer=? AND i.subject=? ORDER BY t.name',[person.issuer,person.subject]);
+async function teamsOfMember(api,person){
+  const rows=await api.store.query('SELECT t.id,t.name,m.role FROM principal_identities i JOIN memberships m ON m.principal_id=i.principal_id AND m.active=1 JOIN teams t ON t.id=m.team_id WHERE i.issuer=? AND i.subject=? ORDER BY t.name',[person.issuer,person.subject]);
+  const permitted=[];for(const row of rows)if(await installedIssuer(api,person.issuer,'identity.login',row.id))permitted.push(row);return permitted;
 }
 /** Which teams a verified identity token may sign in to, so a person on several chooses rather than being refused. */
 async function identityTeams(api,res,body,requestId){
@@ -190,9 +198,9 @@ async function identityTeams(api,res,body,requestId){
 }
 /** Make `person` a member of team `team` when the team is linked to an organization they belong to; true if joined. */
 async function joinThroughOrganization(api,person,team){
-  const found=await api.store.one('SELECT id,name FROM teams WHERE id=? OR name=?',[team,team]);if(!found)return false;
+  const found=await api.store.one('SELECT id,name FROM teams WHERE id=? OR name=?',[team,team]);if(!found||!await installedIssuer(api,person.issuer,'identity.login',found.id))return false;
   const slug=linkedOrganization(api,found);if(!slug)return false;
-  if(!await inOrganization(api,person.subject,slug))return false;
+  if(!await inOrganization({...api,identityIssuer:person.issuer},person.subject,slug))return false;
   const now=api.clock.nowMs(),linked=await api.store.one('SELECT principal_id FROM principal_identities WHERE issuer=? AND subject=?',[person.issuer,person.subject]);
   const pid=linked?.principal_id??api.ids.next('user');
   const statements=[];

package/server/identity.mjs

@@ -1,3 +1,4 @@
+import { installedIssuer } from './apps.mjs';
 // Federation (protocol P02): a person signed in with an identity service
 // (Volter, https://id.volter.ai) proves who they are with an access token
 // whose audience is this server's public origin, verified from the issuer's
@@ -7,9 +8,12 @@ import { verifyIdentityToken } from '@volter/identity';
 
 /** The issuer and subject a token names, or null when it does not verify or no issuer is configured. */
 export async function identityOf(api, token) {
-  if (!api.identityIssuer || !api.publicOrigin || typeof token !== 'string' || !token) return null;
+  if (!api.publicOrigin || typeof token !== 'string' || !token || token.length>32768) return null;
   try {
-    const person = await verifyIdentityToken(token, { issuer: api.identityIssuer, audience: api.publicOrigin });
-    return { issuer: api.identityIssuer, subject: person.subject, email: person.email ?? null, name: person.name ?? null };
+    // Unverified iss only selects an already installed issuer; it never chooses an arbitrary key URL.
+    const claims=JSON.parse(Buffer.from(token.split('.')[1]??'', 'base64url').toString('utf8'));
+    if(typeof claims.iss!=='string'||!await installedIssuer(api,claims.iss,'identity.login'))return null;
+    const person=await verifyIdentityToken(token,{issuer:claims.iss,audience:api.publicOrigin});
+    return {issuer:claims.iss,subject:person.subject,email:person.email??null,name:person.name??null};
   } catch { return null; }
 }

package/server/machine-link.mjs

@@ -1,3 +1,4 @@
+import { appAuthentication } from './apps.mjs';
 // Machine doors through the server (design §11).
 //
 //   GET  /api/v1/teams/{team}/machines/{id}/link     the machine's one outbound link
@@ -55,8 +56,13 @@ export async function machineGrantRows(api, teamId, 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.installation_id&&auth.kind!=='delegated'&&!await appAuthentication(api,auth))return null;
   if (auth.kind === 'delegated') {
-    const row = await api.store.one('SELECT id, revision FROM machine_grants WHERE team_id=? AND machine_id=? AND id=? AND expires_at>?', [auth.team_id, machineId, auth.grant_id, api.clock.nowMs()]);
+    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
+      JOIN memberships service ON service.team_id=i.team_id AND service.principal_id=i.principal_id
+      WHERE g.team_id=? AND g.machine_id=? AND g.id=? AND g.expires_at>? AND i.state='active' AND a.state='active'
+        AND installer.active=1 AND installer.role IN ('owner','admin') AND service.active=1`,[auth.team_id,machineId,auth.grant_id,api.clock.nowMs()]);
     return row ? { principal: auth.principal_id, groups: [], grants: [row.id], revisions: { [row.id]: row.revision }, ...(auth.name ? { name: auth.name } : {}), ...(auth.roomContext ? { roomContext: auth.roomContext } : {}) } : null;
   }
   const machine = await api.store.one('SELECT custodian_id FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', [auth.team_id, machineId]);
@@ -87,6 +93,11 @@ export function closeChannelsFor(api, teamId, { principalId = null, groupId = nu
   return closed;
 }
 
+/** Installation revocation closes its channels even when the bearer names another principal. */
+export function closeAppChannels(api,installationId,reason='app_uninstalled'){
+  for(const entry of channels(api))if(entry.installationId===installationId)entry.close(reason);
+}
+
 /** Close the channels a revocation or machine removal leaves without authority; the next stream would be refused anyway. */
 export function closeMachineChannels(api, teamId, machineId, { grantId = null, reason = 'access_revoked' } = {}) {
   let closed = 0;
@@ -130,7 +141,7 @@ export async function machineGrantRoute({ api, req, res, auth, machineId, grantI
     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 };
     const response = result(api, auth, row);
     await guardedMutation(api, res, auth, [{ sql: 'SELECT 1 ok FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', params: [auth.team_id, machineId], code: 'not_found', status: 404, message: 'machine not found' }], [
-      { sql: 'INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at) VALUES (?,?,?,?,?,?,?,?,?)', params: [auth.team_id, id, machineId, body.subject_id, JSON.stringify(body.caps), JSON.stringify(body.targets), auth.principal_id, now, body.expires_at] },
+      { sql: 'INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at,app_installation_id) VALUES (?,?,?,?,?,?,?,?,?,?)', params: [auth.team_id, id, machineId, body.subject_id, JSON.stringify(body.caps), JSON.stringify(body.targets), auth.principal_id, now, body.expires_at, auth.installation_id??null] },
     ], { status: 201, body: response, targetId: id });
     return send(res, 201, response, requestId, { ETag: '"1"' });
   }
@@ -157,11 +168,11 @@ export async function authorizeMachineUpgrade(api, { authenticate, url, headers
   const presented = bearerFrom(headers);
   // A Room member typing into a session bound to their Room: the session names the machine, the server finds it.
   const session = /^\/api\/v1\/teams\/([^/]+)\/sessions\/([^/]+)\/channel$/.exec(pathname);
-  if (session) return api.delegatedIssuers.length && looksDelegated(presented) ? await delegatedSessionChannel(api, session[1], decodeURIComponent(session[2]), presented) : { status: 404, code: 'not_found', message: 'not found' };
+  if (session) return looksDelegated(presented) ? await delegatedSessionChannel(api, session[1], decodeURIComponent(session[2]), presented) : { status: 404, code: 'not_found', message: 'not found' };
   const match = /^\/api\/v1\/teams\/([^/]+)\/machines\/([^/]+)\/(link|channel)$/.exec(pathname);
   if (!match) return { status: 404, code: 'not_found', message: 'not found' };
   const [, teamId, machineId, door] = match;
-  if (door === 'channel' && api.delegatedIssuers.length && looksDelegated(presented)) return await delegatedChannel(api, teamId, machineId, presented);
+  if (door === 'channel' && looksDelegated(presented)) return await delegatedChannel(api, teamId, machineId, presented);
   const auth = await authenticate(api, presented);
   if (!auth) return { status: 401, code: 'authentication_required', message: 'authentication required' };
   if (door === 'link') {
@@ -176,6 +187,7 @@ export async function authorizeMachineUpgrade(api, { authenticate, url, headers
     if (!membership?.active) return { status: 401, code: 'authentication_required', message: 'authentication required' };
     Object.assign(auth, { team_id: teamId, role: membership.role, active: membership.active, group_ids: (await api.store.query('SELECT group_id FROM group_members WHERE team_id=? AND principal_id=?', [teamId, auth.principal_id])).map((row) => row.group_id) });
   } else if (auth.team_id !== teamId || !auth.active) return { status: 401, code: 'authentication_required', message: 'authentication required' };
+  if(auth.installation_id){if(!auth.app_actions.includes('machines.control'))return {status:403,code:'forbidden',message:'app lacks machines.control scope'};}
   if (!await claimFor(api, auth, machineId)) return { status: 404, code: 'not_found', message: 'machine not found' };
   return { door, teamId, machineId, auth };
 }
@@ -184,6 +196,16 @@ export async function authorizeMachineUpgrade(api, { authenticate, url, headers
  * 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.
  */
+function installedGuard(access,action){
+  return {sql:`SELECT 1 FROM app_installations i 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
+    JOIN memberships service ON service.team_id=i.team_id AND service.principal_id=i.principal_id
+    WHERE i.id=? AND i.team_id=? AND i.created_at=? AND i.state='active' AND a.state='active'
+      AND installer.active=1 AND installer.role IN ('owner','admin') AND service.active=1
+      AND EXISTS (SELECT 1 FROM json_each(i.actions_json) WHERE value=?)`,
+    params:[access.installationId,access.teamId,access.installedAt,action],status:404,code:'not_found',message:'integration authorization changed'};
+}
+
 async function delegatedChannel(api, teamId, machineId, token) {
   const access = await delegatedAccessOf(api, token);
   if (!access) return { status: 401, code: 'authentication_required', message: 'authentication required' };
@@ -197,18 +219,19 @@ async function delegatedChannel(api, teamId, machineId, token) {
     // 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([
+      installedGuard(access,'delegation.surfaces'),
       { 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(surfaceCaps(access.kind, access.scope, publication.max_scope)), JSON.stringify([publication.target]), issuer, now, access.expiresAt] },
+      { sql: 'INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at,app_installation_id) VALUES (?,?,?,?,?,?,?,?,?,?)', params: [teamId, id, machineId, principal, JSON.stringify(surfaceCaps(access.kind, access.scope, publication.max_scope)), JSON.stringify([publication.target]), issuer, now, access.expiresAt, access.installationId] },
     ]);
   } 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 } };
+  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 } };
 }
 
 /**
@@ -227,12 +250,13 @@ async function delegatedSessionChannel(api, teamId, sessionRef, token) {
   const now = api.clock.nowMs(), id = api.ids.next('grant'), principal = delegatedPrincipal(access);
   const issuer = `delegated:${new URL(access.issuer).host}:session:${target.sessionId}`;
   await api.store.guardedTransaction([
+    installedGuard(access,'delegation.sessions'),
     { sql: 'SELECT 1 ok FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', params: [teamId, target.machineId], code: 'not_found', status: 404, message: 'session not found' },
   ], [
     { 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, target.machineId, principal, JSON.stringify(access.scope === 'control' ? ['observe', 'interact'] : ['observe']), JSON.stringify([`session:${target.harness}/${target.nativeId}`]), issuer, now, access.expiresAt] },
+    { sql: 'INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at,app_installation_id) VALUES (?,?,?,?,?,?,?,?,?,?)', params: [teamId, id, target.machineId, principal, JSON.stringify(access.scope === 'control' ? ['observe', 'interact'] : ['observe']), JSON.stringify([`session:${target.harness}/${target.nativeId}`]), issuer, now, access.expiresAt, access.installationId] },
   ]).catch((error) => { if (error.code !== 'not_found') throw error; return null; });
-  return { door: 'channel', teamId, machineId: target.machineId, auth: { kind: 'delegated', team_id: teamId, principal_id: principal, group_ids: [], grant_id: id, grant_issuer: issuer, expires_at: access.expiresAt, name: access.name, roomContext: access.roomContext } };
+  return { door: 'channel', teamId, machineId: target.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, name: access.name, roomContext: access.roomContext } };
 }
 
 /**
@@ -331,13 +355,13 @@ 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, grantIssuer: auth.grant_issuer ?? null,
+    teamId: auth.team_id, machineId, installationId:auth.installation_id??null, 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); },
   };
   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' ? setTimeout(() => entry.close('token_expired'), Math.max(0, auth.expires_at - api.clock.nowMs())) : null;
+  const expiry = (auth.kind === 'delegated'||(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;
   channel.on('error', () => {});
   channel.on('close', () => { if (expiry) clearTimeout(expiry); channels(api).delete(entry); entry.dropStreams('caller closed'); });
   channel.on('stream', async (stream, accept, refuse) => {
@@ -393,8 +417,8 @@ export async function deliverSessionRoomNotice(api, access) {
   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] }]);
+    await api.store.guardedTransaction([installedGuard(access,'delegation.notices')],[{ sql: 'INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at,app_installation_id) VALUES (?,?,?,?,?,?,?,?,?,?)',
+      params: [access.teamId, id, target.machineId, principal, JSON.stringify(['mail']), JSON.stringify([`mail:${to}`]), `delegated:room-notice:${digest}`, now, access.expiresAt, access.installationId] }]);
     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');

package/server/migrations/013.mjs

@@ -0,0 +1,38 @@
+// Apps own settings and foreign-id maps outside Teams. These rows are consent and credentials only.
+export default `
+ALTER TABLE audit ADD COLUMN actor_json TEXT NOT NULL DEFAULT '[]' CHECK(json_valid(actor_json));
+CREATE TABLE apps (
+  id TEXT PRIMARY KEY, team_id TEXT NOT NULL REFERENCES teams(id),
+  principal_id TEXT NOT NULL REFERENCES principals(id), name TEXT NOT NULL, description TEXT NOT NULL,
+  actions_json TEXT NOT NULL CHECK(json_valid(actions_json)), events_json TEXT NOT NULL CHECK(json_valid(events_json)),
+  redirect_urls_json TEXT NOT NULL CHECK(json_valid(redirect_urls_json)), webhook_url TEXT, issuer TEXT,
+  secret_hash TEXT NOT NULL, state TEXT NOT NULL CHECK(state IN ('active','retired')), created_at INTEGER NOT NULL
+) STRICT;
+CREATE TABLE app_installations (
+  id TEXT PRIMARY KEY, app_id TEXT NOT NULL REFERENCES apps(id), team_id TEXT NOT NULL REFERENCES teams(id),
+  principal_id TEXT NOT NULL REFERENCES principals(id), installer_id TEXT NOT NULL REFERENCES principals(id),
+  actions_json TEXT NOT NULL CHECK(json_valid(actions_json)), role TEXT NOT NULL CHECK(role IN ('admin','member','viewer')),
+  state TEXT NOT NULL CHECK(state IN ('active','uninstalled')), signing_secret TEXT NOT NULL,
+  created_at INTEGER NOT NULL, uninstalled_at INTEGER, UNIQUE(app_id,team_id)
+) STRICT;
+CREATE TABLE app_install_codes (
+  code_hash TEXT PRIMARY KEY, installation_id TEXT NOT NULL REFERENCES app_installations(id),
+  redirect_url TEXT NOT NULL, expires_at INTEGER NOT NULL, consumed_at INTEGER
+) STRICT;
+CREATE TABLE app_credentials (
+  credential_id TEXT PRIMARY KEY REFERENCES credentials(id), installation_id TEXT NOT NULL REFERENCES app_installations(id),
+  parent_id TEXT REFERENCES credentials(id), actions_json TEXT NOT NULL CHECK(json_valid(actions_json)),
+  actor_json TEXT NOT NULL CHECK(json_valid(actor_json))
+) STRICT;
+CREATE TABLE identity_app_credentials (
+  credential_id TEXT PRIMARY KEY REFERENCES credentials(id), installation_id TEXT NOT NULL REFERENCES app_installations(id)
+) STRICT;
+CREATE TABLE app_webhook_deliveries (
+  id TEXT PRIMARY KEY, installation_id TEXT NOT NULL REFERENCES app_installations(id), event_id TEXT NOT NULL,
+  body TEXT NOT NULL CHECK(json_valid(body)), state TEXT NOT NULL CHECK(state IN ('pending','delivered','failed','cancelled')),
+  attempts INTEGER NOT NULL DEFAULT 0, next_at INTEGER NOT NULL, lease_until INTEGER, created_at INTEGER NOT NULL,
+  last_status INTEGER, UNIQUE(installation_id,event_id)
+) STRICT;
+CREATE INDEX app_delivery_due ON app_webhook_deliveries(state,next_at);
+CREATE INDEX app_credential_installation ON app_credentials(installation_id);
+`;

package/server/migrations/014.mjs

@@ -0,0 +1,8 @@
+// Credential fences and lineage remain local; no foreign principal identifiers.
+export default `
+ALTER TABLE app_credentials ADD COLUMN subject_principal_id TEXT REFERENCES principals(id);
+ALTER TABLE app_credentials ADD COLUMN subject_credential_id TEXT REFERENCES credentials(id);
+ALTER TABLE app_credentials ADD COLUMN grants_json TEXT NOT NULL DEFAULT 'null' CHECK(json_valid(grants_json));
+ALTER TABLE machine_grants ADD COLUMN app_installation_id TEXT REFERENCES app_installations(id);
+CREATE INDEX machine_grants_installation ON machine_grants(app_installation_id);
+`;

package/server/migrations/index.mjs

@@ -11,7 +11,9 @@ import m009 from './009.mjs';
 import m010 from './010.mjs';
 import m011 from './011.mjs';
 import m012 from './012.mjs';
-export const MIGRATIONS = [m001, m002, m003, m004, m005, m006, m007, m008, m009, m010, m011, m012];
+import m013 from './013.mjs';
+import m014 from './014.mjs';
+export const MIGRATIONS = [m001, m002, m003, m004, m005, m006, m007, m008, m009, m010, m011, m012, m013, m014];
 /** 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). */

package/server/publications.mjs

@@ -1,3 +1,4 @@
+import { installedIssuer } from './apps.mjs';
 // Published surfaces: what a delegated token (./delegated.mjs) may open.
 //
 //   /api/v1/teams/{team}/machines/{id}/publications[/{publication}]   list, publish, unpublish
@@ -80,7 +81,7 @@ export async function publicationRoute({ api, req, res, auth, machineId, publica
     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 (!api.delegatedIssuers.includes(workplace)) fail(400, 'invalid_request', `this server does not trust ${workplace} as a delegated issuer`);
+    if (!await installedIssuer(api,workplace,'delegation.surfaces',auth.team_id)) 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]);