@hanamesh/dsh-app-host 0.2.0-rc.2

package/dist/router/receipts.js

@@ -0,0 +1,156 @@
+/**
+ * T6 — usage receipts (design 2026-09-22 §3, STATUS `T6`).
+ *
+ * The Router knows which provider / model it injected into which application instance; the gateway knows when that
+ * instance really served an authorized request. This ledger turns the two into content-free hourly receipts
+ *
+ *     { appId, providerId, model, hour, count }      hour = UTC `YYYYMMDDHH`, count = forwarded requests in that hour
+ *
+ * kept in app-host's own storage domain (`hanamesh_router_receipts`, one global snapshot, ONE `global.set` per
+ * publication, debounced) and reported through the usage plugin's record seat as the receipt of that hour's `use`
+ * event (see usage-evidence.js). No prompt, response, credential or URL is ever recorded — only the provider id,
+ * the model name the Router routed, and a count.
+ *
+ *   inject   Router `credentialResolver` resolved a route for an instance → the instance's route is remembered
+ *            (first api-key / provider env entry in declaration order) and the (app, route, hour) row counts one injection.
+ *   activity the instance's gateway forwarded an authorized request → the (app, route, hour) row counts one request;
+ *            an instance whose route is unknown (recovered / attached, no injection this run) counts against a
+ *            route-less row so the hour's `use` is still reported, just without a receipt.
+ *   reported once the usage seat accepted (or already had) the hour's `use` event the rows are flagged; later requests in
+ *            the same hour keep counting locally but are not re-reported (the seat de-duplicates by key).
+ *
+ * Without a storage domain (library use, tests) the ledger is memory-only and behaves identically.
+ */
+import { z } from 'zod';
+import { requireCondition } from '../errors.js';
+
+const pad = n => String(n).padStart(2,'0');
+/** UTC hour bucket `YYYYMMDDHH` of an epoch-millisecond instant. */
+export function hourBucket(ms) {
+  const d = new Date(ms);
+  return `${d.getUTCFullYear()}${pad(d.getUTCMonth()+1)}${pad(d.getUTCDate())}${pad(d.getUTCHours())}`;
+}
+/** Bucket → epoch ms of its first instant (used for retention and for ordering). */
+export function bucketStart(bucket) {
+  return Date.UTC(Number(bucket.slice(0,4)),Number(bucket.slice(4,6))-1,Number(bucket.slice(6,8)),Number(bucket.slice(8,10)));
+}
+const PROVIDER = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/, MODEL = /^[A-Za-z0-9][A-Za-z0-9_.:/@+-]{0,127}$/, APP = /^[a-z0-9][a-z0-9-]*$/, BUCKET = /^\d{10}$/;
+const SECRET = /(?:^sk-|^sk_|^bearer[.:-]|ghp_|github_pat_|xox[baprs]-|secret|password|api.?key|private.?key)/i;
+/** A route the Router actually resolved: provider id plus the model it routed (granted, else the app's declared default, else null). */
+export function normalizeRoute(route) {
+  if (!route || typeof route !== 'object') return null;
+  const providerId = route.providerId, model = route.model ?? null;
+  if (typeof providerId !== 'string' || !PROVIDER.test(providerId) || SECRET.test(providerId)) return null;
+  if (model !== null && (typeof model !== 'string' || !MODEL.test(model) || SECRET.test(model))) return { providerId, model:null };
+  return { providerId, model };
+}
+const row = z.object({ appId:z.string(), providerId:z.string().nullable(), model:z.string().nullable(), hour:z.string(),
+  count:z.number().int().nonnegative(), injections:z.number().int().nonnegative(), firstAt:z.number().int().nonnegative(), lastAt:z.number().int().nonnegative(), reported:z.boolean() });
+/** Shape of the persisted global; the storage-domain spec itself lives in `./receipts-domain.js`
+ * so the library entry never pulls a DSH-only peer into a plain consumer's import graph. */
+export const receiptsGlobalSchema = z.object({ schema:z.literal(1), items:z.record(z.string(),row) });
+export const receiptsGlobalInitial = { schema:1, items:{} };
+const key = (appId,providerId,model,hour) => `${appId}|${providerId ?? ''}|${model ?? ''}|${hour}`;
+const DAY = 86_400_000;
+
+/**
+ * @param {{domain?:{global:{get():any,set(value:any):Promise<void>}}, clock?:()=>number, persistDelayMs?:number, maxItems?:number, retentionMs?:number}} [options]
+ */
+export function createReceiptLedger({ domain, clock = Date.now, persistDelayMs = 5_000, maxItems = 5_000, retentionMs = 90*DAY } = {}) {
+  requireCondition(domain === undefined || (domain && domain.global && typeof domain.global.get === 'function' && typeof domain.global.set === 'function'),
+    'INVALID_DOMAIN','receipts domain must expose global.get/set.');
+  requireCondition(Number.isSafeInteger(persistDelayMs) && persistDelayMs >= 0 && Number.isSafeInteger(maxItems) && maxItems > 0,'INVALID_OPTIONS','persistDelayMs / maxItems out of range.');
+  const loaded = domain ? domain.global.get() : null;
+  /** @type {Record<string, any>} */
+  const items = loaded && loaded.schema === 1 && loaded.items && typeof loaded.items === 'object' ? structuredClone(loaded.items) : {};
+  /** instanceId → normalized route (or null when the Router resolved nothing for it). */
+  const routes = new Map();
+  let dirty = false, closed = false, timer = null, writing = Promise.resolve();
+
+  function prune() {
+    const cutoff = clock() - retentionMs;
+    for (const [k,item] of Object.entries(items)) if (bucketStart(item.hour) < cutoff) delete items[k];
+    const keys = Object.keys(items);
+    if (keys.length > maxItems) {
+      keys.sort((a,b) => items[a].reported === items[b].reported ? items[a].lastAt - items[b].lastAt : (items[a].reported ? -1 : 1));
+      for (const k of keys.slice(0, keys.length - maxItems)) delete items[k];
+    }
+  }
+  /** ONE global.set per publication; every mutation since the last one rides in the same image. */
+  function persistNow() {
+    if (!dirty || !domain) { dirty = false; return writing; }
+    dirty = false; prune();
+    const image = { schema:1, items:structuredClone(items) };
+    writing = writing.then(() => domain.global.set(image)).catch(() => { dirty = true; });
+    return writing;
+  }
+  function schedule() {
+    dirty = true;
+    if (!domain || closed) return;
+    if (persistDelayMs === 0) { void persistNow(); return; }
+    if (timer === null) { timer = setTimeout(() => { timer = null; void persistNow(); }, persistDelayMs); timer.unref?.(); }
+  }
+  function touch(appId, route, at, field) {
+    requireCondition(typeof appId === 'string' && APP.test(appId),'INVALID_APP','appId must be an application id.');
+    requireCondition(Number.isSafeInteger(at) && at >= 0,'INVALID_TIME','at must be epoch milliseconds.');
+    const hour = hourBucket(at), k = key(appId, route?.providerId ?? null, route?.model ?? null, hour);
+    const item = items[k] ?? (items[k] = { appId, providerId:route?.providerId ?? null, model:route?.model ?? null, hour, count:0, injections:0, firstAt:at, lastAt:at, reported:false });
+    item[field] += 1; item.firstAt = Math.min(item.firstAt, at); item.lastAt = Math.max(item.lastAt, at);
+    schedule();
+    return { ...item };
+  }
+  const api = Object.freeze({
+    /** The Router injected credentials into an instance; `routes` in declaration order, the first valid one is the instance's route. */
+    inject({ appId, instanceId, routes: resolved = [], at = clock() }) {
+      requireCondition(typeof appId === 'string' && APP.test(appId),'INVALID_APP','appId must be an application id.');
+      requireCondition(typeof instanceId === 'string' && instanceId.length > 0,'INVALID_INSTANCE','instanceId is required.');
+      const route = (Array.isArray(resolved) ? resolved : []).map(normalizeRoute).find(Boolean) ?? null;
+      routes.set(instanceId, route);
+      return route ? touch(appId, route, at, 'injections') : null;
+    },
+    /** The instance's gateway forwarded an authorized request. */
+    activity({ appId, instanceId, at = clock() }) {
+      return touch(appId, routes.get(instanceId) ?? null, at, 'count');
+    },
+    /** The instance ended; its route binding is dropped (rows stay until reported / pruned). */
+    forget(instanceId) { routes.delete(instanceId); },
+    routeOf(instanceId) { const r = routes.get(instanceId); return r ? { ...r } : null; },
+    /**
+     * Hours ready to report as one `use` event each: rows of an (app, hour) that saw real requests and were not reported yet.
+     * `before` (a bucket) keeps the current hour out unless `includeCurrent`; `appId` narrows to one app.
+     * The receipt is the routed row with the most requests; `occurredAt` is the earliest request of the hour.
+     */
+    pending({ appId, includeCurrent = false, now = clock() } = {}) {
+      const current = hourBucket(now), groups = new Map();
+      for (const item of Object.values(items)) {
+        if (item.reported || item.count === 0 || (appId !== undefined && item.appId !== appId)) continue;
+        if (!includeCurrent && item.hour >= current) continue;
+        const g = key(item.appId,'','',item.hour), group = groups.get(g) ?? { appId:item.appId, hour:item.hour, occurredAt:item.firstAt, count:0, receipt:null };
+        group.occurredAt = Math.min(group.occurredAt, item.firstAt); group.count += item.count;
+        if (item.providerId !== null && (group.receipt === null || item.count > group.receipt.count)) group.receipt = { providerId:item.providerId, model:item.model, count:item.count };
+        groups.set(g, group);
+      }
+      return [...groups.values()].sort((a,b) => a.hour.localeCompare(b.hour) || a.appId.localeCompare(b.appId));
+    },
+    /** The hour's `use` event reached the seat (recorded or already there): flag every row of that (app, hour). */
+    markReported(appId, hour) {
+      requireCondition(typeof hour === 'string' && BUCKET.test(hour),'INVALID_HOUR','hour must be a UTC bucket.');
+      let n = 0;
+      for (const item of Object.values(items)) if (item.appId === appId && item.hour === hour && !item.reported) { item.reported = true; n++; }
+      if (n > 0) schedule();
+      return n;
+    },
+    /** Local inspection (router route): the receipt rows, newest hour first, optionally for one app. Never includes credentials. */
+    list({ appId } = {}) {
+      return Object.values(items).filter(item => appId === undefined || item.appId === appId)
+        .sort((a,b) => b.hour.localeCompare(a.hour) || a.appId.localeCompare(b.appId) || String(a.providerId).localeCompare(String(b.providerId)))
+        .map(item => ({ appId:item.appId, providerId:item.providerId, model:item.model, hour:item.hour, count:item.count, injections:item.injections,
+          firstAt:new Date(item.firstAt).toISOString(), lastAt:new Date(item.lastAt).toISOString(), reported:item.reported }));
+    },
+    size: () => Object.keys(items).length,
+    /** Publish now (tests, orderly shutdown). */
+    async persist() { if (timer !== null) { clearTimeout(timer); timer = null; } await persistNow(); },
+    async close() { if (closed) return; closed = true; if (timer !== null) { clearTimeout(timer); timer = null; } await persistNow(); routes.clear(); },
+  });
+  return api;
+}

