@huaqiu/dsh-auth 0.3.10 → 0.3.11

package/lib/index.d.mts

@@ -144,6 +144,10 @@ declare class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
    * short-circuit to false and forces a fresh remote validation next time.
    */
   private stale;
+  /** Last host credential version seen; see `observeHostVersion`. */
+  private lastHostVersion;
+  private _log;
+  private get log();
   constructor(config?: Partial<HuaqiuAuthConfig> | null, opts?: {
     fetchImpl?: typeof fetch;
   });
@@ -159,11 +163,45 @@ declare class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
    * standalone (auth.eda.cn) login. Otherwise a stale `~/.dsh/auth/session.json`
    * would let the DSH plugins keep calling the backend while hq-edge itself has
    * no auth info. The standalone fallbacks only apply when no host is configured.
+   *
+   * A host credential the host itself reports as `authenticated: false` counts
+   * as "no credential" — otherwise `/session` would hand the browser half a user
+   * object its own `authenticated` flag contradicts, and the browser half (which
+   * adopts the session only when `authenticated` is true) would silently drop
+   * it. That mismatch is exactly how "the token reached HQ Edge but never
+   * reached the plugin" presents.
    */
   private resolve;
-  /** Spec §7: resolve → local expiry → remote validation → update state. */
+  /**
+   * Track the host's credential version so a replaced credential re-arms the
+   * session after a 401.
+   *
+   * `invalidate()` (called when a backend answers 401) must keep the session
+   * down — but only for *that* credential. HQ Edge bumps `version` whenever EDA
+   * replaces or clears its credential, so a new version means the operator has
+   * a new token and the previous rejection no longer applies.
+   */
+  private observeHostVersion;
+  /**
+   * Spec §7: resolve → local expiry → remote validation → update state.
+   *
+   * In HOST mode there is no remote validation: the host is the authority. It
+   * received the credential from EDA and publishes its own `authenticated`
+   * verdict, so probing `www.eda.cn/api/token/validate` here is not just
+   * redundant — it is wrong. That endpoint does not know the credential class
+   * EDA hands to HQ Edge (it answers `result: false`) and is unreachable in
+   * offline deployments, so gating on it made every host-mode session read as
+   * unauthenticated even while hq-edge reported `authenticated: true`.
+   */
   private validateInternal;
-  /** Validation-scoped invalidation: keep the credential, drop cached validity. */
+  /** Validation-scoped invalidation: keep the credential, drop cached validity.
+   *
+   *  In host mode the host cache *is* the cached validity — the validator only
+   *  confirmed what the host already said — so the next call must re-fetch:
+   *  otherwise a 401-driven `auth.invalidate()` would keep stale=true latched
+   *  for the full `hostSessionTtlSeconds` (default 300 s), and an HQ-Edge
+   *  credential replace in between would be invisible until the cache expired.
+   */
   private markStale;
   setCredentials(info: HuaqiuUserInfo): void;
   invalidate(): void;

package/lib/index.mjs

