@hawcx/oauth-client 0.2.0 → 5.1.0

package/dist/delegation/transport.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Secure transport for ECIES-encrypted and signed delegation requests.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegationTransport = void 0;
+const crypto_1 = require("./crypto");
+const exceptions_1 = require("./exceptions");
+class DelegationTransport {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.signer = options.signer;
+        this.verifier = options.verifier;
+        this.encryptor = options.encryptor;
+        this.decryptor = options.decryptor;
+        this.timeoutSeconds = options.timeoutSeconds ?? 15;
+        this.clockSkewSeconds = options.clockSkewSeconds ?? 300;
+    }
+    /**
+     * Send an encrypted and signed delegation request to the IDP.
+     */
+    async send(options) {
+        const { endpoint, payload, includeBaseUrl = true, headers: extraHeaders = {} } = options;
+        let encryptedEnv;
+        let headers;
+        try {
+            const body = Buffer.from(JSON.stringify(payload));
+            encryptedEnv = await this.encryptor.encrypt(body);
+            const ts = (0, crypto_1.nowS)();
+            const sig = this.signer.signDetached(encryptedEnv, ts);
+            headers = {
+                'Content-Type': 'application/json',
+                'X-Enc-Alg': 'x25519-aesgcm',
+                'X-Timestamp': String(ts),
+                'X-Signature-Alg': sig.alg,
+                'X-Signature': sig.signatureB64,
+            };
+            if (sig.kid) {
+                headers['X-Key-Id'] = sig.kid;
+            }
+            Object.assign(headers, extraHeaders);
+        }
+        catch (error) {
+            throw new exceptions_1.DelegationRequestError('Failed to prepare secure request', { cause: error });
+        }
+        let response;
+        let responseData;
+        try {
+            const url = includeBaseUrl ? this.baseUrl + endpoint : endpoint;
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeoutSeconds * 1000);
+            try {
+                response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: encryptedEnv,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            responseData = Buffer.from(await response.arrayBuffer());
+        }
+        catch (error) {
+            throw new exceptions_1.DelegationRequestError('Request to IDP failed', { cause: error });
+        }
+        try {
+            const respSig = response.headers.get('x-signature');
+            const respAlg = response.headers.get('x-signature-alg');
+            const respKid = response.headers.get('x-key-id');
+            const respTsHeader = response.headers.get('x-timestamp');
+            if (!respSig || !respAlg || !respTsHeader) {
+                throw new exceptions_1.DelegationResponseError('Missing signature headers in IDP response');
+            }
+            const respTs = Number(respTsHeader);
+            if (!Number.isFinite(respTs)) {
+                throw new exceptions_1.DelegationResponseError('Invalid response timestamp');
+            }
+            const skew = Math.abs((0, crypto_1.nowS)() - respTs);
+            if (skew > this.clockSkewSeconds) {
+                throw new exceptions_1.DelegationResponseError(`Response timestamp outside allowed skew (${this.clockSkewSeconds}s)`);
+            }
+            this.verifier.verify(responseData, respTs, respSig, respAlg, respKid ?? undefined);
+            if (response.headers.get('x-enc-alg') !== 'x25519-aesgcm') {
+                throw new exceptions_1.DelegationResponseError('IDP response must be ECIES encrypted');
+            }
+            const plaintext = await this.decryptor.decrypt(responseData);
+            const decryptedData = JSON.parse(plaintext.toString('utf-8'));
+            if (response.status >= 400) {
+                const errorDetail = decryptedData?.detail;
+                const errorBody = errorDetail ? String(errorDetail) : JSON.stringify(decryptedData);
+                throw new exceptions_1.DelegationRequestError(`IDP returned ${response.status}`, {
+                    statusCode: response.status,
+                    responseBody: errorBody,
+                });
+            }
+            return decryptedData;
+        }
+        catch (error) {
+            if (error instanceof exceptions_1.DelegationRequestError) {
+                throw error;
+            }
+            if (error instanceof exceptions_1.DelegationResponseError) {
+                throw error;
+            }
+            if (response.status >= 400) {
+                const responseText = responseData.toString('utf-8').substring(0, 500);
+                throw new exceptions_1.DelegationRequestError(`IDP returned ${response.status}`, {
+                    statusCode: response.status,
+                    responseBody: responseText,
+                    cause: error,
+                });
+            }
+            throw new exceptions_1.DelegationResponseError('Failed to process secure response', { cause: error });
+        }
+    }
+}
+exports.DelegationTransport = DelegationTransport;
+//# sourceMappingURL=transport.js.map

