@allbluecn/web-app 0.23.5 → 0.23.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allbluecn/web-app",
-  "version": "0.23.5",
+  "version": "0.23.6",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [

package/src/components/desktop-agent/agent-chat.tsx

@@ -4,8 +4,9 @@
 
 // 本地文件助手 · 对话区（桌面本地优先 P3-B5）：useChat 直连 Pro desktop 域
 // AgentService 的 `POST /prompt`（AG-UI SSE）。
-// - connection：lib/desktop-agent/connection 包装——每次 connect 懒取 appInfo 的
-//   agentPort/agentToken（backend 重启换端口/令牌后下一问即用新值），引用稳定。
+// - connection：lib/desktop-agent/connection 包装——每次 connect 懒取桌面桥的 agent
+//   端点（新壳 agentCredentials 按需取 {port, token}，旧壳回落 appInfo 的
+//   agentPort/agentToken；backend 重启换端口/令牌后下一问即用新值），引用稳定。
 // - threadId：mount 级稳定值（useChat 1.0 起必填，变化即重建 ChatClient）。B4 端点
 //   每次 POST 新建 pi 会话，threadId 仅作 run 归属回显——一期不保留多轮上下文，
 //   输入区常驻提示告知。

package/src/lib/changelog/sdk-versions.ts

@@ -112,7 +112,7 @@ export const SDK_GROUPS: SdkGroup[] = [
     "items": [
       {
         "name": "@allbluecn/web-app",
-        "version": "v0.23.5",
+        "version": "v0.23.6",
         "lastUpdate": "Nov 1, 2026",
         "source": "apps/web/package.json",
         "docsUrl": "https://github.com/allbluecn/allblue"

package/src/lib/desktop-agent/__tests__/connection.test.ts

@@ -2,10 +2,12 @@
 // AllBlue - 理想之海
 // Copyright (C) 2026 AllBlue Contributors
 
-// desktop-agent 连接（桌面本地优先 P3-B5）：appInfo 调用时懒取 agentPort/agentToken
-// → 真实 fetchServerSentEvents 直连 http://127.0.0.1:{port}/prompt。fetch 打桩、
-// SSE 解析走真实 @tanstack/ai-client 实现——请求线格式即与 Pro 端点的跨仓契约：
-// URL / X-Desktop-Token / X-Run-Id 头 / forwardedProps.cwd（端点 extractCwd 取值位）。
+// desktop-agent 连接（桌面本地优先 P3-B5）：调用时懒取 agent 端点 → 真实
+// fetchServerSentEvents 直连 http://127.0.0.1:{port}/prompt。fetch 打桩、SSE 解析
+// 走真实 @tanstack/ai-client 实现——请求线格式即与 Pro 端点的跨仓契约：URL /
+// X-Desktop-Token / X-Run-Id 头 / forwardedProps.cwd（端点 extractCwd 取值位）。
+// 两种壳形态各覆盖：新壳经 agentCredentials 按需取凭据（appInfo.agentToken 恒 null，
+// 不参与连接），旧壳回落 appInfo 的 agentPort/agentToken。
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { UIMessage } from '@tanstack/ai-client'
 
@@ -18,7 +20,15 @@ type AppInfo = {
   agentToken?: string | null
 }
 
-const bridgeRef: { current: { appInfo: () => Promise<AppInfo> } | null } = { current: null }
+type AgentCredentials = { port: number; token: string }
+
+type Bridge = {
+  appInfo: () => Promise<AppInfo>
+  /** 新壳按需取凭据通道；旧壳无此方法（undefined） */
+  agentCredentials?: () => Promise<AgentCredentials | null>
+}
+
+const bridgeRef: { current: Bridge | null } = { current: null }
 
 vi.mock('@/lib/desktop-bridge-types', () => ({
   getDesktopBridge: () => bridgeRef.current,
@@ -36,6 +46,14 @@ function bridgeWith(info: Partial<AppInfo>) {
   return { appInfo: vi.fn(async () => ({ ...BASE_INFO, ...info })) }
 }
 
+/** 新壳桥：appInfo 里 agentPort 仍广播（门控用）、agentToken 恒 null；凭据走按需 IPC */
+function newShellBridge(credentials: AgentCredentials | null, info: Partial<AppInfo> = {}) {
+  return {
+    appInfo: vi.fn(async () => ({ ...BASE_INFO, agentPort: null, agentToken: null, ...info })),
+    agentCredentials: vi.fn(async () => credentials),
+  }
+}
+
 const encoder = new TextEncoder()
 function sse(event: Record<string, unknown>): Uint8Array {
   return encoder.encode(`data: ${JSON.stringify(event)}\n\n`)
@@ -119,6 +137,50 @@ describe('resolveDesktopAgentEndpoint（appInfo 懒取）', () => {
   })
 })
 
+describe('resolveDesktopAgentEndpoint（新壳 agentCredentials 优先 / 旧壳回落 appInfo）', () => {
+  it('新壳：用 agentCredentials 的 {port, token} 构造端点，不读 appInfo 的令牌', async () => {
+    // appInfo 故意给一个不同的端口 + 陈旧令牌：端点必须只来自 agentCredentials
+    const bridge = newShellBridge({ port: 2468, token: 'tok-cred' }, { agentPort: 4567, agentToken: 'ok' })
+    bridgeRef.current = bridge
+    await expect(resolveDesktopAgentEndpoint()).resolves.toEqual({
+      url: 'http://127.0.0.1:2468/prompt',
+      token: 'tok-cred',
+    })
+    expect(bridge.agentCredentials).toHaveBeenCalledTimes(1)
+    expect(bridge.appInfo).not.toHaveBeenCalled()
+  })
+
+  it('新壳：agentCredentials 返回 null（未装配）或抛错（IPC 断开）→ null，不回落 appInfo', async () => {
+    const bridge = newShellBridge(null)
+    bridgeRef.current = bridge
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+    expect(bridge.appInfo).not.toHaveBeenCalled()
+
+    bridgeRef.current = {
+      appInfo: vi.fn(async () => ({ ...BASE_INFO, agentPort: 4567, agentToken: null })),
+      agentCredentials: vi.fn(async () => {
+        throw new Error('ipc closed')
+      }),
+    }
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+  })
+
+  it('新壳：agentCredentials 产出的端口/令牌非法 → null（与 appInfo 路径同口径）', async () => {
+    bridgeRef.current = newShellBridge({ port: 0, token: 'tok' })
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+    bridgeRef.current = newShellBridge({ port: 4567, token: '' })
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+  })
+
+  it('旧壳（无 agentCredentials）→ 回落 appInfo 的 agentPort + agentToken', async () => {
+    bridgeRef.current = bridgeWith({ agentPort: 4567, agentToken: 'tok-abc' })
+    await expect(resolveDesktopAgentEndpoint()).resolves.toEqual({
+      url: 'http://127.0.0.1:4567/prompt',
+      token: 'tok-abc',
+    })
+  })
+})
+
 describe('createDesktopAgentConnection（fetchServerSentEvents 包装）', () => {
   it('端点不可用 → 抛 DesktopAgentUnavailableError，且不发起 fetch', async () => {
     const fetchMock = stubSseFetch(RUN_EVENTS)
@@ -173,6 +235,31 @@ describe('createDesktopAgentConnection（fetchServerSentEvents 包装）', () =>
     expect(body.messages).toEqual([expect.objectContaining({ role: 'user', content: '列出目录' })])
   })
 
+  it('新壳：URL / X-Desktop-Token 取自 agentCredentials（appInfo 的 agentToken 恒 null 不参与）', async () => {
+    const fetchMock = stubSseFetch(RUN_EVENTS)
+    const bridge = newShellBridge({ port: 2468, token: 'tok-cred' }, { agentPort: 4567, agentToken: null })
+    bridgeRef.current = bridge
+    await drain(
+      createDesktopAgentConnection().connect([USER_MESSAGE], undefined, undefined, { threadId: 't-1', runId: 'r-1' }),
+    )
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('http://127.0.0.1:2468/prompt')
+    expect((init?.headers as Record<string, string>)['X-Desktop-Token']).toBe('tok-cred')
+    // 每次 connect 都重新按需取一次凭据（backend 重启换端口/令牌后下一问即用新值）
+    expect(bridge.agentCredentials).toHaveBeenCalledTimes(1)
+    expect(bridge.appInfo).not.toHaveBeenCalled()
+  })
+
+  it('新壳未装配（agentCredentials → null）→ 抛 DesktopAgentUnavailableError，不发 fetch', async () => {
+    const fetchMock = stubSseFetch(RUN_EVENTS)
+    bridgeRef.current = newShellBridge(null)
+    await expect(
+      drain(createDesktopAgentConnection().connect([USER_MESSAGE], undefined, undefined, { threadId: 't', runId: 'r' })),
+    ).rejects.toBeInstanceOf(DesktopAgentUnavailableError)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
   it('SSE 帧原样产出为 AG-UI chunk（RUN_STARTED 起、RUN_FINISHED 止）', async () => {
     stubSseFetch(RUN_EVENTS)
     bridgeRef.current = bridgeWith({ agentPort: 4567, agentToken: 'tok-abc' })
@@ -191,7 +278,7 @@ describe('createDesktopAgentConnection（fetchServerSentEvents 包装）', () =>
     ])
   })
 
-  it('每次 connect 都重取 appInfo（backend 重启换端口/令牌后下一问即用新值）', async () => {
+  it('旧壳：每次 connect 都重取 appInfo（backend 重启换端口/令牌后下一问即用新值）', async () => {
     const fetchMock = stubSseFetch(RUN_EVENTS)
     const appInfo = vi
       .fn<() => Promise<AppInfo>>()

package/src/lib/desktop-agent/connection.ts

@@ -5,13 +5,18 @@
 // 本地文件助手的 agent 连接（桌面本地优先 P3-B5）：useChat 的 connection 适配。
 //
 // 端点 = Pro desktop 域 AgentService（B4）：backend utilityProcess 内 127.0.0.1
-// 随机端口 `POST /prompt`（AG-UI SSE），须带 `X-Desktop-Token`。端口与令牌经
-// desktopBridge.appInfo() 的 agentPort/agentToken 广播——backend 重启即换新值
-// （main 侧 backend exit 清空），所以**每次请求时懒取**，不在组件顶层静态拼 URL。
+// 随机端口 `POST /prompt`（AG-UI SSE），须带 `X-Desktop-Token`。端口与令牌经桌面桥
+// 取得，两种壳形态：
+// - 新壳：`desktopBridge.agentCredentials()` 按需 IPC 返回 { port, token }（令牌不再
+//   随 appInfo 常驻广播——常驻信息面会让任意 renderer JS（含 XSS）随时拿到令牌去读
+//   已授权目录；appInfo.agentToken 在新壳恒为 null 占位）。
+// - 旧壳（无 agentCredentials）：回落 `desktopBridge.appInfo()` 的 agentPort/agentToken。
+// backend 重启即换新值（main 侧 backend exit 清空），所以**每次请求时懒取**，不在组件
+// 顶层静态拼 URL。
 //
 // 为什么包一层而不是直接 fetchServerSentEvents(url, options)：其 url 参数只接受
 // 同步 getter，且在 connect() 内先于（可异步的）options 求值——URL 无法来自同一次
-// 调用里 await 的 appInfo。包装只做「await appInfo → 构造 fetchServerSentEvents →
+// 调用里 await 的桥调用。包装只做「await 桥 → 构造 fetchServerSentEvents →
 // 原样委托 connect」，SSE 解析/AG-UI 协议/abort 全部是官方实现，无自定义协议面。
 //
 // 请求线格式（与 Pro 端点的跨仓契约，见 agent-service.ts extractCwd/extractPrompt）：
@@ -28,8 +33,8 @@ export interface DesktopAgentEndpoint {
   token: string
 }
 
-/** agent 端点不可用：无桥（云 Web / OSS）、旧壳（appInfo 无 agent 字段）、或
- *  agent 未装配（DESKTOP_AGENT 门控未开 / bundle 装配失败 → agentPort null） */
+/** agent 端点不可用：无桥（云 Web / OSS）、旧壳（appInfo 无 agent 字段）、新壳未装配
+ *  （agentCredentials 返回 null）、或 DESKTOP_AGENT 门控未开 / bundle 装配失败 */
 export class DesktopAgentUnavailableError extends Error {
   constructor() {
     super('desktop agent endpoint unavailable')
@@ -37,20 +42,36 @@ export class DesktopAgentUnavailableError extends Error {
   }
 }
 
-/** 调用时读取当前 agent 端点；不可用返回 null（端口/令牌非法同样视为不可用，不拼坏 URL） */
+/** 端口合法性（1..65535 整数）：非法即「不可用」，不拼出坏 URL */
+function isValidAgentPort(port: unknown): port is number {
+  return typeof port === 'number' && Number.isInteger(port) && port >= 1 && port <= 65535
+}
+
+/** 由端口 + 令牌构造端点；任一非法返回 null（不吞半截凭据）。令牌空串按不可用处理
+ *  ——新壳 appInfo.agentToken 恒 null，回落路径若拿到空串说明壳未装配 */
+function buildEndpoint(port: unknown, token: unknown): DesktopAgentEndpoint | null {
+  if (!isValidAgentPort(port)) return null
+  if (typeof token !== 'string' || token === '') return null
+  return { url: `http://127.0.0.1:${port}/prompt`, token }
+}
+
+/** 调用时读取当前 agent 端点；不可用返回 null（端口/令牌非法同样视为不可用，不拼坏 URL）。
+ *  取端点优先 agentCredentials（新壳按需取凭证），旧壳回落 appInfo 的 agentPort/agentToken。 */
 export async function resolveDesktopAgentEndpoint(): Promise<DesktopAgentEndpoint | null> {
   const bridge = getDesktopBridge()
   if (!bridge) return null
-  // main 未就绪 / IPC 断开时 appInfo 会抛错：归「服务未就绪」（不可用 → 上层抛
-  // DesktopAgentUnavailableError），不把原生错误原文当「运行失败：<原文>」透出
+  // 新壳独占使用 agentCredentials：其存在即表示令牌不再经 appInfo 广播，回落拿到
+  // 的只会是恒 null 占位，无收益。IPC 断开/main 未就绪时抛错与 appInfo 同口径归
+  // 「服务未就绪」（不可用），不把原生错误原文透出成「运行失败：<原文>」
+  if (typeof bridge.agentCredentials === 'function') {
+    const credentials = await bridge.agentCredentials().catch(() => null)
+    if (!credentials) return null
+    return buildEndpoint(credentials.port, credentials.token)
+  }
+  // 旧壳：端口/令牌同随 appInfo 广播
   const info = await bridge.appInfo().catch(() => null)
   if (!info) return null
-  const { agentPort, agentToken } = info
-  if (typeof agentPort !== 'number' || !Number.isInteger(agentPort) || agentPort < 1 || agentPort > 65535) {
-    return null
-  }
-  if (typeof agentToken !== 'string' || agentToken === '') return null
-  return { url: `http://127.0.0.1:${agentPort}/prompt`, token: agentToken }
+  return buildEndpoint(info.agentPort, info.agentToken)
 }
 
 /**

package/src/lib/desktop-bridge-types.ts

@@ -9,15 +9,26 @@ export interface DesktopBridgeApi {
    *  字段）：backend utilityProcess 装配 AgentService 后随 appInfo 广播——
    *  agentPort = 127.0.0.1 随机端口，agentToken = 启动时生成的访问令牌
    *  （请求须带 X-Desktop-Token 头）。null = agent 未装配（旧壳，或 DESKTOP_AGENT
-   *  门控未开/bundle 装配失败降级），renderer 据此隐藏 agent 入口。 */
+   *  门控未开/bundle 装配失败降级），renderer 据此隐藏 agent 入口。
+   *  ⚠ agentToken 仅旧壳有值：新壳把它移出 appInfo 常驻广播（任意 renderer JS
+   *  含 XSS 都能随时取到令牌去读已授权目录），改由 agentCredentials 按需取一次，
+   *  保留下来的该字段**恒为 null（纯兼容占位，勿再消费）**。agentPort 仍随
+   *  appInfo 广播（仅端口、不可用于取文件，供入口门控）。 */
   appInfo: () => Promise<{
     version: string
     clientId: string
     platform: string
     backendPort: number | null
     agentPort?: number | null
+    /** @deprecated 新壳恒 null（令牌不再广播）；请改用 agentCredentials() */
     agentToken?: string | null
   }>
+  /** 本地文件助手 agent 凭据按需获取（Pro 侧新增 IPC `desktopBridge:agentCredentials`）：
+   *  仅在建立 agent 连接时调用一次，返回 { port, token }（port = 127.0.0.1 随机端口，
+   *  token = 请求头 X-Desktop-Token 的值）；agent 未装配 → null。与 appInfo 不同，
+   *  本方法**不是**常驻可查询的信息面，令牌不进入任何长期可读的全局面。
+   *  旧壳无此方法 → undefined，调用方回落到 appInfo 的 agentPort/agentToken。 */
+  agentCredentials?: () => Promise<{ port: number; token: string } | null>
   cloudLogin: (email: string, password: string) => Promise<{ ok: boolean; userId?: string; error?: string }>
   /** A10 轻量云身份激活：登录成功后取 cloud-session.json 解出的纯 session
    *  token（renderer 再走 exchangeRemoteTokenFn 换权益并写 remote-auth）。 */

package/src/routes/api/sync/__tests__/bootstrap.test.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// /api/sync/bootstrap 未登录态回归哨兵（sync 族状态码对齐）：requireAuth 抛
+// UnauthorizedError 必须映射 401 + { error: 'unauthorized' }（此前裸调直上抛
+// → 500）。非鉴权异常必须原样上抛（不吞）。
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ requireAuth: vi.fn(), getPrisma: vi.fn() }))
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getRequest: () => ({ url: 'https://allblue.test/api/sync/bootstrap' }),
+}))
+vi.mock('@/server/auth-helpers', () => ({
+  requireAuth: mocks.requireAuth,
+  UnauthorizedError: class UnauthorizedError extends Error {
+    constructor(message = 'UNAUTHORIZED') {
+      super(message)
+      this.name = 'UnauthorizedError'
+    }
+  },
+}))
+vi.mock('@allbluecn/database/get-prisma', () => ({ getPrisma: mocks.getPrisma }))
+
+import { Route } from '../bootstrap'
+import { UnauthorizedError } from '@/server/auth-helpers'
+
+type Handler = () => Promise<Response>
+const GET = (Route.options.server as { handlers?: { GET?: Handler } } | undefined)?.handlers?.GET
+if (!GET) throw new Error('GET handler missing')
+
+const call = () => GET()
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.requireAuth.mockResolvedValue({ user: { id: 'u1' } })
+  mocks.getPrisma.mockResolvedValue({})
+})
+
+describe('/api/sync/bootstrap', () => {
+  it('未登录（UnauthorizedError）→ 401 + { error: "unauthorized" }', async () => {
+    mocks.requireAuth.mockRejectedValue(new UnauthorizedError())
+
+    const res = await call()
+
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ error: 'unauthorized' })
+    // 鉴权失败不得触达数据库
+    expect(mocks.getPrisma).not.toHaveBeenCalled()
+  })
+
+  it('未登录（裸 Error("UNAUTHORIZED")，跨实例兜底）→ 401', async () => {
+    mocks.requireAuth.mockRejectedValue(new Error('UNAUTHORIZED'))
+
+    const res = await call()
+
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ error: 'unauthorized' })
+  })
+
+  it('非鉴权异常（取 Prisma 失败）→ 原样上抛，不吞成响应', async () => {
+    mocks.getPrisma.mockRejectedValue(new Error('db down'))
+
+    await expect(call()).rejects.toThrow('db down')
+  })
+})

package/src/routes/api/sync/__tests__/pull.test.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// /api/sync/pull 未登录态回归哨兵（sync 族状态码对齐）：requireAuth 抛
+// UnauthorizedError 必须映射 401 + { error: 'unauthorized' }（此前裸调直上抛
+// → 500）。非鉴权异常必须原样上抛（不吞）。
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ requireAuth: vi.fn() }))
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getRequest: () => ({ url: 'https://allblue.test/api/sync/pull' }),
+}))
+vi.mock('@/server/auth-helpers', () => ({
+  requireAuth: mocks.requireAuth,
+  UnauthorizedError: class UnauthorizedError extends Error {
+    constructor(message = 'UNAUTHORIZED') {
+      super(message)
+      this.name = 'UnauthorizedError'
+    }
+  },
+}))
+vi.mock('@allbluecn/database/get-prisma', () => ({ getPrisma: async () => ({}) }))
+
+import { Route } from '../pull'
+import { UnauthorizedError } from '@/server/auth-helpers'
+
+type Handler = (ctx: { request: Request }) => Promise<Response>
+const POST = (Route.options.server as { handlers?: { POST?: Handler } } | undefined)?.handlers?.POST
+if (!POST) throw new Error('POST handler missing')
+
+const post = (body: unknown = { scopes: [], lastSeq: 0 }) =>
+  POST({
+    request: new Request('https://allblue.test/api/sync/pull', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    }),
+  })
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.requireAuth.mockResolvedValue({ user: { id: 'u1' } })
+})
+
+describe('/api/sync/pull', () => {
+  it('未登录（UnauthorizedError）→ 401 + { error: "unauthorized" }', async () => {
+    mocks.requireAuth.mockRejectedValue(new UnauthorizedError())
+
+    const res = await post()
+
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ error: 'unauthorized' })
+  })
+
+  it('未登录（裸 Error("UNAUTHORIZED")，跨实例兜底）→ 401', async () => {
+    mocks.requireAuth.mockRejectedValue(new Error('UNAUTHORIZED'))
+
+    const res = await post()
+
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ error: 'unauthorized' })
+  })
+
+  it('非鉴权异常（scopes/lastSeq 缺失，schema 校验失败）→ 原样上抛，不吞成响应', async () => {
+    await expect(post({})).rejects.toMatchObject({ name: 'ZodError' })
+  })
+})