@@ -1,6 +1,34 @@
+import { getLogger } from "@huaqiu/dsh-plugin-log";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+//#region src/host.ts
+/**
+* HQ Edge host mode for `dsh-auth`.
+*
+* In standalone DSH, credentials arrive only when the user logs in through the
+* browser (auth.eda.cn iframe → postMessage → `webServer` route →
+* `setCredentials`). That means the node half is empty until a browser tab
+* focuses the card, and every tool returns `needs_auth` in the gap — including
+* across a process restart (the in-memory cache is gone).
+*
+* Host mode removes that gap. When HQ Edge is the host, it already holds the
+* operator-supplied token + user id, and exposes them on a loopback route. The
+* node half fetches them on boot and is authoritative immediately, without
+* waiting for a browser. The browser half is untouched — host mode is *mode*,
+* not API (spec §5/§14).
+*
+* Resolution order inside `getUserInfo()` (spec §6.2):
+*   1. host session   — HQ Edge configured → fetch + cache (TTL)
+*   2. pushed session — what the browser half sent (today's behaviour)
+*   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;
+}
 /**
 * Resolve the effective config: overlay `config` (highest) > env (safety net
 * for non-supervisor installs) > defaults. Centralised here so only `dsh-auth`
@@ -33,8 +61,15 @@ function resolveHostConfig(config, env = process.env) {
 	};
 }
 /**
-* Fetches and caches the host (HQ Edge) session. The cache is memory-only with a
-* TTL; the loopback GET is cheap and the token is static, so we never persist it.
+* Fetches and caches the host (HQ Edge) session. The cache is memory-only with
+* a TTL; the loopback GET is cheap, so we never persist the credential.
+*
+* Caching rule — **only a usable session is cached**. A host that is up but has
+* no credential yet (EDA not logged in, or the login dialog still open) must
+* NOT be cached: the operator may complete the login a second later, and a
+* cached negative would pin every tool to `needs_auth` for the whole TTL. The
+* old code cached whatever it got, so a DSH that booted before EDA
+* authenticated stayed "logged out" for up to `hostSessionTtlSeconds` (300s).
 */
 var HostSessionResolver = class {
 	baseUrl;
@@ -56,22 +91,45 @@ var HostSessionResolver = class {
 		if (!this.enabled) return null;
 		const now = Date.now();
 		if (this.cache !== null && now - this.cache.fetchedAt < this.ttlMs) return this.cache.info;
+		const url = `${this.baseUrl}${this.path}`;
+		let info = null;
+		let status = null;
 		try {
-			const res = await this.doFetch(`${this.baseUrl}${this.path}`, {
+			const res = await this.doFetch(url, {
 				method: "GET",
 				headers: { accept: "application/json" }
 			});
-			if (!res.ok) return this.cache?.info ?? null;
-			const info = normalizeHostUser(await res.json());
-			if (!info) return this.cache?.info ?? null;
+			status = res.status;
+			if (res.ok) info = normalizeHostUser(await res.json());
+		} catch (err) {
+			log$1().warn("host session fetch failed", {
+				url,
+				error: String(err)
+			});
+			info = null;
+		}
+		if (info !== null && info.authenticated) {
 			this.cache = {
 				info,
 				fetchedAt: now
 			};
+			log$1().debug("host session resolved", {
+				url,
+				status,
+				userId: info.id,
+				version: info.version ?? null,
+				authenticated: info.authenticated
+			});
 			return info;
-		} catch {
-			return this.cache?.info ?? null;
 		}
+		this.cache = null;
+		log$1().info("no usable host session", {
+			url,
+			status,
+			parsed: info !== null,
+			hostAuthenticated: info?.authenticated ?? null
+		});
+		return null;
 	}
 	/** Drop the cached value so the next `resolve()` re-fetches (reactive invalidation). */
 	clear() {
@@ -83,16 +141,30 @@ function asId(raw) {
 	if (typeof raw === "number" && Number.isFinite(raw)) return String(raw);
 	return null;
 }
-/** Parse the host route payload into a credential, tolerating key-name drift. */
+/**
+* Parse the host route payload into a credential, tolerating key-name drift.
+*
+* HQ Edge answers `GET /api/v1/auth/token` with
+* `{ authenticated, token, userId, version }`. The `authenticated` flag is the
+* host's own verdict and is carried through verbatim; hosts that predate it
+* (or a minimal `{ token, userId }` stub) omit the key, in which case the
+* presence of a usable token+id is taken as the old contract was: authenticated.
+*/
 function normalizeHostUser(data) {
 	const token = typeof data.token === "string" && data.token.length > 0 ? data.token : null;
 	const id = asId(data.userId) ?? asId(data.id) ?? asId(data.user_id);
 	if (!token || !id) return null;
 	const nickname = typeof data.nickname === "string" && data.nickname.length > 0 ? data.nickname : void 0;
+	const authenticated = data.authenticated === void 0 ? true : data.authenticated === true;
+	const version = typeof data.version === "number" && Number.isFinite(data.version) ? data.version : void 0;
+	const expiresAt = typeof data.expiresAt === "number" && Number.isFinite(data.expiresAt) ? data.expiresAt : void 0;
 	return {
 		id,
 		token,
-		...nickname ? { nickname } : {}
+		authenticated,
+		...nickname ? { nickname } : {},
+		...version !== void 0 ? { version } : {},
+		...expiresAt !== void 0 ? { expiresAt } : {}
 	};
 }
 /**
@@ -305,6 +377,13 @@ var InMemoryHuaqiuAuthService = class {
 	* short-circuit to false and forces a fresh remote validation next time.
 	*/
 	stale = false;
+	/** Last host credential version seen; see `observeHostVersion`. */
+	lastHostVersion = null;
+	_log = null;
+	get log() {
+		if (this._log === null) this._log = getLogger("dsh-auth");
+		return this._log;
+	}
 	constructor(config, opts) {
 		const resolved = resolveHostConfig(config);
 		this.doFetch = opts?.fetchImpl ?? globalThis.fetch.bind(globalThis);
@@ -316,11 +395,17 @@ var InMemoryHuaqiuAuthService = class {
 			fetchImpl: this.doFetch
 		});
 		this.hostMode = this.host.enabled;
+		this.log.info("auth service started", {
+			hostMode: this.hostMode,
+			hostAuthPath: resolved.hostAuthPath,
+			hostSessionTtlSeconds: resolved.hostSessionTtlSeconds
+		});
 	}
 	/** Host mode is active iff a host base URL was configured (see HostSessionResolver.enabled). */
 	hostMode;
 	auth = {
 		isAuthenticated: async () => {
+			if (await this.resolve() === null) return false;
 			if (this.stale) return false;
 			return (await this.validateInternal()).status === "valid";
 		},
@@ -353,26 +438,83 @@ var InMemoryHuaqiuAuthService = class {
 	* standalone (auth.eda.cn) login. Otherwise a stale `~/.dsh/auth/session.json`
 	* would let the DSH plugins keep calling the backend while hq-edge itself has
 	* no auth info. The standalone fallbacks only apply when no host is configured.
+	*
+	* A host credential the host itself reports as `authenticated: false` counts
+	* as "no credential" — otherwise `/session` would hand the browser half a user
+	* object its own `authenticated` flag contradicts, and the browser half (which
+	* adopts the session only when `authenticated` is true) would silently drop
+	* it. That mismatch is exactly how "the token reached HQ Edge but never
+	* reached the plugin" presents.
 	*/
 	async resolve() {
 		if (this.host.enabled) {
 			const host = await this.host.resolve();
-			if (host) return toUserInfo(host);
-			return null;
+			if (!host || !host.authenticated) {
+				this.log.debug("host session unusable", {
+					hostReachable: host !== null,
+					hostAuthenticated: host?.authenticated ?? null
+				});
+				return null;
+			}
+			this.observeHostVersion(host.version);
+			return toUserInfo(host);
 		}
 		if (this.current) return this.current;
 		return readPersisted();
 	}
-	/** Spec §7: resolve → local expiry → remote validation → update state. */
+	/**
+	* Track the host's credential version so a replaced credential re-arms the
+	* session after a 401.
+	*
+	* `invalidate()` (called when a backend answers 401) must keep the session
+	* down — but only for *that* credential. HQ Edge bumps `version` whenever EDA
+	* replaces or clears its credential, so a new version means the operator has
+	* a new token and the previous rejection no longer applies.
+	*/
+	observeHostVersion(version) {
+		if (typeof version !== "number" || !Number.isFinite(version)) return;
+		if (this.lastHostVersion !== null && version !== this.lastHostVersion) {
+			this.stale = false;
+			this.validator.invalidate();
+			this.log.info("host credential replaced — re-arming session", { version });
+		}
+		this.lastHostVersion = version;
+	}
+	/**
+	* Spec §7: resolve → local expiry → remote validation → update state.
+	*
+	* In HOST mode there is no remote validation: the host is the authority. It
+	* received the credential from EDA and publishes its own `authenticated`
+	* verdict, so probing `www.eda.cn/api/token/validate` here is not just
+	* redundant — it is wrong. That endpoint does not know the credential class
+	* EDA hands to HQ Edge (it answers `result: false`) and is unreachable in
+	* offline deployments, so gating on it made every host-mode session read as
+	* unauthenticated even while hq-edge reported `authenticated: true`.
+	*/
 	async validateInternal() {
 		const info = await this.resolve();
 		if (!info) {
-			this.stale = true;
+			if (!this.host.enabled) this.stale = true;
 			return {
 				status: "invalid",
 				reason: "invalid"
 			};
 		}
+		if (this.host.enabled) {
+			if (this.validator.isLocallyExpired(info.expiresAt)) {
+				this.validator.invalidate(info.token);
+				this.stale = true;
+				return {
+					status: "invalid",
+					reason: "expired"
+				};
+			}
+			return {
+				status: "valid",
+				userId: info.id,
+				...info.expiresAt !== void 0 ? { expiresAt: info.expiresAt } : {}
+			};
+		}
 		if (this.validator.isLocallyExpired(info.expiresAt)) {
 			this.validator.invalidate(info.token);
 			this.stale = true;
@@ -386,10 +528,18 @@ var InMemoryHuaqiuAuthService = class {
 		else if (result.status === "invalid") this.stale = true;
 		return result;
 	}
-	/** Validation-scoped invalidation: keep the credential, drop cached validity. */
+	/** Validation-scoped invalidation: keep the credential, drop cached validity.
+	*
+	*  In host mode the host cache *is* the cached validity — the validator only
+	*  confirmed what the host already said — so the next call must re-fetch:
+	*  otherwise a 401-driven `auth.invalidate()` would keep stale=true latched
+	*  for the full `hostSessionTtlSeconds` (default 300 s), and an HQ-Edge
+	*  credential replace in between would be invisible until the cache expired.
+	*/
 	markStale() {
 		this.stale = true;
 		this.validator.invalidate();
+		if (this.host.enabled) this.host.clear();
 	}
 	setCredentials(info) {
 		this.current = info;
@@ -420,7 +570,8 @@ function toUserInfo(host) {
 	return {
 		id: host.id,
 		token: host.token,
-		...host.nickname !== void 0 ? { nickname: host.nickname } : {}
+		...host.nickname !== void 0 ? { nickname: host.nickname } : {},
+		...host.expiresAt !== void 0 ? { expiresAt: host.expiresAt } : {}
 	};
 }
 //#endregion
@@ -505,6 +656,7 @@ function createAuthHandler(service) {
 }
 //#endregion
 //#region src/index.ts
+const log = getLogger("dsh-auth");
 const name = "@huaqiu/dsh-auth";
 const inject = ["webServer"];
 /**
@@ -516,6 +668,11 @@ const inject = ["webServer"];
 *   without a supervisor (spec §6.4).
 */
 function apply(ctx, config) {
+	log.info("applying dsh-auth node half", {
+		hasConfig: config != null,
+		configKeys: config != null ? Object.keys(config) : [],
+		hqEdgeBaseUrl: config?.hqEdgeBaseUrl ?? null
+	});
 	const service = new InMemoryHuaqiuAuthService(config);
 	ctx.effect(() => ctx.provide("huaqiuAuth", service));
 	ctx.effect(() => ctx.webServer.register({
@@ -523,6 +680,10 @@ function apply(ctx, config) {
 		path: AUTH_ROUTE_PREFIX,
 		handler: createAuthHandler(service)
 	}));
+	log.info("dsh-auth node half ready", {
+		routes: AUTH_ROUTE_PREFIX,
+		hostMode: service.hostMode
+	});
 }
 //#endregion
 export { AUTH_ROUTE_PREFIX, InMemoryHuaqiuAuthService, apply, createAuthHandler, inject, name };

package/package.json

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

package/src/host.ts

@@ -20,6 +20,18 @@
  *   4. null           → tools return needs_auth
  */
 
+import { getLogger, type PluginLogger } from '@huaqiu/dsh-plugin-log'
+
+// Lazy so test suites that `vi.mock('@deepseek-ai/dsh-home-paths', …)` before
+// the test's TMP constant is initialised don't trigger `dshHomePath('logs')` at
+// module-load time. Every site goes through `log()` instead of holding a module
+// reference to the logger.
+let _log: PluginLogger | null = null
+function log(): PluginLogger {
+  if (_log === null) _log = getLogger('dsh-auth')
+  return _log
+}
+
 export interface HuaqiuAuthConfig {
   /** HQ Edge base URL, e.g. "http://localhost:18080". Absent → standalone. */
   hqEdgeBaseUrl?: string
@@ -90,11 +102,37 @@ export interface ResolvedHostUser {
   id: string
   token: string
   nickname?: string
+  /**
+   * The HOST's own verdict on the credential.
+   *
+   * HQ Edge receives its credential from EDA (`AuthStateChanged`) and reports
+   * `authenticated` alongside the token; that verdict is authoritative for host
+   * mode. This plugin must not substitute its own guess: the token class EDA
+   * hands to HQ Edge is not necessarily known to the public `www.eda.cn`
+   * token-validation endpoint, so a remote probe there can answer "not valid"
+   * for a credential the operator's own editor considers live.
+   */
+  authenticated: boolean
+  /**
+   * Host-side state version (HQ Edge bumps it on every credential replace and
+   * clear). A change means "this is a different credential than the one you
+   * looked at", which is how a 401-driven invalidation gets undone.
+   */
+  version?: number
+  /** Unix seconds, when the host knows the expiry. */
+  expiresAt?: number
 }
 
 /**
- * Fetches and caches the host (HQ Edge) session. The cache is memory-only with a
- * TTL; the loopback GET is cheap and the token is static, so we never persist it.
+ * Fetches and caches the host (HQ Edge) session. The cache is memory-only with
+ * a TTL; the loopback GET is cheap, so we never persist the credential.
+ *
+ * Caching rule — **only a usable session is cached**. A host that is up but has
+ * no credential yet (EDA not logged in, or the login dialog still open) must
+ * NOT be cached: the operator may complete the login a second later, and a
+ * cached negative would pin every tool to `needs_auth` for the whole TTL. The
+ * old code cached whatever it got, so a DSH that booted before EDA
+ * authenticated stayed "logged out" for up to `hostSessionTtlSeconds` (300s).
  */
 export class HostSessionResolver {
   private cache: HostSession | null = null
@@ -117,21 +155,47 @@ export class HostSessionResolver {
     if (this.cache !== null && now - this.cache.fetchedAt < this.ttlMs) {
       return this.cache.info
     }
+    const url = `${this.baseUrl}${this.path}`
+    let info: ResolvedHostUser | null = null
+    let status: number | null = null
     try {
-      const res = await this.doFetch(`${this.baseUrl}${this.path}`, {
+      const res = await this.doFetch(url, {
         method: 'GET',
         headers: { accept: 'application/json' },
       })
-      if (!res.ok) return this.cache?.info ?? null
-      const data = await res.json() as Record<string, unknown>
-      const info = normalizeHostUser(data)
-      if (!info) return this.cache?.info ?? null
+      status = res.status
+      if (res.ok) {
+        const data = await res.json() as Record<string, unknown>
+        info = normalizeHostUser(data)
+      }
+    } catch (err) {
+      // Network error: nothing usable right now.
+      log().warn('host session fetch failed', { url, error: String(err) })
+      info = null
+    }
+    if (info !== null && info.authenticated) {
       this.cache = { info, fetchedAt: now }
+      // Never log the credential itself — id/version are enough to correlate
+      // this plugin with the HQ Edge log line that served it.
+      log().debug('host session resolved', {
+        url,
+        status,
+        userId: info.id,
+        version: info.version ?? null,
+        authenticated: info.authenticated,
+      })
       return info
-    } catch {
-      // Network error: fall back to a previously cached value if we have one.
-      return this.cache?.info ?? null
     }
+    // Unusable (unreachable, unparseable, or the host says it has no
+    // credential). Drop the cache so the very next call re-asks the host.
+    this.cache = null
+    log().info('no usable host session', {
+      url,
+      status,
+      parsed: info !== null,
+      hostAuthenticated: info?.authenticated ?? null,
+    })
+    return null
   }
 
   /** Drop the cached value so the next `resolve()` re-fetches (reactive invalidation). */
@@ -146,7 +210,15 @@ function asId(raw: unknown): string | null {
   return null
 }
 
-/** Parse the host route payload into a credential, tolerating key-name drift. */
+/**
+ * Parse the host route payload into a credential, tolerating key-name drift.
+ *
+ * HQ Edge answers `GET /api/v1/auth/token` with
+ * `{ authenticated, token, userId, version }`. The `authenticated` flag is the
+ * host's own verdict and is carried through verbatim; hosts that predate it
+ * (or a minimal `{ token, userId }` stub) omit the key, in which case the
+ * presence of a usable token+id is taken as the old contract was: authenticated.
+ */
 export function normalizeHostUser(data: Record<string, unknown>): ResolvedHostUser | null {
   const token = typeof data.token === 'string' && data.token.length > 0
     ? data.token
@@ -158,5 +230,19 @@ export function normalizeHostUser(data: Record<string, unknown>): ResolvedHostUs
   const nickname = typeof data.nickname === 'string' && data.nickname.length > 0
     ? data.nickname
     : undefined
-  return { id, token, ...(nickname ? { nickname } : {}) }
+  const authenticated = data.authenticated === undefined ? true : data.authenticated === true
+  const version = typeof data.version === 'number' && Number.isFinite(data.version)
+    ? data.version
+    : undefined
+  const expiresAt = typeof data.expiresAt === 'number' && Number.isFinite(data.expiresAt)
+    ? data.expiresAt
+    : undefined
+  return {
+    id,
+    token,
+    authenticated,
+    ...(nickname ? { nickname } : {}),
+    ...(version !== undefined ? { version } : {}),
+    ...(expiresAt !== undefined ? { expiresAt } : {}),
+  }
 }

package/src/index.ts

@@ -6,10 +6,13 @@
  */
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-host-webserver'
+import { getLogger } from '@huaqiu/dsh-plugin-log'
 import { InMemoryHuaqiuAuthService, type HuaqiuAuthService } from './service.js'
 import { AUTH_ROUTE_PREFIX, createAuthHandler } from './routes.js'
 import type { HuaqiuAuthConfig } from './host.js'
 
+const log = getLogger('dsh-auth')
+
 export type { HuaqiuAuthApi, HuaqiuAuthService, HuaqiuUserInfo } from './service.js'
 export { InMemoryHuaqiuAuthService } from './service.js'
 export { AUTH_ROUTE_PREFIX, createAuthHandler, type AuthHandler } from './routes.js'
@@ -33,6 +36,16 @@ declare module '@deepseek-ai/cordis' {
  *   without a supervisor (spec §6.4).
  */
 export function apply(ctx: Context, config?: Partial<HuaqiuAuthConfig>): void {
+  // The single most useful line when a harness upgrade "loses" the credential:
+  // it proves whether the overlay `config` still reached `apply(ctx, config)`.
+  // When `hostMode` is false under HQ Edge, the endpoint was not delivered and
+  // every tool will report `needs_auth` no matter what the browser does.
+  log.info('applying dsh-auth node half', {
+    hasConfig: config != null,
+    configKeys: config != null ? Object.keys(config) : [],
+    hqEdgeBaseUrl: config?.hqEdgeBaseUrl ?? null,
+  })
+
   const service = new InMemoryHuaqiuAuthService(config)
   ctx.effect(() => ctx.provide('huaqiuAuth', service))
 
@@ -41,4 +54,6 @@ export function apply(ctx: Context, config?: Partial<HuaqiuAuthConfig>): void {
     path: AUTH_ROUTE_PREFIX,
     handler: createAuthHandler(service),
   }))
+
+  log.info('dsh-auth node half ready', { routes: AUTH_ROUTE_PREFIX, hostMode: service.hostMode })
 }

package/src/routes.ts

@@ -15,8 +15,18 @@
  * the documented channel).
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { getLogger, type PluginLogger } from '@huaqiu/dsh-plugin-log'
 import type { HuaqiuAuthService, HuaqiuUserInfo } from './service.js'
 
+// Lazy so test suites that `vi.mock('@deepseek-ai/dsh-home-paths', …)` before
+// their TMP constant is initialised don't trigger `dshHomePath('logs')` at
+// module-load time.
+let _log: PluginLogger | null = null
+function log(): PluginLogger {
+  if (_log === null) _log = getLogger('dsh-auth')
+  return _log
+}
+
 export const AUTH_ROUTE_PREFIX = '/api/v1/huaqiu/auth'
 
 export type AuthHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void> | void

package/src/service.ts

@@ -23,6 +23,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
+import { getLogger, type PluginLogger } from '@huaqiu/dsh-plugin-log'
 import {
   HostSessionResolver,
   resolveHostConfig,
@@ -156,6 +157,13 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
    * short-circuit to false and forces a fresh remote validation next time.
    */
   private stale = false
+  /** Last host credential version seen; see `observeHostVersion`. */
+  private lastHostVersion: number | null = null
+  private _log: PluginLogger | null = null
+  private get log(): PluginLogger {
+    if (this._log === null) this._log = getLogger('dsh-auth')
+    return this._log
+  }
 
   constructor(
     config?: Partial<HuaqiuAuthConfig> | null,
@@ -176,6 +184,11 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
       fetchImpl: this.doFetch,
     })
     this.hostMode = this.host.enabled
+    this.log.info('auth service started', {
+      hostMode: this.hostMode,
+      hostAuthPath: resolved.hostAuthPath,
+      hostSessionTtlSeconds: resolved.hostSessionTtlSeconds,
+    })
   }
 
   /** Host mode is active iff a host base URL was configured (see HostSessionResolver.enabled). */
@@ -183,6 +196,15 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
 
   readonly auth: HuaqiuAuthApi = {
     isAuthenticated: async () => {
+      // `stale` is "an upstream 401 was reported against a previous credential".
+      // Run resolve() *first* so the host's version comparator can run — HQ Edge
+      // bumps its credential version when the operator re-authes, and a newer
+      // version means the previous 401 no longer applies. Only after that
+      // observation do we honour the stale latch (if the credential is
+      // unchanged). Without this ordering, a 401-driven invalidation would
+      // keep the operator logged out even after HQ Edge swapped credentials.
+      const info = await this.resolve()
+      if (info === null) return false
       if (this.stale) return false
       return (await this.validateInternal()).status === 'valid'
     },
@@ -224,24 +246,78 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
    * standalone (auth.eda.cn) login. Otherwise a stale `~/.dsh/auth/session.json`
    * would let the DSH plugins keep calling the backend while hq-edge itself has
    * no auth info. The standalone fallbacks only apply when no host is configured.
+   *
+   * A host credential the host itself reports as `authenticated: false` counts
+   * as "no credential" — otherwise `/session` would hand the browser half a user
+   * object its own `authenticated` flag contradicts, and the browser half (which
+   * adopts the session only when `authenticated` is true) would silently drop
+   * it. That mismatch is exactly how "the token reached HQ Edge but never
+   * reached the plugin" presents.
    */
   private async resolve(): Promise<HuaqiuUserInfo | null> {
     if (this.host.enabled) {
       const host = await this.host.resolve()
-      if (host) return toUserInfo(host)
-      return null
+      if (!host || !host.authenticated) {
+        this.log.debug('host session unusable', {
+          hostReachable: host !== null,
+          hostAuthenticated: host?.authenticated ?? null,
+        })
+        return null
+      }
+      this.observeHostVersion(host.version)
+      return toUserInfo(host)
     }
     if (this.current) return this.current
     return readPersisted()
   }
 
-  /** Spec §7: resolve → local expiry → remote validation → update state. */
+  /**
+   * Track the host's credential version so a replaced credential re-arms the
+   * session after a 401.
+   *
+   * `invalidate()` (called when a backend answers 401) must keep the session
+   * down — but only for *that* credential. HQ Edge bumps `version` whenever EDA
+   * replaces or clears its credential, so a new version means the operator has
+   * a new token and the previous rejection no longer applies.
+   */
+  private observeHostVersion(version?: number): void {
+    if (typeof version !== 'number' || !Number.isFinite(version)) return
+    if (this.lastHostVersion !== null && version !== this.lastHostVersion) {
+      this.stale = false
+      this.validator.invalidate()
+      this.log.info('host credential replaced — re-arming session', { version })
+    }
+    this.lastHostVersion = version
+  }
+
+  /**
+   * Spec §7: resolve → local expiry → remote validation → update state.
+   *
+   * In HOST mode there is no remote validation: the host is the authority. It
+   * received the credential from EDA and publishes its own `authenticated`
+   * verdict, so probing `www.eda.cn/api/token/validate` here is not just
+   * redundant — it is wrong. That endpoint does not know the credential class
+   * EDA hands to HQ Edge (it answers `result: false`) and is unreachable in
+   * offline deployments, so gating on it made every host-mode session read as
+   * unauthenticated even while hq-edge reported `authenticated: true`.
+   */
   private async validateInternal(): Promise<AuthValidationResult> {
     const info = await this.resolve()
     if (!info) {
-      this.stale = true
+      // Host mode deliberately does NOT latch `stale` here: an unreachable or
+      // not-yet-logged-in host is a transient condition, and latching would
+      // freeze the session even after the host recovers.
+      if (!this.host.enabled) this.stale = true
       return { status: 'invalid', reason: 'invalid' }
     }
+    if (this.host.enabled) {
+      if (this.validator.isLocallyExpired(info.expiresAt)) {
+        this.validator.invalidate(info.token)
+        this.stale = true
+        return { status: 'invalid', reason: 'expired' }
+      }
+      return { status: 'valid', userId: info.id, ...(info.expiresAt !== undefined ? { expiresAt: info.expiresAt } : {}) }
+    }
     // Local expiry is an optimization; remote validation stays authoritative.
     if (this.validator.isLocallyExpired(info.expiresAt)) {
       this.validator.invalidate(info.token)
@@ -256,10 +332,18 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
     return result
   }
 
-  /** Validation-scoped invalidation: keep the credential, drop cached validity. */
+  /** Validation-scoped invalidation: keep the credential, drop cached validity.
+   *
+   *  In host mode the host cache *is* the cached validity — the validator only
+   *  confirmed what the host already said — so the next call must re-fetch:
+   *  otherwise a 401-driven `auth.invalidate()` would keep stale=true latched
+   *  for the full `hostSessionTtlSeconds` (default 300 s), and an HQ-Edge
+   *  credential replace in between would be invisible until the cache expired.
+   */
   private markStale(): void {
     this.stale = true
     this.validator.invalidate()
+    if (this.host.enabled) this.host.clear()
   }
 
   setCredentials(info: HuaqiuUserInfo): void {
@@ -300,5 +384,6 @@ function toUserInfo(host: ResolvedHostUser): HuaqiuUserInfo {
     id: host.id,
     token: host.token,
     ...(host.nickname !== undefined ? { nickname: host.nickname } : {}),
+    ...(host.expiresAt !== undefined ? { expiresAt: host.expiresAt } : {}),
   }
 }