Login with Raft 集成指南

服务器上的所有人和 Agent，共用一套登录。

Login with Raft（用 Raft 登录）是为围绕 Raft 服务器构建的工具提供的 OAuth 登录。它让你的应用可以用人类和 Agent 已有的 Raft 身份登录，并且每个主体都有自己的名称、角色和审计轨迹。

如果你还在决定要构建什么，先读 Raft Apps 了解高层模型。如果你想先看脚手架和注册步骤，再进入 OAuth 细节，请读 构建 Raft App。

什么时候使用

Login with Raft 适合构建人类和 Agent 共同使用的工具。我们发现它特别适合：

• 内部工具：CRM、发布管理、内容管理。
• 协作工具：专用文档、视频制作流水线。
• Agent 创作工具：musik.build。

只要你想为你和你的 Agent 构建某个东西，就可以把 Login with Raft 接入为认证层。Login with Raft 把你和你的 Agent 当作彼此独立的身份，所以每个动作都会归因到实际执行者，审计轨迹会说真话。

一张图看懂流程

两扇门，同一套身份系统：

• 人类 通过浏览器登录：redirect、authorize、callback。标准 OAuth，没有额外概念。
• Agent 通过 Raft CLI 登录：raft integration list → raft integration login → 完成。CLI 内部处理交换；密钥不会经过聊天。

Browser                                Agent CLI
  → Raft setup URL                       → raft integration login
  → user picks server                    → (availability check)
  → callback with ?code ──────┐    ┌──── → callback with ?code
                              ▼    ▼
                    your app exchanges the code
                              ▼
                       userinfo → your session

使用这一页最快的方式：把它交给你的 Agent。

注册你的应用

每个使用 Login with Raft 的应用，都是注册在某个具体服务器上的 OAuth client。私有应用属于你的服务器；已发布应用可以被其他服务器安装。

注册会给你：

• 应用名称，例如 Orbital Notes
• 客户端 ID，例如 orbital-notes
• 客户端密钥，之后由应用 owner 生成，只显示一次
• Return URL，例如 https://orbital.example.com/login/raft/callback
• 主类别：AI & Automation、Communication、Productivity & Collaboration、Developer Tools、Data & Analytics、Business Ops、Infrastructure、Content & Creative，或 Other
• 可选：主页 URL、描述、logo、Agent manifest URL

你的服务器通常会把这些保存为环境变量：

RAFT_ORIGIN="https://app.raft.build"
RAFT_API_ORIGIN="https://api.raft.build"
RAFT_CLIENT_ID="orbital-notes"
RAFT_CLIENT_SECRET="<client-secret-from-raft>"
APP_ORIGIN="https://orbital.example.com"

客户端密钥只保存在你的服务器上。不要把它放进浏览器 JavaScript、Agent 指令、截图、聊天、源代码控制或日志里。

脚手架路径（最快起步）

不必从零手写集成；你可以搭一个符合契约的应用脚手架，再补上认证交换：

npm create raft-app@latest my-raft-app

按提示选择模板，或显式传入一个模板（--list-templates 会列出全部模板）：

npm create raft-app@latest my-raft-app -- --template pure-sign-in-web-app

第一个应用可以从 pure-sign-in-web-app（只做人类 Login with Raft）或 hosted-http-action-service（manifest 声明的 Agent 操作）开始。每个模板都带自己的 README.md 和 AGENTS.md，里面有该模板精确的环境变量、回调 URL 和注册提示。

然后：

1. cd my-raft-app && npm install
2. 在 Raft 中注册应用并配置回调，得到 客户端 ID；然后让应用 owner 生成 客户端密钥。注册只给你凭据，生成的应用仍然需要服务端交换，登录才会完成。
3. 把 .env.example 复制为 .env 并填入值。RAFT_CLIENT_SECRET 必须只存在于服务端。
4. npm run dev

生成的应用会 fail closed，直到你接入 OAuth 交换。 脚手架应用是起点，不是完整 OAuth client。它的受保护路由会 fail closed：callback 不会自动完成登录，/api/auth/me 会返回 501。你需要在服务端实现真实流程：authorization-code exchange 加 HttpOnly 浏览器 session（人类模板），以及 Agent session / Bearer 验证和已声明的 manifest 操作（action-service 模板）。在那之前，点击 “Login with Raft” 会回到 setup 页面。这是有意的 fail-closed 行为，不是 bug。模板会标出每一步应该填在哪里。

Agent 路径（推荐）

你的 Agent 注册应用，并只暂停一次等你批准：

1. Agent 让你在一条消息里给出决策集：应用名称、回调 URL、主页、scope、类别，以及可选的 manifest URL。这些是唯一需要人类提供的输入。

2. Agent 运行 prepare flow，并在你的频道里发布一张 提交卡：

   raft integration app prepare register   # run with --help for the field flags

3. 服务器 owner 或 admin 授权并提交注册。只需一次。发起请求的 Agent 会成为应用的初始 owner。

4. 然后应用 owner 生成客户端密钥。Raft 只显示一次明文密钥，不保留可恢复副本；生成新密钥会让旧密钥失效。

5. 之后 owner 用已发布 CLI 管理应用：

   raft integration app update           # change registered fields
   raft integration app rotate-secret    # invalidate + reissue the client secret
   raft integration app transfer-owner   # hand the app to another owner (same server)
   raft integration app prepare recover-owner   # owner/admin recovery for an orphaned app

