@hawcx/oauth-client 5.1.0 → 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/README.md

@@ -450,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>`
@@ -512,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
@@ -595,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',
 });
 

package/dist/index.d.ts

@@ -19,5 +19,5 @@ export type { HawcxOAuthErrorFields } from './errors';
 export { ClientAssertionSigner, CLIENT_ASSERTION_TYPE } from './client-assertion';
 export * from './delegation';
 export * from './stepup';
-export declare const VERSION = "5.1.0";
+export declare const VERSION = "5.2.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -44,5 +44,5 @@ Object.defineProperty(exports, "CLIENT_ASSERTION_TYPE", { enumerable: true, get:
 __exportStar(require("./delegation"), exports);
 // Step-up module
 __exportStar(require("./stepup"), exports);
-exports.VERSION = '5.1.0';
+exports.VERSION = '5.2.0';
 //# sourceMappingURL=index.js.map

package/dist/management/jwt_transport.d.ts

@@ -0,0 +1,109 @@
+/**
+ * JWT-bearer transport for the Hawcx management API (Path A: private_key_jwt).
+ *
+ * Each request is authenticated with a per-request EdDSA JWT whose `aud` is
+ * the full request URL, carrying a `body_sha256` claim over the EXACT bytes
+ * sent.  This mirrors the wire contract verified end-to-end against hx_auth
+ * (see spec.md §management-api-auth / Python SDK Path A implementation).
+ *
+ * Construction:
+ *   const transport = new JwtBearerTransport({
+ *     baseUrl: 'https://api.hawcx.com',
+ *     configId: 'your-config-id',
+ *     clientId: 'your-client-id',
+ *     oidcSigningKey: pkcs8Pem,   // Ed25519 PKCS#8 PEM — same key registered in admin console
+ *     kid: 'key-id',
+ *   });
+ *
+ * The `http` constructor option accepts an injectable fetch-compatible function
+ * (same signature as the global `fetch`) for testing.
+ */
+import { type JWK } from 'jose';
+import type { KeyLike } from 'jose';
+import type { JsonObject } from '../delegation/transport';
+/**
+ * A fetch-compatible callable — accepts `(url: string, init: RequestInit)`
+ * and returns a `Promise<Response>`.  Mirrors the global `fetch` signature so
+ * the real `fetch` can be passed unchanged.
+ */
+export type HttpFetch = (url: string, init: RequestInit) => Promise<Response>;
+export interface JwtBearerTransportOptions {
+    /** Base URL of the management API, e.g. `https://api.hawcx.com` */
+    baseUrl: string;
+    /** Tenant config identifier; forwarded as `X-Config-Id`. */
+    configId: string;
+    /**
+     * Ed25519 private signing key.  Accepts:
+     *   - PKCS#8 PEM string (e.g. `"-----BEGIN PRIVATE KEY-----\n…"`)
+     *   - JWK object `{ kty:'OKP', crv:'Ed25519', d, x, kid? }`
+     *   - jose `KeyLike` / `CryptoKey` already imported
+     */
+    oidcSigningKey: string | JWK | KeyLike;
+    /** Key ID embedded in the JWT `kid` header. */
+    kid: string;
+    /** OAuth client ID; used as both `iss` and `sub` in the per-request JWT. */
+    clientId: string;
+    /**
+     * JWT time-to-live in seconds (default: 60).  The server rejects tokens
+     * older than its configured TTL; do not set this above 120.
+     */
+    jwtTtlSeconds?: number;
+    /**
+     * Per-request timeout in seconds (default: 15).  A stalled
+     * (connected-but-silent) server would otherwise hang the call forever and
+     * can exhaust connection pools server-side.  Mirrors the ECIES
+     * `DelegationTransport`'s 15s `AbortController`.
+     */
+    timeoutSeconds?: number;
+    /**
+     * Injectable fetch implementation.  Defaults to the global `fetch`
+     * (Node >= 18).  Pass a capturing fake in tests.
+     */
+    http?: HttpFetch;
+}
+/**
+ * Drop-in transport for the management API that authenticates via a per-request
+ * EdDSA JWT (`private_key_jwt`, Path A).
+ *
+ * The `send` method has the same name and signature as `DelegationTransport.send`
+ * so the factory can swap transports behind `StepUpClient` without any change to
+ * the business-method layer.
+ */
+export declare class JwtBearerTransport {
+    private readonly baseUrl;
+    private readonly configId;
+    private readonly kid;
+    private readonly clientId;
+    private readonly jwtTtlSeconds;
+    private readonly timeoutMs;
+    private readonly http;
+    /** Lazily-imported (and memoised) signing key. */
+    private keyPromise?;
+    private readonly importKeyFn;
+    constructor(options: JwtBearerTransportOptions);
+    private importKey;
+    /**
+     * Mint a per-request EdDSA JWT.
+     *
+     * @param audience - full request URL (`baseUrl + endpoint`), pinned per-call
+     * @param bodySha256 - base64url (no-padding) of SHA-256 over the exact body bytes
+     */
+    private mintJwt;
+    /**
+     * Send an authenticated POST to `endpoint` with `payload` serialised as JSON.
+     *
+     * Matches the signature of `DelegationTransport.send` so the two transports
+     * are drop-in substitutes behind `StepUpClient`.
+     *
+     * @param options.endpoint - API path, e.g. `/v1/management/stepup/start-token`
+     * @param options.payload  - request body; serialised once and hashed; the
+     *   EXACT same bytes are sent and hashed — no double-serialisation.
+     * @param options.headers  - optional extra headers merged last (win over built-ins)
+     */
+    send<TReq extends JsonObject, TRes extends JsonObject>(options: {
+        endpoint: string;
+        payload: TReq;
+        headers?: Record<string, string>;
+    }): Promise<TRes>;
+}
+//# sourceMappingURL=jwt_transport.d.ts.map

