@super-protocol/certs library v1.0.0

[marchuk-vlad]

Summary by CodeRabbit

• New Features

  • Full X.509 toolkit: key & certificate generation, CSR creation, parsing, and chain validation (offline, OCSP, CRL).
  • OCSP and CRL helpers, network fetching with in-memory caching, and key-format interop across PEM/DER/Node/WebCrypto.
  • Utility functions and exported constants for PKI workflows; central top-level exports.

• Chores

  • Project scaffolding: package manifest, license, .gitignore, ESLint, VS Code, TypeScript configs, build scripts, and CI/CD workflows.

• Tests

  • Comprehensive Vitest suites and helpers covering generator, helper, OCSP, CRL, and validator flows.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a new npm package implementing X.509/CSR generation and parsing, key conversion utilities, OCSP and CRL handling, certificate chain construction and validation, TypeScript build configs, CI workflows, tests, and packaging metadata.

Changes

Cohort / File(s)	Summary
Project & Packaging package.json, LICENSE, .gitignore, README.md, .vscode/settings.json	New package manifest and metadata, Business Source License, comprehensive .gitignore, README examples, and workspace TypeScript SDK setting.
Linting & TS Config .eslintrc.json, tsconfig.json, tsconfig.mjs.json, tsconfig.cjs.json, vitest.config.ts	ESLint config with test overrides; TS configs for ESM/CJS builds and project; Vitest config for tests and CI reporting.
CI/CD Workflows .github/workflows/pull-request.yml, .github/workflows/npm-publish.yml	PR and publish workflows that lint/build/test, perform ESM smoke-imports, and publish npm packages with computed dist-tags.
Entrypoint & Exports src/index.ts	Top-level re-exports aggregating the package public surface.
Types & Constants src/types.ts, src/constants.ts	Domain types for certificate/OCSP flows and exported OID and timeout constants.
Crypto Initialization src/setup-crypto.ts	Configures shared WebCrypto instance, pkijs/x509 wiring, K-256 curve/OID mapping, and exports the crypto provider.
Key Transformation src/crypto-key-transformer.ts	Convert between Node KeyObjects, PKCS#8/SPKI PEM, and WebCrypto CryptoKey; import/export and derive public key.
Certificate Generation & Parsing src/generator.ts, src/helper.ts	Certificate/CSR generation, parsing, PEM↔DER helpers, chain building/ordering, extension extraction, and cached binary downloader.
OCSP & CRL Handling src/ocsp.ts, src/crl.ts	OCSP request/response parsing and generation, network grouping/fetching and verification; CRL URL extraction, concurrent download and parsing.
Validation Engine src/validator.ts	Certificate chain validation using pkijs engine with optional OCSP/CRL inputs and validated-path membership checks.
Utilities src/utils.ts	IP validation, PromiseSettled guards, retry-with-interval utility, and ArrayBuffer/Uint8Array conversions.
Tests & Helpers test/* test/generator.test.ts, test/ocsp.spec.ts, test/validator.spec.ts, test/helper.spec.ts, test/mocks.ts, test/test-helpers.ts	Vitest suites and helpers covering generation, parsing, ordering, validator behavior (offline/OCSP), and fetch mocking.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Validator
    participant CertHelper as CertificatesHelper
    participant OCSP as OCSPHelper
    participant CRL as CRLHelper
    participant Remote as Remote_Servers
    participant ChainEngine as CertificateChainValidationEngine

    Client->>Validator: validateCertChain(certsPem, caPem, options)
    Validator->>CertHelper: sortCertsFromLeafToRoot(certsPem)
    CertHelper-->>Validator: sortedCerts

    alt options.checkOcsp
        Validator->>OCSP: getOCSPResponseFromCerts(sortedCerts, caCerts, oids)
        OCSP->>CertHelper: getExtensionValue(AIA_OID)
        CertHelper-->>OCSP: ocspUrls
        OCSP->>Remote: POST ocspRequest
        Remote-->>OCSP: ocspResponse
        OCSP->>OCSP: verify response, nonce, signer chain
        OCSP-->>Validator: basicOcspResponses
    end

    alt options.checkCrl
        Validator->>CRL: getCRLFromCerts(sortedCerts)
        CRL->>CertHelper: getExtensionValue(CRL_DP_OID)
        CertHelper-->>CRL: crlUrls
        CRL->>Remote: GET crlUrl
        Remote-->>CRL: crlBinary
        CRL->>CRL: parse CRL
        CRL-->>Validator: crlList
    end

    Validator->>ChainEngine: verify(chain=sortedCerts, trusted=caCerts, ocspResponses, crls)
    ChainEngine-->>Validator: verificationResult
    alt valid
        Validator-->>Client: { isValid: true }
    else invalid
        Validator-->>Client: { isValid: false, errorMessage }
    end

Loading

sequenceDiagram
    participant Dev as Developer
    participant Generator as CertificateGenerator
    participant Crypto as WebCrypto
    participant X509Gen as X509CertificateGenerator
    participant PEM as PEM_Encoder

    Dev->>Generator: generateCert(params)
    Generator->>Crypto: normalize/import keys
    Crypto-->>Generator: CryptoKey(s)
    Generator->>X509Gen: build X.509 object with extensions
    X509Gen-->>Generator: unsignedCert
    Generator->>X509Gen: sign(unsignedCert, privateKey)
    X509Gen-->>Generator: signedCert
    Generator->>PEM: encode signedCert -> PEM
    PEM-->>Dev: certificate PEM

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Poem

🐰 I hopped through keys and OIDs tonight,
I stitched a chain from leaf to light,
I chased the nonce and fetched the CRL,
With PEM and DER I cast my spell,
Now certs can bloom beneath my bite. 🌿🔐

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}