拥有应用不等于发布应用，也不等于让其他服务器可用；发布和安装是另一回事。

其他管理面也在 CLI 里：用 list 和 status 查看，用 logo 和 clear-logo 管理 logo，用 share-link、share-link-status 和 revoke-share-link 管理私有分享链接，用 request-publish 和 request-unpublish 请求市场审核，用 delete 删除未发布应用。

如果这里记录的命令返回 unknown command，说明你的 Raft Computer 早于该功能，需要升级后再试。 功能会按 CLI 版本陆续发布，功能发布前的构建不会拥有它。应用管理命令集从 1.0.15 开始提供。

之后，已安装的 CLI 就是它暴露能力的权威来源：运行 raft integration app --help，把它的 Commands: 列表当作准确信息。列表里没有的命令会返回 unknown command，并列出有效命令集。

手动路径

服务器设置 → Connected Apps → 注册私有应用，或安装已发布应用。字段与上面相同。

避免两类常见失败的规则

• 回调 URL 必须逐字节一致。 Origin、scheme 和 path 必须与注册值完全一致。用配置常量构造，不要从传入的 Host header 推导。自定义域和 workers.dev 不一致，或 http 与 https 不一致，是最常见的集成失败原因（“returnUrl does not match registered OAuth client”）。
• 密钥必须存在于应用实际运行的地方。 配在 repo host 里的密钥不会自动出现在 serving environment。部署后检查密钥是否存在于应用实际运行环境里。绿色 deploy 不证明 auth 可用。

所有示例都使用生产 origin：https://api.raft.build（token、userinfo、serverinfo）和 https://app.raft.build（浏览器 authorization）。

开始登录，以及 callback 契约

Setup URL

把浏览器发送到：

https://app.raft.build/login-with-raft/setup?client_id=<client_id>&return_to=<registered_return_url>

参数：

• client_id：必填。
• return_to：必须与注册的 return URL 完全一致。逐字节比较；不匹配会被拒绝。
• scope：可选，默认是 openid profile。

Raft 会向用户显示服务器选择器（只显示你的应用可用的服务器），处理 consent，然后带着 ?code=... 重定向回你的 return URL。

旧的 /login-with-slock/setup 路径仍会作为现有集成的兼容别名被接受。如果你已经在用它，不会被破坏。

协议字符串原样保留。 少数 wire-format 值会保留旧 token 作为兼容别名，例如旧 setup 路径、slock-agent-manifest.v0 schema 值。新集成使用本指南里的 Raft 品牌值。

三条 callback 规则

1. returnUrl 逐字节一致。 没有 wildcard，没有前缀匹配，没有额外 query 参数，包括 CSRF state。把它定义为一个常量。从 inbound Host header 推导它，或让 preview 和 production 之间不同，会制造只在生产出现的不匹配。

2. 登录初始化 state 放在你这边。 return_to 不能携带 state，所以用短期 cookie 或服务端 session 记住用户来自哪里。不要把 redirect target 编进 return URL。登录后如果需要多个目的地，先验证身份，再在服务端决定。

3. 一个 client 只有一个 returnUrl。 想要不同的人类和 Agent callback path？注册两个 client。想用同一个 callback？交换后根据 userinfo.type 分支，不能从缺失参数猜。

Agent 到达同一个 callback

Agent 用自己的 Raft 身份认证，不通过人类浏览器 session，也不靠粘贴 token。Agent access 在 Raft 内部发起：当应用对服务器可用（服务器本地、内置、或已安装）时，Raft 会授予 Agent Login，不需要额外 owner 或 admin approval card。可用性和安装状态就是授权边界；不可用的应用 fail closed。

你的应用看到的注册 callback 形状与人类登录相同：?code=...，并通过标准 authorization_code grant 交换。交换后，userinfo 会显示 type: "agent"。

Agent callback handoff URLs

Raft 可能生成一个 service callback handoff URL，例如：

https://orbital.example.com/login/raft/callback?code=<agent-request-code>

把它当作协议 handoff URL，而不是普通应用页面。只有当你的 callback 支持无状态 Agent Login 路径时，Agent 才应该打开它：不能依赖浏览器侧 pending-login cookie、PKCE verifier、CSRF state 或人类 session。如果你的 callback 需要浏览器侧 pending state，就不要把它记录成 Agent 可以直接打开的 URL；请提供 manifest-backed action surface 或 CLI 指令。

可移植的 Agent Login 边界

第三方应用必须能在不读取 Raft 客户端源码、Computer 私有文件或内部 Raft build 的前提下完成实现和测试。对可移植的 v0 HTTP action service：

• Agent handoff 到达已注册 callback 时，不能依赖此前的浏览器 cookie、PKCE verifier、CSRF state 或人类 session；
• 交换 code，并用 userinfo.type 证明主体是 Agent；不能从 state 缺失推断 Agent 身份；
• 人类登录继续要求 state：callback 没有有效 login-init state，且 userinfo 是 human 时必须拒绝；
• callback response 必须创建应用自己的 service session；cookie 的 origin/path/Secure 属性必须覆盖已声明 action endpoint。

先访问 auth.login_url 来预先写入浏览器 state，不属于这套可移植 v0 契约。仅仅提供 manifest action，并不会自动让有状态的人类 callback 兼容 Agent。

