device-center 0.2.0-beta.3 → 0.2.0-beta.5

package/server/drivers/windowsSecurity.mjs

@@ -0,0 +1,119 @@
+import { spawnSync } from 'node:child_process';
+import { win32 } from 'node:path';
+
+// Fixed PowerShell code; paths and secrets travel only on stdin, never in arguments.
+// No execution-policy change, elevation, password, external download or shell expansion.
+export const powershellPath = (environment = process.env) => {
+  const systemRoot = environment.SystemRoot;
+  if (!systemRoot || !win32.isAbsolute(systemRoot) || /[\r\n\0]/.test(systemRoot)) throw new Error('windows_system_root_required');
+  return win32.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+};
+export const powershellArguments = source => ['-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(source, 'utf16le').toString('base64')];
+export function runPowerShell(source, input, { spawnImpl = spawnSync, environment = process.env } = {}) {
+  const result = spawnImpl(powershellPath(environment), powershellArguments(source), {
+    input: JSON.stringify(input), encoding: 'utf8', windowsHide: true, shell: false, timeout: 15_000, maxBuffer: 512 * 1024,
+  });
+  // PowerShell diagnostics can contain input values. Never relay them to the caller.
+  if (result.error || result.status !== 0) throw new Error('windows_security_operation_failed');
+  try { return JSON.parse(result.stdout.replace(/^\uFEFF/, '').trim()); }
+  catch { throw new Error('windows_security_response_invalid'); }
+}
+export const powershellPreamble = `
+$ErrorActionPreference = 'Stop'
+# A Node child launched from PowerShell 7 inherits its module search path.
+# Windows PowerShell 5.1 must load its own built-in modules (including Set-Acl),
+# not incompatible PS7 or user-installed modules. This affects only this child.
+$env:PSModulePath = [IO.Path]::Combine($PSHOME, 'Modules')
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+`;
+export const windowsStorageSource = powershellPreamble + `
+function Assert-PlainPath([string] $path) {
+  $cursor = [IO.Path]::GetFullPath($path)
+  while ($cursor) {
+    if ([IO.File]::Exists($cursor) -or [IO.Directory]::Exists($cursor)) {
+      $item = Get-Item -LiteralPath $cursor -Force
+      if (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'reparse_point' }
+    }
+    $parent = [IO.Path]::GetDirectoryName($cursor)
+    if ($parent -eq $cursor) { break }
+    $cursor = $parent
+  }
+}
+function Assert-Private([string] $path) {
+  Assert-PlainPath $path
+  $acl = Get-Acl -LiteralPath $path
+  if ($acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value) { throw 'owner_required' }
+  $currentAllowed = $false
+  foreach ($rule in $acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])) {
+    if ($rule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow) { throw 'deny_rule' }
+    if ($rule.IdentityReference.Value -notin @($sid.Value, 'S-1-5-18')) { throw 'private_acl_required' }
+    if ($rule.IdentityReference.Value -eq $sid.Value -and ($rule.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -eq [System.Security.AccessControl.FileSystemRights]::FullControl) { $currentAllowed = $true }
+  }
+  if (-not $currentAllowed) { throw 'current_user_access_required' }
+}
+switch ($request.operation) {
+  'ensure-directory' {
+    Assert-PlainPath $request.path
+    if (-not [IO.Directory]::Exists($request.path)) {
+      $directory = [IO.Directory]::CreateDirectory($request.path)
+      $acl = New-Object System.Security.AccessControl.DirectorySecurity
+      $acl.SetOwner($sid)
+      $acl.SetAccessRuleProtection($true, $false)
+      foreach ($principal in @($sid.Value, 'S-1-5-18')) {
+        $identity = [System.Security.Principal.SecurityIdentifier]::new($principal)
+        $rule = [System.Security.AccessControl.FileSystemAccessRule]::new($identity, 'FullControl', 'ContainerInherit, ObjectInherit', 'None', 'Allow')
+        $acl.AddAccessRule($rule)
+      }
+      Set-Acl -LiteralPath $directory.FullName -AclObject $acl
+    }
+    Assert-Private $request.path
+    @{ ok = $true } | ConvertTo-Json -Compress
+  }
+  'assert-file' {
+    Assert-Private ([IO.Path]::GetDirectoryName($request.path))
+    Assert-Private $request.path
+    @{ ok = $true } | ConvertTo-Json -Compress
+  }
+  'secure-new-file' {
+    # Called only after our exclusive wx creation in an already protected directory.
+    Assert-Private ([IO.Path]::GetDirectoryName($request.path))
+    Assert-PlainPath $request.path
+    $acl = [System.Security.AccessControl.FileSecurity]::new()
+    $acl.SetOwner($sid)
+    $acl.SetAccessRuleProtection($true, $false)
+    foreach ($principal in @($sid.Value, 'S-1-5-18')) {
+      $identity = [System.Security.Principal.SecurityIdentifier]::new($principal)
+      $acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($identity, 'FullControl', 'Allow'))
+    }
+    Set-Acl -LiteralPath $request.path -AclObject $acl
+    Assert-Private $request.path
+    @{ ok = $true } | ConvertTo-Json -Compress
+  }
+  'protect' {
+    Add-Type -AssemblyName System.Security
+    $data = [Convert]::FromBase64String($request.data)
+    $encrypted = [System.Security.Cryptography.ProtectedData]::Protect($data, $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser)
+    @{ data = [Convert]::ToBase64String($encrypted) } | ConvertTo-Json -Compress
+    [Array]::Clear($data, 0, $data.Length)
+  }
+  'unprotect' {
+    Add-Type -AssemblyName System.Security
+    $data = [System.Security.Cryptography.ProtectedData]::Unprotect([Convert]::FromBase64String($request.data), $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser)
+    @{ data = [Convert]::ToBase64String($data) } | ConvertTo-Json -Compress
+    [Array]::Clear($data, 0, $data.Length)
+  }
+  default { throw 'unknown_storage_operation' }
+}
+`;
+export function windowsStorage(operation, values) {
+  if (process.platform !== 'win32') throw new Error('windows_only');
+  return runPowerShell(windowsStorageSource, { operation, ...values });
+}
+export const protectWindowsIdentity = value => ({ format: 'device-center-dpapi-v1', data: windowsStorage('protect', { data: Buffer.from(JSON.stringify(value)).toString('base64') }).data });
+export function unprotectWindowsIdentity(value) {
+  if (value?.format !== 'device-center-dpapi-v1' || typeof value.data !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value.data)) throw new Error('windows_encrypted_identity_required');
+  return JSON.parse(Buffer.from(windowsStorage('unprotect', { data: value.data }).data, 'base64').toString('utf8'));
+}

