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

package/dist/gateway.js

@@ -0,0 +1,224 @@
+import { createServer, request } from 'node:http';
+import { randomBytes, createHash } from 'node:crypto';
+import { AppHostError, requireCondition, bounded } from './errors.js';
+import { loopbackOrigin } from './descriptor.js';
+
+/**
+ * `frame-ancestors` is matched against EVERY ancestor, not just the direct parent. Inside a
+ * desktop shell the chain is `<shell origin>` → DSH workspace → app frame, so the shell's own
+ * webview origin (e.g. `tauri://localhost`) must be listed too or the app document is served
+ * and then refused by the webview — a blank frame (HanaMesh desktop rc.4, 2026-09-21). The
+ * value is `parentOrigin` plus the configured extra ancestors, space-separated.
+ */
+export function frameAncestorsValue(parentOrigin, frameAncestors = []) {
+  return [parentOrigin, ...frameAncestors.filter(origin => origin !== parentOrigin)].join(' ');
+}
+/** Only exact origins of a scheme a webview can actually host a top-level document on. */
+export function ancestorOrigin(value) {
+  let url;
+  try { url = new URL(value); } catch { requireCondition(false, 'INVALID_FRAME_ANCESTOR', 'Expected an explicit ancestor origin.'); }
+  requireCondition(['http:', 'https:', 'tauri:', 'asset:', 'file:'].includes(url.protocol) && !url.username && !url.password &&
+    (url.pathname === '/' || url.pathname === '') && !url.search && !url.hash && (url.protocol === 'file:' || url.hostname),
+    'INVALID_FRAME_ANCESTOR', 'Only scheme://host[:port] ancestor origins are accepted.');
+  // `URL.origin` is the string "null" for non-special schemes such as tauri:; rebuild it.
+  return url.protocol === 'file:' ? 'file://' : `${url.protocol}//${url.host}`;
+}
+export function rewriteCsp(value, ancestors) {
+  if (/(?:^|;)\s*frame-ancestors\b/i.test(value))
+    return value.replace(/(^|;)(\s*)frame-ancestors\b[^;]*/ig, (_, delimiter, whitespace) => `${delimiter}${whitespace}frame-ancestors ${ancestors}`);
+  return `${value}${value.trimEnd().endsWith(';') ? '' : ';'} frame-ancestors ${ancestors}`;
+}
+export function embeddingHeaders(rawHeaders, ancestors) {
+  const output = []; let hasCsp = false;
+  for (let i = 0; i < rawHeaders.length; i += 2) {
+    const key = rawHeaders[i], value = rawHeaders[i + 1];
+    if (key.toLowerCase() === 'x-frame-options') continue;
+    if (key.toLowerCase() === 'content-security-policy') { output.push(key, rewriteCsp(value, ancestors)); hasCsp = true; }
+    else output.push(key, value);
+  }
+  if (!hasCsp) output.push('Content-Security-Policy', `frame-ancestors ${ancestors}`);
+  return output;
+}
+const token = () => randomBytes(32).toString('hex');
+function cookies(header) {
+  const map = new Map();
+  for (const part of (header ?? '').split(';')) {
+    const at = part.indexOf('='); if (at > 0) map.set(part.slice(0,at).trim(), part.slice(at+1).trim());
+  }
+  return map;
+}
+function fail(res, status, code) {
+  res.writeHead(status, { 'content-type':'application/json', 'cache-control':'no-store', 'content-security-policy':"default-src 'none'; frame-ancestors 'none'" });
+  res.end(JSON.stringify({ error: { code } }));
+}
+
+/** Fixed upstream only. Bootstrap is our own response, not a rewritten app document. */
+export class FixedGateway {
+  constructor({ upstream, parentOrigin, isLeaseActive, cookieAllowlist = [], allowAppAuthorization = false, maxUploadBytes = 32 * 1024 * 1024, frameAncestors = [], onForward = () => {} }) {
+    this.upstream = loopbackOrigin(upstream); this.parentOrigin = loopbackOrigin(parentOrigin);
+    requireCondition(Array.isArray(frameAncestors) && frameAncestors.length <= 8, 'INVALID_FRAME_ANCESTOR', 'frameAncestors must be a short list of origins.');
+    this.ancestors = frameAncestorsValue(this.parentOrigin, frameAncestors.map(ancestorOrigin));
+    requireCondition(typeof isLeaseActive === 'function','INVALID_GATEWAY','A live lease authorization check is required.');
+    this.isLeaseActive = isLeaseActive; this.cookieAllowlist = new Set(cookieAllowlist);
+    this.allowAppAuthorization = allowAppAuthorization; this.maxUploadBytes = maxUploadBytes;
+    requireCondition(typeof onForward === 'function','INVALID_GATEWAY','onForward must be a function.');
+    this.onForward = onForward;
+    this.tickets = new Map(); this.grants = new Map(); this.sockets = new Set(); this.upstreams = new Set();
+    this.cookiePrefix = `hm_app_${token().slice(0,12)}_`;
+  }
+  async start() {
+    this.server = createServer((req,res) => this.#handle(req,res));
+    this.server.on('connection', socket => { this.sockets.add(socket); socket.once('close', () => this.sockets.delete(socket)); });
+    this.server.on('upgrade', (req,socket,head) => this.#upgrade(req,socket,head));
+    this.server.on('connect', (_req,socket) => socket.end('HTTP/1.1 405 Method Not Allowed\r\nConnection: close\r\n\r\n'));
+    await new Promise((resolve,reject) => { this.server.once('error',reject); this.server.listen(0,'127.0.0.1',resolve); });
+    this.origin = `http://127.0.0.1:${this.server.address().port}`;
+    return this.origin;
+  }
+  issue(viewKey) {
+    requireCondition(this.isLeaseActive(viewKey),'LEASE_EXPIRED','Cannot grant access to an inactive view.');
+    for (const [key,t] of this.tickets) if (t.expiresAt < Date.now() || !this.isLeaseActive(t.viewKey)) this.tickets.delete(key);
+    for (const [key,g] of this.grants) if (!this.isLeaseActive(g.viewKey)) this.grants.delete(key);
+    requireCondition(this.tickets.size < 512,'TOO_MANY_TICKETS','Too many pending iframe tickets.');
+    const ticket = token(); this.tickets.set(ticket,{ viewKey, expiresAt:Date.now()+60_000 });
+    return `${this.origin}/__hanamesh_bootstrap/${ticket}`;
+  }
+  #requestShape(req) {
+    if (req.headers.host !== new URL(this.origin).host) return false;
+    if (!req.url?.startsWith('/') || req.url.startsWith('//') || req.url.includes('\\') || req.url.length > 8_192) return false;
+    try { if (/^[\/\\]{2}|[\x00-\x1f]/.test(decodeURIComponent(req.url))) return false; } catch { return false; }
+    if (req.headers.origin && ![this.parentOrigin,this.origin].includes(req.headers.origin)) return false;
+    if (req.headers['sec-fetch-dest'] === 'document') return false; // never top-level navigation
+    return true;
+  }
+  #authorized(req) {
+    if (!this.#requestShape(req)) return false;
+    // Cookie capability + live lease. Origin/loopback alone never authenticate.
+    for (const [name,value] of cookies(req.headers.cookie)) {
+      if (!name.startsWith(this.cookiePrefix)) continue;
+      const grant = this.grants.get(value);
+      if (grant?.cookieName === name && this.isLeaseActive(grant.viewKey)) return true;
+    }
+    return this.#embeddedAuthorized(req);
+  }
+  /**
+   * Embedded webviews (Tauri/WKWebView, WebView2 with tracking prevention) never return
+   * the bootstrap cookie: the app frame is a third party under the shell's own top-level
+   * origin, so `SameSite=Strict`/third-party cookies are dropped and every request after
+   * the 303 arrived without a grant → 403 with `frame-ancestors 'none'` → a blank frame
+   * (2026-09-21, HanaMesh desktop rc.4 + Vibe). Fall back to Fetch Metadata, which the
+   * same webviews do send: a request is accepted without a cookie only when it comes from
+   * inside an app document already served by this gateway (`same-origin`), or is the
+   * post-bootstrap frame navigation initiated by the registered parent (`same-site` +
+   * `iframe` + parent referer), and a bootstrap ticket for a still-live lease has been
+   * consumed for this instance. Cross-site and address-bar (`none`) requests stay denied.
+   */
+  #embeddedAuthorized(req) {
+    if (!this.#liveGrantExists()) return false;
+    const site = req.headers['sec-fetch-site'];
+    if (site === 'same-origin') return true;
+    // WebSocket handshakes: every browser sets `Origin` on them (not spoofable from web content); some
+    // WebKit builds omit Fetch Metadata there. The app's own origin is equivalent to same-origin.
+    if (req.headers.upgrade?.toLowerCase() === 'websocket' && req.headers.origin === this.origin) return true;
+    if (site !== 'same-site' || req.headers['sec-fetch-dest'] !== 'iframe') return false;
+    let referer;
+    try { referer = new URL(req.headers.referer).origin; } catch { return false; }
+    return referer === this.parentOrigin;
+  }
+  #liveGrantExists() {
+    for (const [value,g] of this.grants) { if (this.isLeaseActive(g.viewKey)) return true; this.grants.delete(value); }
+    return false;
+  }
+  #headers(req, upgrade = false) {
+    const headers = { ...req.headers, host:new URL(this.upstream).host };
+    const allowedCookies = [...cookies(req.headers.cookie)].filter(([key]) => this.cookieAllowlist.has(key));
+    if (allowedCookies.length) headers.cookie = allowedCookies.map(([k,v]) => `${k}=${v}`).join('; ');
+    else delete headers.cookie;
+    if (!this.allowAppAuthorization) delete headers.authorization;
+    for (const key of Object.keys(headers)) if (/^(?:x-dsh|x-hanamesh|proxy-authorization|proxy-authenticate)/i.test(key)) delete headers[key];
+    if (!upgrade) {
+      for (const key of String(req.headers.connection ?? '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean)) delete headers[key];
+      delete headers.connection; delete headers['proxy-connection']; delete headers.upgrade;
+    }
+    return headers;
+  }
+  #bootstrap(req,res) {
+    const ticket = req.url.slice('/__hanamesh_bootstrap/'.length);
+    const item = this.tickets.get(ticket);
+    let referer;
+    try { referer = new URL(req.headers.referer).origin; } catch {}
+    if (req.method !== 'GET' || req.headers['sec-fetch-dest'] !== 'iframe' || referer !== this.parentOrigin ||
+      !item || item.expiresAt <= Date.now() || !this.isLeaseActive(item.viewKey)) return fail(res,403,'GATEWAY_BOOTSTRAP_DENIED');
+    this.tickets.delete(ticket);
+    const value = token(), suffix = createHash('sha256').update(item.viewKey).digest('hex').slice(0,16);
+    const cookieName = this.cookiePrefix + suffix;
+    for (const [old,g] of this.grants) if (g.cookieName === cookieName) this.grants.delete(old);
+    this.grants.set(value,{ viewKey:item.viewKey, cookieName });
+    // No `referrer-policy: no-referrer` here: browsers apply it to the redirect hop, so the
+    // `/` navigation that follows arrives without a Referer and the cookie-less embedded path
+    // (parent-referer + same-site iframe) can never match (WKWebView, 2026-09-21). The Referer
+    // of that hop is the parent document, never this ticket URL, so nothing leaks upstream.
+    res.writeHead(303, {
+      location:'/', 'set-cookie':`${cookieName}=${value}; Path=/; HttpOnly; SameSite=Strict`,
+      'cache-control':'no-store',
+      'content-security-policy':`default-src 'none'; frame-ancestors ${this.ancestors}`,
+    });
+    res.end();
+  }
+  /**
+   * rc.27 usage evidence: one call per request this gateway actually forwarded for an authorized view and the
+   * app answered with anything but 401/403. Bootstrap tickets and every gateway denial never reach here; the
+   * host's own readiness probes go to the upstream directly, never through the gateway. A throwing hook must
+   * never break the proxied response.
+   */
+  #forwarded() { try { this.onForward(); } catch {} }
+  #handle(req,res) {
+    if (!this.#requestShape(req)) return fail(res,403,'GATEWAY_REQUEST_DENIED');
+    if (req.url.startsWith('/__hanamesh_bootstrap/')) return this.#bootstrap(req,res);
+    if (!this.#authorized(req)) return fail(res,403,'GATEWAY_AUTH_REQUIRED');
+    if (!['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'].includes(req.method)) return fail(res,405,'METHOD_NOT_ALLOWED');
+    if (Number(req.headers['content-length']) > this.maxUploadBytes) return fail(res,413,'UPLOAD_TOO_LARGE');
+    const upstream = request(this.upstream + req.url,{ method:req.method,headers:this.#headers(req) }, response => {
+      if (response.statusCode !== 401 && response.statusCode !== 403) this.#forwarded();
+      res.writeHead(response.statusCode, embeddingHeaders(response.rawHeaders,this.ancestors));
+      response.pipe(res, { end:false });
+      response.once('error', () => res.destroy());
+      response.once('end', () => { if (Object.keys(response.trailers).length) res.addTrailers(response.trailers); res.end(); });
+    });
+    this.upstreams.add(upstream); upstream.once('close',() => this.upstreams.delete(upstream));
+    upstream.setTimeout(120_000,() => upstream.destroy(new Error('Upstream idle timeout')));
+    upstream.once('error',() => { if (!res.headersSent) fail(res,502,'GATEWAY_UPSTREAM_FAILED'); else res.destroy(); });
+    let size = 0;
+    req.on('data', chunk => {
+      size += chunk.length;
+      if (size > this.maxUploadBytes) { if (!res.headersSent) fail(res,413,'UPLOAD_TOO_LARGE'); upstream.destroy(); }
+    });
+    req.once('aborted',() => upstream.destroy()); res.once('close',() => upstream.destroy());
+    req.pipe(upstream);
+  }
+  #upgrade(req,socket,head) {
+    if (!this.#authorized(req) || req.headers.upgrade?.toLowerCase() !== 'websocket') {
+      socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return;
+    }
+    const upstream = request(this.upstream + req.url,{ method:'GET',headers:this.#headers(req,true) });
+    this.upstreams.add(upstream); upstream.once('close',() => this.upstreams.delete(upstream));
+    const timer = setTimeout(() => { upstream.destroy(); socket.destroy(); },10_000);
+    upstream.once('upgrade',(res,peer,upHead) => {
+      clearTimeout(timer); this.sockets.add(peer); peer.once('close',() => this.sockets.delete(peer)); this.#forwarded();
+      const lines = [`HTTP/1.1 ${res.statusCode} ${res.statusMessage}`];
+      for (let i=0;i<res.rawHeaders.length;i+=2) lines.push(`${res.rawHeaders[i]}: ${res.rawHeaders[i+1]}`);
+      socket.write(lines.join('\r\n')+'\r\n\r\n'); if (upHead.length) socket.write(upHead); if (head.length) peer.write(head);
+      peer.pipe(socket); socket.pipe(peer);
+      peer.on('error',() => socket.destroy()); socket.on('error',() => peer.destroy());
+      socket.once('close',() => peer.destroy()); peer.once('close',() => socket.destroy());
+    });
+    upstream.once('response',() => { clearTimeout(timer); upstream.destroy(); socket.end('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n'); });
+    upstream.once('error',() => { clearTimeout(timer); socket.destroy(); }); upstream.end();
+  }
+  async close() {
+    this.tickets.clear(); this.grants.clear();
+    for (const request of this.upstreams) request.destroy();
+    for (const socket of this.sockets) socket.destroy();
+    if (this.server?.listening) await bounded(new Promise((resolve,reject) => this.server.close(error => error ? reject(error) : resolve())),2_000,'Gateway shutdown');
+  }
+}

package/dist/guardian.js

@@ -0,0 +1,113 @@
+// One guardian per owned runtime. It never attaches to an arbitrary PID.
+// Losing the parent's IPC channel triggers cleanup, even when the host was SIGKILLed.
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FileLock } from './store.js';
+import { guardianEnvironment, processIdentity } from './runtime.js';
+if (process.versions.electron !== undefined) {
+  const refusal = { type:'guardian.refused', code:'NODE_RUNTIME_REQUIRED', message:'Guardian requires a standalone Node.js runtime.' };
+  if (process.connected) await new Promise(resolve => process.send(refusal, () => resolve()));
+  process.exit(78);
+}
+let child, lock, stopping, config, resolveAppExit;
+const appExited = new Promise(resolve => { resolveAppExit = resolve; });
+// The guardian must outlive a killed host. Its stdout/stderr pipes die with that host;
+// EPIPE is transport loss, not a reason to abandon the exact process group it owns.
+for (const output of [process.stdout,process.stderr]) output.on('error', error => {
+  if (error.code !== 'EPIPE') throw error;
+});
+const send = value => { if (process.connected) process.send(value, () => {}); };
+function signalOwned(signal) {
+  if (!child?.pid) return;
+  try {
+    // The process group was created by this exact child handle (detached:true).
+    // This is not process-name matching and is never used for attach instances.
+    if (process.platform !== 'win32') process.kill(-child.pid, signal);
+    else if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+  } catch (e) { if (e.code !== 'ESRCH') throw e; }
+}
+function ownedGroupAlive() {
+  if (!child?.pid) return false;
+  if (process.platform === 'win32') return child.exitCode === null && child.signalCode === null;
+  try { process.kill(-child.pid, 0); return true; }
+  catch (error) { if (error.code === 'ESRCH') return false; if (error.code === 'EPERM') return true; throw error; }
+}
+async function waitForOwnedGroupExit(timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (ownedGroupAlive() && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 25));
+  return !ownedGroupAlive();
+}
+async function cleanup(reason) {
+  if (stopping) return stopping;
+  stopping = (async () => {
+    let timer, confirmed = !child?.pid;
+    if (child?.pid) {
+      const ended = child.exitCode !== null || child.signalCode !== null ? Promise.resolve() :
+        new Promise(resolve => child.once('close', resolve));
+      signalOwned('SIGTERM');
+      // The launcher deliberately survives TERM to anchor its owned process group.
+      // Its close event therefore cannot be the normal app's graceful-exit signal.
+      await Promise.race([ended, appExited, new Promise(resolve => { timer = setTimeout(resolve, config.stopGraceMs); })]);
+      clearTimeout(timer);
+      // A descendant can hold the process group after its leader has exited.
+      // Kill only the group originally created by this guardian.
+      signalOwned('SIGKILL');
+      confirmed = process.platform === 'win32' ? await Promise.race([
+        ended.then(() => true), new Promise(resolve => { timer = setTimeout(() => resolve(false), 2_000); }),
+      ]) : await waitForOwnedGroupExit(2_000);
+      clearTimeout(timer);
+    }
+    if (!confirmed) throw new Error('Owned process group termination was not confirmed; runtime lock retained.');
+    if (lock) await lock.release();
+    if (process.connected) await new Promise(resolve => process.send({ type:'stopped', reason }, () => resolve()));
+    process.exit(0);
+  })().catch(error => { send({ type: 'error', code: error.code ?? 'GUARDIAN_FAILURE', message: error.message, details: error.details ?? {} }); process.exit(1); });
+  return stopping;
+}
+process.on('disconnect', () => void cleanup('host-disconnected'));
+process.on('SIGTERM', () => void cleanup('guardian-term'));
+process.on('SIGINT', () => void cleanup('guardian-int'));
+process.on('message', async message => {
+  if (message?.type === 'stop') { void cleanup('requested'); return; }
+  if (message?.type !== 'launch' || config) return;
+  config = message.config;
+  try {
+    if (!process.connected || stopping) return;
+    // A force-killed guardian leaves this lock behind. The record names this pid + start token and
+    // the children created below, so the next guardian can prove the stale owner dead (or its
+    // orphans ours) instead of failing DATA_ROOT_BUSY until a human deletes the file.
+    lock = new FileLock(join(config.dataDir, '.runtime.lock'), { reclaimDead: true, orphanGraceMs: config.stopGraceMs });
+    await lock.acquire();
+    if (!process.connected || stopping) { await lock.release(); return; }
+    send({ type:'ownership-ready' });
+    child = spawn(config.nodeBinary, [fileURLToPath(new URL('./launcher.js', import.meta.url))], {
+      env: guardianEnvironment(config.nodeBinary), shell: false,
+      detached: true, stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+    });
+    child.stdout.pipe(process.stdout); child.stderr.pipe(process.stderr);
+    const record = async (pid, role, command, group) => {
+      const live = await processIdentity(pid);
+      await lock.annotate({ child: { pid, role, command, group, start: live?.start ?? null }, port: config.port ?? null });
+    };
+    // The launcher (group leader) is recorded before it is told to launch anything.
+    child.once('spawn', () => record(child.pid, 'launcher', config.nodeBinary, true).then(() => child.send({type:'launch',config}, error => {
+      if(error){send({type:'error',code:'SPAWN_FAILED',message:error.message});void cleanup('ipc-error');}
+    }), error => { send({type:'error',code:error.code ?? 'SPAWN_FAILED',message:error.message}); void cleanup('lock-annotate-error'); }));
+    child.on('message', message => {
+      if(message.type==='spawned')record(message.pid,'app',config.command,false).then(()=>send({type:'spawned',pid:message.pid,groupId:child.pid,
+        guardianBinary:process.execPath,launcherBinary:message.launcherBinary}),
+        error=>{send({type:'error',code:error.code ?? 'GUARDIAN_FAILURE',message:error.message});void cleanup('lock-annotate-error');});
+      if(message.type==='app-exit'){resolveAppExit();send(message);if(!stopping)void cleanup('app-exited');}
+      if(message.type==='error'){send(message);void cleanup('spawn-error');}
+    });
+    child.once('error', error => { send({ type: 'error', code: 'SPAWN_FAILED', message: error.message }); void cleanup('spawn-error'); });
+    child.once('exit', (code, signal) => {
+      if(!stopping){send({type:'app-exit',code,signal});void cleanup('group-leader-exited');}
+    });
+  } catch (error) {
+    send({ type: 'error', code: error.code ?? 'SPAWN_FAILED', message: error.message, details: error.details ?? {} });
+    void cleanup('setup-error');
+  }
+});
+send({ type: 'guardian-ready' });

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+export type Awaitable<T> = T | Promise<T>;
+export type InstanceStatus = 'reserved'|'starting'|'ready'|'stopping'|'stopped'|'failed'|'interrupted';
+export type LeaseStatus = 'active'|'closed'|'expired'|'stopped'|'failed';
+export interface Readiness { path:string; status:number; bodyIncludes?:string; header?:{name:string;value:string}; }
+export interface GatewayPolicy { cookieAllowlist?:string[]; allowAppAuthorization?:boolean; }
+interface DeploymentBase { id:string; dataId:string; readiness:Readiness; embedding?:'direct'|'gateway'; startTimeoutMs?:number; stopGraceMs?:number; gateway?:GatewayPolicy; }
+/** rc.4: what an app needs, never where it comes from. `projection:'env'` names a process variable; `projection:'file'` a path relative to the app HOME. */
+export type CredentialEnvEntry =
+  { env:string; kind?:'api-key'|'grant'; providers?:string[]; required?:boolean; purpose?:string; projection?:'env'; sets?:Record<string,string> }
+| { path:string; kind?:'api-key'|'grant'; providers?:string[]; required?:boolean; purpose?:string; projection:'file'; base?:'home'|'dataDir'; format?:string; sets?:Record<string,string> };
+/** rc.8 `sets`: non-secret companion env applied by the broker when this slot is granted (each key must be a declared env slot). Value `{{provider}}` is replaced with the granted credential's provider id. */
+/** `base`: where `path` is rooted — the app HOME (`<dataDir>/home`, default) or the data directory itself (e.g. a `$XXX_HOME={{dataDir}}` app). `format`: opaque id the credential broker maps a grant to (e.g. `codex-cli-auth-json`, `oauth-cli-kit`); the host never interprets it. */
+export interface CredentialResolverInput { appId:string; deploymentId:string; instanceId:string; principalId:string; credentialEnv:CredentialEnvEntry[]; }
+/** File projection policy (rc.6): `if-absent` (default) never clobbers a file the app rotated itself; `overwrite` replaces it (new grant version); `remove` deletes it (revoke / app-owned). The host never reads the file back. Events: `credential.injected` (env names + written files), `credential.file-kept`, `credential.file-removed`, `credential.env-rejected`, `credential.resolver-failed`. rc.7: a stopped instance adopts a changed app definition on open (`instance.definition-adopted`); only a running one refuses with `DEFINITION_CHANGED` (409). */
+export type CredentialFilePolicy = 'if-absent'|'overwrite'|'remove';
+export interface CredentialResolverResult { env?:Record<string,string>; files?:Array<{path:string;content?:string;mode?:number;policy?:CredentialFilePolicy}>; secrets?:string[]; }
+/** Seated by the credential broker (plugin-auth-apikey). Undefined / throw = inject nothing; the launch proceeds. */
+export type CredentialResolver = (input:CredentialResolverInput)=>Awaitable<CredentialResolverResult|undefined>;
+export interface RuntimeManifestItem { id:string; version:string; kind:'tar.gz'|'zip'; installTo:string; platforms:Record<string,{asset:string;sha256:string;size?:number;strip?:number;url?:string}>; }
+export interface RuntimeManifest { schema:1; sources:Array<{id:string;kind:'https'|'file';base:string}>; items:RuntimeManifestItem[]; }
+export interface RuntimeSelection { manifest:RuntimeManifest; item:string; exec:string; }
+interface OwnedDeploymentBase extends DeploymentBase { mode:'owned'; args:string[]; cwd?:string; env?:Record<string,string>; envAllowlist?:string[]; credentialEnv?:CredentialEnvEntry[]; }
+export type OwnedDeployment = OwnedDeploymentBase & ({ command:string; runtime?:never }|{ command?:never; runtime:RuntimeSelection });
+export interface AttachedDeployment extends DeploymentBase { mode:'attach'; url:string; }
+export type Deployment = OwnedDeployment|AttachedDeployment;
+/** rc.27 `packageName`: the npm package shipping this app — the usage-evidence `hanaRef`. Optional; the installed-package scan binds it otherwise (`AppHost.bindPackageName`). */
+export interface AppDefinition { id:string; name:string; singleInstanceOnly?:boolean; packageName?:string; deployments:Deployment[]; }
+export interface InstanceRecord {
+  id:string; appId:string; deploymentId:string; dataId:string; principalId:string; dataDir:string; mode:'owned'|'attach';
+  definitionHash:string; status:InstanceStatus; runtimeId:string|null; endpoint:string|null; gatewayOrigin:string|null;
+  pid:number|null; guardianPid:number|null; createdAt:number; updatedAt:number; errorCode?:string;
+}
+export interface ViewLease { principalId:string; viewId:string; instanceId:string; generation:number; status:LeaseStatus; expiresAt:number; createdAt:number; originalSessionId:string|null; }
+export interface StoredLease extends ViewLease { tokenHash:string; }
+export interface HostEvent { sequence:number; at:number; type:string; instanceId:string; principalId:string; viewId?:string; generation?:number; [key:string]:unknown; }
+/** rc.27: a request the instance's gateway forwarded for an authorized view (never bootstrap, denials, 401/403 or host probes). In-memory only. */
+export interface InstanceActivity { type:'instance.activity'; instanceId:string; appId:string; deploymentId:string; principalId:string; at:number; }
+export interface Snapshot { schema:1; revision:number; sequence:number; instances:InstanceRecord[]; leases:StoredLease[]; events:HostEvent[]; }
+export interface SnapshotStore { init():Promise<void>; load():Promise<Snapshot>; save(snapshot:Snapshot):Promise<void>; close():Promise<void>; }
+export interface OpenRequest { appId:string; deploymentId:string; viewId:string; leaseToken?:string; instanceId?:string; originalSessionId?:string; }
+export interface LeaseRequest { viewId:string; leaseToken:string; }
+export interface RecoverRequest { viewId:string; instanceId:string; confirm:true; }
+export interface OpenReceipt { instance:InstanceRecord; lease:ViewLease; leaseToken:string; uiUrl:string|null; originalSessionId:string|null; }
+export interface AppListing {
+  contractVersion:1; apps:Array<{id:string;name:string;singleInstanceOnly:boolean;packageName:string|null;deployments:Array<{id:string;dataId:string;mode:'owned'|'attach';embedding:'direct'|'gateway';credentialEnv:CredentialEnvEntry[]}>}>;
+  instances:InstanceRecord[]; views:ViewLease[]; sequence:number;
+}
+export interface EventPage { events:HostEvent[]; sequence:number; resetRequired:boolean; }
+export interface HostOptions {
+  store:SnapshotStore; dataRoot:string; parentOrigin:string; leaseTtlMs?:number; sweepIntervalMs?:number;
+  nodeBinary?:string; clock?:()=>number; checkpoint?:(point:string,details:Record<string,unknown>)=>Awaitable<void>; credentialResolver?:CredentialResolver|null;
+  runtimeLedgerReader?:(root:string)=>Awaitable<{schema:1;items:Record<string,{version:string}>}>;
+}
+export class AppHost {
+  constructor(options:HostOptions);
+  /** rc.4: seat or clear the credential broker; returns a disposer that clears it only if still the same function. */
+  setCredentialResolver(resolver:CredentialResolver|null):()=>void;
+  register(definition:AppDefinition):{appId:string;definitionHash:string}; init():Promise<this>;
+  /** rc.27: bind the npm package that ships `appId` (from the installed scan); a definition-declared `packageName` wins. */
+  bindPackageName(appId:string,packageName:string):void;
+  /** Usage-evidence `hanaRef` for an app, or null when unknown (then no evidence is reported for it). */
+  packageName(appId:string):string|null;
+  /** rc.27: real gateway activity per instance; not persisted, not in `eventsSince`. Returns a disposer. */
+  onActivity(listener:(activity:InstanceActivity)=>void):()=>void;
+  beginOpen(input:OpenRequest,principalId?:string):Promise<OpenReceipt>;
+  open(input:OpenRequest,principalId?:string):Promise<OpenReceipt>; start(input:OpenRequest,principalId?:string):Promise<OpenReceipt>;
+  resume(input:LeaseRequest,principalId?:string,options?:{waitForReady?:boolean}):Promise<OpenReceipt>;
+  recoverView(input:RecoverRequest,principalId?:string):Promise<OpenReceipt>;
+  heartbeat(input:LeaseRequest,principalId?:string):Promise<ViewLease>;
+  close(input:LeaseRequest,principalId?:string):Promise<{instanceId:string;alreadyClosed:boolean}>;
+  stop(instanceId:string,options?:{confirm?:boolean},principalId?:string):Promise<InstanceRecord>; stopAll():Promise<void>;
+  sweepLeases():Promise<void>; instance(id:string,principalId?:string):InstanceRecord|null; instanceList(principalId?:string):InstanceRecord[];
+  list(principalId?:string):AppListing; eventsSince(sequence?:number,principalId?:string):EventPage;
+  subscribe(listener:(event:HostEvent|{type:'host.error';code:string})=>void):()=>void;
+  logTail(id:string,limit?:number,principalId?:string):Array<{at:number;stream:string;text:string}>; dispose():Promise<void>;
+}
+export class AppHostError extends Error { constructor(code:string,message:string,details?:Record<string,unknown>,status?:number); code:string; details:Record<string,unknown>; status:number; }
+export class AtomicFileStore implements SnapshotStore {
+  constructor(root:string,options?:{checkpoint?:(point:string,snapshot:Snapshot)=>Awaitable<void>}); readonly path:string;
+  init():Promise<void>; load():Promise<Snapshot>; save(snapshot:Snapshot):Promise<void>; close():Promise<void>;
+}
+export interface DshStorageBinding {
+  layout:'single'; domain:'hanamesh_app_host'; readSnapshot():Promise<Snapshot|null|undefined>;
+  publishSnapshot(snapshot:Snapshot):Promise<void>; acquireExclusive():Promise<void>; releaseExclusive():Promise<void>;
+}
+export class DshDomainSnapshotStore implements SnapshotStore {
+  constructor(binding:DshStorageBinding); init():Promise<void>; load():Promise<Snapshot>; save(snapshot:Snapshot):Promise<void>; close():Promise<void>;
+}
+export interface AuthenticatedSubject { principalId:string; [key:string]:unknown; }
+export interface HttpOptions<Request=unknown> {
+  parentOrigin:string; authenticate(request:Request):Awaitable<AuthenticatedSubject|null>;
+  authorize(subject:AuthenticatedSubject,path:string,input:unknown):Awaitable<boolean>;
+}
+export function createHttpHandler<Request=unknown,Response=unknown>(host:AppHost,options:HttpOptions<Request>):(request:Request,response:Response)=>Promise<void>;
+export class FixedGateway {
+  constructor(options:{upstream:string;parentOrigin:string;isLeaseActive:(viewKey:string)=>boolean;cookieAllowlist?:string[];allowAppAuthorization?:boolean;maxUploadBytes?:number;frameAncestors?:string[];
+    /** rc.27: called once per forwarded request the upstream answered with anything but 401/403 (and per accepted WebSocket upgrade). */
+    onForward?:()=>void});
+  origin:string; start():Promise<string>; issue(viewKey:string):string; close():Promise<void>;
+}
+export function rewriteCsp(value:string,parentOrigin:string):string;
+export function embeddingHeaders(rawHeaders:string[],parentOrigin:string):string[];
+export function validateDefinition(input:AppDefinition):AppDefinition;
+/** rc.27 usage evidence: `open` once per instance reaching ready, `use` once per app per UTC hour of real gateway activity, through the optional usage seat. */
+export const SOURCE_PLUGIN:'@hanamesh/dsh-app-host';
+export function hourBucket(ms:number):string;
+/** T6 usage receipt riding on a `use` event: provider × model × forwarded-request count of that UTC hour; never content. */
+export interface UsageReceipt { providerId:string; model:string|null; count:number; }
+export interface UsageRecordInput { hanaRef:string; action:'open'|'use'; occurredAt?:string; idempotencyKey:string; sourcePlugin:string; sourceHanaRef?:string; targetRef?:string; receipt?:UsageReceipt; }
+export interface UsageRecordResult { disposition:'recorded'|'duplicate'|'withheld'|'rejected'; eventId?:string; code?:string; }
+export interface UsageSeat { record(input:UsageRecordInput):Awaitable<UsageRecordResult>; }
+/** T6 receipt ledger (storage domain `hanamesh_router_receipts`): hourly rows per app × Router route, reported through the usage seat when the hour closes. */
+export interface ReceiptRoute { providerId:string; model:string|null; }
+export interface ReceiptRow { appId:string; providerId:string|null; model:string|null; hour:string; count:number; injections:number; firstAt:string; lastAt:string; reported:boolean; }
+export interface ReceiptLedger {
+  inject(input:{appId:string;instanceId:string;routes?:readonly {providerId:string;model?:string|null}[];at?:number}):Record<string,unknown>|null;
+  activity(input:{appId:string;instanceId:string;at?:number}):Record<string,unknown>;
+  forget(instanceId:string):void; routeOf(instanceId:string):ReceiptRoute|null;
+  pending(options?:{appId?:string;includeCurrent?:boolean;now?:number}):{appId:string;hour:string;occurredAt:number;count:number;receipt:UsageReceipt|null}[];
+  markReported(appId:string,hour:string):number; list(options?:{appId?:string}):ReceiptRow[]; size():number;
+  persist():Promise<void>; close():Promise<void>;
+}
+export function createReceiptLedger(options?:{domain?:{global:{get():unknown;set(value:unknown):Promise<void>}};clock?:()=>number;persistDelayMs?:number;maxItems?:number;retentionMs?:number}):ReceiptLedger;
+export function normalizeRoute(route:unknown):ReceiptRoute|null;
+export function createUsageEvidence(options:{host:AppHost;seat:()=>UsageSeat|unknown;receipts?:ReceiptLedger;logger?:{debug?:(...args:unknown[])=>void};clock?:()=>number;sweepIntervalMs?:number}):{
+  flush(options?:{appId?:string;includeCurrent?:boolean}):Promise<void>; settle():Promise<void>; receipts:ReceiptLedger; close():void;
+};
+export const name:'hanamesh-app-host';
+export const inject:readonly ['webServer','storageDomain','connection'];
+export function apply(ctx:unknown,config?:import('./dsh.js').DshPluginConfig):Promise<void>;

