feat: implement crypto hardening and bump deps

.github/workflows/dependency-review.yml

@@ -22,5 +22,6 @@ jobs:
         with:
           fail-on-severity: moderate
           comment-summary-in-pr: always
-          # Allow LGPL (more permissive than GPL)
-          allow-licenses: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD, Unlicense, LGPL-2.1, LGPL-3.0, MPL-2.0, BlueOak-1.0.0
+          # SPDX allowlist for dependencies currently in this repo's lockfile.
+          # Keep this explicit so license policy changes are intentional in PRs.
+          allow-licenses: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD, Unlicense, BlueOak-1.0.0, MPL-2.0, Zlib, CC0-1.0, Python-2.0, LGPL-2.0-only, LGPL-2.1, LGPL-2.1-only, LGPL-3.0, LGPL-3.0-only, LGPL-3.0-or-later

ENHANCEMENT_JWKS_HTTP_feedback.md

@@ -15,7 +15,7 @@ I’ll call out where I think you’re solid, and then a few small polish / hard
 - **HS512 secret strength:** 64-byte minimum with explicit enforcement.
 - **Single-mode requirement:** config error if HS + asym are both set.
 
-From a design perspective, this is _much_ safer than the majority of “roll your own JWT” setups in the wild.
+From a design perspective, this is _much_ safer than the majority of "roll your own JWT" setups in the wild.
 
 ---
 
@@ -50,9 +50,9 @@ Narrower is always safer.
 
 ---
 
-### 2. Make the “mode determined by config” super explicit
+### 2. Make the "mode determined by config" super explicit
 
-You describe it correctly, but I’d tighten the language so nobody later “simplifies” it back to trusting `alg`:
+You describe it correctly, but I’d tighten the language so nobody later "simplifies" it back to trusting `alg`:
 
 > **Mode selection**
 >
@@ -73,7 +73,7 @@ That’s great. I’d add one short line:
 
 > When importing JWKs, the expected algorithm (`'EdDSA'`, `'RS256'`, etc.) is provided explicitly, so keys cannot be repurposed for other algorithms even within the same key family.
 
-That signals that you’re not just whitelisting “any RS\*”, you’re actually pinning at import time too.
+That signals that you’re not just whitelisting "any RS\*", you’re actually pinning at import time too.
 
 ---
 
@@ -83,14 +83,14 @@ Returning `null` to callers is fine, but I’d explicitly say:
 
 > Internally, verification failures are **logged with structured metadata** (issuer, kid, reason category) and counted in metrics. Externally, all failures are returned as `null` to avoid leaking details.
 
-Otherwise someone might over-interpret “fail-silent” as “we don’t log anything,” which would be painful in prod.
+Otherwise someone might over-interpret "fail-silent" as "we don’t log anything," which would be painful in prod.
 
 ---
 
 ### 5. A couple of small wording / clarity tweaks
 
-- You sometimes say **“decrypt key”** – for JWT as you’re using it, it’s **sign/verify**, not encrypt/decrypt. I’d keep wording to “signing key” / “verification key” to avoid confusion with JWE.
-- In “Security Checklist,” maybe add:
+- You sometimes say **"decrypt key"** – for JWT as you’re using it, it’s **sign/verify**, not encrypt/decrypt. I’d keep wording to "signing key" / "verification key" to avoid confusion with JWE.
+- In "Security Checklist," maybe add:
   - `[ ] JWT_AUD is specific per service (no wildcard audiences)` – avoids token reuse between services.
 
 ---
@@ -107,4 +107,4 @@ From a security-model standpoint, this looks **strong and well-documented**:
 - EdDSA with JWKS + optional thumbprint pinning
 - Reasonable claim validation (`iss`, `aud`, `exp`, `nbf`, `iat`)
 
-If you clean up the minor consistency bits (RSA vs not, “decrypt” wording, explicit mention of logging), I’d feel very comfortable shipping this as the public “here’s why you can trust our JWT handling” story for flarelette.
+If you clean up the minor consistency bits (RSA vs not, "decrypt" wording, explicit mention of logging), I’d feel very comfortable shipping this as the public "here’s why you can trust our JWT handling" story for flarelette.

IMPLEMENTATION_SUMMARY.md

