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

package/server/drivers/cloudRegistry.mjs

@@ -2,6 +2,7 @@ import { randomBytes, randomUUID, createHash } from 'node:crypto';
 import { fail, object, text, publicIdentity, verifyRequest, normalizeReport } from './driverProtocol.mjs';
 import { validateCertificate } from './certificates.mjs';
 import { createRelay } from './relay.mjs';
+import { createDeviceProfiles } from './deviceProfiles.mjs';
 
 const PAIR_AGE = 5 * 60_000;
 export function createCloudRegistry({ db, origin, now = Date.now, multiUser = false, legacyOwnerMapped = !multiUser }) {
@@ -19,6 +20,10 @@ export function createCloudRegistry({ db, origin, now = Date.now, multiUser = fa
   }
   db.exec('CREATE INDEX IF NOT EXISTS cloud_drivers_tenant_created ON cloud_drivers(tenant_id, created_at)');
   for (const table of ['driver_pairings', 'cloud_drivers']) if (!db.prepare(`PRAGMA table_info(${table})`).all().some(c => c.name === 'certificate')) db.exec(`ALTER TABLE ${table} ADD COLUMN certificate TEXT`);
+  if (!db.prepare('PRAGMA table_info(cloud_drivers)').all().some(c => c.name === 'control_seen_at')) db.exec('ALTER TABLE cloud_drivers ADD COLUMN control_seen_at INTEGER');
+  db.exec(`CREATE TABLE IF NOT EXISTS driver_collection_requests (driver_id TEXT PRIMARY KEY, request_id TEXT NOT NULL,
+    requested_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, completed_at INTEGER)`);
+  const profiles = createDeviceProfiles({ db, now, initialize: true });
   if (multiUser && !legacyOwnerMapped && db.prepare("SELECT 1 FROM cloud_drivers WHERE tenant_id='cloud-owner' LIMIT 1").get()) throw new Error('cloud_legacy_owner_mapping_required');
   let starts = [], globalLookups = [], globalApprovals = [];
   const lookups = new Map(), approvals = new Map();
@@ -54,7 +59,18 @@ export function createCloudRegistry({ db, origin, now = Date.now, multiUser = fa
     if (row.revoked_at != null) fail('driver_revoked', 403);
     return row;
   }
-  const descriptor = row => ({ id: row.id, name: row.name, platform: row.platform, fingerprint: row.fingerprint, shareSsh: Boolean(row.share_ssh), createdAt: row.created_at, revokedAt: row.revoked_at, lastSeen: row.last_seen });
+  const descriptor = row => {
+    const profile = profiles.get(row.tenant_id, `${row.id}:host`);
+    return { id: row.id, name: profile.displayName || row.name, reportedName: row.name, profile, platform: row.platform, fingerprint: row.fingerprint, shareSsh: Boolean(row.share_ssh), createdAt: row.created_at, revokedAt: row.revoked_at, lastSeen: row.last_seen };
+  };
+  const collection = row => {
+    const request = db.prepare('SELECT * FROM driver_collection_requests WHERE driver_id=?').get(row.id);
+    const connected = row.last_seen != null && now() - row.last_seen <= 90_000;
+    const supported = connected && row.control_seen_at != null && now() - row.control_seen_at <= 30_000;
+    return { supported, reason: !connected ? 'driver_not_connected' : row.control_seen_at == null ? 'driver_upgrade_required' : !supported ? 'driver_control_unavailable' : null,
+      status: !request ? 'idle' : request.completed_at != null ? 'completed' : request.expires_at <= now() ? 'timeout' : 'pending',
+      requestedAt: request?.requested_at ?? null, completedAt: request?.completed_at ?? null, expiresAt: request?.expires_at ?? null };
+  };
   const peers = row => db.prepare('SELECT * FROM cloud_drivers WHERE tenant_id=? AND revoked_at IS NULL AND certificate IS NOT NULL').all(row.tenant_id).map(peer => ({ ...descriptor(peer), certificate: peer.certificate }));
   const relay = createRelay({ db, now, getDriver: id => db.prepare('SELECT * FROM cloud_drivers WHERE id=?').get(id) });
   const registry = {
@@ -118,6 +134,7 @@ export function createCloudRegistry({ db, origin, now = Date.now, multiUser = fa
       const report = normalizeReport(input.payload, Boolean(row.share_ssh), now());
       if (row.last_seen != null && now() - row.last_seen < 15_000) fail('driver_report_too_frequent', 429);
       db.prepare('UPDATE cloud_drivers SET last_seen=?, report_json=? WHERE id=?').run(now(), JSON.stringify(report), row.id);
+      if (report.collectionRequestId && report.resources[0].observedAt != null) db.prepare('UPDATE driver_collection_requests SET completed_at=? WHERE driver_id=? AND request_id=? AND completed_at IS NULL AND expires_at>?').run(now(), row.id, report.collectionRequestId, now());
       return { ok: true, receivedAt: now() };
     },
     disconnect(input) {
@@ -133,6 +150,24 @@ export function createCloudRegistry({ db, origin, now = Date.now, multiUser = fa
       return { ok: true };
     },
     bindings: tenantId => db.prepare('SELECT * FROM cloud_drivers WHERE tenant_id=? ORDER BY created_at').all(tenantId).map(descriptor),
+    saveProfile(input, tenantId) {
+      if (!registry.devices(tenantId).some(d => d.id === input?.deviceId)) fail('device_not_found', 404);
+      return { profile: profiles.save(tenantId, input) };
+    },
+    collect(input, tenantId) {
+      object(input, ['deviceId']);
+      if (typeof input.deviceId !== 'string') fail('invalid_device_id');
+      const device = registry.devices(tenantId).find(d => d.id === input.deviceId);
+      if (!device) fail('device_not_found', 404);
+      if (device.kind !== 'management') fail('collection_requires_local_ssh_check', 409);
+      const row = db.prepare('SELECT * FROM cloud_drivers WHERE id=? AND tenant_id=? AND revoked_at IS NULL').get(device.managementDriver.id, tenantId);
+      const current = collection(row);
+      if (!current.supported) fail(current.reason, 409);
+      if (current.status === 'pending') return { status: 'pending', collection: current };
+      if (current.requestedAt != null && now() - current.requestedAt < 10_000) fail('collection_rate_limited', 429);
+      db.prepare('INSERT INTO driver_collection_requests VALUES (?,?,?,?,NULL) ON CONFLICT(driver_id) DO UPDATE SET request_id=excluded.request_id,requested_at=excluded.requested_at,expires_at=excluded.expires_at,completed_at=NULL').run(row.id, randomUUID(), now(), now() + 75_000);
+      return { status: 'pending', collection: collection(row) };
+    },
     devices(tenantId) {
       return db.prepare('SELECT * FROM cloud_drivers WHERE tenant_id=? AND revoked_at IS NULL ORDER BY created_at').all(tenantId).flatMap(row => {
         const report = row.report_json ? JSON.parse(row.report_json).resources : [{ id: 'host', name: row.name, platform: row.platform, kind: 'management', observedAt: null, memory: { status: 'unobserved', usedMb: null, totalMb: null }, disk: { status: 'unobserved', usedGb: null, totalGb: null } }];
@@ -140,7 +175,7 @@ export function createCloudRegistry({ db, origin, now = Date.now, multiUser = fa
           const latest = resource.observedAt == null || row.last_seen == null ? null : Math.min(resource.observedAt, row.last_seen);
           const age = latest == null ? null : Math.max(0, now() - latest);
           const connected = row.last_seen != null && now() - row.last_seen <= 90_000;
-          return { ...resource, id: `${row.id}:${resource.id}`, role: resource.kind === 'management' ? 'driver' : 'resource', source: 'driver-report', transport: 'driver', scope: 'host', state: age == null ? 'unknown' : !connected || age > (resource.kind === 'management' ? 90_000 : 300_000) ? 'expired' : 'online', lastHeartbeat: latest, heartbeatAgeMs: age, memory: resource.memory, disk: resource.disk, synthetic: false, managementDriver: { ...descriptor(row), origin, connected }, capabilities: { observation: true, remoteExecution: false } };
+          return profiles.apply(tenantId, { ...resource, id: `${row.id}:${resource.id}`, role: resource.kind === 'management' ? 'driver' : 'resource', source: 'driver-report', transport: 'driver', scope: 'host', state: age == null ? 'unknown' : !connected || age > (resource.kind === 'management' ? 90_000 : 300_000) ? 'expired' : 'online', lastHeartbeat: latest, heartbeatAgeMs: age, memory: resource.memory, disk: resource.disk, synthetic: false, managementDriver: { ...descriptor(row), origin, connected }, collection: resource.kind === 'management' ? collection(row) : { supported: false, reason: 'collection_requires_local_ssh_check', status: 'idle' }, capabilities: { observation: true, remoteExecution: false } });
         });
       });
     },
@@ -149,6 +184,13 @@ export function createCloudRegistry({ db, origin, now = Date.now, multiUser = fa
     start: registry.start, poll: registry.poll, report: registry.report, disconnect: registry.disconnect,
     machine(action, input) {
       const row = driver(input, `/api/driver/${action}`);
+      if (action === 'control') {
+        object(input.payload, []);
+        if (row.control_seen_at != null && now() - row.control_seen_at < 3000) fail('driver_control_too_frequent', 429);
+        db.prepare('UPDATE cloud_drivers SET control_seen_at=? WHERE id=?').run(now(), row.id);
+        const request = db.prepare('SELECT * FROM driver_collection_requests WHERE driver_id=? AND completed_at IS NULL AND expires_at>?').get(row.id, now());
+        return { request: request ? { id: request.request_id, action: 'collect-resources', expiresAt: request.expires_at } : null };
+      }
       if (action === 'certificate') { object(input.payload, ['certificate']); const cert = validateCertificate(input.payload.certificate, row.fingerprint, now()); db.prepare('UPDATE cloud_drivers SET certificate=? WHERE id=?').run(cert, row.id); return { ok: true }; }
       if (action === 'peers') { object(input.payload, []); return { peers: peers(row) }; }
       if (!row.certificate) fail('driver_certificate_required', 409);
@@ -160,6 +202,7 @@ export function createCloudRegistry({ db, origin, now = Date.now, multiUser = fa
       return {
         lookup: input => registry.lookup(input, tenantId), approve: input => registry.approve(input, tenantId),
         revoke: input => registry.revoke(input, tenantId), bindings: () => registry.bindings(tenantId), devices: () => registry.devices(tenantId), relayUsage: () => relay.usage(tenantId),
+        saveProfile: input => registry.saveProfile(input, tenantId), collect: input => registry.collect(input, tenantId),
       };
     },
   };

package/server/drivers/deviceProfiles.mjs

@@ -0,0 +1,47 @@
+// Descriptive owner metadata. It never changes device identity or grants access.
+export const DEVICE_TYPES = ['unspecified', 'personal', 'server', 'workstation', 'other'];
+const fail = (message, statusCode = 400) => { throw Object.assign(new Error(message), { statusCode }); };
+function string(value, max, multiline = false) {
+  if (typeof value !== 'string' || value.length > max || (multiline ? /[\x00-\x09\x0b-\x1f\x7f]/ : /[\x00-\x1f\x7f]/).test(value)) fail('invalid_device_profile');
+  return value.trim();
+}
+export function normalizeDeviceProfile(value) {
+  if (!value || Array.isArray(value) || Object.keys(value).some(k => !['displayName', 'type', 'purpose', 'tags', 'services'].includes(k)) || !DEVICE_TYPES.includes(value.type)) fail('invalid_device_profile');
+  const list = (items, max, length) => {
+    if (!Array.isArray(items) || items.length > max) fail('invalid_device_profile');
+    const result = items.map(v => string(v, length));
+    if (result.some(v => !v)) fail('invalid_device_profile');
+    return [...new Set(result)];
+  };
+  return { displayName: string(value.displayName, 80), type: value.type, purpose: string(value.purpose, 240, true), tags: list(value.tags, 8, 24), services: list(value.services, 12, 40) };
+}
+const EMPTY = { displayName: '', type: 'unspecified', purpose: '', tags: [], services: [], revision: 0, updatedAt: null, servicesSource: 'user-declared' };
+export function createDeviceProfiles({ db, now = Date.now, initialize = false }) {
+  const ensure = () => db.exec(`CREATE TABLE IF NOT EXISTS device_profiles (
+    tenant_id TEXT NOT NULL, device_id TEXT NOT NULL, profile_json TEXT NOT NULL,
+    revision INTEGER NOT NULL, updated_at INTEGER NOT NULL, PRIMARY KEY(tenant_id, device_id))`);
+  if (initialize) ensure();
+  const get = (tenantId, id) => {
+    if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='device_profiles'").get()) return { ...EMPTY, tags: [], services: [] };
+    const row = db.prepare('SELECT * FROM device_profiles WHERE tenant_id=? AND device_id=?').get(tenantId, id);
+    return row ? { ...normalizeDeviceProfile(JSON.parse(row.profile_json)), revision: row.revision, updatedAt: row.updated_at, servicesSource: 'user-declared' } : { ...EMPTY, tags: [], services: [] };
+  };
+  return {
+    get,
+    apply(tenantId, device) {
+      const profile = get(tenantId, device.id);
+      return { ...device, reportedName: device.reportedName ?? device.name, name: profile.displayName || device.name, profile };
+    },
+    save(tenantId, input) {
+      if (!input || Array.isArray(input) || Object.keys(input).some(k => !['deviceId', 'profile', 'revision'].includes(k)) || typeof input.deviceId !== 'string' || !input.deviceId || input.deviceId.length > 200 || !Number.isSafeInteger(input.revision) || input.revision < 0) fail('invalid_device_profile');
+      const profile = normalizeDeviceProfile(input.profile); ensure();
+      db.exec('BEGIN IMMEDIATE');
+      try {
+        if (get(tenantId, input.deviceId).revision !== input.revision) fail('device_profile_conflict', 409);
+        db.prepare('INSERT INTO device_profiles VALUES (?,?,?,?,?) ON CONFLICT(tenant_id,device_id) DO UPDATE SET profile_json=excluded.profile_json,revision=excluded.revision,updated_at=excluded.updated_at').run(tenantId, input.deviceId, JSON.stringify(profile), input.revision + 1, now());
+        db.exec('COMMIT');
+        return get(tenantId, input.deviceId);
+      } catch (error) { db.exec('ROLLBACK'); throw error; }
+    },
+  };
+}

package/server/drivers/driverProtocol.mjs

@@ -50,7 +50,8 @@ function metric(input, kind) {
   return { status: input.status, [used]: input.status === 'ok' ? input[used] : null, [total]: input.status === 'ok' ? input[total] : null };
 }
 export function normalizeReport(payload, shareSsh, now) {
-  object(payload, ['resources']);
+  object(payload, ['resources', 'collectionRequestId']);
+  if (payload.collectionRequestId !== undefined && (typeof payload.collectionRequestId !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(payload.collectionRequestId))) fail('invalid_collection_request');
   if (!Array.isArray(payload.resources) || !payload.resources.length || payload.resources.length > 16) fail('invalid_driver_resources');
   const ids = new Set();
   const resources = payload.resources.map((value, index) => {
@@ -62,5 +63,5 @@ export function normalizeReport(payload, shareSsh, now) {
     if (observedAt !== null && (!Number.isSafeInteger(observedAt) || observedAt < 0 || observedAt > now + 90_000)) fail('invalid_driver_observation_time');
     return { id: value.id, name: text(value.name), platform: text(value.platform, 64), kind: value.kind, observedAt: observedAt == null ? null : Math.min(observedAt, now), memory: metric(value.memory, 'memory'), disk: metric(value.disk, 'disk') };
   });
-  return { resources };
+  return { resources, ...(payload.collectionRequestId ? { collectionRequestId: payload.collectionRequestId } : {}) };
 }

package/server/drivers/inventory.mjs

@@ -4,12 +4,14 @@ import { discoverSsh } from './sshConfig.mjs';
 import { prepareSshProfile, probeSsh } from './sshProbe.mjs';
 import { normalizeConnectionPlan, readConnectionPlan, writeConnectionPlan } from './connectionPlans.mjs';
 import { inspectSshImport } from './sshInitialization.mjs';
+import { createDeviceProfiles } from './deviceProfiles.mjs';
 
 function associations(db, tenantId) {
   if (!db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='ssh_associations'").get()) return [];
   return db.prepare('SELECT alias, created_at AS createdAt FROM ssh_associations WHERE tenant_id = ? ORDER BY alias COLLATE NOCASE').all(tenantId);
 }
 export function createInventory({ db, tenantId, runtime = 'native', sshHome, sshProbe = probeSsh }) {
+  const profiles = createDeviceProfiles({ db });
   const activeChecks = new Set();
   const pendingChecks = new Set();
   const exclusions = () => db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='ssh_exclusions'").get()
@@ -48,7 +50,7 @@ export function createInventory({ db, tenantId, runtime = 'native', sshHome, ssh
         capabilities: { observation: Boolean(profile), remoteExecution: false },
       };
     });
-    return [observeLocalDriver({ runtime }), ...remote, ...listDevices(db, tenantId)];
+    return [observeLocalDriver({ runtime }), ...remote, ...listDevices(db, tenantId)].map(device => profiles.apply(tenantId, device));
   };
   const check = async (input) => {
     if (!input || Array.isArray(input) || Object.keys(input).some((key) => key !== 'alias') || typeof input.alias !== 'string') throw Object.assign(new Error('invalid_ssh_check'), { statusCode: 400 });
@@ -149,5 +151,22 @@ export function createInventory({ db, tenantId, runtime = 'native', sshHome, ssh
       return { removed, excluded: chosen.length, systemConfigurationChanged: false };
     } catch (cause) { db.exec('ROLLBACK'); throw cause; }
   };
-  return { list, discovery, associate, check, checkBatch, remove, associateAndCheck: (input) => configure(input, false), initializeAndCheck: (input) => configure(input, true), saveConnections, initialization, initialize };
+  const find = input => {
+    if (!input || Array.isArray(input) || typeof input.deviceId !== 'string') throw Object.assign(new Error('invalid_device_id'), { statusCode: 400 });
+    const device = list().find(d => d.id === input.deviceId);
+    if (!device) throw Object.assign(new Error('device_not_found'), { statusCode: 404 });
+    return device;
+  };
+  const saveProfile = input => { find(input); return { profile: profiles.save(tenantId, input) }; };
+  const collect = async input => {
+    if (Object.keys(input ?? {}).some(k => k !== 'deviceId')) throw Object.assign(new Error('invalid_collection_request'), { statusCode: 400 });
+    const device = find(input);
+    if (device.transport === 'ssh') {
+      const result = await check({ alias: device.ssh.alias });
+      if (!result.ok) return { status: 'failed', error: result.error, device: list().find(d => d.id === device.id) };
+    }
+    else if (device.source !== 'local-runtime' || runtime !== 'native') throw Object.assign(new Error('collection_unavailable'), { statusCode: 409 });
+    return { status: 'completed', device: list().find(d => d.id === device.id) };
+  };
+  return { list, discovery, associate, check, checkBatch, remove, saveProfile, collect, associateAndCheck: (input) => configure(input, false), initializeAndCheck: (input) => configure(input, true), saveConnections, initialization, initialize };
 }

package/server/index.mjs

@@ -13,6 +13,7 @@ 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));
@@ -42,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' });
@@ -79,11 +81,18 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
       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 (['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 (['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') {
@@ -111,7 +120,7 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
         }
         accountRegistry = registry.forTenant(principal.tenantId);
         if (path === '/api/drivers' && request.method === 'GET') return sendJson(response, 200, { drivers: accountRegistry.bindings() });
-        const ownerActions = { '/api/drivers/pairing/lookup': 'lookup', '/api/drivers/pairing/approve': 'approve', '/api/drivers/revoke': 'revoke' };
+        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, accountRegistry[ownerActions[path]](await readJson(request)));
@@ -144,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)));

package/src/api.js

@@ -6,6 +6,8 @@ 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, code, fingerprint) => request('/api/drivers/pairing/approve', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id, shareSsh, code, fingerprint }), timeoutMs: 12000 }),

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; }