@hawcx/oauth-client 5.1.0 → 6.0.0

package/CHANGELOG.md

@@ -0,0 +1,479 @@
+# 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).
+
+## [Unreleased]
+
+## [6.0.0] - 2026-10-10
+
+First public release since 5.2.0. **Major version** because of the BREAKING
+entries below, which change behaviour for configurations that 5.2.0 accepted.
+It contains everything from the internal release candidates 6.0.0-rc.1 and
+6.0.0-rc.2, plus one fix to `ClientAssertionSigner` made after rc.2.
+
+### Breaking — action needed when upgrading from 5.2.0
+
+- **Management API response signatures are verified by default
+  (TOB-HSDK-11).** `JwtBearerTransport` and `StepUpClient.withPrivateKeyJwt`
+  now verify `X-Response-Signature` on every successful response. This
+  reverses the 5.2.0 note that callers "may" verify the header themselves.
+  The SDK checks the following:
+  - the JWS uses ES256, ES384 or ES512 and verifies against
+    `${issuer}/.well-known/jwks.json`;
+  - `iat` is within `clockSkewSeconds` (default 300);
+  - `body_sha256` matches the exact response bytes;
+  - the token carries no `aud`, `sub` or `nonce`.
+
+  Responses with status 400 and above are not verified. hx_auth signs every
+  jwt-mode 2xx, so production traffic is unaffected. **Action needed** if any
+  of these apply:
+  - A gateway, CDN or proxy strips response headers. Every call fails with
+    `ResponseSignatureInvalidError`; let `X-Response-Signature` through.
+  - Mocks, stubs or contract-test harnesses built against 5.2.0 return
+    unsigned 2xx responses. Sign the responses, or disable verification in the
+    test harness.
+  - `baseUrl` is not the OP host, such as an internal service URL or local dev
+    with separate ports. The JWKS is fetched from `baseUrl` by default, so set
+    `issuer`.
+- **`baseUrl` (and `issuer`) values that used to be accepted now throw at
+  construction (TOB-HSDK-13).** The affected classes are `JwtBearerTransport`
+  and `StepUpClient.withPrivateKeyJwt` (`DelegationRequestError`),
+  `DelegationTransport` and the `DelegationClient`/`StepUpClient` ECIES
+  factories (`DelegationRequestError`), legacy `HawcxOAuth`
+  (`HawcxOAuthError`), and `HawcxOAuth.fromIssuer` (`DiscoveryError`):
+  - **Plain `http:` on a non-loopback host.** Examples:
+    `http://hawcx-api:8080` (docker-compose service name),
+    `http://0.0.0.0:8080`, `http://host.docker.internal:8080`, and in-cluster
+    service URLs behind a TLS-terminating gateway. Only `localhost`,
+    `127.0.0.1` and `[::1]` may use `http:`. **Action needed:** use `https:`,
+    or point the SDK at a loopback address.
+  - **Userinfo, query or fragment in the base.** For example
+    `https://user:pw@api.hawcx.com`, `https://api.hawcx.com?tenant=x` or
+    `https://api.hawcx.com#x`. **Action needed:** remove them.
+- **The signed JWT `aud` string changes for non-canonical base spellings
+  (TOB-HSDK-13).** Host case and default ports are now normalised, so
+  `baseUrl: 'https://API.Hawcx.com:443'` produces
+  `aud = https://api.hawcx.com/v1/...`, where 5.2.0 produced
+  `https://API.Hawcx.com:443/v1/...`. The new value is the one `fetch`
+  actually sends. **Action needed** only if a server compares `aud` by exact
+  string against a configured non-canonical value: update that value, or use
+  a canonical `baseUrl`. Canonical bases (lower-case host, no default port,
+  with or without a trailing slash or a path prefix) produce byte-identical
+  URLs and `aud`.
+
+### Added
+
+- New options on `JwtBearerTransport` and `StepUpClient.withPrivateKeyJwt`:
+  `issuer` (defaults to `baseUrl`), `verifyResponseSignature` (defaults to
+  `true`) and `clockSkewSeconds`. `verifyResponseSignature: false` is an
+  **emergency escape hatch** that restores the 5.2.0 behaviour and emits a
+  one-time process warning. `withPrivateKeyJwt` now also passes
+  `clockSkewSeconds` through to the transport.
+- New error classes, both subclasses of `DelegationResponseError`, exported
+  with a stable `code`:
+  - `ResponseSignatureInvalidError` (`response_signature_invalid`).
+  - `ResponseSignatureUnavailableError` (`response_signature_unavailable`).
+    It means the signing keys could not be fetched, and **the request may
+    already have been applied** server-side.
+
+### Changed
+
+- Every security-relevant URL is now parsed and joined with the WHATWG `URL`
+  API rather than by string concatenation (TOB-HSDK-13). This covers
+  `JwtBearerTransport` and `DelegationTransport` (`baseUrl` + endpoint),
+  legacy `new HawcxOAuth({ baseUrl })` (`/oauth2/token` and `/keys`), and the
+  `fromIssuer` issuer and discovery URL. Each joined URL must keep the base's
+  origin and stay under the base path prefix, or the SDK throws (fail
+  closed). An endpoint must be a relative path that starts with a single
+  `/`. It may not contain `//`, a backslash, whitespace or control
+  characters, a fragment, or a percent-encoded `/`, `.` or `\` (`%2f`,
+  `%2e`, `%5c`, any case) in its path.
+- Discovered `token_endpoint` and `jwks_uri` values carrying userinfo are now
+  rejected (`DiscoveryError`).
+- The `clearCache()` deprecation warning now says it will be removed in a
+  future major version rather than in 6.0.0. It is still deprecated (use
+  `refreshJwks()`) and still present in 6.0.0.
+
+### Fixed
+
+- **Discovery mode now sends `client_id` on the public-client (PKCE) token
+  exchange.** Previously `exchangeCode()` added `client_id` to the token form
+  only when a `private_key_jwt` signer was set; a public PKCE exchange sent
+  only the `X-Config-Id` header. The OP then fell back to the project's
+  default client (`token.legacy_config_id_fallback`) and stamped the id_token
+  `aud` with that client's id, so on a project with more than one public OIDC
+  client, an app using a non-default client failed verification with
+  "Unexpected JWT audience". `exchangeCode()` now always sends the configured
+  `clientId` as `client_id` in discovery mode (RFC 6749 §4.1.3), for public
+  and `private_key_jwt` clients alike; the OP resolves that specific client
+  and stamps `aud` with it. `X-Config-Id` is still sent.
+  - Single-client projects are unaffected: their `clientId` is the default
+    client, so the resolved client and `aud` are the same as before.
+  - Legacy mode (`new HawcxOAuth({ configId, baseUrl })`) has no `clientId`
+    and is unchanged: it sends no `client_id`.
+- `ClientAssertionSigner.sign()` now reads the clock once for `iat` and `exp`.
+  Two separate reads could straddle a second boundary and make the assertion
+  one second longer than its lifetime; at `withLifetimeSeconds(120)` that
+  exceeds the OP's 120s cap and the token exchange is rejected.
+
+## [6.0.0-rc.2] - 2026-10-10
+
+> **Release candidate, internal only.** Published to AWS CodeArtifact
+> (`npm-internal`), not public npm; the release workflow refuses to publish a
+> prerelease publicly. Contains everything in 6.0.0-rc.1 plus the fix below.
+> To install, point the `@hawcx` scope at CodeArtifact
+> (`aws codeartifact login --tool npm --domain hawcx --repository npm-internal --namespace @hawcx`)
+> and run `npm install @hawcx/oauth-client@6.0.0-rc.2`.
+
+### Fixed
+
+- **Discovery mode now sends `client_id` on the public-client (PKCE) token
+  exchange.** Previously `exchangeCode()` added `client_id` to the token form
+  only when a `private_key_jwt` signer was set; a public PKCE exchange sent
+  only the `X-Config-Id` header. The OP then fell back to the project's
+  default client (`token.legacy_config_id_fallback`) and stamped the id_token
+  `aud` with that client's id, so on a project with more than one public OIDC
+  client, an app using a non-default client failed verification with
+  "Unexpected JWT audience". `exchangeCode()` now always sends the configured
+  `clientId` as `client_id` in discovery mode (RFC 6749 §4.1.3), for public
+  and `private_key_jwt` clients alike; the OP resolves that specific client
+  and stamps `aud` with it. `X-Config-Id` is still sent.
+  - Single-client projects are unaffected: their `clientId` is the default
+    client, so the resolved client and `aud` are the same as before.
+  - Legacy mode (`new HawcxOAuth({ configId, baseUrl })`) has no `clientId`
+    and is unchanged: it sends no `client_id`.
+
+## [6.0.0-rc.1] - 2026-10-07
+
+> **Release candidate, internal only.** Published to AWS CodeArtifact
+> (`npm-internal`), not public npm; the release workflow refuses to publish a
+> prerelease publicly. **Major version** because of the BREAKING entries below,
+> which change behaviour for configurations that 5.2.0 accepted. To install,
+> point the `@hawcx` scope at CodeArtifact
+> (`aws codeartifact login --tool npm --domain hawcx --repository npm-internal --namespace @hawcx`)
+> and run `npm install @hawcx/oauth-client@6.0.0-rc.1`.
+
+### Security — management API response signatures are verified by default (TOB-HSDK-11)
+
+- **BREAKING — `JwtBearerTransport` and `StepUpClient.withPrivateKeyJwt` now
+  verify `X-Response-Signature` on every successful response, and this is on
+  by default.** This reverses the 5.2.0 note that callers "may" verify the
+  header themselves. The SDK checks the following:
+  - the JWS uses ES256, ES384 or ES512 and verifies against
+    `${issuer}/.well-known/jwks.json`;
+  - `iat` is within `clockSkewSeconds` (default 300);
+  - `body_sha256` matches the exact response bytes;
+  - the token carries no `aud`, `sub` or `nonce`.
+
+  Responses with status 400 and above are not verified. hx_auth signs every
+  jwt-mode 2xx, so production traffic is unaffected. The following will
+  **break**:
+  - A gateway, CDN or proxy that strips response headers. Every call fails
+    with `ResponseSignatureInvalidError`.
+  - Customer mocks, stubs and contract-test harnesses built against 5.2.0 that
+    return unsigned 2xx responses. Sign the responses, or disable verification
+    in the test harness.
+  - A `baseUrl` that is not the OP host, such as an internal service URL or
+    local dev with separate ports. The JWKS is fetched from `baseUrl` by
+    default, so set `issuer`.
+- New options on both: `issuer` (defaults to `baseUrl`),
+  `verifyResponseSignature` (defaults to `true`) and `clockSkewSeconds`.
+  `verifyResponseSignature: false` is an **emergency escape hatch** that
+  restores the 5.2.0 behaviour and emits a one-time process warning.
+  `withPrivateKeyJwt` now also passes `clockSkewSeconds` through to the
+  transport.
+- New error classes, both subclasses of `DelegationResponseError`, exported
+  with a stable `code`:
+  - `ResponseSignatureInvalidError` (`response_signature_invalid`).
+  - `ResponseSignatureUnavailableError` (`response_signature_unavailable`).
+    It means the signing keys could not be fetched, and **the request may
+    already have been applied** server-side.
+
+### Security — structured URL validation and joining (TOB-HSDK-13)
+
+- Every security-relevant URL is now parsed and joined with the WHATWG `URL`
+  API rather than by string concatenation. This covers `JwtBearerTransport`
+  and `DelegationTransport` (`baseUrl` + endpoint), legacy
+  `new HawcxOAuth({ baseUrl })` (`/oauth2/token` and `/keys`), and the
+  `fromIssuer` issuer and discovery URL. Each joined URL must keep the base's
+  origin and stay under the base path prefix, or the SDK throws (fail
+  closed). An endpoint must be a relative path that starts with a single
+  `/`. It may not contain `//`, a backslash, whitespace or control
+  characters, a fragment, or a percent-encoded `/`, `.` or `\` (`%2f`,
+  `%2e`, `%5c`, any case) in its path.
+- **BREAKING — `baseUrl` (and `issuer`) values that used to be accepted now
+  throw at construction.** The affected classes are `JwtBearerTransport` and
+  `StepUpClient.withPrivateKeyJwt` (`DelegationRequestError`),
+  `DelegationTransport` and the `DelegationClient`/`StepUpClient`
+  ECIES factories (`DelegationRequestError`), legacy `HawcxOAuth`
+  (`HawcxOAuthError`), and `HawcxOAuth.fromIssuer` (`DiscoveryError`):
+  - **Plain `http:` on a non-loopback host.** Examples:
+    `http://hawcx-api:8080` (docker-compose service name),
+    `http://0.0.0.0:8080`, `http://host.docker.internal:8080`, and in-cluster
+    service URLs behind a TLS-terminating gateway. Only `localhost`,
+    `127.0.0.1` and `[::1]` may use `http:`. Use `https:`, or point the SDK
+    at a loopback address.
+  - **Userinfo, query or fragment in the base.** For example
+    `https://user:pw@api.hawcx.com`, `https://api.hawcx.com?tenant=x` or
+    `https://api.hawcx.com#x`.
+- **BREAKING — the signed JWT `aud` string changes for non-canonical base
+  spellings.** Host case and default ports are now normalised, so
+  `baseUrl: 'https://API.Hawcx.com:443'` produces
+  `aud = https://api.hawcx.com/v1/...`, where 5.2.0 produced
+  `https://API.Hawcx.com:443/v1/...`. The new value is the one `fetch`
+  actually sends. A server that compares `aud` by exact string against a
+  configured non-canonical value will reject the new form. Canonical bases
+  (lower-case host, no default port, with or without a trailing slash or a
+  path prefix) produce byte-identical URLs and `aud`.
+- Discovered `token_endpoint` and `jwks_uri` values carrying userinfo are now
+  rejected (`DiscoveryError`).
+
+## [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/README.md

