livedesk 0.1.500 → 0.1.501

package/bin/livedesk.js

@@ -34,6 +34,7 @@ import {
 import { runLegacyClientUpdateSupervisorCli } from '../bootstrap/legacy-client-update.js';
 import { transferSavedClientSessionToHub } from '../bootstrap/hub-auth-handoff.js';
 import {
+  buildUpdateHostWorkerEnvironment,
   cancelUpdateHostJob,
   ensureUpdateHost,
   getUpdateHostJob,
@@ -2680,8 +2681,7 @@ async function runManager(args, resolvedRole = null, runtimeLock = null, updateH
       reportLauncherUpdate(`[LiveDesk Hub] Could not persist the restart supervisor state: ${error instanceof Error ? error.message : String(error)}.`, true);
       throw error;
     }
-    const workerEnvironment = {
-      ...process.env,
+    const workerEnvironment = buildUpdateHostWorkerEnvironment(process.env, {
       LIVEDESK_RESTART_WAIT_PID: String(process.pid),
       LIVEDESK_RESTART_PREVIOUS_RUNTIME_PID: String(request?.pid || 0),
       LIVEDESK_RESTART_OPERATION_ID: operationId,
@@ -2701,7 +2701,7 @@ async function runManager(args, resolvedRole = null, runtimeLock = null, updateH
       LIVEDESK_RESTART_FALLBACK_CWD: originalCwd,
       LIVEDESK_UPDATE_ORIGINAL_CWD: originalCwd,
       LIVEDESK_RESTART_LOG_PATH: hubLogPath
-    };
+    });
     const hostJobId = `hub-${safeUpdatePathSegment(operationId)}`;
     let hostJob;
     try {

package/bootstrap/legacy-client-update.js

@@ -20,6 +20,12 @@ import {
   createWindowsProcessTreeTracker,
   drainOwnedWindowsAgentTreeUntilStopped
 } from '../client/src/runtime/agent-process-lifecycle.js';
+import {
+  addExactNpxRecoveryCacheArgument,
+  isInterruptedExactNpxInstallFailure,
+  normalizeExactNpxRecoveryCache,
+  prepareExactNpxCacheRecovery
+} from './npm-update-cache.mjs';
 
 const DEFAULT_RUNTIME_PORT = 5179;
 const TARGET_ATTEMPT_LIMIT = 3;
@@ -169,8 +175,8 @@ export function buildLegacyClientUpdateNpxEnvironment(baseEnv, neutralCwd) {
   return env;
 }
 
-function buildExactNpxArgs(neutralCwd, preference, version, args = []) {
-  return [
+function buildExactNpxArgs(neutralCwd, preference, version, args = [], recoveryCache = '') {
+  return addExactNpxRecoveryCacheArgument([
     '-y',
     preference,
     '--prefix',
@@ -178,7 +184,7 @@ function buildExactNpxArgs(neutralCwd, preference, version, args = []) {
     '--workspaces=false',
     `livedesk@${version}`,
     ...args
-  ];
+  ], recoveryCache);
 }
 
 function positivePid(value) {
@@ -1018,21 +1024,36 @@ export function prefetchExactNpxRestore(config, env = process.env, options = {})
     throw new Error('LiveDesk cannot prefetch an exact restore without the current product version.');
   }
   const neutralCwd = prepareNeutralCwd(config?.neutralCwd);
-  const invocation = resolveNpxInvocation(
-    buildExactNpxArgs(neutralCwd, '--prefer-offline', version, ['--version']),
-    env
-  );
-  const result = (options.spawnSyncImpl || spawnSync)(
-    invocation.command,
-    invocation.args,
-    {
+  const packageSpec = `livedesk@${version}`;
+  const spawnSyncImpl = options.spawnSyncImpl || spawnSync;
+  const runPrefetch = args => {
+    const invocation = resolveNpxInvocation(args, env);
+    return spawnSyncImpl(invocation.command, invocation.args, {
       cwd: neutralCwd,
       env: buildLegacyClientUpdateNpxEnvironment(env, neutralCwd),
       encoding: 'utf8',
       timeout: options.timeoutMs ?? 120_000,
       windowsHide: true
-    }
-  );
+    });
+  };
+  let prepared = prepareExactNpxCacheRecovery({
+    args: buildExactNpxArgs(neutralCwd, '--prefer-offline', version, ['--version']),
+    env,
+    operationId: config?.operationId,
+    phase: 'restore-prefetch'
+  });
+  let result = runPrefetch(prepared.args);
+  if (!prepared.recoveryCache
+    && isInterruptedExactNpxInstallFailure(result, packageSpec, env)) {
+    prepared = prepareExactNpxCacheRecovery({
+      args: prepared.args,
+      env,
+      operationId: config?.operationId,
+      phase: 'restore-prefetch-retry',
+      force: true
+    });
+    result = runPrefetch(prepared.args);
+  }
   const output = `${result?.stdout || ''}\n${result?.stderr || ''}`.trim();
   if (result?.error || result?.status !== 0) {
     throw new Error(
@@ -1055,7 +1076,8 @@ export function prefetchExactNpxRestore(config, env = process.env, options = {})
     strategy: 'npx-exact-connected-proof',
     productVersion: version,
     agentVersion: cleanVersion(config?.currentAgentVersion),
-    preference: '--prefer-offline'
+    preference: '--prefer-offline',
+    recoveryCache: prepared.recoveryCache
   };
 }
 
@@ -1076,9 +1098,15 @@ export function spawnReplacement(version, preference, env = process.env, restart
   const neutralCwd = isLocalRestore
     ? ''
     : prepareNeutralCwd(env.LIVEDESK_UPDATE_NEUTRAL_CWD);
+  const recoveryCache = isLocalRestore
+    ? ''
+    : normalizeExactNpxRecoveryCache(env.LIVEDESK_CLIENT_UPDATE_NPX_CACHE);
   const invocation = isLocalRestore
     ? { command: process.execPath, args: [localRestoreLauncher, ...roleArgs] }
-    : resolveNpxInvocation(buildExactNpxArgs(neutralCwd, preference, version, roleArgs), env);
+    : resolveNpxInvocation(
+      buildExactNpxArgs(neutralCwd, preference, version, roleArgs, recoveryCache),
+      env
+    );
   const replacementEnv = isLocalRestore
     ? { ...env }
     : buildLegacyClientUpdateNpxEnvironment(env, neutralCwd);
@@ -1344,6 +1372,9 @@ export async function launchAndVerifyLegacyClientReplacement(
     LIVEDESK_CLIENT_UPDATE_LOCAL_LAUNCHER: kind === 'restore'
       ? String(config.localRestoreLauncher?.entryPath || '')
       : '',
+    LIVEDESK_CLIENT_UPDATE_NPX_CACHE: kind === 'restore'
+      ? String(config.npxRestore?.recoveryCache || '')
+      : '',
     LIVEDESK_CLIENT_RUNTIME_PORT: String(config.runtimePort),
     LIVEDESK_DEVICE_ID: config.deviceId,
     LIVEDESK_SKIP_BROWSER_OPEN: '1'

package/bootstrap/npm-update-cache.mjs

@@ -0,0 +1,158 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+
+const EXACT_LIVEDESK_PACKAGE_PATTERN = /^livedesk@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/;
+
+function environmentValue(env, name) {
+  const expected = String(name || '').toLowerCase();
+  const entry = Object.entries(env || {}).find(([key]) => String(key).toLowerCase() === expected);
+  return String(entry?.[1] || '').trim();
+}
+
+function safePathSegment(value, fallback = 'unknown') {
+  return String(value || '')
+    .replace(/[^A-Za-z0-9._-]/g, '_')
+    .slice(0, 100) || fallback;
+}
+
+function pathInside(root, candidate) {
+  const base = resolve(root);
+  const target = resolve(candidate);
+  return target === base || target.startsWith(`${base}${sep}`);
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function parseExactLiveDeskPackageSpec(value) {
+  const match = EXACT_LIVEDESK_PACKAGE_PATTERN.exec(String(value || '').trim());
+  return match ? { packageSpec: match[0], version: match[1] } : null;
+}
+
+export function getExactNpxInstallHash(packageSpec) {
+  return createHash('sha512').update(String(packageSpec || '')).digest('hex').slice(0, 16);
+}
+
+export function resolveNpmCacheRoot(env = process.env) {
+  const configured = environmentValue(env, 'npm_config_cache');
+  if (configured) return resolve(configured);
+  if (process.platform === 'win32') {
+    const localAppData = environmentValue(env, 'LOCALAPPDATA')
+      || join(os.homedir(), 'AppData', 'Local');
+    return resolve(localAppData, 'npm-cache');
+  }
+  return resolve(os.homedir(), '.npm');
+}
+
+export function inspectExactNpxInstall(packageSpec, env = process.env) {
+  const exact = parseExactLiveDeskPackageSpec(packageSpec);
+  if (!exact) return { state: 'not-exact-livedesk', packageSpec: '', version: '', installDir: '' };
+  const installDir = join(resolveNpmCacheRoot(env), '_npx', getExactNpxInstallHash(exact.packageSpec));
+  if (!existsSync(installDir)) {
+    return { state: 'absent', ...exact, installDir };
+  }
+  const rootManifest = readJson(join(installDir, 'package.json'));
+  const productManifest = readJson(join(installDir, 'node_modules', 'livedesk', 'package.json'));
+  const healthy = rootManifest
+    && typeof rootManifest.dependencies?.livedesk === 'string'
+    && productManifest?.name === 'livedesk'
+    && String(productManifest.version || '') === exact.version;
+  return {
+    state: healthy ? 'healthy' : 'interrupted',
+    ...exact,
+    installDir
+  };
+}
+
+export function createExactNpxRecoveryCache(operationId, phase = 'package', options = {}) {
+  const root = resolve(
+    String(options.tempDirectory || os.tmpdir()),
+    'livedesk-update-npm-cache'
+  );
+  const nonce = safePathSegment(
+    options.nonce || `${process.pid}-${Date.now()}-${randomBytes(5).toString('hex')}`,
+    String(process.pid)
+  );
+  return join(
+    root,
+    `${safePathSegment(operationId, 'operation')}-${safePathSegment(phase, 'package')}-${nonce}`
+  );
+}
+
+export function normalizeExactNpxRecoveryCache(value, options = {}) {
+  const configured = String(value || '').trim();
+  if (!configured || !isAbsolute(configured)) return '';
+  const root = resolve(
+    String(options.tempDirectory || os.tmpdir()),
+    'livedesk-update-npm-cache'
+  );
+  const candidate = resolve(configured);
+  return candidate !== root && pathInside(root, candidate) ? candidate : '';
+}
+
+export function addExactNpxRecoveryCacheArgument(args, recoveryCache) {
+  const values = Array.isArray(args) ? args.map(value => String(value)) : [];
+  if (!recoveryCache
+    || values.some(value => value === '--cache' || value.startsWith('--cache='))) {
+    return values;
+  }
+  const packageIndex = values.findIndex(value => parseExactLiveDeskPackageSpec(value));
+  if (packageIndex < 0) return values;
+  return [
+    ...values.slice(0, packageIndex),
+    '--cache',
+    recoveryCache,
+    ...values.slice(packageIndex)
+  ];
+}
+
+export function prepareExactNpxCacheRecovery({
+  args,
+  env = process.env,
+  operationId,
+  phase,
+  force = false,
+  nonce,
+  tempDirectory
+} = {}) {
+  const values = Array.isArray(args) ? args.map(value => String(value)) : [];
+  const exact = values.map(parseExactLiveDeskPackageSpec).find(Boolean);
+  if (!exact || values.some(value => value === '--cache' || value.startsWith('--cache='))) {
+    return { args: values, recoveryCache: '', recovered: false, inspection: null };
+  }
+  const inspection = inspectExactNpxInstall(exact.packageSpec, env);
+  if (!force && inspection.state !== 'interrupted') {
+    return { args: values, recoveryCache: '', recovered: false, inspection };
+  }
+  const recoveryCache = createExactNpxRecoveryCache(operationId, phase, {
+    nonce,
+    tempDirectory
+  });
+  return {
+    args: addExactNpxRecoveryCacheArgument(values, recoveryCache),
+    recoveryCache,
+    recovered: true,
+    inspection
+  };
+}
+
+export function isInterruptedExactNpxInstallFailure(result, packageSpec, env = process.env) {
+  const exact = parseExactLiveDeskPackageSpec(packageSpec);
+  if (!exact) return false;
+  const output = `${result?.error?.message || ''}\n${result?.stdout || ''}\n${result?.stderr || ''}`;
+  if (!/\bENOENT\b|Could not read package\.json/i.test(output)) return false;
+  const expectedPath = join(
+    resolveNpmCacheRoot(env),
+    '_npx',
+    getExactNpxInstallHash(exact.packageSpec),
+    'package.json'
+  ).replaceAll('\\', '/').toLowerCase();
+  return output.replaceAll('\\', '/').toLowerCase().includes(expectedPath);
+}

package/bootstrap/update-host-client.mjs

@@ -9,6 +9,61 @@ export const UPDATE_HOST_PROTOCOL_VERSION = 1;
 export const UPDATE_HOST_DEFAULT_START_TIMEOUT_MS = 8_000;
 export const UPDATE_HOST_DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
 export const UPDATE_HOST_MAX_MESSAGE_BYTES = 2 * 1024 * 1024;
+export const UPDATE_HOST_MAX_ENVIRONMENT_KEYS = 512;
+export const UPDATE_HOST_MAX_ENVIRONMENT_VALUE_BYTES = 128 * 1024;
+
+const UPDATE_HOST_ENVIRONMENT_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_()]*$/;
+
+export function isValidUpdateHostEnvironmentEntry(key, value) {
+  return UPDATE_HOST_ENVIRONMENT_KEY_PATTERN.test(String(key || ''))
+    && Buffer.byteLength(String(value ?? ''), 'utf8') <= UPDATE_HOST_MAX_ENVIRONMENT_VALUE_BYTES;
+}
+
+function updateHostEnvironmentPriority(key) {
+  const normalized = String(key || '').toUpperCase();
+  if (normalized.startsWith('LIVEDESK_')
+    || normalized.startsWith('LIVE_DESK_')
+    || normalized.startsWith('REMOTE_HUB_')) {
+    return 0;
+  }
+  if (/^(PATH|PATHEXT|SYSTEMROOT|WINDIR|COMSPEC|TEMP|TMP|TMPDIR|HOME|HOMEDRIVE|HOMEPATH|USERPROFILE|APPDATA|LOCALAPPDATA|LANG|LC_ALL|TZ|PORT)$/.test(normalized)
+    || normalized.startsWith('NPM_')
+    || normalized.startsWith('NODE_')
+    || normalized.endsWith('_PROXY')
+    || normalized.startsWith('OPENAI_')
+    || normalized.startsWith('CODEX_')) {
+    return 1;
+  }
+  return 2;
+}
+
+export function buildUpdateHostWorkerEnvironment(baseEnv = process.env, requiredEnv = {}) {
+  const requiredEntries = Object.entries(requiredEnv || {}).map(([key, value]) => [String(key), String(value ?? '')]);
+  for (const [key, value] of requiredEntries) {
+    if (!isValidUpdateHostEnvironmentEntry(key, value)) {
+      throw new Error(`invalid-required-update-host-environment-entry:${key}`);
+    }
+  }
+  if (requiredEntries.length > UPDATE_HOST_MAX_ENVIRONMENT_KEYS) {
+    throw new Error('invalid-required-update-host-environment-count');
+  }
+
+  const requiredKeys = new Set(requiredEntries.map(([key]) => key.toUpperCase()));
+  const availableBaseEntries = UPDATE_HOST_MAX_ENVIRONMENT_KEYS - requiredEntries.length;
+  const baseEntries = Object.entries(baseEnv || {})
+    .filter(([key, value]) => value != null
+      && !requiredKeys.has(String(key).toUpperCase())
+      && isValidUpdateHostEnvironmentEntry(key, value))
+    .map(([key, value]) => [String(key), String(value)])
+    .sort((left, right) => {
+      const priorityDifference = updateHostEnvironmentPriority(left[0]) - updateHostEnvironmentPriority(right[0]);
+      if (priorityDifference) return priorityDifference;
+      return left[0] < right[0] ? -1 : (left[0] > right[0] ? 1 : 0);
+    })
+    .slice(0, availableBaseEntries);
+
+  return Object.fromEntries([...baseEntries, ...requiredEntries]);
+}
 
 function normalizedStateDir(stateDir) {
   return resolve(String(stateDir || join(os.homedir(), '.livedesk')).trim());

package/bootstrap/update-host.mjs

@@ -8,15 +8,16 @@ import { dirname, isAbsolute, resolve, sep } from 'node:path';
 import { spawn } from 'node:child_process';
 import {
   getUpdateHostPaths,
+  isValidUpdateHostEnvironmentEntry,
+  UPDATE_HOST_MAX_ENVIRONMENT_KEYS,
   UPDATE_HOST_MAX_MESSAGE_BYTES,
   UPDATE_HOST_PROTOCOL_VERSION
 } from './update-host-client.mjs';
+import { prepareExactNpxCacheRecovery } from './npm-update-cache.mjs';
 
 const MAX_LOG_BYTES = 1024 * 1024;
 const MAX_ARGUMENT_COUNT = 512;
 const MAX_ARGUMENT_BYTES = 1024 * 1024;
-const MAX_ENVIRONMENT_KEYS = 512;
-const MAX_ENVIRONMENT_VALUE_BYTES = 128 * 1024;
 const ALLOWED_JOB_KINDS = new Set(['hub-update', 'client-update']);
 const TERMINAL_RESULT_STAGES = new Set(['updated', 'restored', 'failed', 'connected', 'cancelled']);
 
@@ -173,9 +174,9 @@ function validateJob(value) {
   }
   if (args.length === 0 || args.length > MAX_ARGUMENT_COUNT) throw new Error('invalid-update-host-arguments');
   if (Buffer.byteLength(JSON.stringify(args), 'utf8') > MAX_ARGUMENT_BYTES) throw new Error('update-host-arguments-too-large');
-  if (!env || Object.keys(env).length > MAX_ENVIRONMENT_KEYS) throw new Error('invalid-update-host-environment');
+  if (!env || Object.keys(env).length > UPDATE_HOST_MAX_ENVIRONMENT_KEYS) throw new Error('invalid-update-host-environment');
   for (const [key, item] of Object.entries(env)) {
-    if (!/^[A-Za-z_][A-Za-z0-9_()]*$/.test(key) || Buffer.byteLength(item, 'utf8') > MAX_ENVIRONMENT_VALUE_BYTES) {
+    if (!isValidUpdateHostEnvironmentEntry(key, item)) {
       throw new Error('invalid-update-host-environment-entry');
     }
   }
@@ -270,13 +271,26 @@ function beginHostReplacement() {
 }
 
 function startJob(value) {
-  const job = validateJob(value);
+  const validatedJob = validateJob(value);
   if (currentJob && ['accepted', 'running'].includes(currentJob.state)) {
-    if (currentJob.jobId === job.jobId && currentJob.operationId === job.operationId) return currentJob;
+    if (currentJob.jobId === validatedJob.jobId && currentJob.operationId === validatedJob.operationId) return currentJob;
     const error = new Error(`LiveDesk Update Host is busy with ${currentJob.operationId}.`);
     error.code = 'LIVEDESK_UPDATE_HOST_BUSY';
     throw error;
   }
+  const cacheRecovery = validatedJob.kind === 'client-update'
+    ? prepareExactNpxCacheRecovery({
+      args: validatedJob.args,
+      env: validatedJob.env,
+      operationId: validatedJob.operationId,
+      phase: 'target-worker'
+    })
+    : { args: validatedJob.args, recoveryCache: '', recovered: false };
+  const job = {
+    ...validatedJob,
+    args: cacheRecovery.args,
+    recoveryCache: cacheRecovery.recoveryCache
+  };
   currentJob = {
     ...job,
     state: 'accepted',
@@ -307,6 +321,9 @@ function startJob(value) {
   currentJob.startedAt = new Date().toISOString();
   currentJob.state = 'running';
   workerSpawnCount += 1;
+  if (cacheRecovery.recovered) {
+    appendLog(`job=${job.jobId} operation=${job.operationId} npm-cache-recovery=isolated reason=interrupted-exact-npx-install`);
+  }
   appendLog(`job=${job.jobId} kind=${job.kind} operation=${job.operationId} state=running workerPid=${currentJob.workerPid}`);
   publishStatus();
   child.once('error', error => finishJob(currentJob, 'failed', { error: error.message }));

package/hub/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",

package/hub/src/http/hub-ui-session.js

@@ -0,0 +1,119 @@
+import crypto from 'node:crypto';
+
+export const HUB_UI_SESSION_COOKIE = 'livedesk_hub_ui';
+export const HUB_UI_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
+
+const SAFE_HTTP_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+function secureEqual(left, right) {
+  const leftBuffer = Buffer.from(String(left || ''), 'utf8');
+  const rightBuffer = Buffer.from(String(right || ''), 'utf8');
+  return leftBuffer.length === rightBuffer.length
+    && leftBuffer.length > 0
+    && crypto.timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+function parseCookies(value) {
+  const result = new Map();
+  for (const part of String(value || '').split(';')) {
+    const separator = part.indexOf('=');
+    if (separator <= 0) continue;
+    const key = part.slice(0, separator).trim();
+    const rawValue = part.slice(separator + 1).trim();
+    if (!key) continue;
+    try {
+      result.set(key, decodeURIComponent(rawValue));
+    } catch {
+      result.set(key, rawValue);
+    }
+  }
+  return result;
+}
+
+function randomToken() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+export function createHubUiSessionAuthority({
+  ttlMs = HUB_UI_SESSION_TTL_MS,
+  maxSessions = 32,
+  now = () => Date.now()
+} = {}) {
+  const sessions = new Map();
+
+  function purgeExpired() {
+    const current = now();
+    for (const [sessionId, session] of sessions) {
+      if (session.expiresAt <= current) sessions.delete(sessionId);
+    }
+    while (sessions.size >= maxSessions) {
+      sessions.delete(sessions.keys().next().value);
+    }
+  }
+
+  function issue(userId) {
+    const normalizedUserId = String(userId || '').trim();
+    if (!normalizedUserId) throw new Error('hub-ui-session-user-required');
+    purgeExpired();
+    const sessionId = randomToken();
+    const csrfToken = randomToken();
+    const expiresAt = now() + ttlMs;
+    sessions.set(sessionId, { userId: normalizedUserId, csrfToken, expiresAt });
+    return { sessionId, csrfToken, expiresAt };
+  }
+
+  function authorize(req, currentUserId, {
+    requireCsrf = !SAFE_HTTP_METHODS.has(String(req.method || 'GET').toUpperCase())
+  } = {}) {
+    purgeExpired();
+    const sessionId = parseCookies(req.headers?.cookie).get(HUB_UI_SESSION_COOKIE) || '';
+    if (!sessionId) {
+      return { ok: false, status: 401, error: 'hub-ui-session-required' };
+    }
+    const session = sessions.get(sessionId);
+    if (!session) {
+      return { ok: false, status: 401, error: 'hub-ui-session-expired' };
+    }
+    const normalizedUserId = String(currentUserId || '').trim();
+    if (!normalizedUserId || session.userId !== normalizedUserId) {
+      sessions.delete(sessionId);
+      return { ok: false, status: 403, error: 'hub-ui-session-account-mismatch' };
+    }
+    if (requireCsrf && !secureEqual(req.headers?.['x-livedesk-csrf'], session.csrfToken)) {
+      return { ok: false, status: 403, error: 'hub-ui-csrf-invalid' };
+    }
+    return { ok: true, sessionId, userId: session.userId, expiresAt: session.expiresAt };
+  }
+
+  return {
+    issue,
+    authorize,
+    revokeAll() {
+      sessions.clear();
+    },
+    sessionCount: () => sessions.size
+  };
+}
+
+export function serializeHubUiSessionCookie(sessionId, expiresAt, { secure = false } = {}) {
+  const maxAgeSeconds = Math.max(1, Math.floor((Number(expiresAt || 0) - Date.now()) / 1000));
+  return [
+    `${HUB_UI_SESSION_COOKIE}=${encodeURIComponent(String(sessionId || ''))}`,
+    'Path=/',
+    'HttpOnly',
+    'SameSite=Strict',
+    `Max-Age=${maxAgeSeconds}`,
+    secure ? 'Secure' : ''
+  ].filter(Boolean).join('; ');
+}
+
+export function clearHubUiSessionCookie({ secure = false } = {}) {
+  return [
+    `${HUB_UI_SESSION_COOKIE}=`,
+    'Path=/',
+    'HttpOnly',
+    'SameSite=Strict',
+    'Max-Age=0',
+    secure ? 'Secure' : ''
+  ].filter(Boolean).join('; ');
+}