# Contributing to @peculiar/webcrypto Thank you for your interest in contributing to `@peculiar/webcrypto`! 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 `^20.19.0 || >=22.12.0` (CI uses Node.js 24) - npm (the repository is locked with `package-lock.json`) ### Installation ```bash git clone https://github.com/PeculiarVentures/webcrypto.git cd webcrypto 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 public API (`Crypto`, and `CryptoKey` re-exported from `webcrypto-core`). - `src/crypto.ts` contains `Crypto`; `src/subtle.ts` contains `SubtleCrypto`, which registers the providers (some depend on what the running Node.js `crypto` supports). - `src/mechs//` contains the providers (`aes`, `des`, `rsa`, `ec`, `ed`, `ed25519`, `hmac`, `hkdf`, `pbkdf`, `sha`, `shake`), built on `node:crypto` on top of the `webcrypto-core` base providers. `src/mechs/storage.ts` maps the public `CryptoKey` objects to their internal key data. - `src/keys/` contains the internal key classes (`@peculiar/json-schema` decorators for JWK); `src/converters/` contains the JWK base64url converter. - `src/index.spec.ts` contains the public-API smoke tests, `src/webcrypto-test.spec.ts` runs the shared `@peculiar/webcrypto-test` suite, and the other `*.spec.ts` files sit next to the code they test. - `build/` is generated by `npm run build` and is not committed. ## 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 `*.spec.ts` (mechanism tests in `src/mechs//`, public-API tests in `src/index.spec.ts`). - 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 builds `src/index.ts` into `build/index.js` with `.d.ts` declarations. Output is unbundled, so every source module is emitted under `build/` mirroring `src/`, but only `build/index.js` is reachable through `exports`. The syntax target comes from `engines.node`; do not set `target` in `tsdown.config.ts`. `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. 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. The package targets Node.js only (`platform: "node"` in `tsdown.config.ts`); the providers use `node:crypto`. `webcrypto-core`, `@peculiar/asn1-schema` and `@peculiar/json-schema` are peer dependencies (and devDependencies): keys are parsed and serialized with classes that register in the module-level schema storages, and `CryptoKey` is re-exported from `webcrypto-core`, so the app must load a single copy of each. Keep the peer and dev ranges in sync. `@peculiar/utils` is a regular dependency; import it from the root or its subpaths (`@peculiar/utils/bytes`, `@peculiar/utils/pem`, ...), never from `@peculiar/utils/legacy`. The package is `"sideEffects": false`. Import-time work (decorator registration) must stay in the module that defines the class it writes to, so a bundler that keeps the class also keeps the registration. The declarations are generated from the source. `Crypto.subtle` is typed with the DOM `SubtleCrypto` overloads on top of `webcrypto-core`'s type; `src/index.spec.ts` compiles typical consumer calls, so keep it passing `npm run typecheck`. ### 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(rsa)!: ...`) 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 to the owning module. - Keep `Buffer` and other Node.js types out of the public API; it follows the WebCrypto `Crypto` interface. - Keep public exports stable; 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. 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 `v2`) 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/webcrypto/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. ## License By contributing to this project, you agree that your contributions will be licensed under the MIT License.