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

package/dist/gateway.js

@@ -1,7 +1,8 @@
 import { createServer, request } from 'node:http';
 import { randomBytes, createHash } from 'node:crypto';
 import { AppHostError, requireCondition, bounded } from './errors.js';
-import { loopbackOrigin } from './descriptor.js';
+import { documentOrigin, DESKTOP_ORIGIN } from './workspace-origin.js';
+import { loopbackOrigin, workspaceOrigin } from './descriptor.js';
 
 /**
  * `frame-ancestors` is matched against EVERY ancestor, not just the direct parent. Inside a
@@ -15,6 +16,7 @@ export function frameAncestorsValue(parentOrigin, frameAncestors = []) {
 }
 /** Only exact origins of a scheme a webview can actually host a top-level document on. */
 export function ancestorOrigin(value) {
+  if (value === DESKTOP_ORIGIN) return 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 &&
@@ -40,6 +42,8 @@ export function embeddingHeaders(rawHeaders, ancestors) {
   return output;
 }
 const token = () => randomBytes(32).toString('hex');
+// Keep retired names reserved for the process lifetime; 192-bit labels fit DNS's 63-byte limit.
+const desktopNames = new Set();
 function cookies(header) {
   const map = new Map();
   for (const part of (header ?? '').split(';')) {
@@ -55,7 +59,7 @@ function fail(res, status, 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);
+    this.upstream = loopbackOrigin(upstream); this.parentOrigin = workspaceOrigin(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.');
@@ -63,6 +67,7 @@ export class FixedGateway {
     this.allowAppAuthorization = allowAppAuthorization; this.maxUploadBytes = maxUploadBytes;
     requireCondition(typeof onForward === 'function','INVALID_GATEWAY','onForward must be a function.');
     this.onForward = onForward;
+    this.children = new Map(); this.pendingChildren = new Map(); this.scopeKey = null; this.closed = false; this.authorizations = new Map();
     this.tickets = new Map(); this.grants = new Map(); this.sockets = new Set(); this.upstreams = new Set();
     this.cookiePrefix = `hm_app_${token().slice(0,12)}_`;
   }
@@ -72,7 +77,14 @@ export class FixedGateway {
     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}`;
+    const port = this.server.address().port;
+    if (this.parentOrigin === DESKTOP_ORIGIN && this.scopeKey) {
+      const name = token().slice(0,48);
+      if (desktopNames.has(name)) { await this.close(); throw new AppHostError('GATEWAY_ORIGIN_REUSED','A retired origin name cannot be reassigned.'); }
+      desktopNames.add(name);
+      this.origin = `http://control-${name}.localhost:${port}`;
+      this.dataOrigin = `http://data-${name}.localhost:${port}`;
+    } else this.origin = `http://127.0.0.1:${port}`;
     return this.origin;
   }
   issue(viewKey) {
@@ -83,16 +95,115 @@ export class FixedGateway {
     const ticket = token(); this.tickets.set(ticket,{ viewKey, expiresAt:Date.now()+60_000 });
     return `${this.origin}/__hanamesh_bootstrap/${ticket}`;
   }
+  async issueAsync(viewKey) {
+    if (this.parentOrigin !== DESKTOP_ORIGIN) return this.issue(viewKey);
+    requireCondition(!this.closed && this.isLeaseActive(viewKey),'LEASE_EXPIRED','Inactive view.');
+    this.revokeInactive();
+    let child = this.children.get(viewKey);
+    if (!child) {
+      let pending = this.pendingChildren.get(viewKey);
+      if (!pending) {
+        requireCondition(this.children.size + this.pendingChildren.size < 512,'TOO_MANY_TICKETS','Too many views.');
+        pending = (async () => {
+          const scoped = new FixedGateway({upstream:this.upstream,parentOrigin:this.parentOrigin,frameAncestors:this.ancestors.split(' ').slice(1),
+            isLeaseActive:key => key === viewKey && this.isLeaseActive(key),cookieAllowlist:[...this.cookieAllowlist],
+            allowAppAuthorization:this.allowAppAuthorization,maxUploadBytes:this.maxUploadBytes,onForward:this.onForward});
+          scoped.scopeKey = viewKey;
+          await scoped.start();
+          if (this.closed || !this.isLeaseActive(viewKey)) { await scoped.close(); throw new AppHostError('LEASE_EXPIRED','Inactive view.'); }
+          this.children.set(viewKey,scoped);
+          scoped.expiryTimer = setInterval(() => { if (!scoped.isLeaseActive(viewKey)) void scoped.close(); },50);
+          scoped.expiryTimer.unref();
+          return scoped;
+        })();
+        this.pendingChildren.set(viewKey,pending);
+      }
+      try { child = await pending; }
+      finally { if (this.pendingChildren.get(viewKey) === pending) this.pendingChildren.delete(viewKey); }
+    }
+    return child.issue(viewKey);
+  }
+  authorizeChallenge(viewKey, gatewayOrigin, challenge) {
+    const child = this.children.get(viewKey), item = child?.tickets.get(challenge);
+    requireCondition(child && !child.closed && child.origin === gatewayOrigin && item && item.viewKey === viewKey &&
+      item.loaded && !item.authorized && item.expiresAt > Date.now() && child.isLeaseActive(viewKey),
+      'GATEWAY_CHALLENGE_DENIED','Invalid or inactive challenge.',{},403);
+    const authorization = token(); item.authorized = true;
+    child.authorizations.set(authorization,{challenge,viewKey,expiresAt:item.expiresAt});
+    return {authorization};
+  }
+  revokeInactive() {
+    for (const [key,child] of this.children) if (!this.isLeaseActive(key) || child.closed) {
+      this.children.delete(key); void child.close();
+    }
+  }
+  #desktopBootstrap(req,res) {
+    const challenge = req.url.slice('/__hanamesh_bootstrap/'.length), item = this.tickets.get(challenge);
+    if (!this.scopeKey || req.method !== 'GET' || req.headers['sec-fetch-dest'] !== 'iframe' ||
+      !item || item.loaded || item.expiresAt <= Date.now() || !this.isLeaseActive(item.viewKey)) return fail(res,403,'GATEWAY_BOOTSTRAP_DENIED');
+    item.loaded = true;
+    const nonce = token();
+    const body = `<!doctype html><meta charset="utf-8"><title>应用连接中</title><p>应用连接中…</p><script nonce="${nonce}">
+      const challenge=${JSON.stringify(challenge)}, gatewayOrigin=${JSON.stringify(this.origin)};
+      let proved=false, redeemed=false;
+      addEventListener('message',async event=>{
+        const exact=event.origin==='dsh-app://app'&&event.source===parent;
+        console.info('HM_BOOTSTRAP_PROOF',JSON.stringify({origin:event.origin,parent:event.source===parent,accepted:exact}));
+        if(!exact||event.data?.challenge!==challenge)return;
+        if(event.data.type==='hm-bootstrap-parent'&&!proved){proved=true;parent.postMessage({type:'hm-bootstrap-proof',challenge},'dsh-app://app');}
+        if(event.data.type==='hm-bootstrap-authorize'&&proved&&!redeemed&&typeof event.data.authorization==='string'){
+          redeemed=true;
+          const response=await fetch('/__hanamesh_exchange',{method:'POST',credentials:'omit',headers:{'content-type':'application/json'},
+            body:JSON.stringify({challenge,authorization:event.data.authorization})});
+          if(response.ok)location.replace(${JSON.stringify(this.dataOrigin+'/')});else document.querySelector('p').textContent='应用授权失败';
+        }
+      });
+      parent.postMessage({type:'hm-bootstrap-ready',challenge},'dsh-app://app');
+    </script>`;
+    res.writeHead(200,{'content-type':'text/html; charset=utf-8','cache-control':'no-store','referrer-policy':'origin',
+      'content-security-policy':`default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${this.ancestors}`});
+    res.end(body);
+  }
+  async #exchange(req,res) {
+    if (!this.scopeKey || req.method !== 'POST' || req.headers.origin !== this.origin || req.headers['sec-fetch-site'] !== 'same-origin' ||
+      req.headers['content-type'] !== 'application/json') return fail(res,403,'GATEWAY_EXCHANGE_DENIED');
+    let body='';
+    for await (const chunk of req) { body+=chunk; if(body.length>1024)return fail(res,413,'BODY_TOO_LARGE'); }
+    let input; try { input=JSON.parse(body); } catch { return fail(res,400,'INVALID_JSON'); }
+    const grant=this.authorizations.get(input.authorization);
+    if(!grant || Object.keys(input).some(k=>!['challenge','authorization'].includes(k)) || grant.challenge!==input.challenge ||
+      grant.expiresAt<=Date.now() || !this.isLeaseActive(grant.viewKey))return fail(res,403,'GATEWAY_EXCHANGE_DENIED');
+    this.authorizations.delete(input.authorization);this.tickets.delete(grant.challenge);
+    this.grants.clear();this.grants.set(token(),{viewKey:grant.viewKey,initialNavigation:true,navigated:false});
+    res.writeHead(204,{'cache-control':'no-store'});res.end();
+  }
+  #desktopAuthorized(req) {
+    if (!this.scopeKey || this.closed || req.headers.host !== new URL(this.dataOrigin).host || !this.isLeaseActive(this.scopeKey)) return false;
+    const grant = [...this.grants.values()].find(g => g.viewKey === this.scopeKey);
+    if (!grant) return false;
+    let referer;try {referer=documentOrigin(req.headers.referer);}catch{}
+    // One natural control-to-data navigation, tied to the redeemed complete live view binding.
+    if (grant.initialNavigation && req.method === 'GET' && req.url === '/' && !req.headers.origin &&
+      req.headers['sec-fetch-dest'] === 'iframe' && req.headers['sec-fetch-mode'] === 'navigate' &&
+      req.headers['sec-fetch-site'] === 'cross-site' && referer === this.origin) {
+      grant.initialNavigation = false; grant.navigated = true; return true;
+    }
+    if (!grant.navigated) return false;
+    if (req.headers.upgrade?.toLowerCase() === 'websocket') return req.headers.origin === this.dataOrigin;
+    return req.headers['sec-fetch-site'] === 'same-origin' &&
+      (req.headers.origin ? req.headers.origin === this.dataOrigin : referer === this.dataOrigin);
+  }
   #requestShape(req) {