package/dist/router/routes.js

@@ -0,0 +1,48 @@
+import { randomUUID } from 'node:crypto';
+import { AppHostError, requireCondition } from '../errors.js';
+import { loopbackOrigin } from '../descriptor.js';
+
+export const ROUTER_ROUTES=Object.freeze(['/hanamesh/router/providers','/hanamesh/router/plan','/hanamesh/router/grant',
+  '/hanamesh/router/revoke','/hanamesh/router/model','/hanamesh/router/mode','/hanamesh/router/gateway','/hanamesh/router/receipts']);
+async function body(req){
+  requireCondition(req.headers['content-type']?.split(';')[0].trim()==='application/json','CONTENT_TYPE_REQUIRED','Expected application/json.',{},415);
+  const chunks=[];let total=0;for await(const chunk of req){total+=chunk.length;requireCondition(total<=16_384,'BODY_TOO_LARGE','Request body is too large.',{},413);chunks.push(chunk);}
+  try{return JSON.parse(Buffer.concat(chunks).toString('utf8'));}catch{throw new AppHostError('INVALID_JSON','Malformed JSON.',{},400);}
+}
+function send(res,status,value){res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store',
+  'x-content-type-options':'nosniff','content-security-policy':"default-src 'none'; frame-ancestors 'none'"});res.end(JSON.stringify(value));}
+const statusFor=code=>({APP_NOT_FOUND:404,ENTRY_UNKNOWN:404,ROUTER_PROVIDER_ABSENT:404,RISK_NOT_ACKNOWLEDGED:403,
+  CONSUMER_MISMATCH:403,ENTRY_NOT_ROUTED:409,GATEWAY_OFF:409,GATEWAY_UNREACHABLE:503}[code]??400);
+
+export function createRouterHttpHandler(router,{parentOrigin,authenticate,authorize}){
+  parentOrigin=loopbackOrigin(parentOrigin);requireCondition(typeof authenticate==='function'&&typeof authorize==='function','AUTH_BINDING_REQUIRED','Router authentication is required.');
+  return async(req,res)=>{const traceId=randomUUID();try{
+    requireCondition(req.headers.host===new URL(parentOrigin).host,'HOST_DENIED','Unrecognized request host.',{},403);
+    requireCondition(req.url?.startsWith('/')&&!req.url.startsWith('//')&&!req.url.includes('\\'),'BAD_TARGET','Invalid request target.');
+    const url=new URL(req.url,parentOrigin),path=url.pathname;requireCondition(ROUTER_ROUTES.includes(path),'NOT_FOUND','Unknown router route.',{},404);
+    const readOnly=['/hanamesh/router/providers','/hanamesh/router/plan','/hanamesh/router/receipts'].includes(path);
+    requireCondition(req.method===(readOnly?'GET':'POST'),'METHOD_NOT_ALLOWED','State changes require POST.',{},405);
+    requireCondition(!req.headers.origin||req.headers.origin===parentOrigin,'ORIGIN_DENIED','Unapproved browser origin.',{},403);
+    requireCondition(req.headers['sec-fetch-dest']!=='iframe'&&req.headers['sec-fetch-site']!=='cross-site','FRAME_CONTROL_DENIED','An application frame cannot control the router.',{},403);
+    requireCondition(req.headers['x-hanamesh-client']==='workspace-v1','CSRF_DENIED','Explicit workspace client header is required.',{},403);
+    if(!readOnly)requireCondition(req.headers.origin===parentOrigin,'CSRF_DENIED','Workspace origin is required.',{},403);
+    const subject=await authenticate(req);requireCondition(subject&&typeof subject.principalId==='string','UNAUTHENTICATED','Host authentication is required.',{},401);
+    const input=readOnly?Object.fromEntries(url.searchParams):await body(req);
+    if(path==='/hanamesh/router/providers')requireCondition(Object.keys(input).length===0,'UNKNOWN_FIELDS','No provider parameters are accepted.');
+    if(path==='/hanamesh/router/plan')requireCondition(Object.keys(input).every(key=>key==='appId')&&typeof input.appId==='string','UNKNOWN_FIELDS','Plan accepts only appId.');
+    if(path==='/hanamesh/router/receipts')requireCondition(Object.keys(input).every(key=>key==='appId'),'UNKNOWN_FIELDS','Receipts accept only an optional appId.');
+    requireCondition(await authorize(subject,path,input)===true,'FORBIDDEN','Operation is not authorized.',{},403);
+    let result;
+    if(path==='/hanamesh/router/providers')result={providers:await router.providers()};
+    if(path==='/hanamesh/router/plan')result=await router.plan(input.appId);
+    if(path==='/hanamesh/router/receipts')result=await router.receipts(input.appId);
+    if(path==='/hanamesh/router/grant')result=await router.grant(input.appId,input.entryId,input.subject,{model:input.model,riskAcknowledged:input.riskAcknowledged});
+    if(path==='/hanamesh/router/revoke')result=await router.revoke(input.appId,input.entryId);
+    if(path==='/hanamesh/router/model')result=await router.setModel(input.appId,input.entryId,input.model??'');
+    if(path==='/hanamesh/router/mode'){await router.setMode(input.appId,input.mode);result=await router.plan(input.appId);}
+    if(path==='/hanamesh/router/gateway')result=await router.enableGateway(input.enabled===true);
+    send(res,200,{...result,traceId});
+  }catch(error){const trusted=error instanceof AppHostError||typeof error?.code==='string',code=trusted?(error.code??error.message):'INTERNAL_ERROR';
+    send(res,trusted?(error.status??statusFor(code)):500,{error:{code,message:trusted?error.message:'The operation could not be completed.'},traceId});}
+  };
+}

