@cosignet/sdk

轻量、零依赖的 TypeScript 客户端，用于 Cosignet — 人在回路中 批准高风险 AI 代理操作， 并附带绑定负载的通行密钥签名。

在危险操作执行前引入人工审批：暂停操作，获取一个人的明确通行密钥批准（Face ID / Touch ID / Windows Hello / 安全密钥），仅在签署的决策 绑定到确切负载 后才继续执行——事后修改操作则签名不再匹配。Cosignet 是一个审批和证据层，而非执行器或策略引擎。可在任何支持全局 fetch + Web Crypto 的环境中运行：Node 18+、Cloudflare Workers、Deno 和浏览器。

状态： 早期访问。已发布到 npm 上，名为 @cosignet/sdk。

安装

npm install @cosignet/sdk

请求审批并等待决策

import { Cosignet } from '@cosignet/sdk';

const cosignet = new Cosignet({ apiKey: process.env.COSIGNET_API_KEY! });

const decision = await cosignet.requestApproval(
  {
    username: 'alex',
    action: '向供应商电汇',
    payload: { to: 'acct_8821', amount_usd: 4200, memo: 'INV-2025-118' },
    notify: 'telegram_or_email',
  },
  { onCreated: (c) => console.log('在此处审批:', c.url) },
);

if (decision.status === 'approved') {
  // 继续——decision.rawAssertion 是签名后的证明
} else {
  // 'rejected' | 'expired' | 'pending'（超时）
}

requestApproval 通过你自己的出站连接进行长轮询（约25秒一跳），因此它能在 CLI 工具和处于 NAT/防火墙后的锁定 VPC 中工作——无需入站 webhook、开放端口或公网 IP。

当 Cosignet 不可用时故障关闭

如果你的系统无法获得已签名的批准，那么被限制的操作绝对不能执行。不可用性绝不能降级为自动批准。将所有超时、网络错误和5xx视为“未批准”。

实现注意事项：

• 在日志和告警中区分“拒绝”和“不可用”。前者是人的决策，后者是操作条件。
• 读取时使用指数退避和抖动重试；总等待时间不超过你自己操作的截止时间，然后视为过期。
• 确保被限制的操作在你的侧是幂等的，以便在状态不明确时重试不会导致重复执行。
• 绝不要缓存批准以供重用。已签名的决策绑定到一个负载哈希；将其视为一次性使用。

详见 当 Cosignet 不可用时 获取完整的可用性和紧急预案指导。

较低级别的调用

const created = await cosignet.createConfirmation({ username, action, payload });
const status  = await cosignet.getConfirmation(created.id, { wait: 25 }); // 长轮询

使用幂等键安全重试

传递 idempotencyKey（作为 Idempotency-Key 头发送），这样重试创建时——例如网络问题中断了长轮询——使用 相同的键和相同的 action/payload 会返回 原始 确认（idempotent: true），而不会生成重复确认或重新通知审批人。使用不同的参数重用键会被拒绝并返回 422。

await cosignet.createConfirmation({
  username: 'alex',
  action: '向供应商电汇',
  payload: { to: 'acct_8821', amount_usd: 4200 },
  idempotencyKey: 'wire-INV-2025-118', // 每个逻辑操作稳定
});

将审批人发送回你的应用

传递 returnUrl 可以在决议（批准/拒绝/过期）后，在审批页面上显示一个 "返回到 <host>" 按钮——方便人类返回你的应用以重新触发已超时的操作。它必须是 https URL，且仅作为点击链接渲染（永不服务端获取）。

await cosignet.requestApproval({
  username: 'alex',
  action: '向供应商电汇',
  payload: { to: 'acct_8821', amount_usd: 4200 },
  returnUrl: 'https://app.example.com/approvals',
});

通知

notify（'none' | 'telegram' | 'email' | 'telegram_or_email'）控制向特定签署人发送的 个人主动触达 通知：

• telegram —— 向审批人关联的 Telegram 发送私信（telegram_or_email 在审批人已关联聊天时优先使用这种方式）。
• email —— 向 审批人自己的地址 发送电子邮件。优先级：你在仪表板中为审批人设置的直接电子邮件（仅用于投递），然后是已验证的成员邮箱，最后是账户联系地址（作为最后手段）。
• telegram_or_email —— 如果关联了 Telegram 则用 Telegram，否则用上述电子邮件。
• none —— 不发送个人通知。