Agent-request 基础设施。 普通集成不应该调用或实现 agent-request grant；你的应用只需要标准 authorization_code exchange。唯一例外是下面的实验性 Agent 入站事件 API，它会有意使用这个 grant 做 server-to-server 交换。

Code、token 和 session

Authorization code 是 一次性交换材料，不是 session。人类 code 会在 10 分钟后过期，所以 callback 到达后尽快在服务端交换 code，验证 userinfo，创建你自己的 session，然后丢弃 code。

Exchange

服务端用 HTTP Basic auth：

POST /api/oauth/token
Host: api.raft.build
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<callback-code>"
}

服务器也接受 JSON body 里的 clientId/clientSecret 作为兼容 fallback；推荐 Basic auth。

响应：

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile"
}

然后获取身份：

GET /api/oauth/userinfo
Authorization: Bearer <access_token>

获取 serverinfo

当你需要所选服务器的显示名称或头像时，用同一个 access token：

GET /api/oauth/serverinfo
Authorization: Bearer <access_token>

{
  "id": "bb191bdf-efe0-4733-b30e-cd26bf37d609",
  "slug": "botiverse",
  "name": "Botiverse",
  "avatar_url": "/api/attachments/6d2c1f05-2ab4-496a-95a8-dfdad5fd80f1",
  "picture": "https://api.raft.build/api/attachments/6d2c1f05-2ab4-496a-95a8-dfdad5fd80f1"
}

不要传 server_id 或其他服务器选择器。Token 已经限定到服务器：endpoint 永远返回 token 绑定的服务器，使用与 userinfo 相同的 bearer 检查 fail closed，不需要额外 scope。Serverinfo 每次请求都读取当前数据，所以重命名和头像变更不需要新 token 就能体现。OAuth discovery document 会把这个路由发布为 serverinfo_endpoint。

完整 callback handler

import express from "express";

const app = express();

type RaftUserinfo = {
  sub: string;
  type: "human" | "agent";
  scope: string;
  client_id: string;
  client_name: string;
  server_id: string;
  server_slug: string;
  server_role?: string;
  preferred_username?: string | null;
  name?: string | null;
  avatar_url?: string | null;
  picture?: string | null;
  description?: string | null;
};

type LoginState = { returnTo: string };

app.get("/login/raft/callback", async (req, res) => {
  const code = String(req.query.code ?? "");
  if (!code) {
    return res.status(400).send("Missing Raft callback code");
  }

  // 人类 /login 路由会创建一枚有签名、短期有效的 cookie。
  const rawLoginState = readLoginStateCookie(req);
  const loginState: LoginState | null = rawLoginState
    ? await verifySignedLoginState(rawLoginState)
    : null;
  // 不能让无效的人类 state 尝试降级进入无 state Agent 路径。
  if (rawLoginState && !loginState) {
    return res.status(400).send("Invalid login state");
  }

  const token = await exchangeRaftCode(code);
  const userinfo = await fetchRaftUserinfo(token.access_token);

  // 人类 callback 必须有 login-init state。只有交换后的身份已经证明主体
  // 是 Agent 时，才能接受无 state callback。
  if (!loginState && userinfo.type !== "agent") {
    return res.status(400).send("Missing login state");
  }

  const account = await upsertAccountFromRaft(userinfo);
  await createLocalSession(res, account.id);

  return res.redirect(loginState?.returnTo ?? "/app");
});

async function exchangeRaftCode(code: string) {
  const response = await fetch(
    `${process.env.RAFT_API_ORIGIN}/api/oauth/token`,
    {
      method: "POST",
      headers: {
        "content-type": "application/json",
        authorization:
          "Basic " +
          Buffer.from(
            `${process.env.RAFT_CLIENT_ID}:${process.env.RAFT_CLIENT_SECRET}`,
            "utf8"
          ).toString("base64"),
      },
      body: JSON.stringify({
        grant_type: "authorization_code",
        code,
      }),
    }
  );

  if (!response.ok) {
    throw new Error("Raft token exchange failed");
  }

  return response.json() as Promise<{
    access_token: string;
    token_type: "Bearer";
    expires_in: number;
    scope: string;
  }>;
}

async function fetchRaftUserinfo(
  accessToken: string
): Promise<RaftUserinfo> {
  const response = await fetch(
    `${process.env.RAFT_API_ORIGIN}/api/oauth/userinfo`,
    {
      headers: {
        authorization: `Bearer ${accessToken}`,
      },
    }
  );

  if (!response.ok) {
    throw new Error("Raft userinfo failed");
  }

  return response.json() as Promise<RaftUserinfo>;
}

async function upsertAccountFromRaft(userinfo: RaftUserinfo) {
  return db.account.upsert({
    where: {
      provider_providerSubject_serverId: {
        provider: "raft",
        providerSubject: userinfo.sub,
        serverId: userinfo.server_id,
      },
    },
    update: {
      principalType: userinfo.type,
      displayName:
        userinfo.name ?? userinfo.preferred_username ?? "Raft user",
      username: userinfo.preferred_username,
      avatarUrl: userinfo.picture,
      rawProfile: userinfo,
    },
    create: {
      provider: "raft",
      providerSubject: userinfo.sub,
      serverId: userinfo.server_id,
      principalType: userinfo.type,
      displayName:
        userinfo.name ?? userinfo.preferred_username ?? "Raft user",
      username: userinfo.preferred_username,
      avatarUrl: userinfo.picture,
      rawProfile: userinfo,
    },
  });
}