@@ -450,22 +450,65 @@ 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.
+
+Every successful response is authenticated too. The SDK verifies the
+`X-Response-Signature` JWS (ES256/ES384/ES512) against
+`${issuer}/.well-known/jwks.json`. It also checks that the JWS `iat` is within
+`clockSkewSeconds` (default 300) and that its `body_sha256` matches the exact
+response bytes. `issuer` defaults to `baseUrl`, because the management API and
+the OP share a host in every Hawcx environment. Set `issuer` explicitly if they
+differ, for example in local development.
+
+> **Scope:** by default the JWKS comes from the **same origin as the API**.
+> Verification therefore protects against tampering *between* that origin and
+> you: caches, proxies and gateways, or a compromised downstream service. It
+> does **not** protect against a compromised origin. If you need that, pin
+> `issuer` to a separately trusted host.
+
+Failures throw one of two subclasses of `DelegationResponseError`, each with a
+stable `code`:
+
+- `ResponseSignatureInvalidError` (`code: 'response_signature_invalid'`): the
+  header is missing or empty, or the signature does not verify. Treat the
+  response as untrusted.
+- `ResponseSignatureUnavailableError` (`code: 'response_signature_unavailable'`):
+  the signing keys could not be obtained. The JWKS fetch failed, timed out or
+  returned something unusable, or a newly rotated `kid` arrived while refetching
+  was cooling down. **The server has already processed the request**, so a
+  non-idempotent write such as `consumeReceipt` may have been applied. Reconcile
+  state rather than retrying blindly.
+
+`verifyResponseSignature: false` turns verification off. It is an emergency
+escape hatch only, and it logs a one-time process warning.
+
 ### Methods
 
 #### `stepUp.startToken(options): Promise<StepUpStartTokenResponse>`