package/src/routes/api/sync/__tests__/push.test.ts

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// /api/sync/push 未登录态回归哨兵（sync 族状态码对齐）：requireAuth 抛
+// UnauthorizedError 必须映射 401 + { error: 'unauthorized' }——此前 handler 内
+// 裸调 requireAuth，异常直上抛由框架统一回 500，客户端把「会话过期」误判成
+// 服务端故障并在同步循环里反复重试。非鉴权异常必须原样上抛（不吞）。
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ requireAuth: vi.fn() }))
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getRequest: () => ({ url: 'https://allblue.test/api/sync/push' }),
+}))
+vi.mock('@/server/auth-helpers', () => ({
+  requireAuth: mocks.requireAuth,
+  UnauthorizedError: class UnauthorizedError extends Error {
+    constructor(message = 'UNAUTHORIZED') {
+      super(message)
+      this.name = 'UnauthorizedError'
+    }
+  },
+}))
+vi.mock('@allbluecn/database/get-prisma', () => ({ getPrisma: async () => ({}) }))
+
+import { Route } from '../push'
+import { UnauthorizedError } from '@/server/auth-helpers'
+
+type Handler = (ctx: { request: Request }) => Promise<Response>
+const POST = (Route.options.server as { handlers?: { POST?: Handler } } | undefined)?.handlers?.POST
+if (!POST) throw new Error('POST handler missing')
+
+const post = (body: unknown = { ops: [] }) =>
+  POST({
+    request: new Request('https://allblue.test/api/sync/push', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    }),
+  })
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.requireAuth.mockResolvedValue({ user: { id: 'u1' } })
+})
+
+describe('/api/sync/push', () => {
+  it('未登录（UnauthorizedError）→ 401 + { error: "unauthorized" }', async () => {
+    mocks.requireAuth.mockRejectedValue(new UnauthorizedError())
+
+    const res = await post()
+
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ error: 'unauthorized' })
+  })
+
+  it('未登录（裸 Error("UNAUTHORIZED")，跨实例兜底）→ 401', async () => {
+    mocks.requireAuth.mockRejectedValue(new Error('UNAUTHORIZED'))
+
+    const res = await post()
+
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ error: 'unauthorized' })
+  })
+
+  it('非鉴权异常（ops 缺失，schema 校验失败）→ 原样上抛，不吞成响应', async () => {
+    await expect(post({})).rejects.toMatchObject({ name: 'ZodError' })
+  })
+})