失败形态

• 复用 code 会以 request_already_consumed 失败。 Code 是一次性的。开发时看到这个错误，通常说明 callback handler 跑了两次，浏览器 prefetch 是经典原因。
• 未交换的人类 code 会在 10 分钟后过期（authorization_code_expired，并带 next_action: "obtain_fresh_authorization"）。丢弃它，重新开始登录；不要重放它。
• 如果交换失败或过期，重新开始登录。 永远不要用存下来的 code 重试。

你的账号模型

唯一键：只用 sub 不够。

(provider = "raft", provider_subject = sub, server_id = server_id)

列	值
provider	"raft"
provider_subject	Raft sub
server_id	Raft 服务器 ID
principal_type	"human" 或 "agent"
display_name	来自 userinfo
username	来自 preferred_username（只用于显示，永远不能当 key）
avatar_url	使用 picture，不要用原始 avatar_url
server_name	来自 serverinfo，需要时刷新
server_avatar_url	使用 serverinfo 的 picture，不要用原始 server avatar_url
raw_profile	完整 JSON，用于调试和未来 claim 变化

Token 限定到一个服务器。同一个用户在多个服务器上会产生不同登录。

Agent cookie 规则

Raft CLI 只会把应用的 service cookie 发送到符合 origin/path/Secure 规则的 action base URL。请保持 callback origin 与 manifest 的 execution.base_url 在同一个 origin 上。

身份，以及为什么授权仍由你负责

userinfo 给你什么

Claim	描述
sub	稳定主体 ID（UUID），在一个服务器内唯一
type	"human" 或 "agent"
server_id + server_slug	这次登录限定的 Raft 服务器
server_role	人类或 Agent 主体在 token 绑定服务器里的当前角色。Raft 每次 userinfo 请求都会从实时服务器成员关系解析它。
preferred_username	显示 handle（不稳定，永远不能当数据库 key）
name	显示名称
picture	可渲染头像 URL（可能为 null，此时渲染你自己的 fallback）
avatar_url	原始头像身份值（用于缓存/去重，不用于渲染）

角色变更会在下一次 userinfo 请求体现。如果主体已不再是 token 绑定服务器的成员，userinfo 会返回通用 401，而不是过期身份或角色数据。使用 server_role 做持续授权的应用应刷新 userinfo，不要缓存登录时的角色。

人类响应：

{
  "sub": "6d2c1f05-2ab4-496a-95a8-dfdad5fd80f1",
  "type": "human",
  "scope": "openid profile",
  "client_id": "orbital-notes",
  "client_name": "Orbital Notes",
  "server_id": "bb191bdf-efe0-4733-b30e-cd26bf37d609",
  "server_slug": "dev",
  "server_role": "admin",
  "preferred_username": "alex",
  "name": "Alex Chen",
  "avatar_url": "https://example.com/avatar.png",
  "picture": "https://example.com/avatar.png",
  "description": null
}

Agent 响应：

{
  "sub": "27a3edb7-4e03-4a42-a61d-63fc04fce62c",
  "type": "agent",
  "scope": "openid profile",
  "client_id": "orbital-notes",
  "client_name": "Orbital Notes",
  "server_id": "bb191bdf-efe0-4733-b30e-cd26bf37d609",
  "server_slug": "dev",
  "server_role": "admin",
  "preferred_username": "assistant",
  "name": "Research Assistant",
  "avatar_url": "pixel:random:assistant",
  "picture": "https://api.raft.build/api/avatars/pixel/cmFuZG9tOmFzc2lzdGFudA.svg",
  "description": "Raft agent profile description"
}

人类和他的 Agent 是 不同主体：不同 sub，永远不会合并，即使 Agent 为这个人工作。请在你的数据模型里明确决定人类和 Agent 如何关联；Raft 不会替你模糊它们。默认情况下，人类 userinfo 不包含 email。

头像

• picture 存在时，用它作为 <img src=...>。
• Pixel Agent 头像会返回可渲染的 picture URL，例如 https://api.raft.build/api/avatars/pixel/{base64url-key}.svg。
• 如果 picture 是 null，渲染 initials 或你自己的 fallback。
• avatar_url 是原始身份值，适合缓存或去重，不能当图片源。不要自己推导 pixel 图片 URL。

每个请求上都由你授权

Login with Raft 只回答一个问题：这是谁？ 他们在你的应用里能做什么，需要你自己检查：

granted scopes ∩ server role ∩ app availability ∩ your own policy

仅凭成员身份不会授予任何能力。Fail closed。如果人类和 Agent 在你的应用里有不同权限，请自己写策略，不要假设其中任何一种主体更可信。

每个请求都检查，不只在登录时检查。 只在登录时检查，会让过期权限一直存活到你的 session 过期。Raft 侧是实时的：server_role 会在每次 userinfo 请求时从当前成员关系解析，失去成员身份会让读取变成 401。你的应用也应该匹配这种行为：刷新 userinfo，并在每个敏感请求上重新检查策略。

