本地浏览器同步登录态方案

用户本地 Chrome/Edge
        |
        | Browser Extension
        | - 用户授权站点
        | - 读取 Cookie
        | - 读取 localStorage
        v
Poco Backend Auth State
        |
        | snapshot / commit
        v
远程浏览器 / 任务浏览器

核心原则：

Backend Auth State 仍是唯一长期保存位置。
本地扩展只负责采集用户授权范围内的状态并提交。
Executor Manager 和 Executor 不需要感知数据来自远程浏览器、任务浏览器还是本地浏览器。
合并、加密、清空逻辑继续复用现有 Auth State 服务。

5. 组件职责

5.1 Browser Extension

负责用户本地浏览器侧的授权和采集。
使用 optional_host_permissions 让用户按站点授权。
使用 chrome.cookies.getAll 读取授权 domain 的 Cookie。
使用 content script 读取授权 origin 的 localStorage。
维护本地同步基线 base_version 和 base_state。
调用 Backend 用户态 Auth State 接口提交变更。

5.2 Frontend

提供“同步本地浏览器登录态”入口。
展示功能说明、隐私说明和风险提示。
生成一次性配对 token，用于扩展绑定当前 Poco 用户。
展示已同步站点和清除入口。

5.3 Backend

提供用户态 Auth State 读取、提交和清空接口。
复用现有 Auth State 加密存储和三方合并逻辑。
校验用户身份，确保只能操作当前用户自己的 Auth State。
记录 updated_by_run_id，区分本地浏览器导入来源。
提供一次性配对 token 的生成、校验和失效机制。

6. 数据模型

本地浏览器同步继续使用现有 Auth State 结构：

{
  "cookies": [
    {
      "name": "sid",
      "value": "...",
      "domain": ".example.com",
      "path": "/",
      "expires": 1767225600,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "local_storage": {
    "https://example.com": {
      "token": "...",
      "user_id": "123"
    }
  },
  "observed_scopes": {
    "cookie_domains": [".example.com"],
    "local_storage_origins": ["https://example.com"]
  },
  "tombstones": {
    "cookies": [
      {
        "name": "sid",
        "domain": ".example.com",
        "path": "/"
      }
    ],
    "local_storage": [
      {
        "origin": "https://example.com",
        "key": "token"
      }
    ]
  }
}

扩展本地仅保存同步基线：

{
  "base_version": 12,
  "base_state": {}
}

说明：

base_state 用于生成增量变更和 tombstone。
扩展本地不得长期保存 Poco 访问令牌明文。
如果需要保存扩展会话凭据，应使用 Chrome extension storage，并尽量使用短期 token。

7. Backend 接口建议

7.1 生成配对 Token

POST /api/v1/browser-sync/pairing-token

用途：

前端在用户登录后生成一次性配对 token。
用户复制或通过扩展跳转完成绑定。
token 应具备短有效期，并且使用后立即失效。

{
  "pairing_token": "pst_xxx",
  "expires_at": "2026-05-03T10:00:00Z"
}

7.2 读取当前用户 Auth State 快照

GET /api/v1/auth-state/snapshot

说明：

用户态接口使用当前登录用户身份，不允许通过 query 参数指定任意 user_id。
返回结构可与内部 snapshot 接口保持一致。

7.3 提交本地浏览器状态

POST /api/v1/auth-state/commit

请求：

{
  "base_version": 12,
  "base_state": {},
  "new_state": {},
  "run_id": "local_browser:device_xxx"
}

说明：

run_id 使用 local_browser:{device_id} 格式，便于审计来源。
Backend 继续执行现有三方合并。
返回最新版本和合并后的 state，供扩展刷新本地基线。

7.4 清空本地同步登录态

DELETE /api/v1/auth-state

说明：

清空当前用户的 Auth State。
Frontend 和扩展都应提供清空入口。
清空后远程浏览器和任务浏览器不再恢复旧登录态。

8. 扩展设计

8.1 Manifest 权限

建议使用 Manifest V3：

{
  "manifest_version": 3,
  "name": "Poco Browser Sync",
  "permissions": ["cookies", "storage", "scripting"],
  "host_permissions": ["https://api.poco.example.com/*"],
  "optional_host_permissions": ["https://*/*", "http://*/*"],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html"
  }
}