Built-in algorithm seeding

Purpose

Seeds the default AlgorithmRegistry with the 13 built-in algorithm implementations required by RFC 7518 §3 and RFC 8037: HS256/HS384/HS512, RS256/RS384/RS512, PS256/PS384/PS512, ES256/ES384/ES512, EdDSA, plus the dual-flag-opt-in none. The seeding runs once at module load via a side-effect import from both algorithms/index.ts and the package root index.ts, so the registry is always populated before any verify or sign call. Idempotent via a module-scoped boolean — safe to call multiple times if a test reload cycles the module graph.

Features

Seeds 14 algorithms total (13 RFC-mandated + none).
Idempotent: seedBuiltinAlgorithms() is a no-op after the first call.
Side-effect import from algorithms/index.ts and src/index.ts.

Usage: Basic Example

import { defaultRegistry, seedBuiltinAlgorithms } from "@suaveplan/jws";

// Already seeded by the side-effect import — these are introspection-only:
defaultRegistry.algorithms();
// ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512",
//  "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA", "none"]

Usage: Advanced Example

import { AlgorithmRegistry, seedBuiltinAlgorithms } from "@suaveplan/jws";

// Build an isolated registry for an integration test, seeded identically to
// the default. (Useful when you want to register additional experimental
// algorithms without polluting the global registry.)
const isolated = new AlgorithmRegistry();
// Manually re-register the built-ins:
// (Note: `seedBuiltinAlgorithms` seeds the *default* registry, not an arbitrary
//  one; tests needing isolation use `defaultRegistry` directly or build the
//  isolated registry up from named imports of `hs256` / `rs256` / etc.)
seedBuiltinAlgorithms(); // idempotent no-op if already seeded

API Reference

seedBuiltinAlgorithms(): void — idempotent; seeds the package-shared defaultRegistry.

Implementation Notes

The side-effect import import "./builtin.js" at the top of algorithms/index.ts AND src/index.ts is load-bearing — without it, the first compactVerify call would throw JWS.ALG_UNSUPPORTED because the registry would be empty. The dual-import is defence in depth: any consumer importing from either the package root or the ./algorithms subpath triggers seeding. The implementation guards against double-registration via the idempotency flag rather than via the registry's own duplicate-rejection logic — that way a seedBuiltinAlgorithms() call from a test after a registry reset doesn't throw.

2.6 KiB Raw Blame History