device-center 0.1.0-beta.1 → 0.2.0-beta.2

package/server/drivers/remote.mjs

@@ -0,0 +1,111 @@
+import { Duplex } from 'node:stream';
+import { Server, connect } from 'node:tls';
+import { createServer as createNetServer } from 'node:net';
+import { signedRequest, object } from './driverProtocol.mjs';
+import { cloudPost, readLink } from './cloudLink.mjs';
+import { certificateName } from './certificates.mjs';
+import { accessFile, readAccess, peerFingerprint, readGrantedLog, lanEndpoint, audit } from './access.mjs';
+import { dirname, join } from 'node:path';
+
+export const machinePost = (state, action, payload = {}, fetchImpl) => cloudPost(state.origin, `/api/driver/${action}`, signedRequest(state.privateKey,state.origin,`/api/driver/${action}`,state.driverId,payload),fetchImpl);
+export async function remotePeers(state, fetchImpl) { return (await machinePost(state,'peers',{},fetchImpl)).peers; }
+class RelayStream extends Duplex {
+  constructor(state, channelId, fetchImpl) {
+    super({ autoDestroy: false }); this.state=state;this.channelId=channelId;this.fetchImpl=fetchImpl;this.pending=[];this.deadline=Date.now()+60000;this.on('error',()=>{});this.timer=setTimeout(()=>void this.tick(),0);
+  }
+  _read() {}
+  _write(chunk, encoding, callback) {
+    if (this.pending.length + Math.ceil(chunk.length/4096) > 32) return callback(new Error('relay_backpressure'));
+    for (let at=0;at<chunk.length;at+=4096) this.pending.push(chunk.subarray(at,at+4096).toString('base64'));
+    callback();
+  }
+  _final(callback) { callback(); }
+  _destroy(error, callback) { clearTimeout(this.timer);void machinePost(this.state,'relay/close',{channelId:this.channelId},this.fetchImpl).catch(()=>{});callback(error); }
+  async tick() {
+    if(this.destroyed)return;
+    try {
+      if(Date.now()>this.deadline)throw new Error('relay_session_expired');
+      const answer=await machinePost(this.state,'relay/exchange',{channelId:this.channelId,frames:this.pending.splice(0,2)},this.fetchImpl);
+      for(const frame of answer.frames) { if(!this.push(Buffer.from(frame,'base64'))) { /* bounded total TLS response, max 96 KiB */ } }
+      if(this.readableLength>131072)throw new Error('relay_backpressure');
+      if(!this.destroyed)this.timer=setTimeout(()=>void this.tick(),500);
+    }catch(error){this.destroy(error);}
+  }
+}
+export function createTargetTls(state, file, route, fetchImpl) {
+  const grants=readAccess(file).grants.filter(g=>g.expiresAt>Date.now());
+  const server=new Server({key:state.privateKey,cert:state.certificate,ca:grants.map(g=>g.certificate),minVersion:'TLSv1.3',handshakeTimeout:3000,requestCert:true,rejectUnauthorized:true});
+  server.on('tlsClientError',()=>{});
+  server.on('secureConnection', socket=>{
+    let buffer='', done=false;
+    socket.setTimeout(20000,()=>socket.destroy());socket.on('error',()=>{});
+    socket.on('data',async chunk=>{
+      if(done)return;
+      buffer+=chunk.toString('utf8');if(Buffer.byteLength(buffer)>2048){done=true;socket.destroy();return;}
+      if(!buffer.includes('\n'))return;
+      done=true;
+      try {
+        if(buffer.indexOf('\n')!==buffer.length-1)throw new Error('access_invalid_operation');
+        const fingerprint=peerFingerprint(socket);
+        if (!(await remotePeers(state,fetchImpl)).some(p=>p.fingerprint===fingerprint)) throw new Error('access_peer_revoked');
+        const result=readGrantedLog({file,fingerprint,request:JSON.parse(buffer),route});socket.end(JSON.stringify({ok:true,result})+'\n');
+      }catch(error){socket.end(JSON.stringify({ok:false,error:/^access_[a-z_]+$/.test(error.message)?error.message:'access_read_failed'})+'\n');}
+    });
+  });
+  return server;
+}
+export async function requestTls(state, peer, request, options, route) {
+  return new Promise((resolve,reject)=>{
+    const socket=connect({ ...options,key:state.privateKey,cert:state.certificate,ca:[peer.certificate],servername:certificateName(peer.fingerprint),minVersion:'TLSv1.3',rejectUnauthorized:true });
+    let timeout=setTimeout(()=>socket.destroy(new Error('access_request_timeout')), options.socket?30000:3000);
+    let buffer='', settled=false;
+    function finish(error,value){if(settled)return;settled=true;clearTimeout(timeout);socket.destroy();options.socket?.destroy();error?reject(error):resolve(value);}
+    socket.once('secureConnect',()=>{
+      try{clearTimeout(timeout);timeout=setTimeout(()=>socket.destroy(new Error('access_response_timeout')),30000);if(peerFingerprint(socket)!==peer.fingerprint)throw new Error('access_peer_mismatch');socket.write(JSON.stringify(request)+'\n');}catch(e){finish(e);}
+    });
+    socket.on('data',chunk=>{buffer+=chunk.toString('utf8');if(Buffer.byteLength(buffer)>100000)return finish(new Error('access_response_too_large'));if(buffer.includes('\n')){try{const reply=JSON.parse(buffer);if(!reply.ok)throw new Error(reply.error);finish(null,{...reply.result,route});}catch(e){finish(e);}}});
+    socket.once('error',e=>finish(e));socket.once('end',()=>{if(!settled)finish(new Error('access_response_incomplete'));});
+  });
+}
+export function createRemoteClient({ linkFile, fetchImpl, dial = requestTls }) {
+  return {
+    async peers(){const state=readLink(linkFile);if(!state?.driverId||state.disabled)throw new Error('driver_not_bound');return {peers:(await remotePeers(state,fetchImpl)).map(({certificate,...p})=>p)};},
+    async read(input){
+      object(input,['fingerprint','label','bytes']);
+      const state=readLink(linkFile);if(!state?.driverId||state.disabled||!state.certificate)throw new Error('driver_secure_identity_required');
+      const file=accessFile(linkFile),peer=readAccess(file).trusts.find(p=>p.fingerprint===input.fingerprint);
+      if(!peer)throw new Error('access_peer_not_trusted');
+      const request={operation:'read-log',label:input.label,bytes:input.bytes??16384};
+      if(typeof request.label!=='string'||!/^[a-zA-Z0-9_-]{1,40}$/.test(request.label)||!Number.isInteger(request.bytes)||request.bytes<1||request.bytes>65536)throw new Error('access_invalid_operation');
+      // Directory lookup proves current account membership and revocation before either route.
+      const current=(await remotePeers(state,fetchImpl)).find(p=>p.id===peer.id&&p.fingerprint===peer.fingerprint);
+      if(!current)throw new Error('relay_peer_unavailable');
+      let fallbackReason=null,result;
+      if(peer.lan){try{const endpoint=lanEndpoint(peer.lan);result=await dial(state,peer,request,endpoint,'lan-direct');}catch(e){if(!['ECONNREFUSED','ETIMEDOUT','EHOSTUNREACH','ENETUNREACH','access_request_timeout'].includes(e.code??e.message))throw e;fallbackReason='approved_lan_unreachable';}}
+      if(!result){const {channelId}=await machinePost(state,'relay/open',{targetId:peer.id},fetchImpl);const stream=new RelayStream(state,channelId,fetchImpl);result=await dial(state,peer,request,{socket:stream},'cloud-relay');}
+      audit(join(dirname(file),'access-audit.jsonl'),{fingerprint:peer.fingerprint,label:request.label,route:result.route,bytes:result.bytes,outcome:'received'});
+      return {...result,fallbackReason};
+    },
+  };
+}
+export function createRemoteAgent({ linkFile, fetchImpl }) {
+  let stopped=true,timer,listener,listenerConfig='',polling=false;const streams=new Set(),status={state:'disabled',error:null,lan:null};
+  async function tick(){
+    if(stopped||polling)return;polling=true;
+    try{
+      const state=readLink(linkFile),file=accessFile(linkFile),access=readAccess(file);
+      if(!state?.driverId||state.disabled||!state.certificate){listener?.close();listener=null;listenerConfig='';status.lan=null;for(const stream of streams)stream.destroy();status.state='disabled';return;}
+      const grants=access.grants.filter(g=>g.expiresAt>Date.now());
+      const wanted=grants.length&&access.listen?JSON.stringify(access.listen):'';
+      if(wanted!==listenerConfig){listener?.close();listener=null;listenerConfig=wanted;status.lan=null;
+        if(wanted){const endpoint=lanEndpoint(access.listen);listener=createNetServer(socket=>{const tls=createTargetTls(state,file,'lan-direct',fetchImpl);tls.emit('connection',socket);socket.once('close',()=>tls.close());});listener.maxConnections=4;listener.on('error',()=>{status.error='access_lan_listen_failed';listenerConfig='';});listener.listen(endpoint.port,endpoint.host,()=>{status.lan=endpoint;});}}
+      if(!grants.length){status.state='no-active-grants';return;}
+      const {incoming}=await machinePost(state,'relay/accept',{},fetchImpl);
+      status.state='waiting';status.error=null;
+      if(incoming){const allowed=grants.some(g=>g.fingerprint===incoming.fingerprint&&g.certificate===incoming.certificate);if(!allowed){await machinePost(state,'relay/close',{channelId:incoming.channelId},fetchImpl);return;}
+        const stream=new RelayStream(state,incoming.channelId,fetchImpl),tls=createTargetTls(state,file,'cloud-relay',fetchImpl);streams.add(stream);stream.once('close',()=>{streams.delete(stream);tls.close();});tls.emit('connection',stream);}
+    }catch(e){status.error=/^(driver_|access_|relay_)[a-z_]+$/.test(e.message)?e.message:'driver_cloud_unavailable';status.state='retrying';}
+    finally{polling=false;if(!stopped)timer=setTimeout(()=>void tick(),3000);}
+  }
+  return {status:()=>({...status}),start(){if(stopped){stopped=false;void tick();}},stop(){stopped=true;clearTimeout(timer);listener?.close();for(const stream of streams)stream.destroy();}};
+}

