@huaqiu/dsh-auth 0.1.2 → 0.2.1

package/lib/index.mjs

@@ -16,10 +16,18 @@ function resolveHostConfig(config, env = process.env) {
 		const parsed = Number.parseInt(ttlRaw, 10);
 		if (Number.isFinite(parsed) && parsed > 0) ttl = parsed;
 	}
+	const vTtlRaw = config?.validationTtlSeconds ?? env.HQ_EDGE_VALIDATION_TTL_SECONDS;
+	let validationTtlSeconds = 60;
+	if (typeof vTtlRaw === "number" && Number.isFinite(vTtlRaw) && vTtlRaw > 0) validationTtlSeconds = vTtlRaw;
+	else if (typeof vTtlRaw === "string" && vTtlRaw.trim().length > 0) {
+		const parsed = Number.parseInt(vTtlRaw, 10);
+		if (Number.isFinite(parsed) && parsed > 0) validationTtlSeconds = parsed;
+	}
 	return {
 		hqEdgeBaseUrl: baseUrl,
 		hostAuthPath,
-		hostSessionTtlSeconds: ttl
+		hostSessionTtlSeconds: ttl,
+		validationTtlSeconds
 	};
 }
 /**
@@ -85,6 +93,135 @@ function normalizeHostUser(data) {
 		...nickname ? { nickname } : {}
 	};
 }
+/**
+* Classifies the HTTP status of the validation request.
+*
+* 401 → unauthorized; 403 → forbidden; any other non-ok status (incl. 5xx) →
+* unavailable. A 2xx body of `{ result: false }` → unauthorized (the endpoint
+* does not distinguish expired vs revoked, so we use the generic
+* `unauthorized` reason; local expiry is the only source of `expired`).
+*/
+function classifyStatus(status) {
+	if (status === 401) return {
+		status: "invalid",
+		reason: "unauthorized"
+	};
+	if (status === 403) return {
+		status: "invalid",
+		reason: "forbidden"
+	};
+	return {
+		status: "unavailable",
+		error: /* @__PURE__ */ new Error(`token validation HTTP ${status}`)
+	};
+}
+var TokenValidator = class {
+	ttlMs;
+	validateUrl;
+	fetchImpl;
+	now;
+	/** token → { result, at }; in-memory only, never persisted (spec §8). */
+	cache = /* @__PURE__ */ new Map();
+	/** token → in-flight promise; coalesces concurrent validate() calls (§16). */
+	inFlight = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.ttlMs = options.ttlMs ?? 6e4;
+		this.validateUrl = options.validateUrl ?? "https://www.eda.cn/api/token/validate";
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+		this.now = options.now ?? (() => Date.now());
+	}
+	/**
+	* Cheap local expiry check — an optimization, not authoritative validation.
+	* Unknown expiry ⇒ not assumed invalid (spec §6).
+	*/
+	isLocallyExpired(expiresAt) {
+		if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) return false;
+		return expiresAt * 1e3 <= this.now();
+	}
+	/**
+	* Validate a token. Cached within TTL; a single in-flight request is shared
+	* by concurrent callers. Never treats a network failure as "invalid".
+	*/
+	async validate(token, session) {
+		if (!token) return {
+			status: "invalid",
+			reason: "invalid"
+		};
+		if (this.isLocallyExpired(session?.expiresAt)) {
+			this.cache.delete(token);
+			return {
+				status: "invalid",
+				reason: "expired"
+			};
+		}
+		const cached = this.cache.get(token);
+		if (cached && this.now() - cached.at < this.ttlMs) return cached.result;
+		const inFlight = this.inFlight.get(token);
+		if (inFlight) return inFlight;
+		const promise = this.validateRemotely(token);
+		this.inFlight.set(token, promise);
+		try {
+			const result = await promise;
+			this.cache.set(token, {
+				result,
+				at: this.now()
+			});
+			return result;
+		} finally {
+			this.inFlight.delete(token);
+		}
+	}
+	/** Drop cached/in-flight validation for a token (or all when omitted). */
+	invalidate(token) {
+		if (token === void 0) {
+			this.cache.clear();
+			this.inFlight.clear();
+			return;
+		}
+		this.cache.delete(token);
+		this.inFlight.delete(token);
+	}
+	/** Resolve a currently-cached result (no remote call), or null. */
+	peek(token) {
+		const cached = this.cache.get(token);
+		if (!cached) return null;
+		if (this.now() - cached.at >= this.ttlMs) {
+			this.cache.delete(token);
+			return null;
+		}
+		return cached.result;
+	}
+	async validateRemotely(token) {
+		const url = `${this.validateUrl}?token=${encodeURIComponent(token)}`;
+		let res;
+		try {
+			res = await this.fetchImpl(url, {
+				method: "GET",
+				headers: { accept: "application/json" }
+			});
+		} catch (err) {
+			return {
+				status: "unavailable",
+				error: err
+			};
+		}
+		if (!res.ok) return classifyStatus(res.status);
+		let body;
+		try {
+			body = await res.json();
+		} catch (err) {
+			return {
+				status: "unavailable",
+				error: /* @__PURE__ */ new Error(`token validation: unparseable response (${String(err)})`)
+			};
+		}
+		if ((typeof body === "object" && body !== null ? body.result : void 0) === true) return { status: "valid" };
+		return {
+			status: "invalid",
+			reason: "unauthorized"
+		};
+	}
+};
 //#endregion
 //#region src/service.ts
 /**
@@ -124,10 +261,12 @@ function readPersisted() {
 		const token = typeof raw.token === "string" && raw.token.length > 0 ? raw.token : null;
 		if (!id || !token) return null;
 		const nickname = typeof raw.nickname === "string" && raw.nickname.length > 0 ? raw.nickname : void 0;
+		const expiresAt = typeof raw.expiresAt === "number" && Number.isFinite(raw.expiresAt) ? raw.expiresAt : void 0;
 		return {
 			id,
 			token,
-			...nickname ? { nickname } : {}
+			...nickname ? { nickname } : {},
+			...expiresAt !== void 0 ? { expiresAt } : {}
 		};
 	} catch {
 		return null;
@@ -153,39 +292,97 @@ var InMemoryHuaqiuAuthService = class {
 	current = null;
 	listeners = /* @__PURE__ */ new Set();
 	host;
