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

package/dist/installation-status.d.ts

@@ -0,0 +1,21 @@
+/** Advertised metadata only. Discovery performs no installation read. */
+export const INSTALLATION_STATUS_CAPABILITY:Readonly<{contract:'hanamesh.installation-status';contractVersion:'1';path:'/hanamesh/library/installation-status'}>;
+export interface InstallationReaderConfig {
+ /** Absolute official executable and explicitly selected user/config directories. Never supplied by a website. */
+ executable:string;home:string;configDir:string;
+ /** Identity and exact HTTPS marketplace URL from the registered AgentPluginDTO. */
+ pluginName:string;marketplace:string;marketplaceUrl:string;
+ /** Required positive bounded operation budgets. No product default is inferred. */
+ timeoutMs:number;maxOutputBytes:number;
+}
+export interface InstallationStatusRequest {contractVersion:'1';consent:'read-installations'}
+export interface InstallationObservation {
+ channel:'hanamesh'|'dsh'|'claude'|'codex';
+ scope:{id:'current-runtime'|'other-runtime'|'agent-cli'|'desktop-app';kind:'responding-runtime'|'unobserved-runtime'|'official-user-profile'|'desktop-app';label:string};
+ status:'installed'|'not-installed'|'incomplete'|'unknown';version:string|null;versionKind:'core'|'agent-distribution';
+ components:readonly {name:string;version:string|null;active?:boolean;status?:string}[];
+ identity:{pluginName:string;marketplace:string}|null;
+ reason:{code:string;message:string;action:string}|null;
+ blocked?:readonly {code:string;moduleName?:string}[];
+}
+export interface InstallationStatus {schemaVersion:1;client:'hanamesh'|'dsh';checkedAt:string;observations:readonly InstallationObservation[];traceId?:string}

package/dist/installation-status.js

@@ -0,0 +1,2 @@
+/** Public read-only capability. A probe advertises this metadata without running readers. */
+export const INSTALLATION_STATUS_CAPABILITY=Object.freeze({contract:'hanamesh.installation-status',contractVersion:'1',path:'/hanamesh/library/installation-status'});

package/dist/library/catalog.js

@@ -1,45 +1,157 @@
+import semver from 'semver';
 import { readFile } from 'node:fs/promises';
 import { AppHostError, requireCondition } from '../errors.js';
 
+// Catalog schema versions are SemVer; install-target protocol '1' is a separate grammar.
+const catalogVersion=value=>typeof value==='string'&&/^1\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$(?![\s\S])/u.test(value);
+
 const MAX_BYTES=2*1024*1024;
+const HANAMESH_SCHEMA='hanamesh.catalog.v1';
+const MAX_SOURCE_LINKS=500;
 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));
+// WHATWG URL canonicalizes hostnames (including IPv6); no DNS lookup or origin aliasing.
+const catalogOrigin=url=>(url.protocol==='https:'&&!url.port)||
+  (url.protocol==='http:'&&['127.0.0.1','[::1]','localhost'].includes(url.hostname));
 
 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.');
+  const viewQuery=!url.search||(url.searchParams.size===1&&url.searchParams.get('view')==='hanamesh');
+  requireCondition(catalogOrigin(url)&&!url.username&&!url.password&&viewQuery&&!url.hash,
+    'INVALID_CATALOG_URL','Catalog manifests require standard-port HTTPS or loopback HTTP (127.0.0.1, ::1, localhost), with only an optional view=hanamesh query.');
   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)&&
+  let endpoint;try{endpoint=validateManifestUrl(value?.transport?.endpoint);}catch{throw new AppHostError('INVALID_CATALOG_MANIFEST','Catalog endpoint URL is invalid.');}
+  const hana=endpoint.searchParams.get('view')==='hanamesh';
+  requireCondition(own(value,['manifestVersion','providerId','name','description','homepage','attribution','transport','query',...(hana?['limits']:[])])&&
+    catalogVersion(value.manifestVersion)&&/^[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);
+    'INVALID_CATALOG_MANIFEST','Catalog source manifest does not match catalog schema major 1.');
+  if(hana){
+    requireCondition(displayUrl(value.attribution.url,true)&&
+      own(value.limits,['maxBodyBytes','maxSourceLinks'])&&
+      Number.isSafeInteger(value.limits.maxBodyBytes)&&value.limits.maxBodyBytes>0&&value.limits.maxBodyBytes<=MAX_BYTES&&
+      Number.isSafeInteger(value.limits.maxSourceLinks)&&value.limits.maxSourceLinks>=0&&value.limits.maxSourceLinks<=MAX_SOURCE_LINKS&&
+      value.query.supported.every(key=>['q','category','cursor','limit'].includes(key))&&value.query.sorts.length===0,
+      'INVALID_CATALOG_MANIFEST','HanaMesh manifest limits or query declaration is invalid.');
+  }else{
+    const attribution=validateManifestUrl(value.attribution.url);
+    requireCondition(!attribution.search,'INVALID_CATALOG_MANIFEST','Default catalog attribution must not contain a query.');
+  }
   requireCondition(endpoint.pathname.endsWith('/v1/plugins'),'INVALID_CATALOG_MANIFEST','Catalog endpoint must end in /v1/plugins.');
   return structuredClone(value);
 }
 
