@gldywn/sct.js

中文文档
2.0.0发布于 2025/07/25MITTypeScriptESM + CJS近 30 天下载 4088

验证 JavaScript 证书透明度的签名证书时间戳

中文使用文档
文档目录12 节
  1. 状态
  2. SCT如何获得
  3. 安装
  4. 使用量
  5. 校验证书前 SCT
  6. 正在验证 X.509 SCT (来自 TLS 扩展 / OCSP)
  7. 测试
  8. 更新测试数据
  9. 运行测试
  10. 许可证
  11. 浏览器兼容性
  12. 鸣谢

SCT.js (英语)

SCT.js是TypeScript中用于Node.js的证书透明SCT验证器. 它使用内置 node:crypto 用于所有加密操作的模块.

Build Status Coverage Status (codecov.io) npm

状态

  • 该图书馆稳定并可供生产使用.
  • 支持两者 X.509 (韩语) 财务报告和审定财务报表 证书前 SCT条目.
  • X.509条目的测试套件由原始的Rust库移植. 其扩充后为证书前条目综合生成的测试套件,涵盖多个签名算法的所有成功和出错案例(ECDSA P-256/P-384,RSA 2048/3072/4096).

SCT如何获得

已签名的证书时间戳(SCT)是证书透明的核心,但可以通过几种方式交付给客户端. 这个图书馆负责 核查 不论如何获得, 获得证书及其相关的SCT是客户申请的责任.

提供SCT有三种主要方法:

  1. 嵌入证书中 : SCT 直接作为扩展(1.3.6.1.4.1.11129.2.4.2) (中文(简体) ). 这是最常见的方法.
  2. 通过 TLS 扩展 : SCT在TLS握手期间通过 signed_certificate_timestamp 扩展名。 这对在日志被信任之前或当 CA 不参与 CT 时发布的证书有用.
  3. 通过 OCSP 刻录 : SCT包含在主干OCSP响应中,由服务器在TLS握手期间发送.

这个库可以从其中任何一个来源校验SCT,条件是您可以提供SCT数据及其对应的证书或证书前数据.

安装

npm install @gldywn/sct.js

使用量

图书馆支持两种主要验证方案: 预认证 (最常见的,见于最后证书)和通过 TLS 扩展或 OCSP,以X.509最后证书进行核查.

校验证书前 SCT

这是最常见的使用案例,通常用于验证在证书签发期间被直接嵌入的SCT. 要做到这一点,您需要两种最终证书(leafCert)及其签发人证书(issuerCert) (中文(简体) ). 这个 reconstructPrecert 函数用于创建SCT最初针对的数据结构.

完整、可操作的例子见 实例/核实-预告.ts。 。 。 .

import { verifySct, reconstructPrecert, ENTRY_TYPE, Log } from '@gldywn/sct.js';

try {
  // The leaf certificate (end-entity) and the issuer certificate both DER-encoded X.509
  const leafCert = readTestData('leaf_google-cert.bin', 'precert');
  const issuerCert = readTestData('issuer_google-cert.bin', 'precert');

  // The SCT embedded within the leaf certificate (extracted from the certificate itself)
  const precertSct = readTestData('google-sct0.bin', 'precert');

  // Helper function to reconstruct the precertificate data structure to verify the SCT against
  const precert = reconstructPrecert(leafCert, issuerCert);

  // A list of trusted logs
  const trustedLogs: Log[] = [
    {
      description: 'Fetched Google Test Log',
      key: getTrustedLogKey(),
      id: createHash('sha256')
        .update(getTrustedLogKey().export({ type: 'spki', format: 'der' }))
        .digest(),
      url: 'test.com',
      operated_by: 'Test',
      max_merge_delay: 0,
      status: 'usable',
    },
  ];

  const { log, sct } = verifySct(precertSct, precert, ENTRY_TYPE.PRECERT_ENTRY, Date.now(), trustedLogs);
  console.log(`Pre-cert SCT verification successful!`);
  console.log(`  Log ID: ${log.id.toString('hex')}`);
  console.log(`  Log: ${log.description}`);
  console.log(`  Timestamp: ${new Date(Number(sct.timestamp)).toISOString()}`);
} catch (error) {
  console.error('Error while verifying pre-certificate SCT:', error);
}

