Node.js SDK API Reference

The SDK exposes two construction paths on HawcxOAuth:

Both modes share the same exchangeCode / verifyToken / refreshJwks methods.

HawcxOAuth (discovery mode)

HawcxOAuth.fromIssuer(config)

Async factory. Fetches <issuer>/.well-known/openid-configuration once at construction, reads the token endpoint + JWKS URI + supported id_token signing algorithm, and wires a verifier that enforces signature, iss, aud, exp, and nbf on subsequent verifyToken calls.

import { HawcxOAuth } from '@hawcx/oauth-client';

const oauth = await HawcxOAuth.fromIssuer({
  issuer: process.env.HAWCX_BASE_URL!,     // discovery + expected `iss`
  configId: process.env.HAWCX_CONFIG_ID!,  // → X-Config-Id header
  clientId: process.env.HAWCX_CLIENT_ID!,  // → expected `aud` on id_tokens
});

Config:

Throws DiscoveryError if the discovery document is unreachable, returns non-2xx, isn't valid JSON, or is missing any of token_endpoint, jwks_uri, id_token_signing_alg_values_supported. The underlying network / parse error is preserved as err.cause.

oauth.discoveryMetadata

The resolved OIDC discovery document. Useful for diagnostics — confirm which endpoints and signing algs were picked up.

oauth.discoveryMetadata?.token_endpoint;
oauth.discoveryMetadata?.jwks_uri;
oauth.discoveryMetadata?.id_token_signing_alg_values_supported;

null on clients constructed via the legacy constructor.

HawcxOAuth (legacy mode)

For 4.x callers; new code should prefer the discovery path above.

import { HawcxOAuth } from '@hawcx/oauth-client';

const oauth = new HawcxOAuth({
  configId: process.env.HAWCX_CONFIG_ID!,
  baseUrl: process.env.HAWCX_BASE_URL!,
  timeout: 10_000,
});

Config:

Verifies signature + exp + nbf. iss and aud are not checked (the legacy constructor has no way to know what to expect).

Shared methods

exchangeCode(code, codeVerifier, redirectUri?)

Exchange an authorization code for verified claims.

const { idToken, claims } = await oauth.exchangeCode(authCode, codeVerifier);

// With redirect_uri (RFC 6749 §4.1.3) when your auth request registered one:
const { idToken, claims } = await oauth.exchangeCode(
  authCode,
  codeVerifier,
  'https://app.example.com/auth/callback',
);

Returns:

verifyToken(token, options?)

Verify a JWT and return its claims.

• Discovery mode enforces signature + iss + aud + exp + nbf.
• Legacy mode enforces signature + exp + nbf. iss and aud are not checked — the legacy SDK has no way to know what to expect.
• options.nonce is checked in both modes when provided. If the token's nonce claim doesn't match, TokenVerificationError is thrown regardless of construction path.

const claims = await oauth.verifyToken(idToken);

// With expected nonce, when your auth request bound one:
const claims = await oauth.verifyToken(idToken, { nonce: 'expected-nonce' });

refreshJwks()

Refresh the JWKS cache (useful for key rotation or tests).

oauth.refreshJwks();

Error Types

import {
  HawcxOAuthError,
  DiscoveryError,
  TokenExchangeError,
  TokenVerificationError,
} from '@hawcx/oauth-client';

• DiscoveryError — fromIssuer could not resolve a usable discovery document. Underlying network / parse error is preserved as err.cause.
• TokenExchangeError — code exchange failed (invalid/expired code, network error, missing id_token in response). Carries statusCode.
• TokenVerificationError — JWT verification failed. Messages include Token expired, Invalid signature, Token not yet valid, and (in discovery mode) Unexpected JWT audience / Unexpected JWT issuer.

Step-Up Client (Management API)

