@huaqiu/dsh-auth 0.1.1

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

@@ -0,0 +1,395 @@
+/**
+ * `sidebar.footer.action` entry: the Huaqiu EDA account trigger at the bottom
+ * of the DSH sidebar (beside Settings).
+ *
+ * - Not logged in: shows the HQ icon and opens the login dialog through
+ *   `auth.login({ lang, theme })` — a real modal (backdrop + centered card +
+ *   auth.eda.cn iframe) that is ALWAYS TRANSPARENT in the embed itself
+ *   (`fill=full` is never sent, see `lib.ts#buildLoginUrl`), and the card
+ *   surface masks Blink's white base canvas so the login card floats over
+ *   the dimmed app in both light and dark themes. `lang`/`theme` follow the
+ *   host UI. Click on the backdrop, the × button, or Escape closes it, and
+ *   auth.eda.cn's own `close_dialog` postMessage closes it as well.
+ * - Logged in: the trigger becomes the user's AVATAR (`headimage` from the
+ *   auth.eda.cn payload, HQ icon while it is missing/fails to load) and a click
+ *   opens a context menu with「Go to profile」(the eda.cn account page, with
+ *   the access token) and「Log out」— the same shape as `hq-eda-ai`'s
+ *   `UserMenu`, portalled to `document.body` with fixed positioning so the
+ *   sidebar's `overflow: hidden` can never clip it.
+ *
+ * THEMING: colors prefer DSH's `--dsw-alias-*` tokens (so a custom host theme
+ * is honored) and fall back to an explicit light/dark pair chosen from
+ * `useIsDark()`; the two paths cannot disagree, because ui-layout's presenter
+ * writes `body[data-ds-dark-theme]` from the very snapshot that installs those
+ * tokens.
+ */
+import { memo, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore, type CSSProperties } from 'react'
+import { createPortal } from 'react-dom'
+import { getAuth, getAuthState, subscribeAuth } from '../auth-state.js'
+import { buildProfileUrl } from '../lib.js'
+import { useIsDark, useLocale } from '../ui-env.js'
+import { useT } from '../i18n.js'
+import { HQ_ICON } from './hq-icon.jsx'
+
+export interface SidebarFooterActionOwnerProps {
+  wide?: boolean
+}
+
+const AVATAR_SIZE = 26
+const ICON_SIZE = 22
+
+/** One color scheme's menu colors (DSH token first, explicit fallback second). */
+interface Palette {
+  surface: string
+  border: string
+  text: string
+  muted: string
+  hover: string
+  danger: string
+  dangerHover: string
+  avatarBg: string
+  shadow: string
+}
+
+const LIGHT_PALETTE: Palette = {
+  surface: 'var(--dsw-alias-bg-overlay, #ffffff)',
+  border: 'var(--dsw-alias-border-l1, #e4e7ec)',
+  text: 'var(--dsw-alias-label-primary, #3a4356)',
+  muted: 'var(--dsw-alias-label-secondary, #8a94a6)',
+  hover: 'var(--dsw-alias-interactive-bg-hover, #f5f7fa)',
+  danger: 'var(--dsw-alias-state-error-primary, #d4380d)',
+  dangerHover: 'rgba(216, 56, 13, 0.08)',
+  avatarBg: 'var(--dsw-alias-bg-layer-2, #eef2f7)',
+  shadow: '0 12px 32px rgba(15, 23, 42, 0.16)',
+}
+
+const DARK_PALETTE: Palette = {
+  surface: 'var(--dsw-alias-bg-overlay, #20242c)',
+  border: 'var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.14))',
+  text: 'var(--dsw-alias-label-primary, #e6eaf0)',
+  muted: 'var(--dsw-alias-label-secondary, #8b95a5)',
+  hover: 'var(--dsw-alias-interactive-bg-hover, rgba(255, 255, 255, 0.08))',
+  danger: 'var(--dsw-alias-state-error-primary, #ff7875)',
+  dangerHover: 'rgba(255, 120, 117, 0.14)',
+  avatarBg: 'var(--dsw-alias-bg-layer-2, rgba(255, 255, 255, 0.10))',
+  shadow: '0 12px 32px rgba(0, 0, 0, 0.46)',
+}
+
+const TRIGGER_BASE: CSSProperties = {
+  width: '100%',
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+  padding: '8px 12px',
+  border: 'none',
+  borderRadius: 8,
+  background: 'transparent',
+  fontSize: 13,
+  fontWeight: 500,
+  cursor: 'pointer',
+  textAlign: 'left',
+  whiteSpace: 'nowrap',
+  overflow: 'hidden',
+}
+
+const MENU_BASE: CSSProperties = {
+  position: 'fixed',
+  zIndex: 2147483000,
+  minWidth: 184,
+  padding: 6,
+  borderWidth: 1,
+  borderStyle: 'solid',
+  borderRadius: 12,
+  fontFamily: 'inherit',
+  fontSize: 13,
+}
+
+const MENU_HEADER_BASE: CSSProperties = {
+  padding: '6px 10px 8px',
+  fontSize: 12,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+}
+
+const MENU_ITEM_BASE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+  width: '100%',
+  padding: '8px 10px',
+  border: 'none',
+  borderRadius: 8,
+  background: 'transparent',
+  font: 'inherit',
+  fontSize: 13,
+  textAlign: 'left',
+  cursor: 'pointer',
+}
+
+/**
+ * One menu row. Hover is tracked in state: the client bundle ships no CSS
+ * file, so inline styles cannot express `:hover`.
+ */
+function MenuItem({
+  label,
+  icon,
+  danger,
+  palette,
+  onSelect,
+}: {
+  label: string
+  icon: React.JSX.Element
+  danger?: boolean
+  palette: Palette
+  onSelect: () => void
+}): React.JSX.Element {
+  const [hovered, setHovered] = useState(false)
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      style={{
+        ...MENU_ITEM_BASE,
+        color: danger ? palette.danger : palette.text,
+        background: hovered ? (danger ? palette.dangerHover : palette.hover) : 'transparent',
+      }}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      onClick={onSelect}
+    >
+      {icon}
+      <span>{label}</span>
+    </button>
+  )
+}
+
+function UserIcon(): React.JSX.Element {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={15}
+      height={15}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      style={{ flex: '0 0 auto' }}
+    >
+      <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" />
+      <circle cx="12" cy="7" r="4" />
+    </svg>
+  )
+}
+
+function LogoutIcon(): React.JSX.Element {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={15}
+      height={15}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      style={{ flex: '0 0 auto' }}
+    >
+      <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" />
+      <polyline points="16 17 21 12 16 7" />
+      <line x1="21" x2="9" y1="12" y2="12" />
+    </svg>
+  )
+}
+
+export const HuaqiuAuthSidebarAction = memo(function HuaqiuAuthSidebarAction({ wide }: SidebarFooterActionOwnerProps): React.JSX.Element | null {
+  const authState = useSyncExternalStore(subscribeAuth, getAuthState)
+  const auth = getAuth()
+  const dark = useIsDark()
+  const locale = useLocale()
+  const t = useT()
+  const [menuOpen, setMenuOpen] = useState(false)
+  const [menuStyle, setMenuStyle] = useState<CSSProperties | null>(null)
+  const [avatarBroken, setAvatarBroken] = useState(false)
+  const [hovered, setHovered] = useState(false)
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const menuRef = useRef<HTMLDivElement | null>(null)
+
+  const palette = dark ? DARK_PALETTE : LIGHT_PALETTE
+  const authenticated = authState.authenticated
+  const avatar = authenticated && !avatarBroken ? authState.avatar : undefined
+  const showLabel = wide !== false
+
+  // A new avatar URL is a fresh chance to render it.
+  useEffect(() => {
+    setAvatarBroken(false)
+  }, [authState.avatar])
+
+  // Logging out (from anywhere: menu, another tab surface, node invalidation)
+  // must never leave an orphan menu pointing at a signed-out account.
+  useEffect(() => {
+    if (!authenticated) setMenuOpen(false)
+  }, [authenticated])
+
+  // Anchor the portalled menu to the trigger before paint: the sidebar footer
+  // sits at the bottom edge, so the menu grows UPWARD from the trigger's top.
+  useLayoutEffect(() => {
+    if (!menuOpen || !triggerRef.current) return
+    const rect = triggerRef.current.getBoundingClientRect()
+    setMenuStyle({
+      ...MENU_BASE,
+      background: palette.surface,
+      borderColor: palette.border,
+      color: palette.text,
+      boxShadow: palette.shadow,
+      left: Math.max(8, Math.round(rect.left)),
+      bottom: Math.max(8, Math.round(window.innerHeight - rect.top + 8)),
+      ...(wide ? { width: Math.round(rect.width) } : {}),
+    })
+  }, [menuOpen, wide, avatar, palette])
+
+  // Close on: outside click, Escape, resize or scroll (the anchor moved).
+  useEffect(() => {
+    if (!menuOpen) return
+    const onPointerDown = (event: MouseEvent): void => {
+      const target = event.target as Node
+      if (triggerRef.current?.contains(target)) return
+      if (menuRef.current?.contains(target)) return
+      setMenuOpen(false)
+    }
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') setMenuOpen(false)
+    }
+    const dismiss = (): void => setMenuOpen(false)
+    document.addEventListener('mousedown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    window.addEventListener('resize', dismiss)
+    window.addEventListener('scroll', dismiss, true)
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+      window.removeEventListener('resize', dismiss)
+      window.removeEventListener('scroll', dismiss, true)
+    }
+  }, [menuOpen])
+
+  if (!auth) return null
+
+  /**
+   *「Go to profile」always carries the token, so eda.cn can establish the
+   * session in the opened tab (it hides the token itself — see
+   * `lib.ts#buildProfileUrl`). The snapshot normally has it; fall back to the
+   * client so a stale snapshot can never open an unauthenticated tab.
+   */
+  const openProfile = (): void => {
+    setMenuOpen(false)
+    void (async () => {
+      const info = authState.token
+        ? { token: authState.token, phone: authState.phone }
+        : await auth.getUserInfo()
+            .then((i) => (i ? { token: i.token, phone: i.phone } : null))
+            .catch(() => null)
+      if (!info?.token) return
+      window.open(buildProfileUrl(info), '_blank', 'noopener,noreferrer')
+    })()
+  }
+
+  const label = authenticated
+    ? (authState.nickname ?? t('sidebar.account'))
+    : t('sidebar.login')
+
+  const title = authenticated ? t('sidebar.accountTitle') : t('sidebar.loginTitle')
+  const triggerBackground = menuOpen || hovered ? palette.hover : 'transparent'
+
+  return (
+    <div style={{ position: 'relative', width: '100%' }}>
+      <button
+        ref={triggerRef}
+        type="button"
+        aria-haspopup="menu"
+        aria-expanded={menuOpen}
+        onClick={() => {
+          if (!authenticated) {
+            // Always-transparent embed in the host's language and color scheme;
+            // `closeOnOutsideClick` defaults to true. The login dialog owns
+            // the DOM (backdrop + card + iframe) and closes itself on
+            // backdrop click, Escape, the × button, or the embed's
+            // `close_dialog` postMessage.
+            void auth.login({ lang: locale, theme: dark ? 'dark' : 'light' })
+            return
+          }
+          setMenuOpen((open) => !open)
+        }}
+        onMouseEnter={() => setHovered(true)}
+        onMouseLeave={() => setHovered(false)}
+        style={{
+          ...TRIGGER_BASE,
+          color: palette.text,
+          padding: wide ? '8px 12px' : '8px 6px',
+          background: triggerBackground,
+        }}
+        title={title}
+      >
+        {avatar ? (
+          <span
+            style={{
+              flex: '0 0 auto',
+              width: AVATAR_SIZE,
+              height: AVATAR_SIZE,
+              borderRadius: '50%',
+              overflow: 'hidden',
+              background: palette.avatarBg,
+              display: 'block',
+            }}
+          >
+            <img
+              src={avatar}
+              alt=""
+              width={AVATAR_SIZE}
+              height={AVATAR_SIZE}
+              onError={() => setAvatarBroken(true)}
+              style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}
+            />
+          </span>
+        ) : (
+          <HQ_ICON size={ICON_SIZE} />
+        )}
+        {showLabel ? (
+          <span style={{ overflow: 'hidden', textOverflow: 'ellipsis' }}>{label}</span>
+        ) : null}
+      </button>
+
+      {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>
+              ) : null}
+              <MenuItem
+                label={t('menu.profile')}
+                icon={<UserIcon />}
+                palette={palette}
+                onSelect={openProfile}
+              />
+              <MenuItem
+                label={t('menu.logout')}
+                icon={<LogoutIcon />}
+                danger
+                palette={palette}
+                onSelect={() => {
+                  setMenuOpen(false)
+                  void auth.logout()
+                }}
+              />
+            </div>,
+            document.body,
+          )
+        : null}
+    </div>
+  )
+})

