@blockcerts/cert-verifier-js

中文文档

6.39.1发布于 2026/10/28MITTypeScriptESM + CJS近 30 天下载 1.1万

用于校验 Blockcert 的 Javascript 库

文档目录24 节

安装
导入
从第4版
在节点运行
实例
未解析的块证书的发现版本
解析块证书
校验块证书
Certificate
new Certificate(certificateDefinition, options)
verify(stepCallback)
常数
i18n (英语)
探险家APIS
撤销
状态列表
HTTP缓存服务合同
文件系统缓存文件合同
违反合同行为
贡献
运行测试
手工测试
构建
核查进程

@ blockcerts/ cert- 验证器- js

用于解析和校验的图书馆块牌证书.

ImportANT 注:截至本库第5版,v1区块符不再支持. 如有需要,请使用https://www.npmjs.com/package/@blockcerts/cert-verifer-js-v1-legacy.

使用量

安装

$ npm i @blockcerts/cert-verifier-js

导入

从第4版

证书的证明现在变成了同步的. 当你导入 Certificate 构造器和即时电源相同(见下文),消费者现在需要调用即时电源功能 init。。。 .

示例

import { Certificate } from '@blockcerts/cert-verifier-js';
let certificate = new Certificate(certificateDefinition);
await certificate.init();

常见

默认曝光 :

const { Certificate } = require('@blockcerts/cert-verifier-js');
var certificate = new Certificate(certificateDefinition);
await certificate.init();

在节点运行

const { Certificate } = require('@blockcerts/cert-verifier-js/dist/verifier-node.js');
var certificate = new Certificate(certificateDefinition);
await certificate.init();

ES模块

import { Certificate } from '@blockcerts/cert-verifier-js';
let certificate = new Certificate(certificateDefinition);
await certificate.init();

脚本标签( ife)

检查这里的示例

<script src='node_modules/@blockcerts/cert-verifier-js/dist/verifier-iife.js'></script>
<script>
  var certificate = new Verifier.Certificate(certificateDefinition);
  await certificate.init();
</script>

实例

您可以在测试文件夹。。。 .

在那个手动测试文件夹您将在节点和浏览器环境中找到执行实例.

未解析的块证书的发现版本

import { retrieveBlockcertsVersion } from '@blockcerts/cert-verifier-js';
const version = retrieveBlockcertsVersion(blockcertDocument['@context']);
// return 1, 2 or 3

解析块证书

var fs = require('fs');

fs.readFile('./certificate.json', 'utf8', async function (err, data) {
  if (err) {
    console.log(err);
  }

  let certificate = new Certificate(data);
  await certificate.init();
  console.log(cert.name);
});

校验块证书

var fs = require('fs');

fs.readFile('./certificate.json', 'utf8', async function (err, data) {
  if (err) {
    console.log(err);
  }

  let certificate = new Certificate(data);
  await certificate.init();
  const verificationResult = await certificate.verify(({code, label, status, errorMessage}) => {
    console.log('Code:', code, label, ' - Status:', status);
    if (errorMessage) {
      console.log(`The step ${code} fails with the error: ${errorMessage}`);
    }
  });

  if (verificationResult.status === 'failure') {
    console.log(`The certificate is not valid. Error: ${verificationResult.errorMessage}`);
  }
});

API 密码

`Certificate`

`new Certificate(certificateDefinition, options)`

const certificate = new Certificate(certificateDefinition);

构造器自动剖析证书。打电话 certificate.init() 用于处理所需的初始设置.

参数