package/src/routes/api/sync/__tests__/snapshot.test.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// /api/sync/snapshot 未登录态回归哨兵（sync 族状态码对齐）：requireAuth 抛
+// UnauthorizedError 必须映射 401 + { error: 'unauthorized' }（此前裸调直上抛
+// → 500）。非鉴权异常必须原样上抛（不吞）。
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ requireAuth: vi.fn() }))
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getRequest: () => ({ url: 'https://allblue.test/api/sync/snapshot' }),
+}))
+vi.mock('@/server/auth-helpers', () => ({
+  requireAuth: mocks.requireAuth,
+  UnauthorizedError: class UnauthorizedError extends Error {
+    constructor(message = 'UNAUTHORIZED') {
+      super(message)
+      this.name = 'UnauthorizedError'
+    }
+  },
+}))
+vi.mock('@allbluecn/database/get-prisma', () => ({ getPrisma: async () => ({}) }))
+
+import { Route } from '../snapshot'
+import { UnauthorizedError } from '@/server/auth-helpers'
+
+type Handler = (ctx: { request: Request }) => Promise<Response>
+const GET = (Route.options.server as { handlers?: { GET?: Handler } } | undefined)?.handlers?.GET
+if (!GET) throw new Error('GET handler missing')
+
+/** table 合法时才会走到业务查询；未登录用例用合法 URL 确保失败点只在鉴权 */
+const call = (table = 'projects') =>
+  GET({
+    request: new Request(`https://allblue.test/api/sync/snapshot?table=${table}`),
+  })
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.requireAuth.mockResolvedValue({ user: { id: 'u1' } })
+})
+
+describe('/api/sync/snapshot', () => {
+  it('未登录（UnauthorizedError）→ 401 + { error: "unauthorized" }', async () => {
+    mocks.requireAuth.mockRejectedValue(new UnauthorizedError())
+
+    const res = await call()
+
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ error: 'unauthorized' })
+  })
+
+  it('未登录（裸 Error("UNAUTHORIZED")，跨实例兜底）→ 401', async () => {
+    mocks.requireAuth.mockRejectedValue(new Error('UNAUTHORIZED'))
+
+    const res = await call()
+
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ error: 'unauthorized' })
+  })
+
+  it('非鉴权异常（缺少 table 参数，schema 校验失败）→ 原样上抛，不吞成响应', async () => {
+    await expect(call('')).rejects.toMatchObject({ name: 'ZodError' })
+  })
+})

