认证与权限
凭证分层
| 凭证 | 形态 | 用途 | 能否读取数据 |
|---|
| Site ID | st_... 公开 | 采集归属 | 否 |
| 浏览器会话 | HttpOnly Cookie（生产 __Host-、Secure、SameSite=Strict） | 网页后台 | 是（按角色） |
| 恢复密钥 | strk_...，256 位随机，仅保存摘要 | 在新设备恢复工作区、近期强认证 | 仅用于建立会话 |
| API 凭证 | stk_... | REST 与 MCP（Bearer） | 是（按 scope、网站、访问窗口） |
| 采集凭证 | sti_... + 签名密钥 | 服务端/边缘上报 | 否（只写） |
| 引导令牌 | stb_...，1 小时 | 程序化 onboarding | 仅汇总 |
| OAuth 令牌 | 由 /oauth/token 签发 | 通用 MCP 客户端 | 是（按同意页授权） |
Scope
| scope | 说明 |
|---|
summary:read | 读取汇总报表（PV、UV、来源、页面排行、AI 汇总等），不含访客/请求级明细与收入 |
details:read | 读取访客、会话、单请求明细与分类证据（含路径、UA 等不可信原始字段） |
conversions:read | 读取目标、漏斗与转化次数（不含收入金额） |
revenue:read | 读取收入金额与订单 |
exports:write | 创建与下载导出文件（导出内容仍受其它读取 scope 限制） |
imports:write | 上传并提交历史数据导入 |
sites:write | 添加/修改网站、分组、安装与验证 |
settings:write | 修改网站设置、目标、漏斗、过滤器、自定义维度、推广成本与保留设置 |
reports:write | 保存报表、创建计划与投递目标 |
shares:write | 创建/撤销公开分享（仍需服务端开启公开分享功能） |
members:admin | 邀请、降级、移除成员 |
credentials:admin | 创建、轮换、吊销 API 凭证与授权 |
audit:read | 读取审计日志 |
usage:read | 读取用量、配额与成本估算 |
默认 AI 凭证只有 summary:read。收入、访客明细、成员与凭证管理需要单独授予；授予者不能授出超过自身的权限。
规则
- 所有带 ID 的路径都会二次校验归属；不在授权范围内一律返回 404，不泄露他人网站是否存在。
- Cookie 会话的写操作必须同源（Origin 校验）；Bearer 请求不需要 Cookie。
- 私有接口不允许跨域携带凭证；
/api/v1/collect/browser 允许任意来源但只能写入，并按网站域名校验 Origin。 - 删除数据、缩短保留期、开启公开分享等高风险动作只能在浏览器会话中，经“预览 → 10 分钟内重新输入恢复密钥 → 输入确认文字”执行。API 凭证与 MCP 只能预览。
- 变更接口支持
Idempotency-Key；同键不同参数返回 409。 - 限流返回 429 与
Retry-After。
采集签名（服务端 / 边缘）
Authorization: Bearer sti_...
X-SiteTrace-Timestamp: <unix 秒，±300 秒>
X-SiteTrace-Nonce: <16-64 位随机，一次性>
X-SiteTrace-Signature: v1=hex(HMAC-SHA256(signing_secret, "<ts>.<nonce>.<sha256(body)>"))
OAuth（仅 /mcp）
- 发现：
/.well-known/oauth-protected-resource/mcp、/.well-known/oauth-authorization-server - 授权：
/authorize（授权码 + PKCE S256），令牌：/oauth/token，动态注册：/oauth/register（限流） - 资源（audience）：
/mcp；令牌权限在每次请求时按工作区授权记录重新校验，吊销立即生效。