package/src/client/ui-env.ts

@@ -0,0 +1,175 @@
+/**
+ * Host theme + locale sensing for the client UI.
+ *
+ * The DSH slot system injects React components with PROPS, not the cordis ctx,
+ * so the cards cannot reach `ctx.theme` / `ctx.locale` the way a plugin body
+ * can. Both services do, however, publish their state into the DOM, and that
+ * is what this module reads:
+ *
+ * - THEME — `ui-layout`'s presenter switches `body[data-ds-dark-theme]` from
+ *   the resolved snapshot (`packages/client/ui-layout/src/client/theme-presenter.ts`,
+ *   `DARK_ATTRIBUTE`), so the attribute's presence IS the dark palette. Same
+ *   signal the sibling packages already use
+ *   (`dsh-tool-schematic-gen/src/client/theme.ts`). `prefers-color-scheme` is
+ *   deliberately NOT consulted: DSH resolves `system` itself, and an OS-dark /
+ *   DSH-light combination would then be misdetected.
+ * - LOCALE — `dsh-client-locale` writes `<html lang>` on every locale change
+ *   (`syncDocumentLanguage`: `zh-CN` | `en`). Falling back to the browser's
+ *   own `navigator.languages` keeps the UI usable on hosts without that
+ *   plugin. Chinese is the last resort because this is a Chinese-first app
+ *   (and `hq-eda-ai` defaults to zh: `languageMap[lang] || "zh"`).
+ *
+ * Both are exposed as `useSyncExternalStore` snapshots so every mounted card
+ * re-renders together when the user flips theme or language.
+ */
+import { useSyncExternalStore } from 'react'
+import type { AuthLocale, AuthTheme } from './lib.js'
+
+/** DSH's dark-palette marker, written by ui-layout's theme presenter. */
+export const DARK_ATTRIBUTE = 'data-ds-dark-theme'
+
+function isDarkDocument(): boolean {
+  if (typeof document === 'undefined') return false
+  if (document.body?.hasAttribute(DARK_ATTRIBUTE)) return true
+  // Fallbacks for hosts that mark the scheme on <html> instead of <body>.
+  const root = document.documentElement
+  if (!root) return false
+  const dataTheme = root.getAttribute('data-theme')
+  if (dataTheme !== null) return dataTheme.toLowerCase() === 'dark'
+  return root.classList.contains('dark')
+}
+
+/** `zh-CN`, `zh-Hans`, `en-GB`, … → our locale id (`undefined` = unknown). */
+function localeFromTag(tag: string | null | undefined): AuthLocale | undefined {
+  if (!tag) return undefined
+  const primary = tag.toLowerCase().split('-')[0]
+  return primary === 'zh' || primary === 'en' ? primary : undefined
+}
+
+function detectLocale(): AuthLocale {
+  if (typeof document !== 'undefined') {
+    const fromDocument = localeFromTag(document.documentElement?.getAttribute('lang'))
+    if (fromDocument) return fromDocument
+  }
+  if (typeof navigator !== 'undefined' && typeof window !== 'undefined') {
+    // `window` is the browser test: Node exposes a global `navigator`
+    // reporting the machine's own language, which would otherwise decide the
+    // locale for non-browser runs (same guard DSH's locale plugin uses).
+    for (const tag of [...(navigator.languages ?? []), navigator.language]) {
+      const match = localeFromTag(tag)
+      if (match) return match
+    }
+  }
+  return 'zh'
+}
+
+let dark = isDarkDocument()
+let locale = detectLocale()
+const listeners = new Set<() => void>()
+let darkObserver: MutationObserver | null = null
+let localeObserver: MutationObserver | null = null
+
+function notify(): void {
+  for (const listener of [...listeners]) {
+    try {
+      listener()
+    } catch {
+      /* one crashing subscriber must not strand the rest on a stale value */
+    }
+  }
+}
+
+/** Re-read the DOM and notify only what actually changed. */
+export function syncUiEnv(): void {
+  let changed = false
+  const nextDark = isDarkDocument()
+  if (nextDark !== dark) {
+    dark = nextDark
+    changed = true
+  }
+  const nextLocale = detectLocale()
+  if (nextLocale !== locale) {
+    locale = nextLocale
+    changed = true
+  }
+  if (changed) notify()
+}
+
+/** Start observing (idempotent; also re-reads so no change is missed). */
+function watch(): void {
+  if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') return
+  if (!darkObserver && document.body) {
+    darkObserver = new MutationObserver(syncUiEnv)
+    darkObserver.observe(document.body, { attributes: true, attributeFilter: [DARK_ATTRIBUTE] })
+  }
+  if (!localeObserver && document.documentElement) {
+    localeObserver = new MutationObserver(syncUiEnv)
+    localeObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['lang', 'data-theme', 'class'],
+    })
+  }
+  syncUiEnv()
+}
+
+function subscribe(callback: () => void): () => void {
+  watch()
+  listeners.add(callback)
+  return () => {
+    listeners.delete(callback)
+  }
+}
+
+/**
+ * Imperative subscription for non-React consumers (e.g. the login dialog's
+ * backdrop/card DOM). The callback fires on every theme or locale flip.
+ */
+export function subscribeUiEnv(callback: () => void): () => void {
+  return subscribe(callback)
+}
+
+const getDark = (): boolean => dark
+const getLocale = (): AuthLocale => locale
+
+/**
+ * Synchronous read of the current dark-palette state. Safe outside React
+ * (the auth client uses it when appending the overlay iframe, before any
+ * component has a chance to subscribe).
+ */
+export function getCurrentDark(): boolean {
+  return dark
+}
+
+/** Synchronous read of the current host UI locale. */
+export function getCurrentLocale(): AuthLocale {
+  return locale
+}
+
+/** Synchronous read of the current host surface color (matches the palette). */
+export function getCurrentSurfaceColor(): string {
+  return dark ? 'var(--dsw-alias-bg-layer-1, #20242c)' : 'var(--dsw-alias-bg-layer-1, #ffffff)'
+}
+
+/** `true` while the host renders the dark palette. */
+export function useIsDark(): boolean {
+  return useSyncExternalStore(subscribe, getDark, getDark)
+}
+
+/** The host UI language. */
+export function useLocale(): AuthLocale {
+  return useSyncExternalStore(subscribe, getLocale, getLocale)
+}
+
+/** The host color scheme in auth.eda.cn's own vocabulary. */
+export function useColorScheme(): AuthTheme {
+  return useIsDark() ? 'dark' : 'light'
+}
+
+/** Release the observers (called from `apply()`'s disposer). */
+export function disposeUiEnv(): void {
+  darkObserver?.disconnect()
+  localeObserver?.disconnect()
+  darkObserver = null
+  localeObserver = null
+  listeners.clear()
+}