+	validator;
+	/**
+	* True once the current credential has been rejected (API 401) or explicitly
+	* invalidated. Keeps the credential for recovery but makes `isAuthenticated()`
+	* short-circuit to false and forces a fresh remote validation next time.
+	*/
+	stale = false;
 	constructor(config, opts) {
 		const resolved = resolveHostConfig(config);
 		this.host = new HostSessionResolver(resolved.hqEdgeBaseUrl ?? "", resolved.hostAuthPath ?? "/api/v1/auth/token", (resolved.hostSessionTtlSeconds ?? 300) * 1e3, opts?.fetchImpl);
+		this.validator = new TokenValidator({
+			ttlMs: (resolved.validationTtlSeconds ?? 60) * 1e3,
+			fetchImpl: opts?.fetchImpl
+		});
 		this.hostMode = this.host.enabled;
 	}
 	/** Host mode is active iff a host base URL was configured (see HostSessionResolver.enabled). */
 	hostMode;
 	auth = {
-		isAuthenticated: () => this.host.enabled || this.current !== null || readPersisted() !== null,
+		isAuthenticated: async () => {
+			if (this.stale) return false;
+			return (await this.validateInternal()).status === "valid";
+		},
 		getAccessToken: async () => (await this.resolve())?.token ?? null,
 		getUserInfo: async () => this.resolve(),
 		login: async () => {},
 		logout: async () => this.invalidate(),
+		validate: () => this.validateInternal(),
+		invalidate: () => this.markStale(),
 		onAuthStateChanged: (listener) => this.on(listener)
 	};
-	/** Spec §6.2 resolution order: host → pushed → persisted → null. */
+	/**
+	* Spec §6.2 resolution order: host → pushed → persisted → null.
+	*
+	* Host mode is STRICT: an enabled host is the single source of truth. If the
+	* host yields no credential, the operator is unauthenticated — we must NOT
+	* fall back to a pushed/persisted credential left behind by an earlier
+	* 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.
+	*/
 	async resolve() {
 		if (this.host.enabled) {
 			const host = await this.host.resolve();
 			if (host) return toUserInfo(host);
+			return null;
 		}
 		if (this.current) return this.current;
 		return readPersisted();
 	}