+const textWithin=(value,max,nonempty=false)=>typeof value==='string'&&value.length<=max&&(!nonempty||value.length>0)&&
+  !/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u.test(value);
+const npmName=value=>textWithin(value,214,true)&&/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+function displayUrl(value,catalogSource=false){
+  if(!textWithin(value,2048,true))return false;
+  try{const url=new URL(value);return (catalogSource?catalogOrigin(url):url.protocol==='https:'&&!url.port)&&!url.username&&!url.password;}catch{return false;}
+}
+function timestamp(value,utc=false){
+  if(typeof value!=='string')return false;
+  const match=/^(\d{4})-(\d{2})-(\d{2})T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(?:\.\d+)?(Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.exec(value);
+  if(!match||(utc&&match[7]!=='Z')||!Number.isFinite(Date.parse(value)))return false;
+  const date=new Date(`${match[1]}-${match[2]}-${match[3]}T00:00:00Z`);
+  return Number.isFinite(date.getTime())&&date.toISOString().slice(0,10)===value.slice(0,10);
+}
+// Display-only C-INDEXER-CATALOG SuitePresentationDTO; never an install/upgrade decision.
+const suiteIdentities={
+  core:{names:['@hanamesh/core','hanamesh-core'],repo:'yzsnstotz/hanamesh-core'},
+  usage:{names:['@hanamesh/usage','hanamesh-usage'],repo:'yzsnstotz/hanamesh-usage'},
+  'app-host':{names:['@hanamesh/dsh-app-host'],repo:'yzsnstotz/hanamesh-plugin-app-host'},
+  brand:{names:['@hanamesh/brand','hanamesh-brand'],repo:'yzsnstotz/hanamesh-brand'},
+};
+const suiteComponent=value=>Object.hasOwn(suiteIdentities,value);
+const exactVersion=value=>textWithin(value,128,true)&&!value.startsWith('v')&&Boolean(semver.valid(value))&&value.trim()===value;
+const packageFact=fact=>fact&&suiteComponent(fact.component)&&suiteIdentities[fact.component].names.includes(fact.npmPackageName)&&suiteIdentities[fact.component].repo===fact.githubRepo;
+const distinctComponents=(facts,count)=>Array.isArray(facts)&&facts.length===count&&new Set(facts.map(fact=>fact?.component)).size===count;
+function suitePresentation(value,item){
+  if(!(own(value,['schemaVersion','id','role','component','canonicalHanaId','installable','installTargets','components','distributionVersion','agentPlugins'])&&
+    value.schemaVersion===1&&value.id==='hanamesh'&&['suite','component','client-only'].includes(value.role)&&suiteComponent(value.component)&&
+    (value.canonicalHanaId===null||plain(value.canonicalHanaId))&&typeof value.installable==='boolean'))return false;
+  const canonical=value.role==='suite'&&value.component==='usage'&&value.installable&&value.canonicalHanaId===item.id;
+  if(value.role!==(value.component==='usage'?'suite':value.component==='brand'?'client-only':'component')||value.installable!==canonical)return false;
+  if(value.distributionVersion!==undefined&&(!canonical||!exactVersion(value.distributionVersion)))return false;
+  if(value.components!==undefined&&(!canonical||!distinctComponents(value.components,4)||!value.components.every(fact=>
+    own(fact,['component','npmPackageName','githubRepo','version'])&&packageFact(fact)&&exactVersion(fact.version))))return false;
+  if(value.installTargets!==undefined){
+    if(!canonical||!distinctComponents(value.installTargets,3)||!value.installTargets.every(target=>{
+      if(!(own(target,['component','npmPackageName','githubRepo','version','source'])&&target.component!=='brand'&&packageFact(target)&&
+        (target.version===undefined||exactVersion(target.version))))return false;
+      const fact=value.components?.find(fact=>fact.component===target.component),source=target.source;
+      if(fact&&(fact.npmPackageName!==target.npmPackageName||fact.githubRepo!==target.githubRepo||
+        (target.version!==undefined&&fact.version!==target.version)))return false;
+      if(source?.source==='npm')return own(source,['source','name','version'])&&source.name===target.npmPackageName&&
+        exactVersion(source.version)&&source.version===target.version&&fact?.version===target.version;
+      // Approved standard distribution retains immutable historical Git DTOs, without choosing a fallback source.
+      return own(source,['source','repo','ref'])&&source.source==='github'&&source.repo===target.githubRepo&&
+        typeof source.ref==='string'&&/^[0-9a-f]{40}$/i.test(source.ref);
+    }))return false;
+  }
+  if(value.agentPlugins!==undefined){
+    const agents=value.agentPlugins;
+    if(!canonical||!Array.isArray(agents)||agents.length<1||agents.length>2||new Set(agents.map(agent=>agent?.host)).size!==agents.length||
+      !agents.every(agent=>own(agent,['host','pluginName','pluginId','marketplaceUrl','version'])&&['claude','codex'].includes(agent.host)&&
+        agent.pluginName==='hanamesh'&&agent.pluginId==='hanamesh@hanamesh'&&agent.marketplaceUrl==='https://github.com/yzsnstotz/hanamesh-plugins'&&
+        exactVersion(agent.version)&&agent.version===value.distributionVersion))return false;
+  }
+  return true;
+}
+
+function validateHanaItem(item,maxSourceLinks){
+  const optionalText={description:5000,latestVersion:64,license:80};
+  const source=item?.source;
+  requireCondition(own(item,['id','itemId','packageName','name','displayName','summary','catalogKind','source','description','homepage','latestVersion','license','categories','keywords','repository','package','publisher','updatedAt','official','suite'])&&
+    (item.official===undefined||typeof item.official==='boolean')&&(item.suite===undefined||suitePresentation(item.suite,item))&&
+    plain(item.id)&&item.id===item.itemId&&
+    textWithin(item.name,160,true)&&textWithin(item.displayName,120,true)&&textWithin(item.summary,1000)&&
+    ['application','plugin','entry'].includes(item.catalogKind)&&
+    (item.packageName===null?item.package===undefined:
+      npmName(item.packageName)&&own(item.package,['registry','name'])&&item.package.registry==='npm'&&item.package.name===item.packageName)&&
+    Object.entries(optionalText).every(([key,max])=>item[key]===undefined||textWithin(item[key],max))&&
+    (item.homepage===undefined||displayUrl(item.homepage))&&
+    (item.updatedAt===undefined||timestamp(item.updatedAt))&&
+    (item.categories===undefined||(Array.isArray(item.categories)&&item.categories.length<=32&&item.categories.every(value=>textWithin(value,64,true)&&/^[a-z0-9][a-z0-9._:-]{0,63}$/.test(value))))&&
+    (item.keywords===undefined||(Array.isArray(item.keywords)&&item.keywords.length<=64&&item.keywords.every(value=>textWithin(value,64))))&&
+    (item.repository===undefined||(own(item.repository,['url','subdirectory'])&&displayUrl(item.repository.url)&&new URL(item.repository.url).hostname==='github.com'&&
+      (item.repository.subdirectory===undefined||(textWithin(item.repository.subdirectory,240,true)&&!/^\/|^[a-z]:/i.test(item.repository.subdirectory)&&!item.repository.subdirectory.includes('\\')&&!item.repository.subdirectory.split('/').includes('..')))))&&
+    (item.publisher===undefined||(own(item.publisher,['name','url'])&&textWithin(item.publisher.name,120,true)&&(item.publisher.url===undefined||displayUrl(item.publisher.url))))&&
+    own(source,['sourceId','sourceRef','sourceLinks'])&&textWithin(source.sourceId,120,true)&&textWithin(source.sourceRef,512,true)&&
+    Array.isArray(source.sourceLinks)&&source.sourceLinks.length<=maxSourceLinks&&source.sourceLinks.every(link=>
+      own(link,['sourceId','sourceRef','sourceUrl','firstSeenAt','lastSeenAt'])&&textWithin(link.sourceId,120,true)&&textWithin(link.sourceRef,512,true)&&
+      displayUrl(link.sourceUrl)&&timestamp(link.firstSeenAt)&&timestamp(link.lastSeenAt)),
+    'INVALID_CATALOG_PAGE','HanaMesh catalog item does not match its public schema.');
+}
+
 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.');
+    'INVALID_CATALOG_PAGE','Catalog item does not match catalog schema major 1.');
 }
 