certificateDefinition (单位:千美元)String|Object: 证书定义. 可以是字符串也可以是JSON对象.
options: (中文(简体) )Object: 选项对象. 使用的属性如下:
- 语言 : (String: 用于设置核查员所使用语言的语言代码. 默认 : en-US如果设置为 auto 它会使用用户的浏览器语言( 如果有的话), 或者默认为 en-US见专栏更多信息.
- 探险家: ([Object]:自v4.1.0起,可为交易探索者提供自定义服务API. 这使得客户能够选择一个可能更可靠的/私人的探险家来取回捆绑在块链上的交易. 见专栏更多信息.
- (原始内容存档于2013-10-12). ResolverUrl : (AString: 通过此选项来指定您自己所做的解析器 URL 。默认情况下,此库使用不推荐用于生产的DIF通用解析器.
- 状态列表 CacheUrl : (String: 缓存服务的HTTP URL,或本地 JSON 缓存文件的文件系统路径(仅节点/服务器侧),用于存储/检索位点状态表/状态表2021 状态列表在核查之间。见专栏更多信息.

回返

证书实例具有以下属性:

certificateImage数字 : String证书图像的原始数据
certificateJson数字 : Object证书 JSON 对象
description数字 : String证书说明
expires数字 : String|null终止日期
id数字 : String证书的标识
isFormatValid数字 : Boolean。指出证书是否具有有效格式
issuedOn数字 : String8. 印发日期(ISO-8601)
issuer数字 : Object证书签发者
locale数字 : String。验证人使用的语言代码
metadataJson数字 : Object|null 证书元数据对象
name数字 : String证书名称
recipientFullName数字 : String。收件人的全名
recordLink数字 : String。链接到证书记录
revocationKey数字 : String|null。撤销键(如有)
sealImage数字 : String. 海豹图像原始数据;
signature数字 : String|null证书签名
signatureImage数字 : SignatureImage[]证书阵列签名行。。。 .
signers: 签名者[. 显示一些与 Blockcerts 签名有关的信息的对象。包含:
- chain? IBlockchainObject。。。 .
- issuerName? string链式签名于
- issuerProfileDomain? string。。。 .
- issuerProfileUrl? string。。。 .
- issuerPublicKey数字 : string。当前的签名者公用钥匙.
- rawTransactionLink? string与原始交易数据的链接(JSON)
- signatureSuiteType数字 : string。。。 .
- signingDate数字 : string。。。 .
- transactionId? string。。。 .
- transactionLink? string。浏览器链接到交易细节
subtitle数字 : String|null证书的子标题
version数字 : CertificateVersion。。。 . 证书的版本

`verify(stepCallback)`

这将运行证书的验证。该函数为同步.

const certificateVerification = await certificate.verify(({code, label, status, errorMessage}) => {
    console.log('Sub step update:', code, label, status);
}));
console.log(`Verification was a ${certificateVerification.status}:`, certificateVerification.message);

参数

({code, label, status, errorMessage}) => {} (单位:千美元)Function:每当子步状态改变时,就调用回调函数. 回调参数有4个属性:
- code: 子步骤代码
- label: 子步骤的可读标签
- status: 子步状态( u)success, (中文(简体) ), failure, (中文(简体) ), starting(中文(简体) )
- errorMessage: 错误消息( 可选)

回返

最后核查情况:

{ code, status, message }

code: 最后一个步骤的代码(final(中文(简体) )
status: 最终核查状况success, (中文(简体) ), failure(中文(简体) )
message 字符串QQ对象:状态消息. 它已经国际化,如果失败,它会返回失败步骤的错误信息。当物体时,其形状如下:
- label: 最后一步的主要标签
- description: 关于印发的进一步详情
- linkText: 提供了交易链接文本的翻译

说明: 展览: verificationSteps 根据证书的性质生成。全部步骤阵列在核查之前提供,以便使消费者更加灵活。例如,您可能想要为动画预交验证步骤,或者对步骤和/或子步骤进行计数.

VerificationStep 形状如下:

{
    code: 'formatValidation',
    label: 'Format validation',
    labelPending: 'Validating format',
    subSteps: [
      {
        code: 'getTransactionId',
        label: 'Get transaction ID',
        labelPending: 'Getting transaction ID',
        parentStep: 'formatValidation'
      },
      ...
    ]
}

这里可以检查返回对象的形状 : https://github.com/blockchain-certificates/cert-virifer-js/blob/master/src/data/i18n.json#L41 (中文(简体) )

常数

一些常数正在被曝光:

import { BLOCKCHAINS, STEPS, CERTIFICATE_VERSIONS, VERIFICATION_STATUSES } from '@blockcerts/cert-verifier-js';

BLOCKCHAINS: 由库支持的所有块链的描述对象
STEPS: 所有核查步骤的描述对象(顶级)
CERTIFICATE_VERSIONS: 所有证书版本的列表
VERIFICATION_STATUSES

i18n (英语)

曝光函数 getSupportedLanguages() 返回库支持的一系列语言代码.

import { getSupportedLanguages } from '@blockcerts/cert-verifier-js';
getSupportedLanguages(); // ['en-US', 'es-ES', 'mt', ...]

您可以使用密码 locale 选项.

请注意,在我们努力增加新语言的同时,欢迎任何新译名通过forking & PR.

探险家APIS

从v4.1.0起,这个库的客户能够提供一组区块链探索器,用于检索用于在区块链上存储区块的交易数据,通过 explorerAPIs 选项键.

注:由于本库增加了Typescript,一些类型现在已暴露给消费者.

财产被设定为 options 参数 Certificate 下述构造器:

const certificate = new Certificate(definition, options);

物体的预期形状如下:

  key?: string;
  keyPropertyName?: string;
  serviceName?: TRANSACTION_APIS; 
  serviceURL: string | ExplorerURLs;
  priority: 0 | 1 | -1; // 0 means the custom API will be ran before the public APIs listed, 1 after, -1 is reserved for default explorers
  parsingFunction: TExplorerParsingFunction;

关于每个项目的更多信息:

serviceName:当消费者想覆盖所提供默认的探索者API的一些信息(例如提供他们自己的服务API密钥)时,他们应该将API服务的名称与这个属性相匹配.
key: 探索者服务 API 密钥值.
keyPropertyName:要持有密钥值的预期参数名。取决于每项服务。 (i:以太斯干:"apiKey", Blockcrypher:"token"等). 密钥通过时需要 .
serviceURL: 当设置为 string 将假定为 mainnet 断层链. 当设定为对象时,客户可以为该对象提供url服务 mainnet 联合国 testnet 区块链的版本. 对象随后被形状为:

{
  main: 'url',
  test: 'url'
}

priority: 此选项允许客户在库提供的默认浏览器之前/之后决定是否希望看到其自定义探索器被执行(关于默认探索器列表,请参见常数/api文件). 如果选项设定为 0,自定义的探险者将首先被调用。如果设置为 1 他们将被召归于不义者. -1 为默认探索者保留值.
parsingFunction (response: Object, chain?: SupportedChains, key?: string, keyPropertyName?: string): 需要此函数来解析从 API 返回到 TransactionData 用于库的形状. 参数 :
- response: 被调用到的探索者服务返回的响应对象.
- chain: (可选)要查看的块链。主要用于识别是测试链还是主链.
- key: (可选) 当需要进一步调用相同的API时,API密钥会再次被注入解析函数以方便.
- keyPropertyName: (可选) 当需要进一步调用相同的API时,API密钥再次被注入解析函数以供参考. 预期输出形状如下:

interface TransactionData {
  remoteHash: string;
  issuingAddress: string;
  time: string | Date;
  revokedAddresses: string[];
}

消费者需要为自己使用的每一项服务写出自己的功能.

撤销

这个 assertionId 现附于 revocationList URL 请求作为查询参数,允许过滤 revokedAssertions 提供者: {revocationList}?assertionId={assertionIdValue} 更多细节在这里这张票。。。 .

状态列表

使用位点状态表/状态表2021中,库获取状态列表 credentialStatus.statusListCredential。可以通过提供 statusListCredentialCacheUrl 选项,如下:

// HTTP caching service
const certificate = new Certificate(definition, { statusListCredentialCacheUrl: 'https://my-caching-service.example.com/status-list-cache' });

// filesystem cache file (Node/server-side only)
const certificate = new Certificate(definition, { statusListCredentialCacheUrl: './cache/status-list-cache.json' });

价值 statusListCredentialCacheUrl 确定使用哪种缓存策略 :

如果它是 HTTP( S) URL (从 http:// 或者说 https://),图书馆使用 HTTP 缓存服务 战略(见下文).
否则,它被视为一种 文件系统路径 与本地 JSON 缓存文件( 相对或绝对), 直接使用节点读取/ 写入 fs 模块。此策略仅可使用服务器侧 (Node); 无法在浏览器上下文中使用 .

无论采用何种策略,图书馆自行管理缓存决定:

身份认证表本身 ttl 属性(以毫秒表示,预计在 credentialSubject.ttl)确定可信任缓存条目的时间。若为 Date.now() - cachedAt 低于 ttl,则使用缓存证书,且状态列表不作重排.
如果缓存条目缺失, stale, 或缓存后端无法访问, 库将返回到获取状态列表的证书 statusListCredential如果获取的文档定义了 ttl图书馆把它写回缓存.
如果状态列表证书没有定义 ttl,它不会被写到缓存中,并且会在每次验证中被取出新数据,即使 statusListCredentialCacheUrl 已经设定.
若为 statusListCredentialCacheUrl 不提供缓存策略, 不使用缓存策略, 状态列表证书总是被取出新鲜的, 匹配库的先前行为 .
该库不执行HTTP缓存服务的任何专用授权/自动调试机制. 如果您的缓存服务需要认证, 请直接嵌入到 statusListCredentialCacheUrl 本身作为查询参数(例如. https://my-caching-service.example.com/status-list-cache?token=my-secret-token),每向服务处提出要求,都会保留.

两种策略都具有相同的缓存输入形状, { cachedAt: number, credential: Object },因此缓存后端在存储按状态列表 URL 键的条目时不需要知道使用的策略 :

HTTP缓存服务合同

缓存服务被问及 GET {statusListCredentialCacheUrl} 带有 url 已添加查询参数( 任何已存在的查询参数 statusListCredentialCacheUrl ) (中文(简体). 预计它会用JSON外形的有效载荷进行响应 { credential: Object, cachedAt: number } (单位:千美元)cachedAt 是一个毫秒的时代时间戳,或者如果该 URL 没有被缓存的话是 falsy/ error 反应.
新的抓取被写回 POST {statusListCredentialCacheUrl} 和一个身体 { url: statusListCredentialUrl, credential: Object, cachedAt: number }。。。 .
如果没有请求的状态列表 URL 的缓存条目,服务必须返回一个 falsy/空响应(如 HTTP 404 或空正文)——这被作为普通缓存错失处理,库透明地回取状态列表的证书.

文件系统缓存文件合同

文件在 statusListCredentialCacheUrl (相对于 process.cwd() 当给出相对路径时)持有由状态列表证书URL键入的单个JSON对象: { [url]: { cachedAt: number, credential: Object } }。。。 .
如果文件尚未存在,则它被作为空存储器处理(每个 URL 丢失缓存),并在第一个写入时被创建(与任何缺失的中间目录一起).
通过读取整个文件,在状态列表 URL 所键入的新条目中合并,并完全重写文件——没有文件锁定,所以同时从多个进程写到同一个缓存文件不安全.
因为这个库是文件系统缓存文件的唯一所有者/作者,所以它也收集它:每次呼叫 checkBitStringStatusList 带有文件系统 statusListCredentialCacheUrl 刷出任何条目 ttl 已消费(即. Date.now() - cachedAt >= ttl)从程序前的文件中,只有在条目实际被删除的情况下才重写文件. 无可解决的条目 ttl,或不符合预期形状,被这个清理通道所未受. 这是一次轻量级,最优异的传球,每通电话都完成,而不是计划/背景工作——没有定期计时器,也没有对HTTP缓存服务进行清理,预计它会管理自己的垃圾收集.
此后端仅为节点/ 服务器侧。若为 statusListCredentialCacheUrl 解析到文件系统路径( 即它不是 http(s):// URL) 当库在浏览器中运行时, 它会扔出一个清晰的 VerifierError 解释文件系统缓存在那种环境中是不支持的,而不是由于来自基本动态的混乱模块解析/运行时间错误而失败 fs 导入.

违反合同行为

如果缓存后端( HTTP 响应正文, 或文件系统缓存文件内容) 存在, 但不符合 { cachedAt, credential } 形状(如无效的 JSON, 或缺失的对象) credential 或非数字 cachedAt),图书馆认为这是被错误地配置了缓存集成,并扔出一个 VerifierError如果核查失败,而不是默不作声地后退——这样做是为了使一体化错误显而易见,而不是打开失败并隐藏一个破碎的缓存.

所抛出的错误消息包括缓存位置,以帮助诊断这个问题. 对于HTTP缓存URL,查询字符串和片段被剥去后才会被包含入出错消息中(只保留出错源和路径),因为根据上面的指针可以嵌入一个认证符——这可以防止秘密泄露到被抛出的错误或下游日志中去. 文件系统路径作为-is包含.

贡献

运行测试

$ npm run test

手工测试

您可以测试构建输出( E)npm run build)在浏览器和(或)节点中,以确保以低的间接费用获得令人满意的结果.

浏览器

测试浏览器的构建只需运行 npm run test:manual:browser。这将打开一个 HTML 页面,如果您的默认浏览器将测试每个版本的定着度.

注 V1: 在编写本报告时,由于浏览器存在混合内容块,预计v1证书在检索发行者配置文件时会失败. 为规避这个问题,您可以修改v1证书,将发行方配置设置为HTTPS. 这意味着使用证书进行诱导,并会产生散列错配错误. 您也可以更改浏览器的设置来禁用混合内容块过滤器。该证书自被撤销后仍未被验证. 我们正在寻找一个工作V1的例子.

注五3:该证书因被吊销而不予验证. 这确实证明代码是有效的.

节点

要测试节点构建, 您首先需要启动服务器 : npm run test:manual:node:server

然后在单独的控制台窗口中运行: npm run test:manual:node:verify

注 V1: v1 验证没有通过,因为拒绝发行者配置文件检索。我们正在寻找一个工作V1的例子. 注五3:该证书因被吊销而不予验证. 这确实证明代码是有效的.

构建

$ npm run build

构建文件在 dist 文件夹.

核查进程

如果你想了解核查过程的详情,请查看文档。。。 .

联系人

联系我们 blockcerts 社区论坛。。。 .

版本与发布记录

@blockcerts/cert-verifier-js 共发布 140 个版本，首次发布于 2018/09/19；过去 12 个月发布了 14 个版本。

版本	发布日期	距今
`6.39.1`latest	2026/10/28	11 天前
`6.39.0`	2026/09/30	1 个月前
`6.38.1`	2026/09/15	1 个月前
`6.38.0`	2026/09/14	1 个月前
`6.37.2`	2026/09/04	2 个月前
`6.37.1`	2026/09/04	2 个月前

关于 @blockcerts/cert-verifier-js 的常见问题

@blockcerts/cert-verifier-js 是什么？

用于校验 Blockcert 的 Javascript 库

如何安装 @blockcerts/cert-verifier-js？

在项目目录运行 npm install @blockcerts/cert-verifier-js，或使用 pnpm add / yarn add / bun add。

@blockcerts/cert-verifier-js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@blockcerts/cert-verifier-js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@blockcerts/cert-verifier-js 可以商用吗？

@blockcerts/cert-verifier-js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@blockcerts/cert-verifier-js 的下载量有多少？

根据 npm 官方下载统计，@blockcerts/cert-verifier-js 在 2026/10/09 – 2026/11/07 这 30 天内被下载 10,778 次，日均约 359 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@blockcerts/cert-verifier-js 还在维护吗？

最新版本 6.39.1 发布于 2026/10/28（11 天前）；至今共发布 140 个版本，其中过去 12 个月发布了 14 个；首次发布于 2018/09/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。