+	/** Spec §7: resolve → local expiry → remote validation → update state. */
+	async validateInternal() {
+		const info = await this.resolve();
+		if (!info) {
+			this.stale = true;
+			return {
+				status: "invalid",
+				reason: "invalid"
+			};
+		}
+		if (this.validator.isLocallyExpired(info.expiresAt)) {
+			this.validator.invalidate(info.token);
+			this.stale = true;
+			return {
+				status: "invalid",
+				reason: "expired"
+			};
+		}
+		const result = await this.validator.validate(info.token, { expiresAt: info.expiresAt });
+		if (result.status === "valid") this.stale = false;
+		else if (result.status === "invalid") this.stale = true;
+		return result;
+	}
+	/** Validation-scoped invalidation: keep the credential, drop cached validity. */
+	markStale() {
+		this.stale = true;
+		this.validator.invalidate();
+	}
 	setCredentials(info) {
 		this.current = info;
-		writePersisted(info);
+		this.stale = false;
+		this.validator.invalidate();
+		if (!this.hostMode) writePersisted(info);
 		this.emit();
 	}
 	invalidate() {
 		const was = this.host.enabled || this.current !== null || readPersisted() !== null;
 		this.current = null;
 		this.host.clear();
+		this.stale = true;
+		this.validator.invalidate();
 		deletePersisted();
 		if (was) this.emit();
 	}
@@ -225,10 +422,12 @@ function normalizeUserInfo(data) {
 	const id = typeof data.userId === "string" && data.userId.length > 0 ? data.userId : typeof data.userId === "number" && Number.isFinite(data.userId) ? String(data.userId) : typeof data.id === "string" && data.id.length > 0 ? data.id : typeof data.id === "number" && Number.isFinite(data.id) ? String(data.id) : null;
 	if (!token || !id) return null;
 	const nickname = typeof data.nickname === "string" && data.nickname.length > 0 ? data.nickname : void 0;
+	const expiresAt = typeof data.expiresAt === "number" && Number.isFinite(data.expiresAt) ? data.expiresAt : void 0;
 	return {
 		id,
 		token,
-		...nickname ? { nickname } : {}
+		...nickname ? { nickname } : {},
+		...expiresAt !== void 0 ? { expiresAt } : {}
 	};
 }
 function createAuthHandler(service) {
@@ -255,7 +454,7 @@ function createAuthHandler(service) {
 			if (req.method === "GET" && pathname === `/api/v1/huaqiu/auth/session`) {
 				const user = await service.auth.getUserInfo();
 				sendJson(res, 200, {
-					authenticated: service.auth.isAuthenticated(),
+					authenticated: await service.auth.isAuthenticated(),
 					user
 				});
 				return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-auth",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",

package/src/client/transport.ts

@@ -30,6 +30,7 @@ export function createWebServerAuthTransport(
           token: info.token,
           userId: info.id,
           ...(info.nickname !== undefined ? { nickname: info.nickname } : {}),
+          ...(info.expiresAt !== undefined ? { expiresAt: info.expiresAt } : {}),
         }),
       })
       if (!res.ok) throw new Error(`auth push failed: HTTP ${res.status}`)

package/src/host.ts

@@ -27,10 +27,13 @@ export interface HuaqiuAuthConfig {
   hostAuthPath?: string
   /** Seconds a host session is reused before re-fetching. Default 300. */
   hostSessionTtlSeconds?: number
+  /** Seconds remote token-validation results are cached. Default 60. */
+  validationTtlSeconds?: number
 }
 
 export const DEFAULT_HOST_AUTH_PATH = '/api/v1/auth/token'
 export const DEFAULT_HOST_TTL_SECONDS = 300