StepUpClient is the entry point for the management / step-up API (/v1/management/*) — startToken and consumeReceipt.

StepUpClient.withPrivateKeyJwt(options) (recommended)

Mints a short-lived per-request EdDSA Bearer JWT (iss = sub = clientId, aud = the full endpoint URL, ~60s lifetime, random jti, and a body_sha256 claim that binds the JWT to the exact request body bytes). Routing uses the X-Config-Id header.

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.

import { StepUpClient } from '@hawcx/oauth-client';

const privateJwk = JSON.parse(process.env.HAWCX_PRIVATE_JWK!); // OKP/Ed25519, with kid

const stepUp = StepUpClient.withPrivateKeyJwt({
  baseUrl: 'https://api.hawcx.com',
  configId: process.env.HAWCX_CONFIG_ID!,   // X-Config-Id tenant routing
  clientId: process.env.HAWCX_CLIENT_ID!,   // iss/sub in the per-request JWT
  oidcSigningKey: privateJwk,               // same key as your OIDC ClientAssertionSigner
  kid: privateJwk.kid,
});

// Begin a step-up flow
const { start_token, expires_in } = await stepUp.startToken({
  userId: '[email protected]',
  purpose: 'change_mfa_method',
  newMfaMethod: 'totp',   // 'email_otp' | 'sms_otp' | 'totp'
});

// Finalize after the user completes the MFA challenge
const { ok } = await stepUp.consumeReceipt({
  receipt: 'step-up-receipt-from-client',
});

Options (StepUpClientPrivateKeyJwtOptions):

The step-up base options (apiPrefix, default /v1; relyingParty; extraHeaders; tenantHeaderName / tenantHeaderValue, sent as a request header when both are set) are accepted too.

Response signature verification

Since 6.0.0 the SDK verifies every successful management response before returning it. Each 2xx response carries an X-Response-Signature header, a compact JWS signed with the same key the OIDC JWKS publishes. The SDK accepts the response only when:

• the JWS uses ES256, ES384 or ES512 (the algorithm follows the curve of the signing key; production uses ES512) and verifies against {issuer}/.well-known/jwks.json;
• its body_sha256 claim matches the SHA-256 of the exact response bytes;
• its iat is within clockSkewSeconds of local time;
• it carries no aud, sub or nonce claim, so an ID token signed by the same key cannot pass as a response signature.

Responses with status 400 and above are not signed and are not verified.

By default the JWKS is fetched from {baseUrl}/.well-known/jwks.json, because the management API and the OIDC issuer share one host in every Hawcx environment. Set issuer only if your baseUrl is not that host, for example an internal gateway URL or local development with separate ports.

Verification detects a response that was changed in transit, for example by a proxy that terminates TLS. Because the keys come from the same origin as the API by default, it does not protect against someone who can impersonate that origin itself. The signature binds the response body, not the request it answers.

A failure throws one of two errors, both subclasses of DelegationResponseError with a stable code:

import {
  ResponseSignatureInvalidError,
  ResponseSignatureUnavailableError,
} from '@hawcx/oauth-client';

try {
  await stepUp.consumeReceipt({ receipt });
} catch (err) {
  if (err instanceof ResponseSignatureUnavailableError) {
    // err.code === 'response_signature_unavailable'
    // The signing keys could not be fetched. The request may already have been
    // applied server-side: reconcile state before retrying.
  } else if (err instanceof ResponseSignatureInvalidError) {
    // err.code === 'response_signature_invalid'
    // Missing or bad signature. Treat the response as untrusted.
  }
  throw err;
}

URL rules

Every base URL the SDK sends credentials to is validated at construction: baseUrl and issuer here, the ECIES fromSecretKey / fromKeys factories, the legacy new HawcxOAuth({ baseUrl }) and HawcxOAuth.fromIssuer. Since 6.0.0 a base URL must:

• use https:. Plain http: is accepted only for localhost, 127.0.0.1 and [::1];
• carry no userinfo (user:pw@), query or fragment.

It may include a path prefix, such as https://gateway.example.com/hawcx. Request URLs are joined structurally and must stay on the base's origin and under that prefix. An invalid value throws DelegationRequestError from the management clients, HawcxOAuthError from the legacy constructor and DiscoveryError from fromIssuer.

Host case and default ports are normalised, so https://API.Hawcx.com:443 and https://api.hawcx.com produce the same request URL and the same signed aud.

StepUpClient.fromSecretKey(options) (legacy, deprecated)

// 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',
});

Delegation Client

Use the delegation client for backend-driven MFA setup and user/device management.

DelegationClient.fromSecretKey(options)

import { DelegationClient } from '@hawcx/oauth-client';

const client = DelegationClient.fromSecretKey({
  secretKey: process.env.HAWCX_SECRET_KEY!,
  baseUrl: process.env.HAWCX_BASE_URL!,
  apiKey: process.env.HAWCX_CONFIG_ID
});

DelegationClient.fromKeys(options)

const client = DelegationClient.fromKeys({
  spSigningKey: process.env.SP_ED25519_PRIVATE_KEY_PEM!,
  spEncryptionKey: process.env.SP_X25519_PRIVATE_KEY_PEM!,
  idpVerifyKey: process.env.IDP_ED25519_PUBLIC_KEY_PEM!,
  idpEncryptionKey: process.env.IDP_X25519_PUBLIC_KEY_PEM!,
  spKid: process.env.SP_KEY_ID!,
  idpKid: process.env.IDP_KEY_ID!,
  baseUrl: process.env.HAWCX_BASE_URL!,
  apiKey: process.env.HAWCX_CONFIG_ID
});

MFA

import { MfaMethod } from '@hawcx/oauth-client';

const result = await client.mfa.initiate({
  userId: '[email protected]',
  mfaMethod: MfaMethod.SMS,
  phoneNumber: '+15551234567'
});

await client.mfa.verify({
  userId: '[email protected]',
  sessionId: result.session_id,
  otp: '123456'
});

Users

const creds = await client.users.getCredentials('[email protected]');

Devices

const devices = await client.devices.list('[email protected]');
await client.devices.revoke({ userId: '[email protected]', deviceId: 'h2index' });