@huaqiu/dsh-auth 0.3.15 → 0.3.17

package/lib/index.mjs

@@ -24,10 +24,10 @@ import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
 *   3. persisted file — node-side `~/.dsh/auth/session.json`, written on every set
 *   4. null           → tools return needs_auth
 */
-let _log = null;
-function log$1() {
-	if (_log === null) _log = getLogger("dsh-auth");
-	return _log;
+let _log$1 = null;
+function log$2() {
+	if (_log$1 === null) _log$1 = getLogger("dsh-auth");
+	return _log$1;
 }
 /**
 * Resolve the effective config: overlay `config` (highest) > env (safety net
@@ -38,6 +38,7 @@ function resolveHostConfig(config, env = process.env) {
 	const baseUrl = config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? "";
 	const hostAuthPath = config?.hostAuthPath ?? env.HQ_EDGE_AUTH_PATH ?? "/api/v1/auth/token";
 	const hostLoginPath = config?.hostLoginPath ?? env.HQ_EDGE_LOGIN_PATH ?? "/api/v1/auth/login";
+	const hostLogoutPath = config?.hostLogoutPath ?? env.HQ_EDGE_LOGOUT_PATH ?? "/api/v1/auth/logout";
 	const ttlRaw = config?.hostSessionTtlSeconds ?? env.HQ_EDGE_HOST_TTL_SECONDS;
 	let ttl = 300;
 	if (typeof ttlRaw === "number" && Number.isFinite(ttlRaw) && ttlRaw > 0) ttl = ttlRaw;
@@ -56,6 +57,7 @@ function resolveHostConfig(config, env = process.env) {
 		hqEdgeBaseUrl: baseUrl,
 		hostAuthPath,
 		hostLoginPath,
+		hostLogoutPath,
 		hostSessionTtlSeconds: ttl,
 		validationTtlSeconds
 	};
@@ -102,7 +104,7 @@ var HostSessionResolver = class {
 			status = res.status;
 			if (res.ok) info = normalizeHostUser(await res.json());
 		} catch (err) {
-			log$1().warn("host session fetch failed", {
+			log$2().warn("host session fetch failed", {
 				url,
 				error: String(err)
 			});
@@ -113,7 +115,7 @@ var HostSessionResolver = class {
 				info,
 				fetchedAt: now
 			};
-			log$1().debug("host session resolved", {
+			log$2().debug("host session resolved", {
 				url,
 				status,
 				userId: info.id,
@@ -123,7 +125,7 @@ var HostSessionResolver = class {
 			return info;
 		}
 		this.cache = null;
-		log$1().info("no usable host session", {
+		log$2().info("no usable host session", {
 			url,
 			status,
 			parsed: info !== null,
@@ -323,6 +325,12 @@ var TokenValidator = class {
 const PERSIST_FILE = "session.json";
 const PERSIST_DIR = () => dshHomePath("auth");
 /**
+* Bounded wait for the host to confirm a logout. Shorter than the login wait
+* (which must cover a human completing the EDA dialog): logout is a host-side
+* operation, so a confirmation that takes longer than this means it failed.
+*/
+const LOGOUT_WAIT_MS = 3e4;
+/**
 * Returns the persisted session, or null if absent/unreadable. Best-effort: a
 * corrupt or unreadable file is treated as "no session" rather than thrown.
 */
@@ -369,6 +377,7 @@ var InMemoryHuaqiuAuthService = class {
 	validator;
 	doFetch;
 	hostLoginPath;
+	hostLogoutPath;
 	/** Bound on the host login RPC (user must complete the EDA dialog). */
 	loginWaitMs;
 	/**
@@ -389,6 +398,7 @@ var InMemoryHuaqiuAuthService = class {
 		this.doFetch = opts?.fetchImpl ?? globalThis.fetch.bind(globalThis);
 		this.host = new HostSessionResolver(resolved.hqEdgeBaseUrl ?? "", resolved.hostAuthPath ?? "/api/v1/auth/token", (resolved.hostSessionTtlSeconds ?? 300) * 1e3, this.doFetch);
 		this.hostLoginPath = resolved.hostLoginPath ?? "/api/v1/auth/login";
+		this.hostLogoutPath = resolved.hostLogoutPath ?? "/api/v1/auth/logout";
 		this.loginWaitMs = 3e5;
 		this.validator = new TokenValidator({
 			ttlMs: (resolved.validationTtlSeconds ?? 60) * 1e3,
@@ -424,7 +434,22 @@ var InMemoryHuaqiuAuthService = class {
 			this.validator.invalidate();
 			this.emit();
 		},
-		logout: async () => this.invalidate(),
+		logout: async () => {
+			if (!this.host.enabled) {
+				this.invalidate();
+				return;
+			}
+			const res = await this.doFetch(`${this.host.baseUrl}${this.hostLogoutPath}`, {
+				method: "POST",
+				headers: { accept: "application/json" },
+				signal: AbortSignal.timeout(LOGOUT_WAIT_MS)
+			});
+			if (!res.ok) throw new Error(`host logout not completed: HTTP ${res.status}`);
+			this.host.clear();
+			this.stale = true;
+			this.validator.invalidate();
+			this.emit();
+		},
 		validate: () => this.validateInternal(),
 		invalidate: () => this.markStale(),
 		onAuthStateChanged: (listener) => this.on(listener)
@@ -576,6 +601,43 @@ function toUserInfo(host) {
 }
 //#endregion
 //#region src/routes.ts
+let _log = null;
+function log$1() {
+	if (_log === null) _log = getLogger("dsh-auth");
+	return _log;
+}
+/**
+* eda.cn user-profile endpoint, reached with the access token as `X-token`
+* (the same endpoint hq-eda-ai's `/api/middleware/getUserInfo` proxies).
+* Returns `{ code: 200000, result: { id, nickname, headimage, phone, username } }`.
+*/
+const EDA_USER_INFO_URL = "https://www.eda.cn/api/chiplet/u/base/get";
+/** Fetch the eda.cn profile for a token. Null on any failure (UI degrades). */
+async function fetchEdaUserProfile(token, doFetch = globalThis.fetch.bind(globalThis)) {
+	try {
+		const res = await doFetch(EDA_USER_INFO_URL, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"X-token": token
+			},
+			body: "{}"
+		});
+		if (!res.ok) return null;
+		const body = await res.json();
+		if (body.code !== 2e5 || !body.result) return null;
+		const r = body.result;
+		return {
+			...typeof r.nickname === "string" && r.nickname ? { nickname: r.nickname } : {},
+			...typeof r.headimage === "string" && r.headimage ? { headimage: r.headimage } : {},
+			...typeof r.phone === "string" && r.phone ? { phone: r.phone } : {},
+			...typeof r.username === "string" && r.username ? { username: r.username } : {}
+		};
+	} catch (err) {
+		log$1().warn("fetchEdaUserProfile failed", { error: String(err?.message || err) });
+		return null;
+	}
+}
 const AUTH_ROUTE_PREFIX = "/api/v1/huaqiu/auth";
 function sendJson(res, status, body) {
 	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
@@ -619,7 +681,7 @@ function createAuthHandler(service) {
 				return;
 			}
 			if (req.method === "POST" && pathname === `/api/v1/huaqiu/auth/logout`) {
-				service.invalidate();
+				await service.auth.logout();
 				sendJson(res, 200, { ok: true });
 				return;
 			}
@@ -635,6 +697,15 @@ function createAuthHandler(service) {
 				sendJson(res, 200, { hostMode: service.hostMode });
 				return;
 			}
+			if (req.method === "GET" && pathname === `/api/v1/huaqiu/auth/user-info`) {
+				const token = await service.auth.getAccessToken();
+				if (!token) {
+					sendJson(res, 200, { userInfo: null });
+					return;
+				}
+				sendJson(res, 200, { userInfo: await fetchEdaUserProfile(token) });
+				return;
+			}
 			if (req.method === "POST" && pathname === `/api/v1/huaqiu/auth/login`) {
 				await service.auth.login();
 				const user = await service.auth.getUserInfo();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-auth",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.0",
-    "@huaqiu/dsh-plugin-log": "0.3.15"
+    "@huaqiu/dsh-plugin-log": "0.3.17"
   },
   "files": [
     "lib",

package/src/client/auth-state.ts

@@ -22,6 +22,11 @@ export interface AuthState {
   token?: string
   /** Bound mobile number, forwarded to the profile page as `phone=`. */
   phone?: string
+  /**
+   * Rich eda.cn profile fetched in host mode (host session carries only
+   * {token, userId}): nickname + headimage, merged above the host session.
+   */
+  profile?: { nickname?: string; headimage?: string }
 }
 
 /** Snapshot for one credential payload (`null` = logged out). */
@@ -76,6 +81,20 @@ export function subscribeAuth(callback: () => void): () => void {
   return () => listeners.delete(callback)
 }
 
+/**
+ * Merge the rich eda.cn profile (nickname + headimage) into the store —
+ * sidebar components call this after `auth.getUserProfile()` in host mode.
+ * The trigger then renders the real name/photo instead of the bare HQ icon.
+ */
+export function setProfile(profile: { nickname?: string; headimage?: string } | null | undefined): void {
+  setState({ ...state, profile: profile ?? undefined })
+}
+
+/** Current profile (nickname + headimage) resolved from the host, if any. */
+export function getProfile(): { nickname?: string; headimage?: string } | undefined {
+  return state.profile
+}
+
 /** Register the node re-sync hook (wired in apply(); called by the login card on mount). */
 export function registerAuthSync(fn: () => void): void {
   syncNow = fn

package/src/client/client.ts

@@ -31,7 +31,20 @@ export interface AuthClient {
     isHostMode(): boolean
     getAccessToken(): Promise<string | null>
     getUserInfo(): Promise<AuthTokenPayload | null>
+    /**
+     * Rich eda.cn profile (nickname + headimage) for the current token. The
+     * node half resolves the token and calls eda.cn — used by the sidebar in
+     * host mode when the host session carries only {token, userId} (e.g.
+     * kicad). Null on failure; the UI degrades to the HQ icon.
+     */
+    getUserProfile(): Promise<{ nickname?: string; headimage?: string } | null>
     login(options?: LoginOptions): Promise<void>
+    /**
+     * Request logout. In host mode this asks the EDA host (through the node
+     * half → hq-edge → TriggerLogout) to log out; it never declares the
+     * operator logged out locally. Throws when the request is rejected, so
+     * the UI keeps showing the authenticated state.
+     */
     logout(): Promise<void>
     onAuthStateChanged(listener: (info: AuthTokenPayload | null) => void): () => void
   }
@@ -140,6 +153,11 @@ export function createAuthClient(deps: AuthClientDeps): AuthClient {
       if (hostMode && !hostSessionLoaded) await resolveHost()
       return hostMode ? hostSession : (hostSession ?? storage.get())
     },
+    getUserProfile: async (): Promise<{ nickname?: string; headimage?: string } | null> => {
+      if (hostMode && !hostSessionLoaded) await resolveHost()
+      if (!(await auth.getAccessToken())) return null
+      return transport.fetchUserInfo()
+    },
     login: async (options?: LoginOptions): Promise<void> => {
       // Host mode: hq-edge owns the session — ask the host (EDA) to open its
       // own login dialog instead of the auth.eda.cn iframe. The node route
@@ -157,10 +175,15 @@ export function createAuthClient(deps: AuthClientDeps): AuthClient {
     },
     logout: async (): Promise<void> => {
       if (hostMode) {
-        // Host-owned session: nothing to revoke browser-side beyond our cache.
-        hostSession = null
-        storage.clear()
-        emit(null)
+        // Host-owned session: ask the EDA host to log out (node half →
+        // hq-edge → AuthService.TriggerLogout). Success only means the
+        // request was accepted, so re-resolve the host session and emit the
+        // HOST's verdict — never a locally invented "logged out". A rejected
+        // request throws and leaves `hostSession` (the real state) intact.
+        await transport.pushLogout()
+        hostSessionLoaded = false
+        await resolveHost()
+        emit(hostSession)
         return
       }
       storage.clear()

package/src/client/transport.ts

@@ -30,6 +30,13 @@ export interface AuthTransport {
    * session to pick up the fresh credential.
    */
   triggerLogin(): Promise<void>
+  /**
+   * Fetch the rich eda.cn profile (nickname + headimage) for the current
+   * token. The node half resolves the token (host → pushed → persisted) and
+   * calls eda.cn; used by the sidebar in host mode when the host session
+   * carries only {token, userId} — e.g. host mode under kicad.
+   */
+  fetchUserInfo(): Promise<EdaUserProfile | null>
 }
 
 /** Minimal session user shape returned by the node `/session` route. */
@@ -40,6 +47,14 @@ export interface HostSessionUser {
   expiresAt?: number
 }
 
+/** Rich eda.cn profile served by the node `/user-info` route. */
+export interface EdaUserProfile {
+  nickname?: string
+  headimage?: string
+  phone?: string
+  username?: string
+}
+
 export function createWebServerAuthTransport(
   base: string = '/api/v1/huaqiu/auth',
   doFetch: typeof fetch = globalThis.fetch.bind(globalThis),
@@ -95,5 +110,18 @@ export function createWebServerAuthTransport(
       })
       if (!res.ok) throw new Error(`auth login trigger failed: HTTP ${res.status}`)
     },
+    async fetchUserInfo() {
+      try {
+        const res = await doFetch(`${base}/user-info`, {
+          method: 'GET',
+          headers: { accept: 'application/json' },
+        })
+        if (!res.ok) return null
+        const body = await res.json() as { userInfo?: EdaUserProfile | null }
+        return body.userInfo ?? null
+      } catch {
+        return null
+      }
+    },
   }
 }

package/src/client/ui/sidebar-action.tsx

@@ -25,7 +25,7 @@
  */
 import { memo, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore, type CSSProperties } from 'react'
 import { createPortal } from 'react-dom'
-import { getAuth, getAuthState, getHqEdge, subscribeAuth } from '../auth-state.js'
+import { getAuth, getAuthState, getHqEdge, setProfile, subscribeAuth } from '../auth-state.js'
 import { buildProfileUrl } from '../lib.js'
 import { useIsDark, useLocale } from '../ui-env.js'
 import { useT } from '../i18n.js'
@@ -222,7 +222,6 @@ export const HuaqiuAuthSidebarAction = memo(function HuaqiuAuthSidebarAction({ w
 
   const palette = dark ? DARK_PALETTE : LIGHT_PALETTE
   const authenticated = authState.authenticated
-  const avatar = authenticated && !avatarBroken ? authState.avatar : undefined
   const showLabel = wide !== false
 
   // Hide the trigger only when an HQ Edge host that ALREADY exposes its own
@@ -234,10 +233,36 @@ export const HuaqiuAuthSidebarAction = memo(function HuaqiuAuthSidebarAction({ w
   const targetHost = hostMode ? (getHqEdge()?.context?.getTargetHost?.() ?? '') : ''
   if (hostMode && targetHost === 'hq-eda') return null
 
+  // Host sessions (kicad/generic) carry only {token, userId} — no nickname,
+  // no avatar. Fetch the rich eda.cn profile (name + photo) so the trigger
+  // renders the real account instead of a bare HQ icon. Standalone DSH already
+  // has both from the auth.eda.cn payload, so this is host-only.
+  const profile = authState.profile
+  useEffect(() => {
+    if (!hostMode || targetHost === 'hq-eda') return
+    if (!authenticated) {
+      setProfile(null)
+      return
+    }
+    let cancelled = false
+    auth?.getUserProfile?.()
+      .then((info) => {
+        if (cancelled) return
+        setProfile(info)
+      })
+      .catch(() => { /* UI degrades to the HQ icon */ })
+    return () => { cancelled = true }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hostMode, targetHost, authenticated])
+
+  const displayName = profile?.nickname ?? authState.nickname
+  const displayAvatar = profile?.headimage ?? authState.avatar
+  const avatar = authenticated && !avatarBroken ? displayAvatar : undefined
+
   // A new avatar URL is a fresh chance to render it.
   useEffect(() => {
     setAvatarBroken(false)
-  }, [authState.avatar])
+  }, [displayAvatar])
 
   // Logging out (from anywhere: menu, another tab surface, node invalidation)
   // must never leave an orphan menu pointing at a signed-out account.
@@ -309,7 +334,7 @@ export const HuaqiuAuthSidebarAction = memo(function HuaqiuAuthSidebarAction({ w
   }
 
   const label = authenticated
-    ? (authState.nickname ?? t('sidebar.account'))
+    ? (displayName ?? t('sidebar.account'))
     : t('sidebar.login')
 
   const title = authenticated ? t('sidebar.accountTitle') : t('sidebar.loginTitle')
@@ -376,8 +401,8 @@ export const HuaqiuAuthSidebarAction = memo(function HuaqiuAuthSidebarAction({ w
       {menuOpen && menuStyle
         ? createPortal(
             <div ref={menuRef} role="menu" style={menuStyle}>
-              {authState.nickname ? (
-                <div style={{ ...MENU_HEADER_BASE, color: palette.muted }} title={authState.nickname}>{authState.nickname}</div>
+              {displayName ? (
+                <div style={{ ...MENU_HEADER_BASE, color: palette.muted }} title={displayName}>{displayName}</div>
               ) : null}
               <MenuItem
                 label={t('menu.profile')}
@@ -392,7 +417,11 @@ export const HuaqiuAuthSidebarAction = memo(function HuaqiuAuthSidebarAction({ w
                 palette={palette}
                 onSelect={() => {
                   setMenuOpen(false)
-                  void auth.logout()
+                  // Host mode: a rejected logout request must leave the UI
+                  // authenticated — `auth.logout()` only REQUESTS the logout,
+                  // the state comes from the host. Swallow the rejection so it
+                  // never becomes an unhandled promise error.
+                  void auth.logout().catch(() => { /* host refused — stay authenticated */ })
                 }}
               />
             </div>,

package/src/host.ts

@@ -39,6 +39,8 @@ export interface HuaqiuAuthConfig {
   hostAuthPath?: string
   /** Host endpoint that triggers the EDA login dialog; default "/api/v1/auth/login". */
   hostLoginPath?: string
+  /** Host endpoint that requests EDA logout; default "/api/v1/auth/logout". */
+  hostLogoutPath?: string
   /** Seconds a host session is reused before re-fetching. Default 300. */
   hostSessionTtlSeconds?: number
   /** Seconds remote token-validation results are cached. Default 60. */
@@ -47,6 +49,7 @@ export interface HuaqiuAuthConfig {
 
 export const DEFAULT_HOST_AUTH_PATH = '/api/v1/auth/token'
 export const DEFAULT_HOST_LOGIN_PATH = '/api/v1/auth/login'
+export const DEFAULT_HOST_LOGOUT_PATH = '/api/v1/auth/logout'
 export const DEFAULT_HOST_TTL_SECONDS = 300
 export const DEFAULT_VALIDATION_TTL_SECONDS = 60
 
@@ -68,6 +71,9 @@ export function resolveHostConfig(
   const hostLoginPath = config?.hostLoginPath
     ?? env.HQ_EDGE_LOGIN_PATH
     ?? DEFAULT_HOST_LOGIN_PATH
+  const hostLogoutPath = config?.hostLogoutPath
+    ?? env.HQ_EDGE_LOGOUT_PATH
+    ?? DEFAULT_HOST_LOGOUT_PATH
   const ttlRaw = config?.hostSessionTtlSeconds ?? env.HQ_EDGE_HOST_TTL_SECONDS
   let ttl = DEFAULT_HOST_TTL_SECONDS
   if (typeof ttlRaw === 'number' && Number.isFinite(ttlRaw) && ttlRaw > 0) {
@@ -88,6 +94,7 @@ export function resolveHostConfig(
     hqEdgeBaseUrl: baseUrl,
     hostAuthPath,
     hostLoginPath,
+    hostLogoutPath,
     hostSessionTtlSeconds: ttl,
     validationTtlSeconds,
   }

package/src/routes.ts

@@ -27,6 +27,50 @@ function log(): PluginLogger {
   return _log
 }
 
+/**
+ * eda.cn user-profile endpoint, reached with the access token as `X-token`
+ * (the same endpoint hq-eda-ai's `/api/middleware/getUserInfo` proxies).
+ * Returns `{ code: 200000, result: { id, nickname, headimage, phone, username } }`.
+ */
+export const EDA_USER_INFO_URL = 'https://www.eda.cn/api/chiplet/u/base/get'
+
+export interface EdaUserProfile {
+  nickname?: string
+  headimage?: string
+  phone?: string
+  username?: string
+}
+
+/** Fetch the eda.cn profile for a token. Null on any failure (UI degrades). */
+export async function fetchEdaUserProfile(
+  token: string,
+  doFetch: typeof fetch = globalThis.fetch.bind(globalThis),
+): Promise<EdaUserProfile | null> {
+  try {
+    const res = await doFetch(EDA_USER_INFO_URL, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'X-token': token,
+      },
+      body: '{}',
+    })
+    if (!res.ok) return null
+    const body = (await res.json()) as { code?: number; result?: Record<string, unknown> }
+    if (body.code !== 200000 || !body.result) return null
+    const r = body.result
+    return {
+      ...(typeof r.nickname === 'string' && r.nickname ? { nickname: r.nickname } : {}),
+      ...(typeof r.headimage === 'string' && r.headimage ? { headimage: r.headimage } : {}),
+      ...(typeof r.phone === 'string' && r.phone ? { phone: r.phone } : {}),
+      ...(typeof r.username === 'string' && r.username ? { username: r.username } : {}),
+    }
+  } catch (err) {
+    log().warn('fetchEdaUserProfile failed', { error: String((err as Error)?.message || err) })
+    return null
+  }
+}
+
 export const AUTH_ROUTE_PREFIX = '/api/v1/huaqiu/auth'
 
 export type AuthHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void> | void
@@ -86,7 +130,11 @@ export function createAuthHandler(service: HuaqiuAuthService): AuthHandler {
       }
 
       if (req.method === 'POST' && pathname === `${AUTH_ROUTE_PREFIX}/logout`) {
-        service.invalidate()
+        // Forward through `auth.logout()` rather than invalidating locally: in
+        // host mode the EDA host owns the session, so only it can log the
+        // operator out. A rejected request surfaces as 500 and the browser
+        // half keeps its current (authenticated) state.
+        await service.auth.logout()
         sendJson(res, 200, { ok: true })
         return
       }
@@ -103,6 +151,20 @@ export function createAuthHandler(service: HuaqiuAuthService): AuthHandler {
         return
       }
 
+      if (req.method === 'GET' && pathname === `${AUTH_ROUTE_PREFIX}/user-info`) {
+        // Rich profile (nickname + headimage) for the sidebar when the host
+        // session carries only {token, userId} — e.g. host mode under kicad.
+        // The token is resolved by the node half (host → pushed → persisted).
+        const token = await service.auth.getAccessToken()
+        if (!token) {
+          sendJson(res, 200, { userInfo: null })
+          return
+        }
+        const userInfo = await fetchEdaUserProfile(token)
+        sendJson(res, 200, { userInfo })
+        return
+      }
+
       if (req.method === 'POST' && pathname === `${AUTH_ROUTE_PREFIX}/login`) {
         // Host-mode login: forward to HQ Edge, which asks EDA (KiCad) to open
         // its TriggerLoginDialog. Blocks until the dialog is completed.

package/src/service.ts

@@ -51,8 +51,17 @@ export interface HuaqiuAuthApi {
   isAuthenticated(): Promise<boolean>
   getAccessToken(): Promise<string | null>
   getUserInfo(): Promise<HuaqiuUserInfo | null>
-  /** Node-side no-op: login always happens in the browser. */
+  /** Node-side no-op in standalone: login always happens in the browser. */
   login(): Promise<void>
+  /**
+   * Request logout.
+   *
+   * In host mode this asks the EDA host (through hq-edge) to log out — it is
+   * a REQUEST, never a local declaration. The authoritative state keeps coming
+   * from the host, so on success we only drop the cached host session and let
+   * the next `resolve()` re-ask hq-edge. A failed request throws and leaves
+   * the current authentication state untouched.
+   */
   logout(): Promise<void>
   /**
    * Single authoritative validation path (spec §7). Works identically for
@@ -91,6 +100,13 @@ export interface HuaqiuAuthService {
 const PERSIST_FILE = 'session.json'
 const PERSIST_DIR = () => dshHomePath('auth')
 
+/**
+ * Bounded wait for the host to confirm a logout. Shorter than the login wait
+ * (which must cover a human completing the EDA dialog): logout is a host-side
+ * operation, so a confirmation that takes longer than this means it failed.
+ */
+const LOGOUT_WAIT_MS = 30_000
+
 /**
  * Returns the persisted session, or null if absent/unreadable. Best-effort: a
  * corrupt or unreadable file is treated as "no session" rather than thrown.
@@ -149,6 +165,7 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
   private readonly validator: TokenValidator
   private readonly doFetch: typeof fetch
   private readonly hostLoginPath: string
+  private readonly hostLogoutPath: string
   /** Bound on the host login RPC (user must complete the EDA dialog). */
   private readonly loginWaitMs: number
   /**
@@ -178,6 +195,7 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
       this.doFetch,
     )
     this.hostLoginPath = resolved.hostLoginPath ?? '/api/v1/auth/login'
+    this.hostLogoutPath = resolved.hostLogoutPath ?? '/api/v1/auth/logout'
     this.loginWaitMs = 5 * 60_000
     this.validator = new TokenValidator({
       ttlMs: (resolved.validationTtlSeconds ?? 60) * 1000,
@@ -231,7 +249,31 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
       this.validator.invalidate()
       this.emit()
     },
-    logout: async () => this.invalidate(),
+    logout: async () => {
+      // Standalone: the browser owns the credential — drop it locally.
+      if (!this.host.enabled) {
+        this.invalidate()
+        return
+      }
+      // Host mode: the EDA host (KiCad) owns the session, so logout is a
+      // REQUEST forwarded through hq-edge (→ AuthService.TriggerLogout).
+      // Success only means the host accepted/performed it; the authoritative
+      // state is whatever the host reports next, so we drop the cached host
+      // session and let the following resolve() re-ask hq-edge instead of
+      // declaring the operator logged out ourselves.
+      const res = await this.doFetch(`${this.host.baseUrl}${this.hostLogoutPath}`, {
+        method: 'POST',
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(LOGOUT_WAIT_MS),
+      })
+      if (!res.ok) {
+        throw new Error(`host logout not completed: HTTP ${res.status}`)
+      }
+      this.host.clear()
+      this.stale = true
+      this.validator.invalidate()
+      this.emit()
+    },
     validate: () => this.validateInternal(),
     invalidate: () => this.markStale(),
     onAuthStateChanged: (listener) => this.on(listener),