@@ -104,7 +104,7 @@ Added exports for all new explicit API functions and types.
 
 ### 4. Documentation
 
-**New Guide:** `docs/explicit-config.md`
+**New Guide:** `docs/user-guide/explicit-config.md`
 
 - Complete API reference
 - Use case examples
@@ -257,7 +257,7 @@ export async function mintToken(c: Context) {
 
 - ✨ **Added:** `packages/flarelette-jwt-ts/src/explicit.ts` (489 lines)
 - ✨ **Added:** `packages/flarelette-jwt-ts/tests/explicit.test.ts` (470 lines)
-- ✨ **Added:** `docs/explicit-config.md` (complete guide)
+- ✨ **Added:** `docs/user-guide/explicit-config.md` (complete guide)
 - ✨ **Added:** `examples/explicit-config-example.ts` (example code)
 - 📝 **Updated:** `packages/flarelette-jwt-ts/src/index.ts` (added exports)
 - 📝 **Updated:** `README.md` (added new API section)

README.md

@@ -18,7 +18,7 @@
 
 **Environment-driven JWT authentication for Cloudflare Workers. Like Starlette, but for the edge.**
 
-Cross-language JWT toolkit (TypeScript + Python) with identical APIs. Automatically selects HS512 or EdDSA based on environment configuration, loads secrets via Cloudflare bindings, and works across Workers, Node.js, and Python runtimes.
+Cross-language JWT toolkit (TypeScript + Python) with identical APIs. Automatically selects HS512 or EdDSA based on environment configuration, and supports ES512 and RSA for external OIDC verification. Loads secrets via Cloudflare bindings and works across Workers, Node.js, and Python runtimes.
 
 ## Part of the Flarelette Ecosystem
 
@@ -88,7 +88,7 @@ const token = await signWithConfig({ sub: 'user123' }, config)
 const payload = await verifyWithConfig(token, config)
 ```
 
-> **New in v1.9.0:** The explicit configuration API eliminates environment setup complexity. See [Explicit Configuration Guide](./docs/explicit-config.md).
+> **New in v1.9.0:** The explicit configuration API eliminates environment setup complexity. See [Explicit Configuration Guide](./docs/user-guide/explicit-config.md).
 
 ### Basic Example (Environment-Based)
 
@@ -145,7 +145,7 @@ Flarelette JWT Kit is designed to prevent common JWT vulnerabilities:
 **Mode selection is driven exclusively by server environment variables:**
 
 - HS512 mode: `algorithms: ['HS512']` only
-- EdDSA/RSA mode: `algorithms: ['EdDSA', 'RS256', 'RS384', 'RS512']` only
+- EdDSA/ECDSA/RSA mode: `algorithms: ['EdDSA', 'ES256', 'ES384', 'ES512', 'RS256', 'RS384', 'RS512']` only
 
 The `alg` header is treated as untrusted input and must match the allowed algorithms for the selected mode. Mismatches are rejected.
 
@@ -239,7 +239,7 @@ When verifying tokens, the library uses the first available key source in this o
 ## Documentation
 
 - **[Getting Started](./docs/getting-started.md)** — Installation, first token, and basic setup
-- **[Explicit Configuration](./docs/explicit-config.md)** 🆕 — No environment setup required! Use config objects directly
+- **[Explicit Configuration](./docs/user-guide/explicit-config.md)** 🆕 — No environment setup required! Use config objects directly
 - **[Core Concepts](./docs/core-concepts.md)** — Algorithms, modes, and architecture
 - **[Usage Guide](./docs/usage-guide.md)** — Complete API reference for TypeScript and Python
 - **[Service Delegation](./docs/service-delegation.md)** — RFC 8693 actor claims for zero-trust
@@ -254,10 +254,12 @@ When verifying tokens, the library uses the first available key source in this o
 npx flarelette-jwt-secret --len=64 --dotenv
 ```
 
-**Generate EdDSA keypairs:**
+**Generate asymmetric keypairs (EdDSA default, or ES256/ES384/ES512):**
 
 ```bash
-npx flarelette-jwt-keygen --kid=ed25519-2025-01
+npx flarelette-jwt-keygen --kid=ed25519-2025-01           # EdDSA (default)
+npx flarelette-jwt-keygen --alg=ES512 --kid=es512-2025-01 # ECDSA P-521
+npx flarelette-jwt-keygen --alg=EdDSA --dotenv            # Output as .env assignments
 ```
 
 ## Contributing

THIRD_PARTY_LICENSES.md

@@ -17,10 +17,9 @@ The TypeScript package depends on the following NPM packages:
 @flarelette/jwt-kit-env@1.8.1
 │ C:\Users\chris\git\flarelette-jwt-kit
 │
-└─┬ @chrislyons-dev/flarelette-jwt@1.12.0 -> .\packages\flarelette-jwt-ts
-  │ Environment-driven JWT authentication for Cloudflare Workers with secret-name indirection
+└─┬ @chrislyons-dev/flarelette-jwt@1.14.0 -> .\packages\flarelette-jwt-ts
+  │
   └── jose@6.1.3
-      JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes
 ```
 
 ---
@@ -77,4 +76,4 @@ This script:
 
 ---
 
-**Last generated**: 2025-12-09
+**Last generated**: 2026-03-05

docs/architecture/.pages

@@ -0,0 +1,4 @@
+nav:
+  - README.md
+  - exclude:
+      - "*.md"

docs/architecture/README.md

@@ -1,7 +1,7 @@
-# 🏗️ flarelette-jwt-kit
+# <img src="../images/archlette-stainedglassA-light.png" alt="" height="28" width="28" style="vertical-align:middle"> flarelette-jwt-kit
 
 **Architecture Documentation**
-Generated 2025-12-08 19:38:11
+Generated 2026-03-05 17:59:12
 
 ## Overview
 
@@ -13,44 +13,25 @@ JWT authentication and authorization library
 
 The system context diagram shows how flarelette-jwt-kit fits into its environment, including external systems and users.
 
-![System Context Diagram](./diagrams/structurizr-SystemContext.png)
+<img src="./diagrams/structurizr-SystemContext.png" alt="System Context Diagram" style="max-width: 100%; height: auto;">
 
 ---
 
 ## Containers
 
 The container diagram shows the high-level technology choices and how containers communicate.
 
-![Container Diagram](./diagrams/structurizr-Containers.png)
-
-<table>
-<thead>
-<tr>
-<th>Container</th>
-<th>Type</th>
-<th>Description</th>
-<th>Details</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td><strong>@chrislyons-dev/flarelette-jwt</strong></td>
-<td><code>Service</code></td>
-<td>Environment-driven JWT authentication for Cloudflare Workers with secret-name indirection</td>
-<td><a href="./chrislyons_dev_flarelette_jwt.md">View →</a></td>
-</tr>
-<tr>
-<td><strong>flarelette-jwt</strong></td>
-<td><code>Service</code></td>
-<td>Environment-driven JWT authentication for Cloudflare Workers Python with secret-name indirection</td>
-<td><a href="./flarelette_jwt.md">View →</a></td>
-</tr>
-</tbody>
-</table>
+<img src="./diagrams/structurizr-Containers.png" alt="Container Diagram" style="max-width: 100%; height: auto;">
+
+| Container | Type | Description | Details |
+| --- | --- | --- | --- |
+| **@chrislyons-dev/flarelette-jwt** | `Service` | TypeScript implementation of the Flarelette JWT Kit: An environment-driven JWT authentication package for Cloudflare Workers | [View](./chrislyons_dev_flarelette_jwt.md) |
+| **flarelette-jwt** | `Service` | Python implementation of the Flarelette JWT Kit: An environment-driven JWT authentication package for Cloudflare Workers | [View](./flarelette_jwt.md) |
 
 
 ---
 
 <div align="center">
 <sub>Generated with <a href="https://github.com/chrislyons-dev/archlette">Archlette</a> Architecture-as-Code toolkit</sub>
 </div>
+

docs/architecture/chrislyons_dev_flarelette_jwt.md

@@ -6,143 +6,43 @@
 
 ## Container Context
 
-![Container Diagram](./diagrams/structurizr-Containers.png)
+<img src="./diagrams/structurizr-Containers.png" alt="Container Diagram" style="max-width: 100%; height: auto;">
 
 ---
 
 ## Container Information
 
-<table>
-<tbody>
-<tr>
-<td><strong>Name</strong></td>
-<td>@chrislyons-dev/flarelette-jwt</td>
-</tr>
-<tr>
-<td><strong>Type</strong></td>
-<td><code>Service</code></td>
-</tr>
-<tr>
-<td><strong>Description</strong></td>
-<td>Environment-driven JWT authentication for Cloudflare Workers with secret-name indirection</td>
-</tr>
-<tr>
-<td><strong>Tags</strong></td>
-<td><code>Auto-generated</code></td>
-</tr>
-</tbody>
-</table>
-
+| Field | Value |
+| --- | --- |
+| **Name** | @chrislyons-dev/flarelette-jwt |
+| **Type** | `Service` |
+| **Description** | TypeScript implementation of the Flarelette JWT Kit: An environment-driven JWT authentication package for Cloudflare Workers || **Tags** | `Auto-generated` |
 ---
 
 ## Components
 
 
 ### Component View
 
-![Component Diagram](./diagrams/structurizr-Components__chrislyons_dev_flarelette_jwt.png)
+<img src="./diagrams/structurizr-Components__chrislyons_dev_flarelette_jwt.png" alt="Component Diagram" style="max-width: 100%; height: auto;">
 
 ### Component Details
 
-<table>
-<thead>
-<tr>
-<th>Component</th>
-<th>Type</th>
-<th>Description</th>
-<th>Code</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td><strong>core</strong></td>
-<td><code>module</code></td>
-<td>CLI utility for generating JWT secrets.
-
-This script provides options to generate secrets in various formats, including JSON and dotenv.
-It is designed to be executed as a standalone Node.js script. | Configuration utilities for JWT operations.
-
-This module provides functions to read environment variables and derive JWT-related configurations.
-It includes support for both symmetric (HS512) and asymmetric (EdDSA) algorithms. | JWT signing utilities.
-
-This module provides functions to sign JWT tokens using either HS512 or EdDSA algorithms.
-It supports custom claims and configuration overrides.</td>
-<td><a href="./chrislyons_dev_flarelette_jwt__core.md">View →</a></td>
-</tr>
-<tr>
-<td><strong>explicit</strong></td>
-<td><code>module</code></td>
-<td>Explicit configuration API for JWT operations.
-
-This module provides functions that accept explicit configuration objects
-instead of relying on environment variables or global state. Use this API
-when you need full control over configuration, especially in development
-environments or when working with multiple JWT configurations.</td>
-<td><a href="./chrislyons_dev_flarelette_jwt__explicit.md">View →</a></td>
-</tr>
-<tr>
-<td><strong>util</strong></td>
-<td><code>module</code></td>
-<td>High-level JWT utilities for creating, delegating, verifying, and authorizing JWT tokens | Key generation utility for EdDSA keys.
-
-This script generates EdDSA key pairs and exports them in JWK format.
-It is designed to be executed as a standalone Node.js script. | Secret generation and validation utilities.
-
-This module provides functions to generate secure secrets and validate base64url-encoded secrets.
-It ensures compatibility with JWT signing requirements. | Utility functions for JWT operations.
-
-This module provides helper functions for parsing JWTs, checking expiration, and mapping OAuth scopes.
-It is designed to support core JWT functionalities.</td>
-<td><a href="./chrislyons_dev_flarelette_jwt__util.md">View →</a></td>
-</tr>
-<tr>
-<td><strong>main</strong></td>
-<td><code>module</code></td>
-<td>Entry point for the flarelette-jwt library.
-
-This module re-exports core functionalities, including signing, verification, utilities, and type definitions.
-It serves as the main interface for library consumers.</td>
-<td><a href="./chrislyons_dev_flarelette_jwt__main.md">View →</a></td>
-</tr>
-<tr>
-<td><strong>jwks</strong></td>
-<td><code>module</code></td>
-<td>JSON Web Key Set (JWKS) utilities.
-
-This module provides functions to fetch and manage JWKS, including caching and key lookup by key ID (kid).
-It supports integration with external JWKS services.</td>
-<td><a href="./chrislyons_dev_flarelette_jwt__jwks.md">View →</a></td>
-</tr>
-<tr>
-<td><strong>types</strong></td>
-<td><code>module</code></td>
-<td>Type definitions for JWT operations.
-
-This module defines types for JWT headers, payloads, profiles, and related structures.
-It ensures type safety and consistency across the library.</td>
-<td><a href="./chrislyons_dev_flarelette_jwt__types.md">View →</a></td>
-</tr>
-<tr>
-<td><strong>verify</strong></td>
-<td><code>module</code></td>
-<td>JWT verification utilities.
-
-This module provides functions to verify JWT tokens using either HS512 or EdDSA algorithms.
-It supports integration with JWKS services and thumbprint pinning.</td>
-<td><a href="./chrislyons_dev_flarelette_jwt__verify.md">View →</a></td>
-</tr>
-<tr>
-<td><strong>adapters</strong></td>
-<td><code>module</code></td>
-<td>Component inferred from directory: adapters</td>
-<td><a href="./chrislyons_dev_flarelette_jwt__adapters.md">View →</a></td>
-</tr>
-</tbody>
-</table>
+| Component | Type | Description | Code |
+| --- | --- | --- | --- |
+| **core** | `module` | CLI utility for generating JWT secrets.<br><br>This script provides options to generate secrets in various formats, including JSON and dotenv.<br>It is designed to be executed as a standalone Node.js script. \| Configuration utilities for JWT operations.<br><br>This module provides functions to read environment variables and derive JWT-related configurations.<br>It includes support for both symmetric (HS512) and asymmetric (EdDSA) algorithms. \| JWT signing utilities.<br><br>This module provides functions to sign JWT tokens using either HS512 or EdDSA algorithms.<br>It supports custom claims and configuration overrides. | [View](./chrislyons_dev_flarelette_jwt__core.md) |
+| **explicit** | `module` | Explicit configuration API for JWT operations.<br><br>This module provides functions that accept explicit configuration objects<br>instead of relying on environment variables or global state. Use this API<br>when you need full control over configuration, especially in development<br>environments or when working with multiple JWT configurations. | [View](./chrislyons_dev_flarelette_jwt__explicit.md) |
+| **util** | `module` | High-level JWT utilities for creating, delegating, verifying, and authorizing JWT tokens \| Key generation utility for EdDSA and ECDSA keys.<br><br>Generates asymmetric key pairs and exports them in JWK format.<br>Designed to be executed as a standalone Node.js script. \| Secret generation and validation utilities.<br><br>This module provides functions to generate secure secrets and validate base64url-encoded secrets.<br>It ensures compatibility with JWT signing requirements. \| Utility functions for JWT operations.<br><br>This module provides helper functions for parsing JWTs, checking expiration, and mapping OAuth scopes.<br>It is designed to support core JWT functionalities. | [View](./chrislyons_dev_flarelette_jwt__util.md) |
+| **main** | `module` | Entry point for the flarelette-jwt library.<br><br>This module re-exports core functionalities, including signing, verification, utilities, and type definitions.<br>It serves as the main interface for library consumers. | [View](./chrislyons_dev_flarelette_jwt__main.md) |
+| **jwks** | `module` | JSON Web Key Set (JWKS) utilities.<br><br>This module provides functions to fetch and manage JWKS, including caching and key lookup by key ID (kid).<br>It supports integration with external JWKS services. | [View](./chrislyons_dev_flarelette_jwt__jwks.md) |
+| **types** | `module` | Type definitions for JWT operations.<br><br>This module defines types for JWT headers, payloads, profiles, and related structures.<br>It ensures type safety and consistency across the library. | [View](./chrislyons_dev_flarelette_jwt__types.md) |
+| **verify** | `module` | JWT verification utilities.<br><br>This module provides functions to verify JWT tokens using either HS512 or EdDSA algorithms.<br>It supports integration with JWKS services and thumbprint pinning. | [View](./chrislyons_dev_flarelette_jwt__verify.md) |
+| **adapters** | `module` | Component inferred from directory: adapters | [View](./chrislyons_dev_flarelette_jwt__adapters.md) |
 
 
 ---
 
 <div align="center">
 <sub><a href="./README.md">← Back to System Overview</a> | Generated with <a href="https://github.com/chrislyons-dev/archlette">Archlette</a></sub>
 </div>
+