# Contributing to @peculiar/x509 Thank you for your interest in contributing to `@peculiar/x509`! This document describes how to set up the project, which checks a change must pass, and how releases are made. ## Development Setup ### Prerequisites - Node.js `^22.18.0 || ^24.11.0 || >=26.0.0` for development, as required by tsdown and Vitest (CI uses Node.js 24). The published package supports `^20.19.0 || >=22.12.0`. - npm (the repository is locked with `package-lock.json`) ### Installation ```bash git clone https://github.com/PeculiarVentures/x509.git cd x509 npm ci npm test npm run build ``` ## Project Layout - `src/index.ts` is the package's only entry point and must stay aligned with the package exports. When it runs, it registers the built-in extensions, attributes and signature formatters. - `src/.ts` holds one public class or a small group of related types: certificates (`x509_cert.ts`, `x509_cert_generator.ts`), CRLs, PKCS#10 requests, names, public keys, PEM and text converters. - `src/extensions/` and `src/attributes/` contain the typed X.509 extensions and PKCS#10 attributes and their factories. - `src/*_algorithm.ts` map WebCrypto algorithms to ASN.1 algorithm identifiers. Each registers itself in the `tsyringe` container when it is loaded; `src/algorithm.ts` holds the `AlgorithmProvider` that resolves them. - `src/provider.ts` holds the `cryptoProvider` registry (defaults to `globalThis.crypto`). - `build/` is generated by `npm run build` and is not committed. - `website/` is the [documentation site](https://peculiarventures.github.io/x509/) (Docusaurus), a separate npm package with its own lockfile. Its API pages are generated from `src/` with TypeDoc. The root lint, format, test and build tools ignore it; run it with `npm ci --prefix website && npm run build --prefix website`. - `website/docs/examples/` holds the runnable examples: each `*.example.ts` is a complete script, shown on its `.mdx` page with a **Run** button. They import `@peculiar/x509` from `src/` (no build needed) and are typechecked with `npx tsc --noEmit -p website/docs/examples`, so an API change that breaks an example fails the **Website** workflow. Imports in examples must fit on one line. ## Development Workflow ### Code Quality Before opening a pull request, run: ```bash npm run lint # oxlint npm run format:check # oxfmt npm run typecheck # tsc --noEmit npm test # vitest, runs once and exits npm run build # tsdown, also checks the package with attw ``` Fix lint and formatting issues with `npm run lint:fix` and `npm run format`. Use `npm run coverage` to produce a coverage report. ### Testing - Use Vitest. - Put tests next to the code they cover as `src/.spec.ts` (issue regressions and public-API tests in `src/index.spec.ts`). - `vitest.setup.ts` loads the Reflect polyfill that `tsyringe` needs and registers one `@peculiar/webcrypto` instance as the crypto provider; specs read it with `cryptoProvider.get()` instead of setting their own. It stays the test provider because some specs cover algorithms only it implements (brainpool and K-256 curves, Ed448/X448 as `EdDSA`/`ECDH-ES`). The issue regressions in `src/index.spec.ts` use Node.js's built-in WebCrypto. - Cover new behavior and bug fixes with tests. ### Build And Package Exports The package is ESM-only; there is no CommonJS build, and CommonJS consumers load it through `require(esm)`. tsdown (`tsdown.config.ts`) bundles `src/index.ts` into a single `build/index.js` with a `build/index.d.ts` declaration, both with the LICENSE banner, and keeps every dependency external. There is no browser script bundle: browsers use the ESM build through a bundler or a CDN such as esm.sh (see the README). The syntax target comes from `engines.node`; do not set `target` in `tsdown.config.ts`. The output stays bundled because importing the package registers the extensions, attributes, algorithms and signature formatters at module level. With a single module, bundlers keep those calls whenever any export is used, so the package can still be published with `"sideEffects": false`. Don't switch to unbundled output without moving that registration. `exports` and the legacy `main`/`module`/`types` fields in `package.json` are generated by tsdown on every build and must not be edited by hand. To change the entry point, change `entry` in `tsdown.config.ts`, run `npm run build`, and commit the regenerated `package.json`. CI fails if the build changes `package.json`. Use named exports only (no `export default`) and no top-level `await`, so `require()` of the package keeps working on supported Node.js versions. `@peculiar/asn1-schema` is a peer dependency (and a dev dependency for the tests): its decorators register the `@peculiar/asn1-*` classes in a module-level schema storage, and x509 serializes and parses those classes with `AsnConvert`, so the application must have a single copy. The other `@peculiar/asn1-*` packages are regular dependencies; they are released in lockstep and peer on asn1-schema themselves. The tsconfig keeps `experimentalDecorators` for the `tsyringe` `@injectable()` decorators. It sets `"useDefineForClassFields": false`, as v2 did: the base classes call `onInit()` from their constructor to fill fields that subclasses declare without an initializer, and define semantics would reset those fields to `undefined`. `vitest.config.ts` applies the same semantics to the tests. ### Commit Messages Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). Pull requests are squash-merged, so the pull request title becomes the commit message and must follow the same format. ```plain type(scope): description [optional body] [optional footer] ``` Types: `feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `build`, `ci`, `chore`, `style`, `revert`. Mark breaking changes with `!` after the type or scope (for example `feat!: ...`) and/or a `BREAKING CHANGE:` footer. ### Pull Requests 1. Fork the repository and create a branch from `master`. 2. Make your changes, with tests. 3. Run the checks listed above. 4. Open a pull request with a Conventional Commit title. ## Code Style - Write TypeScript. - Follow the oxlint (`.oxlintrc.json`) and oxfmt (`.oxfmtrc.json`) configuration. Keep the lint config practical: prefer fixing the source over adding rules that only create churn, and disable a rule only when it fights the established style. - Keep changes small and localized. - Keep the code free of Node.js-specific APIs; the package runs in Node.js and browsers and uses WebCrypto through `cryptoProvider`. - Don't add import-time side effects beyond the registrations described above. - Document every public exported type and function with concise TSDoc. - Keep public exports and class identities stable; downstream packages (`@peculiar/pdf`, `@peculiar/acme-*`, `@webcrypto-local/*`, ...) depend on them, and breaking changes need a major release. ## Releases Releases are managed by [release-please](https://github.com/googleapis/release-please) (`release-please-config.json`, `.release-please-manifest.json`): 1. On every push to `master`, the **Publish** workflow first runs lint, format, typecheck, tests, and build (the **Test** workflow). Only when they pass does release-please open or update a `chore(release): vX.Y.Z` pull request that bumps `package.json`/`package-lock.json`. The version comes from the commits: a breaking change bumps major, `feat` bumps minor, and `fix`, `perf`, `build`, and `revert` bump patch. Other types do not trigger a release. Changes under `website/` never trigger a release. 2. Merge the release pull request. release-please creates the `vX.Y.Z` tag and a GitHub Release with the notes from the pull request; the workflow then publishes that commit to npm via Trusted Publisher, with provenance, and moves the major tag (for example `v3`) when this is the newest release of that major. To retry a failed npm publish, run **Publish** manually from the `vX.Y.Z` tag. Set the optional `RELEASE_TOKEN` secret (PAT or GitHub App token) so the Test workflow runs on the release pull request. Release notes live only in [GitHub Releases](https://github.com/PeculiarVentures/x509/releases); there is no `CHANGELOG.md`. Only `feat`, `fix`, `perf`, `build`, `revert`, and breaking changes are listed. Force a version with a `Release-As: x.y.z` line in a commit body. To fix the notes for a merged change, add a `BEGIN_COMMIT_OVERRIDE` … `END_COMMIT_OVERRIDE` block with the corrected commit message to that pull request's description; edits to the release pull request description are overwritten when new commits land. The website is deployed separately: the **Website** workflow typechecks the examples and builds `website/` on every pull request, and publishes it to GitHub Pages on every push to `master`. ## License By contributing to this project, you agree that your contributions will be licensed under the MIT License.