# @gldywn/sct\.js 中文文档

规范地址：https://npmcn.com/package/%40gldywn/sct.js/

版本：2\.0\.0
npm 元数据更新时间：2025-07-25T10:43:26.576Z
中文译文更新时间：2026-11-16T15:57:08.454Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gldywn/sct.js
原文对照：https://npmcn.com/package/%40gldywn/sct.js/?lang=original
项目主页：https://github.com/Gldywn/sct.js#readme
源码仓库：https://github.com/Gldywn/sct.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：140 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-07-10T14:13:52.274Z
- 最新版本发布：2025-07-25T10:43:26.378Z
- 近 30 天下载量：4088（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）

## 中文简介

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

## 安装

```sh
npm install @gldywn/sct.js
```

也可以使用：`pnpm add @gldywn/sct.js`、`yarn add @gldywn/sct.js`、`bun add @gldywn/sct.js`

## README

# SCT.js (英语)

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

[![Build Status](https://github.com/Gldywn/sct.js/actions/workflows/build.yml/badge.svg)](https://github.com/Gldywn/sct.js/actions/workflows/build.yml) [![Coverage Status (codecov.io)](https://codecov.io/gh/Gldywn/sct.js/branch/main/graph/badge.svg)](https://codecov.io/gh/Gldywn/sct.js) [![npm](https://img.shields.io/npm/v/@gldywn/sct.js.svg)](https://www.npmjs.com/package/@gldywn/sct.js)

## 状态

-   该图书馆稳定并可供生产使用.
-   支持两者 **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数据及其对应的证书或证书前数据.

## 安装

```sh
npm install @gldywn/sct.js
```

## 使用量

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

### 校验证书前 SCT

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

> 完整、可操作的例子见 [实例/核实-预告.ts](https://npmcn.com/package/%40gldywn/sct.js/examples/verify-precert.ts)。 。 。 .

```typescript
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](https://npmcn.com/package/%40gldywn/sct.js/examples/verify-x509.ts)。 。 。 .

```typescript
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);
}
```

## 测试

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

### 更新测试数据

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

```sh
npm run test:setup
```

此命令执行以下步骤:

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

### 运行测试

要运行完整的测试套件 :

```sh
npm test
```

## 许可证

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

## 浏览器兼容性

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

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

## 鸣谢

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

## 常见问题

### @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 和提交记录判断。