package/server/index.mjs

@@ -9,9 +9,11 @@ import { createConnector, PROTOCOL_VERSIONS, TOOLS } from './connector.mjs';
 import { createCloudAccess } from './cloudAccess.mjs';
 import { createCloudRegistry } from './drivers/cloudRegistry.mjs';
 import { createPublisher, defaultLinkFile, linkSummary, readLink } from './drivers/cloudLink.mjs';
+import { createRemoteAgent, createRemoteClient } from './drivers/remote.mjs';
 
 const PROJECT_ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)));
 const MIME_TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.png': 'image/png' };
+const PUBLIC_GUIDES = Object.freeze({ '/install/agent.md': 'docs/agent-install.md', '/install/trial.md': 'docs/friend-trial.md', '/install/remote-access.md': 'docs/remote-access.md', '/install/device-profiles.md': 'docs/device-profiles.md', '/install/troubleshooting.md': 'docs/troubleshooting.md' });
 function sendJson(response, status, payload, headers = {}) {
   response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', ...headers });
   response.end(JSON.stringify(payload));
@@ -41,6 +43,7 @@ async function serveStatic(pathname, response) {
   let filePath;
   if (pathname === '/' || pathname === '/index.html') filePath = resolve(PROJECT_ROOT, 'index.html');
   else if (pathname === '/login') filePath = resolve(PROJECT_ROOT, 'login.html');
+  else if (pathname === '/start' || pathname === '/start.html') filePath = resolve(PROJECT_ROOT, 'start.html');
   else if (pathname.startsWith('/src/')) {
     filePath = resolve(PROJECT_ROOT, `.${pathname}`);
     if (!filePath.startsWith(resolve(PROJECT_ROOT, 'src') + '/')) return sendJson(response, 404, { error: 'not_found' });
@@ -62,21 +65,34 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
   const cloud = Boolean(cloudAccess);
   const absoluteDbPath = resolve(dbPath);
   const db = openDatabase(absoluteDbPath);
-  const principal = cloud ? { tenantId: 'cloud-owner', subject: 'owner' } : currentPrincipal();
   const startedAt = Date.now();
   let lastInitializeAt = null;
-  const inventory = createInventory({ db, tenantId: principal.tenantId, runtime: cloud ? 'container' : runtime, sshHome, sshProbe });
-  const registry = cloud ? createCloudRegistry({ db, origin: publicOrigin }) : null;
+  let inventory, registry;
+  try {
+    inventory = cloud ? null : createInventory({ db, tenantId: currentPrincipal().tenantId, runtime, sshHome, sshProbe });
+    registry = cloud ? createCloudRegistry({ db, origin: publicOrigin, multiUser: cloudAccess.accountMode === 'multi-user', legacyOwnerMapped: cloudAccess.legacyOwnerMapped }) : null;
+  } catch (cause) { db.close(); throw cause; }
   const publisher = !cloud && runtime === 'native' && cloudLinkFile ? createPublisher({ file: cloudLinkFile, inventory, fetchImpl: driverFetch }) : null;
-  const connector = createConnector({ inventory, transport: 'Streamable HTTP', onInitialize: () => { lastInitializeAt = Date.now(); } });
+  const remoteAgent = !cloud && runtime === 'native' && cloudLinkFile ? createRemoteAgent({ linkFile: cloudLinkFile, fetchImpl: driverFetch }) : null;
+  const remoteClient = remoteAgent ? createRemoteClient({ linkFile: cloudLinkFile, fetchImpl: driverFetch }) : null;
+  const connector = cloud ? null : createConnector({ inventory, remoteClient, transport: 'Streamable HTTP', onInitialize: () => { lastInitializeAt = Date.now(); } });
   const server = createHttpServer(async (request, response) => {
     try {
       const origin = cloudAccess ? cloudAccess.validate(request) : validateLocalRequest(request);
       const url = new URL(request.url ?? '/', origin);
       const path = url.pathname;
+      // Public static installation reference only. No identity, configuration or owner API.
+      if (['/start', '/start.html', '/src/start.js', '/src/start.css', '/src/onboarding.js'].includes(path) && request.method === 'GET') return await serveStatic(path, response);
+      if (Object.hasOwn(PUBLIC_GUIDES, path) && request.method === 'GET') {
+        const body = await readFile(resolve(PROJECT_ROOT, PUBLIC_GUIDES[path]));
+        response.writeHead(200, { 'content-type': 'text/markdown; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', 'content-security-policy': "default-src 'none'; frame-ancestors 'none'", 'referrer-policy': 'no-referrer' });
+        return response.end(body);
+      }
+      let accountRegistry;
       if (cloud) {
         const machineActions = { '/api/driver/pair/start': 'start', '/api/driver/pair/poll': 'poll', '/api/driver/report': 'report', '/api/driver/disconnect': 'disconnect' };
         if (Object.hasOwn(machineActions, path) && request.method === 'POST') return sendJson(response, 200, registry[machineActions[path]](await readJson(request)));
+        if (['control','certificate','peers','relay/open','relay/accept','relay/exchange','relay/close'].some(action => path === `/api/driver/${action}`) && request.method === 'POST') return sendJson(response, 200, registry.machine(path.slice('/api/driver/'.length), await readJson(request)));
         if (['/login', '/src/login.js', '/src/login.css'].includes(path) && request.method === 'GET') return await serveStatic(path, response);
         if (path === '/api/auth/options' && request.method === 'GET') return sendJson(response, 200, cloudAccess.options(request));
         if (path === '/api/auth/continue' && request.method === 'POST') {
@@ -97,15 +113,17 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
           if (request.headers.origin !== origin) return sendJson(response, 403, { error: 'same_origin_required' });
           return sendJson(response, 200, { ok: true }, { 'set-cookie': cloudAccess.logout(request) });
         }
-        if (!await cloudAccess.authenticated(request)) {
+        const principal = await cloudAccess.resolvePrincipal(request);
+        if (!principal) {
           if (path === '/' && request.method === 'GET') { response.writeHead(303, { location: '/login', 'cache-control': 'no-store' }); return response.end(); }
           return sendJson(response, 401, { error: 'authentication_required' });
         }
-        if (path === '/api/drivers' && request.method === 'GET') return sendJson(response, 200, { drivers: registry.bindings() });
-        const ownerActions = { '/api/drivers/pairing/lookup': 'lookup', '/api/drivers/pairing/approve': 'approve', '/api/drivers/revoke': 'revoke' };
+        accountRegistry = registry.forTenant(principal.tenantId);
+        if (path === '/api/drivers' && request.method === 'GET') return sendJson(response, 200, { drivers: accountRegistry.bindings() });
+        const ownerActions = { '/api/devices/profile': 'saveProfile', '/api/devices/collect': 'collect', '/api/drivers/pairing/lookup': 'lookup', '/api/drivers/pairing/approve': 'approve', '/api/drivers/revoke': 'revoke' };
         if (Object.hasOwn(ownerActions, path) && request.method === 'POST') {
           if (request.headers.origin !== origin) return sendJson(response, 403, { error: 'same_origin_required' });
-          return sendJson(response, 200, registry[ownerActions[path]](await readJson(request)));
+          return sendJson(response, 200, accountRegistry[ownerActions[path]](await readJson(request)));
         }
         if (path === '/api/driver/download' && request.method === 'GET') {
           let bundle; try { bundle = await readFile(driverBundlePath); } catch { return sendJson(response, 404, { error: 'driver_bundle_unavailable' }); }
@@ -127,7 +145,7 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
           if (cause.message === 'invalid_json') return sendJson(response, 400, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
           throw cause;
         }
-        const answer = connector(message);
+        const answer = await connector(message);
         if (answer === undefined) { response.writeHead(202, { 'cache-control': 'no-store' }); return response.end(); }
         return sendJson(response, answer.error?.code === -32600 ? 400 : 200, answer);
       }
@@ -135,6 +153,14 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
         if (request.method !== 'GET' || !web) return sendJson(response, 404, { error: 'not_found' });
         return await serveStatic(path, response);
       }
+      if (!cloud && ['/api/devices/profile', '/api/devices/collect'].includes(path) && request.method === 'POST') {
+        if (request.headers.origin !== origin) return sendJson(response, 403, { error: 'same_origin_required' });
+        const input = await readJson(request);
+        if (path === '/api/devices/profile') return sendJson(response, 200, inventory.saveProfile(input));
+        const result = await inventory.collect(input);
+        if (result.device.source === 'local-runtime') publisher?.requestCollection();
+        return sendJson(response, 200, result);
+      }
       if (path === '/api/devices/ssh' && request.method === 'POST') {
         if (request.headers.origin !== origin) return sendJson(response, 403, { error: 'same_origin_required' });
         return sendJson(response, 200, inventory.associate(await readJson(request)));
@@ -157,7 +183,11 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
         return sendJson(response, 200, inventory.initialize(await readJson(request)));
       }
       if (request.method !== 'GET') return sendJson(response, 404, { error: 'not_found' });
-      if (!cloud && path === '/api/driver/link') return sendJson(response, 200, { ...linkSummary(cloudLinkFile ? readLink(cloudLinkFile) : null), publisher: publisher?.status() ?? null });
+      if (!cloud && path === '/api/driver/link') return sendJson(response, 200, { ...linkSummary(cloudLinkFile ? readLink(cloudLinkFile) : null), publisher: publisher?.status() ?? null, remoteAgent: remoteAgent?.status() ?? null });
+      if (!cloud && path === '/api/remote/peers') {
+        const summary = linkSummary(cloudLinkFile ? readLink(cloudLinkFile) : null);
+        return sendJson(response, 200, { ...summary, peers: summary.configured && remoteClient ? (await remoteClient.peers()).peers : [] });
+      }
       if (path === '/api/ssh/candidates') return sendJson(response, 200, inventory.discovery());
       if (path === '/api/ssh/initialization') return sendJson(response, 200, inventory.initialization());
       if (path === '/api/health') return sendJson(response, 200, { ok: true, mode: cloud ? 'cloud' : 'local', runtime: cloud ? 'cloud' : runtime });
@@ -171,13 +201,13 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
       if (path === '/api/connector/status') return sendJson(response, 200, {
         service: { state: 'running', runtime: cloud ? 'cloud' : runtime, startedAt, persistence: process.env.DEVICE_CENTER_SERVICE_MANAGER ?? 'foreground' },
         client: { state: lastInitializeAt === null ? 'waiting' : Date.now() - lastInitializeAt > 300_000 ? 'stale' : 'observed', lastInitializeAt, evidence: 'MCP initialize request; not authenticated identity or continuous liveness' },
-        targetAgentImplemented: false,
+        targetAgentImplemented: Boolean(remoteAgent),
       });
       if (path === '/api/overview') {
         if (url.searchParams.has('environment') && url.searchParams.get('environment') !== 'local') return sendJson(response, 400, { error: 'cloud_not_configured' });
-        const devices = cloud ? registry.devices() : inventory.list();
+        const devices = cloud ? accountRegistry.devices() : inventory.list();
         const stats = devices.reduce((totals, device) => { totals.total++; totals[device.state]++; return totals; }, { total: 0, online: 0, unknown: 0, expired: 0 });
-        return sendJson(response, 200, { devices, stats, projects: [], mode: cloud ? 'cloud' : 'local-inventory', enrollmentAvailable: cloud, ...(cloud ? { drivers: registry.bindings(), controlOrigin: publicOrigin } : {}) });
+        return sendJson(response, 200, { devices, stats, projects: [], mode: cloud ? 'cloud' : 'local-inventory', enrollmentAvailable: cloud, ...(cloud ? { drivers: accountRegistry.bindings(), controlOrigin: publicOrigin, accountMode: cloudAccess.accountMode, relayUsage: accountRegistry.relayUsage(), capabilities: { telemetry: true, relay: true, authorizedLogRead: true, remoteExecution: false, cloudMcp: false } } : {}) });
       }
       return sendJson(response, 404, { error: 'not_found' });
     } catch (cause) {
@@ -187,6 +217,7 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
   });
   server.requestTimeout = 10_000;
   if (publisher) { server.once('listening', () => publisher.start()); server.once('close', () => publisher.stop()); }
+  if (remoteAgent) { server.once('listening', () => remoteAgent.start()); server.once('close', () => remoteAgent.stop()); }
   return { server, db, dbPath: absoluteDbPath };
 }
 

package/server/mcp.mjs

@@ -7,13 +7,15 @@ import { fileURLToPath } from 'node:url';
 import { currentPrincipal } from './adapters/identity/localDemo.mjs';
 import { createConnector } from './connector.mjs';
 import { createInventory } from './drivers/inventory.mjs';
+import { createRemoteClient } from './drivers/remote.mjs';
+import { defaultLinkFile } from './drivers/cloudLink.mjs';
 const root = resolve(fileURLToPath(new URL('..', import.meta.url)));
 const db = new DatabaseSync(resolve(process.env.DEVICE_CENTER_DB_PATH ?? resolve(root, 'data/device-center.sqlite')), { readOnly: true });
 const inventory = createInventory({ db, tenantId: currentPrincipal().tenantId, runtime: process.env.DEVICE_CENTER_RUNTIME === 'container' ? 'container' : 'native' });
-const handle = createConnector({ inventory, transport: 'MCP stdio' });
+const handle = createConnector({ inventory, remoteClient: process.env.DEVICE_CENTER_RUNTIME === 'container' ? null : createRemoteClient({linkFile:defaultLinkFile()}), transport: 'MCP stdio' });
 let initialized = false;
 const input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity, terminal: false });
-input.on('line', (line) => {
+input.on('line', async (line) => {
   let answer;
   try {
     if (line.length > 16_384) throw new Error('too_large');
@@ -21,7 +23,7 @@ input.on('line', (line) => {
     if (message.method === 'notifications/initialized') initialized = true;
     if (Object.hasOwn(message, 'id') && !['initialize', 'ping'].includes(message.method) && !initialized) {
       answer = { jsonrpc: '2.0', id: message.id, error: { code: -32002, message: 'Initialize handshake required' } };
-    } else answer = handle(message);
+    } else answer = await handle(message);
   } catch { answer = { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }; }
   if (answer) process.stdout.write(JSON.stringify(answer) + '\n');
 });

package/server/unifiedAccess.mjs

@@ -23,8 +23,12 @@ export function createUnifiedAccess({ config, publicOrigin, now = Date.now, fetc
   const account = httpsOrigin(config.accountOrigin);
   const publicUrl = new URL(publicOrigin);
   if (publicUrl.hostname === account.hostname || !publicUrl.hostname.endsWith(`.${account.hostname}`) || !backend.hostname.endsWith(`.${account.hostname}`)) throw new Error('unified_shared_cookie_domain_required');
-  if (typeof config.ownerEmail !== 'string' || !/^[^\s@]+@[^\s@]+$/.test(config.ownerEmail)) throw new Error('unified_owner_required');
-  const ownerEmail = config.ownerEmail.toLowerCase();
+  const accountMode = config.accountMode ?? 'personal';
+  if (!['personal', 'multi-user'].includes(accountMode)) throw new Error('unified_account_mode_invalid');
+  if (accountMode === 'personal' && (typeof config.ownerEmail !== 'string' || !/^[^\s@]+@[^\s@]+$/.test(config.ownerEmail))) throw new Error('unified_owner_required');
+  const ownerEmail = typeof config.ownerEmail === 'string' ? config.ownerEmail.toLowerCase() : undefined;
+  const validId = id => typeof id === 'string' && id.length > 0 && id.length <= 256 && !/[\x00-\x1f\x7f]/.test(id);
+  if (config.legacyOwnerId !== undefined && (accountMode !== 'multi-user' || !validId(config.legacyOwnerId))) throw new Error('unified_legacy_owner_invalid');
   const sessions = new Map(), profiles = new Map(), attempts = new Map();
   let active = 0;
   const tokenFrom = (request) => {
@@ -59,9 +63,12 @@ export function createUnifiedAccess({ config, publicOrigin, now = Date.now, fetc
       let data;
       try { data = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw failure('unified_service_unavailable', 503); }
       phase = 'identity';
-      if (!['email', 'google', 'apple'].includes(data.auth?.token_kind) || data.profile?.is_anonymous !== false || typeof data.profile.id !== 'string' || !data.profile.id || data.profile.deleted_at) throw failure('unified_sign_in_required', 401);
-      if (data.profile.email?.toLowerCase() !== ownerEmail) throw failure('unified_owner_only', 403);
-      const profile = { id: data.profile.id };
+      if (!['email', 'google', 'apple'].includes(data?.auth?.token_kind) || data?.profile?.is_anonymous !== false || !validId(data.profile.id) || data.profile.deleted_at) throw failure('unified_sign_in_required', 401);
+      if (accountMode === 'personal' && (typeof data.profile.email !== 'string' || data.profile.email.toLowerCase() !== ownerEmail)) throw failure('unified_owner_only', 403);
+      // Stable upstream subject, never an email, decoded JWT claim or browser tenant selector.
+      const tenantId = accountMode === 'personal' || data.profile.id === config.legacyOwnerId
+        ? 'cloud-owner' : `account-${digest(JSON.stringify([backend.origin, data.profile.id]))}`;
+      const profile = { id: data.profile.id, tenantId };
       if (profiles.size >= 64) profiles.delete(profiles.keys().next().value);
       profiles.set(key, { profile, expires: now() + PROFILE_AGE });
       return profile;
@@ -71,23 +78,32 @@ export function createUnifiedAccess({ config, publicOrigin, now = Date.now, fetc
     }
     finally { active--; }
   }
+  async function resolvePrincipal(request) {
+    expire();
+    const value = readCookie(request, COOKIE), token = tokenFrom(request);
+    if (!value || !/^[a-zA-Z0-9_-]{43}$/.test(value)) return null;
+    const session = sessions.get(digest(value));
+    if (!session) return null;
+    if (!token || digest(token) !== session.tokenDigest) { sessions.delete(digest(value)); return null; }
+    try {
+      const profile = await verifyProfile(token);
+      if (profile.id !== session.profileId) { sessions.delete(digest(value)); return null; }
+      return { tenantId: profile.tenantId };
+    } catch (cause) {
+      if ([401, 403].includes(cause.statusCode)) { sessions.delete(digest(value)); return null; }
+      throw cause; // An outage never switches to the old local password.
+    }
+  }
   return {
     provider: 'app-services',
+    accountMode,
+    legacyOwnerMapped: accountMode === 'personal' || config.legacyOwnerId !== undefined,
+    resolvePrincipal,
     options(request) {
-      return { provider: 'app-services', accountLoginUrl: `${account.origin}/?login=1&loginNext=%2Fdashboard`, automaticContinue: readCookie(request, SIGNED_OUT) !== '1' };
+      return { provider: 'app-services', accountMode, accountLoginUrl: `${account.origin}/?login=1&loginNext=%2Fdashboard`, automaticContinue: readCookie(request, SIGNED_OUT) !== '1' };
     },
     async authenticated(request) {
-      expire();
-      const value = readCookie(request, COOKIE), token = tokenFrom(request);
-      if (!value || !/^[a-zA-Z0-9_-]{43}$/.test(value)) return false;
-      const session = sessions.get(digest(value));
-      if (!session) return false;
-      if (!token || digest(token) !== session.tokenDigest) { sessions.delete(digest(value)); return false; }
-      try { return (await verifyProfile(token)).id === session.profileId; }
-      catch (cause) {
-        if ([401, 403].includes(cause.statusCode)) { sessions.delete(digest(value)); return false; }
-        throw cause; // An outage never switches to the old local password.
-      }
+      return Boolean(await resolvePrincipal(request));
     },
     async resume(request) {
       const token = tokenFrom(request);

package/src/api.js

@@ -6,8 +6,11 @@ async function request(path, { timeoutMs = 12000, ...options } = {}) {
   return payload;
 }
 export const api = {
+  saveDeviceProfile: (profile) => request('/api/devices/profile', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(profile) }),
+  collectDevice: (deviceId) => request('/api/devices/collect', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ deviceId }), timeoutMs: 30000 }),
+  remotePeers: () => request('/api/remote/peers'),
   lookupPairing: (code) => request('/api/drivers/pairing/lookup', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ code }), timeoutMs: 12000 }),
-  approvePairing: (id, shareSsh) => request('/api/drivers/pairing/approve', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id, shareSsh }), timeoutMs: 12000 }),
+  approvePairing: (id, shareSsh, code, fingerprint) => request('/api/drivers/pairing/approve', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id, shareSsh, code, fingerprint }), timeoutMs: 12000 }),
   revokeDriver: (id) => request('/api/drivers/revoke', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id }), timeoutMs: 12000 }),
   logout: () => request('/api/auth/logout', { method: 'POST' }),
   overview: () => request('/api/overview'),