package/dist/delegation/transport.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Hawcx OAuth Errors
+ */
+/**
+ * Optional structured fields shared across the Hawcx OAuth error hierarchy.
+ * `error` is a stable machine-readable code callers can dispatch on (e.g.
+ * `'state_mismatch'`, `'state_missing'`, or an IdP-supplied OAuth error such as
+ * `'access_denied'`); `errorDescription` is the human-readable detail when one
+ * is available. Both are optional and never affect `.message`.
+ */
+export interface HawcxOAuthErrorFields {
+    /** Machine-readable error code (e.g. `'state_mismatch'`, `'access_denied'`). */
+    error?: string;
+    /** Human-readable error description, when one is available. */
+    errorDescription?: string;
+}
+/**
+ * Canonical root for every Hawcx SDK error, aligned with the Java/Python SDKs
+ * (`HawcxError`). Catch this to handle any SDK-originated failure.
+ */
+export declare class HawcxError extends Error {
+    constructor(message: string);
+}
+/**
+ * Historical base, retained for back-compat. Now a subclass of {@link HawcxError};
+ * every SDK error is catchable via either. New code can catch `HawcxError`.
+ *
+ * Carries optional structured {@link HawcxOAuthErrorFields} (`error` /
+ * `errorDescription`) so callers can dispatch on a stable code without parsing
+ * `.message`. These are populated at the relevant raise sites and never alter
+ * the thrown message string.
+ */
+export declare class HawcxOAuthError extends HawcxError {
+    /** Machine-readable error code, when set at the raise site. */
+    readonly error?: string;
+    /** Human-readable error description, when available. */
+    readonly errorDescription?: string;
+    constructor(message: string, fields?: HawcxOAuthErrorFields);
+}
+export declare class TokenExchangeError extends HawcxOAuthError {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number, fields?: HawcxOAuthErrorFields);
+}
+export declare class TokenVerificationError extends HawcxOAuthError {
+    constructor(message: string, fields?: HawcxOAuthErrorFields);
+}
+/**
+ * Thrown when OIDC discovery (`HawcxOAuth.fromIssuer`) cannot resolve a usable
+ * provider configuration — DNS / TLS / network failure, non-2xx response from
+ * `/.well-known/openid-configuration`, malformed JSON, or a discovery document
+ * missing required fields (`token_endpoint`, `jwks_uri`,
+ * `id_token_signing_alg_values_supported`).
+ *
+ * The original failure (when present) is attached as `cause`, so the full
+ * diagnostic stack survives.
+ */
+export declare class DiscoveryError extends HawcxOAuthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    } & HawcxOAuthErrorFields);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,qBAAqB;CAM5D;AAED,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,qBAAqB;CAKjF;AAED,qBAAa,sBAAuB,SAAQ,eAAe;gBAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,qBAAqB;CAI5D;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,eAAe;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,qBAAqB;CAOnF"}