package/src/host.ts

@@ -0,0 +1,139 @@
+/**
+ * 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
+ */
+
+export interface HuaqiuAuthConfig {
+  /** HQ Edge base URL, e.g. "http://localhost:18080". Absent → standalone. */
+  hqEdgeBaseUrl?: string
+  /** Path on the host; default "/api/v1/auth/token". */
+  hostAuthPath?: string
+  /** Seconds a host session is reused before re-fetching. Default 300. */
+  hostSessionTtlSeconds?: number
+}
+
+export const DEFAULT_HOST_AUTH_PATH = '/api/v1/auth/token'
+export const DEFAULT_HOST_TTL_SECONDS = 300
+
+/**
+ * Resolve the effective config: overlay `config` (highest) > env (safety net
+ * for non-supervisor installs) > defaults. Centralised here so only `dsh-auth`
+ * inspects these variables (spec §8).
+ */
+export function resolveHostConfig(
+  config?: Partial<HuaqiuAuthConfig> | null,
+  env: NodeJS.ProcessEnv = process.env,
+): HuaqiuAuthConfig {
+  const baseUrl = config?.hqEdgeBaseUrl
+    ?? env.HQ_EDGE_BASE_URL
+    ?? ''
+  const hostAuthPath = config?.hostAuthPath
+    ?? env.HQ_EDGE_AUTH_PATH
+    ?? DEFAULT_HOST_AUTH_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) {
+    ttl = ttlRaw
+  } else if (typeof ttlRaw === 'string' && ttlRaw.trim().length > 0) {
+    const parsed = Number.parseInt(ttlRaw, 10)
+    if (Number.isFinite(parsed) && parsed > 0) ttl = parsed
+  }
+  return { hqEdgeBaseUrl: baseUrl, hostAuthPath, hostSessionTtlSeconds: ttl }
+}
+
+export interface HostSession {
+  info: ResolvedHostUser
+  fetchedAt: number
+}
+
+export interface ResolvedHostUser {
+  id: string
+  token: string
+  nickname?: string
+}
+
+/**
+ * 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.
+ */
+export class HostSessionResolver {
+  private cache: HostSession | null = null
+
+  constructor(
+    readonly baseUrl: string,
+    readonly path: string,
+    readonly ttlMs: number,
+    private readonly doFetch: typeof fetch = globalThis.fetch.bind(globalThis),
+  ) {}
+
+  /** Host mode is active iff a base URL was configured. */
+  get enabled(): boolean {
+    return this.baseUrl.length > 0
+  }
+
+  async resolve(): Promise<ResolvedHostUser | null> {
+    if (!this.enabled) return null
+    const now = Date.now()
+    if (this.cache !== null && now - this.cache.fetchedAt < this.ttlMs) {
+      return this.cache.info
+    }
+    try {
+      const res = await this.doFetch(`${this.baseUrl}${this.path}`, {
+        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
+      this.cache = { info, fetchedAt: now }
+      return info
+    } catch {
+      // Network error: fall back to a previously cached value if we have one.
+      return this.cache?.info ?? null
+    }
+  }
+
+  /** Drop the cached value so the next `resolve()` re-fetches (reactive invalidation). */
+  clear(): void {
+    this.cache = null
+  }
+}
+
+function asId(raw: unknown): string | null {
+  if (typeof raw === 'string' && raw.length > 0) return 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. */
+export function normalizeHostUser(data: Record<string, unknown>): ResolvedHostUser | null {
+  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
+    : undefined
+  return { id, token, ...(nickname ? { nickname } : {}) }
+}