@livedesk/client 0.1.230 → 0.1.232

package/bin/livedesk-client.js

@@ -4171,14 +4171,21 @@ export async function resolveManagerFromSupabase(supabase, options = {}) {
     if (options.signal?.aborted) {
         throw createHubDiscoveryError('hub-registry-aborted', 'LiveDesk Hub registry lookup was cancelled.');
     }
-    const session = await refreshSessionIfNeeded(supabase);
+    const fetchImpl = explicitAuthenticatedFetch(supabase, options.fetchImpl);
+    const supplied = normalizeRuntimeAuthSession(options.session, { requireRefreshToken: true });
+    const suppliedExpiresAt = Number(supplied.session?.expires_at || 0);
+    const suppliedFresh = supplied.ok && (suppliedExpiresAt <= 0
+        || suppliedExpiresAt - Math.floor(Date.now() / 1000) > SESSION_REFRESH_SKEW_SECONDS);
+    let session = suppliedFresh ? supplied.session : await refreshSessionIfNeeded(supabase);
     if (!session?.access_token) {
         throw createHubDiscoveryError('hub-registry-auth-required', 'Sign in again before finding the LiveDesk Hub.');
     }
+    if (!fetchImpl && suppliedFresh) {
+        session = await activateSupabaseSession(supabase, session);
+    }
     if (options.signal?.aborted) {
         throw createHubDiscoveryError('hub-registry-aborted', 'LiveDesk Hub registry lookup was cancelled.');
     }
-    const fetchImpl = explicitAuthenticatedFetch(supabase, options.fetchImpl);
     let data;
     if (fetchImpl) {
         const payload = await fetchAuthenticatedSupabaseJson(session, 'livedesk_remote_host_targets', {
@@ -4297,6 +4304,7 @@ export async function waitForManagerFromSupabase(supabase, options = {}) {
     let lastMessage = '';
     let wakeListener = null;
     let initialError = options.initialError || null;
+    let discoverySession = options.session || null;
     console.log('Waiting for a LiveDesk Hub. LiveDesk is listening for Hub-online events with adaptive registry retries as a fallback.');
     try {
         while (true) {
@@ -4306,7 +4314,16 @@ export async function waitForManagerFromSupabase(supabase, options = {}) {
             if (!wakeListener) {
                 try {
                     wakeListener = await createWakeListener({
-                        getAccessToken: async () => (await refreshSessionIfNeeded(supabase))?.access_token || ''
+                        getAccessToken: async () => {
+                            const normalized = normalizeRuntimeAuthSession(discoverySession, { requireRefreshToken: true });
+                            const expiresAt = Number(normalized.session?.expires_at || 0);
+                            if (normalized.ok && (expiresAt <= 0
+                                || expiresAt - Math.floor(Date.now() / 1000) > SESSION_REFRESH_SKEW_SECONDS)) {
+                                return normalized.session.access_token;
+                            }
+                            discoverySession = await refreshSessionIfNeeded(supabase);
+                            return discoverySession?.access_token || '';
+                        }
                     });
                 } catch (error) {
                     if (attempts === 0) {
@@ -4325,6 +4342,7 @@ export async function waitForManagerFromSupabase(supabase, options = {}) {
                     signal => resolveManagerFromSupabase(supabase, {
                         allowRelayFallback: options.allowRelayFallback === true,
                         probeEndpoint: options.probeEndpoint,
+                        session: discoverySession,
                         signal
                     }),
                     {
@@ -4495,6 +4513,7 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null, get
                         }
                         return await resolveManagerFromSupabase(supabase, {
                             allowRelayFallback,
+                            session,
                             signal
                         });
                     }
@@ -4527,6 +4546,7 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null, get
             if (!resolved) {
                 resolved = await waitForManagerFromSupabase(supabase, {
                     allowRelayFallback,
+                    session,
                     initialError: initialDiscoveryError,
                     shouldStop: () => Boolean(roleRestartRequest?.role)
                 });

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "@livedesk/client",
-  "version": "0.1.230",
-  "description": "LiveDesk local remote client",
-  "type": "module",
-  "bin": {
-    "client": "bin/livedesk-client.js",
-    "livedesk-client": "bin/livedesk-client.js",
-    "livedesk-client-node": "bin/livedesk-client-node.js",
-    "livedesk-client-fast": "bin/livedesk-client-fast.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "tests/",
-    "README.md",
-    "THIRD_PARTY_NOTICES.md"
-  ],
-  "scripts": {
-    "check": "node --check bin/client-version.js && node --check bin/livedesk-client.js && node --check bin/livedesk-client-node.js && node --check bin/livedesk-client-update-bootstrap.cjs && node --check bin/livedesk-client-fast.js",
-    "test:version": "node --test tests/client-version.test.mjs",
-    "pack:dry": "npm pack --dry-run",
-    "prepublishOnly": "node ../../scripts/livedesk-release-git-gate.mjs"
-  },
-  "keywords": [
-    "livedesk",
-    "remote",
-    "agent",
-    "local",
-    "desktop"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@ffmpeg-installer/ffmpeg": "^1.1.0",
-    "ffmpeg-static": "^5.3.0",
-    "@livedesk/runtime-core": "0.1.4",
-    "@supabase/supabase-js": "^2.110.0",
-    "node-screenshots": "^0.2.8",
-    "ws": "^8.18.3"
-  },
-  "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.430",
-    "@livedesk/fast-osx-arm64": "0.1.430",
-    "@livedesk/fast-osx-x64": "0.1.430",
-    "@livedesk/fast-win-x64": "0.1.430"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@livedesk/client",
+  "version": "0.1.232",
+  "description": "LiveDesk local remote client",
+  "type": "module",
+  "bin": {
+    "client": "bin/livedesk-client.js",
+    "livedesk-client": "bin/livedesk-client.js",
+    "livedesk-client-node": "bin/livedesk-client-node.js",
+    "livedesk-client-fast": "bin/livedesk-client-fast.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "tests/",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "check": "node --check bin/client-version.js && node --check bin/livedesk-client.js && node --check bin/livedesk-client-node.js && node --check bin/livedesk-client-update-bootstrap.cjs && node --check bin/livedesk-client-fast.js",
+    "test:version": "node --test tests/client-version.test.mjs",
+    "pack:dry": "npm pack --dry-run",
+    "prepublishOnly": "node ../../scripts/livedesk-release-git-gate.mjs"
+  },
+  "keywords": [
+    "livedesk",
+    "remote",
+    "agent",
+    "local",
+    "desktop"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "ffmpeg-static": "^5.3.0",
+    "@livedesk/runtime-core": "0.1.4",
+    "@supabase/supabase-js": "^2.110.0",
+    "node-screenshots": "^0.2.8",
+    "ws": "^8.18.3"
+  },
+  "optionalDependencies": {
+    "@livedesk/fast-linux-x64": "0.1.431",
+    "@livedesk/fast-osx-arm64": "0.1.431",
+    "@livedesk/fast-osx-x64": "0.1.431",
+    "@livedesk/fast-win-x64": "0.1.431"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/security/device-credential-store.js

@@ -1,190 +1,219 @@
-import crypto from 'node:crypto';
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { decodeCanonicalBase64Url } from '@livedesk/runtime-core';
-import { createOsSecretStore, OS_SECRET_REFERENCE } from '@livedesk/runtime-core/os-secret-store';
-
-const STORE_VERSION = 1;
-
-function credentialError(code) {
-  const error = new Error(code);
-  error.code = code;
-  return error;
-}
-
-function clean(value, maximum = 512) {
-  return String(value || '').replace(/[\0\r\n]/g, '').trim().slice(0, maximum);
-}
-
-function atomicPrivateJson(filePath, value) {
-  mkdirSync(path.dirname(filePath), { recursive: true });
-  const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-  renameSync(temporary, filePath);
-}
-
-function loadJson(filePath) {
-  try {
-    const value = JSON.parse(readFileSync(filePath, 'utf8'));
-    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
-  } catch {
-    return null;
-  }
-}
-
-function requirePrivateKey(value) {
-  const der = decodeCanonicalBase64Url(value, 100, 512);
-  let key;
-  try {
-    key = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
-  } catch {
-    throw credentialError('device-private-key-invalid');
-  }
-  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
-    throw credentialError('device-private-key-invalid');
-  }
-  return key;
-}
-
-function parseCredential(credential) {
-  const text = String(credential || '');
-  const parts = text.split('.');
-  if (parts.length !== 2 || text.length > 8192) throw credentialError('device-credential-invalid');
-  const payloadBytes = decodeCanonicalBase64Url(parts[0], 32, 4096);
-  const signature = decodeCanonicalBase64Url(parts[1], 64, 64);
-  let payload;
-  try {
-    payload = JSON.parse(payloadBytes.toString('utf8'));
-  } catch {
-    throw credentialError('device-credential-invalid');
-  }
-  if (!payload || Number(payload.version) !== 1) throw credentialError('device-credential-invalid');
-  const hubPublicDer = decodeCanonicalBase64Url(payload.hubPublicKey, 80, 160);
-  let hubPublicKey;
-  try {
-    hubPublicKey = crypto.createPublicKey({ key: hubPublicDer, format: 'der', type: 'spki' });
-  } catch {
-    throw credentialError('device-credential-invalid');
-  }
-  if (hubPublicKey.asymmetricKeyType !== 'ec'
-    || hubPublicKey.asymmetricKeyDetails?.namedCurve !== 'prime256v1'
-    || !crypto.verify('sha256', Buffer.from(parts[0], 'utf8'), { key: hubPublicKey, dsaEncoding: 'ieee-p1363' }, signature)) {
-    throw credentialError('device-credential-signature-invalid');
-  }
-  const normalized = {
-    serial: clean(payload.serial, 128),
-    accountId: clean(payload.accountId, 128),
-    hubId: clean(payload.hubId, 128),
-    deviceId: clean(payload.deviceId, 128),
-    devicePublicKey: clean(payload.devicePublicKey, 512),
-    hubPublicKey: hubPublicDer.toString('base64url'),
-    issuedAt: Number(payload.issuedAt),
-    expiresAt: Number(payload.expiresAt)
-  };
-  if (!normalized.serial || !normalized.accountId || !normalized.hubId || !normalized.deviceId
-    || !Number.isSafeInteger(normalized.issuedAt) || !Number.isSafeInteger(normalized.expiresAt)
-    || normalized.expiresAt <= Date.now()) {
-    throw credentialError('device-credential-expired');
-  }
-  return { text, payloadText: parts[0], payload: normalized, hubPublicKey };
-}
-
-export function createClientDeviceCredentialStore({
-  filePath = String(process.env.LIVEDESK_DEVICE_CREDENTIAL_PATH || '').trim()
-    || path.join(os.homedir(), '.livedesk-client', 'device-credential-v1.json'),
-  deviceId
-} = {}) {
-  const normalizedDeviceId = clean(deviceId, 128);
-  if (!normalizedDeviceId) throw credentialError('device-id-required');
-  const privateKeyStore = createOsSecretStore({
-    service: 'LiveDesk',
-    account: `client-device-private-key:${normalizedDeviceId}`,
-    dataDir: path.dirname(filePath)
-  });
-  let state = loadJson(filePath);
-  let privateKey;
-  let publicKey;
-  if (state) {
-    if (Number(state.version) !== STORE_VERSION || state.deviceId !== normalizedDeviceId) throw credentialError('device-key-state-invalid');
-    const plaintextPrivateKey = clean(state.privateKey, 1024);
-    if (plaintextPrivateKey) {
-      if (!privateKeyStore.write(plaintextPrivateKey)) throw credentialError('device-private-key-migration-failed');
-      state = { ...state, privateKeyRef: OS_SECRET_REFERENCE, updatedAt: new Date().toISOString() };
-      delete state.privateKey;
-      atomicPrivateJson(filePath, state);
-    }
-    if (state.privateKeyRef !== OS_SECRET_REFERENCE) throw credentialError('device-private-key-reference-invalid');
-    const privateKeyText = privateKeyStore.read();
-    if (!privateKeyText) throw credentialError('device-private-key-secure-store-unavailable');
-    privateKey = requirePrivateKey(privateKeyText);
-    publicKey = crypto.createPublicKey(privateKey);
-    const publicText = publicKey.export({ format: 'der', type: 'spki' }).toString('base64url');
-    if (publicText !== state.publicKey) throw credentialError('device-key-mismatch');
-  } else {
-    const generated = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
-    privateKey = generated.privateKey;
-    publicKey = generated.publicKey;
-    const privateKeyText = privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64url');
-    if (!privateKeyStore.write(privateKeyText)) throw credentialError('device-private-key-secure-store-unavailable');
-    state = {
-      version: STORE_VERSION,
-      deviceId: normalizedDeviceId,
-      publicKey: publicKey.export({ format: 'der', type: 'spki' }).toString('base64url'),
-      privateKeyRef: OS_SECRET_REFERENCE,
-      credential: '',
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString()
-    };
-    atomicPrivateJson(filePath, state);
-  }
-
-  function saveCredential(credential) {
-    const parsed = parseCredential(credential);
-    if (parsed.payload.deviceId !== normalizedDeviceId || parsed.payload.devicePublicKey !== state.publicKey) {
-      throw credentialError('device-credential-binding-invalid');
-    }
-    state.credential = parsed.text;
-    state.accountId = parsed.payload.accountId;
-    state.hubId = parsed.payload.hubId;
-    state.updatedAt = new Date().toISOString();
-    atomicPrivateJson(filePath, state);
-    return parsed;
-  }
-
-  function readCredential() {
-    if (!state.credential) return null;
-    try {
-      const parsed = parseCredential(state.credential);
-      if (parsed.payload.deviceId !== normalizedDeviceId || parsed.payload.devicePublicKey !== state.publicKey) return null;
-      return parsed;
-    } catch {
-      return null;
-    }
-  }
-
-  function clearCredential() {
-    state.credential = '';
-    state.accountId = '';
-    state.hubId = '';
-    state.updatedAt = new Date().toISOString();
-    atomicPrivateJson(filePath, state);
-  }
-
-  return Object.freeze({
-    filePath,
-    deviceId: normalizedDeviceId,
-    publicKey: state.publicKey,
-    privateKey,
-    sign(message) {
-      return crypto.sign('sha256', Buffer.from(String(message || ''), 'utf8'), {
-        key: privateKey,
-        dsaEncoding: 'ieee-p1363'
-      }).toString('base64url');
-    },
-    readCredential,
-    saveCredential,
-    clearCredential,
-    parseCredential
-  });
-}
+import crypto from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { decodeCanonicalBase64Url } from '@livedesk/runtime-core';
+import { createOsSecretStore, OS_SECRET_REFERENCE } from '@livedesk/runtime-core/os-secret-store';
+
+const STORE_VERSION = 1;
+
+function credentialError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function clean(value, maximum = 512) {
+  return String(value || '').replace(/[\0\r\n]/g, '').trim().slice(0, maximum);
+}
+
+function credentialRoot() {
+  const configured = clean(process.env.LIVEDESK_CLIENT_CREDENTIAL_ROOT, 4096);
+  return configured ? path.resolve(configured) : path.join(os.homedir(), '.livedesk-client');
+}
+
+function defaultCredentialPath(deviceId) {
+  const deviceHash = crypto.createHash('sha256').update(String(deviceId), 'utf8').digest('hex');
+  return path.join(credentialRoot(), 'security', 'device-credentials', `${deviceHash}.json`);
+}
+
+function legacyCredentialPath() {
+  return path.join(credentialRoot(), 'device-credential-v1.json');
+}
+
+function atomicPrivateJson(filePath, value) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, filePath);
+}
+
+function loadJson(filePath) {
+  try {
+    const value = JSON.parse(readFileSync(filePath, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function requirePrivateKey(value) {
+  const der = decodeCanonicalBase64Url(value, 100, 512);
+  let key;
+  try {
+    key = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  } catch {
+    throw credentialError('device-private-key-invalid');
+  }
+  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
+    throw credentialError('device-private-key-invalid');
+  }
+  return key;
+}
+
+function parseCredential(credential) {
+  const text = String(credential || '');
+  const parts = text.split('.');
+  if (parts.length !== 2 || text.length > 8192) throw credentialError('device-credential-invalid');
+  const payloadBytes = decodeCanonicalBase64Url(parts[0], 32, 4096);
+  const signature = decodeCanonicalBase64Url(parts[1], 64, 64);
+  let payload;
+  try {
+    payload = JSON.parse(payloadBytes.toString('utf8'));
+  } catch {
+    throw credentialError('device-credential-invalid');
+  }
+  if (!payload || Number(payload.version) !== 1) throw credentialError('device-credential-invalid');
+  const hubPublicDer = decodeCanonicalBase64Url(payload.hubPublicKey, 80, 160);
+  let hubPublicKey;
+  try {
+    hubPublicKey = crypto.createPublicKey({ key: hubPublicDer, format: 'der', type: 'spki' });
+  } catch {
+    throw credentialError('device-credential-invalid');
+  }
+  if (hubPublicKey.asymmetricKeyType !== 'ec'
+    || hubPublicKey.asymmetricKeyDetails?.namedCurve !== 'prime256v1'
+    || !crypto.verify('sha256', Buffer.from(parts[0], 'utf8'), { key: hubPublicKey, dsaEncoding: 'ieee-p1363' }, signature)) {
+    throw credentialError('device-credential-signature-invalid');
+  }
+  const normalized = {
+    serial: clean(payload.serial, 128),
+    accountId: clean(payload.accountId, 128),
+    hubId: clean(payload.hubId, 128),
+    deviceId: clean(payload.deviceId, 128),
+    devicePublicKey: clean(payload.devicePublicKey, 512),
+    hubPublicKey: hubPublicDer.toString('base64url'),
+    issuedAt: Number(payload.issuedAt),
+    expiresAt: Number(payload.expiresAt)
+  };
+  if (!normalized.serial || !normalized.accountId || !normalized.hubId || !normalized.deviceId
+    || !Number.isSafeInteger(normalized.issuedAt) || !Number.isSafeInteger(normalized.expiresAt)
+    || normalized.expiresAt <= Date.now()) {
+    throw credentialError('device-credential-expired');
+  }
+  return { text, payloadText: parts[0], payload: normalized, hubPublicKey };
+}
+
+export function createClientDeviceCredentialStore({
+  filePath = String(process.env.LIVEDESK_DEVICE_CREDENTIAL_PATH || '').trim(),
+  deviceId
+} = {}) {
+  const normalizedDeviceId = clean(deviceId, 128);
+  if (!normalizedDeviceId) throw credentialError('device-id-required');
+  const configuredPath = clean(filePath, 4096);
+  const resolvedFilePath = configuredPath
+    ? path.resolve(configuredPath)
+    : defaultCredentialPath(normalizedDeviceId);
+  const privateKeyStore = createOsSecretStore({
+    service: 'LiveDesk',
+    account: `client-device-private-key:${normalizedDeviceId}`,
+    dataDir: path.dirname(resolvedFilePath)
+  });
+  let state = loadJson(resolvedFilePath);
+  let migratedLegacy = false;
+  if (!state && !configuredPath && !existsSync(resolvedFilePath)) {
+    const legacyState = loadJson(legacyCredentialPath());
+    if (Number(legacyState?.version) === STORE_VERSION && legacyState?.deviceId === normalizedDeviceId) {
+      state = legacyState;
+      migratedLegacy = true;
+    }
+  }
+  let privateKey;
+  let publicKey;
+  if (state) {
+    if (Number(state.version) !== STORE_VERSION || state.deviceId !== normalizedDeviceId) throw credentialError('device-key-state-invalid');
+    const plaintextPrivateKey = clean(state.privateKey, 1024);
+    if (plaintextPrivateKey) {
+      if (!privateKeyStore.write(plaintextPrivateKey)) throw credentialError('device-private-key-migration-failed');
+      state = { ...state, privateKeyRef: OS_SECRET_REFERENCE, updatedAt: new Date().toISOString() };
+      delete state.privateKey;
+      atomicPrivateJson(resolvedFilePath, state);
+    }
+    if (state.privateKeyRef !== OS_SECRET_REFERENCE) throw credentialError('device-private-key-reference-invalid');
+    const privateKeyText = privateKeyStore.read();
+    if (!privateKeyText) throw credentialError('device-private-key-secure-store-unavailable');
+    privateKey = requirePrivateKey(privateKeyText);
+    publicKey = crypto.createPublicKey(privateKey);
+    const publicText = publicKey.export({ format: 'der', type: 'spki' }).toString('base64url');
+    if (publicText !== state.publicKey) throw credentialError('device-key-mismatch');
+    if (migratedLegacy) {
+      atomicPrivateJson(resolvedFilePath, state);
+      try { rmSync(legacyCredentialPath(), { force: true }); } catch {}
+    }
+  } else {
+    const generated = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    privateKey = generated.privateKey;
+    publicKey = generated.publicKey;
+    const privateKeyText = privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64url');
+    if (!privateKeyStore.write(privateKeyText)) throw credentialError('device-private-key-secure-store-unavailable');
+    state = {
+      version: STORE_VERSION,
+      deviceId: normalizedDeviceId,
+      publicKey: publicKey.export({ format: 'der', type: 'spki' }).toString('base64url'),
+      privateKeyRef: OS_SECRET_REFERENCE,
+      credential: '',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    };
+    atomicPrivateJson(resolvedFilePath, state);
+  }
+
+  function saveCredential(credential) {
+    const parsed = parseCredential(credential);
+    if (parsed.payload.deviceId !== normalizedDeviceId || parsed.payload.devicePublicKey !== state.publicKey) {
+      throw credentialError('device-credential-binding-invalid');
+    }
+    state.credential = parsed.text;
+    state.accountId = parsed.payload.accountId;
+    state.hubId = parsed.payload.hubId;
+    state.updatedAt = new Date().toISOString();
+    atomicPrivateJson(resolvedFilePath, state);
+    return parsed;
+  }
+
+  function readCredential() {
+    if (!state.credential) return null;
+    try {
+      const parsed = parseCredential(state.credential);
+      if (parsed.payload.deviceId !== normalizedDeviceId || parsed.payload.devicePublicKey !== state.publicKey) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  function clearCredential() {
+    state.credential = '';
+    state.accountId = '';
+    state.hubId = '';
+    state.updatedAt = new Date().toISOString();
+    atomicPrivateJson(resolvedFilePath, state);
+  }
+
+  return Object.freeze({
+    filePath: resolvedFilePath,
+    deviceId: normalizedDeviceId,
+    publicKey: state.publicKey,
+    privateKey,
+    sign(message) {
+      return crypto.sign('sha256', Buffer.from(String(message || ''), 'utf8'), {
+        key: privateKey,
+        dsaEncoding: 'ieee-p1363'
+      }).toString('base64url');
+    },
+    readCredential,
+    saveCredential,
+    clearCredential,
+    parseCredential
+  });
+}