package/dist/router/sources.js

@@ -0,0 +1,87 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const KNOWN = Object.freeze({
+  DEEPSEEK_API_KEY:'deepseek', OPENAI_API_KEY:'openai', ANTHROPIC_API_KEY:'anthropic', GEMINI_API_KEY:'google',
+});
+export const providerOf = ref => KNOWN[ref] ?? (ref.endsWith('_API_KEY') ? ref.slice(0,-8).toLowerCase().replaceAll('_','-') : undefined);
+const refForProvider = provider => Object.keys(KNOWN).find(ref => KNOWN[ref] === provider)
+  ?? `${provider.toUpperCase().replaceAll('-','_')}_API_KEY`;
+const safeJson = async response => {
+  try { return await response.json(); } catch { return {}; }
+};
+
+export function createProviderSources({ credentials, apps, llm = () => undefined, fetcher = globalThis.fetch.bind(globalThis),
+  webOrigin, codingOauth = {}, dshHome = process.env.DSH_HOME }) {
+  const mode = codingOauth.mode ?? 'http';
+  async function dshProviders() {
+    const refs = new Set(Object.keys(KNOWN));
+    for (const app of apps.list().apps) for (const deployment of app.deployments ?? []) for (const entry of deployment.credentialEnv ?? [])
+      for (const provider of entry.providers ?? []) if (provider !== 'coding-oauth-gateway') refs.add(refForProvider(provider));
+    const catalog = new Map((llm()?.listProviders?.() ?? []).map(item => [item.id,item]));
+    return await Promise.all([...refs].sort().map(async ref => {
+      const info = await credentials.describe(ref);
+      const id = providerOf(ref);
+      const meta = catalog.get(id);
+      let models;
+      if (meta && typeof llm()?.listModels === 'function') {
+        try { models = (await llm().listModels(id)).map(item => item.id ?? item.model).filter(Boolean); } catch {}
+      }
+      return { id, source:'dsh-models', kind:'api-key', displayName:meta?.name ?? id, ref,
+        ...(info.keyHint ? { keyHint:info.keyHint } : {}), ...(models?.length ? { models } : {}),
+        state:info.configured ? 'configured' : 'absent' };
+    }));
+  }
+  async function fileGateway({ reveal = false } = {}) {
+    if (!dshHome) return null;
+    const path = join(dshHome,'.coding-oauth-gateway.json');
+    let fileStat, value;
+    try { fileStat = await stat(path); value = JSON.parse(await readFile(path,'utf8')); } catch { return null; }
+    if ((fileStat.mode & 0o077) !== 0) return { id:'coding-oauth-gateway', source:'coding-oauth-gateway', kind:'api-key',
+      displayName:'Coding OAuth Gateway', state:'unreachable' };
+    const base = { id:'coding-oauth-gateway', source:'coding-oauth-gateway', kind:'api-key', displayName:'Coding OAuth Gateway',
+      ...(Array.isArray(value.models) ? { models:value.models } : {}), ...(value.keyHint ? { keyHint:value.keyHint } : {}) };
+    if (!value.enabled) return { ...base, state:'gateway-off' };
+    if (!Number.isSafeInteger(value.port)) return { ...base, state:'unreachable' };
+    return { ...base, state:'configured', baseUrl:`http://127.0.0.1:${value.port}/v1`, ...(reveal ? { value:value.apiKey } : {}) };
+  }
+  async function httpGateway({ reveal = false } = {}) {
+    let response;
+    try { response = await fetcher(`${webOrigin}/plugins/dsh-grok-build/gateway${reveal?'/reveal':''}`, { method:reveal?'POST':'GET' }); }
+    catch { return { id:'coding-oauth-gateway', source:'coding-oauth-gateway', kind:'api-key', displayName:'Coding OAuth Gateway', state:'unreachable' }; }
+    if (response.status === 404) return null;
+    if (!response.ok) return { id:'coding-oauth-gateway', source:'coding-oauth-gateway', kind:'api-key', displayName:'Coding OAuth Gateway', state:'unreachable' };
+    const value = await safeJson(response);
+    const base = { id:'coding-oauth-gateway', source:'coding-oauth-gateway', kind:'api-key', displayName:'Coding OAuth Gateway',
+      ...(Array.isArray(value.models) ? { models:value.models } : {}), ...(value.keyHint ? { keyHint:value.keyHint } : {}) };
+    if (!reveal && !value.enabled) return { ...base, state:'gateway-off' };
+    if (!reveal && (!value.running || !Number.isSafeInteger(value.port))) return { ...base, state:'unreachable' };
+    const port = value.port ?? (await httpGateway())?.baseUrl?.match(/:(\d+)\/v1$/)?.[1];
+    return { ...base, state:'configured', ...(port ? { baseUrl:`http://127.0.0.1:${port}/v1` } : {}), ...(reveal ? { value:value.apiKey } : {}) };
+  }
+  const gateway = options => mode === 'file' ? fileGateway(options) : httpGateway(options);
+  return {
+    async list() { const values = await dshProviders(), extra = await gateway(); if (extra) values.push(extra); return values; },
+    async enableGateway(enabled) {
+      if (mode === 'file') throw Object.assign(new Error('GATEWAY_FILE_MODE'),{code:'GATEWAY_FILE_MODE'});
+      const response = await fetcher(`${webOrigin}/plugins/dsh-grok-build/gateway`, { method:'PATCH',
+        headers:{'content-type':'application/json'}, body:JSON.stringify({enabled}) });
+      if (!response.ok) throw Object.assign(new Error(response.status===404?'ROUTER_PROVIDER_ABSENT':'GATEWAY_UNREACHABLE'),{code:response.status===404?'ROUTER_PROVIDER_ABSENT':'GATEWAY_UNREACHABLE'});
+      return await safeJson(response);
+    },
+    async resolve(subject) {
+      if (subject.kind === 'api-key') {
+        const resolved = await credentials.resolve(subject.ref);
+        return resolved?.value ? { value:resolved.value, provider:{ id:providerOf(subject.ref), source:'dsh-models', ref:subject.ref } } : undefined;
+      }
+      if (subject.kind === 'provider' && subject.providerId === 'coding-oauth-gateway') {
+        const provider = await gateway(), revealed = await gateway({reveal:true});
+        if (!provider) throw Object.assign(new Error('ROUTER_PROVIDER_ABSENT'),{code:'ROUTER_PROVIDER_ABSENT'});
+        if (provider.state === 'gateway-off') throw Object.assign(new Error('GATEWAY_OFF'),{code:'GATEWAY_OFF'});
+        if (provider.state !== 'configured' || !revealed?.value) throw Object.assign(new Error('GATEWAY_UNREACHABLE'),{code:'GATEWAY_UNREACHABLE'});
+        return { value:revealed.value, provider:{...provider, ...revealed, value:undefined} };
+      }
+      return undefined;
+    },
+  };
+}

