SuperAPI AI 工具集

persona-webhooks-events

安全与审计

查看项目

更新于 10-16 06:20

技能介绍

用途:在实现 Persona Webhook 消费端时,对投递事件完成真实性校验、持久接收、幂等去重、事件时间排序与资源核对。Webhook 在签名通过前都视为不可信投递,且可能出现重复或乱序。

主要能力与用法:

  1. 解析前先捕获:读取精确原始字节与 Persona-Signature 头,先执行大小、方法、内容类型与时间戳策略检查,再做业务处理。
  2. 解析签名候选项:提取 t 及每个 v1 值,拒绝残缺或格式错误项,仅保留脱敏诊断元数据。
  3. 计算并比较:以 webhook secret 对 t + '.' + rawBody 计算 HMAC-SHA256,对所有 v1 候选项做常数时间比较以支持密钥轮换。
  4. 确认持久接收:校验通过后,以唯一约束插入事件 ID 与原始体哈希,随后快速确认;重复插入视为成功的无操作。
  5. 按提供方时间处理:按事件类型路由并容忍未知类型,使用 data.attributes.created-at(而非到达顺序)约束状态迁移。
  6. 有后果操作前先核对:审批、拒绝、付款或权限变更前,读取当前 Persona 资源并应用带版本的领域策略。

认证:Webhook 认证使用端点签名密钥与 Persona-Signature HMAC 协议,不使用 REST bearer key;资源核对另行使用环境 bearer key。

输出:签名校验契约与测试向量、持久接收/去重/排序/路由设计、核对与业务迁移回执;返回环境、资源与事件标识、API 版本、模板上下文、源契约指纹、证据、未决风险、回滚状态与最终决策,且不得暴露 bearer key、webhook secret、inquiry 会话令牌、原始身份文档或非必要 PII。

错误处理:签名不匹配时返回配置的失败响应,记录脱敏哈希与时间戳且不入业务队列;重复事件直接确认已持久化 ID;旧事件后到时存储审计并比较提供方创建时间与当前资源状态以防回退;未知事件类型安全保留观察,不崩溃。

限制:需 HTTPS 端点、保留精确原始字节、带轮换元数据的 secret、持久唯一事件存储与核对 worker。工具使用上仅用 Read/Grep 检查配置与文档,未经操作员明确批准不得变更生产资源。校验须对照第一方证据、固定 API 版本、脱敏契约夹具、预期失败路径与回滚路径;请求成功不等于身份决策成功。