@allbluecn/web-app 0.23.5 → 0.23.7

package/src/routes/__tests__/-edition-routing.test.tsx

@@ -15,7 +15,7 @@ async function importIndexRoute(profileId: 'oss' | 'saas', desktop = false) {
   return import('../_public/index/route')
 }
 
-async function importNavRoute(opts: { profileId: 'oss' | 'saas'; desktop: boolean }) {
+async function importNavRoute(opts: { profileId: 'oss' | 'saas'; desktop: boolean; desktopClient?: boolean }) {
   vi.resetModules()
   vi.doMock('@/plugins/modules.gen', () => ({ profileId: opts.profileId }))
   // 部分 mock：保留真实 GUEST_USER_ID 等导出——source-mode 键隔离引入了
@@ -24,6 +24,9 @@ async function importNavRoute(opts: { profileId: 'oss' | 'saas'; desktop: boolea
     const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
     return { ...actual, isDesktopServer: () => opts.desktop }
   })
+  // 客户端导航判定（desktopBridge 运行时事实）：桌面壳里 process.env 无
+  // DEPLOY_TARGET，仅靠 isDesktopServer 会在浏览器 side 失守
+  vi.doMock('@/lib/desktop-env', () => ({ isDesktopClient: () => opts.desktopClient === true }))
   return import('../_nav/route')
 }
 
@@ -115,6 +118,13 @@ describe('_nav beforeLoad', () => {
       catchRedirect(() => Route.options.beforeLoad!({ context: { session: null }, location } as never)),
     ).toBeNull()
   })