package/src/routes/api/sync/bootstrap.ts

@@ -9,6 +9,7 @@ import { createFileRoute } from "@tanstack/react-router"
 import { getRequest } from "@tanstack/react-start/server"
 import { getPrisma } from "@allbluecn/database/get-prisma"
 import { requireAuth } from "@/server/auth-helpers"
+import { mapSyncAuthError } from "@/server/sync/http-errors"
 import { resolveSyncScopes } from "@/server/sync/scopes"
 import { SYNC_TABLES } from "@allbluecn/sync-core/registrations"
 
@@ -16,22 +17,26 @@ export const Route = createFileRoute("/api/sync/bootstrap")({
   server: {
     handlers: {
       GET: async () => {
-        const session = await requireAuth(getRequest())
-        const prisma = await getPrisma()
+        try {
+          const session = await requireAuth(getRequest())
+          const prisma = await getPrisma()
 
-        const [{ seq }] = await prisma.$queryRawUnsafe<Array<{ seq: bigint }>>(
-          `SELECT COALESCE(MAX(seq), 0) AS seq FROM sync_change_log`,
-        )
-        const counts = await Promise.all(
-          SYNC_TABLES.map(async (reg) => {
-            const [r] = await prisma.$queryRawUnsafe<Array<{ c: bigint }>>(
-              `SELECT COUNT(*)::bigint AS c FROM ${reg.table}`,
-            )
-            return { name: reg.table, count: Number(r.c) }
-          }),
-        )
-        void resolveSyncScopes // scopes 解析在快照分页端点逐页执行（此处仅鉴权）
-        return Response.json({ watermarkSeq: Number(seq), tables: counts })
+          const [{ seq }] = await prisma.$queryRawUnsafe<Array<{ seq: bigint }>>(
+            `SELECT COALESCE(MAX(seq), 0) AS seq FROM sync_change_log`,
+          )
+          const counts = await Promise.all(
+            SYNC_TABLES.map(async (reg) => {
+              const [r] = await prisma.$queryRawUnsafe<Array<{ c: bigint }>>(
+                `SELECT COUNT(*)::bigint AS c FROM ${reg.table}`,
+              )
+              return { name: reg.table, count: Number(r.c) }
+            }),
+          )
+          void resolveSyncScopes // scopes 解析在快照分页端点逐页执行（此处仅鉴权）
+          return Response.json({ watermarkSeq: Number(seq), tables: counts })
+        } catch (e) {
+          return mapSyncAuthError(e)
+        }
       },
     },
   },

package/src/routes/api/sync/pull.ts

@@ -9,6 +9,7 @@ import { getRequest } from "@tanstack/react-start/server"
 import { z } from "zod"
 import { getPrisma } from "@allbluecn/database/get-prisma"
 import { requireAuth } from "@/server/auth-helpers"
+import { mapSyncAuthError } from "@/server/sync/http-errors"
 import { resolveSyncScopes } from "@/server/sync/scopes"
 
 const pullSchema = z.object({
@@ -23,73 +24,77 @@ export const Route = createFileRoute("/api/sync/pull")({
   server: {
     handlers: {
       POST: async ({ request }) => {
-        const session = await requireAuth(getRequest())
-        const userId = session.user.id
-        const body = pullSchema.parse(await request.json())
+        try {
+          const session = await requireAuth(getRequest())
+          const userId = session.user.id
+          const body = pullSchema.parse(await request.json())
 
-        const prisma = await getPrisma()
-        const { SYNC_TABLE_MAP } = await import("@allbluecn/sync-core/registrations")
-        // scopes 服务端权威解析（客户端回显值仅作对账提示，不参与过滤）
-        const scopes = await resolveSyncScopes(prisma, userId)
-        const limit = Math.min(body.limit ?? PAGE_LIMIT, PAGE_LIMIT)
+          const prisma = await getPrisma()
+          const { SYNC_TABLE_MAP } = await import("@allbluecn/sync-core/registrations")
+          // scopes 服务端权威解析（客户端回显值仅作对账提示，不参与过滤）
+          const scopes = await resolveSyncScopes(prisma, userId)
+          const limit = Math.min(body.limit ?? PAGE_LIMIT, PAGE_LIMIT)
 
-        const logRows = await prisma.$queryRawUnsafe<
-          Array<{ seq: bigint; table_name: string; pk: string; op: string }>
-        >(
-          `SELECT seq, table_name, pk, op FROM sync_change_log
+          const logRows = await prisma.$queryRawUnsafe<
+            Array<{ seq: bigint; table_name: string; pk: string; op: string }>
+          >(
+            `SELECT seq, table_name, pk, op FROM sync_change_log
 WHERE seq > $1 AND scope = ANY($2)
 ORDER BY seq ASC
 LIMIT $3`,
-          body.lastSeq,
-          scopes,
-          limit + 1,
-        )
-        const hasMore = logRows.length > limit
-        const page = hasMore ? logRows.slice(0, limit) : logRows
+            body.lastSeq,
+            scopes,
+            limit + 1,
+          )
+          const hasMore = logRows.length > limit
+          const page = hasMore ? logRows.slice(0, limit) : logRows
 
-        const changes: Array<Record<string, unknown>> = []
-        for (const row of page) {
-          const reg = SYNC_TABLE_MAP.get(row.table_name)
-          if (!reg) continue // 未注册表（历史注册被移除）跳过
-          const change: Record<string, unknown> = {
-            table: row.table_name,
-            pk: row.pk,
-            op: row.op,
-          }
-          if (row.op === "upsert") {
-            // pk 来自 change_log（客户端 push 时写入）——键必须经注册表 pkColumns
-            // 白名单过滤（注入面收口），值参数化
-            const params: unknown[] = []
-            let where: string
-            if (reg.pkColumns.length === 1) {
-              params.push(row.pk)
-              where = `"${reg.pkColumns[0]}" = $1`
+          const changes: Array<Record<string, unknown>> = []
+          for (const row of page) {
+            const reg = SYNC_TABLE_MAP.get(row.table_name)
+            if (!reg) continue // 未注册表（历史注册被移除）跳过
+            const change: Record<string, unknown> = {
+              table: row.table_name,
+              pk: row.pk,
+              op: row.op,
+            }
+            if (row.op === "upsert") {
+              // pk 来自 change_log（客户端 push 时写入）——键必须经注册表 pkColumns
+              // 白名单过滤（注入面收口），值参数化
+              const params: unknown[] = []
+              let where: string
+              if (reg.pkColumns.length === 1) {
+                params.push(row.pk)
+                where = `"${reg.pkColumns[0]}" = $1`
+              } else {
+                const parsed = JSON.parse(row.pk) as Record<string, string>
+                where = reg.pkColumns
+                  .map((k) => {
+                    params.push(parsed[k])
+                    return `"${k}" = $${params.length}`
+                  })
+                  .join(" AND ")
+              }
+              const rows = await prisma.$queryRawUnsafe<Record<string, unknown>[]>(
+                `SELECT ${reg.columns.map((c) => `"${c}"`).join(", ")}, sync_version FROM ${reg.table} WHERE ${where}`,
+                ...params,
+              )
+              if (rows.length === 0) continue // 行已删（change_log 略滞后），下轮 delete 事件收敛
+              const payload: Record<string, unknown> = {}
+              for (const c of reg.columns) payload[c] = rows[0][c] ?? null
+              change.payload = payload
+              change.syncVersion = Number(rows[0].sync_version ?? 0)
             } else {
-              const parsed = JSON.parse(row.pk) as Record<string, string>
-              where = reg.pkColumns
-                .map((k) => {
-                  params.push(parsed[k])
-                  return `"${k}" = $${params.length}`
-                })
-                .join(" AND ")
+              change.syncVersion = 0
             }
-            const rows = await prisma.$queryRawUnsafe<Record<string, unknown>[]>(
-              `SELECT ${reg.columns.map((c) => `"${c}"`).join(", ")}, sync_version FROM ${reg.table} WHERE ${where}`,
-              ...params,
-            )
-            if (rows.length === 0) continue // 行已删（change_log 略滞后），下轮 delete 事件收敛
-            const payload: Record<string, unknown> = {}
-            for (const c of reg.columns) payload[c] = rows[0][c] ?? null
-            change.payload = payload
-            change.syncVersion = Number(rows[0].sync_version ?? 0)
-          } else {
-            change.syncVersion = 0
+            changes.push(change)
           }
-          changes.push(change)
-        }
 
-        const nextSeq = page.length ? Number(page[page.length - 1].seq) : body.lastSeq
-        return Response.json({ changes, nextSeq, hasMore })
+          const nextSeq = page.length ? Number(page[page.length - 1].seq) : body.lastSeq
+          return Response.json({ changes, nextSeq, hasMore })
+        } catch (e) {
+          return mapSyncAuthError(e)
+        }
       },
     },
   },

package/src/routes/api/sync/push.ts

@@ -15,6 +15,7 @@ import { getRequest } from "@tanstack/react-start/server"
 import { z } from "zod"
 import { getPrisma } from "@allbluecn/database/get-prisma"
 import { requireAuth } from "@/server/auth-helpers"
+import { mapSyncAuthError } from "@/server/sync/http-errors"
 import { resolveSyncScopes } from "@/server/sync/scopes"
 
 const pushSchema = z.object({
@@ -82,72 +83,76 @@ export const Route = createFileRoute("/api/sync/push")({
   server: {
     handlers: {
       POST: async ({ request }) => {
-        const session = await requireAuth(getRequest())
-        const userId = session.user.id
-        const body = pushSchema.parse(await request.json())
+        try {
+          const session = await requireAuth(getRequest())
+          const userId = session.user.id
+          const body = pushSchema.parse(await request.json())
 
-        const prisma = await getPrisma()
-        const { applyOp, admitScopeForOp } = await import("@allbluecn/sync-core")
-        const { SYNC_TABLE_MAP } = await import("@allbluecn/sync-core/registrations")
-        const scopes = await resolveSyncScopes(prisma, userId)
-        // 首次上云的 scope 动态准入（C1 / 裁定 R5）：空云账号的 scopes 只有
-        // user:<id>，而 outbox 的容器行 scope = 自身 id、子行 scope = 父容器 id。
-        // 逐 op 按「属主自证」累积准入集合（同一 Set 穿过整批 op，依赖 outbox
-        // 的父先子后拓扑序），再交给 applyOp 做行级校验——准入只覆盖自证行，
-        // 不放宽到整表（边界见 @allbluecn/sync-core 的 scope-admission 头注释）。
-        const admittedScopes = new Set(scopes)
+          const prisma = await getPrisma()
+          const { applyOp, admitScopeForOp } = await import("@allbluecn/sync-core")
+          const { SYNC_TABLE_MAP } = await import("@allbluecn/sync-core/registrations")
+          const scopes = await resolveSyncScopes(prisma, userId)
+          // 首次上云的 scope 动态准入（C1 / 裁定 R5）：空云账号的 scopes 只有
+          // user:<id>，而 outbox 的容器行 scope = 自身 id、子行 scope = 父容器 id。
+          // 逐 op 按「属主自证」累积准入集合（同一 Set 穿过整批 op，依赖 outbox
+          // 的父先子后拓扑序），再交给 applyOp 做行级校验——准入只覆盖自证行，
+          // 不放宽到整表（边界见 @allbluecn/sync-core 的 scope-admission 头注释）。
+          const admittedScopes = new Set(scopes)
 
-        // 整批单事务：逐 op 应用（依赖拓扑由客户端 outbox 顺序保证）
-        const results = await prisma.$transaction(async (tx) => {
-          const executor = {
-            query: <T = Record<string, unknown>>(sql: string, params: unknown[]) =>
-              tx.$queryRawUnsafe<T[]>(sql, ...params),
-            execute: (sql: string, params: unknown[]) =>
-              tx.$executeRawUnsafe(sql, ...params),
-          }
-          const out: Array<Record<string, unknown>> = []
-          for (const op of body.ops) {
-            const reg = SYNC_TABLE_MAP.get(op.table)
-            if (!reg) {
-              out.push({ opId: op.opId, status: "conflict", conflict: { reason: "unknownTable" } })
-              continue
+          // 整批单事务：逐 op 应用（依赖拓扑由客户端 outbox 顺序保证）
+          const results = await prisma.$transaction(async (tx) => {
+            const executor = {
+              query: <T = Record<string, unknown>>(sql: string, params: unknown[]) =>
+                tx.$queryRawUnsafe<T[]>(sql, ...params),
+              execute: (sql: string, params: unknown[]) =>
+                tx.$executeRawUnsafe(sql, ...params),
             }
-            const payload = op.payload as SyncPayload | undefined
-            await admitScopeForOp(executor, reg, { pk: op.pk, op: op.op, payload }, userId, admittedScopes)
-            const ctxScopes = [...admittedScopes]
-            let outcome = await applyOp(executor, reg, { ...op, payload }, {
-              userId,
-              scopes: ctxScopes,
-              now: new Date(),
-            })
-            // 编号重发号特例：stories/bugs 撞 identifier 唯一键 → 服务端重发号重试
-            if (outcome.kind === "conflict" && outcome.reason === "uniqueViolation" && (op.table === "stories" || op.table === "bugs") && payload) {
-              const oldIdentifier = payload.identifier as string | undefined
-              const newIdentifier = await reissueIdentifier(tx, op.table, payload)
-              if (newIdentifier && newIdentifier !== oldIdentifier) {
-                outcome = await applyOp(executor, reg, { ...op, payload }, {
-                  userId,
-                  scopes: ctxScopes,
-                  now: new Date(),
-                })
-                if (outcome.kind === "applied") {
-                  out.push({
-                    opId: op.opId,
-                    status: "applied",
-                    syncVersion: outcome.syncVersion,
-                    row: outcome.row,
-                    renamed: { from: oldIdentifier ?? "", to: newIdentifier },
+            const out: Array<Record<string, unknown>> = []
+            for (const op of body.ops) {
+              const reg = SYNC_TABLE_MAP.get(op.table)
+              if (!reg) {
+                out.push({ opId: op.opId, status: "conflict", conflict: { reason: "unknownTable" } })
+                continue
+              }
+              const payload = op.payload as SyncPayload | undefined
+              await admitScopeForOp(executor, reg, { pk: op.pk, op: op.op, payload }, userId, admittedScopes)
+              const ctxScopes = [...admittedScopes]
+              let outcome = await applyOp(executor, reg, { ...op, payload }, {
+                userId,
+                scopes: ctxScopes,
+                now: new Date(),
+              })
+              // 编号重发号特例：stories/bugs 撞 identifier 唯一键 → 服务端重发号重试
+              if (outcome.kind === "conflict" && outcome.reason === "uniqueViolation" && (op.table === "stories" || op.table === "bugs") && payload) {
+                const oldIdentifier = payload.identifier as string | undefined
+                const newIdentifier = await reissueIdentifier(tx, op.table, payload)
+                if (newIdentifier && newIdentifier !== oldIdentifier) {
+                  outcome = await applyOp(executor, reg, { ...op, payload }, {
+                    userId,
+                    scopes: ctxScopes,
+                    now: new Date(),
                   })
-                  continue
+                  if (outcome.kind === "applied") {
+                    out.push({
+                      opId: op.opId,
+                      status: "applied",
+                      syncVersion: outcome.syncVersion,
+                      row: outcome.row,
+                      renamed: { from: oldIdentifier ?? "", to: newIdentifier },
+                    })
+                    continue
+                  }
                 }
               }
+              out.push(mapOutcome(op.opId, outcome))
             }
-            out.push(mapOutcome(op.opId, outcome))
-          }
-          return out
-        })
+            return out
+          })
 
-        return Response.json({ results })
+          return Response.json({ results })
+        } catch (e) {
+          return mapSyncAuthError(e)
+        }
       },
     },
   },

package/src/routes/api/sync/snapshot.ts

@@ -10,6 +10,7 @@ import { getRequest } from "@tanstack/react-start/server"
 import { z } from "zod"
 import { getPrisma } from "@allbluecn/database/get-prisma"
 import { requireAuth } from "@/server/auth-helpers"
+import { mapSyncAuthError } from "@/server/sync/http-errors"
 import { resolveSyncScopes } from "@/server/sync/scopes"
 import { SYNC_TABLE_MAP } from "@allbluecn/sync-core/registrations"
 
@@ -25,79 +26,83 @@ export const Route = createFileRoute("/api/sync/snapshot")({
   server: {
     handlers: {
       GET: async ({ request }) => {
-        const session = await requireAuth(getRequest())
-        const userId = session.user.id
-        const url = new URL(request.url)
-        const body = snapshotSchema.parse({
-          table: url.searchParams.get("table") ?? undefined,
-          cursor: url.searchParams.get("cursor") ?? undefined,
-          limit: url.searchParams.get("limit") ? Number(url.searchParams.get("limit")) : undefined,
-        })
+        try {
+          const session = await requireAuth(getRequest())
+          const userId = session.user.id
+          const url = new URL(request.url)
+          const body = snapshotSchema.parse({
+            table: url.searchParams.get("table") ?? undefined,
+            cursor: url.searchParams.get("cursor") ?? undefined,
+            limit: url.searchParams.get("limit") ? Number(url.searchParams.get("limit")) : undefined,
+          })
 
-        const reg = SYNC_TABLE_MAP.get(body.table)
-        if (!reg) {
-          return Response.json({ error: "unknown table" }, { status: 400 })
-        }
-        const prisma = await getPrisma()
-        const scopes = await resolveSyncScopes(prisma, userId)
-        const scopeColumn = reg.scope.kind === "self" ? reg.scope.column ?? "id" : reg.scope.column!
+          const reg = SYNC_TABLE_MAP.get(body.table)
+          if (!reg) {
+            return Response.json({ error: "unknown table" }, { status: 400 })
+          }
+          const prisma = await getPrisma()
+          const scopes = await resolveSyncScopes(prisma, userId)
+          const scopeColumn = reg.scope.kind === "self" ? reg.scope.column ?? "id" : reg.scope.column!
 
-        // 行级 scope 过滤 + (pk) 序分页；参数化拼接（列名来自注册表白名单）
-        const params: unknown[] = []
-        const where: string[] = []
-        if (reg.scope.kind !== "self") {
-          params.push(scopes.map((s) => s.replace(/^(ws|proj):/, "")))
-          where.push(`"${reg.scope.column!}" = ANY($${params.length})`)
-        }
-        if (body.cursor) {
-          const cursorKeys = JSON.parse(body.cursor) as Record<string, string>
-          // (pk) > (cursor) 行比较——单列与复合分别构造
-          if (reg.pkColumns.length === 1) {
-            params.push(cursorKeys[reg.pkColumns[0]])
-            where.push(`"${reg.pkColumns[0]}" > $${params.length}`)
-          } else {
-            const tuples = reg.pkColumns
-              .map((k) => {
-                params.push(cursorKeys[k])
-                return `$${params.length}`
-              })
-              .join(", ")
-            const cols = reg.pkColumns.map((k) => `"${k}"`).join(", ")
-            where.push(`(${cols}) > (${tuples})`)
+          // 行级 scope 过滤 + (pk) 序分页；参数化拼接（列名来自注册表白名单）
+          const params: unknown[] = []
+          const where: string[] = []
+          if (reg.scope.kind !== "self") {
+            params.push(scopes.map((s) => s.replace(/^(ws|proj):/, "")))
+            where.push(`"${reg.scope.column!}" = ANY($${params.length})`)
           }
-        }
-        const limit = Math.min(body.limit ?? PAGE_LIMIT, PAGE_LIMIT)
-        const orderBy = [...reg.pkColumns].map((k) => `"${k}" ASC`).join(", ")
+          if (body.cursor) {
+            const cursorKeys = JSON.parse(body.cursor) as Record<string, string>
+            // (pk) > (cursor) 行比较——单列与复合分别构造
+            if (reg.pkColumns.length === 1) {
+              params.push(cursorKeys[reg.pkColumns[0]])
+              where.push(`"${reg.pkColumns[0]}" > $${params.length}`)
+            } else {
+              const tuples = reg.pkColumns
+                .map((k) => {
+                  params.push(cursorKeys[k])
+                  return `$${params.length}`
+                })
+                .join(", ")
+              const cols = reg.pkColumns.map((k) => `"${k}"`).join(", ")
+              where.push(`(${cols}) > (${tuples})`)
+            }
+          }
+          const limit = Math.min(body.limit ?? PAGE_LIMIT, PAGE_LIMIT)
+          const orderBy = [...reg.pkColumns].map((k) => `"${k}" ASC`).join(", ")
 
-        const rows = await prisma.$queryRawUnsafe<Record<string, unknown>[]>(
-          `SELECT ${reg.columns.map((c) => `"${c}"`).join(", ")}, sync_version FROM ${reg.table}
+          const rows = await prisma.$queryRawUnsafe<Record<string, unknown>[]>(
+            `SELECT ${reg.columns.map((c) => `"${c}"`).join(", ")}, sync_version FROM ${reg.table}
 ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
 ORDER BY ${orderBy}
 LIMIT ${limit + 1}`,
-          ...params,
-        )
-        const hasMore = rows.length > limit
-        const page = hasMore ? rows.slice(0, limit) : rows
-        const items = page.map((r) => {
-          const payload: Record<string, unknown> = {}
-          for (const c of reg.columns) payload[c] = r[c] ?? null
-          const pk =
-            reg.pkColumns.length === 1
-              ? String(r[reg.pkColumns[0]])
-              : JSON.stringify(Object.fromEntries(reg.pkColumns.map((k) => [k, String(r[k])])))
-          return { pk, payload, syncVersion: Number((r as { sync_version?: number }).sync_version ?? 1) }
-        })
-        const nextCursor = page.length
-          ? reg.pkColumns.length === 1
-            ? String(page[page.length - 1][reg.pkColumns[0]])
-            : JSON.stringify(Object.fromEntries(reg.pkColumns.map((k) => [k, String(page[page.length - 1][k])])))
-          : null
-        // nextCursor 包 JSON 时以 base64 走 query 参数（复合键含花括号引号）
-        return Response.json({
-          rows: items,
-          nextCursor: nextCursor === null ? null : reg.pkColumns.length === 1 ? nextCursor : Buffer.from(nextCursor).toString("base64"),
-          hasMore,
-        })
+            ...params,
+          )
+          const hasMore = rows.length > limit
+          const page = hasMore ? rows.slice(0, limit) : rows
+          const items = page.map((r) => {
+            const payload: Record<string, unknown> = {}
+            for (const c of reg.columns) payload[c] = r[c] ?? null
+            const pk =
+              reg.pkColumns.length === 1
+                ? String(r[reg.pkColumns[0]])
+                : JSON.stringify(Object.fromEntries(reg.pkColumns.map((k) => [k, String(r[k])])))
+            return { pk, payload, syncVersion: Number((r as { sync_version?: number }).sync_version ?? 1) }
+          })
+          const nextCursor = page.length
+            ? reg.pkColumns.length === 1
+              ? String(page[page.length - 1][reg.pkColumns[0]])
+              : JSON.stringify(Object.fromEntries(reg.pkColumns.map((k) => [k, String(page[page.length - 1][k])])))
+            : null
+          // nextCursor 包 JSON 时以 base64 走 query 参数（复合键含花括号引号）
+          return Response.json({
+            rows: items,
+            nextCursor: nextCursor === null ? null : reg.pkColumns.length === 1 ? nextCursor : Buffer.from(nextCursor).toString("base64"),
+            hasMore,
+          })
+        } catch (e) {
+          return mapSyncAuthError(e)
+        }
       },
     },
   },

package/src/server/sync/http-errors.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// sync 族 HTTP 路由（server.handlers）未登录错误的**单一映射来源**。
+//
+// 背景：server.handlers 不走 serverFn 的 authContextMiddleware 链，requireAuth 抛的
+// UnauthorizedError 若在 handler 内未捕获会直上抛 → 框架统一回 500。同族的
+// account-status 与 attachments/content 已把未登录映射为 401，而 push/pull/
+// bootstrap/snapshot 长期裸调 requireAuth（族内状态码不一致），客户端会把
+// 「会话过期」误判为服务端故障并在同步循环里反复重试。
+//
+// 判定含 message 兜底：跨模块实例（双份 module / 测试 mock 的 UnauthorizedError）
+// 与裸 `new Error('UNAUTHORIZED')` 抛点都不满足 instanceof，但语义相同——与
+// account-status / attachments content 的判定口径逐字一致。
+import { UnauthorizedError } from "@/server/auth-helpers"
+
+/** 是否「未登录」错误（instanceof 优先，UNAUTHORIZED 消息兜底防实例不一致漏判） */
+export function isUnauthorizedError(e: unknown): boolean {
+  return (
+    e instanceof UnauthorizedError ||
+    (e instanceof Error && e.message === "UNAUTHORIZED")
+  )
+}
+
+/** 未登录统一响应：401 + JSON 信封 `{ error: 'unauthorized' }` */
+export function unauthorizedResponse(): Response {
+  return Response.json({ error: "unauthorized" }, { status: 401 })
+}
+
+/**
+ * sync 路由错误收口：未登录 → 401 响应；**其余异常原样上抛**（不吞、不降级为
+ * 500 响应，保留原始堆栈交由框架/上层日志处理）。
+ *
+ * 用法（handler 体整段包住，深层抛出的 UnauthorizedError 同样被映射）：
+ * ```ts
+ * try { ... } catch (e) { return mapSyncAuthError(e) }
+ * ```
+ */
+export function mapSyncAuthError(e: unknown): Response {
+  if (isUnauthorizedError(e)) return unauthorizedResponse()
+  throw e
+}