Embassy 身份

Federation 统一签发用户身份并保存账户数据。客户端通过 Embassy 直接访问 Federation；产品需要自己的后端能力时，再配置对应 Bureau 的可信业务入口。

身份边界

• Federation：服务端运行容器，签发 user_token，管理账户、Service 和 Bureau 记录。
• Embassy User：保存当前 user_token，执行用户登录和业务请求。
• Embassy Admin：使用管理员 Session 管理 Federation，包括授权 Federation 签发 Bureau Token。
• Bureau：由 bureau_id 区分的产品业务分区；产品后端使用独立 Bureau 客户端证明机器身份。

Embassy 只有 user 和 admin 两个身份子域：

import { Embassy } from "@downcity/federation";

const embassy = new Embassy({
  federation_url: "https://fed.example.com",
});

Embassy 本身不绑定 Bureau。登录流程需要产品分区时，才在本次登录中传入 bureau_id。

用户身份

账户流程统一位于 embassy.user.account。登录成功后，同一个 Embassy 实例会立即使用 新的 User Token：

const providers = await embassy.user.account.providers();

await embassy.user.account.login({
  provider: "email",
  bureau_id: "product-web",
  input: {
    email: "[email protected]",
    password: "password",
  },
});

const current_user = await embassy.user.current();
const user_token = embassy.user.account.token();

User Token 是 Federation 使用 Ed25519 私钥签发的 JWT。它包含 user_id、 bureau_id、issuer、audience 和有效期；公开验签密钥由以下接口发布：

/.well-known/downcity.json
/.well-known/jwks.json

用户侧 AI、Payment 和普通 Service 请求直接发送到 Federation：

const models = await embassy.user.ai.catalog();
const accounts = embassy.user.service("accounts");
const services = await embassy.user.list_services();

当当前 Bureau 配置了可信 server_url 时，相对路径请求会发送到该 origin，并自动携带 当前 User Token。Embassy 不会把 Token 转发到其他 origin：

const result = await embassy.user.post(
  "/reports/summary",
  { range: "today" },
);

管理员身份

管理员使用 ID 和密码换取有期限的 Admin Session。不存在 Root Admin Token：

await embassy.admin.login({
  admin_id: "owner",
  password: "password",
});

const current_admin = await embassy.admin.current();
const bureaus = await embassy.admin.bureaus.list();

密码遗失时，由拥有部署权限的人运行 fed deploy --admin-reset 重设管理员凭证。

Bureau Token

登录后的 Federation Admin 可以签发 Bureau Token：

fed bureau token

CLI 请求 Federation 生成高熵 Token。Federation 只保存 token_id、用途、hash 和生命周期状态， 明文只返回一次，应写入业务服务的部署环境：

DOWNCITY_FEDERATION_URL=https://fed.example.com
DOWNCITY_BUREAU_TOKEN=fb_br_xxx.secret

业务服务通过独立的 Bureau 客户端验证收到的 Federation User Token：

import { Bureau } from "@downcity/federation";

const bureau = new Bureau({
  federation_url: process.env.DOWNCITY_FEDERATION_URL!,
  bureau_token: process.env.DOWNCITY_BUREAU_TOKEN!,
});

const identity = await bureau.identify(request);

bureau_token 是长期、可撤销的不透明 Bearer 凭证，不是 JWT，也不能签发 User Token。 它在创建时绑定 bureau_id；identify() 会验证签名、issuer、audience、有效期和该 bureau_id。发生泄露时，使用 fed bureau token revoke <token_id> 立即撤销。

User Token 的签发权威始终是 Federation。账户登录或 Admin 管理接口都只是进入 Federation 签发流程的入口，Bureau Token 无权调用 User Token 签发接口。

继续阅读：

• Federation SDK
• 模型池
• 用量与计费