@debridge-finance/ 无边界验证- sdk
DeBridge 验证 SDK 无边际意图 API (英语:POST /v1.0/bundle答复.
目的
当用户向deBridge API提交捆绑请求时,响应包含预期用户会签名的交易和可签名的有效载荷(EIP-712消息,许可,索拉纳交易等).
每个字段的用户标志都是潜在的攻击矢量. 如果API被泄露(MITM,服务器错误,恶意重写),用户可以不知不觉地在耗尽资金的交易上签名.
这个SDK在签约前运行在客户端上. 它验证反应结构,并对照原始请求、协议变量和特定环境的白名单检查可标志的有效载荷.
减少威胁
- MITM攻击 与API的终点相对.
- API 一侧的臭虫 产生错误的反应.
- API 信任减少 ——客户不再需要接受API基于信仰的反应.
- 回归安全网 当测试新的API版本时.
安装
npm install @debridge-finance/borderless-validation-sdk
宣布的同伴依赖范围 :
@solana/web3.js >= 1.90.0bs58 >= 5.0.0viem >= 2.0.0zod ^3.0.0 || ^4.0.0
基本用途
import {
createValidator,
Environment,
ViolationCode,
} from "@debridge-finance/borderless-validation-sdk";
const validator = createValidator({ environment: Environment.Prod });
const url = "https://cross-chain-api.debridge.finance/v1.0/bundle";
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(request),
}).then(res => res.json());
const result = validator.validate(url, request, response);
if (!result.ok) {
if (result.violations.some(v => v.code === ViolationCode.HigherApiVersion)) {
// Special case: the API response was produced for a newer validation
// version than this SDK supports. The SDK cannot reliably validate it.
// Decide in your app whether to block, warn, update the SDK, or use
// another fallback flow.
console.error("API validation version is newer than SDK support:", result.violations);
return;
}
if (result.violations.some(v => v.code === ViolationCode.UnexpectedValidationError)) {
// Special case: this indicates an internal Validation SDK error.
// The client app must decide how to handle it: block signing, report
// telemetry, retry after SDK update, or use another fallback flow.
console.error("Validation SDK internal error:", result.violations);
return;
}
console.error("Validation failed:", result.violations);
// Do NOT let the user sign anything.
return;
}
// Safe to proceed with signing.
API 密码
createValidator(config: ValidatorConfig): Validator
type ValidatorConfig = {
environment: Environment;
};
type Validator = {
validate(url: string, request: object, response: object): ValidationResult;
};
type ValidationResult = {
ok: boolean; // true if no violations
violations: Violation[]; // all issues found
};
type Violation = {
code: ViolationCode; // machine-readable identifier
message: string; // human-readable description
path: string; // JSON path of the offending field
expected?: unknown; // the value the validator expected (concrete, comparable to `actual`)
actual?: unknown; // the value found in the response (concrete, comparable to `expected`)
details?: unknown; // extra machine-readable context (e.g. caught error object)
};
validator.validate() 从不扔 - 每一个错误条件都报告为: Violation安全呼叫任何代码路径.
UI团队整合指南
SDK是用来运行的 介于 接收 API 回复并提交用户签名。 把它接入接缝.
1. 呼叫地点
┌───────────────┐ ┌─────────┐ ┌────────────────────┐ ┌───────────────┐
│ Build request │ ──▶ │ fetch() │ ──▶ │ validator.validate │ ──▶ │ Sign / submit │
└───────────────┘ └─────────┘ └────────────────────┘ └───────────────┘
│
▼
ok ? proceed : block
- 在此之前
validate数字 : 用户尚未看到或签署任何文件. - 之后
validate数字 : 若为result.ok === false, (中文(简体) ), 不转发任何可标志的有效载荷 (意向信息,许可,交易)到钱包. API 响应无法信任 .
2. 选择环境
import { Environment } from "@debridge-finance/borderless-validation-sdk";
Environment.Prod——无煤气特性的生产.Environment.Gasless——具有无气特性的生产.Environment.Dev——开发者环境(又名Stage).
通过同样的环境 您的应用程序已经配置 —— 不要让它成为用户选择 .
3. 传递您拨打的确切的 URL
const url = "https://cross-chain-api.debridge.finance/v1.0/bundle";
const response = await fetch(url, { ... });
const result = validator.validate(url, request, response);
这个 url 参数用于API兼容性和未来端点检查。 传出你交给的相同字符串 fetch;在发布中明确启用之前,不要依赖URL验证.
4. 处理侵权行为
打开 result.ok === false数字 :
- 堵住签名流. 不要显示钱包弹出或将任何待决 tx 写入状态 .
- 完整记录
violations数组 到错误报告系统(Sentry / Datadog /等)。 包含code, (中文(简体) ),path, (中文(简体) ),expected, (中文(简体) ),actual, (中文(简体) ),details。 。 。 . - 向用户显示通用错误 . 不泄露原始内容
Violation数据输入UI——消息是给开发者的,而不是最终用户的. 单"引文无效,请重试"即可. - 不自动重试 . 如果API被泄露,重复会更糟糕. 让用户手动触发重试 .
5. 浏览器兼容性
SDK同时作为CJS和ESM发布,只使用与浏览器兼容的API(无) fs, (中文(简体) ), crypto, (中文(简体) ), Buffer, (中文(简体) ), process) (中文(简体) ).
摇树:无害环境管理建筑保留了被命名的出口。 只导入 createValidator 将不会拉入未使用的验证器 .
6. 套装大小
大约1 MB已解开(其中很多是源地图——投放生产). 最重的对等级是 @solana/web3.js如果你的应用只处理 EVM 交易, 你的捆绑者树摇应该消除它的大部分.
7. 类型脚本
全面申报船舶 dist/types/。 。 。 . ValidatorConfig, (中文(简体) ), ValidationResult, (中文(简体) ), Violation,以及 ViolationCode 全部出口——直接使用,不要重新申报.
8. 不做什麽
- ❌ 不要跳过验证 因为"API是我们自己的。" 妥协探测是整点.
- ❌ 不要变异
request或者说responseaPI呼叫和validate()——验证人需要用户收到的准确的有效载荷. - ❌ 不要解释
violations[].message方案 ——电文措辞在版本之间可能会有变化. 分会code换句话说. - ❌ 如果
environment变化. 通过createValidator每个环境.
发展
见 CLAUDE.md 项目惯例、审定规则和安全准则.
见 src/README.md 用于概述源代码结构和验证流程.
- 单位测试 :
npm test - Zod 3 单元相容性测试 :
npm run test:zod3 - Zod 3 E2E相容性测试 :
npm run test:e2e:zod3 - Zod 3 E2E相容性测试( CI 模式):
npm run test:e2e:zod3:ci - Zod 3/4 完全兼容性检查 :
npm run test:zod-compat - 单位测试覆盖率 :
npm run coverage - E2E 测试( 默认使用阶段 API; 覆盖到
API_BASE_URL:npm run test:e2e - 使用校验大小写记录的 E2E 测试 :
npm run test:e2e:record-validation-cases - E2E测试( CI 模式, 串行加较长的超时):
npm run test:e2e:ci - E2E覆盖率:
npm run coverage:e2e - 下载匹配的 Java 验证器 CLI :
npm run download:java-validator-cli - 比较类型脚本和 Java E2E 验证结果:
npm run test:e2e:java-parity - 全面建设 :
npm run build - 仅建立无害环境管理:
npm run build:esm - 只构建 CJS :
npm run build:cjs - 仅构建类型声明 :
npm run build:types - 清洁构建输出 :
npm run clean
释放
Nx公司从常规承诺的 PR 标题中剪辑了释放:
- 将公关定为一项常规承诺:
fix: ...(标出),feat: ...(未成年人),feat!: ...(主要内容). 其他类型(ci, (中文(简体) ),chore, (中文(简体) ),docs, (中文(简体) ),test, (中文(简体) ),refactor,不触发释放. - 挤出公关
master。 。 。 . - 行动- 创建发行 • 运行工作流程
master; 勾选dry-run预览下一个版本,并 先换换日志 经批准后release环境 工作流程起伏package.json, (中文(简体) ), 更新CHANGELOG.md,推动v<version>标签,创建 GitHub 发布 并发布软件包到 npm(受托出版,无 npm 令牌).
发布合并的更改而无需修改 fix:编号 :feat: 标题,设置 version (单位:千美元)patch, (中文(简体) ), minor, (中文(简体) ), major 或者说 1.2.3) (中文(简体) ).
如果 npm 发布步骤失败, 则重新运行 Create Release with publish_only。 。 。 .
Java 等同 E2E 验证
此检查通过 TypeScript SDK 及其运行存储器的 E2E 验证大小写 Java端口,然后验证两种执行产生等效的验证结果.
1. 核对
从根使用 TypeScript SDK 版本 package.json数字 :
npm run test:e2e:java-parity
要选择另一个 TypeScript SDK 版本的 Java 版本, 请通过该版本 明确:
npm run test:e2e:java-parity [-- <typescript-sdk-version>]
参数只选择 Java 释放映射 。 它不检查或安装该版本的TypeScript SDK;TypeScript结果总是来自当前工作树.
命令需要Java和访问 GitHub 发布. 对于认证的 GitHub 访问, 它使用
GITHUB_TOKEN, (中文(简体) ), GH_TOKEN,或由 gh auth token顺序.
2. 执行流程和生成的文件
命令执行以下步骤:
-
从命令行参数或根确定请求的 TypeScript SDK 版本
package.json。 。 。 . -
查找最新发布的 Java 发布注释包含
TypeScript SDK tag: v<version>并期望释放中包含一个cli-*.jar资产. -
下载和验证Java CLI, 除非同一经核实的发布已经在下面缓存 :
.cache/java-validation-sdk/releases/<typescript-version>/<java-release-tag>/此目录包含 CLI JAR 及其
metadata.json缓存元数据 . -
检查Java CLI是否支持预期的CLI合同版本.
-
运行普通的 TypeScript E2E 套件,并启用校验大小写记录。 每个杰斯特工人 将其验证器输入和 TypeScript 结果写入单独的 JSONL 文件 :
.cache/recorded-validation-cases/<date>__<unix-timestamp>/ └── recorded-cases__pid-<pid>.jsonl每个JSONL行包含测试身份,验证器 URL,请求,响应,验证器配置, 和类型脚本
ValidationResult一个验证人引用. -
以相同的顺序向 Java CLI 守护进程发送所有记录的输入并读取一个 Java
ValidationResult每个输入. -
比较相应的TypeScript和Java结果. 最多10个不匹配被打印到 操纵台 完整的不匹配报告写到:
.cache/java-validation-sdk/parity-check-runs/<date>__<unix-timestamp>/mismatches.json
临时 .cache/recorded-validation-cases/latest-run.json 文件连接 E2E 记录器
当命令完成时,将删除。 成功对等检查也会删除
其记录的验证案例。 如果 E2E 执行或对等比较失败,则记录的案例是
留作调查之用. 仅在不匹配需要时创建对等检查运行目录
报告.
3. 比较规则
生下来的 ValidationResult 不直接比较对象。 每个结果都缩小为这个形状:
{
ok: boolean;
violations: Array<{
code: string;
path: string;
expected?: unknown;
actual?: unknown;
}>;
}
比较内容包括:
- 顶级
ok数值; - 违反次数,包括重复违反次数;
- 每一个违反者
code财务报告和审定财务报表path· ; - 存在值和 JSON 值
expected财务报告和审定财务报表actual· ; - 内嵌值类型、字符串外壳和阵列元素顺序
expected财务报告和审定财务报表actual。 。 。 .
比较前:
- 违反情况加以分类,因此两个SDK报告违反情况的顺序并不重要;
- 对象密钥按递归排序,因此对象属性顺序无关紧要; 2;
- 未排序数组,因此其元素顺序仍然重要.
比较故意忽略:
- 违反
message* 文本; - 违反
details· ; - 任何其他违规领域;
- 任何其他顶级结果字段.
正常化后,两个结果对象进行序列化和精确比较. 任何剩余 差异作为对等不匹配报告.
许可证
BUSL-1.1号线