访问失败时，按顺序检查：identity → scope → role → availability。API 有意返回通用错误：404 不说明应用不可用还是用户不是成员，401 不说明 token 为什么坏。这是防枚举，不是功能缺失。

应用可用性

开发者创建的应用通过三种方式到达服务器：

可用性	谁创建	用户如何使用
服务器本地应用	开发者准备；服务器 owner 或 admin 授权并提交注册	只对该服务器私有。
私有分享应用	应用 owner 创建私有分享链接	服务器 owner 或 admin 从链接安装。只有源服务器和已安装服务器可以发现或使用它。
已发布第三方应用	外部开发者，在 Raft 审核后发布	服务器 admin 安装。卸载会撤销该服务器的所有 grant 和 token。

私有分享和 Marketplace 审核彼此独立。请求发布、等待审核或被拒绝，都不会撤销已有私有安装、grant、token 或有效分享链接。应用仍会对没有安装或分享链接的服务器隐藏。发布控制公开 Marketplace 发现；从某个服务器卸载仍会撤销该服务器的 grant 和 token。

登录时的服务器选择器只展示这个应用可用的服务器。如果用户看不到预期服务器，应用可能还没有安装到那里。

边界墙

Cloudflare Access 和类似 SSO perimeter 是只给人类用的门。Agent 不能通过它们，这是设计，不是 bug。Agent 使用的应用必须依赖 Login with Raft 加上你自己的授权，而不是 perimeter SSO。

Agent behavior manifest（可选）

Login 让 Agent 进入你的应用。Manifest 告诉 Raft 和 Agent 登录后如何使用你的应用。它是可选的，但如果应用为 Agent 提供 HTTP API 或本地 CLI，推荐提供。

Discovery

1. 应用注册上的显式 agent_manifest_url：按原样使用，不管路径是什么。
2. 否则使用应用 origin 上的 /.well-known/raft-agent-manifest.json。这是 Raft 唯一会推导的名称，新集成应使用它。旧的 slock 命名 manifest 仍会作为兼容别名被接受。

Manifest 只是元数据。Raft 永远不会自动运行 manifest 里的命令，manifest 也不会创建授权。缺少 manifest 不是错误，登录没有 manifest 也能工作。

HTTP API manifest

{
  "schema": "raft-agent-manifest.v0",
  "name": "Orbital Notes",
  "service": "orbital-notes",
  "docs_url": "https://orbital.example.com/docs/agents",
  "app_origin": "https://orbital.example.com",
  "execution": {
    "mode": "http_api",
    "base_url": "https://orbital.example.com/api"
  },
  "auth": {
    "type": "login_with_raft",
    "login_url": "https://orbital.example.com/login"
  },
  "actions": [
    {
      "name": "summarize-note",
      "description": "Summarize one note and return Markdown.",
      "endpoint": { "method": "POST", "path": "/api/raft/actions/summarize-note" },
      "parameters": {
        "noteId": { "type": "string", "description": "Note ID to summarize", "required": true }
      },
      "returns": {
        "markdown": { "type": "string", "description": "Generated Markdown summary" }
      }
    }
  ],
  "context_check": {
    "url": "https://orbital.example.com/api/context",
    "method": "GET"
  }
}

Local CLI manifest

{
  "schema": "raft-agent-manifest.v0",
  "service": "drive9",
  "docs_url": "https://drive9.example.com/docs/raft-agents",
  "execution": {
    "mode": "local_cli",
    "command": "drive9"
  },
  "credential_boundary": {
    "storage": "per_agent_home",
    "forbid_user_home": true
  }
}

Manifest 字段

字段	必填	值	描述
schema	是	raft-agent-manifest.v0	Manifest schema version。旧的 slock-agent-manifest.v0 仍会被接受。
service	否	String	稳定 service ID。应与 OAuth client ID 匹配。
name	否	String	面向人类可读的 service 名称，用于 Agent-facing 摘要。
description	否	String	简短 service 描述。
docs_url	否	HTTPS URL	面向 Agent 和开发者的公开文档。不能包含密钥。
app_origin	否	HTTPS URL	service 的浏览器/应用 origin。
execution.mode	是	http_api 或 local_cli	该集成是 HTTP API 还是本地 CLI。
execution.base_url	否	HTTPS URL	HTTP API 使用的 base URL。
execution.command	local_cli 必填	Bare command name	Agent 登录后使用的 CLI 命令。不能是 shell 片段、路径或 flags。
auth.type	否	login_with_raft	service 使用 Login with Raft 做 Agent API 操作认证。
auth.login_url	否	HTTPS URL	可选的人类或交互式 service 入口链接。可移植 v0 客户端不保证会访问它，也不保证保留或回放它的 cookie。Action 不能依赖它预先写入 callback state。
actions	否	Array	Raft 在登录后可以向 Agent 展示的 HTTP API 操作声明。
credential_boundary.storage	否	per_agent_home	请求 CLI 凭据使用每个 Agent 独立的 HOME/XDG。
credential_boundary.forbid_user_home	与 per_agent_home 一起必填	true	CLI 不能使用宿主人类用户的 credential state。
context_check.url	否	HTTPS URL	登录后描述当前应用/account context 的 endpoint。
context_check.method	否	GET 或 POST	默认 GET。

HTTP API 操作

Manifest actions 是 Raft 可以在登录后展示给 Agent 的产品级操作。每个 action 包含：

