使用 Agent Auth 为代理完成注册

通过 Sigiro 的 Agent Auth API 注册代理主机、授予最小能力，并轮换或撤销其凭据。

当软件而不是人员需要向托管版 Sigiro 进行身份验证时，请使用 Agent Auth。Sigiro 支持委托身份：用户只需批准一次代理并将其绑定到工作区，之后代理即可使用自己的密钥和短期令牌无人值守运行。

无需安装另一个 Sigiro 可执行文件。请在代理主机中集成官方 @auth/agent SDK。 Sigiro 不支持自主代理身份。

开始之前

先创建或登录托管版 Sigiro 账户：

sigiro signup --name "Your Name" --email you@example.com
# 已有账户：
sigiro auth login

该账户必须仅属于一个 Sigiro 工作区。Agent Auth 会把获批代理绑定到此工作区。

请为 SDK 使用持久化密钥存储。SDK 会保存主机和代理的 Ed25519 私钥以及连接记录。默认内存存储只适用于短期示例；一旦丢失，就必须注册新身份。

1. 发现 Sigiro

读取在线提供方文档，不要硬编码生命周期路由：

curl -fsS https://sigiro.com/.well-known/agent-configuration | jq

确认 issuer 为 https://sigiro.com/api/auth，受保护资源为 https://sigiro.com，且 modes 仅包含 delegated。

列出可用能力：

curl -fsS https://sigiro.com/api/auth/capability/list | jq

只请求进程必需的能力。OTLP 导出器只需要 telemetry:ingest，不需要读取或告警管理能力。

2. 添加官方 SDK

aube add @auth/agent@0.6.2

使用 Sigiro 服务源创建客户端。生产环境必须传入持久化 storage，例如由密钥存储支持的 KVStorage。不要把私钥保存到源代码、日志、截图或未加密的应用状态中。

import { AgentAuthClient, MemoryStorage } from '@auth/agent';

const client = new AgentAuthClient({
  urls: ['https://sigiro.com'],
  allowDirectDiscovery: true,
  hostName: 'production-telemetry-host',
  storage: new MemoryStorage(), // 生产环境请替换为持久化密钥存储。
  onApprovalRequired: (approval) => {
    const url = approval.verification_uri_complete ?? approval.verification_uri;
    approvalUi.show({ url, code: approval.user_code });
  },
});

const providers = await client.init();
if (providers.length !== 1) throw new Error('Sigiro 发现失败');

approvalUi.show 表示经过身份验证且不会持久保存内容的操作员界面。该界面不得将批准 URL 或代码写入应用日志。

connectAgent 会生成主机和代理的 Ed25519 密钥。Sigiro 的发现文档和生产配置允许动态主机注册，因此此流程不需要单独的主机注册命令或令牌。管理员预先配置的主机则使用 SDK 的 enrollHost 流程及其一次性注册令牌；不要混用这两条路径。

3. 注册并批准代理

以委托模式连接，并且只请求遥测写入能力：

const connection = await client.connectAgent({
  provider: 'https://sigiro.com',
  mode: 'delegated',
  name: 'production telemetry exporter',
  capabilities: ['telemetry:ingest'],
  reason: "Send this service's OpenTelemetry data to Sigiro",
  preferredMethod: 'device_authorization',
});

if (connection.status !== 'active') {
  throw new Error(`代理未激活：${connection.status}`);
}

打开显示的验证 URL，登录 Sigiro，确认代码并批准请求的能力。SDK 会轮询，直到批准成功或请求过期。批准链接和代码有效期很短，但仍不得写入日志或支持工单。

批准后，请将 connection.agentId 与 SDK 的持久化状态一起保存。不要导出或复制私钥。

4. 验证遥测请求

在发送遥测请求之前立即签发新的能力限定令牌：

const authorization = await client.signJwt({
  agentId: connection.agentId,
  audience: 'https://sigiro.com',
  capabilities: ['telemetry:ingest'],
});

const headers = {
  Authorization: `Bearer ${authorization.token}`,
};

将此请求头附加到 https://sigiro.com/v1/traces、/v1/metrics、 /v1/logs 或 /v1development/profiles 的 OTLP/HTTP 请求。代理令牌有效期很短；导出器传输层必须在过期前获取新令牌，不要把单个令牌放入长期环境变量。

Sigiro 会先验证代理状态、工作区绑定、audience、重放状态和 telemetry:ingest 授权，再接收遥测数据。不要对另一个请求重复使用已签名令牌。

5. 轮换代理密钥

通过 SDK 轮换密钥：

await client.rotateAgentKey(connection.agentId);

该操作会替换已注册的公钥，并更新配置存储中的私钥。轮换后，请丢弃旧密钥签发的所有令牌。请确保 SDK 存储在重启后仍然可用，以便主机继续管理代理。

6. 撤销并验证

仅为负向验证创建一个令牌，然后撤销代理：

const tokenBeforeRevocation = await client.signJwt({
  agentId: connection.agentId,
  audience: 'https://sigiro.com',
  capabilities: ['telemetry:ingest'],
});

await client.disconnectAgent(connection.agentId);

disconnectAgent 会先撤销远程身份及其能力授权，然后删除本地连接。此后使用 tokenBeforeRevocation 发出的请求必须失败。Sigiro 的 OTLP/HTTP 端点会为已撤销的代理令牌返回 HTTP 401。如果请求仍被接受，应将其视为撤销失败并停止导出器。

如需停用整个主机而不是单个代理，请从批准该主机的 Sigiro 账户撤销主机。撤销主机也会撤销其下的所有代理。

故障排除

发现失败： 提供方 URL 应为 https://sigiro.com，而不是 issuer 路径。使用 curl 检查 well-known 文档。
批准过期： 再次调用 connectAgent，并在新请求超时前完成批准。
缺少能力： 明确请求 telemetry:ingest，不要通过增加无关能力来规避问题。
重启后身份消失： 将 MemoryStorage 替换为持久化 KVStorage 后端，并按密钥材料保护该后端。
签名令牌因重放被拒绝： 每个请求都签发新令牌。Sigiro 的认证实例共享重放保护。
已撤销代理仍能发送数据： 停止进程，保留失败响应并联系 Sigiro。在查明撤销失败原因之前，不要创建替代身份。

有关人员注册、OAuth 登录和普通访问令牌，请参阅向托管版 Sigiro 发送遥测。有关 Sigiro CLI 行为，请参阅 CLI 参考。