另外，团队触达 是通过 Slack 广播到共享频道，在仪表板中按账户配置。它是附加的，配置后始终触发，与 notify 无关（因此 notify:'none' 仍会发布到 Slack）。审批人通过仪表板的“审批人”部分设置其 Telegram 和电子邮件。

关于 public: true 的揭示说明： 提交到透明度日志中的电子邮件是 账户指定的已验证电子邮件（在仪表板设置中选择，作为责任方——不是个人签署人）。直接通知邮件仅用于投递，从不用于揭示哈希。

每个频道 仅包含链接：通知携带审批 URL，绝不包含 action 或 payload。审批始终要求审批人在确认页面上使用绑定负载的通行密钥——不存在在频道内批准的方式。

验证 Webhook

verifyWebhookSignature 重新计算 原始 请求主体的十六进制 HMAC-SHA256，并与 Cosignet-Signature 头部进行恒定时间比较。传递你收到的确切字节——重新序列化 JSON 会改变签名。

import { verifyWebhookSignature } from '@cosignet/sdk';

const ok = await verifyWebhookSignature({
  body: rawBody,                              // 原始字符串，不是解析后的 JSON
  signature: req.headers['cosignet-signature'],
  secret: process.env.COSIGNET_WEBHOOK_SECRET!,
  timestamp: req.headers['cosignet-timestamp'], // 可选重放保护
  toleranceSeconds: 300,                         // 可选
});
if (!ok) return res.status(401).end();

验证

详见 docs/verification.md 获取调用方检查清单：仅在 approved 时继续，将决策与你即将执行的操作进行比对，并将拒绝/过期/超时视为硬性中止。

API

• new Cosignet({ apiKey, baseUrl?, fetch? })
• createConfirmation(input) → CreatedConfirmation
• getConfirmation(id, { wait? }) → Confirmation
• requestApproval(input, { timeoutMs?, onCreated? }) → Confirmation
• verifyWebhookSignature({ body, signature, secret, timestamp?, toleranceSeconds? }) → Promise<boolean>

公开审批揭示（选择加入，默认关闭）

默认情况下，透明度日志会隐藏负载，不暴露任何审批人身份。在 createConfirmation/requestApproval 上设置 public: true 可将单个审批选择加入 公开揭示：其原始的 action + payload 将在验证包中可读，并且账户指定的已验证电子邮件（在仪表板设置中选择——责任方，不是个人签署人）的 PBKDF2 哈希值将被提交到 Merkle 叶子中，以便任何人可以检查候选地址是否匹配。

await cosignet.requestApproval({
  username: 'alice',
  action: '发布 Q3 董事会决议',
  payload: { docId: 'res-2026-Q3' },
  public: true, // 永久且不可逆——请参见下面的注意事项
});

• 永久且不可逆 —— 一旦发布就不能取消发布。
• 需要 在你的账户中启用 公开揭示（仪表板设置）；否则请求将被拒绝。
• 诚实性：负载揭示受通行密钥约束（强）；电子邮件哈希由 Cosignet 签名的树头证明——而非由通行密钥签名——且电子邮件是低熵的，因此匹配仅证明 已知 地址，而非匿名性。提交的电子邮件命名的是账户选择的责任方，不一定是个体签署人；当未选择电子邮件时，叶子仅揭示负载。
• 不要为包含秘密或个人数据的确认启用此功能。

示例与安全文档

• examples/ —— 可复制的 cURL、Node、Python、GitLab CI、MCP/工具封装和 Worker 示例。
• security/ —— 负载绑定、WebAuthn 证明模型、威胁模型、透明度日志和负责任披露。

食谱

使用通行密钥审批限制高风险操作：

• recipes/ai-agent-gate —— 在 AI 编码代理（Claude Code）运行危险 shell 命令前暂停，直到人类共同签名。
• recipes/cli-approval —— 包装任意命令（例如 terraform destroy）。
• recipes/ci-cd —— 在批准前阻止管道（GitHub Actions / GitLab CI）。
• recipes/backend-service —— 暂停服务中的不可逆操作。

反馈与请求

• 功能请求、产品创意、SDK/API 人体工程学和路线图讨论：提交 功能问题。
• 新示例或集成请求：提交 示例请求问题。
• 安全报告：发送邮件至 [email protected]；请勿就漏洞提交公开问题。

贡献与安全

• 代码、问题和讨论托管在 GitLab：https://gitlab.com/cosignet/sdk。
• 欢迎贡献——请参见 CONTRIBUTING 和我们的 行为准则。
• 私下报告漏洞：SECURITY.md · [email protected]。

许可证

MIT © Cosignet