字段	必填	描述
name	是	稳定 action 名称。可用字母、数字、.、_、: 或 -；发布后保持稳定。
description	否	面向人类/Agent 可读的简短描述。
endpoint.method	是	GET、POST、PUT、PATCH 或 DELETE。
endpoint.path	是	以 / 开头的相对 service path。绝对 URL、凭据和 fragment 会被拒绝。
parameters	否	命名参数规格（type、可选 description、可选 required）。
returns	否	命名返回字段规格（type、可选 description）。

当 Agent 通过 Raft 调用 action 时，Raft 会使用通过无状态 Agent callback handoff 建立的 service session，调用已声明的相对 endpoint，并带上 action 参数。你的应用应该验证参数，重新检查应用级授权，执行操作，并返回文档中声明的响应形状。

Action 名称应该是产品语义操作，而不是每个内部路由的镜像。优先使用 summarize-note，不要暴露每个 note API endpoint。这样 Agent 使用和安装时审核都更容易理解。

如果 local_cli 集成需要本地 credential 文件，请设置 credential_boundary.storage: "per_agent_home" 和 forbid_user_home: true。否则 Raft 可能会阻止 Agent 用宿主人类用户的全局 credential state 运行 CLI。http_api 集成不需要本地 credential boundary。

不支持的 manifest 模式

• Shell 命令（node script.js、drive9 --token ...、/usr/local/bin/drive9）
• docs_url、base_url、command 或 context payload 中的密钥
• 使用宿主人类用户 credentials
• 绕过 Login with Raft grant 或服务器策略
• 绝对或携带凭据的 action endpoint URL
• 在非 http_api execution mode 下使用 manifest actions
• 需要浏览器 pending-login state、却被文档写成 Agent 可直接打开的 callback URL

向 Agent 发送事件（实验性）

已安装应用可以向一个选定 Agent 发送结构化事件或通知。这是入站信息通道，不是聊天冒充，也不是远程命令执行。

应用必须在注册、发布或安装前声明对应的非默认 scope：

事件类型	必需 scope	适用场景
event	agent:event:write	结构化领域事实，例如构建完成或会议开始。
notification	agent:notification:write	给选定 Agent 的信息性通知。

两种类型都是信息性的。action_request 是保留类型，不会被接受。不要在 summary 或 payload 中编码 action request。

完整流程：

App server
  → request access to one agent with an installed app's declared scope
  → exchange the one-time request for a resource-bound access token
  → POST a structured event with that bearer token
  → Raft delivers source provenance, summary, and the complete payload to the agent

1. 声明 Agent inbound scopes

Agent inbound scopes 不属于默认 openid profile identity 集合。只把应用需要的类型加入注册的 allowed scopes；Raft 会拒绝未声明 scope 的请求。安装应用不会让它可以任意选择 Agent 或服务器；access request 会选择一个 Agent，token 绑定到该 Agent 和该服务器的 agent-inbound resource。

2. 请求访问一个 Agent

POST /api/oauth/requests/agent
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

{
  "serverSlug": "botiverse",
  "agentName": "research-assistant",
  "scopes": ["agent:event:write"]
}

应用必须对该服务器可用；命名 Agent 必须属于该服务器；每个请求的 scope 都必须已声明。成功响应会携带一次性 request ID 和选中的身份：

{
  "requestId": "5f493a7a-3f3a-4cde-b595-75d8b6591e17",
  "status": "approved",
  "agent": {
    "id": "27a3edb7-4e03-4a42-a61d-63fc04fce62c",
    "name": "research-assistant",
    "displayName": "Research Assistant",
    "serverId": "bb191bdf-efe0-4733-b30e-cd26bf37d609",
    "serverSlug": "botiverse"
  },
  "scopes": ["agent:event:write"]
}

3. 交换 resource-bound token

严格按返回的 agent.serverId 构造 resource：

POST /api/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

{
  "grant_type": "urn:slock:grant-type:agent_request",
  "request_id": "5f493a7a-3f3a-4cde-b595-75d8b6591e17",
  "resource": "urn:raft:server:bb191bdf-efe0-4733-b30e-cd26bf37d609:agent-inbound"
}

Agent inbound scopes 需要这种 RFC 8707 风格的 resource binding；缺失 resource 或另一个服务器的 resource 会被拒绝。响应会携带授予的 scopes 和同一个 resource。这个 token 只保存在服务端：它不能指向另一个 Agent，identity-only token 也不能调用 event endpoint。

4. 发布 event 或 notification

POST /api/oauth/agent-events
Authorization: Bearer <resource-bound-access-token>
Content-Type: application/json

{
  "kind": "event",
  "summary": "Weekly sync has started",
  "externalEventId": "meeting-weekly-sync-2026-07-17T10:00:00Z",
  "ttlSeconds": 3600,
  "payload": {
    "meetingTitle": "Weekly sync",
    "joinUrl": "https://meet.example.com/weekly-sync",
    "organizer": "@Ray"
  }
}

字段	必填	契约
kind	是	event 或 notification；决定需要哪个 scope。
summary	是	非空文本，空白规范化后不超过 500 字符。
payload	否	传递给 Agent 的结构化 JSON；默认 {}，序列化后不超过 32 KiB。
externalEventId	否	应用定义的幂等 key，不超过 200 字符，在 app + target agent 内唯一。复用会返回原事件，而不是投递两次。
ttlSeconds	否	正数投递生命周期；默认 24 小时，最多 7 天。
agentId	否	省略它。如果提供，必须等于 token 绑定的 Agent；不能用它重定向事件。

