@huaqiu/dsh-auth 0.1.1 → 0.2.0

package/src/service.ts

@@ -29,28 +29,62 @@ 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
+  /**
+   * True when running in HQ Edge host mode (a host base URL was configured —
+   * overlay `config.hqEdgeBaseUrl` or `HQ_EDGE_BASE_URL`). The browser half
+   * reads this over the webServer config route to decide whether the sidebar
+   * login entrypoint is needed: in host mode EDA hands the credential to
+   * hq-edge, so the auth plugin's own login UI is suppressed.
+   */
+  readonly hostMode: boolean
 }
 
 const PERSIST_FILE = 'session.json'
@@ -71,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
   }
@@ -103,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,
@@ -115,20 +164,37 @@ 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
   }
 
+  /** Host mode is active iff a host base URL was configured (see HostSessionResolver.enabled). */
+  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.
+   * Returns the credential regardless of validation state (recovery keeps the
+   * value; `validate()`/`isAuthenticated()` decide whether it is usable).
+   */
   private async resolve(): Promise<HuaqiuUserInfo | null> {
     if (this.host.enabled) {
       const host = await this.host.resolve()
@@ -138,8 +204,37 @@ export class InMemoryHuaqiuAuthService implements HuaqiuAuthService {
     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
+    this.stale = false
+    this.validator.invalidate()
     void writePersisted(info)
     this.emit()
   }
@@ -148,6 +243,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()
   }

package/src/validation.ts

@@ -0,0 +1,182 @@
+/**
+ * Token validation for `@huaqiu/dsh-auth`.
+ *
+ * Single authoritative validation path shared by standalone (auth.eda.cn) and
+ * HQ Edge host credentials. Uses the existing Huaqiu endpoint
+ *
+ *   GET https://www.eda.cn/api/token/validate?token=<token>
+ *   → { code, message, result: boolean }
+ *
+ * (the same endpoint consumed by `NextChat/app/auth/is_token_valid.ts`; probe:
+ *   `curl "https://www.eda.cn/api/token/validate?token=__dummy__"` → 200
+ *   `{"code":200000,"message":"success","result":false}`).
+ *
+ * Local expiry is a cheap pre-check only (never authoritative). Remote
+ * validation is authoritative, short-lived in-memory cached, and never
+ * persisted. Network / 5xx failures are reported as `unavailable` — they are
+ * NOT converted into "token invalid", so a transient network blip never forces
+ * the user to log in again.
+ */
+/**
+ * Outcome of an authoritative token validation.
+ *
+ * - `valid`       — the Huaqiu API accepted the token.
+ * - `invalid`     — the token is definitively rejected/expired.
+ * - `unavailable` — validation could not be performed (network/5xx); the token
+ *                   is NOT declared invalid (spec §17/§18).
+ */
+export type AuthValidationResult =
+  | { status: 'valid'; userId?: string; expiresAt?: number }
+  | { status: 'invalid'; reason: 'expired' | 'unauthorized' | 'forbidden' | 'invalid' }
+  | { status: 'unavailable'; error: Error }
+
+/** Default remote validation TTL — spec §8 (30–60s); 60s chosen. */
+export const DEFAULT_VALIDATION_TTL_MS = 60_000
+/** Existing Huaqiu token-validation endpoint (see header). */
+export const DEFAULT_VALIDATE_URL = 'https://www.eda.cn/api/token/validate'
+
+export interface TokenValidatorOptions {
+  /** Remote-validation cache TTL in ms. Default `DEFAULT_VALIDATION_TTL_MS`. */
+  ttlMs?: number
+  /** Validation endpoint. Default `DEFAULT_VALIDATE_URL`. */
+  validateUrl?: string
+  /** Injectable fetch (tests). Defaults to global fetch. */
+  fetchImpl?: typeof fetch
+  /** Injectable clock (tests). Defaults to Date.now. */
+  now?: () => number
+}
+
+interface ValidationCacheEntry {
+  result: AuthValidationResult
+  at: number
+}
+
+/**
+ * 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: number): AuthValidationResult {
+  if (status === 401) return { status: 'invalid', reason: 'unauthorized' }
+  if (status === 403) return { status: 'invalid', reason: 'forbidden' }
+  return { status: 'unavailable', error: new Error(`token validation HTTP ${status}`) }
+}
+
+export class TokenValidator {
+  private readonly ttlMs: number
+  private readonly validateUrl: string
+  private readonly fetchImpl: typeof fetch
+  private readonly now: () => number
+  /** token → { result, at }; in-memory only, never persisted (spec §8). */
+  private readonly cache = new Map<string, ValidationCacheEntry>()
+  /** token → in-flight promise; coalesces concurrent validate() calls (§16). */
+  private readonly inFlight = new Map<string, Promise<AuthValidationResult>>()
+
+  constructor(options: TokenValidatorOptions = {}) {
+    this.ttlMs = options.ttlMs ?? DEFAULT_VALIDATION_TTL_MS
+    this.validateUrl = options.validateUrl ?? DEFAULT_VALIDATE_URL
+    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?: number): boolean {
+    if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) return false
+    return expiresAt * 1000 <= 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: string, session?: { expiresAt?: number }): Promise<AuthValidationResult> {
+    if (!token) return { status: 'invalid', reason: 'invalid' }
+
+    // Local expiry first — no remote call (spec §6/§7).
+    if (this.isLocallyExpired(session?.expiresAt)) {
+      this.cache.delete(token)
+      return { status: 'invalid', reason: 'expired' }
+    }
+
+    // Fresh cache hit within TTL.
+    const cached = this.cache.get(token)
+    if (cached && this.now() - cached.at < this.ttlMs) {
+      return cached.result
+    }
+
+    // Reuse an in-flight request instead of stacking duplicates (§16).
+    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?: string): void {
+    if (token === undefined) {
+      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: string): AuthValidationResult | null {
+    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
+  }
+
+  private async validateRemotely(token: string): Promise<AuthValidationResult> {
+    const url = `${this.validateUrl}?token=${encodeURIComponent(token)}`
+    let res: Response
+    try {
+      res = await this.fetchImpl(url, {
+        method: 'GET',
+        headers: { accept: 'application/json' },
+      })
+    } catch (err) {
+      // Network failure — NOT "token invalid" (spec §17). Do not force a login
+      // merely because the network is temporarily unavailable.
+      return { status: 'unavailable', error: err as Error }
+    }
+
+    if (!res.ok) return classifyStatus(res.status)
+
+    let body: unknown
+    try {
+      body = await res.json()
+    } catch (err) {
+      return { status: 'unavailable', error: new Error(`token validation: unparseable response (${String(err)})`) }
+    }
+
+    const result = typeof body === 'object' && body !== null
+      ? (body as Record<string, unknown>).result
+      : undefined
+    if (result === true) {
+      return { status: 'valid' }
+    }
+    // 2xx but the token is not accepted (`result` missing/false).
+    return { status: 'invalid', reason: 'unauthorized' }
+  }
+}