Development and releases

Tests

npm install
npm test

npm run test:types builds the TypeScript declarations from the source’s JSDoc (types/, not committed; npm pack builds them too) and type-checks two consumers through the package’s exports: a TypeScript file and a // @ts-check JavaScript file, each with deliberate mistakes that must still fail. It also compiles every ```ts example in the documentation, so an example that no longer matches the API fails the check.

The tests run with node:test against a strict in-memory OpenID Provider and SSF transmitter, injected through the library’s fetch option. The stub enforces public clients, PKCE, PAR and DPoP (proof signature, htm/htu/ath, key binding and nonces). The suite covers:

state, the front channel, RFC 9207 and the setup checks;
ID token validation, refresh (OIDC Core §12.2) and UserInfo;
DPoP, PAR, resource indicators, logout and dynamic registration;
the token cache, and several accounts per browser;
the SSF receiver: polling, catch-up, SET validation, acknowledgement and redelivery;
that the library imports no Node.js built-ins.

Node.js 24.22.1 or later is required (.nvmrc), the release that fixes HTTP2Shell (CVE-2026-111497).

API references

The site’s TypeScript API (TypeDoc) and JavaScript API (JSDoc) are generated from the source’s JSDoc by tools/apidocs. That is a package of its own, outside the npm workspace, because TypeDoc runs on TypeScript 6 and the library builds its declarations with 7. To build them locally:

cd tools/apidocs && npm ci && npm run build   # writes _site_api/api and _site_api/jsdoc

Continuous integration

Workflow	Runs on	Does
`tests.yml`	every push and pull request	`npm test`, then builds the demo container and smoke-tests the page, its headers and the modules it loads
`npm-publish.yml`	pushes to `main` and `develop` that change the package	tests, stamps the version, packs and publishes to npm with provenance
`pages.yml`	pushes to `main` that change the docs or the library’s source	builds this site and the API references, and deploys them

Branches

develop is where work comes together. Create every feature or fix branch from it, and merge back into it.
main is what is released. It receives develop when a release is cut.

git switch develop && git pull
git switch -c feature/<short-name>    # or fix/<short-name>
# commit, push, and open a pull request into develop

Versions and releases

Versions follow the usual npm form (scripts/version.mjs):

M.N is in the VERSION file. After bumping it, run npm run version:sync so the committed package.json files say M.N.0. npm run version:check (also run in CI) fails if they don’t.
The patch number is worked out at build time from the versions already on npm, so nobody edits it: one more than the highest published M.N release, from 0. CI writes it into the package just before packing, so a release needs no version commit.

Push to	Publishes	npm dist-tag	Example
`main`	a release, `M.N.P`	`latest`	`0.2.0`, `0.2.1`, …
`develop`	a pre-release of the next release, `M.N.P-next.R`	`next`	`0.2.1-next.0`, `0.2.1-next.1`, …

npm never resolves a range like ^0.2.0 to a pre-release, so a develop build only reaches someone who installs @next. npm run version:print shows the next release version; add -- --channel next for the next pre-release.

A pull request builds, tests and packs, and publishes nothing. Each published commit is tagged v<version>. Publishing uses the repository secret NPM_TOKEN, or npm trusted publishing once it is configured.