package/dist/management/jwt_transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt_transport.d.ts","sourceRoot":"","sources":["../../src/management/jwt_transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAmC,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAK1D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;IACvC,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IAEjC,kDAAkD;IAClD,OAAO,CAAC,UAAU,CAAC,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;gBAE7C,OAAO,EAAE,yBAAyB;IAyB9C,OAAO,CAAC,SAAS;IAajB;;;;;OAKG;YACW,OAAO;IAiBrB;;;;;;;;;;OAUG;IACG,IAAI,CAAC,IAAI,SAAS,UAAU,EAAE,IAAI,SAAS,UAAU,EAAE,OAAO,EAAE;QACpE,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,IAAI,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,IAAI,CAAC;CAiFlB"}

package/dist/management/jwt_transport.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * JWT-bearer transport for the Hawcx management API (Path A: private_key_jwt).
+ *
+ * Each request is authenticated with a per-request EdDSA JWT whose `aud` is
+ * the full request URL, carrying a `body_sha256` claim over the EXACT bytes
+ * sent.  This mirrors the wire contract verified end-to-end against hx_auth
+ * (see spec.md §management-api-auth / Python SDK Path A implementation).
+ *
+ * Construction:
+ *   const transport = new JwtBearerTransport({
+ *     baseUrl: 'https://api.hawcx.com',
+ *     configId: 'your-config-id',
+ *     clientId: 'your-client-id',
+ *     oidcSigningKey: pkcs8Pem,   // Ed25519 PKCS#8 PEM — same key registered in admin console
+ *     kid: 'key-id',
+ *   });
+ *
+ * The `http` constructor option accepts an injectable fetch-compatible function
+ * (same signature as the global `fetch`) for testing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtBearerTransport = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_crypto_2 = require("node:crypto");
+const jose_1 = require("jose");
+const exceptions_1 = require("../delegation/exceptions");
+/**
+ * Drop-in transport for the management API that authenticates via a per-request
+ * EdDSA JWT (`private_key_jwt`, Path A).
+ *
+ * The `send` method has the same name and signature as `DelegationTransport.send`
+ * so the factory can swap transports behind `StepUpClient` without any change to
+ * the business-method layer.
+ */
+class JwtBearerTransport {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.configId = options.configId;
+        this.kid = options.kid;
+        this.clientId = options.clientId;
+        this.jwtTtlSeconds = options.jwtTtlSeconds ?? 60;
+        this.timeoutMs = (options.timeoutSeconds ?? 15) * 1000;
+        this.http = options.http ?? ((...args) => fetch(...args));
+        const key = options.oidcSigningKey;
+        if (typeof key === 'string') {
+            // PKCS#8 PEM
+            this.importKeyFn = () => (0, jose_1.importPKCS8)(key, 'EdDSA');
+        }
+        else if (isJwk(key)) {
+            // Plain JWK object
+            this.importKeyFn = () => (0, jose_1.importJWK)(key, 'EdDSA');
+        }
+        else {
+            // Already a jose KeyLike / CryptoKey — wrap in a resolved promise.
+            const resolved = Promise.resolve(key);
+            this.importKeyFn = () => resolved;
+        }
+    }
+    // ── Key loading ────────────────────────────────────────────────────────────
+    importKey() {
+        if (!this.keyPromise) {
+            // Don't memoise a rejection — reset so the next call retries.
+            this.keyPromise = this.importKeyFn().catch((err) => {
+                this.keyPromise = undefined;
+                throw err;
+            });
+        }
+        return this.keyPromise;
+    }
+    // ── JWT minting ────────────────────────────────────────────────────────────
+    /**
+     * Mint a per-request EdDSA JWT.
+     *
+     * @param audience - full request URL (`baseUrl + endpoint`), pinned per-call
+     * @param bodySha256 - base64url (no-padding) of SHA-256 over the exact body bytes
+     */
+    async mintJwt(audience, bodySha256) {
+        const key = await this.importKey();
+        const nowSec = Math.floor(Date.now() / 1000);
+        return new jose_1.SignJWT({ body_sha256: bodySha256 })
+            .setProtectedHeader({ alg: 'EdDSA', kid: this.kid, typ: 'JWT' })
+            .setIssuer(this.clientId)
+            .setSubject(this.clientId)
+            .setAudience(audience)
+            .setIssuedAt(nowSec)
+            .setExpirationTime(nowSec + this.jwtTtlSeconds)
+            .setJti((0, node_crypto_1.randomUUID)())
+            .sign(key);
+    }
+    // ── Transport ──────────────────────────────────────────────────────────────
+    /**
+     * Send an authenticated POST to `endpoint` with `payload` serialised as JSON.
+     *
+     * Matches the signature of `DelegationTransport.send` so the two transports
+     * are drop-in substitutes behind `StepUpClient`.
+     *
+     * @param options.endpoint - API path, e.g. `/v1/management/stepup/start-token`
+     * @param options.payload  - request body; serialised once and hashed; the
+     *   EXACT same bytes are sent and hashed — no double-serialisation.
+     * @param options.headers  - optional extra headers merged last (win over built-ins)
+     */
+    async send(options) {
+        const { endpoint, payload, headers: extraHeaders = {} } = options;
+        // Canonicalise body ONCE.  The same Buffer is both hashed and sent.
+        const bodyBytes = Buffer.from(JSON.stringify(payload));
+        // SHA-256 → base64url without padding (RFC 7515 §2).
+        const hash = (0, node_crypto_2.createHash)('sha256').update(bodyBytes).digest();
+        const bodySha256 = hash.toString('base64url').replace(/=+$/, '');
+        const url = this.baseUrl + endpoint;
+        let jwt;
+        try {
+            jwt = await this.mintJwt(url, bodySha256);
+        }
+        catch (err) {
+            throw new exceptions_1.DelegationRequestError('Failed to sign management request', { cause: err });
+        }
+        // Extra headers are merged first so the transport's own auth/routing
+        // headers (Authorization, X-Config-Id, X-Hawcx-Protocol-Version) cannot
+        // be accidentally overridden by the caller's header bag.
+        const requestHeaders = {
+            ...extraHeaders,
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${jwt}`,
+            'X-Config-Id': this.configId,
+            'X-Hawcx-Protocol-Version': '2',
+        };
+        let response;
+        let responseData;
+        // Bound every request with a timeout: a connected-but-silent server would
+        // otherwise hang the call indefinitely and can exhaust connection pools.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            response = await this.http(url, {
+                method: 'POST',
+                headers: requestHeaders,
+                body: bodyBytes,
+                signal: controller.signal,
+            });
+            responseData = Buffer.from(await response.arrayBuffer());
+        }
+        catch (err) {
+            if (err instanceof exceptions_1.DelegationRequestError)
+                throw err;
+            throw new exceptions_1.DelegationRequestError('Request to management API failed', { cause: err });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = responseData.toString('utf-8');
+        // Check the HTTP status BEFORE parsing JSON. A non-JSON error body (e.g. a
+        // WAF/proxy HTML 403) must still surface its status as a
+        // DelegationRequestError — not get masked as a JSON parse failure that the
+        // caller can't distinguish from a malformed 200.
+        if (response.status >= 400) {
+            let errorBody = text;
+            try {
+                const errJson = JSON.parse(text);
+                if (errJson?.detail)
+                    errorBody = String(errJson.detail);
+            }
+            catch {
+                // Non-JSON error body — keep the raw text.
+            }
+            throw new exceptions_1.DelegationRequestError(`Management API returned ${response.status}`, {
+                statusCode: response.status,
+                responseBody: errorBody,
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            throw new exceptions_1.DelegationResponseError('Failed to parse management API response', { cause: err });
+        }
+        return parsed;
+    }
+}
+exports.JwtBearerTransport = JwtBearerTransport;
+// ── helpers ──────────────────────────────────────────────────────────────────
+/** Narrow check: is this value a plain JWK object (has `kty` string)? */
+function isJwk(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.kty === 'string');
+}
+//# sourceMappingURL=jwt_transport.js.map

package/dist/management/jwt_transport.js.map

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

package/dist/stepup/client.d.ts

@@ -1,6 +1,15 @@
-import { DelegationTransport } from '../delegation/transport';
+import { type JsonObject, type SecureRequestOptions } from '../delegation/transport';
 import { DelegationKeyMaterial } from '../delegation/factory';
+import { type JwtBearerTransportOptions } from '../management/jwt_transport';
 import { StepUpClientBaseOptions, StepUpConsumeOptions, StepUpConsumeResponse, StepUpStartOptions, StepUpStartTokenResponse } from './types';
+/**
+ * Structural interface satisfied by both `DelegationTransport` (ECIES) and
+ * `JwtBearerTransport` (private_key_jwt).  Allows `StepUpClient` to accept
+ * either transport without a hard dependency on the concrete types.
+ */
+interface StepUpTransport {
+    send<TReq extends JsonObject, TRes extends JsonObject>(options: Pick<SecureRequestOptions<TReq>, 'endpoint' | 'payload' | 'headers'>): Promise<TRes>;
+}
 export interface StepUpClientSecretKeyOptions extends StepUpClientBaseOptions {
     secretKey: string;
     apiKey?: string;
@@ -8,19 +17,69 @@ export interface StepUpClientSecretKeyOptions extends StepUpClientBaseOptions {
 export type StepUpClientKeyOptions = StepUpClientBaseOptions & DelegationKeyMaterial & {
     apiKey?: string;
 };
+/**
+ * Options for {@link StepUpClient.withPrivateKeyJwt}.  Combines the
+ * JWT-bearer transport credentials with the standard step-up base options.
+ */
+export interface StepUpClientPrivateKeyJwtOptions extends StepUpClientBaseOptions {
+    /** Ed25519 private signing key (PKCS#8 PEM, JWK object, or jose KeyLike). */
+    oidcSigningKey: JwtBearerTransportOptions['oidcSigningKey'];
+    /** Key ID embedded in the JWT `kid` header. */
+    kid: string;
+    /** OAuth client ID (`iss` / `sub` in the per-request JWT). */
+    clientId: string;
+    /** Tenant config identifier; forwarded as `X-Config-Id`. */
+    configId: string;
+    /** Optional API key forwarded as `apikey` header. */
+    apiKey?: string;
+    /** JWT time-to-live in seconds (default: 60). */
+    jwtTtlSeconds?: number;
+}
 export declare class StepUpClient {
     private transport;
     private options;
     private apiKey?;
     constructor(options: {
-        transport: DelegationTransport;
+        transport: StepUpTransport;
         clientOptions: StepUpClientBaseOptions;
         apiKey?: string;
     });
+    /**
+     * @deprecated since 5.2.0 — the ECIES secret-key credential format is
+     *   proprietary and will be removed in a future major version.  Migrate to
+     *   {@link StepUpClient.withPrivateKeyJwt}, which reuses the standard OIDC
+     *   Ed25519 `private_key_jwt` signing key already registered in the admin
+     *   console (one key, standards-based).
+     */
     static fromSecretKey(options: StepUpClientSecretKeyOptions): StepUpClient;
+    /**
+     * @deprecated since 5.2.0 — the ECIES key-material format is proprietary
+     *   and will be removed in a future major version.  Migrate to
+     *   {@link StepUpClient.withPrivateKeyJwt}.
+     */
     static fromKeys(options: StepUpClientKeyOptions): StepUpClient;
+    /**
+     * Build a `StepUpClient` authenticated via EdDSA `private_key_jwt` (Path A).
+     *
+     * Reuses the same Ed25519 signing key registered in the Hawcx admin console
+     * for OIDC `private_key_jwt` — one key, standards-based, no separate ECIES
+     * credential blob required.
+     *
+     * @example
+     * ```typescript
+     * const stepUp = StepUpClient.withPrivateKeyJwt({
+     *   baseUrl: 'https://api.hawcx.com',
+     *   configId: process.env.HAWCX_CONFIG_ID!,
+     *   clientId: process.env.HAWCX_CLIENT_ID!,
+     *   oidcSigningKey: JSON.parse(process.env.HAWCX_PRIVATE_JWK!),
+     *   kid: 'your-key-id',
+     * });
+     * ```
+     */
+    static withPrivateKeyJwt(options: StepUpClientPrivateKeyJwtOptions): StepUpClient;
     private buildExtraHeaders;
     startToken(options: StepUpStartOptions): Promise<StepUpStartTokenResponse>;
     consumeReceipt(options: StepUpConsumeOptions): Promise<StepUpConsumeResponse>;
 }
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/stepup/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/stepup/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAuD,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnH,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,4BAA6B,SAAQ,uBAAuB;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,qBAAqB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3G,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,MAAM,CAAC,CAAS;gBAEZ,OAAO,EAAE;QACnB,SAAS,EAAE,mBAAmB,CAAC;QAC/B,aAAa,EAAE,uBAAuB,CAAC;QACvC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAMD,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,4BAA4B,GAAG,YAAY;IAMzE,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,YAAY;IAM9D,OAAO,CAAC,iBAAiB;IAmBnB,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAuB1E,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAoBpF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/stepup/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAuD,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnH,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACjG,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,UAAU,eAAe;IACvB,IAAI,CAAC,IAAI,SAAS,UAAU,EAAE,IAAI,SAAS,UAAU,EACnD,OAAO,EAAE,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC,GAC5E,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,4BAA6B,SAAQ,uBAAuB;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,qBAAqB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3G;;;GAGG;AACH,MAAM,WAAW,gCAAiC,SAAQ,uBAAuB;IAC/E,6EAA6E;IAC7E,cAAc,EAAE,yBAAyB,CAAC,gBAAgB,CAAC,CAAC;IAC5D,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,MAAM,CAAC,CAAS;gBAEZ,OAAO,EAAE;QACnB,SAAS,EAAE,eAAe,CAAC;QAC3B,aAAa,EAAE,uBAAuB,CAAC;QACvC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAMD;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,4BAA4B,GAAG,YAAY;IAezE;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,YAAY;IAe9D;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,gCAAgC,GAAG,YAAY;IAiBjF,OAAO,CAAC,iBAAiB;IAmBnB,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAuB1E,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAoBpF"}

package/dist/stepup/client.js

@@ -3,22 +3,81 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StepUpClient = void 0;
 const factory_1 = require("../delegation/factory");
 const exceptions_1 = require("../delegation/exceptions");
+const jwt_transport_1 = require("../management/jwt_transport");
 class StepUpClient {
     constructor(options) {
         this.transport = options.transport;
         this.options = options.clientOptions;
         this.apiKey = options.apiKey;
     }
+    /**
+     * @deprecated since 5.2.0 — the ECIES secret-key credential format is
+     *   proprietary and will be removed in a future major version.  Migrate to
+     *   {@link StepUpClient.withPrivateKeyJwt}, which reuses the standard OIDC
+     *   Ed25519 `private_key_jwt` signing key already registered in the admin
+     *   console (one key, standards-based).
+     */
     static fromSecretKey(options) {
+        if (!fromSecretKeyWarned) {
+            fromSecretKeyWarned = true;
+            process.emitWarning('[@hawcx/oauth-client] StepUpClient.fromSecretKey() is deprecated since 5.2.0. ' +
+                'Migrate to StepUpClient.withPrivateKeyJwt() (standards-based Ed25519 private_key_jwt). ' +
+                'fromSecretKey() will be removed in a future major version.', 'DeprecationWarning');
+        }
         const { apiKey } = options;
         const transport = (0, factory_1.buildTransportFromSecretKey)(options);
         return new StepUpClient({ transport, clientOptions: options, apiKey });
     }
+    /**
+     * @deprecated since 5.2.0 — the ECIES key-material format is proprietary
+     *   and will be removed in a future major version.  Migrate to
+     *   {@link StepUpClient.withPrivateKeyJwt}.
+     */
     static fromKeys(options) {
+        if (!fromKeysWarned) {
+            fromKeysWarned = true;
+            process.emitWarning('[@hawcx/oauth-client] StepUpClient.fromKeys() is deprecated since 5.2.0. ' +
+                'Migrate to StepUpClient.withPrivateKeyJwt() (standards-based Ed25519 private_key_jwt). ' +
+                'fromKeys() will be removed in a future major version.', 'DeprecationWarning');
+        }
         const { apiKey } = options;
         const transport = (0, factory_1.buildTransportFromKeys)(options);
         return new StepUpClient({ transport, clientOptions: options, apiKey });
     }
+    /**
+     * Build a `StepUpClient` authenticated via EdDSA `private_key_jwt` (Path A).
+     *
+     * Reuses the same Ed25519 signing key registered in the Hawcx admin console
+     * for OIDC `private_key_jwt` — one key, standards-based, no separate ECIES
+     * credential blob required.
+     *
+     * @example
+     * ```typescript
+     * const stepUp = StepUpClient.withPrivateKeyJwt({
+     *   baseUrl: 'https://api.hawcx.com',
+     *   configId: process.env.HAWCX_CONFIG_ID!,
+     *   clientId: process.env.HAWCX_CLIENT_ID!,
+     *   oidcSigningKey: JSON.parse(process.env.HAWCX_PRIVATE_JWK!),
+     *   kid: 'your-key-id',
+     * });
+     * ```
+     */
+    static withPrivateKeyJwt(options) {
+        const { apiKey, oidcSigningKey, kid, clientId, configId, jwtTtlSeconds, ...clientOptions } = options;
+        const transport = new jwt_transport_1.JwtBearerTransport({
+            baseUrl: clientOptions.baseUrl,
+            configId,
+            clientId,
+            oidcSigningKey,
+            kid,
+            jwtTtlSeconds,
+            // Thread the request timeout through to the transport — without this it
+            // stays in clientOptions and the JWT transport falls back to its 15s
+            // default regardless of what the caller passed (parity with fromKeys).
+            timeoutSeconds: clientOptions.timeoutSeconds,
+        });
+        return new StepUpClient({ transport, clientOptions, apiKey });
+    }
     buildExtraHeaders() {
         const headers = {
             'X-Hawcx-Protocol-Version': '1',
@@ -75,4 +134,9 @@ class StepUpClient {
     }
 }
 exports.StepUpClient = StepUpClient;
+// Module-level flags so the deprecation warning fires at most once per process
+// (matches the clearCache() pattern in oauth.ts which warns once per instance;
+// here we warn once per process since the factory is static).
+let fromSecretKeyWarned = false;
+let fromKeysWarned = false;
 //# sourceMappingURL=client.js.map

package/dist/stepup/client.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawcx/oauth-client",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "Simple OAuth client for Hawcx authentication with delegation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,6 +47,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ]
 }