package/dist/routes.js

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import { AppHostError, requireCondition } from './errors.js';
+import { loopbackOrigin } from './descriptor.js';
+function browserInstance(instance) {
+  if(!instance)return null;
+  const {id,appId,deploymentId,dataId,mode,status,runtimeId,errorCode}=instance;
+  return {id,appId,deploymentId,dataId,mode,status,runtimeId,...(errorCode?{errorCode}:{})};
+}
+function visible(value) {
+  if(value?.instance)return {...value,instance:browserInstance(value.instance)};
+  if(value?.instances)return {...value,instances:value.instances.map(browserInstance)};
+  return value;
+}
+async function jsonBody(req) {
+  requireCondition(req.headers['content-type']?.split(';')[0].trim()==='application/json','CONTENT_TYPE_REQUIRED','Expected application/json.',{},415);
+  const chunks=[];let total=0;
+  for await(const chunk of req){total+=chunk.length;requireCondition(total<=16_384,'BODY_TOO_LARGE','Request body is too large.',{},413);chunks.push(chunk);}
+  try{return JSON.parse(Buffer.concat(chunks).toString('utf8'));}catch{throw new AppHostError('INVALID_JSON','Malformed JSON.',{},400);}
+}
+function send(res,status,value) {
+  res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store',
+    'x-content-type-options':'nosniff','content-security-policy':"default-src 'none'; frame-ancestors 'none'"});
+  res.end(JSON.stringify(value));
+}
+/** Node request handler. Authentication/authorization MUST come from the host. */
+export function createHttpHandler(host,{parentOrigin,authenticate,authorize}) {
+  parentOrigin=loopbackOrigin(parentOrigin);
+  requireCondition(typeof authenticate==='function'&&typeof authorize==='function','AUTH_BINDING_REQUIRED',
+    'Host authentication and per-operation authorization callbacks are mandatory.');
+  return async(req,res)=>{
+    const traceId=randomUUID();
+    try{
+      requireCondition(req.headers.host===new URL(parentOrigin).host,'HOST_DENIED','Unrecognized request host.',{},403);
+      requireCondition(req.url?.startsWith('/')&&!req.url.startsWith('//')&&!req.url.includes('\\'),'BAD_TARGET','Invalid request target.');
+      const url=new URL(req.url,parentOrigin),path=url.pathname;
+      const known=['/hanamesh/apps','/apps/open','/apps/resume','/apps/recover','/apps/close','/apps/heartbeat','/apps/stop','/apps/events'];
+      requireCondition(known.includes(path),'NOT_FOUND','Unknown app-host route.',{},404);
+      const readOnly=['/hanamesh/apps','/apps/events'].includes(path);
+      requireCondition(req.method===(readOnly?'GET':'POST'),'METHOD_NOT_ALLOWED','State changes require POST.',{},405);
+      requireCondition(!req.headers.origin||req.headers.origin===parentOrigin,'ORIGIN_DENIED','Unapproved browser origin.',{},403);
+      requireCondition(req.headers['sec-fetch-dest']!=='iframe','FRAME_CONTROL_DENIED','An application frame cannot control the host.',{},403);
+      if(!readOnly){
+        requireCondition(req.headers.origin===parentOrigin&&req.headers['x-hanamesh-client']==='workspace-v1',
+          'CSRF_DENIED','Workspace origin and explicit client header are required.',{},403);
+      }
+      const subject=await authenticate(req);
+      requireCondition(subject&&typeof subject.principalId==='string','UNAUTHENTICATED','Host authentication is required.',{},401);
+      const input=readOnly?Object.fromEntries(url.searchParams):await jsonBody(req);
+      requireCondition(await authorize(subject,path,input)===true,'FORBIDDEN','Operation is not authorized.',{},403);
+      let result;
+      switch(path){
+        case '/hanamesh/apps':requireCondition(!url.search,'UNKNOWN_FIELDS','No list parameters are accepted.');result=host.list(subject.principalId);break;
+        case '/apps/open':result=await host.beginOpen(input,subject.principalId);break;
+        case '/apps/resume':result=await host.resume(input,subject.principalId,{waitForReady:false});break;
+        case '/apps/recover':result=await host.recoverView(input,subject.principalId);break;
+        case '/apps/close':result=await host.close(input,subject.principalId);break;
+        case '/apps/heartbeat':result=await host.heartbeat(input,subject.principalId);break;
+        case '/apps/stop':{
+          requireCondition(input&&Object.keys(input).every(k=>['instanceId','confirm'].includes(k))&&
+            typeof input.instanceId==='string'&&(input.confirm===undefined||typeof input.confirm==='boolean'),
+            'INVALID_REQUEST','Stop requires an instanceId and an optional boolean confirmation.');
+          result={instance:await host.stop(input.instanceId,{confirm:input.confirm??false},subject.principalId)};break;
+        }
+        case '/apps/events':requireCondition(Object.keys(input).every(k=>k==='after'),'UNKNOWN_FIELDS','Unknown event parameters.');result=host.eventsSince(Number(input.after??0),subject.principalId);break;
+      }
+      send(res,200,{...visible(result),traceId});
+    }catch(error){
+      const trusted=error instanceof AppHostError;
+      send(res,trusted?error.status:500,{error:{code:trusted?error.code:'INTERNAL_ERROR',
+        message:trusted?error.message:'The operation could not be completed.',
+        ...(trusted?{details:error.details}:{})},traceId});
+    }
+  };
+}