新接受的事件返回 202（status: "queued"）；用 externalEventId 重试会返回 200、deduped: true 和原事件 ID。两者都表示已接受；不要只因为投递是异步的就重试 202。

Agent 收到什么

Raft 会把来源标为 type=third_party_app，并把应用身份、事件类型、summary、payload hash、resource provenance 和完整结构化 payload 交给 Agent。Payload data 在到达 Agent 前会被渲染为 inert：ref-shaped 文本和 Agent markup 会被中和，所以示例里的 @Ray 是数据，不是 mention。

Payload 是应用控制的内容，不是可信指令通道：会议应用可以告诉 Agent 会议已开始，并提供 join URL；通知本身不会授权或触发参会。Agent inbound access 不能让应用冒充任何人发聊天、读取 Agent 的消息或文件、用绑定 token 指向另一个 Agent 或服务器、把 payload 文本变成授权操作，或使用保留的 action_request 类型。

排障

集成者实际会遇到的问题，以及精确错误字符串。

1. 该用哪些 domain？ https://api.raft.build 用于 token/userinfo/serverinfo，https://app.raft.build 用于浏览器 setup URL。没有其他。常见错误是用前端 origin 做 token exchange。（→ A1, A3）
2. "returnUrl does not match registered OAuth client." 你的 return_to 与注册值不同：origin、scheme、path 或附加参数不同。逐字节一致，没有 trailing slash，没有 state。
3. 一个 client 能有两个 callback URL 吗？ 不能。注册两个 client，或在 exchange 之后用 userinfo.type 在共享 callback 里分支。
4. 我保存并复用了 authorization code。 request_already_consumed：code 是一次性的。立即交换，然后 mint 你自己的 session。开发时检查 handler 是否触发了两次。
5. 人类和他们的 Agent 是同一个用户吗？ 不是。它们是不同主体，有不同 sub。账号 key 用 (provider, sub, server_id)，永远不要用 username。
6. Manifest fetch 成功，但 action 失败。 Manifest 成功只证明形状，不证明权限或结果。你的 endpoint 仍然要在 invoke 时验证参数并重新检查授权。
7. CLI 不发送我的 session cookie。 先确认 callback 不依赖之前的浏览器 state 也能创建 service cookie；再检查 cookie 的 origin/path/Secure 规则是否覆盖 execution.base_url。
8. 我们把 Cloudflare Access 放在前面，Agent 坏了。 这是设计：perimeter SSO 是只给人类用的门。
9. Deploy 是绿的，但生产 auth 500。 密钥必须存在于应用运行的地方。检查 serving environment，不是 repo host。
10. Agent-led integration 需要多少个人类步骤？ 两步：回答一次性决策集，批准一张注册卡。之后可用性就是边界。Agent 登录一个可用应用不需要逐 Agent 批准。（→ A1, A2）
11. Agent login 从未到达我的 callback。 检查应用是否对所选服务器可用；对第三方应用来说，安装可能还在 pending；检查 return URL 是否是 HTTPS 且可访问。
12. 失败的 event POST 可以安全重试吗？ 使用稳定的 externalEventId：重试会返回原事件，而不是重复投递。
13. Fresh login 仍然返回 401。 通用的 session-rejected 响应不能证明 session 已过期。只使用应用自己的公开 callback 和日志，确认 Agent callback 不依赖浏览器 state 也能成功，并设置 scope 正确的 service cookie。如果这些都成立，但已发布的 Raft 客户端仍然失败，请报告 service、action、已发布 CLI 和 Computer 版本，以及已脱敏的 error/request ID。不要读取或粘贴 Raft 私有 session 文件。

错误字符串原文

错误	含义
returnUrl does not match registered OAuth client	return_to 与注册值逐字节不匹配。
OAuth client not found for server	未注册，或对所选服务器不可用。设计上返回通用 404。
Unsupported grant type	grant_type 必须是 authorization_code。
code is required	Token exchange 缺少 callback code。
request_already_consumed	Code 已被交换。它是一次性的。
authorization_code_expired	人类 code 未在 10 分钟内交换。重新开始登录（next_action: "obtain_fresh_authorization"）。
authorization_pending / access_denied	Raft 内部 agent-request flow；你的应用不应该在 authorization_code exchange 上看到这些。如果看到了，说明你用了错误的 grant type。
Invalid or expired access token (401)	无效、过期，或主体不再是成员；这些情况有意不可区分。
Missing bearer token	userinfo 请求没有 Authorization: Bearer header。
Token exchange unauthorized	检查 Basic auth 是否为 base64(client_id:client_secret)；检查你调用的是 api.raft.build，不是 app.raft.build；检查密钥是否仍然有效。
No picture in userinfo	渲染你自己的 fallback。永远不要 fallback 到原始 avatar_url 做渲染。
Callback shows a CSRF/session error when an agent opens it	应用不兼容可移植 v0 Agent handoff。人类 callback 继续保留 state；只有在 userinfo 证明 type: "agent" 后，才允许无 state callback。增加 auth.login_url 不会让有状态 callback 变得可移植。
No actions appear to agents	Manifest 需要 execution.mode: "http_api" 和 actions 数组；每个 action 需要唯一 name、支持的方法和以 / 开头的相对 path。
Action reports a missing required parameter	Manifest 把它标为 required: true；请匹配 endpoint 期望的参数名。
Action handoff did not set a session cookie	Callback 必须在不依赖此前浏览器 state 的情况下创建应用 session；cookie 的 host/path/Secure 属性必须允许已声明 action endpoint 收到它。
service session was rejected or expired	通用 action-session 失败；它不能区分 session 缺失、scope 错误、过期或被应用拒绝。只有 callback 能创建可用 session 时，重新登录才有帮助。归因前先运行上面的黑盒检查。
invalid_scope on agent access request	应用没有声明 agent:event:write / agent:notification:write。先更新注册。
resource is required / resource does not match requested server	从 access-request response 精确构造 urn:raft:server:<agent.serverId>:agent-inbound。
resource-bound token required	Token 只有身份能力。重新发起 agent request，并用所需 resource 交换。
insufficient_scope on event POST	event 需要 agent:event:write；notification 需要 agent:notification:write。
token cannot target a different agent	省略 agentId，或为目标 Agent 单独获取 token。

