企业官网建设流程全解析

proof-sdk是一个开源的协作编辑器 + 内容溯源模型 + AI Agent HTTP 桥接框架。当你用POST /documents创建一篇共享文档时，响应里会一次性返回两个最重要的凭证：ownerSecret（文档级"主人密钥"）和accessToken（按角色限权的访问令牌）。本文将带你从新手视角看懂这套认证模型，并给出 token 安全最佳实践，帮你避免最常见的密钥泄露与越权问题。

一图看懂：ownerSecret 与 accessToken 有什么区别

这两个凭证的职责完全不同，混用是新手最容易犯的错误：

官方契约文档 AGENT_CONTRACT.md 明确写道：ownerSecret要"安全存储，不要在面向用户的界面中暴露"；能使用accessToken完成的操作，就不要动用ownerSecret。

如何获取这两个 token：创建文档的响应字段

调用POST /documents（兼容别名POST /share/markdown）后，响应体中会直接带上全套凭证与链接：

{ "success": true, "slug": "abc123xy", "shareUrl": "https://your-proof.example/d/abc123xy", "tokenUrl": "https://your-proof.example/d/abc123xy?token=...", "ownerSecret": "8b5f...owner secret...", "accessToken": "4d53...link token...", "accessRole": "commenter" }

注意几个细节：

• accessToken与accessRole是绑定的——同一个 token 只能干它那个角色能干的事；
• shareUrl是"干净"的无 token 链接，tokenUrl/tokenPath才是带?token=的带凭证链接（兼容与调试用）；
• 创建响应会一次性把ownerSecret返回给你，之后只能靠你自己保管，丢失无法从响应里再取。

token 怎么传：服务端认可的 5 种方式

在 server/routes.ts 的getExplicitShareSecret中，服务端按优先级依次接受以下携带方式，方便不同客户端形态接入：

1. 请求体字段：ownerSecret（JSON body）
2. 请求头：x-share-token: <token>
3. 请求头：x-bridge-token: <token>（Agent 桥接场景）
4. 查询参数：?token=<token>（分享链接自带）
5. Cookie：浏览器访问共享文档时写入的 token cookie

此外Authorization: Bearer <token>也是标准的 bearer 通道（以epsess_开头的托管会话 token 会被排除，避免混淆）。如果你拿到的是一个带?token=的分享链接，官方文档 docs/agent-docs.md 推荐直接：

curl -H "Authorization: Bearer $TOKEN" "http://localhost:4000/documents/$SLUG/state"

💡 小技巧：对分享链接本身发Accept: application/json请求，可以一步拿到文档内容、_links路由和agent.auth使用提示，无需浏览器自动化。

权限模型：四个角色如何解析

上面这张 Proof 共享文档界面（截图来自 public/assets/screenshot.jpg）就是这套认证的最终效果：Agent 与人类在同一界面里评论、建议、协作，而每一步操作都由 token 背后的角色约束。

角色定义在 server/share-types.ts：

viewer < commenter < editor < owner_bot

服务端resolveDocumentAccess（server/db.ts）的解析顺序是：

1. 提交的凭证先匹配owner_secret_hash→ 角色owner_bot；
2. 未命中再查document_access表中的access token→ 返回其绑定的viewer/commenter/editor角色（未吊销的 token 才有效）；
3. 若请求完全不带 token，产品决策是"slug 本身就是秘密"，默认按editor放行（无 token 的裸链接场景）。

这意味着：token 不只是"能不能进"，还决定了"能做什么"——同一个accessToken，viewer只能读，commenter可以评论，editor才能修改内容。

入口鉴权配置：PROOF_SHARE_MARKDOWN_AUTH_MODE

除了文档级 token，proof-sdk 还有一层创建入口的鉴权开关，由环境变量控制（实现见 server/hosted-auth.ts）：

而遗留的POST /api/documents路由则由另一个开关PROOF_LEGACY_CREATE_MODE单独管理（allow/warn/disabled/auto）。

token 安全最佳实践清单

结合源码实现，给出 6 条可直接落地的实践：

1. ownerSecret只留在服务端。它拥有暂停、恢复、撤销、删除文档的全部权限，应存入密钥管理或数据库，绝不进前端、日志或聊天窗口。
2. 最小角色原则。给外部协作者签发accessToken时按需选择viewer/commenter/editor，而不是把ownerSecret发出去"图省事"。
3. 善用吊销机制。revokeDocumentAccessTokens支持按角色批量吊销 token，且会自增access_epoch（server/db.ts），让旧凭证立即失效；POST /documents/:slug/revoke可整体撤销文档访问。
4. 警惕 URL 中的 token。tokenUrl出现在浏览器历史、Referer 与日志里。对外分享优先用干净的shareUrl，token 链接仅在必要时下发。
5. 服务端已做哈希存储：所有 token 在数据库中以 SHA-256 哈希保存（secret_hash），并用 timing-safe 比较校验（server/db.ts 的timingSafeEqualString），防时序侧信道。你的自研接入层也应避免在日志中打印明文 token。
6. 变更请求带Idempotency-Key。重试场景下同一幂等键复用不同 payload 会收到IDEMPOTENCY_KEY_REUSED错误，既保安全又保可重放（契约见 AGENT_CONTRACT.md）。

相关文件导航

• 认证契约与 token 语义：AGENT_CONTRACT.md
• Agent 接入与 token 使用示例：docs/agent-docs.md
• 共享链接与凭证解析路由：server/routes.ts
• token 签发、吊销与角色解析：server/db.ts
• 创建入口鉴权模式：server/hosted-auth.ts
• 角色类型定义：server/share-types.ts
• 官方技能文档：docs/proof.SKILL.md

一句话总结：ownerSecret是钥匙串，accessToken是门禁卡——把钥匙串锁进保险柜，把门禁卡按需发出去，再用好吊销与幂等这两道保险，你的 proof-sdk 共享文档就能既协作又安全。🔐