-    if (req.headers.host !== new URL(this.origin).host) return false;
+    if (![this.origin,this.dataOrigin].filter(Boolean).some(origin => req.headers.host === new URL(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.origin && ![this.parentOrigin,this.origin,this.dataOrigin].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;
+    if (this.parentOrigin === DESKTOP_ORIGIN) return this.#desktopAuthorized(req);
     // Cookie capability + live lease. Origin/loopback alone never authenticate.
     for (const [name,value] of cookies(req.headers.cookie)) {
       if (!name.startsWith(this.cookiePrefix)) continue;
@@ -122,7 +233,7 @@ export class FixedGateway {
     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; }
+    try { referer = documentOrigin(req.headers.referer); } catch { return false; }
     return referer === this.parentOrigin;
   }
   #liveGrantExists() {
@@ -143,10 +254,11 @@ export class FixedGateway {
     return headers;
   }
   #bootstrap(req,res) {
+    if (this.parentOrigin === DESKTOP_ORIGIN) return this.#desktopBootstrap(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 {}
+    try { referer = documentOrigin(req.headers.referer); } 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);
@@ -174,13 +286,25 @@ export class FixedGateway {
   #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.parentOrigin === DESKTOP_ORIGIN && req.headers.host === new URL(this.origin).host && req.url === '/__hanamesh_exchange') {
+      void this.#exchange(req,res).catch(()=>{if(!res.headersSent)fail(res,400,'GATEWAY_EXCHANGE_DENIED');else res.destroy();});return;
+    }
+    if (this.parentOrigin === DESKTOP_ORIGIN) {
+      if (req.headers.host === new URL(this.origin).host) {
+        if (req.url.startsWith('/__hanamesh_bootstrap/')) return this.#bootstrap(req,res);
+        return fail(res,403,'GATEWAY_CONTROL_ONLY');
+      }
+      if (req.url.startsWith('/__hanamesh_bootstrap/') || req.url === '/__hanamesh_exchange') return fail(res,403,'GATEWAY_DATA_ONLY');
+    } else 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));
+      // A nested app frame has both the workspace and its own registered data origin as ancestors.
+      // Only the data response admits that exact live view origin; control/bootstrap stays separate.
+      const ancestors = this.dataOrigin ? `${this.ancestors} ${this.dataOrigin}` : this.ancestors;
+      res.writeHead(response.statusCode, embeddingHeaders(response.rawHeaders,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(); });
@@ -215,8 +339,13 @@ export class FixedGateway {
     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();
+  close() { return this.closeTask ??= this.#close(); }
+  async #close() {
+    this.closed = true; clearInterval(this.expiryTimer);
+    this.tickets.clear(); this.grants.clear(); this.authorizations.clear();
+    await Promise.allSettled([...this.pendingChildren.values()]);
+    const children=[...this.children.values()];this.children.clear();
+    await Promise.all(children.map(child=>child.close()));
     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/git-process.js

@@ -0,0 +1,64 @@
+// Module-owned process boundary. No user Git config or credential store is modified.
+import {fork} from 'node:child_process';
+import {openSync,readSync,closeSync,rmSync} from 'node:fs';
+import {join,isAbsolute} from 'node:path';
+const policy=Object.freeze({GIT_CONFIG_NOSYSTEM:'1',GIT_TERMINAL_PROMPT:'0',GIT_CONFIG_COUNT:'2',
+  GIT_CONFIG_KEY_0:'credential.helper',GIT_CONFIG_VALUE_0:'',
+  GIT_CONFIG_KEY_1:'credential.helper',GIT_CONFIG_VALUE_1:'!gh auth git-credential'});
+export function safeGitEnv(base=process.env){
+ const env={...base};
+ for(const key of Object.keys(env))if(/^GIT_CONFIG_(?:COUNT|KEY_\d+|VALUE_\d+|PARAMETERS)$/.test(key)||/^GIT_TRACE/.test(key)||['GIT_ASKPASS','SSH_ASKPASS'].includes(key))delete env[key];
+ return {...env,...policy,npm_config_manage_package_manager_versions:'false',pnpm_config_manage_package_manager_versions:'false'};
+}
+export function hasSafeGitEnv(env=process.env){return Object.entries(policy).every(([key,value])=>env[key]===value)&&!env.GIT_CONFIG_PARAMETERS;}
+export function requireGuardedGitEnv(env=process.env){
+ if(!hasSafeGitEnv(env)||!env.GIT_TRACE2_EVENT)throw Object.assign(new Error('Run this installation/check through node scripts/safe-git.mjs <command>.'),{code:'GIT_GUARD_REQUIRED'});
+}
+const forbidden=/(?:^|[\s/"'])git-credential-osxkeychain(?:$|[\s"'])|(?:^|[\s"'])credential-osxkeychain(?:$|[\s"'])/u;
+/** Internal worker port: the parent and its IPC worker can independently remove this one fresh trace. */
+export function observeGitTrace(directory){
+ const trace=join(directory,'events.jsonl'),fd=openSync(trace,'r'),buffer=Buffer.alloc(64*1024);
+ let failure,position=0,pending='',closed=false;
+ return {check(final=false){
+  if(failure)throw failure;
+  let count;while((count=readSync(fd,buffer,0,buffer.length,position))>0){position+=count;pending+=buffer.toString('utf8',0,count);}
+  const lines=pending.split('\n');pending=lines.pop();if(final&&pending)lines.push(pending);
+  for(const line of lines){
+   let event;try{event=JSON.parse(line);}catch{throw Object.assign(new Error('Invalid Git credential trace.'),{code:'GIT_TRACE_INVALID'});}
+   if(['child_start','exec'].includes(event.event)&&forbidden.test((event.argv??[]).join(' '))){failure=Object.assign(new Error('Forbidden macOS keychain helper was invoked; operation failed.'),{code:'GIT_KEYCHAIN_FORBIDDEN'});throw failure;}
+  }
+ },close(){if(closed)return;closed=true;try{closeSync(fd);}finally{rmSync(directory,{recursive:true,force:true});}}};
+}
+export function guardNodeBinary({workerNode,versions=process.versions,execPath=process.execPath}={}){
+ if(workerNode!==undefined)return typeof workerNode==='string'&&isAbsolute(workerNode)?workerNode:undefined;
+ return versions.electron===undefined&&isAbsolute(execPath)?execPath:undefined;
+}
+/** The detached worker owns the command group. IPC disconnect also cleans it if its caller dies abruptly. */
+export async function spawnGitSafe(command,args,options={}){
+ let directory,worker,deadline,abortFallback,message,stdout='',stderr='';
+ const {workerNode,signal,timeout,encoding='utf8',...childOptions}=options;
+ const nodeRuntime=guardNodeBinary({workerNode});
+ if(!nodeRuntime)throw Object.assign(new Error('An independent Node runtime is required; Electron cannot run the Git supervisor.'),{code:'GIT_GUARD_NODE_REQUIRED'});
+ const abort=()=>{if(worker?.connected)worker.send({abort:true});abortFallback??=setTimeout(()=>worker?.kill('SIGTERM'),1000);};
+ try{
+  if(signal?.aborted)throw Object.assign(new Error('Guarded command aborted.'),{name:'AbortError',code:'ABORT_ERR'});
+  const stdio=options.stdio==='inherit'?['ignore','inherit','inherit','ipc']:['ignore','pipe','pipe','ipc'];
+  worker=fork(new URL('./git-worker.js',import.meta.url),[],{cwd:options.cwd,env:safeGitEnv(options.env??process.env),execArgv:[],execPath:nodeRuntime,detached:process.platform!=='win32',stdio});
+  worker.stdout?.on('data',chunk=>{stdout=(stdout+chunk.toString(encoding)).slice(-4*1024*1024);});
+  worker.stderr?.on('data',chunk=>{stderr=(stderr+chunk.toString(encoding)).slice(-4*1024*1024);});
+  signal?.addEventListener('abort',abort,{once:true});
+  if(timeout)deadline=setTimeout(()=>{if(worker.connected)worker.send({timeout:true});},timeout);
+  const completed=new Promise((resolve,reject)=>{
+   worker.once('error',reject);worker.on('message',value=>{if(value.directory)directory=value.directory;else message=value;});worker.once('close',()=>resolve());
+  });
+  worker.send({command,args,options:{...childOptions,env:safeGitEnv(options.env??process.env)}});
+  await completed;
+  if(message?.error)throw Object.assign(new Error('Guarded command failed.'),message.error);
+  if(!message?.result)throw Object.assign(new Error('Git monitor exited without a result.'),{code:'GIT_GUARD_FAILED'});
+  return {...message.result,stdout,stderr};
+ }finally{
+  clearTimeout(deadline);clearTimeout(abortFallback);signal?.removeEventListener('abort',abort);
+  if(worker?.connected)worker.disconnect();
+  if(directory)rmSync(directory,{recursive:true,force:true});
+ }
+}

package/dist/git-worker.js

@@ -0,0 +1,50 @@
+// Internal IPC supervisor. The parent never detaches a package manager directly.
+import {spawn,spawnSync} from 'node:child_process';
+import {existsSync,mkdtempSync,writeFileSync,rmSync,realpathSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {dirname,join,basename} from 'node:path';
+import {observeGitTrace} from './git-process.js';
+let monitor,directory,timer,done=false,started=false;
+function finish(payload){
+ if(done)return;done=true;clearInterval(timer);
+ try{monitor?.check(true);}catch(error){payload={error:{code:error.code??'GIT_TRACE_INVALID'}};}
+ try{if(monitor)monitor.close();else if(directory)rmSync(directory,{recursive:true,force:true});}catch{payload={error:{code:'GIT_TRACE_CLEANUP_FAILED'}};}
+ const end=()=>{
+  if(process.platform==='win32'){spawnSync('taskkill',['/pid',String(process.pid),'/T','/F'],{stdio:'ignore'});process.exit(1);}
+  else process.kill(-process.pid,'SIGKILL');
+ };
+ if(process.connected)process.send(payload,end);else end();
+}
+function abort(code='ABORT_ERR'){finish({error:{code,...(code==='ABORT_ERR'?{name:'AbortError'}:{})}});}
+process.once('disconnect',()=>abort());
+process.once('SIGTERM',()=>abort());process.once('SIGINT',()=>abort());
+if(!process.connected)process.exit(1);
+process.on('message',request=>{
+ if(request.abort)return abort();if(request.timeout)return abort('ETIMEDOUT');
+ if(started)return;started=true;
+ try{
+  let {command,args,options}=request;
+  // No caller-owned trace exists before this IPC worker can clean on disconnect.
+  directory=mkdtempSync(join(realpathSync(options.env.TMPDIR??tmpdir()),'hm-git-guard-'));
+  writeFileSync(join(directory,'events.jsonl'),'',{mode:0o600});monitor=observeGitTrace(directory);
+  options.env={...options.env,GIT_TRACE2_EVENT:join(directory,'events.jsonl'),GIT_TRACE_REDACT:'1'};
+  if(!process.connected)return abort();
+  process.send({directory},error=>{if(error)abort();});
+  // Native Windows .cmd shims cannot be executed by spawn without a shell.
+  // Resolve the normal npm/global pnpm JS entry and keep argument arrays intact.
+  const manager=basename(command).replace(/\.cmd$/i,'').toLowerCase();
+  if(process.platform==='win32'&&['npm','npx','pnpm'].includes(manager)){
+   const pkg=manager==='pnpm'?'pnpm':'npm',entry=manager==='pnpm'?'pnpm.cjs':manager+'-cli.js';
+   const supplied=options.env.npm_execpath;
+   const candidates=[...(supplied&&basename(supplied)===entry?[supplied]:[]),...[dirname(process.execPath),...(options.env.PATH??options.env.Path??'').split(';')].map(base=>join(base,'node_modules',pkg,'bin',entry))];
+   const cli=candidates.find(path=>existsSync(path));if(!cli)throw Object.assign(new Error('Package manager JS entry unavailable.'),{code:'PACKAGE_MANAGER_UNAVAILABLE'});
+   command=process.execPath;args=[cli,...args];
+  }
+  const {input,...spawnOptions}=options;
+  const child=spawn(command,args,{...spawnOptions,stdio:[input===undefined?'ignore':'pipe','inherit','inherit'],detached:false});
+  if(input!==undefined){child.stdin.on('error',()=>{});child.stdin.end(input);}
+  child.once('error',error=>finish({error:{code:error.code??'SPAWN_FAILED'}}));
+  child.once('close',(code,signal)=>finish({result:{code,status:code,signal}}));
+  timer=setInterval(()=>{try{monitor.check();}catch(error){finish({error:{code:error.code??'GIT_TRACE_INVALID'}});}},25);
+ }catch(error){finish({error:{code:error.code??'GIT_GUARD_FAILED'}});}
+});

package/dist/index.d.ts

@@ -47,8 +47,8 @@ export interface AppListing {
 }
 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;
+  store:SnapshotStore; dataRoot:string; parentOrigin:string; frameAncestors?:string[]; leaseTtlMs?:number; sweepIntervalMs?:number;
+  nodeBinary?:string; nodeBinaryProvider?:()=>string|undefined; 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 {
@@ -66,6 +66,7 @@ export class AppHost {
   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>;
+  authorizeBootstrap(input:LeaseRequest & {gatewayOrigin:string;challenge:string},principalId?:string):Promise<{authorization:string}>;
   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>;
@@ -88,7 +89,7 @@ export class DshDomainSnapshotStore implements SnapshotStore {
 }
 export interface AuthenticatedSubject { principalId:string; [key:string]:unknown; }
 export interface HttpOptions<Request=unknown> {
-  parentOrigin:string; authenticate(request:Request):Awaitable<AuthenticatedSubject|null>;
+  parentOrigin:string; transportOrigin?: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>;
@@ -96,20 +97,20 @@ 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>;
+  origin:string; dataOrigin?:string; start():Promise<string>; issue(viewKey:string):string; issueAsync(viewKey:string):Promise<string>; authorizeChallenge(viewKey:string,gatewayOrigin:string,challenge:string):{authorization:string}; revokeInactive():void; 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. */
+/** Canonical collecting plugin identity; runtime/transport observations never form business Usage facts. */
 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. */
+/** Independent Router diagnostic receipt: routed provider/model and forwarded-request count; not a successful-business fact. */
 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. */
+/** Router diagnostic ledger (hanamesh_router_receipts). Pending/reported are legacy ledger state, not Usage confirmation. */
 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 {
@@ -122,6 +123,7 @@ export interface ReceiptLedger {
 }
 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;
+/** No verified original fact source is connected: logs USAGE_FACT_UNAVAILABLE and persists Router diagnostics only. Legacy scheduling options remain accepted; no reporting timer runs. flush/settle do not observe Usage completion. */
 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;
 };

package/dist/install-target/fixtures/catalog.json

@@ -0,0 +1,58 @@
+{
+  "schemaVersion": "1.0.0",
+  "revision": "install-target-contract-fixture-1",
+  "items": [
+    {
+      "id": "fixture.install-target.plugin",
+      "name": "@hanamesh-fixture/install-target-plugin",
+      "displayName": "测试目录 · 安装目标插件",
+      "summary": "Install-target contract fixture (test catalog, not a real product).",
+      "latestVersion": "1.2.3",
+      "categories": [
+        "utility"
+      ],
+      "package": {
+        "registry": "npm",
+        "name": "@hanamesh-fixture/install-target-plugin"
+      },
+      "publisher": {
+        "name": "HanaMesh fixture"
+      }
+    },
+    {
+      "id": "fixture.install-target.app",
+      "name": "@hanamesh-fixture/install-target-app",
+      "displayName": "测试目录 · 安装目标应用",
+      "summary": "Install-target contract fixture application (test catalog).",
+      "latestVersion": "0.4.0",
+      "categories": [
+        "hanamesh-app"
+      ],
+      "package": {
+        "registry": "npm",
+        "name": "@hanamesh-fixture/install-target-app"
+      },
+      "publisher": {
+        "name": "HanaMesh fixture"
+      }
+    },
+    {
+      "id": "fixture.install-target.repository-only",
+      "name": "install-target-repository-only",
+      "displayName": "测试目录 · 仅源码",
+      "summary": "Repository-only listing; the market cannot install it.",
+      "categories": [
+        "utility"
+      ],
+      "repository": {
+        "url": "https://example.com/repository"
+      },
+      "publisher": {
+        "name": "HanaMesh fixture"
+      }
+    }
+  ],
+  "page": {
+    "total": 3
+  }
+}

package/dist/install-target/fixtures/consumer-cases.json

@@ -0,0 +1,148 @@
+{
+  "contract": "hanamesh.install-target",
+  "contractVersion": "1",
+  "workspace": "http://127.0.0.1:43123/workspace/fixture-session?token=fixture-token#previous",
+  "targets": [
+    {
+      "id": "CN01",
+      "note": "both identifiers (current Desktop link shape)",
+      "target": {
+        "itemId": "fixture.install-target.plugin",
+        "packageName": "@hanamesh-fixture/install-target-plugin"
+      },
+      "expect": "navigate",
+      "resolves": "fixture.install-target.plugin"
+    },
+    {
+      "id": "CN02",
+      "note": "scoped application",
+      "target": {
+        "itemId": "fixture.install-target.app",
+        "packageName": "@hanamesh-fixture/install-target-app"
+      },
+      "expect": "navigate",
+      "resolves": "fixture.install-target.app"
+    },
+    {
+      "id": "CN03",
+      "note": "package name only; a consumer may require both identifiers",
+      "target": {
+        "packageName": "@hanamesh-fixture/install-target-plugin"
+      },
+      "expect": "navigate",
+      "optional": true,
+      "resolves": "fixture.install-target.plugin"
+    },
+    {
+      "id": "CN04",
+      "note": "item id only; a consumer may require both identifiers",
+      "target": {
+        "itemId": "fixture.install-target.plugin"
+      },
+      "expect": "navigate",
+      "optional": true,
+      "resolves": "fixture.install-target.plugin"
+    },
+    {
+      "id": "CR01",
+      "note": "caller-supplied version",
+      "target": {
+        "itemId": "fixture.install-target.plugin",
+        "packageName": "@hanamesh-fixture/install-target-plugin",
+        "version": "9.0.0"
+      },
+      "expect": "refuse"
+    },
+    {
+      "id": "CR02",
+      "note": "caller-supplied download location",
+      "target": {
+        "itemId": "fixture.install-target.plugin",
+        "packageName": "@hanamesh-fixture/install-target-plugin",
+        "url": "https://evil.example/pkg.tgz"
+      },
+      "expect": "refuse"
+    },
+    {
+      "id": "CR03",
+      "note": "package name grammar",
+      "target": {
+        "itemId": "fixture.install-target.plugin",
+        "packageName": "../escape"
+      },
+      "expect": "refuse"
+    },
+    {
+      "id": "CR04",
+      "note": "item id longer than 160",
+      "target": {
+        "itemId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "packageName": "@hanamesh-fixture/install-target-plugin"
+      },
+      "expect": "refuse"
+    },
+    {
+      "id": "CR05",
+      "note": "control character",
+      "target": {
+        "itemId": "fixture\u0007id",
+        "packageName": "@hanamesh-fixture/install-target-plugin"
+      },
+      "expect": "refuse"
+    },
+    {
+      "id": "CR06",
+      "note": "no identifier",
+      "target": {},
+      "expect": "refuse"
+    }
+  ],
+  "handshake": [
+    {
+      "id": "CH01",
+      "note": "provider implementing v1",
+      "provider": {
+        "contract": "hanamesh.install-target",
+        "contractVersion": "1",
+        "supported": [
+          "1"
+        ]
+      },
+      "expect": "accept"
+    },
+    {
+      "id": "CH02",
+      "note": "provider implementing only a future version",
+      "provider": {
+        "contract": "hanamesh.install-target",
+        "contractVersion": "2",
+        "supported": [
+          "2"
+        ]
+      },
+      "expect": "refuse"
+    },
+    {
+      "id": "CH03",
+      "note": "provider without a declaration (0.2.0-rc.7 and older)",
+      "provider": null,
+      "expect": "refuse"
+    },
+    {
+      "id": "CH04",
+      "note": "declaration for a different contract",
+      "provider": {
+        "contract": "hanamesh.something-else",
+        "contractVersion": "1",
+        "supported": [
+          "1"
+        ]
+      },
+      "expect": "refuse"
+    }
+  ],
+  "workspaces": [
+    "http://127.0.0.1:43123/workspace/fixture-session?token=fixture-token#previous",
+    "http://localhost:43123/workspace/fixture-session?token=fixture-token#previous"
+  ]
+}