正在验证 X.509 SCT (来自 TLS 扩展 / OCSP)

当SCT与证书分开交付时,例如用在 signed_certificate_timestamp TLS扩展或主干OCSP响应. 在这种情况下,SCT与最终的,被编码为X.509的证书直接进行校验,不需要重建.

完整、可操作的例子见 实例/核实-x509.ts。 。 。 .

import { verifySct, ENTRY_TYPE, Log } from '@gldywn/sct.js';

try {
  // The leaf certificate (end-entity), DER-encoded X.509
  const certificate = readTestData('google-cert.bin', 'x509');

  // The SCT, obtained either from the "signed_certificate_timestamp" TLS extension or OCSP response
  const sct = readTestData('google-sct0.bin', 'x509');

  // A list of trusted logs
  const trustedLogs: Log[] = [
    {
      description: "Google 'Pilot' log",
      key: jwkFromRawEcdsa(readTestData('google-pilot-pubkey.bin', 'x509')),
      id: Buffer.from('a4b90990b418581487bb13a2cc67700a3c359804f91bdfb8e377cd0ec80ddc10', 'hex'),
      url: 'ct.googleapis.com/pilot/',
      operated_by: 'Google',
      max_merge_delay: 86400,
      status: 'usable',
    },
  ];

  const { log, sct: parsedSct } = verifySct(sct, certificate, ENTRY_TYPE.X509_ENTRY, Date.now(), trustedLogs);
  console.log(`X.509 SCT verification successful!`);
  console.log(`  Log ID: ${log.id.toString('hex')}`);
  console.log(`  Log: ${log.description}`);
  console.log(`  Timestamp: ${new Date(Number(parsedSct.timestamp)).toISOString()}`);
} catch (error) {
  console.error('Error while verifying X.509 SCT:', error);
}

测试

该项目包括一个综合测试套件,以确保正确性和稳定性.

更新测试数据

该寄存器包括预先生成的测试数据. 为了更新证书前测试的固定装置,运行:

npm run test:setup

此命令执行以下步骤:

  1. 生成测试密钥 : 为所有支持的算法创建新密钥对.
  2. 生成证书前数据 : 新建一套模拟SCT和测试案例.
  3. 获取真实世界数据 : 从谷歌下载最新的测试证书.

运行测试

要运行完整的测试套件 :

npm test

许可证

SCT.js以麻省理工学院的许可证发售.

浏览器兼容性

该图书馆目前用于 只有节点.js环境。 。 。 .

它依赖于Node.js内建模块,比如: crypto 财务报告和审定财务报表 Buffer 在网页浏览器中找不到。 虽然理论上可以通过使用多填充(例如: crypto-browserify 财务报告和审定财务报表 buffer),这在此时没有正式支持或测试. 未来的版本可能包括一个与浏览器兼容的捆绑.

鸣谢

这个库是一个全功能的 TypeScript 端口 锈口/钢丝 图书馆。 它被设计为1:1功能等同,并包括了原作中综合测试套件的忠实出港,以确保正确.

版本与发布记录

@gldywn/sct.js 共发布 5 个版本,首次发布于 2025/07/10;过去 12 个月发布了 0 个版本。

版本发布日期距今
2.0.0latest2025/07/251.3 年前
1.3.12025/07/191.3 年前
1.2.02025/07/171.3 年前
1.1.02025/07/101.4 年前
1.0.02025/07/101.4 年前

关于 @gldywn/sct.js 的常见问题

@gldywn/sct.js 是什么?

验证 JavaScript 证书透明度的签名证书时间戳

如何安装 @gldywn/sct.js?

在项目目录运行 npm install @gldywn/sct.js,或使用 pnpm add / yarn add / bun add。

@gldywn/sct.js 支持 TypeScript 吗?

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

@gldywn/sct.js 支持 ESM 还是 CommonJS?

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

@gldywn/sct.js 可以商用吗?

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

@gldywn/sct.js 的下载量有多少?

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

@gldywn/sct.js 还在维护吗?

最新版本 2.0.0 发布于 2025/07/25(1.3 年前);至今共发布 5 个版本,其中过去 12 个月发布了 0 个;首次发布于 2025/07/10。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。