+export const DEFAULT_VALIDATION_TTL_SECONDS = 60
 
 /**
  * Resolve the effective config: overlay `config` (highest) > env (safety net
@@ -55,7 +58,20 @@ export function resolveHostConfig(
     const parsed = Number.parseInt(ttlRaw, 10)
     if (Number.isFinite(parsed) && parsed > 0) ttl = parsed
   }
-  return { hqEdgeBaseUrl: baseUrl, hostAuthPath, hostSessionTtlSeconds: ttl }
+  const vTtlRaw = config?.validationTtlSeconds ?? env.HQ_EDGE_VALIDATION_TTL_SECONDS
+  let validationTtlSeconds = DEFAULT_VALIDATION_TTL_SECONDS
+  if (typeof vTtlRaw === 'number' && Number.isFinite(vTtlRaw) && vTtlRaw > 0) {
+    validationTtlSeconds = vTtlRaw
+  } else if (typeof vTtlRaw === 'string' && vTtlRaw.trim().length > 0) {
+    const parsed = Number.parseInt(vTtlRaw, 10)
+    if (Number.isFinite(parsed) && parsed > 0) validationTtlSeconds = parsed
+  }
+  return {
+    hqEdgeBaseUrl: baseUrl,
+    hostAuthPath,
+    hostSessionTtlSeconds: ttl,
+    validationTtlSeconds,
+  }
 }
 
 export interface HostSession {

package/src/routes.ts

@@ -2,7 +2,7 @@
  * HTTP adapter: receives the browser-pushed credentials and serves the node
  * auth state (probe / boot restore). Same-origin through `ctx.webServer`:
  *
- *   POST /api/v1/huaqiu/auth/session   body { token, userInfo? }  → cache set
+ *   POST /api/v1/huaqiu/auth/session   body { token, userId, nickname?, expiresAt? } → cache set
  *   POST /api/v1/huaqiu/auth/logout                                → cache cleared
  *   GET  /api/v1/huaqiu/auth/session   → { authenticated, user }
  *   GET  /api/v1/huaqiu/auth/config    → { hostMode }
@@ -45,7 +45,15 @@ function normalizeUserInfo(data: Record<string, unknown>): HuaqiuUserInfo | null
     : null
   if (!token || !id) return null
   const nickname = typeof data.nickname === 'string' && data.nickname.length > 0 ? data.nickname : undefined
-  return { id, token, ...(nickname ? { nickname } : {}) }
+  const expiresAt = typeof data.expiresAt === 'number' && Number.isFinite(data.expiresAt)
+    ? data.expiresAt
+    : undefined
+  return {
+    id,
+    token,
+    ...(nickname ? { nickname } : {}),
+    ...(expiresAt !== undefined ? { expiresAt } : {}),
+  }
 }
 
 export function createAuthHandler(service: HuaqiuAuthService): AuthHandler {
@@ -75,7 +83,7 @@ export function createAuthHandler(service: HuaqiuAuthService): AuthHandler {
 
       if (req.method === 'GET' && pathname === `${AUTH_ROUTE_PREFIX}/session`) {
         const user = await service.auth.getUserInfo()
-        const authenticated = service.auth.isAuthenticated()
+        const authenticated = await service.auth.isAuthenticated()
         sendJson(res, 200, { authenticated, user })
         return
       }

package/src/service.ts

@@ -29,26 +29,52 @@ import {
   type HuaqiuAuthConfig,
   type ResolvedHostUser,
 } from './host.js'
+import { TokenValidator, type AuthValidationResult } from './validation.js'
 
 export interface HuaqiuUserInfo {
   id: string
   token: string
   nickname?: string
+  /** Unix seconds; known for browser-pushed sessions (auth.eda.cn window). */
+  expiresAt?: number
 }
 
 export interface HuaqiuAuthApi {
-  isAuthenticated(): boolean
+  /**
+   * Authoritative async check: a credential exists AND is known to be valid
+   * (local expiry + cached remote validation). Never a mere token-presence
+   * check — a host token supplied by hq-edge is not assumed valid just because
+   * it exists (spec §10). Short-circuits to `false` after `invalidate()` until
+   * re-validated or a fresh credential arrives.
+   */
+  isAuthenticated(): Promise<boolean>
   getAccessToken(): Promise<string | null>
   getUserInfo(): Promise<HuaqiuUserInfo | null>
   /** Node-side no-op: login always happens in the browser. */
   login(): Promise<void>
   logout(): Promise<void>
+  /**
+   * Single authoritative validation path (spec §7). Works identically for
+   * standalone and host credentials; never depends on hq-edge.
+   */
+  validate(): Promise<AuthValidationResult>
+  /**
+   * Mark the current credential's validation state stale without deleting the
+   * credential (kept for recovery). Next validation cannot reuse a previous
+   * "valid" result (spec §9/§11). Call this when an API request returns 401.
+   */
+  invalidate(): void
   onAuthStateChanged(listener: (info: HuaqiuUserInfo | null) => void): () => void
 }
 
 export interface HuaqiuAuthService {
   auth: HuaqiuAuthApi
-  /** Node-only setters used by the webServer route handlers. */
+  /**
+   * Node-only setters used by the webServer route handlers.
+   * NOTE: `service.invalidate()` is the FULL reset (logout: drops the pushed
+   * credential, persisted file and host cache). The capability-level
+   * `auth.invalidate()` is validation-scoped and keeps the credential.
+   */
   setCredentials(info: HuaqiuUserInfo): void
   invalidate(): void
   /**
@@ -79,7 +105,15 @@ function readPersisted(): HuaqiuUserInfo | null {
     const nickname = typeof raw.nickname === 'string' && raw.nickname.length > 0
       ? raw.nickname
       : undefined
-    return { id, token, ...(nickname ? { nickname } : {}) }
+    const expiresAt = typeof raw.expiresAt === 'number' && Number.isFinite(raw.expiresAt)
+      ? raw.expiresAt
+      : undefined
+    return {
+      id,
+      token,
+      ...(nickname ? { nickname } : {}),
+      ...(expiresAt !== undefined ? { expiresAt } : {}),
+    }
   } catch {
     return null
   }
@@ -111,6 +145,13 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
   private current: HuaqiuUserInfo | null = null
   private listeners = new Set<(info: HuaqiuUserInfo | null) => void>()
   private readonly host: HostSessionResolver
+  private readonly validator: TokenValidator
+  /**
+   * True once the current credential has been rejected (API 401) or explicitly
+   * invalidated. Keeps the credential for recovery but makes `isAuthenticated()`
+   * short-circuit to false and forces a fresh remote validation next time.
+   */
+  private stale = false
 
   constructor(
     config?: Partial<HuaqiuAuthConfig> | null,
@@ -123,6 +164,10 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
       (resolved.hostSessionTtlSeconds ?? 300) * 1000,
       opts?.fetchImpl,
     )
+    this.validator = new TokenValidator({
+      ttlMs: (resolved.validationTtlSeconds ?? 60) * 1000,
+      fetchImpl: opts?.fetchImpl,
+    })
     this.hostMode = this.host.enabled
   }
 