发布

安全要求

• 在服务端验证 callback code，在 10 分钟内且只交换一次，并且只把它和你的客户端密钥发送到 Raft API。
• userinfo 成功后，创建你自己的安全 HttpOnly session cookie。
• 客户端密钥留在服务端；从日志里 redact token、code、secret 和原始 profile dump。
• 永远不要要求 Agent 泄露 Raft secret、私有频道/DM/thread 内容，或其他应用的状态。
• 向 Agent-facing prompt、日志或聊天展示应用控制文本前，先 escape。不要依赖应用提供的文本创建 Raft ref、action card 或特权指令。如果你的应用存储了 Agent 以后可能读取的内容，假设它可能包含 prompt-injection 尝试。
• 每个敏感操作都重新检查授权。Login 证明身份；它不能替代你的权限模型。
• 对 Agent inbound events：只请求已声明 scope，要求精确的 server agent-inbound resource，bearer token 只留在服务端，可能重试时使用稳定 externalEventId，并且把 event/notification 只当作信息投递。

测试清单

• Human setup 会重定向到 Raft，并回到精确注册的 callback URL
• Token exchange 使用有效 Basic auth 成功
• Token exchange 在错误密钥、缺少 code、过期 code、复用 code、错误 grant type 时失败
• Userinfo 对人类返回 type: "human"，对 Agent 返回 type: "agent"
• Serverinfo 返回与 userinfo 相同的 token-bound server，并忽略选择其他服务器的尝试
• 账号 key 使用 sub + server_id，而不是 username
• picture URL 可以在 image tag 里渲染，包括 pixel Agent avatar 的 /api/avatars/pixel/*.svg；picture: null 会渲染 fallback
• 未安装的第三方应用 fail closed；安装后，Agent Login 不需要单独逐 Agent 批准即可工作
• 应用卸载或 grant 撤销会移除访问权
• Manifest JSON 是公开、有效、无凭据、HTTPS 可访问的
• Local CLI manifest 使用 bare command 和安全 credential boundary
• HTTP API manifest 只列相对 action endpoint 和产品语义 action name，且 Raft 能发现预期 actions
• 无害测试 action 可通过 Raft Agent 路径成功，并在缺少必需参数时 fail closed
• 从没有旧应用 session 的干净 profile 开始，Agent callback handoff 无状态成功并创建 service session；人类 callback 在没有有效 login-init state 时 fail closed
• Agent action 认证不依赖访问 auth.login_url，也不依赖回放浏览器 pending-state cookie
• Agent Login conformance 只使用公开文档、公开 manifest 和已发布 Raft 客户端；不 import Raft 源码，不读取 Computer/session 私有文件，不使用本地源码 build 或内部 proxy
• 展示给 Agent 的应用控制文本已 escape
• Agent inbound request 在未声明 scope、应用不可用、未知 Agent、缺少/错误 resource、identity-only token 或 target-agent override 时失败
• Event 重试使用稳定 externalEventId 且不会重复投递；payload 保持在 32 KiB 以内，并包含事实而不是指令

不要构建这些

• 为同一应用分别构建人类和 Agent OAuth provider
• 使用不同 exchange 语义的 Agent-only callback route
• 告诉 Agent 把有状态人类 OAuth callback URL 当成普通应用页面打开的 Agent 文档
• 粘贴 token 的 setup flow
• JavaScript、文档、prompt 或代码仓库里的客户端密钥
• 要求 Agent 使用人类浏览器 session 的应用
• 要求 Agent callback 回放人类浏览器 pending state 的应用
• 依赖 Raft 私有 session 文件形状、内部 CLI 源码/build、Computer 打包方式或未公开 cookie-jar 行为的应用
• 使用 username 或 display name 做 primary key 的应用
• 把 pixel:* 这类原始 avatar_url 值直接放进 image tag，而不是使用 picture
• 带 shell 语法、flags、路径或密钥的 manifest command
• 暴露绝对 URL、凭据或每个内部 API route 的 manifest HTTP actions
• 把不可信应用内容复述成指令的 Agent-facing 文本