@huaqiu/dsh-auth 0.1.1

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@huaqiu/dsh-auth",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/index.mjs"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.0 <0.2.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": ">=0.1.0-rc.0 <0.2.0"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

package/src/client/auth-state.ts

@@ -0,0 +1,96 @@
+/**
+ * Module-level auth state store shared by the client React components.
+ *
+ * The DSH slot system injects React components with props, not the cordis ctx,
+ * so the components read login state through this tiny external store
+ * (`useSyncExternalStore`), fed by the singleton `huaqiuAuth` client service
+ * created in `apply()`. When the user logs in (in the sidebar overlay or an
+ * embedded card iframe), `onAuthStateChanged` fires and every mounted card /
+ * sidebar button re-renders.
+ */
+import type { AuthClient } from './client.js'
+
+export interface AuthState {
+  authenticated: boolean
+  nickname?: string
+  /** Avatar URL for the sidebar trigger; absent → the HQ icon is shown. */
+  avatar?: string
+  /**
+   * Access token, needed by「Go to profile」(eda.cn takes it from the query
+   * and hides it itself). Kept in the store, never rendered or logged.
+   */
+  token?: string
+  /** Bound mobile number, forwarded to the profile page as `phone=`. */
+  phone?: string
+}
+
+/** Snapshot for one credential payload (`null` = logged out). */
+function stateOf(info: AuthTokenPayloadLike | null): AuthState {
+  if (!info) return { authenticated: false }
+  return {
+    authenticated: true,
+    ...(info.nickname ? { nickname: info.nickname } : {}),
+    ...(info.avatar ? { avatar: info.avatar } : {}),
+    ...(info.token ? { token: info.token } : {}),
+    ...(info.phone ? { phone: info.phone } : {}),
+  }
+}
+
+type AuthTokenPayloadLike = { nickname?: string; avatar?: string; token?: string; phone?: string } | null
+
+let auth: AuthClient['auth'] | null = null
+let state: AuthState = { authenticated: false }
+const listeners = new Set<() => void>()
+let unsubscribe: (() => void) | null = null
+let syncNow: (() => void) | null = null
+
+function setState(next: AuthState): void {
+  state = next
+  for (const l of listeners) l()
+}
+
+/** Attach the singleton auth capability and push the initial snapshot. */
+export function registerAuth(a: AuthClient['auth']): void {
+  auth = a
+  unsubscribe = a.onAuthStateChanged((info) => {
+    setState(stateOf(info))
+  })
+  void a.getUserInfo()
+    .then((info) => setState(stateOf(info)))
+    .catch(() => setState({ authenticated: false }))
+}
+
+/** The live auth capability (for login()/logout() from components). */
+export function getAuth(): AuthClient['auth'] | null {
+  return auth
+}
+
+/** Current snapshot, for `useSyncExternalStore`'s getSnapshot. */
+export function getAuthState(): AuthState {
+  return state
+}
+
+/** Subscribe, for `useSyncExternalStore`'s subscribe. */
+export function subscribeAuth(callback: () => void): () => void {
+  listeners.add(callback)
+  return () => listeners.delete(callback)
+}
+
+/** Register the node re-sync hook (wired in apply(); called by the login card on mount). */
+export function registerAuthSync(fn: () => void): void {
+  syncNow = fn
+}
+
+/** Re-push the persisted credential to the node half, if one is available. */
+export function syncAuthNow(): void {
+  syncNow?.()
+}
+
+export function disposeAuth(): void {
+  unsubscribe?.()
+  unsubscribe = null
+  auth = null
+  syncNow = null
+  listeners.clear()
+  state = { authenticated: false }
+}

package/src/client/client.ts