package/dist/index.js

@@ -0,0 +1,15 @@
+export { AppHost } from './manager.js';
+export { AppHostError } from './errors.js';
+export { AtomicFileStore, DshDomainSnapshotStore } from './store.js';
+export { createHttpHandler } from './routes.js';
+export { FixedGateway, rewriteCsp, embeddingHeaders } from './gateway.js';
+export { validateDefinition } from './descriptor.js';
+export { createUsageEvidence, hourBucket, SOURCE_PLUGIN } from './usage-evidence.js';
+export { createReceiptLedger, normalizeRoute } from './router/receipts.js';
+/** Bundle root: core API plus a lazy Cordis plugin face, so client-modules can discover this package. */
+export const name = 'hanamesh-app-host';
+export const inject = ['webServer', 'storageDomain', 'connection'];
+export async function apply(ctx, config = {}) {
+  const plugin = await import('./dsh.js');
+  return await plugin.apply(ctx, config);
+}

package/dist/launcher.js

@@ -0,0 +1,17 @@
+// A live group leader prevents process-group-ID reuse during cleanup.
+// It intentionally remains alive until the guardian terminates the owned group.
+import { spawn } from 'node:child_process';
+const send=value=>{if(process.connected)process.send(value,()=>{});};
+let started=false;
+process.on('SIGTERM',()=>{});
+process.on('SIGINT',()=>{});
+process.on('message',message=>{
+  if(started||message?.type!=='launch')return;started=true;
+  const c=message.config;
+  const app=spawn(c.command,c.args,{cwd:c.cwd,env:c.env,shell:false,detached:false,stdio:['ignore','inherit','inherit']});
+  app.once('spawn',()=>send({type:'spawned',pid:app.pid,launcherBinary:process.execPath}));
+  app.once('error',e=>send({type:'error',code:'SPAWN_FAILED',message:e.message}));
+  app.once('exit',(code,signal)=>send({type:'app-exit',code,signal}));
+});
+// The guardian owns this handle and is responsible for reaping it.
+setInterval(()=>{},60_000);

