# micro509
[][npm]
[][jsr]
[][socket]
一个零依赖的 TypeScript PKI 工具包，用于证书、验证、吊销和 PKCS 工作流。
零依赖。支持 Tree-shaking 的子路径入口点。纯 WebCrypto。到处运行：Node、Bun、Deno、浏览器、Cloudflare Workers。
## 安装
```
npm install micro509
```
## 为什么选择 micro509
JavaScript PKI 库通常会迫使你做出糟糕的权衡：
重量级的标准工具包、遗留的加密大杂烩，
或是功能单一的解析工具。
micro509 是一个实用的折中方案：一个现代的、原生支持 WebCrypto 的
PKI 工具包，具有零运行时依赖和类型化的 API，适用于大多数应用程序实际需要的
工作流。
它为你提供了一个用于创建证书和 CSR、
链验证、服务身份匹配、CRL、OCSP、
PKCS#7 SignedData、PFX/PKCS#12、PEM 处理和密钥
导入/导出的单一库。
并且当验证失败时，你会获得你的代码可以处理的类型化结果：[针对每种失败模式的类型化错误代码]、失败的
证书索引，以及结构化的失败详细信息，而不是 `false`。
```
if (!result.ok) {
// result.error.code: 'signature_invalid' | 'certificate_expired' | 'name_constraints_violated' | ...
// result.error.index: which certificate in the chain failed
// result.error.details: { expected, actual } for identity mismatches
}
```
除了验证之外，micro509 还涵盖了在一个零依赖的 JS 包中很难找到的 PKI 领域：
- **OCSP** — 构建请求、解析和验证响应、验证响应者授权
- **PFX / PKCS#12** — 创建和解析受密码保护的密钥+证书包
- **PKCS#7 / CMS** — 签名内容、解析和验证 SignedData、提取证书包
- **CRLs** — 创建、解析、验证和检查吊销状态
- **加密密钥** — PBES2 PKCS#8、遗留 OpenSSL 加密 PEM、PKCS#1、SEC1
- **密钥导入/导出** — PKCS#8、SPKI、JWK、PKCS#1、SEC1，支持生成 RSA、ECDSA、Ed25519
- **服务身份** — 通配符 DNS、IPv6 规范化、URI-ID、SRV-ID、显式 CN 选择性启用
严格的默认值，显式的逃生舱 — 诸如 CN
回退或自签名叶证书接受等危险操作需要显式开启。所有这些都没有 `any`，
没有类型断言，没有非空断言，也没有会破坏边缘运行时的运行时 DI 框架。
## 快速开始
创建一个自签名证书：
```
import { createSelfSignedCertificate } from 'micro509';
const { certificate, keyPair } = await createSelfSignedCertificate({
subject: {
commonName: 'example.com',
organization: 'Acme',
country: 'US',
},
validity: { days: 30 },
extensions: {
keyUsage: ['digitalSignature', 'keyEncipherment'],
subjectAltNames: [
{ type: 'dns', value: 'example.com' },
{ type: 'dns', value: 'www.example.com' },
],
},
});
console.log(certificate.pem);
console.log(await keyPair.exportPkcs8Pem());
```
创建一个 CSR：
```
import { createCertificateSigningRequest, generateKeyPair } from 'micro509';
const keyPair = await generateKeyPair({ kind: 'ed25519' });
const csr = await createCertificateSigningRequest({
subject: { commonName: 'csr.example' },
publicKey: keyPair.publicKey,
signerPrivateKey: keyPair.privateKey,
extensions: {
subjectAltNames: [{ type: 'dns', value: 'csr.example' }],
},
});
console.log(csr.pem);
```
解析一个证书：
```
import { parseCertificatePem, unwrap } from 'micro509';
// Using certificate from previous example
const parsed = unwrap(parseCertificatePem(certificate.pem));
console.log(parsed.subject.values.commonName);
console.log(parsed.extendedKeyUsage);
console.log(parsed.authorityInfoAccess);
```
`parseCertificatePem` 返回一个类型化的 `Result` — 检查 `result.ok`，或者
对于格式错误的输入调用 `unwrap()` 抛出异常。
验证一个链：
```
import { verifyCertificateChain } from 'micro509';
// Assuming you have a self-signed certificate used as both leaf and root; no intermediates
const result = await verifyCertificateChain({
leaf: certificate.pem,
intermediates: [],
roots: [certificate.pem], // Using self-signed cert as root for demo
purpose: 'serverAuth',
serviceIdentity: { type: 'dns', value: 'example.com' },
});
if (result.ok) {
console.log(result.value.chain.length);
} else {
console.log(result.error.code);
}
```
## 运行时支持
| 运行时 | 状态 | 备注 |
| ------- | --------- | -------------------------------------------------- |
| Node | supported | 带有 WebCrypto 全局变量的现代 Node（在 24+ 上测试） |
| Bun | supported | Bun 1.3+ |
| Deno | supported | 需要 WebCrypto 和 Web text/base64 全局变量 |
| Browser | supported | 仅限现代浏览器 |
| Worker | supported | 需要相同的 WebCrypto 和 text/base64 全局变量 |
核心保持纯 ESM 且无副作用。
## 算法支持
| 领域 | 内置支持 |
| ------------------------------ | -------------------------------------------------------------------- |
| 证书和 CSR 签名 | RSA PKCS#1 v1.5, RSA-PSS, ECDSA `P-256` / `P-384` / `P-521`, Ed25519 |
| RSA 密钥 API | `scheme: 'pkcs1-v1_5'` |
| ECDSA 密钥 API | `P-256`, `P-384`, `P-521` |
| 加密的 PKCS#8 和 PFX | PBES2 配合 AES-CBC 以及 PBKDF2 HMAC-SHA1/HMAC-SHA256 |
| 加密的传统 PEM | 用于 RSA 和 EC 私钥的 AES-128-CBC, AES-192-CBC, AES-256-CBC |
`micro509` 专注于在现代 X.509 和基于 WebCrypto 的运行时中具有广泛互操作性的算法。\
它有意将小众的、特定于区块链的或仅用于密钥协商的原语排除在核心 API 之外，除非库明确支持的 PKI 工作流需要它们。
## 标准状态
| 领域 | 状态 |
| ---------------------------- | -------- |
| RFC 5280 路径验证 | complete |
| RFC 6960 OCSP | complete |
| RFC 6125 服务身份 | complete |
| RFC 9618 策略验证 | complete |
有关详细的范围边界，请参阅 [`docs/PKIX-SCOPE.md`](./docs/PKIX-SCOPE.md)；有关公共模块范围，请参阅 [API 参考](https://micro509.kjanat.dev/api/)。
## 导入
对于大多数应用程序，使用根包：
```
import { createCertificate, parseCertificatePem, verifyCertificateChain } from 'micro509';
```
当你想要详尽的高级类型或更窄的
工作流范围时，使用领域入口点：
```
import { parseCertificatePem } from 'micro509/x509';
import { verifyCertificateChain, matchServiceIdentity } from 'micro509/verify';
import { createOcspRequest, checkCertificateRevocation } from 'micro509/revocation';
import { createPfx } from 'micro509/pkcs';
import { generateKeyPair } from 'micro509/keys';
import { pemDecode, pemEncode } from 'micro509/pem';
import type { Micro509Error } from 'micro509/result';
```
完整的稳定子路径列表位于 [API 参考](https://micro509.kjanat.dev/api/)中。
## 更多文档
- API 参考: [micro509.kjanat.dev/api](https://micro509.kjanat.dev/api/)
- 标准范围: [`docs/PKIX-SCOPE.md`](./docs/PKIX-SCOPE.md)
- PKITS 测试套件: [`test/pkits.test.ts`](./test/pkits.test.ts)
- 差异化测试套件: [`test/differential.test.ts`](./test/differential.test.ts)
- 贡献指南: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
## 许可证
[MIT](./LICENSE)