package/dist/errors.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Hawcx OAuth Errors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscoveryError = exports.TokenVerificationError = exports.TokenExchangeError = exports.HawcxOAuthError = exports.HawcxError = void 0;
+/**
+ * Canonical root for every Hawcx SDK error, aligned with the Java/Python SDKs
+ * (`HawcxError`). Catch this to handle any SDK-originated failure.
+ */
+class HawcxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HawcxError';
+    }
+}
+exports.HawcxError = HawcxError;
+/**
+ * Historical base, retained for back-compat. Now a subclass of {@link HawcxError};
+ * every SDK error is catchable via either. New code can catch `HawcxError`.
+ *
+ * Carries optional structured {@link HawcxOAuthErrorFields} (`error` /
+ * `errorDescription`) so callers can dispatch on a stable code without parsing
+ * `.message`. These are populated at the relevant raise sites and never alter
+ * the thrown message string.
+ */
+class HawcxOAuthError extends HawcxError {
+    constructor(message, fields) {
+        super(message);
+        this.name = 'HawcxOAuthError';
+        if (fields?.error !== undefined)
+            this.error = fields.error;
+        if (fields?.errorDescription !== undefined)
+            this.errorDescription = fields.errorDescription;
+    }
+}
+exports.HawcxOAuthError = HawcxOAuthError;
+class TokenExchangeError extends HawcxOAuthError {
+    constructor(message, statusCode, fields) {
+        super(message, fields);
+        this.name = 'TokenExchangeError';
+        this.statusCode = statusCode;
+    }
+}
+exports.TokenExchangeError = TokenExchangeError;
+class TokenVerificationError extends HawcxOAuthError {
+    constructor(message, fields) {
+        super(message, fields);
+        this.name = 'TokenVerificationError';
+    }
+}
+exports.TokenVerificationError = TokenVerificationError;
+/**
+ * Thrown when OIDC discovery (`HawcxOAuth.fromIssuer`) cannot resolve a usable
+ * provider configuration — DNS / TLS / network failure, non-2xx response from
+ * `/.well-known/openid-configuration`, malformed JSON, or a discovery document
+ * missing required fields (`token_endpoint`, `jwks_uri`,
+ * `id_token_signing_alg_values_supported`).
+ *
+ * The original failure (when present) is attached as `cause`, so the full
+ * diagnostic stack survives.
+ */
+class DiscoveryError extends HawcxOAuthError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'DiscoveryError';
+        if (options?.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+exports.DiscoveryError = DiscoveryError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAgBH;;;GAGG;AACH,MAAa,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AALD,gCAKC;AAED;;;;;;;;GAQG;AACH,MAAa,eAAgB,SAAQ,UAAU;IAM7C,YAAY,OAAe,EAAE,MAA8B;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,MAAM,EAAE,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3D,IAAI,MAAM,EAAE,gBAAgB,KAAK,SAAS;YAAE,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAC9F,CAAC;CACF;AAZD,0CAYC;AAED,MAAa,kBAAmB,SAAQ,eAAe;IAGrD,YAAY,OAAe,EAAE,UAAmB,EAAE,MAA8B;QAC9E,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AARD,gDAQC;AAED,MAAa,sBAAuB,SAAQ,eAAe;IACzD,YAAY,OAAe,EAAE,MAA8B;QACzD,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC;AAED;;;;;;;;;GASG;AACH,MAAa,cAAe,SAAQ,eAAe;IACjD,YAAY,OAAe,EAAE,OAAqD;QAChF,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,IAA4B,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QACtD,CAAC;IACH,CAAC;CACF;AARD,wCAQC"}

package/dist/index.d.ts

@@ -1,26 +1,23 @@
 /**
  * Hawcx OAuth Client SDK
  *
- * A lightweight, production-ready Node.js library for exchanging OAuth authorization
- * codes and verifying JWT claims. Built with security, reliability, and ease of use in mind.
+ * Simple, production-ready SDK for exchanging authorization codes
+ * and verifying JWT tokens with Hawcx OAuth service.
  *
  * @example
  * ```typescript
- * import { exchangeCodeForClaims } from '@hawcx/oauth-client';
+ * import { HawcxOAuth } from '@hawcx/oauth-client';
  *
- * const claims = await exchangeCodeForClaims({
- *   code: 'abc123',
- *   oauthTokenUrl: 'https://oauth.example.com/token',
- *   clientId: 'my-app',
- *   publicKey: 'path/to/public.pem'
- * });
- * console.log(claims.sub); // 'user@example.com'
+ * const oauth = new HawcxOAuth({ configId: 'your-api-key' });
+ * const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
  * ```
  */
-export { exchangeCodeForClaims, exchangeCodeForTokenAndClaims, verifyJwt, } from './client';
-export type { ExchangeCodeOptions, VerifyJwtOptions } from './client';
-export { fetchJwks, getKeyFromJwks } from './utils';
-export { HawcxOAuthError, InvalidPublicKeyError, OAuthExchangeError, JWTVerificationError, } from './exceptions';
+export { HawcxOAuth } from './oauth';
+export type { HawcxOAuthConfig, HawcxOAuthIssuerConfig, ExchangeResult, JwtClaims, DiscoveryMetadata, VerifyTokenOptions, } from './oauth';
+export { HawcxError, HawcxOAuthError, TokenExchangeError, TokenVerificationError, DiscoveryError, } from './errors';
+export type { HawcxOAuthErrorFields } from './errors';
+export { ClientAssertionSigner, CLIENT_ASSERTION_TYPE } from './client-assertion';
 export * from './delegation';
-export declare const VERSION = "0.1.0";
+export * from './stepup';
+export declare const VERSION = "5.1.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGtE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGpD,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,cAAc,cAAc,CAAC;AAE7B,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAGlF,cAAc,cAAc,CAAC;AAG7B,cAAc,UAAU,CAAC;AAEzB,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/index.js

@@ -2,20 +2,15 @@
 /**
  * Hawcx OAuth Client SDK
  *
- * A lightweight, production-ready Node.js library for exchanging OAuth authorization
- * codes and verifying JWT claims. Built with security, reliability, and ease of use in mind.
+ * Simple, production-ready SDK for exchanging authorization codes
+ * and verifying JWT tokens with Hawcx OAuth service.
  *
  * @example
  * ```typescript
- * import { exchangeCodeForClaims } from '@hawcx/oauth-client';
+ * import { HawcxOAuth } from '@hawcx/oauth-client';
  *
- * const claims = await exchangeCodeForClaims({
- *   code: 'abc123',
- *   oauthTokenUrl: 'https://oauth.example.com/token',
- *   clientId: 'my-app',
- *   publicKey: 'path/to/public.pem'
- * });
- * console.log(claims.sub); // 'user@example.com'
+ * const oauth = new HawcxOAuth({ configId: 'your-api-key' });
+ * const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
  * ```
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -33,23 +28,21 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.JWTVerificationError = exports.OAuthExchangeError = exports.InvalidPublicKeyError = exports.HawcxOAuthError = exports.getKeyFromJwks = exports.fetchJwks = exports.verifyJwt = exports.exchangeCodeForTokenAndClaims = exports.exchangeCodeForClaims = void 0;
-// Core OAuth client
-var client_1 = require("./client");
-Object.defineProperty(exports, "exchangeCodeForClaims", { enumerable: true, get: function () { return client_1.exchangeCodeForClaims; } });
-Object.defineProperty(exports, "exchangeCodeForTokenAndClaims", { enumerable: true, get: function () { return client_1.exchangeCodeForTokenAndClaims; } });
-Object.defineProperty(exports, "verifyJwt", { enumerable: true, get: function () { return client_1.verifyJwt; } });
-// JWKS utilities
-var utils_1 = require("./utils");
-Object.defineProperty(exports, "fetchJwks", { enumerable: true, get: function () { return utils_1.fetchJwks; } });
-Object.defineProperty(exports, "getKeyFromJwks", { enumerable: true, get: function () { return utils_1.getKeyFromJwks; } });
-// Exceptions
-var exceptions_1 = require("./exceptions");
-Object.defineProperty(exports, "HawcxOAuthError", { enumerable: true, get: function () { return exceptions_1.HawcxOAuthError; } });
-Object.defineProperty(exports, "InvalidPublicKeyError", { enumerable: true, get: function () { return exceptions_1.InvalidPublicKeyError; } });
-Object.defineProperty(exports, "OAuthExchangeError", { enumerable: true, get: function () { return exceptions_1.OAuthExchangeError; } });
-Object.defineProperty(exports, "JWTVerificationError", { enumerable: true, get: function () { return exceptions_1.JWTVerificationError; } });
+exports.VERSION = exports.CLIENT_ASSERTION_TYPE = exports.ClientAssertionSigner = exports.DiscoveryError = exports.TokenVerificationError = exports.TokenExchangeError = exports.HawcxOAuthError = exports.HawcxError = exports.HawcxOAuth = void 0;
+var oauth_1 = require("./oauth");
+Object.defineProperty(exports, "HawcxOAuth", { enumerable: true, get: function () { return oauth_1.HawcxOAuth; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "HawcxError", { enumerable: true, get: function () { return errors_1.HawcxError; } });
+Object.defineProperty(exports, "HawcxOAuthError", { enumerable: true, get: function () { return errors_1.HawcxOAuthError; } });
+Object.defineProperty(exports, "TokenExchangeError", { enumerable: true, get: function () { return errors_1.TokenExchangeError; } });
+Object.defineProperty(exports, "TokenVerificationError", { enumerable: true, get: function () { return errors_1.TokenVerificationError; } });
+Object.defineProperty(exports, "DiscoveryError", { enumerable: true, get: function () { return errors_1.DiscoveryError; } });
+var client_assertion_1 = require("./client-assertion");
+Object.defineProperty(exports, "ClientAssertionSigner", { enumerable: true, get: function () { return client_assertion_1.ClientAssertionSigner; } });
+Object.defineProperty(exports, "CLIENT_ASSERTION_TYPE", { enumerable: true, get: function () { return client_assertion_1.CLIENT_ASSERTION_TYPE; } });
 // Delegation module
 __exportStar(require("./delegation"), exports);
-exports.VERSION = '0.1.0';
+// Step-up module
+__exportStar(require("./stepup"), exports);
+exports.VERSION = '5.1.0';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;;;;;;;;;;;;;;;AAEH,oBAAoB;AACpB,mCAIkB;AAHhB,+GAAA,qBAAqB,OAAA;AACrB,uHAAA,6BAA6B,OAAA;AAC7B,mGAAA,SAAS,OAAA;AAIX,iBAAiB;AACjB,iCAAoD;AAA3C,kGAAA,SAAS,OAAA;AAAE,uGAAA,cAAc,OAAA;AAElC,aAAa;AACb,2CAKsB;AAJpB,6GAAA,eAAe,OAAA;AACf,mHAAA,qBAAqB,OAAA;AACrB,gHAAA,kBAAkB,OAAA;AAClB,kHAAA,oBAAoB,OAAA;AAGtB,oBAAoB;AACpB,+CAA6B;AAEhB,QAAA,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;;;;;;;;;;;;;;;AAEH,iCAAqC;AAA5B,mGAAA,UAAU,OAAA;AASnB,mCAMkB;AALhB,oGAAA,UAAU,OAAA;AACV,yGAAA,eAAe,OAAA;AACf,4GAAA,kBAAkB,OAAA;AAClB,gHAAA,sBAAsB,OAAA;AACtB,wGAAA,cAAc,OAAA;AAIhB,uDAAkF;AAAzE,yHAAA,qBAAqB,OAAA;AAAE,yHAAA,qBAAqB,OAAA;AAErD,oBAAoB;AACpB,+CAA6B;AAE7B,iBAAiB;AACjB,2CAAyB;AAEZ,QAAA,OAAO,GAAG,OAAO,CAAC"}

package/dist/oauth.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Hawcx OAuth Client
+ *
+ * Two construction paths:
+ *
+ *   1. OIDC discovery (recommended) — `HawcxOAuth.fromIssuer(...)` fetches
+ *      `<issuer>/.well-known/openid-configuration` once at startup and wires
+ *      up a verifier that enforces signature + iss + aud + exp + nbf on every
+ *      subsequent `verifyToken` call.
+ *
+ *   2. Legacy — `new HawcxOAuth({ configId, baseUrl })` hits the fixed
+ *      endpoints `/oauth2/token` and `/keys` directly. Backward-compatible
+ *      with v4.x callers, but does NOT verify `iss` or `aud` — the JWT's
+ *      signature is the only check.
+ *
+ * Both modes are safe to share across requests.
+ */
+import { type JWTPayload } from 'jose';
+import { ClientAssertionSigner } from './client-assertion';
+export interface HawcxOAuthConfig {
+    /** Your Hawcx config-id (sent as the `X-Config-Id` header on token exchange) */
+    configId: string;
+    /** Base URL override (default: https://api.hawcx.com) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /**
+     * Tolerated clock skew in seconds when verifying `exp` and `nbf` claims.
+     * Default 10. Set to 0 to require exact-time validation; raise above 10
+     * if you regularly see NTP drift between the issuer and this host.
+     * Spec.md §3.3.
+     */
+    clockToleranceSeconds?: number;
+}
+/**
+ * Options for the discovery-mode factory.
+ *
+ * **configId vs clientId.** Hawcx separates the tenant routing key from the
+ * audience claim — the SDK forwards each to the right place:
+ *
+ *   - `configId` — opaque per-tenant routing key. Sent verbatim as the
+ *     `X-Config-Id` header on the token-exchange POST so the OAuth server can
+ *     look up the tenant.
+ *   - `clientId` — whatever value the tenant has configured (in the Hawcx admin
+ *     console) as the `aud` claim on issued id_tokens. The verifier checks the
+ *     token's `aud` against this exact string.
+ *
+ * Passing the same value for both fails verification with an audience-mismatch
+ * error unless the tenant has configured them identically.
+ */
+export interface HawcxOAuthIssuerConfig {
+    /** Hawcx issuer URL (e.g. `https://api.hawcx.com`). Used for OIDC discovery and as the expected `iss` claim. */
+    issuer: string;
+    /** Hawcx tenant config-id; sent as the `X-Config-Id` header on token exchange. */
+    configId: string;
+    /** Hawcx project / tenant client-id; matched as the expected `aud` claim on id_tokens. */
+    clientId: string;
+    /** Per-request timeout in ms for token exchange and JWKS fetch (default: 10000) */
+    timeout?: number;
+    /** Timeout in ms for the one-shot discovery fetch (default: 5000) */
+    discoveryTimeout?: number;
+    /**
+     * Tolerated clock skew in seconds when verifying `exp` and `nbf` claims.
+     * Default 10. Set to 0 to require exact-time validation; raise above 10
+     * if you regularly see NTP drift between the issuer and this host.
+     * Spec.md §3.3.
+     */
+    clockToleranceSeconds?: number;
+}
+export interface JwtClaims extends JWTPayload {
+    /** Subject (user ID) */
+    sub?: string;
+    /** Issuer */
+    iss?: string;
+    /** Audience */
+    aud?: string | string[];
+    /** Issued at (unix timestamp) */
+    iat?: number;
+    /** Expiration (unix timestamp) */
+    exp?: number;
+    /** Not before (unix timestamp) */
+    nbf?: number;
+    /** JWT ID */
+    jti?: string;
+    /** Nonce */
+    nonce?: string;
+    /** Authentication methods */
+    amr?: string[];
+    /** MFA method used */
+    mfa_method?: string;
+    /** Email */
+    email?: string;
+    /** Name */
+    name?: string;
+}
+export interface ExchangeResult {
+    /** Raw id_token JWT */
+    idToken: string;
+    /** Verified JWT claims */
+    claims: JwtClaims;
+}
+/**
+ * Subset of the OIDC discovery document the SDK actually consumes.
+ * The raw response may include additional fields; they're preserved on
+ * `HawcxOAuth.discoveryMetadata` but the SDK only relies on these.
+ */
+export interface DiscoveryMetadata {
+    issuer: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    id_token_signing_alg_values_supported: string[];
+    [key: string]: unknown;
+}
+export interface VerifyTokenOptions {
+    /**
+     * If set, the JWT's `nonce` claim must equal this value. Use when your
+     * authorization request bound a nonce. Checked in both discovery and
+     * legacy modes — legacy mode skips `iss` / `aud` but the explicit nonce
+     * comparison applies unconditionally when this option is provided.
+     */
+    nonce?: string;
+}
+/**
+ * Hawcx OAuth Client
+ *
+ * Discovery-mode usage (recommended):
+ *
+ * ```typescript
+ * const oauth = await HawcxOAuth.fromIssuer({
+ *   issuer: 'https://api.hawcx.com',
+ *   configId: process.env.HAWCX_CONFIG_ID!,
+ *   clientId: process.env.HAWCX_CLIENT_ID!,
+ * });
+ * const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
+ * ```
+ *
+ * Legacy usage (no discovery; aud/iss are not checked):
+ *
+ * ```typescript
+ * const oauth = new HawcxOAuth({ configId: process.env.HAWCX_CONFIG_ID! });
+ * const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
+ * ```
+ */
+export declare class HawcxOAuth {
+    private readonly configId;
+    private readonly tokenEndpoint;
+    private readonly jwksUrl;
+    private readonly timeout;
+    private readonly clockToleranceSeconds;
+    /** Expected `aud` claim. `null` in legacy mode (audience is not checked). */
+    private readonly expectedAudience;
+    /** Expected `iss` claim. `null` in legacy mode (issuer is not checked). */
+    private readonly expectedIssuer;
+    /**
+     * id_token signing algorithms accepted by `verifyToken`. In discovery mode
+     * this is the intersection of the issuer's advertised algs with the SDK's
+     * closed allowlist ({@link DEFAULT_ID_TOKEN_ALGS}). `null` in legacy mode
+     * (we have no discovery doc to constrain against, so jose's default
+     * "accept whatever the JWKS provides" remains — same as 4.x).
+     */
+    private readonly allowedAlgorithms;
+    /** Resolved OIDC discovery document. `null` in legacy mode. */
+    readonly discoveryMetadata: DiscoveryMetadata | null;
+    private jwks;
+    /**
+     * Optional `private_key_jwt` signer (discovery mode only). `null` ⇒ the
+     * token exchange stays public-client + PKCE. Set via {@link withClientAssertion},
+     * which returns a *new* configured client (this field is `readonly`).
+     */
+    private readonly clientAssertionSigner;
+    /**
+     * Construct a legacy-mode client. For discovery mode, prefer
+     * {@link HawcxOAuth.fromIssuer}.
+     */
+    constructor(config: HawcxOAuthConfig);
+    /**
+     * Construct a client via OIDC discovery.
+     *
+     * Fetches `<issuer>/.well-known/openid-configuration`, reads the token
+     * endpoint, JWKS URI, and supported id_token signing algorithm, and wires
+     * a verifier that enforces signature + `iss` + `aud` + `exp` + `nbf` on
+     * subsequent {@link verifyToken} calls.
+     *
+     * **Discovery is bounded** at `discoveryTimeout` ms (default 5000) so an
+     * unreachable issuer fails fast with {@link DiscoveryError} rather than
+     * hanging your bootstrap.
+     *
+     * @throws {DiscoveryError} if discovery fails to resolve or the document
+     *   is missing required fields (`token_endpoint`, `jwks_uri`,
+     *   `id_token_signing_alg_values_supported`).
+     */
+    static fromIssuer(config: HawcxOAuthIssuerConfig): Promise<HawcxOAuth>;
+    /**
+     * Opt into `private_key_jwt` client authentication (discovery mode only).
+     * When set, the token exchange signs and attaches an RFC 7523
+     * `client_assertion` (in addition to PKCE). Without it, the exchange stays
+     * public-client + PKCE.
+     *
+     * Intended to be called once right after {@link fromIssuer}, before the
+     * client is shared. Returns `this` for chaining.
+     */
+    /**
+     * @beta Experimental `private_key_jwt` surface; may change before stable.
+     *
+     * Returns a **new** discovery-mode client configured with the signer (sharing
+     * this client's resolved discovery state); the original is unchanged, so a
+     * configured client is immutable. Chained usage
+     * (`(await fromIssuer(...)).withClientAssertion(...)`) is unaffected.
+     *
+     * Refuses if the OP's discovery doc advertises
+     * `token_endpoint_auth_methods_supported` without `private_key_jwt`
+     * (the assertion would be silently ignored).
+     */
+    withClientAssertion(signer: ClientAssertionSigner): HawcxOAuth;
+    /**
+     * Exchange authorization code for id_token and verified claims.
+     *
+     * @param code - Authorization code from auth flow
+     * @param codeVerifier - PKCE code verifier
+     * @param redirectUri - Optional. If your original authorization request
+     *   registered a `redirect_uri`, RFC 6749 §4.1.3 requires the token
+     *   request to carry the same value. Omit if the auth request also omitted it.
+     * @param expectedNonce - Optional. If your authorization request bound a
+     *   `nonce`, pass it here so the returned id_token's `nonce` is verified.
+     *   Required whenever the token carries a nonce (verification refuses
+     *   otherwise — OIDC Core §3.1.3.7).
+     */
+    exchangeCode(code: string, codeVerifier: string, redirectUri?: string, expectedNonce?: string): Promise<ExchangeResult>;
+    /**
+     * Verify a JWT token and return its claims.
+     *
+     * In **discovery mode**, enforces signature + `iss` + `aud` + `exp` + `nbf`
+     * (and the optional `nonce` claim if `options.nonce` is provided).
+     *
+     * In **legacy mode**, only the signature is verified. Audience and issuer
+     * claims are not checked, matching the pre-5.x behavior.
+     */
+    verifyToken(token: string, options?: VerifyTokenOptions): Promise<JwtClaims>;
+    /**
+     * Get or create the remote JWKS. jose handles caching + concurrent-fetch
+     * coalescing internally.
+     *
+     * No single-flight guard is needed here: this method is fully synchronous
+     * (no `await` between the null-check and the assignment), so within Node's
+     * single-threaded event loop the first caller assigns `this.jwks` before any
+     * other code runs. Two concurrent `verifyToken` calls therefore cannot create
+     * duplicate `RemoteJWKSet` instances.
+     */
+    private getJwks;
+    /**
+     * Drop the cached JWKS so the next `verifyToken` re-fetches it. Useful after
+     * an operator-triggered signing-key rotation, or in tests.
+     *
+     * Canonical name, aligned with the Java (`refreshJwks`) and Python
+     * (`refresh_jwks`) SDKs.
+     */
+    refreshJwks(): void;
+    /**
+     * @deprecated since 5.1.0 — renamed to {@link refreshJwks} for cross-SDK
+     *   consistency. Will be removed in 6.0.0. Behaviour is identical.
+     */
+    clearCache(): void;
+    private clearCacheWarned;
+}
+//# sourceMappingURL=oauth.d.ts.map