@@ -512,6 +555,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
@@ -595,9 +655,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',
 });
 

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

@@ -1 +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"}
+{"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;CAgBhE"}

package/dist/client-assertion.js

@@ -119,13 +119,17 @@ class ClientAssertionSigner {
      */
     async sign(clientId, audience) {
         const key = await this.importKey();
+        // One clock read for both claims: separate reads can straddle a second
+        // boundary and make exp - iat one second longer than the lifetime, which at
+        // the 120s maximum exceeds the OP's cap.
+        const now = Math.floor(Date.now() / 1000);
         return new jose_1.SignJWT({})
             .setProtectedHeader({ alg: 'EdDSA', typ: 'JWT', kid: this.kid })
             .setIssuer(clientId)
             .setSubject(clientId)
             .setAudience(audience)
-            .setIssuedAt()
-            .setExpirationTime(`${this.lifetimeSeconds}s`)
+            .setIssuedAt(now)
+            .setExpirationTime(now + this.lifetimeSeconds)
             .setJti((0, node_crypto_1.randomUUID)())
             .sign(key);
     }

package/dist/client-assertion.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-assertion.js","sourceRoot":"","sources":["../src/client-assertion.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client-assertion.js","sourceRoot":"","sources":["../src/client-assertion.ts"],"names":[],"mappings":"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"}