@@ -0,0 +1,169 @@
+/**
+ * Auth client core — the Phase 0A POC logic, factored as a testable factory.
+ * `apply()` in index.ts wires this to the real window/document/localStorage.
+ */
+import {
+  AUTH_ORIGIN,
+  buildLoginUrl,
+  handleAuthMessage,
+  type AuthMessageEventLike,
+  type AuthTokenPayload,
+  type LoginOptions,
+} from './lib.js'
+import { closeLoginDialog, isLoginDialogOpen, openLoginDialog } from './ui/login-dialog.js'
+import type { AuthStorage } from './storage.js'
+import type { AuthTransport } from './transport.js'
+
+export interface AuthClientDeps {
+  storage: AuthStorage
+  transport: AuthTransport
+  /** Strict origin gate; defaults to auth.eda.cn. */
+  trustedOrigin?: string
+  loginUrl?: string
+  windowLike: Pick<Window, 'addEventListener' | 'removeEventListener'>
+  documentLike: Pick<Document, 'createElement' | 'body'>
+}
+
+export interface AuthClient {
+  auth: {
+    isAuthenticated(): boolean
+    getAccessToken(): Promise<string | null>
+    getUserInfo(): Promise<AuthTokenPayload | null>
+    login(options?: LoginOptions): Promise<void>
+    logout(): Promise<void>
+    onAuthStateChanged(listener: (info: AuthTokenPayload | null) => void): () => void
+  }
+  /** Route window 'message' events here. Exposed for direct testing. */
+  handleMessageEvent(event: AuthMessageEventLike): void
+  /** Re-push persisted credentials on boot (acceptance group D). */
+  restore(): Promise<void>
+  /** Re-push persisted credentials on demand (heals a reset/absent node half). */
+  syncNow(): Promise<void>
+  dispose(): void
+}
+
+export function createAuthClient(deps: AuthClientDeps): AuthClient {
+  const trustedOrigin = deps.trustedOrigin ?? AUTH_ORIGIN
+  const loginUrl = deps.loginUrl ?? `${AUTH_ORIGIN}/`
+  const { storage, transport } = deps
+  const listeners = new Set<(info: AuthTokenPayload | null) => void>()
+
+  const emit = (info: AuthTokenPayload | null): void => {
+    for (const listener of listeners) listener(info)
+  }
+  const closeIframe = (): void => {
+    // The dialog module owns the DOM. Tear it down on any close path
+    // (token success, logout, close_dialog postMessage, dispose).
+    if (isLoginDialogOpen()) closeLoginDialog()
+  }
+  /**
+   * Open the login dialog (backdrop + centered card + auth.eda.cn iframe).
+   *
+   * The dialog is ALWAYS transparent (no `transparent` option exists): the
+   * embedded doc sets its own root to `background: transparent` (we never
+   * send `fill=full`), and the iframe sits inside a host-painted card so
+   * Blink's white base canvas never reaches the user. See the long header
+   * in `ui/login-dialog.ts` for the full why.
+   */
+  const openIframe = (options: LoginOptions = {}): void => {
+    if (isLoginDialogOpen()) return
+    const baseUrl = loginUrl
+    openLoginDialog(
+      {
+        ...(options.lang ? { lang: options.lang } : {}),
+        ...(options.theme ? { theme: options.theme } : {}),
+      },
+      () => {
+        // Re-render safety: nothing to do here — the auth client's own state
+        // is just the dialog-open boolean, which `isLoginDialogOpen()` reads
+        // directly from the dialog module.
+        void baseUrl
+      },
+    )
+  }
+
+  const auth = {
+    isAuthenticated: (): boolean => storage.get() !== null,
+    getAccessToken: async (): Promise<string | null> => storage.get()?.token ?? null,
+    getUserInfo: async (): Promise<AuthTokenPayload | null> => storage.get(),
+    login: async (options?: LoginOptions): Promise<void> => openIframe(options ?? {}),
+    logout: async (): Promise<void> => {
+      storage.clear()
+      try {
+        await transport.pushLogout()
+      } catch {
+        /* node may be absent — local state is still cleared */
+      }
+      emit(null)
+      closeIframe()
+    },
+    onAuthStateChanged: (listener: (info: AuthTokenPayload | null) => void): (() => void) => {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+
+  const handleMessageEvent = (event: AuthMessageEventLike): void => {
+    // Offline deployment: no origin gate (see lib.ts). Envelope validation is
+    // the only gate, so unrelated window messages can never corrupt state.
+    const msg = handleAuthMessage(event)
+    if (!msg) return
+    if (msg.kind === 'token') {
+      storage.set(msg.info)
+      void transport.pushSession(msg.info).catch(() => { /* node push is best-effort; syncNow heals */ })
+      emit(msg.info)
+      closeIframe()
+    } else if (msg.kind === 'logout') {
+      storage.clear()
+      emit(null)
+      void transport.pushLogout().catch(() => { /* local state already cleared */ })
+      closeIframe()
+    } else if (msg.kind === 'close') {
+      closeIframe()
+    }
+  }
+
+  const onWindowMessage = (event: MessageEvent): void => {
+    handleMessageEvent({ origin: event.origin, data: event.data })
+  }
+
+  deps.windowLike.addEventListener('message', onWindowMessage)
+
+  const restore = async (): Promise<void> => {
+    const restored = storage.get()
+    if (restored) {
+      try {
+        await transport.pushSession(restored)
+      } catch {
+        /* boot push is best-effort; syncNow heals */
+      }
+    }
+  }
+
+  return {
+    auth,
+    handleMessageEvent,
+    restore,
+    /**
+     * Re-push the persisted credential to the node half. Healing path: the
+     * node keeps auth in memory, so a `dsh web` restart (or a failed first
+     * push) drops it while the browser still has the token. Callers re-sync on
+     * focus / visibilitychange / login-card mount so the tool gate reflects
+     * the actual browser login without requiring a page reload.
+     */
+    async syncNow(): Promise<void> {
+      const info = storage.get()
+      if (!info) return
+      try {
+        await transport.pushSession(info)
+      } catch {
+        /* sync is best-effort; a later focus event retries */
+      }
+    },
+    dispose() {
+      deps.windowLike.removeEventListener('message', onWindowMessage)
+      closeIframe()
+      void trustedOrigin // referenced for clarity: the auth iframe URL comes from it
+    },
+  }
+}

package/src/client/i18n.ts

@@ -0,0 +1,97 @@
+/**
+ * zh / en copy for every user-visible string of the auth UI (sidebar trigger,
+ * account menu, login tool card).
+ *
+ * Kept self-contained rather than registered into DSH's `ctx.locale`
+ * namespace — same call the sibling packages made
+ * (`dsh-tool-symbol-footprint/src/client/i18n.ts`) — because the slot system
+ * hands components props, not ctx, and a missing namespace would leave the UI
+ * blank. `en` is typed as `Record<AuthCopyKey, string>`, so a key added to one
+ * language without the other is a COMPILE error (bilingual balance enforced at
+ * build time, mirroring DSH's own locale registry).
+ *
+ * The en「Go to profile」/「Log out」wording is the one the sidebar spec asks
+ * for; the zh side follows `hq-eda-ai`'s `locales/cn.ts` (个人中心 / 退出登录).
+ */
+import { useMemo } from 'react'
+import type { AuthLocale } from './lib.js'
+import { useLocale } from './ui-env.js'
+
+const zh = {
+  'sidebar.login': '华秋EDA AI登录',
+  'sidebar.loginTitle': '登录华秋 EDA AI（eda.cn）账号',
+  'sidebar.accountTitle': '华秋 EDA AI 账号',
+  'sidebar.account': '华秋EDA AI · 已登录',
+
+  'menu.profile': '个人中心',
+  'menu.logout': '退出登录',
+
+  'card.title': '华秋 EDA AI（eda.cn）登录',
+  'card.desc': '工具「{tool}」需要登录华秋 EDA AI 账号才能继续。请在下方的登录框完成登录（或点击左侧「华秋EDA AI登录」按钮）；登录完成后，回复助手「已登录，请重试」，助手会自动重新调用该工具。',
+  'card.loggedIn': '✓ 已登录{nickname} —— 现在可以回复助手「已登录，请重试」，助手会重新调用工具。',
+  'card.loggedOut': '未登录 —— 请在上方登录华秋 EDA AI（eda.cn）账号，或点击左侧「华秋EDA AI登录」按钮；登录完成后让助手重试。',
+  'card.tool': '工具：{tool}',
+  'card.empty': '(无输出)',
+  // Substituted into `{nickname}` by `card.loggedIn`. zh uses a full-width
+  // colon, en a half-width one plus a space; hardcoding '：' made the English
+  // card read "Logged in：John".
+  'card.nicknameSep': '：{nickname}',
+
+  'dialog.close': '关闭',
+} as const
+
+/** Every key of the zh dictionary — the contract both languages satisfy. */
+export type AuthCopyKey = keyof typeof zh
+
+const en: Record<AuthCopyKey, string> = {
+  'sidebar.login': 'Huaqiu EDA AI login',
+  'sidebar.loginTitle': 'Sign in to your Huaqiu EDA AI (eda.cn) account',
+  'sidebar.accountTitle': 'Huaqiu EDA AI account',
+  'sidebar.account': 'Huaqiu EDA AI · signed in',
+
+  'menu.profile': 'Go to profile',
+  'menu.logout': 'Log out',
+
+  'card.title': 'Huaqiu EDA AI (eda.cn) login',
+  // The reply phrase used to be hardcoded to the Chinese "已登录，请重试" even
+  // in these English strings, telling an English-speaking user to type Chinese.
+  'card.desc': 'Tool "{tool}" needs a Huaqiu EDA AI account. Complete the login below (or use the Huaqiu EDA AI button in the sidebar), then reply "I have logged in, please retry" so the assistant can retry the tool.',
+  'card.loggedIn': '✓ Logged in{nickname} — reply "I have logged in, please retry" and the assistant will retry the tool.',
+  'card.loggedOut': 'Not logged in — sign in above, or use the Huaqiu EDA AI button in the sidebar, then ask the assistant to retry.',
+  'card.tool': 'Tool: {tool}',
+  'card.empty': '(no output)',
+  'card.nicknameSep': ': {nickname}',
+
+  'dialog.close': 'Close',
+}
+
+const COPY: Record<AuthLocale, Record<AuthCopyKey, string>> = { zh, en }
+
+/** Every copy key, in declaration order (used to assert bilingual balance). */
+export const AUTH_COPY_KEYS = Object.keys(zh) as AuthCopyKey[]
+
+export type Translate = (key: AuthCopyKey, params?: Record<string, unknown>) => string
+
+/**
+ * Look a key up, interpolating `{name}` placeholders.
+ *
+ * Chain: active locale → zh (the source of truth) → the key itself, so a
+ * missing translation stays VISIBLE instead of blanking the UI.
+ */
+export function translate(locale: AuthLocale, key: AuthCopyKey, params?: Record<string, unknown>): string {
+  const template = COPY[locale]?.[key] ?? COPY.zh[key] ?? key
+  if (!params) return template
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    name in params ? String(params[name]) : match)
+}
+
+/** Translate bound to one locale (stable for the lifetime of that locale). */
+export function createT(locale: AuthLocale): Translate {
+  return (key, params) => translate(locale, key, params)
+}
+
+/** Translate bound to the host UI language, re-created when it changes. */
+export function useT(): Translate {
+  const locale = useLocale()
+  return useMemo(() => createT(locale), [locale])
+}

package/src/client/index.tsx

@@ -0,0 +1,109 @@
+/**
+ * `@huaqiu/dsh-auth` — browser half (the Phase 0A POC).
+ *
+ * Opens the auth.eda.cn login page in an overlay iframe, STRICTLY validates
+ * the postMessage origin, caches credentials in localStorage (reload restore),
+ * and pushes them to the node half over the plugin-owned webServer routes.
+ * Provides the client-side `huaqiuAuth` service mirroring the node surface.
+ *
+ * On top of the credential flow it wires the two UI surfaces the login UX
+ * needs:
+ *   - `sidebar.footer.action` — a persistent 华秋EDA login entrypoint at the
+ *     bottom of the sidebar (login/logout, live state).
+ *   - `tool.call.toolview` (keyed per Huaqiu tool) — when a node tool returns
+ *     `status: "needs_auth"` the tool card becomes the login HIT: an embedded
+ *     auth.eda.cn iframe + login-state line, so login is a step of the
+ *     conversation instead of a dead error the agent has to relay.
+ */
+import { createAuthStorage } from './storage.js'
+import { createWebServerAuthTransport } from './transport.js'
+import { createAuthClient, type AuthClient } from './client.js'
+import { disposeAuth, registerAuth, registerAuthSync } from './auth-state.js'
+import { HuaqiuToolView } from './ui/needs-auth-toolview.jsx'
+import { HuaqiuAuthSidebarAction } from './ui/sidebar-action.jsx'
+import { disposeUiEnv } from './ui-env.js'
+
+/**
+ * Client cordis inject: REAL service names only (the loader maps these to
+ * `ctx.inject([...])` dependencies). The `slots` registry service comes from
+ * `@deepseek-ai/dsh-client-ui-slots`; it is required to register the toolview
+ * and sidebar entries. The PACKAGE-level `dsh.client.inject` in package.json
+ * (graph ordering) stays as-is and is NOT this export.
+ */
+export const inject: string[] = ['slots']
+
+/**
+ * Huaqiu tools that still surface the auth login card via this plugin.
+ *
+ * Currently EMPTY: all five Huaqiu tools now own their keyed HIT cards in
+ * their own plugins (`@huaqiu/dsh-tool-symbol-footprint` for the three
+ * symbol/footprint generators, `@huaqiu/dsh-tool-schematic-gen` for the two
+ * schematic/system generators), and each renders its own inline login card for
+ * `needs_auth`. Keeping the toolview keys here would double-register the same
+ * `tool.call.toolview` slot with an ambiguous winner.
+ *
+ * The auth plugin remains the credential owner: the `huaqiuAuth` client
+ * service, the sidebar login entrypoint and the webServer credential channel.
+ */
+export const AUTH_TOOL_NAMES: readonly string[] = []
+
+/** Minimal structural client context (dsh-client-runtime provides this). */
+export interface ClientContext {
+  provide?(name: string, value: unknown): () => void
+  slots?: {
+    inject(key: string, callback: () => () => void): () => void
+    register(spec: { name: string; key?: string; id?: string }, component: unknown): unknown
+  }
+}
+
+export function apply(ctx: ClientContext): () => void {
+  const client: AuthClient = createAuthClient({
+    storage: createAuthStorage(localStorage),
+    transport: createWebServerAuthTransport(),
+    windowLike: window,
+    documentLike: document,
+  })
+
+  const disposers: Array<() => void> = []
+  const disposeProvide = ctx.provide?.('huaqiuAuth', { auth: client.auth })
+  registerAuth(client.auth)
+  registerAuthSync(() => { void client.syncNow() })
+  void client.restore()
+  disposers.push(client.auth.onAuthStateChanged((info) => {
+    void client.syncNow()
+  }))
+
+  // Healing: the node half keeps auth in memory, so a server restart drops it
+  // while the browser still holds the token. Re-sync whenever the tab regains
+  // focus/visibility so the tool gate flips back to authenticated without a
+  // reload.
+  const sync = (): void => { void client.syncNow() }
+  window.addEventListener('focus', sync)
+  document.addEventListener('visibilitychange', sync)
+  disposers.push(() => {
+    window.removeEventListener('focus', sync)
+    document.removeEventListener('visibilitychange', sync)
+  })
+
+  const slots = ctx.slots
+  if (slots && typeof slots.inject === 'function' && typeof slots.register === 'function') {
+    for (const toolName of AUTH_TOOL_NAMES) {
+      disposers.push(slots.inject('tool.call.toolview', () => slots.register({ name: 'tool.call.toolview', key: toolName }, HuaqiuToolView) as () => void))
+    }
+    disposers.push(slots.inject('sidebar.footer.action', () => slots.register({ name: 'sidebar.footer.action', id: 'huaqiu-auth' }, HuaqiuAuthSidebarAction) as () => void))
+  }
+
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        /* already disposed */
+      }
+    }
+    disposeProvide?.()
+    client.dispose()
+    disposeAuth()
+    disposeUiEnv()
+  }
+}