+
+  it('桌面客户端导航（无 DEPLOY_TARGET，desktopBridge 在场）：同样无条件放行', async () => {
+    const { Route } = await importNavRoute({ profileId: 'saas', desktop: false, desktopClient: true })
+    expect(
+      catchRedirect(() => Route.options.beforeLoad!({ context: { session: null }, location } as never)),
+    ).toBeNull()
+  })
 })
 
 describe('GlobalErrorBoundary', () => {
@@ -146,11 +156,17 @@ describe('GlobalErrorBoundary', () => {
 })
 
 describe('需登录页面 gate', () => {
-  it.each([
-    ['../_nav/settings/route', '/settings/general'],
-    ['../_nav/notifications/route', '/notifications'],
-    ['../_nav/workspaces/route', '/workspaces'],
-  ])('%s 未登录跳 /login', async (mod, pathname) => {
+  // 本 describe 的桌面判定统一钉死（前面的 importNavRoute 会注册 doMock，
+  // vi.doMock 跨 resetModules 持久，不显式覆盖会串味）
+  async function mockDesktop(opts: { desktopServer: boolean; desktopClient: boolean }) {
+    vi.doMock('@/server/desktop-guest', async (importOriginal) => {
+      const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
+      return { ...actual, isDesktopServer: () => opts.desktopServer }
+    })
+    vi.doMock('@/lib/desktop-env', () => ({ isDesktopClient: () => opts.desktopClient }))
+  }
+
+  async function prepareRoute(mod: string, desktop: { desktopServer: boolean; desktopClient: boolean }) {
     vi.resetModules()
     vi.doMock('@/plugins/modules.gen', () => ({ profileId: 'oss' }))
     vi.doMock('@/lib/i18n/server', () => ({ createServerI18n: () => ({ t: (k: string) => k }) }))
@@ -162,7 +178,16 @@ describe('需登录页面 gate', () => {
       NOTIFICATION_LIST_KEY: ['notifications', 'list'],
       NOTIFICATION_UNREAD_KEY: ['notifications', 'unread'],
     }))
-    const { Route } = await import(mod)
+    await mockDesktop(desktop)
+    return import(mod)
+  }
+
+  it.each([
+    ['../_nav/settings/route', '/settings/general'],
+    ['../_nav/notifications/route', '/notifications'],
+    ['../_nav/workspaces/route', '/workspaces'],
+  ])('%s 未登录跳 /login', async (mod, pathname) => {
+    const { Route } = await prepareRoute(mod, { desktopServer: false, desktopClient: false })
     const r = catchRedirect(() =>
       Route.options.beforeLoad!({
         context: { session: null },
@@ -172,4 +197,20 @@ describe('需登录页面 gate', () => {
     expect(r?.to).toBe('/login')
     expect(r?.search?.redirect).toBe(pathname)
   })
+
+  it.each([
+    ['../_nav/settings/route', '/settings/general'],
+    ['../_nav/notifications/route', '/notifications'],
+    ['../_nav/workspaces/route', '/workspaces'],
+  ])('%s 桌面客户端（desktopBridge 在场）未登录也放行', async (mod, pathname) => {
+    const { Route } = await prepareRoute(mod, { desktopServer: false, desktopClient: true })
+    expect(
+      catchRedirect(() =>
+        Route.options.beforeLoad!({
+          context: { session: null },
+          location: { pathname, searchStr: '' },
+        } as never),
+      ),
+    ).toBeNull()
+  })
 })

package/src/routes/__tests__/-login-admin-redirect.test.ts

@@ -0,0 +1,99 @@
+// 桌面端登录页不得跳管理后台 setup（实测 P0：打开 /login 被重定向到
+// http://localhost:3001/setup）。桌面没有管理员概念（本地 guest + 云端账号），
+// 该跳转是 admin 应用首启向导的死链。
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const H = vi.hoisted(() => ({
+  checkAdminExists: vi.fn(async () => ({ hasAdmin: false })),
+  desktopServer: true,
+  desktopClient: false,
+}))
+
+vi.mock('@/server/serverFns/auth/setup', () => ({
+  checkAdminExistsFn: () => H.checkAdminExists(),
+}))
+// 登录页 loader 依赖：无需真实 provider 解析（会触 prisma）
+vi.mock('@/server/serverFns/auth/providers', () => ({
+  getAuthProviders: vi.fn(async () => ({ googleEnabled: false })),
+}))
+
+async function importLoginRoute(opts: { desktopServer?: boolean; desktopClient?: boolean } = {}) {
+  vi.resetModules()
+  H.desktopServer = opts.desktopServer ?? false
+  H.desktopClient = opts.desktopClient ?? false
+  vi.doMock('@/server/desktop-guest', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
+    return { ...actual, isDesktopServer: () => H.desktopServer }
+  })
+  // 客户端导航通道（desktopBridge 运行时事实）：beforeLoad 在浏览器重跑时
+  // process.env.DEPLOY_TARGET 不存在，只有这一条能挡住 admin setup 跳转
+  vi.doMock('@/lib/desktop-env', () => ({ isDesktopClient: () => H.desktopClient }))
+  return import('../_login/login/route')
+}
+
+/** 跑 async beforeLoad，返回 redirect 目标（无跳转 → null） */
+async function runBeforeLoad(
+  Route: Awaited<ReturnType<typeof importLoginRoute>>['Route'],
+): Promise<{ href?: string; to?: string } | null> {
+  try {
+    await (Route.options.beforeLoad as unknown as (ctx: unknown) => Promise<void>)({})
+    return null
+  } catch (e) {
+    return (e as { options?: { href?: string; to?: string } }).options ?? {}
+  }
+}
+
+describe('/login beforeLoad 的 admin 首启向导跳转', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.clearAllMocks()
+  })
+
+  it('桌面端（服务端 SSR）：hasAdmin=false 也不跳 setup（且不发起 admin 检测 RPC）', async () => {
+    H.checkAdminExists.mockResolvedValue({ hasAdmin: false })
+    vi.stubEnv('ADMIN_URL', 'http://admin.example:9999')
+
+    const { Route } = await importLoginRoute({ desktopServer: true })
+    const redirectTarget = await runBeforeLoad(Route)
+
+    expect(redirectTarget).toBeNull()
+    expect(H.checkAdminExists).not.toHaveBeenCalled()
+  })
+
+  it('桌面端（客户端导航：仅 desktopBridge 在场、无 DEPLOY_TARGET）同样不跳 setup', async () => {
+    // K1：beforeLoad 会在浏览器重跑，此时 isDesktopServer 为 false——只靠服务端
+    // 通道会让「本地会话退出 / 注册重置回跳 / 错误页登录链接」再次被送去 setup
+    H.checkAdminExists.mockResolvedValue({ hasAdmin: false })
+    vi.stubEnv('ADMIN_URL', 'http://admin.example:9999')
+
+    const { Route } = await importLoginRoute({ desktopServer: false, desktopClient: true })
+    const redirectTarget = await runBeforeLoad(Route)
+
+    expect(redirectTarget).toBeNull()
+    expect(H.checkAdminExists).not.toHaveBeenCalled()
+  })
+
+  it('web 端：hasAdmin=false 仍跳 ADMIN_URL/setup（既有行为不回归）', async () => {
+    H.checkAdminExists.mockResolvedValue({ hasAdmin: false })
+    vi.stubEnv('ADMIN_URL', 'http://admin.example:9999')
+
+    const { Route } = await importLoginRoute()
+    const redirectTarget = await runBeforeLoad(Route)
+
+    expect(redirectTarget?.href).toBe('http://admin.example:9999/setup')
+  })
+
+  it('web 端：admin 已初始化则放行', async () => {
+    H.checkAdminExists.mockResolvedValue({ hasAdmin: true })
+
+    const { Route } = await importLoginRoute()
+    expect(await runBeforeLoad(Route)).toBeNull()
+  })
+
+  it('web 端：admin 检测失败（RPC 抛错）时放行不阻断登录', async () => {
+    H.checkAdminExists.mockRejectedValue(new Error('rpc down'))
+
+    const { Route } = await importLoginRoute()
+    expect(await runBeforeLoad(Route)).toBeNull()
+  })
+})

package/src/routes/_login/login/route.tsx

@@ -19,6 +19,8 @@ import { createFileRoute, redirect } from '@tanstack/react-router'
 import { z } from 'zod'
 import { getAuthProviders } from '@/server/serverFns/auth/providers'
 import { checkAdminExistsFn } from '@/server/serverFns/auth/setup'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 
 export const Route = createFileRoute('/_login/login')({
   validateSearch: z.object({
@@ -28,9 +30,22 @@ export const Route = createFileRoute('/_login/login')({
     ssoError: z.string().optional(),
   }),
   beforeLoad: async () => {
-    // env 读取必须在 beforeLoad 内（服务端执行）：路由模块会被客户端加载，
-    // 顶层读 process.env 在浏览器 chunk 求值时直接 ReferenceError
-    const adminUrl = process.env.ADMIN_URL || 'http://localhost:3001'
+    // 桌面端（Electron + 本地 PGlite）没有「管理员/首启向导」概念：本地是
+    // guest 影子身份、云端账号经 settings/sync 的 DesktopCloudLogin 激活。
+    // /setup 是 admin 应用（默认 localhost:3001）的首启向导，桌面壳里既没有
+    // 该服务、也没有可初始化超管，跳过去必是死链/连接失败（实测 P0：打开
+    // /login 直接被重定向到 http://localhost:3001/setup）。
+    //
+    // 判定必须双通道：beforeLoad 会在**客户端导航时重跑**，浏览器里
+    // process.env.DEPLOY_TARGET 不存在（isDesktopServer 为 false），只有
+    // desktopBridge 运行时事实（isDesktopClient）能挡住——否则从本地凭据退出、
+    // 注册/重置成功回跳、错误页/邀请页的登录链接都会再次被送去 admin setup。
+    if (isDesktopServer() || isDesktopClient()) return
+    // 以下只在非桌面路径求值：桌面在上一行已返回，不会读 env、也不会发 RPC。
+    // env 读取必须留在 beforeLoad 内（不能提到模块顶层：路由模块会被客户端加载，
+    // 顶层读 process.env 在浏览器 chunk 求值时直接 ReferenceError）；此处再补
+    // typeof 守卫，防非桌面客户端导航时浏览器无 Node process。
+    const adminUrl = (typeof process !== 'undefined' ? process.env.ADMIN_URL : undefined) || 'http://localhost:3001'
     const result = await checkAdminExistsFn().catch(() => null)
     if (result?.hasAdmin === false) {
       throw redirect({ href: `${adminUrl}/setup` })

package/src/routes/_nav/design/canvas/$id/route.tsx

@@ -17,12 +17,17 @@
 
 import { createFileRoute, notFound, redirect } from '@tanstack/react-router'
 import { getDesignDetailFn } from '@/server/serverFns/design/detail'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 
 export const Route = createFileRoute('/_nav/design/canvas/$id')({
   beforeLoad: async (ctx) => {
     const id = ctx.params.id
     const result = await getDesignDetailFn({ data: { id } })
     if (result.error === 'unauthorized') {
+      // 桌面端免登录：不自动跳 /login（guest 已是本地身份，走到这里属异常态），
+      // 降级为 notFound 页，登录与否由用户自主决定
+      if (isDesktopServer() || isDesktopClient()) throw notFound()
       throw redirect({ to: '/login' })
     }
     if (result.error === 'not_found' || !result.prd) {

package/src/routes/_nav/knowledge/$kbId/route.tsx

@@ -17,6 +17,8 @@
 
 import { createFileRoute, redirect } from '@tanstack/react-router'
 import { getKnowledgeDetailFn, listDocumentsFn } from '@/server/serverFns/knowledge'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 import { KnowledgeWorkspacePending } from './-components/knowledge-workspace-pending'
 
 export const Route = createFileRoute('/_nav/knowledge/$kbId')({
@@ -24,8 +26,10 @@ export const Route = createFileRoute('/_nav/knowledge/$kbId')({
   pendingComponent: KnowledgeWorkspacePending,
   beforeLoad: async ({ context, location, params }) => {
     // 会话守卫：ssr:false 路由的 beforeLoad 在客户端导航也会执行，
-    // 覆盖 _nav 守卫不重跑（父路由已匹配）时 session 过期的窗口
-    if (!context.session?.user?.id) {
+    // 覆盖 _nav 守卫不重跑（父路由已匹配）时 session 过期的窗口。
+    // 桌面端免登录（server/client 双判）：本地 guest 即身份，不自动跳 /login，
+    // 缺数据时降级为下方「知识库不存在」分支，登录由用户自主发起。
+    if (!context.session?.user?.id && !isDesktopServer() && !isDesktopClient()) {
       throw redirect({
         to: '/login',
         search: { redirect: location.pathname + location.searchStr },

package/src/routes/_nav/route.tsx

@@ -18,6 +18,7 @@
 import { createFileRoute } from '@tanstack/react-router'
 
 import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 import { requireSessionPage } from '@/lib/auth/page-gate'
 import { listPinnedWorkspacesBriefFn } from '@/server/serverFns/workspace'
 import { listKnowledgeFn } from '@/server/serverFns/knowledge'
@@ -29,7 +30,10 @@ import { NavNotFound } from './-components/nav-not-found'
 
 export const Route = createFileRoute('/_nav')({
   beforeLoad: ({ context, location }) => {
-    if (isDesktopServer()) return
+    // 桌面端免登录：isDesktopServer 只在 SSR/sidecar 成立，客户端导航（beforeLoad
+    // 会在浏览器重跑）必须靠 desktopBridge 运行时事实判定，否则 guest 被误判
+    // 未登录踢去 /login（实测 P0；用户要求「不自动跳转登录，自主决定」）
+    if (isDesktopServer() || isDesktopClient()) return
     requireSessionPage({ context, location })
   },
   loader: async ({ context }) => {

package/src/routes/_nav/settings/account/route.tsx

@@ -19,6 +19,8 @@ import { createFileRoute, redirect } from '@tanstack/react-router'
 import { getAccountTeamFn } from '@/server/serverFns/settings/account-team'
 import type { AvatarConfig } from '@allbluecn/kernel'
 import { toAvatarShape } from '@/components/shared-kit/avatars/avatar-shape'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 
 export const Route = createFileRoute('/_nav/settings/account')({
   beforeLoad: async () => {
@@ -32,6 +34,9 @@ export const Route = createFileRoute('/_nav/settings/account')({
     }
     // 未登录走框架跳转（beforeLoad + redirect），不再下发错误状态由组件二次判断
     if (result.error === 'unauthorized') {
+      // 桌面端免登录：不自动跳 /login（本地 guest 已就绪时这里是异常态），
+      // 降级为页面错误态，登录与否由用户自主决定
+      if (isDesktopServer() || isDesktopClient()) return { error: 'error' as const }
       throw redirect({ to: '/login' })
     }
     return {

package/src/routes/_nav/settings/team/route.tsx

@@ -17,6 +17,8 @@
 
 import { createFileRoute, redirect } from '@tanstack/react-router'
 import { getAccountTeamFn } from '@/server/serverFns/settings/account-team'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 
 export const Route = createFileRoute('/_nav/settings/team')({
   beforeLoad: async () => {
@@ -29,6 +31,9 @@ export const Route = createFileRoute('/_nav/settings/team')({
     }
     // 未登录走框架跳转（beforeLoad + redirect），不再下发错误状态由组件二次判断
     if (result.error === 'unauthorized') {
+      // 桌面端免登录：不自动跳 /login（本地 guest 已就绪时这里是异常态），
+      // 降级为页面错误态，登录与否由用户自主决定
+      if (isDesktopServer() || isDesktopClient()) return { error: 'error' as const }
       throw redirect({ to: '/login' })
     }
     return {

package/src/routes/api/auth/$.ts

@@ -16,13 +16,98 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { createFileRoute } from '@tanstack/react-router'
-import { getAuthConfig } from '@/lib/auth/auth.config'
 import { StartAuthJS } from 'start-authjs'
+import { getAuthConfig } from '@/lib/auth/auth.config'
+import { getCurrentSession } from '@/lib/session'
+import { GUEST_USER_ID, isDesktopServer } from '@/server/desktop-guest'
+import { ensureLocalShadowUser } from '@/server/desktop-bootstrap'
+
+/**
+ * 桌面端「我是谁」端点回落（本地优先 P0 修复）：
+ *
+ * 客户端 useSession()（components/shared-kit/auth/auth-client.ts）打的就是
+ * /api/auth/session。authjs 只认自己的 JWT cookie —— 桌面壳里没有（本地免登录
+ * + 云端身份在 remote-auth.json），于是恒返回 null，所有以 session 判登录态的
+ * 组件（user-menu / collab gate / 评论署名 / AI 面板等）都把本地用户当匿名。
+ *
+ * 修法（服务端单点，覆盖面最大）：仅拦截 GET /api/auth/session，authjs 无会话
+ * 且为桌面部署时回落 getCurrentSession（鉴权单点：authjs → remote-auth 云身份
+ * → guest 影子用户）。其它路径（csrf/providers/signin/callback/...）与 POST
+ * 原样透传，登录/登出语义零改动。
+ *
+ * 安全：/api/auth/session 本就是会话自述端点，返回当前（可能 guest/云）身份
+ * 不扩大暴露面；Session 结构里没有 token/密钥。非桌面部署行为完全不变。
+ *
+ * guest 分支附带「懒 seed 影子用户」（幂等 upsert，失败仅 warn）：端点可能在
+ * root beforeLoad 的 getSessionFn 之前/失败时被调用，不 seed 就会下发一个 DB
+ * 里不存在的身份，随后写入撞 FK（P2003）。
+ */
+function isDesktopSessionEndpoint(request: Request): boolean {
+  if (!isDesktopServer()) return false
+  const pathname = new URL(request.url).pathname.replace(/\/+$/, '')
+  return pathname === '/api/auth/session'
+}
+
+/** 透传 authjs 的 Set-Cookie（坏 cookie 清理头），只替换 body */
+function rebuildSessionResponse(response: Response, payload: unknown): Response {
+  const headers = new Headers()
+  // undici 实现才有 getSetCookie；类型上做可选收窄，其它运行时退化为无 cookie 透传
+  const setCookies = (response.headers as Headers & { getSetCookie?: () => string[] }).getSetCookie?.() ?? []
+  for (const cookie of setCookies) headers.append('set-cookie', cookie)
+  headers.set('content-type', 'application/json')
+  headers.set('cache-control', 'no-store')
+  return new Response(JSON.stringify(payload), {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}
 
 export const Route = createFileRoute('/api/auth/$')({
   server: {
     handlers: {
-      GET: async ({ request }) => (await StartAuthJS(await getAuthConfig())).GET({ request }),
+      GET: async ({ request }) => {
+        const response = await (await StartAuthJS(await getAuthConfig())).GET({ request })
+        // 非桌面 / 非 session 端点 / 非 2xx：原样透传
+        if (!isDesktopSessionEndpoint(request) || !response.ok) return response
+
+        // authjs session 响应是 JSON：有会话 → { user, expires }；无会话 → null。
+        // Response body 只能读一次，故读文本后统一重建。
+        const text = await response.text()
+        let payload: unknown
+        try {
+          payload = JSON.parse(text)
+        } catch {
+          return rebuildSessionResponse(response, text)
+        }
+
+        const authUser = (payload as { user?: { id?: string } | null } | null)?.user
+        // 桌面本地凭据登录（有 authjs cookie）：authjs 结果优先，原样返回
+        if (authUser?.id) return rebuildSessionResponse(response, payload)
+
+        const session = await getCurrentSession(request)
+        if (!session?.user?.id) return rebuildSessionResponse(response, payload)
+
+        // guest 回落：懒 seed 本地影子用户（与 getSessionFn 同一幂等落库）。
+        // 只在 getSessionFn 里 seed 不够——root beforeLoad 的 RPC 失败/慢于端点时，
+        // 这里会下发一个 DB 里不存在的 guest 身份，随后任何写入都撞 FK（P2003）。
+        // 幂等 upsert，失败仅 warn：不阻断「我是谁」响应（首启体验优先）。
+        if (session.user.id === GUEST_USER_ID) {
+          try {
+            await ensureLocalShadowUser()
+          } catch (err) {
+            console.warn('[api/auth/session] 本地影子用户落库失败（不阻断 guest 身份响应）:', err)
+          }
+        }
+
+        return rebuildSessionResponse(response, {
+          user: session.user,
+          expires: session.expires,
+          // 会话来源标记：user-menu 的云态登出编排需区分「云身份」与本地
+          // authjs 凭据登录（二者 user.isGuest 均为 false），旧后端无此字段
+          desktopSession: session.user.isGuest ? 'guest' : 'cloud',
+        })
+      },
       POST: async ({ request }) => (await StartAuthJS(await getAuthConfig())).POST({ request }),
     },
   },

package/src/routes/api/auth/__tests__/auth-session-desktop.test.ts

@@ -0,0 +1,194 @@
+// /api/auth/$ 的 GET 桌面回落（useSession 依赖的「我是谁」端点）。
+// 根因：authjs 只认自己的 JWT cookie，桌面壳内（本地免登录 / 云端身份在
+// remote-auth.json）恒返回 null → useSession() 恒 null → 各组件把本地用户当匿名。
+// 修法：仅 GET /api/auth/session 在 desktop 且 authjs 无会话时回落
+// getCurrentSession（authjs → remote-auth 云身份 → guest 影子身份）。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const H = vi.hoisted(() => ({
+  getSession: vi.fn(),
+  readRemoteAuth: vi.fn(),
+  authJsGet: vi.fn(),
+  authJsPost: vi.fn(),
+  ensureLocalShadowUser: vi.fn(async () => 'local-guest'),
+  desktopServer: true,
+}))
+
+vi.mock('start-authjs', () => ({
+  StartAuthJS: async () => ({ GET: H.authJsGet, POST: H.authJsPost }),
+  getSession: H.getSession,
+}))
+vi.mock('@/lib/auth/auth.config', () => ({
+  getAuthConfig: async () => ({}),
+  resetProfileCache: vi.fn(),
+}))
+vi.mock('@/server/remote-auth', () => ({
+  readRemoteAuth: H.readRemoteAuth,
+}))
+// seed 走真模块会拉起 @allbluecn/database 的模块级 prisma 单例（测试环境无 DB）
+vi.mock('@/server/desktop-bootstrap', () => ({
+  ensureLocalShadowUser: H.ensureLocalShadowUser,
+}))
+
+type AuthRoute = typeof import('../$')['Route']
+
+async function importAuthRoute(desktop: boolean): Promise<AuthRoute> {
+  vi.resetModules()
+  H.desktopServer = desktop
+  vi.doMock('@/server/desktop-guest', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
+    return { ...actual, isDesktopServer: () => H.desktopServer }
+  })
+  return (await import('../$')).Route
+}
+
+/** 模拟 authjs 的 session 端点响应（无会话 → JSON null） */
+function authJsResponse(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+    ...init,
+  })
+}
+
+function callGet(Route: AuthRoute, path = '/api/auth/session'): Promise<Response> {
+  const handlers = (Route.options as unknown as {
+    server: { handlers: Record<string, (ctx: { request: Request }) => Promise<Response>> }
+  }).server.handlers
+  return handlers.GET!({ request: new Request(`http://localhost${path}`, { method: 'GET' }) })
+}
+
+describe('/api/auth/session 桌面回落', () => {
+  beforeEach(() => {
+    // 真实桌面后端由 Electron 主进程注入该 env（fail-open 自检的正常路径）：
+    // 测试里显式给出，避免每条用例都打安全告警
+    vi.stubEnv('DESKTOP_USER_DATA_DIR', '/tmp/allblue-desktop-test')
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.clearAllMocks()
+  })
+
+  it('desktop + 无 authjs cookie → 返回 guest 影子身份（user.id=local-guest）且懒 seed 影子用户', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue(null)
+    H.authJsGet.mockResolvedValue(authJsResponse(null))
+
+    const Route = await importAuthRoute(true)
+    const res = await callGet(Route)
+    const data = (await res.json()) as { user?: { id?: string; isGuest?: boolean }; desktopSession?: string }
+
+    expect(res.status).toBe(200)
+    expect(data.user?.id).toBe('local-guest')
+    expect(data.user?.isGuest).toBe(true)
+    expect(data.desktopSession).toBe('guest')
+    // I3：端点命中 guest 时补 seed（不能只靠 root beforeLoad 的 getSessionFn——
+    // 那一步 RPC 失败时这里会下发未落库身份，后续写入撞 FK P2003）
+    expect(H.ensureLocalShadowUser).toHaveBeenCalledTimes(1)
+  })
+
+  it('desktop guest seed 抛错：仅 warn，不阻断「我是谁」响应', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue(null)
+    H.authJsGet.mockResolvedValue(authJsResponse(null))
+    H.ensureLocalShadowUser.mockRejectedValueOnce(new Error('db gone'))
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const Route = await importAuthRoute(true)
+    const res = await callGet(Route)
+    const data = (await res.json()) as { user?: { id?: string } }
+
+    expect(res.status).toBe(200)
+    expect(data.user?.id).toBe('local-guest')
+    expect(warnSpy).toHaveBeenCalled()
+  })
+
+  it('desktop + remoteAuth 云身份 → 返回云 userId（不是 guest），且不 seed guest 影子行', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue({
+      userId: 'cloud-user-abc',
+      planName: 'pro',
+      features: {},
+      sessionToken: 'cloud-session-token',
+      username: '云端用户',
+    })
+    H.authJsGet.mockResolvedValue(authJsResponse(null))
+
+    const Route = await importAuthRoute(true)
+    const data = (await (await callGet(Route)).json()) as {
+      user?: { id?: string; name?: string; isGuest?: boolean }
+      desktopSession?: string
+    }
+
+    expect(data.user?.id).toBe('cloud-user-abc')
+    expect(data.user?.name).toBe('云端用户')
+    expect(data.user?.isGuest).toBe(false)
+    expect(data.desktopSession).toBe('cloud')
+    expect(H.ensureLocalShadowUser).not.toHaveBeenCalled()
+  })
+
+  it('非 desktop：authjs 的 null 原样透传（不扩大暴露面）', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue(null)
+    H.authJsGet.mockResolvedValue(authJsResponse(null))
+
+    const Route = await importAuthRoute(false)
+    const data = await (await callGet(Route)).json()
+
+    expect(data).toBeNull()
+  })
+
+  it('desktop + 有效 authjs 会话：authjs 结果优先（不追加 desktopSession 标记）', async () => {
+    const authJsSession = { user: { id: 'authjs-user-1', name: '本地账号' }, expires: '2026-12-31' }
+    H.getSession.mockResolvedValue(authJsSession)
+    H.authJsGet.mockResolvedValue(authJsResponse(authJsSession))
+
+    const Route = await importAuthRoute(true)
+    const data = (await (await callGet(Route)).json()) as Record<string, unknown>
+
+    expect((data.user as { id?: string }).id).toBe('authjs-user-1')
+    expect(data.desktopSession).toBeUndefined()
+  })
+
+  it('desktop + 非 session 路径（csrf）：原样透传，不做身份回落', async () => {
+    H.authJsGet.mockResolvedValue(
+      new Response(JSON.stringify({ csrfToken: 't' }), { status: 200, headers: { 'content-type': 'application/json' } }),
+    )
+
+    const Route = await importAuthRoute(true)
+    const data = (await (await callGet(Route, '/api/auth/csrf')).json()) as Record<string, unknown>
+
+    expect(data.csrfToken).toBe('t')
+    expect(H.getSession).not.toHaveBeenCalled()
+  })
+
+  it('POST 原样交给 authjs（登录/登出流程零改动）', async () => {
+    H.authJsPost.mockResolvedValue(new Response('{}', { status: 200 }))
+
+    const Route = await importAuthRoute(true)
+    const handlers = (Route.options as unknown as {
+      server: { handlers: Record<string, (ctx: { request: Request }) => Promise<Response>> }
+    }).server.handlers
+    const res = await handlers.POST!({
+      request: new Request('http://localhost/api/auth/callback/credentials', { method: 'POST' }),
+    })
+
+    expect(H.authJsPost).toHaveBeenCalledTimes(1)
+    expect(res.status).toBe(200)
+  })
+
+  it('透传 authjs 的 Set-Cookie（坏 cookie 清理头不丢）', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue(null)
+    H.authJsGet.mockResolvedValue(
+      authJsResponse(null, { headers: { 'content-type': 'application/json', 'set-cookie': 'auth.session-token=; Max-Age=0' } }),
+    )
+
+    const Route = await importAuthRoute(true)
+    const res = await callGet(Route)
+
+    expect(res.headers.getSetCookie().some((c) => c.startsWith('auth.session-token='))).toBe(true)
+    expect(res.headers.get('cache-control')).toBe('no-store')
+  })
+})