@@ -130,29 +175,77 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
   readonly hostMode: boolean
 
   readonly auth: HuaqiuAuthApi = {
-    isAuthenticated: () => this.host.enabled || this.current !== null || readPersisted() !== null,
+    isAuthenticated: async () => {
+      if (this.stale) return false
+      return (await this.validateInternal()).status === 'valid'
+    },
     getAccessToken: async () => (await this.resolve())?.token ?? null,
     getUserInfo: async () => this.resolve(),
     login: async () => {
       /* login is a browser action */
     },
     logout: async () => this.invalidate(),
+    validate: () => this.validateInternal(),
+    invalidate: () => this.markStale(),
     onAuthStateChanged: (listener) => this.on(listener),
   }
 
-  /** Spec §6.2 resolution order: host → pushed → persisted → null. */
+  /**
+   * Spec §6.2 resolution order: host → pushed → persisted → null.
+   *
+   * Host mode is STRICT: an enabled host is the single source of truth. If the
+   * host yields no credential, the operator is unauthenticated — we must NOT
+   * fall back to a pushed/persisted credential left behind by an earlier
+   * 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.
+   */
   private async resolve(): Promise<HuaqiuUserInfo | null> {
     if (this.host.enabled) {
       const host = await this.host.resolve()
       if (host) return toUserInfo(host)
+      return null
     }
     if (this.current) return this.current
     return readPersisted()
   }
 
+  /** Spec §7: resolve → local expiry → remote validation → update state. */
+  private async validateInternal(): Promise<AuthValidationResult> {
+    const info = await this.resolve()
+    if (!info) {
+      this.stale = true
+      return { status: 'invalid', reason: 'invalid' }
+    }
+    // Local expiry is an optimization; remote validation stays authoritative.
+    if (this.validator.isLocallyExpired(info.expiresAt)) {
+      this.validator.invalidate(info.token)
+      this.stale = true
+      return { status: 'invalid', reason: 'expired' }
+    }
+    const result = await this.validator.validate(info.token, { expiresAt: info.expiresAt })
+    if (result.status === 'valid') this.stale = false
+    else if (result.status === 'invalid') this.stale = true
+    // 'unavailable' leaves the stale flag untouched — a network blip never
+    // declares the credential invalid (spec §17).
+    return result
+  }
+
+  /** Validation-scoped invalidation: keep the credential, drop cached validity. */
+  private markStale(): void {
+    this.stale = true
+    this.validator.invalidate()
+  }
+
   setCredentials(info: HuaqiuUserInfo): void {
     this.current = info
-    void writePersisted(info)
+    this.stale = false
+    this.validator.invalidate()
+    // Never persist to the standalone store while running under a host: the
+    // host (hq-edge) owns the credential in host mode, and a stale standalone
+    // session must not leak across modes. Persistence is only meaningful in
+    // standalone (silent-login restore).
+    if (!this.hostMode) void writePersisted(info)
     this.emit()
   }
 
@@ -160,6 +253,8 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
     const was = this.host.enabled || this.current !== null || readPersisted() !== null
     this.current = null
     this.host.clear()
+    this.stale = true
+    this.validator.invalidate()
     deletePersisted()
     if (was) this.emit()
   }