package/dist/runtime.js

@@ -0,0 +1,222 @@
+import { spawn, execFile } from 'node:child_process';
+import { createServer, request } from 'node:http';
+import { readdir, readFile, readlink, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, isAbsolute, join } from 'node:path';
+import { promisify } from 'node:util';
+import { AppHostError, bounded } from './errors.js';
+const exec = promisify(execFile);
+export async function resolveNodeBinary(nodeBinary) {
+  let selected = nodeBinary;
+  if (selected === undefined || selected === null || selected === '') {
+    if (process.versions.electron !== undefined) {
+      throw new AppHostError('NODE_RUNTIME_REQUIRED', 'Electron hosts must configure an external Node.js executable.');
+    }
+    // A plain Node host may use itself. This fallback is intentionally unreachable in Electron.
+    selected = process.execPath;
+  }
+  if (typeof selected !== 'string' || !isAbsolute(selected)) {
+    throw new AppHostError('NODE_RUNTIME_REQUIRED', 'nodeBinary must be an absolute executable path.');
+  }
+  try { await access(selected, constants.X_OK); }
+  catch { throw new AppHostError('NODE_RUNTIME_REQUIRED', 'nodeBinary must be an absolute executable path.'); }
+  return selected;
+}
+export function guardianEnvironment(nodeBinary, source = process.env) {
+  const env = {};
+  for (const key of ['DSH_HOME', 'HOME', 'LANG', 'TMPDIR']) {
+    if (typeof source[key] === 'string' && source[key].length) env[key] = source[key];
+  }
+  if (!env.LANG) env.LANG = 'C.UTF-8';
+  env.PATH = `${dirname(nodeBinary)}:/usr/bin:/bin`;
+  return env;
+}
+export async function freePort() {
+  const server = createServer();
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const port = server.address().port;
+  await new Promise((resolve, reject) => server.close(e => e ? reject(e) : resolve()));
+  return port;
+}
+export function readEndpoint(url, { timeoutMs = 600, limit = 128 * 1024 } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = request(url, { method: 'GET', headers: { 'accept-encoding': 'identity' } }, res => {
+      const chunks = []; let length = 0;
+      res.on('data', data => { length += data.length; if (length > limit) req.destroy(new AppHostError('PROBE_TOO_LARGE', 'Readiness response exceeds limit.')); else chunks.push(data); });
+      res.once('end', () => resolve({ status: res.statusCode, headers: res.headers, body: Buffer.concat(chunks).toString('utf8') }));
+      res.once('error', reject);
+    });
+    const timer = setTimeout(() => req.destroy(new AppHostError('PROBE_TIMEOUT', 'Readiness probe timed out.')), timeoutMs);
+    req.once('close', () => clearTimeout(timer)); req.once('error', reject); req.end();
+  });
+}
+
+// Verifies that the actual listening socket belongs to the group created by our
+// exact child handle. A random HTTP 200 (even with the same app marker) is not ready.
+export async function ownsLoopbackPort(pid, port) {
+  if (process.platform === 'linux') {
+    const table = await readFile('/proc/net/tcp', 'utf8');
+    const inodes = new Set(table.trim().split('\n').slice(1).map(line => line.trim().split(/\s+/))
+      .filter(cols => cols[1] === `0100007F:${port.toString(16).toUpperCase().padStart(4, '0')}` && cols[3] === '0A')
+      .map(cols => cols[9]));
+    if (!inodes.size) return false;
+    for (const entry of await readdir('/proc')) {
+      if (!/^\d+$/.test(entry)) continue;
+      try {
+        const stat = await readFile(`/proc/${entry}/stat`, 'utf8');
+        const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        if (Number(rest[2]) !== pid) continue; // field 5: pgrp
+        for (const fd of await readdir(`/proc/${entry}/fd`)) {
+          const target = await readlink(`/proc/${entry}/fd/${fd}`).catch(() => '');
+          const match = /^socket:\[(\d+)\]$/.exec(target);
+          if (match && inodes.has(match[1])) return true;
+        }
+      } catch (error) { if (!['ENOENT','ESRCH','EACCES'].includes(error.code)) throw error; }
+    }
+    return false;
+  }
+  if (process.platform === 'darwin') {
+    let binary;
+    for (const path of ['/usr/sbin/lsof','/usr/bin/lsof']) {
+      try { await access(path, constants.X_OK); binary = path; break; } catch {}
+    }
+    if (!binary) throw new AppHostError('PORT_OWNERSHIP_UNAVAILABLE', 'lsof is required to verify socket ownership on macOS.');
+    let stdout;
+    try { ({ stdout } = await exec(binary, ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-FpgLn'], { timeout: 1_000 })); }
+    catch (error) { if (error.code === 1) return false; throw error; }
+    const blocks = stdout.split(/(?=^p\d+$)/m);
+    return blocks.some(block => block.split('\n').includes(`g${pid}`) && block.includes(`n127.0.0.1:${port}`));
+  }
+  throw new AppHostError('PLATFORM_UNSUPPORTED', 'Owned process/socket verification currently supports POSIX Linux and macOS only.');
+}
+
+// Identity of a live process: a start token (pid reuse guard) and its executable when the
+// platform can say. Unknown fields stay null so callers fail closed; a dead or zombie pid is null.
+let bootId;
+export async function processIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 1) return null;
+  try { process.kill(pid, 0); }
+  catch (error) { if (error.code === 'ESRCH') return null; if (error.code !== 'EPERM') throw error; }
+  if (process.platform === 'linux') {
+    try {
+      const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+      const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+      if (rest[0] === 'Z' || rest[0] === 'X') return null;
+      bootId ??= (await readFile('/proc/sys/kernel/random/boot_id', 'utf8').catch(() => '')).trim();
+      return { pid, start: `${bootId}:${rest[19]}`, command: await readlink(`/proc/${pid}/exe`).catch(() => null) }; // field 22: starttime
+    } catch (error) { if (['ENOENT', 'ESRCH'].includes(error.code)) return null; if (error.code !== 'EACCES') throw error; }
+  }
+  if (process.platform !== 'win32') {
+    for (const binary of ['/bin/ps', '/usr/bin/ps']) {
+      let stdout;
+      try { ({ stdout } = await exec(binary, ['-o', 'stat=', '-o', 'lstart=', '-o', 'comm=', '-p', String(pid)], { timeout: 1_000 })); }
+      catch (error) { if (error.code === 'ENOENT') continue; if (typeof error.code === 'number') return null; throw error; }
+      const fields = stdout.trim().split(/\s+/);
+      if (fields.length < 6 || fields[0].startsWith('Z')) return null;
+      return { pid, start: fields.slice(1, 6).join(' '), command: fields.slice(6).join(' ') || null };
+    }
+  }
+  return { pid, start: null, command: null };
+}
+
+export function redact(line, secrets = []) {
+  for (const secret of secrets) if (typeof secret === 'string' && secret.length >= 4) line = line.split(secret).join('[REDACTED]');
+  return line.replace(/(\bBearer\s+)[^\s"',;]+/gi, '$1[REDACTED]')
+    .replace(/((?:token|secret|password|api[_-]?key)\s*[=:]\s*)[^\s&"',;]+/gi, '$1[REDACTED]')
+    .replace(/("(?:token|secret|password|api[_-]?key)"\s*:\s*")[^"]*/gi, '$1[REDACTED]');
+}
+function lineSink(stream, write, secrets) {
+  let buffer = '', discarding = false;
+  stream.setEncoding('utf8');
+  stream.on('data', chunk => {
+    for (const part of chunk.split(/(?<=\n)/)) {
+      if (!discarding) buffer += part;
+      if (buffer.length > 8_192) { buffer = ''; discarding = true; }
+      if (part.endsWith('\n')) {
+        write(discarding ? '[oversize log line omitted]' : redact(buffer.trimEnd(), secrets));
+        buffer = ''; discarding = false;
+      }
+    }
+  });
+  stream.once('end', () => { if (buffer && !discarding) write(redact(buffer, secrets)); });
+}
+export async function spawnOwned(config, { onLog = () => {} } = {}) {
+  if (!['linux','darwin'].includes(process.platform)) throw new AppHostError('PLATFORM_UNSUPPORTED', 'Owned runtimes are restricted to POSIX.');
+  const nodeBinary = await resolveNodeBinary(config.nodeBinary);
+  const launchConfig = { ...config, nodeBinary };
+  const guardian = spawn(nodeBinary, [fileURLToPath(new URL('./guardian.js', import.meta.url))], {
+    env: guardianEnvironment(nodeBinary),
+    stdio: ['ignore','pipe','pipe','ipc'], shell: false,
+  });
+  const secrets = [...Object.entries(config.env).filter(([key]) => /TOKEN|SECRET|PASSWORD|KEY|AUTH|OAUTH|CREDENTIAL/.test(key)).map(([, value]) => value),
+    ...(Array.isArray(config.secrets) ? config.secrets : [])];
+  lineSink(guardian.stdout, text => onLog('stdout', text), secrets);
+  lineSink(guardian.stderr, text => onLog('stderr', text), secrets);
+  let resolveSpawn, rejectSpawn, resolveOwnership, childPid, groupId, guardianBinary, launcherBinary, appExit, cleanupConfirmed = false;
+  const ownershipReady = new Promise(resolve => { resolveOwnership = resolve; });
+  const spawned = new Promise((resolve, reject) => { resolveSpawn = resolve; rejectSpawn = reject; });
+  const exited = new Promise(resolve => {
+    guardian.once('exit', (code, signal) => { rejectSpawn(new AppHostError('SPAWN_FAILED','Guardian exited before application launch.')); resolve(appExit ?? { code, signal }); });
+    guardian.once('error', error => { rejectSpawn(error); resolve({ code: null, signal: null, error: error.message }); });
+  });
+  guardian.on('message', msg => {
+    if (msg.type === 'stopped') cleanupConfirmed = true;
+    if (msg.type === 'ownership-ready') resolveOwnership();
+    if (msg.type === 'guardian-ready') guardian.send({ type: 'launch', config: launchConfig }, error => { if (error) rejectSpawn(error); });
+    if (msg.type === 'guardian.refused') rejectSpawn(new AppHostError(msg.code ?? 'NODE_RUNTIME_REQUIRED', msg.message ?? 'Guardian refused its runtime.'));
+    if (msg.type === 'spawned') {
+      childPid = msg.pid; groupId = msg.groupId; guardianBinary = msg.guardianBinary; launcherBinary = msg.launcherBinary;
+      resolveSpawn(msg.pid);
+    }
+    if (msg.type === 'app-exit') appExit = { code: msg.code, signal: msg.signal };
+    if (msg.type === 'error') rejectSpawn(new AppHostError(msg.code, msg.message, msg.details ?? {}));
+  });
+  let stopping;
+  const stop = () => {
+    if (stopping) return stopping;
+    stopping = (async () => {
+      if (guardian.exitCode === null && guardian.signalCode === null) {
+      if (guardian.connected) guardian.send({ type: 'stop' }, () => {});
+      else guardian.kill('SIGTERM'); // exact owned child handle only
+      // Do not SIGKILL the guardian: that could orphan the managed application.
+      }
+      const result = await bounded(exited, config.stopGraceMs + 5_000, 'Owned process cleanup');
+      if (!cleanupConfirmed) throw new AppHostError('CLEANUP_UNCONFIRMED', 'Guardian termination was not accompanied by a confirmed cleanup acknowledgement.');
+      return result;
+    })();
+    return stopping;
+  };
+  try {
+    // Ownership recovery may use the declared TERM grace, then 2s KILL confirmation.
+    // Keep the existing 5s bootstrap/probe allowance separate from the launch handshake.
+    // Racing spawned also observes early errors/exits immediately in either phase.
+    await bounded(Promise.race([ownershipReady, spawned]), 5_000 + config.stopGraceMs + 2_000, 'Runtime ownership recovery');
+    await bounded(spawned, 5_000, 'Process spawn');
+  }
+  catch (error) { await stop().catch(() => {}); throw error; }
+  return { mode: 'owned', pid: childPid, groupId, guardianPid: guardian.pid, nodeBinary, guardianBinary, launcherBinary, exited, stop,
+    isAlive: () => guardian.exitCode === null && guardian.signalCode === null && !appExit };
+}
+export async function waitReady(origin, readiness, { runtime, timeoutMs, signal }) {
+  const deadline = Date.now() + timeoutMs;
+  let last = 'No matching response.';
+  while (Date.now() < deadline) {
+    if (signal.aborted) throw new AppHostError('START_CANCELLED','Launch was cancelled.');
+    if (runtime?.mode === 'owned' && !runtime.isAlive()) throw new AppHostError('APP_EXITED','Application exited before readiness.');
+    try {
+      const result = await readEndpoint(new URL(readiness.path, origin), { timeoutMs: Math.min(600, Math.max(25, deadline - Date.now())) });
+      const marker = (!readiness.bodyIncludes || result.body.includes(readiness.bodyIncludes)) &&
+        (!readiness.header || result.headers[readiness.header.name.toLowerCase()] === readiness.header.value);
+      if (result.status === readiness.status && marker) {
+        if (runtime?.mode !== 'owned' || await ownsLoopbackPort(runtime.groupId, Number(new URL(origin).port))) return;
+        last = 'The endpoint is not owned by the launched process group.';
+      } else last = 'Status or application identity marker did not match.';
+    } catch (error) {
+      if (['PLATFORM_UNSUPPORTED','PORT_OWNERSHIP_UNAVAILABLE'].includes(error.code)) throw error;
+      last = 'The readiness endpoint was unavailable.';
+    }
+    await new Promise(resolve => setTimeout(resolve, 35));
+  }
+  throw new AppHostError('READY_TIMEOUT', `Application readiness failed: ${last}`, {}, 504);
+}