package/src/device-state.js

@@ -7,3 +7,22 @@ export function expireSshSnapshots(overview, now = Date.now()) {
   const stats = devices.reduce((totals, device) => { totals.total++; totals[device.state]++; return totals; }, { total: 0, online: 0, unknown: 0, expired: 0 });
   return { ...overview, devices, stats };
 }
+
+export const DEVICE_TYPE_LABELS = { unspecified: '未分类', personal: '个人电脑', server: '服务器', workstation: '工作站', other: '其他' };
+export function deviceStatus(device, now = Date.now()) {
+  if (device.state === 'unknown') return { label: '未知', title: '尚未取得资源数据；未把设备视为已连接。' };
+  if (device.source === 'driver-report' && (device.managementDriver.lastSeen == null || now - device.managementDriver.lastSeen > 90_000)) return { label: '未回报', title: '超过 90 秒未收到 Driver 回报。请确认设备已唤醒、Driver 正在运行且能连接云端。旧数据保留，不表示密钥过期。' };
+  if (device.state === 'expired') return { label: '待采集', title: '上次资源快照较早，点击采集一次取得新数据；不表示设备断线或密钥过期。' };
+  return { label: '在线', title: device.transport === 'ssh' ? '最近一次 SSH 检查成功，不表示持续连接。' : '最近收到真实资源数据。' };
+}
+export function collectionAvailability(device, now = Date.now()) {
+  if (device.source === 'driver-report') {
+    if (device.collection?.status === 'pending' && device.collection.expiresAt > now) return { available: false, pending: true, hint: '等待设备采集…' };
+    if (device.kind !== 'management') return { available: false, hint: '请在管理电脑检查 SSH' };
+    if (device.managementDriver.lastSeen == null || now - device.managementDriver.lastSeen > 90_000) return { available: false, hint: '请启动设备上的 Driver' };
+    if (!device.collection?.supported) return { available: false, hint: device.collection?.reason === 'driver_control_unavailable' ? '采集通道暂不可用' : '需更新设备 Driver' };
+    return { available: true, hint: '通知 Driver 重新采集内存与磁盘；不执行远程命令。' };
+  }
+  if (device.transport === 'ssh') return { available: Boolean(device.ssh?.checkAvailable && !device.ssh.checking && !device.ssh.queued), hint: '使用当前 SSH 配置进行一次只读检查并采集。' };
+  return { available: device.source === 'local-runtime' && device.scope === 'host', hint: '从当前本机进程重新读取内存与磁盘。' };
+}

package/src/login.css

@@ -14,3 +14,7 @@ button:disabled { opacity: .6; }
 .login-link { display: grid; place-items: center; min-height: 44px; margin-top: 24px; border-radius: 8px; color: white; background: #3c622a; text-decoration: none; font-size: 14px; }
 .help { line-height: 1.7; margin: 20px 0; }
 small { color: #788473; }
+
+.install-help { margin-top: 24px; padding-top: 18px; border-top: 1px solid #e3e7e0; line-height: 1.8; }
+.install-help a { color: #3c622a; text-underline-offset: 3px; }
+.install-help span { font-size: 12px; }

package/src/login.js

@@ -30,6 +30,7 @@ try {
   const response = await fetch('/api/auth/options', { signal: AbortSignal.timeout(5000) });
   if (!response.ok) throw new Error();
   options = await response.json();
+  document.querySelector('#access-notes').textContent = options.accountMode === 'multi-user' ? '账号设备隔离 · HTTPS 保护' : '个人访问 · HTTPS 保护';
   loading.hidden = true;
   if (options.provider === 'app-services') {
     const target = new URL(options.accountLoginUrl);