package/server/drivers/windowsService.mjs

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { powershellArguments, powershellPath, powershellPreamble, runPowerShell } from './windowsSecurity.mjs';
+
+const literal = value => `'${String(value).replaceAll("'", "''")}'`;
+export function windowsServiceDefinition({ home, root, node, script, port, dbPath, logPath, errorLogPath, environment = process.env }) {
+  const launcher = `$ErrorActionPreference = 'Stop'\n$env:PORT = '${port}'\n$env:DEVICE_CENTER_DB_PATH = ${literal(dbPath)}\n$env:DEVICE_CENTER_SERVICE_MANAGER = 'windows-task'\n$env:DEVICE_CENTER_RUNTIME = 'native'\n$env:DEVICE_CENTER_PUBLIC_ORIGIN = $null\n$env:DEVICE_CENTER_AUTH_FILE = $null\nSet-Location -LiteralPath ${literal(root)}\n# Windows PowerShell 5.1 treats redirected native stderr as ErrorRecord.\n# Keep Node warnings visible in the log; use its exit code for task failure.\n$ErrorActionPreference = 'Continue'\n$LASTEXITCODE = 1\n& ${literal(node)} ${literal(script)} >> ${literal(logPath)} 2>> ${literal(errorLogPath)}\n$exitCode = $LASTEXITCODE\n$ErrorActionPreference = 'Stop'\nexit $exitCode\n`;
+  return {
+    taskName: `DeviceCenter-${createHash('sha256').update(home.toLowerCase()).digest('hex').slice(0, 16)}`,
+    executable: powershellPath(environment),
+    arguments: ['-WindowStyle', 'Hidden', ...powershellArguments(launcher)].join(' '),
+    workingDirectory: root, logonType: 'InteractiveToken', runLevel: 'Limited', trigger: 'CurrentUserLogon',
+  };
+}
+// COM Task Scheduler is built into Windows. Only this user's exact task is touched.
+export const windowsTaskSource = powershellPreamble + `
+$scheduler = New-Object -ComObject 'Schedule.Service'
+$scheduler.Connect()
+$folder = $scheduler.GetFolder('\\')
+$task = $null
+try { $task = $folder.GetTask($request.task.taskName) } catch {
+  $exception = $_.Exception
+  while ($exception.InnerException) { $exception = $exception.InnerException }
+  if ($exception.HResult -ne -2147024894) { throw }
+}
+function Assert-OurTask {
+  if (-not $task) { throw 'task_missing' }
+  $definition = $task.Definition
+  $principal = $definition.Principal
+  $principalSid = $principal.UserId
+  if ($principal.UserId -ne $sid.Value) { $principalSid = ([System.Security.Principal.NTAccount]::new($principal.UserId)).Translate([System.Security.Principal.SecurityIdentifier]).Value }
+  if ($principalSid -ne $sid.Value -or $principal.LogonType -ne 3 -or $principal.RunLevel -ne 0) { throw 'task_principal_changed' }
+  if ($definition.Actions.Count -ne 1 -or $definition.Triggers.Count -ne 1) { throw 'task_changed' }
+  $action = $definition.Actions.Item(1)
+  $trigger = $definition.Triggers.Item(1)
+  if ($action.Type -ne 0 -or $action.Path -ne $request.task.executable -or $action.Arguments -cne $request.task.arguments -or $action.WorkingDirectory -cne $request.task.workingDirectory -or $trigger.Type -ne 9 -or $trigger.UserId -ne $sid.Value) { throw 'task_action_changed' }
+}
+switch ($request.operation) {
+  'install' {
+    if ($task) { throw 'task_already_exists' }
+    $definition = $scheduler.NewTask(0)
+    $definition.RegistrationInfo.Description = 'Device Center: current user local Driver; login startup only.'
+    $definition.Principal.UserId = $sid.Value
+    $definition.Principal.LogonType = 3
+    $definition.Principal.RunLevel = 0
+    $trigger = $definition.Triggers.Create(9)
+    $trigger.UserId = $sid.Value
+    $action = $definition.Actions.Create(0)
+    $action.Path = $request.task.executable
+    $action.Arguments = $request.task.arguments
+    $action.WorkingDirectory = $request.task.workingDirectory
+    $definition.Settings.Enabled = $true
+    $definition.Settings.AllowDemandStart = $true
+    $definition.Settings.StartWhenAvailable = $true
+    $definition.Settings.DisallowStartIfOnBatteries = $false
+    $definition.Settings.StopIfGoingOnBatteries = $false
+    $definition.Settings.ExecutionTimeLimit = 'PT0S'
+    $definition.Settings.MultipleInstances = 2
+    $definition.Settings.RestartInterval = 'PT1M'
+    $definition.Settings.RestartCount = 3
+    $task = $folder.RegisterTaskDefinition($request.task.taskName, $definition, 2, $sid.Value, $null, 3)
+    $null = $task.Run($null)
+    @{ registered = $true } | ConvertTo-Json -Compress
+  }
+  'status' {
+    if ($task) { Assert-OurTask }
+    @{ exists = [bool]$task; state = $(if ($task) { [int]$task.State } else { $null }) } | ConvertTo-Json -Compress
+  }
+  'stop' { Assert-OurTask; $task.Stop(0); @{ stopped = $true } | ConvertTo-Json -Compress }
+  'remove' { Assert-OurTask; $folder.DeleteTask($request.task.taskName, 0); @{ removed = $true } | ConvertTo-Json -Compress }
+  default { throw 'unknown_task_operation' }
+}
+`;
+export function windowsTask(operation, task) {
+  if (process.platform !== 'win32') throw new Error('windows_only');
+  try { return runPowerShell(windowsTaskSource, { operation, task }); }
+  catch { throw new Error('Windows 当前用户任务操作失败。请检查任务计划程序、组策略或既有任务；未提权、改策略或覆盖任务。可改用 start 前台模式。'); }
+}