-export function validateProviderPage(value){
-  requireCondition(own(value,['schemaVersion','generatedAt','revision','items','page'])&&value.schemaVersion==='1.0.0'&&
+export function validateProviderPage(value,{maxItems=200,maxSourceLinks=MAX_SOURCE_LINKS}={}){
+  if(value?.schemaVersion===HANAMESH_SCHEMA){
+    requireCondition(own(value,['schemaVersion','generatedAt','items','page'])&&
+      (value.generatedAt===undefined||timestamp(value.generatedAt,true))&&Array.isArray(value.items)&&value.items.length<=maxItems&&own(value.page,['nextCursor','total'])&&
+      (Object.keys(value.page).length===0||(Object.keys(value.page).length===2&&typeof value.page.nextCursor==='string'&&value.page.nextCursor.length>0&&Number.isSafeInteger(value.page.total)&&value.page.total>=0)),
+      'INVALID_CATALOG_PAGE','HanaMesh catalog page does not match its public schema.');
+    for(const item of value.items)validateHanaItem(item,maxSourceLinks);
+    return structuredClone(value);
+  }
+  requireCondition(own(value,['schemaVersion','generatedAt','revision','items','page'])&&catalogVersion(value.schemaVersion)&&
     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.');
+    'INVALID_CATALOG_PAGE','Catalog provider page does not match catalog schema major 1.');
   for(const item of value.items)validateItem(item);
   return structuredClone(value);
 }
@@ -63,16 +175,26 @@ export function compareVersions(a,b){
 /** `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);
+async function responseJson(response,label,maxBytes=MAX_BYTES,providerErrors=false){
+  if(!providerErrors)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);
+  requireCondition(!declared||declared<=maxBytes,'CATALOG_RESPONSE_TOO_LARGE',`${label} exceeds the declared body limit.`,{},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);}
+  requireCondition(bytes.byteLength<=maxBytes,'CATALOG_RESPONSE_TOO_LARGE',`${label} exceeds the declared body limit.`,{},502);
+  let value;try{value=JSON.parse(new TextDecoder().decode(bytes));}catch{throw new AppHostError('INVALID_CATALOG_JSON',`${label} returned malformed JSON.`,{},502);}
+  if(!response.ok){
+    const codes={INVALID_REQUEST:400,INVALID_CATALOG_ORIGIN:400,CATALOG_CHANGED:409,UPSTREAM_UNAVAILABLE:503,CATALOG_RESPONSE_TOO_LARGE:500};
+    const code=value?.error?.code;
+    if(typeof code==='string'&&Object.hasOwn(codes,code)&&codes[code]===response.status){
+      const missing=Array.isArray(value.error.missing)?value.error.missing.filter(name=>['CATALOG_DB','HM_SERVER_ORIGIN'].includes(name)):[];
+      throw new AppHostError(code,`${label} was refused by the catalog provider.`,missing.length?{missing:[...new Set(missing)]}:{},response.status);
+    }
+    throw new AppHostError('CATALOG_HTTP_ERROR',`${label} returned HTTP ${response.status}.`,{status:response.status},502);
+  }
+  return value;
 }
 
 async function sameOriginFetch(start,fetchImpl,label){
@@ -89,6 +211,14 @@ async function sameOriginFetch(start,fetchImpl,label){
   }
 }
 
+function hanaQueryCategories(query,category,cursor){
+    const categories=Array.isArray(category)?category:category?[category]:[];
+    requireCondition(typeof query==='string'&&query.length<=200&&categories.length<=20&&categories.every(value=>typeof value==='string'&&/^[a-z0-9][a-z0-9._:-]{0,63}$/.test(value))&&
+      (cursor===undefined||(typeof cursor==='string'&&cursor.length>0)),
+      'INVALID_REQUEST','Catalog query does not match the HanaMesh view contract.');
+  return categories;
+}
+
 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.');
@@ -98,11 +228,25 @@ export async function loadCatalog({fixture,sources=[],fetchImpl=globalThis.fetch
   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);
+  // Validate caller input before any provider request, including discovery.
+  const queryCategories=manifestUrl.searchParams.get('view')==='hanamesh'?hanaQueryCategories(query,category,cursor):undefined;
   const manifestResponse=await sameOriginFetch(manifestUrl,fetchImpl,'Catalog manifest');
-  const manifest=validateCatalogManifest(await responseJson(manifestResponse.response,'Catalog manifest'));
+  const manifest=validateCatalogManifest(await responseJson(manifestResponse.response,'Catalog manifest',MAX_BYTES,manifestUrl.searchParams.get('view')==='hanamesh'));
   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');
+  requireCondition(endpoint.searchParams.get('view')===manifestUrl.searchParams.get('view'),'INVALID_CATALOG_MANIFEST','Catalog endpoint must retain the selected view.');
+  const hana=endpoint.searchParams.get('view')==='hanamesh';
+  if(hana){
+    const categories=queryCategories;
+    if(query)endpoint.searchParams.set('q',query);
+    for(const value of categories)endpoint.searchParams.append('category',value);
+    if(cursor!==undefined)endpoint.searchParams.set('cursor',cursor);
+    endpoint.searchParams.set('limit',String(manifest.query.defaultLimit));
+  }else{
+    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'))};
+  const page=await responseJson(pageResponse.response,'Catalog page',hana?manifest.limits.maxBodyBytes:MAX_BYTES,hana);
+  requireCondition(hana?page?.schemaVersion===HANAMESH_SCHEMA:catalogVersion(page?.schemaVersion),'INVALID_CATALOG_PAGE','Catalog page must match the selected view.');
+  return{source:{kind:'remote',manifestUrl:manifestUrl.href,manifest},...validateProviderPage(page,hana?{maxItems:manifest.query.maxLimit,maxSourceLinks:manifest.limits.maxSourceLinks}:{})};
 }

package/dist/library/client-identity.js

@@ -0,0 +1,31 @@
+/**
+ * Which client this host runs in, for the install-target probe: 'hanamesh' (the HanaMesh desktop client) or 'dsh'
+ * (plain DSH, desktop or CLI). The only fact used is the bundle identifier of the macOS application that contains the
+ * desktop runtime — C-DESKTOP-HOST fixes it to `com.hanamesh.desktop` (DSH_DESKTOP_APP_ID). `evidence` says what was
+ * seen, so a wrong answer can be traced instead of guessed at.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { join, sep } from 'node:path';
+
+export const HANAMESH_BUNDLE_ID = 'com.hanamesh.desktop';
+
+/** `<X>.app` directory that contains `path`, or undefined. */
+export function containingApp(path) {
+  if (typeof path !== 'string') return undefined;
+  const parts = path.split(sep), index = parts.findLastIndex(part => part.endsWith('.app'));
+  return index > 0 ? parts.slice(0, index + 1).join(sep) : undefined;
+}
+
+export async function detectClient({ desktop, platform = process.platform, readBundleId } = {}) {
+  if (!desktop) return { client: 'dsh', evidence: 'not-desktop' };
+  const app = containingApp(desktop.desktopCli?.runtimeDir ?? desktop.runtimeDir);
+  if (!app) return { client: 'dsh', evidence: 'desktop-without-app-bundle' };
+  if (platform !== 'darwin' && !readBundleId) return { client: 'dsh', evidence: `app-bundle-unreadable-on-${platform}` };
+  let id;
+  try {
+    id = readBundleId ? await readBundleId(app) : (await promisify(execFile)('/usr/bin/plutil',
+      ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', join(app, 'Contents', 'Info.plist')])).stdout.trim();
+  } catch (error) { return { client: 'dsh', evidence: `bundle-id-unreadable:${error.code ?? error.message}` }; }
+  return { client: id === HANAMESH_BUNDLE_ID ? 'hanamesh' : 'dsh', evidence: `bundle-id:${id}` };
+}

package/dist/library/desktop-cli.js

@@ -0,0 +1,7 @@
+/** Invoke the inspected upstream Desktop CLI export; the ordinary CLI refuses the reserved profile. */
+import {pathToFileURL} from 'node:url';
+const [entry,runtimeDir,supportDir,...args]=process.argv.slice(2);
+const {runDesktopCli}=await import(pathToFileURL(entry).href);
+if(typeof runDesktopCli!=='function')throw new Error('DSH_BINDING_REQUIRED: Desktop runDesktopCli export is unavailable.');
+process.argv=[process.execPath,entry,...args];
+await runDesktopCli(runtimeDir,supportDir);

package/dist/library/domain.js

@@ -3,6 +3,8 @@ 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)}),
+  schema:zod.object({schema:zod.literal(1),revision:zod.number().int().nonnegative(),sources:zod.array(source),suiteSource:zod.object({mode:zod.enum(['configured','core'])}).strict().optional(),
+    /** Website handoff settings saved from the library settings page; absent → plugin config / proposed defaults. */
+    handoff:zod.object({enabled:zod.boolean(),ports:zod.array(zod.number().int()),allowedOrigins:zod.array(zod.string()),ttlMs:zod.number().int(),pollMs:zod.number().int().min(1).max(2_147_483_647).optional()}).optional()}),
   initial:{schema:1,revision:0,sources:[]},
 }});

