Corsair 接入 Anonyflow：用 API Key 认证实现敏感数据匿名化/去匿名化的完整指南

Corsair 接入 Anonyflow用 API Key 认证实现敏感数据匿名化/去匿名化的完整指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair导读本文围绕corsair-dev/anonyflow插件展开讲解如何在 Corsair 应用中接入 Anonyflow一个专注于隐私保护的数据 Tokenization 服务把姓名、邮箱、身份证号等敏感信息在交给第三方 LLM 或数据分析流程之前进行匿名化Anonymize并在需要时精确还原Deanonymize。读完本文你将掌握插件的安装与租户级 API Key 认证配置、5 个 typed 端点的输入输出与底层请求实现、数据包级字段加密anonymizePacket/deanonymizePacket、以及 429/401 等错误的自动重试与降级处理并能在自己的 Corsair 服务中直接落地这些能力。一、插件概览一个为隐私保护而生的 Tokenization 插件Anonyflow 的定位是隐私优先的数据 Tokenization 服务用于保护敏感的客户信息。在 plugin-docs.yaml 中其官方描述为 Privacy-focused data tokenization service for protecting sensitive customer information.。在 Corsair 生态中它被封装为corsair-dev/anonyflow插件包通过 index.ts 暴露一个anonyflow()工厂函数向 Corsair 注册 5 个 typed API 操作。核心价值在于一份客户端所有请求统一走 Corsair 的corsair/http请求层无需自行拼装 HTTP 调用类型安全输入/输出均由 Zod Schema 定义并校验编译期即可发现参数错误多租户开箱即用认证基于 API KeyCorsair 会在租户首次使用时提示录入凭据并以租户维度隔离调用。该插件没有 WebhookREADME 中明确 No webhooks源码中anonyflowWebhooksNested {}为空对象也没有数据库实体同步AnonyflowSchema.entities为空见 schema/index.ts是一个纯 API 调用型插件。二、安装与快速接入2.1 安装插件使用 pnpm 安装README 官方推荐方式pnpm add corsair-dev/anonyflow从 package.json 可以看到该包声明了两个 peerDependenciescorsair0.1.0Corsair 核心运行时zod^4.1.13用于端点输入/输出 Schema 校验。因此实际使用前项目中还需要同时安装corsair与zod。2.2 在 Corsair 中注册插件创建/修改你的corsair.ts配置文件将插件加入plugins数组import Database from better-sqlite3; import { createCorsair } from corsair; import { anonyflow } from corsair-dev/anonyflow; export const corsair createCorsair({ plugins: [ anonyflow(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });要点说明kekKey Encryption Key与 Hub 的projectApiKey、signingSecret属于 Corsair 全局配置可参考 docs/quick-start.mdx 获取用于加密租户凭据与 Hub 通信多租户是默认行为之后用corsair.withTenant(id)指定调用租户租户之间凭据与数据相互隔离详见 docs/concepts/multi-tenancy.mdx。2.3 连接租户Connect 流程Anonyflow 使用 API Key 认证没有 OAuth 流程。Corsair 会在租户第一次发起调用时提示录入 API KeyREADME 原话Corsair prompts your tenant for credentials on first use。要让租户完成凭据录入需要生成一个 Connect 链接并引导用户浏览器访问const { connectUrl } await corsair.manage.connect.createLink({ plugin: anonyflow, tenantId: acme, }); // 将用户浏览器重定向到 connectUrlHub 会托管该页面并把凭据结果回传给应用完整流程见 docs/management/connect.mdx。三、5 个核心端点操作一览与调用方式README 中给出了完整的端点清单每个端点都带有 Operation ID 与 Risk 标记。源码中这些端点统一挂在core命名空间下见 index.ts 的anonyflowEndpointsNested定义对应tenant.anonyflow.api.core.*的调用路径。OperationOperation IDRisk描述core.anonymizeanonyflow.api.core.anonymizewrite匿名化文本中的敏感数据core.anonymizePacketanonyflow.api.core.anonymizePacketwrite基于 keys 加密数据包内的字段值core.deanonymizeanonyflow.api.core.deanonymizewrite从匿名化映射还原原始文本core.deanonymizePacketanonyflow.api.core.deanonymizePacketwrite基于 keys 解密数据包内的字段值core.testConnectionanonyflow.api.core.testConnectionread校验 API Key 与连通性Risk 标记在权限体系中很关键write意味着该操作会对外部系统产生数据变更此处为写入/变更匿名化映射testConnection属于read级只读探测。schema.test.ts中的测试专门断言了这些 risk 级别确保deanonymize/deanonymizePacket被标记为write、testConnection为read。调用示例单租户视角const tenant corsair.withTenant(acme); await tenant.anonyflow.api.core.testConnection({});下面按端点逐一展开输入、输出与底层 HTTP 行为。3.1core.anonymize匿名化一段文本描述Anonymize sensitive data in text匿名化文本中的敏感数据风险write。输入参数类型必填说明textstring是待匿名化的原始文本输出参数类型必填说明anonymizedTextstring是匿名化后的密文文本底层实现见 endpoints/index.ts 的anonymize函数请求发往POST https://api.anonyflow.com/anony-value请求体为{ data: text }响应经extractValue提取后包装为{ anonymizedText }返回。extractValue的提取规则是优先取响应字符串若响应为对象则先检查status false时抛出AnonyflowAPIError(Anonyflow rejected the request)否则取value字段字符串或字符串数组首元素。测试用例schema.test.ts验证了My name is Athish会被转换成AQICAHiWIc...形式的 Token 密文。const result await tenant.anonyflow.api.core.anonymize({ text: My name is Athish, }); // result.anonymizedText AQICAHiWIc...3.2core.deanonymize还原匿名化文本描述Restore original text from anonymized mapping从匿名化映射还原原始文本风险write。输入参数类型必填说明anonymizedTextstring是待解码的匿名化文本输出参数类型必填说明originalTextstring是还原出的原始文本底层实现请求发往POST https://api.anonyflow.com/deanony-value请求体为{ data: anonymizedText }。测试中AQICAHiWIc...可还原为My name is Athish与anonymize构成完整闭环。3.3core.anonymizePacket按 keys 加密数据包字段描述Encrypt field values within a data packet based on keys基于 keys 加密数据包内的字段值风险write。输入参数类型必填说明dataobject是待匿名化的数据包Recordstring, unknownkeysstring[]是数据包中需要匿名化的字段 key 列表输出参数类型必填说明statustrue是固定为true表示成功valueobject是处理后的数据包Recordstring, unknown底层实现请求发往POST https://api.anonyflow.com/anony-packet请求体为{ data, keys }。响应经requirePacketSuccess校验若status false立即抛出AnonyflowAPIError(Anonyflow rejected the request)。测试中的典型用法await tenant.anonyflow.api.core.anonymizePacket({ data: { firstName: john }, keys: [firstName], }); // { status: true, value: { firstName: AQICAHiWIc... } }只处理keys中列出的字段其余字段原样保留——这非常适合对用户对象中个别敏感字段如姓名、邮箱做定向脱敏而不用整体替换。3.4core.deanonymizePacket按 keys 解密数据包字段描述Decrypt field values within a data packet based on keys基于 keys 解密数据包内的字段值风险write。输入/输出与anonymizePacket完全对称输入datakeys输出{ status: true, value }。请求发往POST https://api.anonyflow.com/deanony-packet请求体为{ data, keys }。await tenant.anonyflow.api.core.deanonymizePacket({ data: { firstName: AQICAHiWIc... }, keys: [firstName], }); // { status: true, value: { firstName: john } }3.5core.testConnection连通性自检描述Verify API key and connectivity校验 API Key 与连通性风险read。输入空对象{}输出{ status: true }。底层实现与其他端点不同这是唯一的 GET 请求发往GET https://api.anonyflow.com/test无请求体。若响应status false则抛出AnonyflowAPIError(Anonyflow rejected the request)。适合在租户完成 Connect 后做一次凭据有效性验证。3.6 所有端点的 Zod Schema输入/输出类型全部由 Zod 定义见 endpoints/types.ts运行时在 endpoints/index.ts 中通过AnonyflowEndpointInputSchemas.op.parse(input)与AnonyflowEndpointOutputSchemas.op.parse(...)强制执行。这意味着参数缺失、类型错误会在进入网络请求之前被拦截返回结构不符合 Schema 时同样会抛错避免脏数据向上蔓延。四、API Key 认证与密钥解析源码级原理4.1 认证方式README 明确Auth: API key无 OAuth。在 index.ts 中defaultAuthType api_key插件默认使用 API Key 认证anonyflowAuthConfig将api_key的账户字段绑定为[tenant_external_id]即凭据以租户外部 ID 为维度存储与隔离插件构造函数支持通过anonyflow({ key })直接注入一个静态 Key适合单租户/服务端场景也支持不传key走租户凭据存储。4.2 keyBuilder 的解析优先级keyBuilder是决定这次请求用哪个 Key的核心逻辑优先级如下若调用来源是endpoint且插件配置了options.key直接使用静态 Key否则若认证类型为api_key调用ctx.keys.get_api_key()读取该租户已存储的 API Key两者都拿不到时抛出AuthMissingError(anonyflow, api_key)。schema.test.ts中的两个用例验证了这一行为未配置 Key 时调用端点会抛api key is requiredkeyBuilder在无 Key 时抛AuthMissingError实例。4.3 请求头x-api-key 而非 Bearer见 client.ts所有请求统一由makeAnonyflowRequest发出Base URLhttps://api.anonyflow.com请求头Content-Type: application/jsonx-api-key: apiKey凭证策略WITH_CREDENTIALS: false、CREDENTIALS: omit、TOKEN: undefined明确不携带 Bearer Token媒体类型application/json; charsetutf-8。makeAnonyflowRequest会在apiKey为空!apiKey.trim()时直接抛出AnonyflowAPIError(Anonyflow API key is required)不会发起网络请求同时将底层corsair/http的ApiError原样上抛其他 Error 包装为AnonyflowAPIError。测试专门断言了发送 x-api-key 且不携带 Bearer Token这一行为TOKEN: undefined这是与其他 OAuth 类插件最显著的区别。五、错误处理与重试策略error-handlers.ts 为插件注册了三级错误处理器并在 index.ts 中与用户自定义errorHandlers合并用户配置优先级更高。处理器匹配条件处理策略RATE_LIMIT_ERRORApiError且 HTTPstatus 429最多重试 5 次并透传retryAfter响应头headersRetryAfterMs作为退避参考AUTH_ERRORApiError且status 401或错误消息包含unauthorized/invalid_auth不重试maxRetries: 0DEFAULT兜底匹配所有错误不重试maxRetries: 0关键设计点限流重试429 是 Anonyflow 服务端限流信号重试 5 次是插件内置的默认容错若响应带Retry-After头会以毫秒为单位通过headersRetryAfterMs告知重试调度器。error-handlers.test.ts验证了retryAfter存在/缺失两种场景下{ maxRetries: 5, headersRetryAfterMs: 1500 | undefined }的输出认证失败不重试401/unauthorized/invalid_auth表示凭据本身有问题重试无意义立即失败以便应用层提示租户更新 API Key匹配严格性RATE_LIMIT_ERROR.match要求必须是ApiError实例且状态码为 429普通 Error 即使消息文本里含 429 也不会误匹配测试中有专门用例。六、插件构建与发布形态从 tsup.config.ts 与 package.json 可以看出插件的工程化形态通过tsup打包为ESMformat: [esm]、target: esnext、platform: node产物输出到dist/corsair与zod声明为external不会被打进产物由宿主应用提供peerDependencies包入口index.ts导出anonyflow()工厂、AnonyflowEndpointInputs/AnonyflowEndpointOutputs类型等内部质量保障jestts-jest跑 schema.test.ts端点行为、权限、请求头与 error-handlers.test.ts重试策略npm run typecheck做类型检查。从源码结构看该插件遵循 Corsair 插件体系的标准契约id: anonyflow、authConfig、schema、endpoints、webhooks、endpointMeta、endpointSchemas、errorHandlers、keyBuilder九个字段齐备可被 Corsair 核心与 MCP 适配层见 docs/mcp-adapters/mcp-adapters.mdx统一识别这意味着插件的操作同样可以暴露为 MCP tools 供 Agent 调用。七、典型落地场景场景一LLM 调用前的数据脱敏将包含用户隐私的文本先anonymize再送入外部 LLM得到结果后按需deanonymize还原避免明文敏感数据离开自己的数据边界const tenant corsair.withTenant(acme); const { anonymizedText } await tenant.anonyflow.api.core.anonymize({ text: User Athish lives at 123 Main St, contact athishexample.com, }); // 将 anonymizedText 交给 LLM 处理 const { originalText } await tenant.anonyflow.api.core.deanonymize({ anonymizedText, });场景二结构化数据的定向字段加密对用户对象做定点脱敏只处理keys列出的字段const { value } await tenant.anonyflow.api.core.anonymizePacket({ data: { id: u_1001, firstName: john, email: johnexample.com, plan: pro }, keys: [firstName, email], }); // value { id: u_1001, firstName: AQICAHiWIc..., email: AQICAHiWIc..., plan: pro }场景三租户接入后的连通性验证try { await tenant.anonyflow.api.core.testConnection({}); console.log(Anonyflow API key is valid); } catch { // 触发 connectUrl 重新引导租户录入凭据 }八、小结corsair-dev/anonyflow是一个典型的纯 API 调用 API Key 认证 无 Webhook 无数据库实体的 Corsair 插件它把 Anonyflow 的 Tokenization 能力以 5 个 typed 端点anonymize、deanonymize、anonymizePacket、deanonymizePacket、testConnection的形式无缝接入 Corsair 的多租户运行时。无论是文本级的anonymize/deanonymize闭环还是数据包级的anonymizePacket/deanonymizePacket定向字段加密都能在租户凭据隔离、Zod 运行时校验与 429 自动重试等机制的保障下稳定工作。对于需要先脱敏、后处理、再还原的数据隐私流水线这是一个开箱即用的接入方案。进一步阅读端点类型细节见 docs/plugins/anonyflow/api.mdx接入步骤见 docs/plugins/anonyflow/overview.mdx插件实现源码index.ts、endpoints/index.ts、endpoints/types.ts、client.ts、error-handlers.ts行为验证测试schema.test.ts、error-handlers.test.ts认证与多租户概念docs/concepts/api-key.mdx、docs/concepts/multi-tenancy.mdx、docs/management/connect.mdx。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考