@gldywn/crlset.js

中文文档
1.2.0发布于 2025/08/08MITTypeScriptESM + CJS近 30 天下载 4088

Fetches and parses the latest Chrome CRLSet in memory, with support for checking whether a certificate or its issuer has been revoked.

原始使用文档
文档目录9 节
  1. Installation
  2. Basic Usage
  3. Advanced Usage
  4. Granular Checks
  5. Direct CRLSet Instantiation
  6. Exported Utility Functions
  7. Test
  8. Running Tests
  9. License

crlset.js

CRLSet.js

CRLSet.js is a lightweight CRLSet parser and verifier in TypeScript for Node.js. It fetches and parses the latest Chrome CRLSet in memory, with support for checking whether a certificate or its issuer has been revoked.

Build Status Coverage Status (codecov.io) npm License: MIT

A CRLSet is a collection of certificate revocation information aggregated by Google and used in Chrome to quickly identify and block revoked certificates. Unlike traditional Certificate Revocation Lists (CRLs) or the Online Certificate Status Protocol (OCSP), which can be slow and unreliable, CRLSets provide a fast and efficient mechanism for checking the revocation status of a certificate.

This library handles the process of fetching the latest CRLSet from Google's Omaha proxy, verifies its signature to ensure its integrity, parses it, and makes it available for revocation checks. It is designed for easy embedding in HTTPS agents or TLS validation flows. While it offers a simple one-line function for most use cases, it also exports its core components for more advanced, custom implementations.

Installation

npm install @gldywn/crlset.js

Basic Usage

The primary function of this library is to determine if a given certificate has been revoked according to the latest CRLSet. This is done by checking the certificate's issuer and serial number against the blocklists in the CRLSet.

For a complete, runnable example, see examples/verify.ts.

console.log('Loading the latest CRLSet...');
/*
 * By default, `loadLatestCRLSet` verifies the CRX signature, checks for a newer version,
 * and downloads it if available. The latest version is cached to avoid redundant downloads.
 * For customization:
 *  - `verifySignature: false`: Disables CRX signature verification (not recommended).
 *  - `updateStrategy: 'on-expiry'`: Updates only when the cached version hard-expires (not recommended).
 * e.g. `await loadLatestCRLSet({ verifySignature: false, updateStrategy: 'on-expiry' })`
 */
const crlSet = await loadLatestCRLSet();
console.log(
  `Successfully loaded CRLSet ${crlSet.sequence} (${crlSet.getBlockedSpkiCount()} blocked SPKIs, ${crlSet.getRevocationCount()} revocations).`,
);

const revokedBySerialInfo = {
  spkiHash: '03b4392598a10a3ff5695cf02a5775586b170f564a808a4d41568578a184e329',
  serialNumber: '179cc56dc82dbded5573c7999997f646',
};

console.log(
  `\nChecking certificate with issuer SPKI hash: ${revokedBySerialInfo.spkiHash} and serial number: ${revokedBySerialInfo.serialNumber}...`,
);
const status = crlSet.check(revokedBySerialInfo.spkiHash, revokedBySerialInfo.serialNumber);
console.log(`Certificate revocation status: ${RevocationStatus[status]}`); // REVOKED_BY_SERIAL

// [...]
crlSet.check(revokedBySpkiInfo.spkiHash, notRevokedInfo.serialNumber); // REVOKED_BY_SPKI
crlSet.check(notRevokedInfo.spkiHash, notRevokedInfo.serialNumber); // OK

Advanced Usage

For more specific use cases, you can use the CRLSet class and other exported functions directly. This allows you to construct a CRLSet instance from custom data or leverage the library's internal mechanics for your own logic. This makes crlset.js a versatile "Swiss Army knife" for handling CRLSets.

Granular Checks

While the check method performs a comprehensive verification, you can also call the underlying methods directly if you need to distinguish between different revocation reasons:

const isRevokedBySpki = crlSet.isRevokedBySPKI(certificateInfo.spkiHash);
console.log(`Is certificate revoked by SPKI?: ${isRevokedBySpki}`);

const isRevokedBySerial = crlSet.isRevokedBySerial(certificateInfo.spkiHash, certificateInfo.serialNumber);
console.log(`Is certificate revoked by serial?: ${isRevokedBySerial}`);

Direct CRLSet Instantiation

You can create a CRLSet instance yourself if you have the header and revocation data.

import { CRLSet, RevocationStatus } from '@gldywn/crlset.js';
import type { CRLSetHeader } from '@gldywn/crlset.js';

// Define the header and revocation data
const header: CRLSetHeader = {
  Sequence: 1,
  NumParents: 1,
  BlockedSPKIs: [],
  NotAfter: Math.floor(Date.now() / 1000) + 3600, // Expires in 1 hour
  ContentType: 'CRLSet',
  DeltaFrom: 0,
};

const revocations = new Map<string, Set<string>>();
const spkiHash = 'a_spki_hash_in_hex';
const serials = new Set(['a_serial_number_in_hex']);
revocations.set(spkiHash, serials);

// Create a new CRLSet instance
const crlSet = new CRLSet(header, revocations);

// Use it as usual
const status = crlSet.check(spkiHash, 'a_serial_number_in_hex');
console.log(RevocationStatus[status]); // REVOKED_BY_SERIAL

Exported Utility Functions

The library exports most of its internal functions, allowing you to build custom logic:

  • fetchCrxUrl(): Retrieves the download URL for the latest CRLSet CRX file from Google's Omaha proxy.
  • downloadLatestCRLSetCrx(): Downloads the full CRLSet CRX file and returns it as a Buffer.
  • fetchRemoteHeader(): Performs a partial download to fetch only the header of the latest CRLSet, useful for quick version checks.
  • unpackCrx(crxBuffer): Parses a raw CRX file buffer, separating the Protobuf header from the main ZIP content.
  • processCrx(crxBuffer, verifySignature): A high-level function that unpacks a CRX file, optionally verifies its signature, and parses the contained CRLSet data.
  • parseCRLSet(crlSetBuffer): Parses the binary CRLSet data (the crl-set file from the ZIP) into a structured header and a map of revocations.
  • parseCRLSetHeader(crlSetBuffer): A lightweight parser that reads only the JSON header from the CRLSet data.
  • verifyCrxSignature(crxHeader, zipBuffer): Verifies the signature of a CRX file against the public keys in its header.

Test

This project includes a comprehensive test suite to ensure correctness and stability.

Running Tests

To run the complete test suite:

npm test

License

CRLSet.js is distributed under the MIT license.

版本与发布记录

@gldywn/crlset.js 共发布 6 个版本,首次发布于 2025/08/01;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.2.0latest2025/08/081.3 年前
1.1.32025/08/061.3 年前
1.1.22025/08/061.3 年前
1.1.12025/08/061.3 年前
1.1.02025/08/061.3 年前
1.0.02025/08/011.3 年前

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

@gldywn/crlset.js 是什么?

Fetches and parses the latest Chrome CRLSet in memory, with support for checking whether a certificate or its issuer has been revoked.

如何安装 @gldywn/crlset.js?

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

@gldywn/crlset.js 支持 TypeScript 吗?

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

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

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

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

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

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

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

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

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