package/server/index.mjs

@@ -1,6 +1,7 @@
 import { createServer as createHttpServer } from 'node:http';
+import { readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { extname, resolve } from 'node:path';
+import { extname, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { openDatabase } from './database.mjs';
 import { currentPrincipal } from './adapters/identity/localDemo.mjs';
@@ -14,6 +15,14 @@ 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' });
+// Deployed archives carry release.json; npm and source installs report only the package version.
+function deployedVersion(releaseFile) {
+  const version = JSON.parse(readFileSync(resolve(PROJECT_ROOT, 'package.json'), 'utf8')).version;
+  let manifest = null;
+  try { manifest = JSON.parse(readFileSync(releaseFile, 'utf8')); } catch { /* not a deployed archive */ }
+  const matches = manifest?.kind === 'device-center-web' && manifest.version === version && /^[a-f0-9]{40}$/.test(manifest.sourceSha ?? '');
+  return { version, sourceSha: matches ? manifest.sourceSha : null };
+}
 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,11 +51,13 @@ async function readJson(request) {
 async function serveStatic(pathname, response) {
   let filePath;
   if (pathname === '/' || pathname === '/index.html') filePath = resolve(PROJECT_ROOT, 'index.html');
+  else if (pathname === '/favicon.svg') filePath = resolve(PROJECT_ROOT, 'favicon.svg');
   else if (pathname === '/login') filePath = resolve(PROJECT_ROOT, 'login.html');
+  else if (pathname === '/pair') 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' });
+    if (!filePath.startsWith(resolve(PROJECT_ROOT, 'src') + sep)) return sendJson(response, 404, { error: 'not_found' });
   } else return sendJson(response, 404, { error: 'not_found' });
   try {
     const body = await readFile(filePath);
@@ -59,10 +70,11 @@ async function serveStatic(pathname, response) {
   } catch { sendJson(response, 404, { error: 'not_found' }); }
 }
 
-export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite', web = true, runtime = 'native', sshHome, sshProbe, publicOrigin, authFile, authFetch, cloudLinkFile, driverFetch, driverBundlePath = resolve(PROJECT_ROOT, 'driver-source.tar.gz') } = {}) {
+export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite', web = true, runtime = 'native', sshHome, sshProbe, publicOrigin, authFile, authFetch, cloudLinkFile, driverFetch, driverBundlePath = resolve(PROJECT_ROOT, 'driver-source.tar.gz'), releaseFile = resolve(PROJECT_ROOT, 'release.json') } = {}) {
   const cloudAccess = createCloudAccess({ publicOrigin, authFile, fetchImpl: authFetch });
   if (runtime === 'cloud' && !cloudAccess) throw new Error('cloud_authentication_required');
   const cloud = Boolean(cloudAccess);
+  const health = Object.freeze({ ok: true, mode: cloud ? 'cloud' : 'local', runtime: cloud ? 'cloud' : runtime, ...deployedVersion(releaseFile) });
   const absoluteDbPath = resolve(dbPath);
   const db = openDatabase(absoluteDbPath);
   const startedAt = Date.now();
@@ -81,8 +93,11 @@ 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 liveness and deployed version only; no account, device or configuration data.
+      if (path === '/api/health' && request.method === 'GET') return sendJson(response, 200, health);
+      if (['/pair', '/src/pair.js', '/src/pair.css', '/src/pairing-handoff.js', '/src/api.js'].includes(path) && request.method === 'GET') return await serveStatic(path, response);
       // Public static installation reference only. No identity, configuration or owner API.
-      if (['/start', '/start.html', '/src/start.js', '/src/start.css', '/src/onboarding.js', '/src/i18n.js', '/src/i18n.css', '/src/messages.js', '/src/install-prompt.js'].includes(path) && request.method === 'GET') return await serveStatic(path, response);
+      if (['/start', '/start.html', '/favicon.svg', '/src/start.js', '/src/start.css', '/src/onboarding.js', '/src/i18n.js', '/src/i18n.css', '/src/messages.js', '/src/install-prompt.js', '/src/install-walkthrough.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' });
@@ -93,7 +108,7 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
         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 (['/login', '/src/login.js', '/src/login-flow.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') {
           if (request.headers.origin !== origin) return sendJson(response, 403, { error: 'same_origin_required' });
@@ -113,12 +128,21 @@ 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) });
         }
-        const principal = await cloudAccess.resolvePrincipal(request);
+        let principal;
+        try { principal = await cloudAccess.resolvePrincipal(request); }
+        catch (cause) {
+          // An identity-provider outage is recoverable in the login UI, not another trip to the account homepage.
+          if (path !== '/' || request.method !== 'GET' || cause.statusCode !== 503) throw cause;
+          const query = new URLSearchParams({ reason: 'unavailable' });
+          if (/^(zh-CN|zh-TW|en|ja|ko|es|fr|de|pt-BR)$/.test(url.searchParams.get('lang') ?? '')) query.set('lang', url.searchParams.get('lang'));
+          response.writeHead(303, { location: `/login?${query}`, 'cache-control': 'no-store' }); return response.end();
+        }
         if (!principal) {
           if (path === '/' && request.method === 'GET') { response.writeHead(303, { location: `/login${/^(zh-CN|zh-TW|en|ja|ko|es|fr|de|pt-BR)$/.test(url.searchParams.get('lang') ?? '') ? '?lang=' + url.searchParams.get('lang') : ''}`, 'cache-control': 'no-store' }); return response.end(); }
           return sendJson(response, 401, { error: 'authentication_required' });
         }
         accountRegistry = registry.forTenant(principal.tenantId);
+        if (path === '/api/auth/session' && request.method === 'GET') return sendJson(response, 200, { authenticated: true });
         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') {
@@ -190,7 +214,6 @@ export function createDeviceCenterServer({ dbPath = './data/device-center.sqlite
       }
       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 });
       if (path === '/api/connector/setup') return sendJson(response, 200, {
         ...(cloud ? { name: 'device-center-connector', dataMode: 'cloud', available: false, url: null, setupCommand: null, reason: 'cloud_driver_not_bound', tools: [] } : {
         name: 'device-center-connector', transport: 'Streamable HTTP', accessMode: 'read-only', dataMode: 'local-inventory',

package/server/unifiedAccess.mjs

@@ -4,6 +4,7 @@ const COOKIE = '__Host-device-center';
 const SIGNED_OUT = '__Host-device-center-signed-out';
 const SESSION_AGE = 8 * 60 * 60 * 1000;
 const PROFILE_AGE = 10_000;
+const PROFILE_TIMEOUT = 8_000;
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 const failure = (message, statusCode) => Object.assign(new Error(message), { statusCode });
 const cookie = (name, value, age) => `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=Strict; Max-Age=${age}`;
@@ -29,7 +30,7 @@ export function createUnifiedAccess({ config, publicOrigin, now = Date.now, fetc
   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();
+  const sessions = new Map(), profiles = new Map(), attempts = new Map(), verifying = new Map();
   let active = 0;
   const tokenFrom = (request) => {
     const token = readCookie(request, 'sessionToken');
@@ -40,15 +41,34 @@ export function createUnifiedAccess({ config, publicOrigin, now = Date.now, fetc
     for (const [id, profile] of profiles) if (profile.expires <= now()) profiles.delete(id);
     for (const [id, times] of attempts) if (!times.some((time) => time > now() - 60_000)) attempts.delete(id);
   };
-  async function verifyProfile(token) {
+  async function requestProfile(token) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const response = await fetchImpl(new URL('/v1/me', backend), { headers: { authorization: `Bearer ${token}`, accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(PROFILE_TIMEOUT) });
+        if (attempt === 0 && [502, 503, 504].includes(response.status)) { await response.body?.cancel(); continue; }
+        return response;
+      } catch (cause) {
+        // Retry only transport failures, never an invalid identity, body or TLS redirect.
+        const transient = ['TimeoutError', 'AbortError'].includes(cause.name) || ['ETIMEDOUT', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET'].includes(cause.code ?? cause.cause?.code);
+        if (attempt || !transient) throw cause;
+      }
+    }
+  }
+  function verifyProfile(token) {
     expire();
     const key = digest(token), cached = profiles.get(key);
-    if (cached) return cached.profile;
+    if (cached) return Promise.resolve(cached.profile);
+    if (verifying.has(key)) return verifying.get(key);
+    const pending = loadProfile(token, key).finally(() => verifying.delete(key));
+    verifying.set(key, pending);
+    return pending;
+  }
+  async function loadProfile(token, key) {
     if (active >= 8) throw failure('unified_service_busy', 503);
     active++;
     let phase = 'request', upstreamStatus;
     try {
-      const response = await fetchImpl(new URL('/v1/me', backend), { headers: { authorization: `Bearer ${token}`, accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(5000) });
+      const response = await requestProfile(token);
       phase = 'response'; upstreamStatus = response.status;
       if ([401, 403].includes(response.status)) throw failure('unified_sign_in_required', 401);
       if (!response.ok || !/^application\/json(?:;|$)/i.test(response.headers.get('content-type') ?? '')) throw failure('unified_service_unavailable', 503);

package/src/api.js

@@ -1,12 +1,16 @@
 import { getLocale } from './i18n.js';
+import { clearLoginNavigation } from './login-flow.js';
 async function request(path, { timeoutMs = 12000, ...options } = {}) {
   const response = await fetch(path, { ...options, cache: 'no-store', signal: AbortSignal.timeout(timeoutMs) });
   const payload = await response.json().catch(() => ({}));
   if (response.status === 401) { location.replace('/login?lang=' + getLocale()); throw new Error('authentication_required'); }
   if (!response.ok) throw new Error(payload.error ?? `http_${response.status}`);
+  clearLoginNavigation();
   return payload;
 }
 export const api = {
+  lookupBrowserPairing: browserTicket => request('/api/drivers/pairing/lookup', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ browserTicket }) }),
+  approveBrowserPairing: input => request('/api/drivers/pairing/approve', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input) }),
   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'),

package/src/install-prompt.js

@@ -7,10 +7,10 @@ export function localizedInstallPrompt(plan, locale) {
     tr('prompt.intro'),
     tr('prompt.choice', { mode: tr(plan.mode === 'local' ? 'guide.local' : plan.mode === 'official' ? 'guide.hosted' : 'guide.custom'), version: plan.version, run: tr(plan.background ? 'prompt.background' : 'prompt.foreground') }),
     plan.controlOrigin ? tr('prompt.private', { origin: plan.controlOrigin }) : '',
-    `1. ${tr('prompt.environment')}`,
+    `1. ${tr(plan.os === 'windows' ? 'prompt.windowsEnvironment' : 'prompt.environment')}`,
     `2. ${tr('prompt.existing', { url: plan.url, status: c.bindingStatus, service: c.serviceStatus })}`,
     `3. ${tr('prompt.userInstall')}\n   ${c.install}\n   ${c.version}\n   ${tr('prompt.config')}`,
-    `4. ${plan.background ? `${tr('prompt.bg')}\n   ${c.servicePlan}\n   ${c.serviceInstall}\n   ${c.serviceStatus}` : `${tr('prompt.fg')}${plan.controlOrigin ? '' : `\n   ${c.foreground}`}`}`,
+    `4. ${plan.background ? `${tr(plan.os === 'windows' ? 'prompt.windowsBackground' : 'prompt.bg')}\n   ${c.servicePlan}\n   ${c.serviceInstall}\n   ${c.serviceStatus}` : `${tr('prompt.fg')}${plan.controlOrigin ? '' : `\n   ${c.foreground}`}`}`,
     `5. ${plan.controlOrigin ? `${tr('prompt.pairBefore')}\n   ${c.pairingPlan}\n   ${c.connect}\n   ${tr('prompt.pairAfter', { origin: plan.controlOrigin })}` : tr('prompt.local')}`,
     `6. ${tr('prompt.mcp', { url: plan.url, mcp: plan.mcpUrl })}`,
     `7. ${tr('prompt.verify')}\n   ${tr('prompt.uninstall')}\n   ${c.uninstallService}`,

package/src/install-walkthrough.js

@@ -0,0 +1,49 @@
+import { translate } from './i18n.js';
+
+// Instruction illustrations only. Navigation never installs software or confirms a binding.
+export function installationSteps({ method = 'agent', mode = 'local', pairingMethod = 'browser', os = 'posix' } = {}) {
+  if (!['agent', 'manual'].includes(method) || !['local', 'official', 'self-hosted'].includes(mode) || !['posix', 'windows'].includes(os) || !['browser', 'headless'].includes(pairingMethod)) throw new Error('invalid_installation_walkthrough');
+  const manual = method === 'manual', cloud = mode !== 'local', headless = manual && pairingMethod === 'headless';
+  return [
+    { tab: 'walk.pasteTab', title: manual ? os === 'windows' ? 'walk.windowsTitle' : 'walk.terminalTitle' : 'walk.agentTitle', body: manual ? os === 'windows' ? 'walk.windowsBody' : 'walk.terminalBody' : 'walk.agentBody', picture: manual ? 'terminal' : 'chat' },
+    { tab: cloud ? 'walk.bindTab' : 'walk.installTab', title: cloud ? headless ? 'walk.headlessTitle' : 'walk.browserTitle' : 'walk.installTitle', body: cloud ? headless ? 'walk.headlessBody' : 'walk.browserBody' : manual ? 'walk.installBody' : 'walk.agentInstallBody', picture: cloud ? headless ? 'headless' : 'pair' : 'install' },
+    { tab: 'walk.checkTab', title: 'walk.checkTitle', body: cloud ? 'walk.cloudCheckBody' : 'walk.localCheckBody', picture: 'dashboard' },
+  ];
+}
+
+const escape = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+const arrows = '<svg viewBox="0 0 32 20" aria-hidden="true"><path d="M2 10h26M20 3l8 7-8 7"/></svg>';
+const clipboard = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5H5v16h14V5h-3M8 3h8v5H8zM8 12h8m-8 4h5"/></svg>';
+const pointer = '<svg class="picture-pointer" viewBox="0 0 30 36" aria-hidden="true"><path d="m4 3 21 18-10 1-5 10z"/></svg>';
+
+export function installWalkthroughMarkup({ method = 'agent', mode = 'local', pairingMethod = 'browser', os = 'posix', step = 0, copied = false, controlOrigin = '', localUrl = 'http://127.0.0.1:5174', locale = 'zh-CN' } = {}) {
+  const steps = installationSteps({ method, mode, pairingMethod, os });
+  if (!Number.isInteger(step) || step < 0 || step >= steps.length) throw new Error('invalid_installation_step');
+  const tr = (key, values) => escape(translate(locale, key, values));
+  const active = steps[step], cloud = mode !== 'local';
+  const window = (title, contents, type = '') => `<div class="picture-window ${type}"><div class="picture-titlebar"><i></i><i></i><i></i><span>${title}</span></div>${contents}</div>`;
+  const paste = type => `<div class="picture-transfer"><span>${clipboard}${tr('walk.copiedContent')}</span>${arrows}<span>${tr(type === 'terminal' ? 'walk.terminal' : 'walk.chat')}</span></div>`;
+  const fingerprint = `<div class="picture-fingerprints"><span>${tr('walk.terminal')}</span><code>${tr('walk.fullFingerprint')}</code><b>=</b><span>${tr('walk.browser')}</span><code>${tr('walk.fullFingerprint')}</code></div>`;
+  const approval = `<div class="picture-approval">${tr('walk.approve')}${pointer}</div>`;
+  const browserTitle = `<span class="picture-address">${escape(controlOrigin || 'https://devices.example.com')}</span>`;
+  let picture;
+  if (active.picture === 'terminal') {
+    picture = `${paste('terminal')}${window(os === 'windows' ? 'Windows PowerShell' : tr('walk.targetTerminal'), `<div class="picture-terminal"><div class="picture-paste-line"><span>${os === 'windows' ? 'PS&gt;' : '$'}</span><div>${tr('walk.pasteScript')}<i class="picture-caret"></i></div>${pointer}</div><div class="picture-keyline"><span>${os === 'windows' ? 'Windows <kbd>Ctrl V</kbd>' : 'macOS <kbd>⌘ V</kbd> · Linux <kbd>Ctrl Shift V</kbd>'}</span><strong>${tr('walk.pressEnter')} <kbd>Enter ↵</kbd></strong></div></div>`, 'terminal-picture')}<div class="picture-launch">${os === 'windows' ? `<span>${tr('walk.openWindows')}</span>` : `<span>${tr('walk.openMac')}</span><span>${tr('walk.openLinux')}</span>`}</div>`;
+  } else if (active.picture === 'chat') {
+    picture = `${paste('chat')}${window(tr('walk.targetChat'), `<div class="picture-chat"><div class="picture-chat-message">${tr('walk.pastePrompt')}<i class="picture-caret"></i></div><div class="picture-send"><span>${tr('walk.send')}</span><b>↑</b>${pointer}</div></div>`, 'chat-picture')}`;
+  } else if (active.picture === 'pair' || active.picture === 'headless') {
+    const headless = active.picture === 'headless';
+    const transfer = headless ? `<div class="picture-transfer headless-transfer"><span>${tr('walk.targetTerminal')}<code>${tr('walk.pairCode')}</code></span>${arrows}<span>${tr('walk.otherBrowser')}</span></div>` : `<div class="picture-auto-open">${tr('walk.autoBrowser')}</div>`;
+    picture = `${transfer}${window(browserTitle, `<div class="picture-pair"><div class="picture-signin"><span>01</span>${tr('walk.signIn')}</div>${headless ? `<div class="picture-code-entry"><span>${tr('walk.openPairing', { action: translate(locale, 'panel.434') })}</span><div>${tr('walk.pasteCode')}${pointer}</div></div>` : ''}<div class="picture-signin"><span>02</span>${tr('walk.compare')}</div>${fingerprint}${approval}</div>`, 'browser-picture')}`;
+  } else if (active.picture === 'install') {
+    picture = window(tr('walk.targetTerminal'), `<div class="picture-install"><div class="picture-install-command"><span>$</span> device-center</div><div class="picture-install-row"><span>01</span>${tr('walk.driver')}</div><div class="picture-install-row"><span>02</span>${tr('walk.service')}</div>${method === 'agent' ? `<div class="picture-install-row"><span>03</span>${tr('walk.mcp')}</div>` : ''}<div class="picture-install-track"><i></i><i></i><i></i></div></div>`, 'terminal-picture');
+  } else {
+    picture = `${!cloud ? `<div class="picture-auto-open">${tr('walk.sameComputer')}</div>` : ''}${window(`<span class="picture-address">${escape(cloud ? controlOrigin || 'https://devices.example.com' : localUrl)}</span>`, `<div class="picture-dashboard"><div class="picture-device"><svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="3" width="18" height="13" rx="2"/><path d="M1 21h22M8 16l-1 5m9-5 1 5"/></svg><strong>${tr('walk.yourDevice')}</strong><span>${tr('walk.awaitReport')}</span></div><div class="picture-metrics"><div><span>${tr('panel.8')}</span><b>— / —</b><i></i></div><div><span>${tr('panel.9')}</span><b>— / —</b><i></i></div></div><div class="picture-report-time">${tr('walk.reportTime')}${pointer}</div></div>`, 'browser-picture')}`;
+  }
+  return `<ol class="walkthrough-tabs" aria-label="${tr('walk.steps')}">${steps.map((item, index) => `<li><button type="button" data-walk-step="${index}" ${index === step ? 'aria-current="step"' : ''}><span>0${index + 1}</span>${tr(item.tab)}</button></li>`).join('')}</ol>
+    <div class="walkthrough-caption" aria-live="polite"><span>${tr(active.title)}</span><small>${tr('walk.counter', { current: step + 1, total: steps.length })}</small></div>
+    <div class="walkthrough-picture" role="img" aria-label="${tr(active.title)}. ${tr(active.body)}">${picture}</div>
+    <p class="walkthrough-description">${tr(active.body)}</p>
+    ${step === 0 && !copied ? `<p class="walkthrough-copy-first">${tr('walk.copyFirst')}</p>` : ''}
+    <div class="walkthrough-navigation"><button type="button" data-walk-step="${step - 1}" ${step === 0 ? 'disabled' : ''}>${tr('walk.previous')}</button><button type="button" data-walk-step="${step === 2 ? 0 : step + 1}">${tr(step === 2 ? 'walk.restart' : 'walk.next')}</button></div>`;
+}

package/src/login-flow.js

@@ -0,0 +1,37 @@
+// A successful POST alone does not prove that the browser saved the panel cookie.
+// This read-only probe keeps a missing session from becoming a navigation loop.
+const NAVIGATION_KEY = 'device-center-login-navigation';
+const storage = () => { try { return window.sessionStorage; } catch { return null; } };
+export function clearLoginNavigation({ store = storage() } = {}) { try { store.removeItem(NAVIGATION_KEY); } catch { /* Optional storage. */ } }
+export function rememberLoginNavigation({ store = storage(), now = Date.now() } = {}) { try { store.setItem(NAVIGATION_KEY, String(now)); } catch { /* The session probe still applies. */ } }
+export function pendingLoginNavigation({ store = storage(), now = Date.now() } = {}) {
+  try {
+    const raw = store.getItem(NAVIGATION_KEY), at = Number(raw);
+    if (raw && Number.isSafeInteger(at) && at <= now && now - at < 60_000) return true;
+  } catch { /* Only a timestamp is stored, never an identity, token or destination. */ }
+  clearLoginNavigation({ store }); return false;
+}
+
+async function checkedFetch(fetchImpl, path, signal, method = 'GET') {
+  const response = await fetchImpl(path, { method, credentials: 'same-origin', cache: 'no-store', redirect: 'error', signal,
+    ...(method === 'POST' ? { headers: { 'content-type': 'application/json' }, body: '{}' } : {}) });
+  if (![200, 401].includes(response.status)) throw new Error(response.status === 403 ? 'login.owner' : response.status === 429 ? 'login.rate' : 'login.unavailable');
+  return response;
+}
+
+export async function continueSession({ fetchImpl = fetch, signal = AbortSignal.timeout(20_000) } = {}) {
+  try {
+    const existing = await checkedFetch(fetchImpl, '/api/auth/session', signal);
+    if (existing.status === 200 && (await existing.json()).authenticated === true) return;
+    if (existing.status !== 401) throw new Error('login.unavailable');
+    const resumed = await checkedFetch(fetchImpl, '/api/auth/continue', signal, 'POST');
+    if (resumed.status === 401) throw new Error('login.first');
+    if ((await resumed.json()).ok !== true) throw new Error('login.unavailable');
+    const session = await checkedFetch(fetchImpl, '/api/auth/session', signal);
+    if (session.status === 401) throw new Error('login.session');
+    if ((await session.json()).authenticated !== true) throw new Error('login.unavailable');
+  } catch (cause) {
+    if (cause.message?.startsWith('login.')) throw cause;
+    throw new Error(cause.name === 'TimeoutError' ? 'login.timeout' : 'login.unavailable');
+  }
+}

package/src/login.css

@@ -11,7 +11,9 @@ input:focus { outline: 2px solid #769e5e; outline-offset: 2px; }
 button { width: 100%; height: 42px; border: 0; border-radius: 8px; color: white; background: #3c622a; font: inherit; cursor: pointer; }
 button:disabled { opacity: .6; }
 #message, #unified-message { min-height: 20px; color: #a53939; }
-.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; }
+.login-link { display: grid; place-items: center; min-height: 44px; margin-top: 16px; border: 1px solid #cfd7cb; border-radius: 8px; color: #3c622a; text-decoration: none; font-size: 14px; }
+.login-link:focus-visible { outline: 2px solid #769e5e; outline-offset: 2px; }
+#unified[aria-busy="true"] #unified-message { color: #667363; }
 .help { line-height: 1.7; margin: 20px 0; }
 small { color: #788473; }
 

package/src/login.js

@@ -1,4 +1,9 @@
 import { initLanguage, getLocale, t } from './i18n.js';
+import { loginDestination } from './pairing-handoff.js';
+import { continueSession, rememberLoginNavigation, pendingLoginNavigation } from './login-flow.js';
+if (location.pathname === '/pair') {
+  await import('./pair.js');
+} else {
 initLanguage();
 function setMessage(element, key) { if (key) element.dataset.i18n = key; else delete element.dataset.i18n; element.textContent = key ? t(key) : ''; }
 const form = document.querySelector('#login');
@@ -9,16 +14,16 @@ async function continueUnified(manual = false) {
   checking = true;
   const message = document.querySelector('#unified-message'), button = document.querySelector('#continue-login');
   button.disabled = true;
+  document.querySelector('#unified').setAttribute('aria-busy', 'true');
+  setMessage(message, 'login.checking');
   try {
-    const response = await fetch('/api/auth/continue', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}', signal: AbortSignal.timeout(10_000) });
-    if (response.ok) { clearInterval(timer); location.replace('/?lang=' + getLocale()); return; }
-    if (response.status === 401) setMessage(message, manual ? 'login.first' : null);
-    else {
-      clearInterval(timer);
-      setMessage(message, response.status === 403 ? 'login.owner' : response.status === 429 ? 'login.rate' : 'login.unavailable');
-    }
-  } catch { setMessage(message, 'login.timeout'); clearInterval(timer); }
-  finally { checking = false; button.disabled = false; }
+    await continueSession();
+    clearInterval(timer); rememberLoginNavigation(); location.replace(loginDestination(getLocale()));
+  } catch (cause) {
+    setMessage(message, cause.message === 'login.first' && !manual ? null : cause.message);
+    if (cause.message !== 'login.first') { clearInterval(timer); watchingUntil = 0; }
+  }
+  finally { checking = false; button.disabled = false; document.querySelector('#unified').setAttribute('aria-busy', 'false'); }
 }
 document.querySelector('#continue-login').addEventListener('click', () => continueUnified(true));
 document.querySelector('#unified-login').addEventListener('click', () => {
@@ -40,7 +45,9 @@ try {
     if (target.protocol !== 'https:' || target.username || target.password) throw new Error();
     document.querySelector('#unified-login').href = target.href;
     document.querySelector('#unified').hidden = false;
-    if (options.automaticContinue) void continueUnified();
+    if (new URLSearchParams(location.search).get('reason') === 'unavailable') setMessage(document.querySelector('#unified-message'), 'login.unavailable');
+    else if (pendingLoginNavigation()) setMessage(document.querySelector('#unified-message'), 'login.returned');
+    else if (options.automaticContinue) void continueUnified();
   } else if (options.provider === 'password') { form.hidden = false; form.elements.username.focus(); }
   else throw new Error();
 } catch { loading.hidden = false; setMessage(loading, 'login.optionsError'); }
@@ -53,7 +60,9 @@ form.addEventListener('submit', async (event) => {
     const data = Object.fromEntries(new FormData(form));
     const response = await fetch('/api/auth/login', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(data), signal: AbortSignal.timeout(10_000) });
     if (!response.ok) throw new Error(response.status === 429 ? 'login.rate' : 'login.credentials');
-    form.reset(); location.replace('/?lang=' + getLocale());
+    form.reset(); location.replace(loginDestination(getLocale()));
   } catch (cause) { setMessage(message, cause.name === 'TimeoutError' ? 'login.timeout' : cause.message.startsWith('login.') ? cause.message : 'login.unavailable'); }
   finally { button.disabled = false; }
 });
+
+}