@hawcx/oauth-client 4.0.1 → 5.2.0

package/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.2.0] - 2026-06-26
+
+### Added — Management API authentication via `private_key_jwt` (Path A)
+
+- **`StepUpClient.withPrivateKeyJwt(...)`** — authenticate `/v1/management/*`
+  (step-up, MFA enforcement, phone-number changes) with a per-request EdDSA
+  Bearer JWT: `iss` = `sub` = `clientId`, `aud` = the full endpoint URL, ~60s
+  `exp`, random `jti`, and a `body_sha256` claim binding the JWT to the exact
+  request body bytes. Reuses the same Ed25519 OIDC `private_key_jwt` signing key
+  already registered in the admin console — one key, standards-based (RFC 7523),
+  no ECIES credential blob required. Tenant routing uses the `X-Config-Id`
+  header. Options include `timeoutSeconds` (default 15) and `jwtTtlSeconds`
+  (default 60).
+- **`JwtBearerTransport`** — the transport backing the Path A client. Responses
+  carry an `X-Response-Signature` (ES256) which callers **may** verify against
+  the OIDC JWKS they already trust (optional, customer-side per the Path A spec).
+
+### Changed
+
+- The ECIES factories **`StepUpClient.fromSecretKey(...)` / `fromKeys(...)`**
+  (the proprietary `hwx_sk_v1_…` blob) are now **deprecated** — they emit a
+  one-time `DeprecationWarning` but remain fully functional and will only be
+  removed in a future major version.
+
+### Migration (ECIES → `private_key_jwt`)
+
+Existing ECIES integrations keep working unchanged; adopting `private_key_jwt`
+is opt-in (spec §10.3):
+
+1. Register your Ed25519 `private_key_jwt` public key in the Admin Console
+   (OAuth tab → **Client authentication**) — the same key used for OIDC login.
+2. Switch the project's Management API auth to **Migrating** (accepts both
+   `ecies` and `jwt`) so existing and new callers coexist during rollout.
+3. Replace `StepUpClient.fromSecretKey(...)` / `fromKeys(...)` with
+   `StepUpClient.withPrivateKeyJwt({ baseUrl, configId, clientId, oidcSigningKey, kid })`.
+4. Once every caller uses `private_key_jwt`, move the project to **Signed
+   tokens** (`jwt` only). ECIES EOL date: TBA (removed no earlier than the next
+   major version).
+
+### Hardening
+
+- `JwtBearerTransport` now bounds every request with a timeout (`timeoutSeconds`,
+  default 15) via an `AbortController`, so a connected-but-silent server can no
+  longer hang the call or exhaust connection pools. Mirrors the ECIES
+  `DelegationTransport`.
+- The HTTP status is now checked **before** parsing the response body, so a
+  non-JSON error body (e.g. a WAF/proxy HTML 403) surfaces its HTTP status as a
+  `DelegationRequestError` instead of being masked as a JSON parse failure.
+
+## [5.1.0] - 2026-06-13
+
+> The `private_key_jwt` / `ClientAssertionSigner` surface is **experimental** (`@beta`)
+> and may change before it is marked stable.
+
+### Cross-SDK consistency
+
+- Added `HawcxError` as the canonical root exception (aligns with Java/Python);
+  `HawcxOAuthError` now extends it (back-compat — catch either).
+- Added a shared **golden test vector** (`tests/fixtures/golden-assertion.json`,
+  byte-identical across the three SDKs) pinning the assertion header/claims/signature
+  for a fixed key.
+- Added `refreshJwks()` as the canonical JWKS-cache reset (aligns with the Java
+  `refreshJwks()` / Python `refresh_jwks()` SDKs). `clearCache()` is now
+  **deprecated** (passthrough; one-time `console.warn`) and will be removed in 6.0.0.
+
+### Production-readiness hardening
+
+- `ClientAssertionSigner` no longer memoizes a *rejected* key import — a transient/
+  structural import failure no longer permanently poisons the signer.
+- `jti` now sourced from `node:crypto` `randomUUID` (explicit import; was the
+  `globalThis.crypto` global).
+- `withClientAssertion` refuses to attach a signer when the OP's discovery doc
+  advertises `token_endpoint_auth_methods_supported` without `private_key_jwt`
+  (prevents a silent downgrade to public-client).
+- `withClientAssertion` is now **immutable** — returns a *new* configured client
+  (the backing `clientAssertionSigner` field is `readonly`) rather than mutating
+  in place. Chained usage (`(await fromIssuer(...)).withClientAssertion(...)`) is
+  unaffected; callers relying on in-place mutation of the original must use the
+  return value.
+- `ClientAssertionSigner` gains `ed25519FromPem(pkcs8Pem, kid)` and
+  `ed25519(keyObject, kid)` factories (parity with the Java SDK).
+- Replaced the `expectedAudience ?? ''` dead-code fallback with a non-null assertion.
+
+### Added
+
+- **`private_key_jwt` client authentication** (RFC 7523 / OIDC Core §9). New
+  `ClientAssertionSigner.ed25519FromJwk(...)` + `HawcxOAuth.withClientAssertion(signer)`
+  (discovery mode). When set, `exchangeCode` signs and attaches a `client_assertion`
+  (EdDSA/Ed25519 only) alongside PKCE; `aud` is the discovered `token_endpoint`.
+  Without a signer, the request is unchanged (public-client + PKCE).
+- `exchangeCode` gains an optional 4th `expectedNonce` argument, threaded to verification.
+
+### Changed / hardened
+
+- **https required** on the issuer, `token_endpoint`, and `jwks_uri` (loopback http
+  still allowed for local dev/tests) — an http issuer let an on-path attacker swap
+  the discovery document.
+- **Nonce**: verification now refuses an id_token that carries a `nonce` when none
+  was supplied to verify against (OIDC Core §3.1.3.7), instead of silently skipping it.
+- **`exp` and `iat` required** in discovery mode — a token with no `exp` (never-expiring)
+  or no `iat` (no issuance anchor) is rejected.
+- **Structured error fields** on the `HawcxOAuthError` hierarchy: new
+  `HawcxOAuthErrorFields` carrying optional `error` / `errorDescription`. The
+  token-endpoint error path now populates these from the OAuth `error` /
+  `error_description` body so callers can dispatch on a stable code without parsing
+  the message string (the message string composition is unchanged for back-compat).
+- JWKS fetch timeout pinned explicitly; token-exchange error bodies that aren't JSON
+  are preserved in the error message; negative `clockToleranceSeconds` rejected.
+
+## [5.0.0] - 2026-05-23
+
+OIDC discovery support. The legacy `new HawcxOAuth({ configId, baseUrl })`
+constructor is unchanged at the signature level — but verification gains a
+default 10-second clock-tolerance window (see `clockToleranceSeconds`
+below). Apps that depend on strict zero-skew validation should pass
+`clockToleranceSeconds: 0`.
+
+### Added
+
+#### OIDC discovery construction path
+
+- `HawcxOAuth.fromIssuer({ issuer, configId, clientId })` — static async
+  factory that fetches `<issuer>/.well-known/openid-configuration` once at
+  startup (5s default timeout) and wires a verifier that enforces signature
+  + `iss` + `aud` + `exp` + `nbf` on every subsequent `verifyToken` call.
+  The legacy path verifies the signature only.
+
+  **`configId` vs `clientId`.** Hawcx separates the tenant routing key from
+  the audience claim, and the SDK forwards each to the right place:
+  - `configId` — sent as `X-Config-Id` on the token-exchange POST (opaque
+    tenant routing key)
+  - `clientId` — the value the tenant has configured (in the Hawcx admin
+    console) as the `aud` claim on issued id_tokens. The verifier matches
+    the token's `aud` against this exact string.
+
+  Passing the same value for both fails verification with
+  `Unexpected JWT audience` unless the tenant happens to configure them
+  identically.
+
+- `HawcxOAuth.prototype.exchangeCode(code, codeVerifier, redirectUri?)` —
+  new optional third argument. If your authorization request registered a
+  `redirect_uri`, RFC 6749 §4.1.3 requires the token request to carry the
+  same value. Omit for flows that didn't include it.
+
+- `HawcxOAuth.prototype.verifyToken(token, { nonce })` — new options object
+  with optional `nonce` field for callers who bind a nonce to the
+  authorization request. Has no effect in legacy mode.
+
+- `HawcxOAuth.prototype.discoveryMetadata` — the resolved OIDC discovery
+  document. `null` on legacy clients; useful for diagnostics ("which
+  token endpoint did we resolve to?", "what signing algorithms?").
+
+- `clockToleranceSeconds` option on both `HawcxOAuthConfig` (legacy) and
+  `HawcxOAuthIssuerConfig` (discovery) — tolerated clock skew in seconds
+  when verifying `exp` and `nbf`. Spec.md §3.3 mandates this knob with a
+  recommended default of 10 seconds, which the SDK now applies. Without
+  it, jose's default of 0 rejected tokens minted under normal NTP drift
+  between issuer and verifier — the root cause of the
+  `exchangeCodeTolerant` workaround in `hawcx_admin_console` pre-5.0.
+  Pass `clockToleranceSeconds: 0` to opt back into strict exact-time
+  validation; raise above 10 if drift on your hosts is wider than that.
+
+- **Algorithm allowlist (spec.md §3.3) — discovery mode.** `fromIssuer`
+  now intersects the issuer's advertised
+  `id_token_signing_alg_values_supported` with a closed SDK allowlist
+  (`{RS256, ES256, ES384, ES512, EdDSA}`). If no advertised alg is in
+  the allowlist, `DiscoveryError` is thrown at construction time. The
+  intersection is then passed to `jose.jwtVerify`'s `algorithms` option
+  on every `verifyToken` call, so verify-time enforcement matches what
+  was resolved at construction — forecloses key-confusion /
+  alg-substitution where the JWKS happens to serve a key type matching
+  whatever the JWT header claims. Mirrors the Java SDK
+  (`JwtVerifier.DEFAULT_ALGORITHMS`). Legacy mode behavior is unchanged
+  (no closed allowlist, no `algorithms:` constraint — same as 4.x).
+
+- `DiscoveryError` — new error class for discovery-resolution failures
+  (DNS / TLS / network failure, non-2xx response, malformed JSON, missing
+  required fields). Underlying cause is preserved as `err.cause`.
+
+- New exported types: `HawcxOAuthIssuerConfig`, `DiscoveryMetadata`,
+  `VerifyTokenOptions`.
+
+### Changed
+
+- `TokenVerificationError.message` now distinguishes audience / issuer
+  mismatches from generic signature failures by parsing jose's
+  `ERR_JWT_CLAIM_VALIDATION_FAILED` code. Code that pattern-matched on
+  the legacy "Invalid signature" message still sees it for signature
+  failures; new "Unexpected JWT audience" / "Unexpected JWT issuer"
+  messages are now used when those specific claims fail.
+
+- `exchangeCode` now sets `grant_type=authorization_code` on the form body.
+  4.x callers won't notice — the OAuth server already inferred the grant
+  type from the presence of `code`. Listed here for completeness.
+
+### Notes for upgraders
+
+If you only construct via `new HawcxOAuth({ configId })`, nothing changes —
+the legacy path is signature-only verification, same as 4.x. If you want
+proper `aud`/`iss` enforcement, switch to `await HawcxOAuth.fromIssuer(...)`
+and pass both `configId` and `clientId` from the admin console.
+
+## [0.2.0] - 2024-11-20
+
+### Breaking Changes
+- **BREAKING**: `apiKey` parameter is now required in `exchangeCodeForClaims()` and `exchangeCodeForTokenAndClaims()`
+- **BREAKING**: At least one of `publicKey` or `jwksUrl` must be provided for JWT verification
+
+### Added
+- Validation to ensure `apiKey` is provided and non-empty
+- Validation to ensure at least one of `publicKey` or `jwksUrl` is provided
+- Clear error messages for missing required parameters
+- Priority logic: `jwksUrl` takes precedence over `publicKey` when both are provided
+
+### Changed
+- Updated all documentation and examples to use `jwksUrl` as the primary recommended method
+- Updated demo application to include `apiKey` parameter
+- Improved error messages for parameter validation
+
+### Fixed
+- Ensures API key is always sent with OAuth token exchange requests
+- Prevents authentication failures due to missing API key
+
+## [0.1.0] - 2024-01-XX
+
+### Added
+- Initial release of Node.js/TypeScript OAuth client SDK
+- OAuth authorization code exchange with PKCE support
+- JWT verification with RS256, ES256/384/512, and EdDSA algorithms
+- Comprehensive error handling with custom exception classes
+- Hawcx delegation client for MFA setup and management
+- ECIES (X25519 + AES-GCM) encryption for secure backend-to-backend communication
+- Ed25519 and RSA-PSS signing support
+- Full TypeScript type definitions
+- Comprehensive documentation and examples
+- Feature parity with Python SDK
+
+### Features
+- 🔐 Secure JWT verification with configurable validation
+- 🆕 Native PKCE (RFC 7636) support
+- 🚀 Simple, async/await API
+- 🎯 High-level Hawcx client with automatic encryption/signing
+- 🛡️ Comprehensive error handling
+- 📝 Full TypeScript support
+- 🔧 Framework-agnostic (works with Express, Fastify, etc.)
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Hawcx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -4,6 +4,7 @@ Simple, production-ready OAuth client SDK for Hawcx authentication.
 
 ## Features
 
+- **OIDC Discovery** - `HawcxOAuth.fromIssuer(...)` resolves endpoints from `/.well-known/openid-configuration` and enforces signature + `iss` + `aud` + `exp` + `nbf` on verify
 - **Simple JWT Verification** - Uses `jose` library for automatic JWKS caching and signature handling
 - **PKCE Support** - Native PKCE (RFC 7636) support for enhanced OAuth security
 - **Delegation API** - Server-to-server user management (MFA, devices)
@@ -17,19 +18,89 @@ Simple, production-ready OAuth client SDK for Hawcx authentication.
 npm install @hawcx/oauth-client
 ```
 
-## Quick Start
+## Quick Start (OIDC discovery, recommended)
+
+`HawcxOAuth.fromIssuer(...)` does the discovery fetch once at startup and
+gives you a client whose `exchangeCode` + `verifyToken` enforce all the
+standard OIDC claim checks. Construct once and reuse.
 
 ```typescript
 import { HawcxOAuth } from '@hawcx/oauth-client';
 
-const oauth = new HawcxOAuth({ configId: 'your-config-id' });
+const oauth = await HawcxOAuth.fromIssuer({
+  issuer: 'https://api.hawcx.com',        // → discovery + expected `iss`
+  configId: process.env.HAWCX_CONFIG_ID!, // → X-Config-Id header
+  clientId: process.env.HAWCX_CLIENT_ID!, // → expected `aud` on id_tokens
+});
 
-// Exchange authorization code for tokens
 const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
 console.log(claims.sub);   // user ID
 console.log(claims.email); // user email
 ```
 
+> **`configId` vs `clientId` — they are different values.**
+> Hawcx separates the tenant routing key from the audience claim:
+>
+> - **`configId`** — the per-tenant config identifier. Sent as the
+>   `X-Config-Id` header on the token-exchange POST so the OAuth server
+>   can look up the tenant.
+> - **`clientId`** — the value the tenant has configured (in the Hawcx
+>   admin console) as the `aud` claim on issued id_tokens. The verifier
+>   matches the token's `aud` against this exact string.
+>
+> Passing the same value for both fails verification with
+> `Unexpected JWT audience` unless your tenant happens to use identical
+> strings.
+
+## Quick Start (legacy)
+
+The legacy single-arg constructor still works for backward compatibility
+with 4.x callers. It verifies the JWT signature only — `iss` and `aud`
+are not checked. Prefer `fromIssuer` for new code.
+
+```typescript
+import { HawcxOAuth } from '@hawcx/oauth-client';
+
+const oauth = new HawcxOAuth({ configId: 'your-config-id' });
+
+const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
+```
+
+---
+
+## Confidential clients (`private_key_jwt`)
+
+If your project is registered in the Hawcx admin console with **Client
+authentication = Signing key (`private_key_jwt`)**, attach an Ed25519 signer.
+The SDK then signs an RFC 7523 `client_assertion` on every token exchange
+(PKCE is still sent). Public clients omit this and keep using PKCE only.
+
+```typescript
+import { HawcxOAuth, ClientAssertionSigner } from '@hawcx/oauth-client';
+
+const privateJwk = JSON.parse(process.env.HAWCX_PRIVATE_JWK!); // OKP/Ed25519, with kid
+
+const oauth = (
+  await HawcxOAuth.fromIssuer({
+    issuer: 'https://dev-demo-api.hawcx.com',
+    configId: process.env.HAWCX_CONFIG_ID!,
+    clientId: process.env.HAWCX_CLIENT_ID!,
+  })
+).withClientAssertion(ClientAssertionSigner.ed25519FromJwk(privateJwk));
+
+const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
+```
+
+The private key must be Ed25519 (`kty: 'OKP', crv: 'Ed25519'`, with a `kid`);
+its public JWK is what you register in the admin console. The assertion's `aud`
+is the discovered `token_endpoint`, and EdDSA is the only accepted algorithm.
+`clientId` must be the confidential client's id — it becomes the assertion
+`iss`/`sub` and the id_token `aud`.
+
+> If you bound a `nonce` at `/authorize`, pass it as the 4th argument to
+> `exchangeCode(code, verifier, redirectUri?, expectedNonce)` — verification
+> refuses a nonce-bearing token when none is supplied (OIDC Core §3.1.3.7).
+
 ---
 
 ## Modules
@@ -46,21 +117,45 @@ console.log(claims.email); // user email
 
 Core module for OAuth 2.1 + PKCE authentication.
 
-### `HawcxOAuth`
+### Construction
+
+#### Discovery mode (recommended)
 
 ```typescript
 import { HawcxOAuth } from '@hawcx/oauth-client';
 
+const oauth = await HawcxOAuth.fromIssuer({
+  issuer: 'https://api.hawcx.com',     // Required: discovery + expected `iss`
+  configId: 'your-config-id',          // Required: X-Config-Id header
+  clientId: 'your-client-id',          // Required: expected `aud` on id_tokens
+  timeout: 10000,                       // Optional: per-request timeout in ms
+  discoveryTimeout: 5000,               // Optional: discovery fetch timeout in ms
+});
+
+oauth.discoveryMetadata; // resolved OIDC discovery doc, for diagnostics
+```
+
+Throws `DiscoveryError` if the discovery document is unreachable, returns
+non-2xx, isn't valid JSON, or is missing any of `token_endpoint`,
+`jwks_uri`, `id_token_signing_alg_values_supported`.
+
+#### Legacy mode
+
+```typescript
 const oauth = new HawcxOAuth({
-  configId: 'your-config-id',        // Required: Your Hawcx config ID
-  baseUrl: 'https://api.hawcx.com',  // Optional: API base URL
-  timeout: 10000,                     // Optional: Request timeout in ms
+  configId: 'your-config-id',        // Required
+  baseUrl: 'https://api.hawcx.com',  // Optional: defaults to api.hawcx.com
+  timeout: 10000,                     // Optional
 });
 ```
 
+Hits the fixed endpoints `<baseUrl>/oauth2/token` and `<baseUrl>/keys`
+directly. **Signature-only verification** — `iss` and `aud` are not
+checked. Kept for backward compatibility with 4.x callers.
+
 ### Methods
 
-#### `exchangeCode(code, codeVerifier): Promise<ExchangeResult>`
+#### `exchangeCode(code, codeVerifier, redirectUri?): Promise<ExchangeResult>`
 
 Exchange an authorization code for tokens.
 
@@ -69,6 +164,13 @@ const { idToken, claims } = await oauth.exchangeCode(
   'authorization-code',
   'pkce-code-verifier'
 );
+
+// With redirect_uri (RFC 6749 §4.1.3) when your auth request registered one:
+const { idToken, claims } = await oauth.exchangeCode(
+  'authorization-code',
+  'pkce-code-verifier',
+  'https://app.example.com/auth/callback'
+);
 ```
 
 **Returns:**
@@ -79,12 +181,16 @@ interface ExchangeResult {
 }
 ```
 
-#### `verifyToken(token): Promise<JwtClaims>`
+#### `verifyToken(token, options?): Promise<JwtClaims>`
 
-Verify an existing JWT token.
+Verify an existing JWT token. In discovery mode, enforces signature + `iss` +
+`aud` + `exp` + `nbf`. In legacy mode, only the signature is checked.
 
 ```typescript
 const claims = await oauth.verifyToken(idToken);
+
+// With expected nonce (useful for flows that bind a nonce to the auth request):
+const claims = await oauth.verifyToken(idToken, { nonce: 'expected-nonce' });
 ```
 
 **Returns:**
@@ -99,34 +205,46 @@ interface JwtClaims {
   name?: string;           // User name
   amr?: string[];          // Authentication methods
   mfa_method?: string;     // MFA method used
+  nonce?: string;          // Nonce (if bound)
 }
 ```
 
-#### `clearCache(): void`
+#### `refreshJwks(): void`
 
-Clear the JWKS cache (useful for testing or key rotation).
+Reset the JWKS cache so the next verification refetches keys (useful for testing
+or key rotation).
 
 ```typescript
-oauth.clearCache();
+oauth.refreshJwks();
 ```
 
+> **Deprecated:** `clearCache()` is a deprecated passthrough that calls
+> `refreshJwks()` (and emits a one-time `console.warn`). It still works but will be
+> removed in 6.0.0 — prefer `refreshJwks()`.
+
 ### Errors
 
 ```typescript
 import {
   HawcxOAuthError,        // Base error class
+  DiscoveryError,         // OIDC discovery resolution failed (fromIssuer only)
   TokenExchangeError,     // Code exchange failed
   TokenVerificationError  // JWT verification failed
 } from '@hawcx/oauth-client';
 
 try {
+  const oauth = await HawcxOAuth.fromIssuer({ issuer, configId, clientId });
   await oauth.exchangeCode(code, verifier);
 } catch (error) {
+  if (error instanceof DiscoveryError) {
+    console.log(error.cause); // original network / parse error
+  }
   if (error instanceof TokenExchangeError) {
     console.log(error.statusCode); // HTTP status code
   }
   if (error instanceof TokenVerificationError) {
-    console.log(error.message); // "Token expired", "Invalid signature", etc.
+    // "Token expired", "Invalid signature", "Unexpected JWT audience: ...", etc.
+    console.log(error.message);
   }
 }
 ```
@@ -332,22 +450,35 @@ try {
 
 For step-up authentication flows (e.g., changing MFA method requires re-authentication).
 
-### `StepUpClient`
+### `StepUpClient` (recommended: `withPrivateKeyJwt`)
+
+`StepUpClient.withPrivateKeyJwt` is the recommended construction path. It reuses
+the same Ed25519 `private_key_jwt` signing key already registered in the Hawcx admin
+console for OIDC — one standards-based key, no separate credential blob required.
 
 ```typescript
 import { StepUpClient } from '@hawcx/oauth-client';
 
-const stepUp = StepUpClient.fromSecretKey({
+const privateJwk = JSON.parse(process.env.HAWCX_PRIVATE_JWK!); // OKP/Ed25519, with kid
+
+const stepUp = StepUpClient.withPrivateKeyJwt({
   baseUrl: 'https://api.hawcx.com',
-  secretKey: process.env.HAWCX_SECRET_KEY!,
-  relyingParty: 'your-app.com',       // Required
-  apiKey: 'optional-api-key',          // Optional
-  apiPrefix: '/v1',                    // Optional (default: '/v1')
-  timeoutSeconds: 15,                  // Optional
-  clockSkewSeconds: 300,               // Optional
+  configId: process.env.HAWCX_CONFIG_ID!,   // X-Config-Id tenant routing
+  clientId: process.env.HAWCX_CLIENT_ID!,   // iss/sub in per-request JWT
+  oidcSigningKey: privateJwk,               // same key as ClientAssertionSigner
+  kid: privateJwk.kid,
+  relyingParty: 'your-app.com',            // Optional
+  apiKey: 'optional-api-key',              // Optional
+  apiPrefix: '/v1',                        // Optional (default: '/v1')
 });
 ```
 
+The signing key must be Ed25519 (`kty: 'OKP', crv: 'Ed25519'`). It accepts a JWK
+object, a PKCS#8 PEM string, or a pre-imported jose `KeyLike`.
+
+Each request is signed with a short-lived per-request EdDSA JWT whose `aud` is the
+full request URL and whose `body_sha256` claim covers the exact bytes sent.
+
 ### Methods
 
 #### `stepUp.startToken(options): Promise<StepUpStartTokenResponse>`
@@ -394,6 +525,23 @@ interface StepUpConsumeResponse {
 }
 ```
 
+### Legacy (deprecated): `fromSecretKey`
+
+`StepUpClient.fromSecretKey` and `StepUpClient.fromKeys` are deprecated since 5.2.0
+and will be removed in a future major version. They use a proprietary ECIES credential
+format. Migrate to `withPrivateKeyJwt`.
+
+```typescript
+// DEPRECATED — migrate to withPrivateKeyJwt above
+import { StepUpClient } from '@hawcx/oauth-client';
+
+const stepUp = StepUpClient.fromSecretKey({
+  baseUrl: 'https://api.hawcx.com',
+  secretKey: process.env.HAWCX_SECRET_KEY!,  // hwx_sk_v1_… blob
+  relyingParty: 'your-app.com',
+});
+```
+
 ---
 
 ## Examples
@@ -477,9 +625,14 @@ async function revokeAllDevices(userId: string) {
 ```typescript
 import { StepUpClient, DelegationClient, MfaMethod } from '@hawcx/oauth-client';
 
-const stepUp = StepUpClient.fromSecretKey({
+const privateJwk = JSON.parse(process.env.HAWCX_PRIVATE_JWK!);
+
+const stepUp = StepUpClient.withPrivateKeyJwt({
   baseUrl: process.env.HAWCX_API_URL!,
-  secretKey: process.env.HAWCX_SECRET_KEY!,
+  configId: process.env.HAWCX_CONFIG_ID!,
+  clientId: process.env.HAWCX_CLIENT_ID!,
+  oidcSigningKey: privateJwk,
+  kid: privateJwk.kid,
   relyingParty: 'myapp.com',
 });
 
@@ -551,7 +704,7 @@ The SDK automatically caches JWKS (JSON Web Key Set) for JWT verification:
 - Keys are fetched lazily on first `verifyToken()` call
 - Cached in memory for the lifetime of the `HawcxOAuth` instance
 - Auto-refreshes if a key ID isn't found (handles key rotation)
-- Call `clearCache()` to force a refresh
+- Call `refreshJwks()` to force a refresh (`clearCache()` is a deprecated alias — see above)
 
 ```typescript
 // Keys fetched once, cached thereafter
@@ -560,7 +713,7 @@ const claims2 = await oauth.verifyToken(token2); // Uses cache
 const claims3 = await oauth.verifyToken(token3); // Uses cache
 
 // Force refresh if needed
-oauth.clearCache();
+oauth.refreshJwks();
 const claims4 = await oauth.verifyToken(token4); // Fetches JWKS again
 ```
 

package/dist/client-assertion.d.ts

@@ -0,0 +1,45 @@
+import type { KeyObject } from 'node:crypto';
+import { type JWK } from 'jose';
+/** RFC 7523 §2.2 assertion type for the `private_key_jwt` method. */
+export declare const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+export declare class ClientAssertionSigner {
+    private readonly importKeyFn;
+    private readonly kid;
+    private readonly lifetimeSeconds;
+    /** Lazily-imported signing key, memoised across sign() calls. */
+    private keyPromise?;
+    private constructor();
+    /**
+     * Build a signer from an Ed25519 *private* JWK (RFC 8037):
+     * `{ kty: 'OKP', crv: 'Ed25519', d, x, kid }`. The `kid` is read from the
+     * JWK. This is the canonical Hawcx key format (what the admin console
+     * generates/downloads). Accepts either a JWK object or its JSON string.
+     */
+    static ed25519FromJwk(privateJwk: JWK | string): ClientAssertionSigner;
+    /**
+     * Build a signer from a PKCS#8 PEM-encoded Ed25519 private key plus its `kid`.
+     * The key type is validated (must be Ed25519) on first use.
+     */
+    static ed25519FromPem(pkcs8Pem: string, kid: string): ClientAssertionSigner;
+    /**
+     * Build a signer from an already-loaded Ed25519 private `KeyObject`
+     * (e.g. from `crypto.createPrivateKey(...)`) plus its `kid`.
+     */
+    static ed25519(privateKey: KeyObject, kid: string): ClientAssertionSigner;
+    /**
+     * Return a copy of this signer using `seconds` as the assertion lifetime
+     * (iat→exp). Clamped to [1, 120] (the OP maximum). Defaults to 60; most
+     * callers never need this.
+     */
+    withLifetimeSeconds(seconds: number): ClientAssertionSigner;
+    private importKey;
+    /**
+     * Build and Ed25519-sign the `client_assertion` JWT for one token exchange.
+     *
+     * @param clientId - becomes `iss` and `sub` (RFC 7523 §3)
+     * @param audience - the OP's token endpoint, exactly as advertised in
+     *   discovery (the OP pins `aud` to that string)
+     */
+    sign(clientId: string, audience: string): Promise<string>;
+}
+//# sourceMappingURL=client-assertion.d.ts.map

package/dist/client-assertion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-assertion.d.ts","sourceRoot":"","sources":["../src/client-assertion.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAmC,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAKjE,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,2DACwB,CAAC;AAK3D,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,iEAAiE;IACjE,OAAO,CAAC,UAAU,CAAC,CAAuB;IAE1C,OAAO;IAUP;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,GAAG,GAAG,MAAM,GAAG,qBAAqB;IA0BtE;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB;IAkB3E;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB;IAazE;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB;IAK3D,OAAO,CAAC,SAAS;IAYjB;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAYhE"}