first commit

docs/security-stack/security/jws/src/algorithms/builtin.md

@@ -0,0 +1,46 @@
+# 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
+
+```ts
+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
+
+```ts
+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.