该技能用于在 Nango 中新增或修改受审计的端点,或判断某端点不应被审计。审计的源头是 packages/types/lib/audit-trail/event.ts 中的 AuditEventTable,它把资源映射到动作及其可携带的元数据;事件联合类型、元数据查找、各资源动作列表和 webapp 过滤器均由它派生。先在此添加动作,再让编译器提示还需改动哪些位置。审计仅限控制面(配置、状态与认证),运行时流量(记录、代理、同步执行)属数据面,不纳入审计。
工作流程:在 AuditEventTable 的资源下添加 <action>: <MetadataShape>,无元数据则写 <action>: never;元数据结构定义在 packages/types/lib/audit-trail/metadata.ts,按内容而非单个动作命名。每个面向客户的端点须声明类型:Audit: AuditPolicy<'<resource>', '<action>', 'account' | 'environment'>,或 Audit: { kind: 'no-audit'; reason: '<why>' }。spec 放在 packages/server/lib/middleware/audit/<resource>.middleware.ts,使用 auditable 定义 policy、target、metadata,并注意中间件挂载顺序。测试放在 <resource>.middleware.unit.test.ts,webapp 需在 packages/webapp/src/pages/Audit/constants.ts 的 actionsByResource 中登记动作。
注意事项:解析器在 zod 之前运行,此时 req.body/params/query 为原始值,应使用 input.ts 中的守卫;target 和 metadata 在 next() 之前解析,处理器生成的值需用 targetFromResponse/metadataFromResponse;403 表示未运行处理器,需确保审计信息可从请求中获取;scope: 'account' 会置空环境。评审清单包括运行 npm run ts-build、断言通用字段、测试破坏检查、确认中间件位于 withScope 之前,并检查拒绝与失败路径。