package/dist/library/handoff.js

@@ -0,0 +1,246 @@
+import { installationStatusCors, serveInstallationStatus } from './installation-status-http.js';
+/**
+ * Website → client install handoff (C-MARKET, 2026-10-15 E/F). Upstream Desktop listens on an OS-assigned port that
+ * nothing records, and a browser tab without the launch token gets 401, so a website can neither find nor enter the
+ * DSH web server. The library therefore opens its own loopback listener on the first free port of a named list and
+ * answers exactly three routes there:
+ *
+ *   GET  /hanamesh/library/install-target   probe (client, ready, need) for allowed website origins only
+ *   POST /hanamesh/library/handoff          queue a target from an allowed website origin; never installs
+ *   GET  /hanamesh/library/handoff?id=      that handoff's state for the same origin
+ *
+ * A queued handoff is shown by the library UI inside the client window with the normal confirmation; only the
+ * person's confirmation installs. States: pending → shown → confirmed → installed | cancelled | failed.
+ */
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { AppHostError, requireCondition } from '../errors.js';
+
+export const HANDOFF_STATES = Object.freeze(['pending', 'shown', 'confirmed', 'installed', 'cancelled', 'failed']);
+const FINAL = new Set(['installed', 'cancelled', 'failed']);
+/** Defaults (owner-approved 2026-10-15, plan §2); every one is visible and editable in the library settings. */
+export const HANDOFF_DEFAULTS = Object.freeze({
+  enabled: true,
+  ports: Object.freeze([39317, 39318, 39319]),
+  allowedOrigins: Object.freeze(['https://market.hanamesh.com']),
+  ttlMs: 600_000,
+  pollMs: 1_500,
+});
+/** Largest accepted handoff request body. A target is itemId (≤160) + packageName (≤214) + contractVersion. */
+export const HANDOFF_BODY_MAX_BYTES = 4096;
+const TIMER_MAX_MS = 2_147_483_647;
+/** Fixed rules (correctness, not policy): listed on the settings page with the reason they cannot be switched off. */
+export const HANDOFF_RULES = Object.freeze([
+  { rule: '只在本机 127.0.0.1 上监听，请求的 Host 必须是 127.0.0.1 或 localhost 加监听端口', why: '防止别的机器或 DNS 重绑定的网页冒充本机' },
+  { rule: '只有「允许交接的网站」里的网站能探测本客户端、交接安装、读交接状态；别的网站什么也读不到', why: '否则任何网页都能知道你装了什么客户端、缺什么，用来识别你' },
+  { rule: '网站交接只会在应用库里弹出确认；只有你点「确认安装」才会安装', why: '网站不能替你决定装什么' },
+  { rule: '交接状态只给发起它的那个网站看', why: '一个网站不能读另一个网站的交接' },
+  { rule: `交接请求体不超过 ${HANDOFF_BODY_MAX_BYTES} 字节`, why: '合法请求只有插件 id、包名、合约版本三项，最长不到 500 字节；更大的一定不是交接' },
+  { rule: '端口在 1024–65535 之间、互不重复，至少一个', why: '1024 以下要管理员权限；没有端口就没有地方让网站找到' },
+  { rule: '网站必须写成来源（协议 + 域名 [+ 端口]），http 只允许 127.0.0.1 / localhost', why: '浏览器按来源校验；明文 http 的公网网站可被中间人冒充' },
+  { rule: `轮询间隔是 1–${TIMER_MAX_MS} 毫秒的整数，作废时间必须大于轮询间隔`, why: '计时器超过上限会立即触发；作废早于第一次轮询，交接永远不会被看到' },
+]);
+export const HANDOFF_SETTING_NAMES = Object.freeze({ enabled: 'library.handoff.enabled', ports: 'library.handoff.ports',
+  allowedOrigins: 'library.handoff.allowedOrigins', ttlMs: 'library.handoff.ttlMs', pollMs: 'library.handoff.pollMs' });
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** Validate and normalise handoff settings; every field is required after merging with the defaults. */
+export function handoffSettings(input = {}) {
+  const value = { ...HANDOFF_DEFAULTS, ...Object.fromEntries(Object.entries(input ?? {}).filter(([, v]) => v !== undefined)) };
+  const invalid = message => new AppHostError('INVALID_HANDOFF_SETTINGS', message, {}, 400);
+  if (Object.keys(value).some(key => !(key in HANDOFF_DEFAULTS))) throw invalid('Unknown handoff setting.');
+  if (typeof value.enabled !== 'boolean') throw invalid('enabled must be true or false.');
+  if (!Array.isArray(value.ports) || value.ports.length < 1 ||
+    value.ports.some(port => !Number.isInteger(port) || port < 1024 || port > 65535) || new Set(value.ports).size !== value.ports.length)
+    throw invalid('ports must be at least one distinct port between 1024 and 65535.');
+  if (!Array.isArray(value.allowedOrigins)) throw invalid('allowedOrigins must be a list of origins.');
+  const origins = value.allowedOrigins.map(origin => {
+    let url; try { url = new URL(origin); } catch { throw invalid(`Not an origin: ${origin}`); }
+    if (!['https:', 'http:'].includes(url.protocol) || url.origin !== origin.replace(/\/$/, '')) throw invalid(`Not an origin: ${origin}`);
+    if (url.protocol === 'http:' && !['127.0.0.1', 'localhost'].includes(url.hostname)) throw invalid(`Plain http is only accepted for loopback: ${origin}`);
+    return url.origin;
+  });
+  if (!Number.isInteger(value.pollMs) || value.pollMs < 1 || value.pollMs > TIMER_MAX_MS) throw invalid(`pollMs must be an integer between 1 and ${TIMER_MAX_MS}.`);
+  if (!Number.isSafeInteger(value.ttlMs) || value.ttlMs <= value.pollMs) throw invalid('ttlMs must be an integer greater than pollMs.');
+  return { enabled: value.enabled, ports: [...value.ports], allowedOrigins: [...new Set(origins)], ttlMs: value.ttlMs, pollMs: value.pollMs };
+}
+
+/**
+ * In-memory handoffs. `observe` links library install events to the handoff shown for the same package. `clientPolled`
+ * records when the client window last fetched open handoffs, so an expiry can say whether the window ever saw it.
+ * A failing subscriber is reported through `onError` (default: console.warn) and does not stop the others.
+ */
+export function createHandoffQueue({ ttlMs = () => HANDOFF_DEFAULTS.ttlMs, now = Date.now, onError = (message, error) => console.warn(message, error) } = {}) {
+  const records = new Map(), listeners = new Set(); let lastPolledAt = null;
+  const publish = record => { for (const listener of listeners) { try { listener(view(record)); } catch (error) { onError('hanamesh-app-host handoff: subscriber failed', error); } } };
+  const view = record => ({ handoffId: record.handoffId, state: record.state, origin: record.origin,
+    ...(record.itemId ? { itemId: record.itemId } : {}), ...(record.packageName ? { packageName: record.packageName } : {}),
+    ...(record.displayName ? { displayName: record.displayName } : {}), ...(record.result ? { result: record.result } : {}),
+    ...(record.error ? { error: record.error } : {}), createdAt: record.createdAt, updatedAt: record.updatedAt });
+  const move = (record, state, extra = {}) => {
+    if (FINAL.has(record.state)) return false;
+    Object.assign(record, extra, { state, updatedAt: now() }); publish(record); return true;
+  };
+  const expire = () => {
+    for (const record of records.values()) {
+      if (!FINAL.has(record.state) && now() - record.createdAt > ttlMs())
+        move(record, 'failed', { error: record.state === 'pending'
+          ? { code: 'HANDOFF_NOT_PICKED_UP', message: lastPolledAt === null || lastPolledAt < record.createdAt
+            ? '交接已过期：客户端的应用库窗口一直没有来取（窗口没打开，或应用库读取交接失败，见应用库提示）。'
+            : '交接已过期：应用库取到了交接，但没能弹出确认，也没有报回原因。', lastPolledAt }
+          : { code: 'HANDOFF_EXPIRED', message: record.state === 'shown'
+            ? '交接已过期：确认框已经弹出，但到期前没有收到「确认」或「取消」（如果点了取消，说明取消没能报回，见应用库提示）。'
+            : '交接已过期：已确认安装，但到期前没有收到安装结果。' } });
+      if (FINAL.has(record.state) && now() - record.updatedAt > ttlMs()) records.delete(record.handoffId);
+    }
+  };
+  return Object.freeze({
+    create({ origin, target, item, alreadyInstalled }) {
+      expire();
+      const at = now(), record = { handoffId: randomUUID(), state: 'pending', origin, target,
+        itemId: item.id, packageName: item.package?.name, displayName: item.displayName, createdAt: at, updatedAt: at };
+      records.set(record.handoffId, record);
+      if (alreadyInstalled) move(record, 'installed', { result: { status: 'already-installed' } }); else publish(record);
+      return view(record);
+    },
+    get(handoffId) {
+      expire();
+      requireCondition(typeof handoffId === 'string' && ID.test(handoffId) && records.has(handoffId), 'HANDOFF_UNKNOWN', 'Unknown handoff.', {}, 404);
+      return view(records.get(handoffId));
+    },
+    /** Handoffs the client window still has to show or is showing. */
+    open() { expire(); return [...records.values()].filter(record => ['pending', 'shown', 'confirmed'].includes(record.state)).map(view); },
+    clientPolled() { lastPolledAt = now(); },
+    lastPolledAt: () => lastPolledAt,
+    /**
+     * Client window reports: shown | cancelled | failed (the confirmation could not be opened; `error.code` says why).
+     * Installs are linked from library events, never from a client claim.
+     */
+    report(input) {
+      requireCondition(input && typeof input === 'object' && Object.keys(input).every(key => ['handoffId', 'state', 'error'].includes(key)) &&
+        ['shown', 'cancelled', 'failed'].includes(input.state) && (input.state === 'failed'
+          ? input.error && typeof input.error === 'object' && Object.keys(input.error).every(key => key === 'code') && typeof input.error.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(input.error.code)
+          : input.error === undefined),
+      'INVALID_INPUT', 'Only handoffId and state shown|cancelled, or failed with error.code, are accepted.');
+      const record = records.get(this.get(input.handoffId).handoffId);
+      if (input.state === 'shown' && record.state !== 'pending') return view(record);
+      move(record, input.state, input.state === 'failed'
+        ? { error: { code: 'HANDOFF_OPEN_FAILED', message: `应用库没能弹出这个安装确认：${input.error.code}`, cause: input.error.code } } : {});
+      return view(record);
+    },
+    observe(event) {
+      const name = event?.packageName ?? event?.result?.packageName; if (!name) return;
+      for (const record of records.values()) {
+        if (record.packageName !== name || !['shown', 'confirmed'].includes(record.state)) continue;
+        if (event.type === 'library.install-started') move(record, 'confirmed');
+        else if (event.type === 'library.install-done') move(record, 'installed', { result: { status: event.status ?? event.result?.status } });
+        else if (event.type === 'library.install-failed') move(record, 'failed', { error: { code: event.code ?? 'INSTALL_FAILED', message: '安装失败' } });
+      }
+    },
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+  });
+}
+
+function send(res, status, value, headers = {}) {
+  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'", ...headers });
+  res.end(value === undefined ? '' : JSON.stringify(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 <= HANDOFF_BODY_MAX_BYTES, 'BODY_TOO_LARGE', `Request body is larger than ${HANDOFF_BODY_MAX_BYTES} bytes.`, { maxBytes: HANDOFF_BODY_MAX_BYTES }, 413); chunks.push(chunk); }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw new AppHostError('INVALID_JSON', 'Malformed JSON.', {}, 400); }
+}
+
+/**
+ * HTTP handler of the handoff listener. `library`: installTarget() and resolveTarget(); `settings()`: current settings;
+ * `port()`: the bound port (Host must be exactly 127.0.0.1:<port> or localhost:<port>).
+ */
+export function createHandoffHandler({ library, queue, settings, port }) {
+  return async (req, res) => {
+    const traceId = randomUUID(); let cors = {};
+    try {
+      const bound = port();
+      requireCondition([`127.0.0.1:${bound}`, `localhost:${bound}`].includes(req.headers.host), 'HOST_DENIED', 'Unrecognized request host.', {}, 403);
+      const url = new URL(req.url ?? '/', `http://${req.headers.host}`), path = url.pathname, origin = req.headers.origin;
+      if (path === '/hanamesh/library/install-target') {
+        // A website not in allowedOrigins gets no CORS grant and no body: it cannot tell which client runs or what it lacks.
+        // Requests without an Origin are not from a website (a person's address bar, a local tool) and are answered.
+        if (origin !== undefined) {
+          requireCondition(settings().allowedOrigins.includes(origin), 'ORIGIN_DENIED', 'Not available.', undefined, 403);
+          cors = { 'access-control-allow-origin': origin, vary: 'Origin', 'access-control-allow-private-network': 'true' };
+        }
+        if (req.method === 'OPTIONS') { send(res, 204, undefined, { ...cors, 'access-control-allow-methods': 'GET' }); return; }
+        requireCondition(req.method === 'GET', 'METHOD_NOT_ALLOWED', 'Discovery requires GET.', {}, 405);
+        requireCondition(!url.search, 'UNKNOWN_FIELDS', 'Discovery takes no parameters.');
+        send(res, 200, { ...library.installTarget(), traceId }, cors); return;
+      }
+      if(path === '/hanamesh/library/installation-status'){
+        cors=installationStatusCors(req,settings().allowedOrigins);
+        await serveInstallationStatus(req,res,{read:library.installationStatus,maxBodyBytes:HANDOFF_BODY_MAX_BYTES,traceId,cors,send});return;
+      }
+      requireCondition(path === '/hanamesh/library/handoff', 'NOT_FOUND', 'Unknown handoff route.', {}, 404);
+      requireCondition(typeof origin === 'string' && settings().allowedOrigins.includes(origin), 'ORIGIN_DENIED',
+        'This website is not allowed to hand installs to this client. Add it in the HanaMesh library settings.', { origin: origin ?? null }, 403);
+      cors = { 'access-control-allow-origin': origin, vary: 'Origin', 'access-control-allow-private-network': 'true' };
+      if (req.method === 'OPTIONS') {
+        send(res, 204, undefined, { ...cors, 'access-control-allow-methods': 'GET, POST', 'access-control-allow-headers': 'content-type' });
+        return;
+      }
+      if (req.method === 'GET') {
+        requireCondition([...url.searchParams.keys()].length === 1 && url.searchParams.has('id'), 'UNKNOWN_FIELDS', 'Only id is accepted.');
+        const record = queue.get(url.searchParams.get('id'));
+        requireCondition(record.origin === origin, 'HANDOFF_UNKNOWN', 'Unknown handoff.', {}, 404);
+        const { origin: _o, createdAt: _c, updatedAt: _u, ...visible } = record;
+        send(res, 200, { ...visible, traceId }, cors); return;
+      }
+      requireCondition(req.method === 'POST', 'METHOD_NOT_ALLOWED', 'Unsupported handoff method.', {}, 405);
+      requireCondition(!url.search, 'UNKNOWN_FIELDS', 'Handoff takes no query.');
+      const target = await jsonBody(req);
+      const probe = library.installTarget();
+      requireCondition(probe.ready, 'INSTALL_TARGET_UNAVAILABLE', probe.error?.message ?? 'Controlled installer is unavailable.', { need: probe.error?.need ?? [] }, 503);
+      const { item } = await library.resolveTarget(target);
+      requireCondition(item.kind !== 'listing', 'NOT_INSTALLABLE', 'Catalog item has no npm package to install.');
+      const installed = item.installed && ['registered', 'installed', 'installed-not-loaded'].includes(item.installed.state) && !item.upgradeAvailable;
+      const record = queue.create({ origin, target, item, alreadyInstalled: installed });
+      send(res, 202, { handoffId: record.handoffId, state: record.state, ...(record.result ? { result: record.result } : {}), traceId }, cors);
+    } 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 && error.details ? { details: error.details } : {}) }, traceId }, cors);
+    }
+  };
+}
+
+/**
+ * The listener itself. `start()` binds 127.0.0.1 on the first free port of settings().ports and reports which one, or
+ * why none could be used (`need`), so the library settings and probes can say it.
+ */
+export function createHandoffListener({ handlerFor, settings, logger, listen = (server, port) => new Promise((resolve, reject) => {
+  const fail = error => { server.off('listening', ok); reject(error); }, ok = () => { server.off('error', fail); resolve(); };
+  server.once('error', fail); server.once('listening', ok); server.listen(port, '127.0.0.1');
+}) }) {
+  let server, state = { status: 'stopped' };
+  async function stop() {
+    const current = server; server = undefined;
+    if (current) await new Promise(resolve => { current.close(() => resolve()); current.closeAllConnections?.(); });
+    state = { status: 'stopped' };
+  }
+  async function start() {
+    await stop();
+    const { enabled, ports } = settings();
+    if (!enabled) { state = { status: 'disabled' }; return state; }
+    const tried = [];
+    for (const port of ports) {
+      const candidate = createServer();
+      candidate.on('request', handlerFor(() => port));
+      try { await listen(candidate, port); server = candidate; state = { status: 'listening', port, origin: `http://127.0.0.1:${port}` }; logger?.info?.('hanamesh-app-host handoff: listening on 127.0.0.1:%d', port); return state; }
+      catch (error) { tried.push({ port, code: error.code ?? 'LISTEN_FAILED' }); candidate.close(); }
+    }
+    state = { status: 'unavailable', tried, need: `网站交接端口 ${ports.join('、')} 都被占用：在应用库设置里换一个空闲端口，并告诉网站同一端口` };
+    logger?.warn?.('hanamesh-app-host handoff: no free port %s', JSON.stringify(tried));
+    return state;
+  }
+  return Object.freeze({ start, stop, state: () => state });
+}