package/dist/library/catalog.js

@@ -0,0 +1,108 @@
+import { readFile } from 'node:fs/promises';
+import { AppHostError, requireCondition } from '../errors.js';
+
+const MAX_BYTES=2*1024*1024;
+const plain=value=>typeof value==='string'&&value.length>0&&!/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u.test(value);
+const own=(value,keys)=>value&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).every(key=>keys.includes(key));
+
+export function validateManifestUrl(value){
+  let url;try{url=new URL(value);}catch{throw new AppHostError('INVALID_CATALOG_URL','Catalog manifest URL is invalid.');}
+  requireCondition(url.protocol==='https:'&&!url.port&&!url.username&&!url.password&&!url.search&&!url.hash,
+    'INVALID_CATALOG_URL','Catalog manifests require standard-port HTTPS without credentials, query, or fragment.');
+  return url;
+}
+
+export function validateCatalogManifest(value){
+  requireCondition(own(value,['manifestVersion','providerId','name','description','homepage','attribution','transport','query'])&&
+    value.manifestVersion==='1.0.0'&&/^[a-z0-9]+(?:[.-][a-z0-9]+)+$/.test(value.providerId)&&plain(value.name)&&
+    own(value.attribution,['name','url','notice'])&&plain(value.attribution.name)&&
+    own(value.transport,['kind','endpoint','method'])&&value.transport.kind==='https-json'&&value.transport.method==='GET'&&
+    own(value.query,['supported','defaultLimit','maxLimit','sorts'])&&Array.isArray(value.query.supported)&&Array.isArray(value.query.sorts)&&
+    Number.isInteger(value.query.defaultLimit)&&value.query.defaultLimit>=1&&value.query.defaultLimit<=200&&
+    Number.isInteger(value.query.maxLimit)&&value.query.maxLimit>=value.query.defaultLimit&&value.query.maxLimit<=200,
+    'INVALID_CATALOG_MANIFEST','Catalog source manifest does not match schema 1.0.0.');
+  validateManifestUrl(value.attribution.url);
+  const endpoint=validateManifestUrl(value.transport.endpoint);
+  requireCondition(endpoint.pathname.endsWith('/v1/plugins'),'INVALID_CATALOG_MANIFEST','Catalog endpoint must end in /v1/plugins.');
+  return structuredClone(value);
+}
+
+function validateItem(item){
+  // Key set = schemas/catalog-provider-page.schema.json `item` (incl. optional `updatedAt`; the production source emits it — 2026-09-20).
+  requireCondition(own(item,['id','name','displayName','summary','description','homepage','latestVersion','license','categories','keywords','capabilities','compatibility','repository','installSource','package','publisher','media','updatedAt'])&&(item.updatedAt===undefined||(typeof item.updatedAt==='string'&&Number.isFinite(Date.parse(item.updatedAt))))&&
+    plain(item.id)&&item.id.length<=160&&plain(item.name)&&plain(item.displayName)&&plain(item.summary)&&
+    (item.categories===undefined||(Array.isArray(item.categories)&&new Set(item.categories).size===item.categories.length&&item.categories.every(x=>/^[a-z0-9][a-z0-9._:-]{0,63}$/.test(x))))&&
+    (item.package===undefined||(own(item.package,['registry','name'])&&item.package.registry==='npm'&&/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(item.package.name))),
+    'INVALID_CATALOG_PAGE','Catalog item does not match schema 1.0.0.');
+}
+
+export function validateProviderPage(value){
+  requireCondition(own(value,['schemaVersion','generatedAt','revision','items','page'])&&value.schemaVersion==='1.0.0'&&
+    Array.isArray(value.items)&&value.items.length<=200&&own(value.page,['nextCursor','total']),
+    'INVALID_CATALOG_PAGE','Catalog provider page does not match schema 1.0.0.');
+  for(const item of value.items)validateItem(item);
+  return structuredClone(value);
+}
+
+export function isApplication(item){return Boolean(item?.categories?.includes('hanamesh-app')&&item?.package?.registry==='npm');}
+/** rc.28 market: an npm-backed entry that is not a HanaMesh application installs as a plain DSH plugin (`dsh plugin add`). */
+export function isPlugin(item){return Boolean(item?.package?.registry==='npm'&&!isApplication(item));}
+/** `application` | `plugin` | `listing` (repository-only / no npm package: browse only). */
+export function itemKind(item){return isApplication(item)?'application':isPlugin(item)?'plugin':'listing';}
+
+/** Exact semver compare without a dependency: numeric core, then a prerelease sorts below its release; unparsable → 0. */
+export function compareVersions(a,b){
+  const parse=value=>{const m=/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(String(value??'').trim());return m&&{core:[+m[1],+m[2],+m[3]],pre:m[4]?m[4].split('.'):null};};
+  const x=parse(a),y=parse(b);if(!x||!y)return 0;
+  for(let i=0;i<3;i++)if(x.core[i]!==y.core[i])return x.core[i]<y.core[i]?-1:1;
+  if(!x.pre&&!y.pre)return 0;if(!x.pre)return 1;if(!y.pre)return -1;
+  for(let i=0;i<Math.max(x.pre.length,y.pre.length);i++){const p=x.pre[i],q=y.pre[i];if(p===undefined)return -1;if(q===undefined)return 1;const np=/^\d+$/.test(p),nq=/^\d+$/.test(q);
+    if(np&&nq){if(+p!==+q)return +p<+q?-1:1;}else if(np!==nq)return np?-1:1;else if(p!==q)return p<q?-1:1;}
+  return 0;
+}
+/** `latestVersion` of the catalog entry is strictly newer than the installed version. */
+export function upgradeAvailable(latestVersion,installedVersion){return compareVersions(latestVersion,installedVersion)>0;}
+
+async function responseJson(response,label){
+  requireCondition(response.ok,'CATALOG_HTTP_ERROR',`${label} returned HTTP ${response.status}.`,{status:response.status},502);
+  const contentType=response.headers.get('content-type')?.split(';')[0].trim().toLowerCase()??'';
+  requireCondition(/^application\/(?:json|.+\+json)$/.test(contentType)&&!response.headers.get('content-encoding'),
+    'CATALOG_RESPONSE_DENIED',`${label} must be unencoded JSON.`,{},502);
+  const declared=Number(response.headers.get('content-length')??0);
+  requireCondition(!declared||declared<=MAX_BYTES,'CATALOG_RESPONSE_TOO_LARGE',`${label} exceeds 2 MiB.`,{},502);
+  const bytes=new Uint8Array(await response.arrayBuffer());
+  requireCondition(bytes.byteLength<=MAX_BYTES,'CATALOG_RESPONSE_TOO_LARGE',`${label} exceeds 2 MiB.`,{},502);
+  try{return JSON.parse(new TextDecoder().decode(bytes));}catch{throw new AppHostError('INVALID_CATALOG_JSON',`${label} returned malformed JSON.`,{},502);}
+}
+
+async function sameOriginFetch(start,fetchImpl,label){
+  const origin=start.origin;let current=start;
+  for(let redirects=0;redirects<=3;redirects++){
+    const response=await fetchImpl(current,{redirect:'manual',headers:{accept:'application/json','accept-encoding':'identity'}});
+    if([301,302,303,307,308].includes(response.status)){
+      requireCondition(redirects<3,'CATALOG_REDIRECT_DENIED','Catalog redirected more than three times.',{},502);
+      const location=response.headers.get('location');requireCondition(location,'CATALOG_REDIRECT_DENIED','Catalog redirect lacks a location.',{},502);
+      const next=new URL(location,current);requireCondition(next.origin===origin,'CATALOG_REDIRECT_DENIED','Catalog redirects must remain on the approved origin.',{},502);
+      current=next;continue;
+    }
+    return{response,url:current};
+  }
+}
+
+export async function loadCatalog({fixture,sources=[],fetchImpl=globalThis.fetch,query='',category='',cursor}={}){
+  if(fixture){
+    requireCondition(typeof fixture==='string','INVALID_FIXTURE','Catalog fixture path is required.');
+    let value;try{value=JSON.parse(await readFile(fixture,'utf8'));}catch(error){throw new AppHostError('INVALID_FIXTURE','Catalog fixture could not be read.',{code:error.code});}
+    return{source:{kind:'fixture',path:fixture},...validateProviderPage(value)};
+  }
+  const enabled=sources.filter(source=>source?.enabled!==false);
+  requireCondition(enabled.length===1,'CATALOG_SOURCE_REQUIRED','Exactly one catalog source must be enabled.');
+  const manifestUrl=validateManifestUrl(enabled[0].manifestUrl);
+  const manifestResponse=await sameOriginFetch(manifestUrl,fetchImpl,'Catalog manifest');
+  const manifest=validateCatalogManifest(await responseJson(manifestResponse.response,'Catalog manifest'));
+  const endpoint=validateManifestUrl(manifest.transport.endpoint);
+  requireCondition(endpoint.origin===manifestUrl.origin,'INVALID_CATALOG_MANIFEST','Catalog endpoint must share the manifest origin.');
+  if(query)endpoint.searchParams.set('q',String(query).slice(0,200));if(category)endpoint.searchParams.set('category',String(category).slice(0,64));if(cursor)endpoint.searchParams.set('cursor',String(cursor).slice(0,2048));endpoint.searchParams.set('limit','50');
+  const pageResponse=await sameOriginFetch(endpoint,fetchImpl,'Catalog page');
+  return{source:{kind:'remote',manifestUrl:manifestUrl.href,manifest},...validateProviderPage(await responseJson(pageResponse.response,'Catalog page'))};
+}

package/dist/library/domain.js

@@ -0,0 +1,8 @@
+import { defineDomain } from '@deepseek-ai/dsh-storage-domain';
+import { z as zod } from 'zod';
+
+const source=zod.object({manifestUrl:zod.string(),enabled:zod.boolean()});
+export const libraryDomainSpec=defineDomain({name:'hanamesh_library',version:1,layout:'single',tables:{},global:{
+  schema:zod.object({schema:zod.literal(1),revision:zod.number().int().nonnegative(),sources:zod.array(source)}),
+  initial:{schema:1,revision:0,sources:[]},
+}});