@connectid-tools/rp-nodejs-sdk 4.2.1 → 5.0.1

package/endpoints/retrieve-token-endpoint.d.ts

@@ -0,0 +1,66 @@
+import { Agent } from 'undici';
+import { Logger } from 'winston';
+import { CallbackParams, RelyingPartyClientSdkConfig } from '../types.js';
+import { JwtHelper } from '../crypto/jwt-helper.js';
+import { ConsolidatedTokenSet } from '../model/consolidated-token-set.js';
+import { ParticipantsEndpoint } from './participants-endpoint';
+/**
+ * Retrieve Token Endpoint
+ *
+ * Handles the token exchange flow (authorization code for tokens).
+ * Validates the ID token and optionally calls UserInfo for compliance.
+ */
+export declare class RetrieveTokenEndpoint {
+    private readonly sdkConfig;
+    private readonly httpClient;
+    private readonly jwtHelper;
+    private readonly logger;
+    private readonly participantsEndpoint;
+    constructor(sdkConfig: RelyingPartyClientSdkConfig, httpClient: Agent, jwtHelper: JwtHelper, logger: Logger, participantsEndpoint: ParticipantsEndpoint);
+    /**
+     * Retrieves tokens from the authorization server.
+     *
+     * Performs the following steps:
+     * 1. Validates callback parameters
+     * 2. Exchanges authorization code for tokens
+     * 3. Validates ID token
+     * 4. Optionally calls UserInfo for compliance
+     *
+     * @param authorisationServerId - Authorization server id
+     * @param callbackParams - OAuth callback parameters from redirect
+     * @param codeVerifier - PKCE code verifier from PAR
+     * @param state - State parameter from PAR
+     * @param nonce - Nonce parameter from PAR
+     * @returns Consolidated token set with validated claims
+     */
+    retrieveTokens(authorisationServerId: string, callbackParams: CallbackParams, codeVerifier: string, state: string, nonce: string): Promise<ConsolidatedTokenSet>;
+    /**
+     * Validates the OAuth callback parameters.
+     *
+     * @param callbackParams - Callback parameters from redirect
+     * @param expectedState - Expected state value
+     * @throws Error if validation fails
+     */
+    private validateCallbackParams;
+    /**
+     * Requests tokens from the token endpoint.
+     *
+     * @param tokenEndpoint - Token endpoint URL
+     * @param code - Authorization code from callback
+     * @param codeVerifier - PKCE code verifier
+     * @param clientAssertion - Client assertion JWT for authentication
+     * @param xFapiInteractionId - FAPI interaction ID
+     * @returns Token response
+     */
+    private requestToken;
+    /**
+     * Calls the UserInfo endpoint for compliance verification.
+     *
+     * This is required by some conformance test suites.
+     *
+     * @param userinfoEndpoint - UserInfo endpoint URL
+     * @param accessToken - Access token
+     * @param xFapiInteractionId - FAPI interaction ID
+     */
+    private callUserInfoForCompliance;
+}

package/endpoints/retrieve-token-endpoint.js

@@ -0,0 +1,159 @@
+import { DiscoveryService } from '../model/discovery-service.js';
+import { HttpClientExtensions } from '../http/http-client-extensions.js';
+import { TokenSet } from '../model/token-set.js';
+import { ConsolidatedTokenSet } from '../model/consolidated-token-set.js';
+import { generateXFapiInteractionId } from '../fapi/fapi-utils.js';
+/**
+ * Retrieve Token Endpoint
+ *
+ * Handles the token exchange flow (authorization code for tokens).
+ * Validates the ID token and optionally calls UserInfo for compliance.
+ */
+export class RetrieveTokenEndpoint {
+    constructor(sdkConfig, httpClient, jwtHelper, logger, participantsEndpoint) {
+        this.sdkConfig = sdkConfig;
+        this.httpClient = httpClient;
+        this.jwtHelper = jwtHelper;
+        this.logger = logger;
+        this.participantsEndpoint = participantsEndpoint;
+    }
+    /**
+     * Retrieves tokens from the authorization server.
+     *
+     * Performs the following steps:
+     * 1. Validates callback parameters
+     * 2. Exchanges authorization code for tokens
+     * 3. Validates ID token
+     * 4. Optionally calls UserInfo for compliance
+     *
+     * @param authorisationServerId - Authorization server id
+     * @param callbackParams - OAuth callback parameters from redirect
+     * @param codeVerifier - PKCE code verifier from PAR
+     * @param state - State parameter from PAR
+     * @param nonce - Nonce parameter from PAR
+     * @returns Consolidated token set with validated claims
+     */
+    async retrieveTokens(authorisationServerId, callbackParams, codeVerifier, state, nonce) {
+        const xFapiInteractionId = generateXFapiInteractionId();
+        try {
+            this.logger.info(`Retrieving tokens for auth server: ${authorisationServerId}`);
+            // Validate callback parameters
+            this.validateCallbackParams(callbackParams, state);
+            const authServer = await this.participantsEndpoint.getAuthServerDetails(authorisationServerId);
+            // Fetch discovery document
+            const discoveryMetadata = await DiscoveryService.fetchDiscoveryDocument(authServer.OpenIDDiscoveryDocument, this.httpClient);
+            // Validate issuer parameter (REQUIRED per FAPI 2.0)
+            if (!callbackParams.iss) {
+                throw new Error('Authorization response missing required iss parameter');
+            }
+            if (callbackParams.iss !== discoveryMetadata.issuer) {
+                throw new Error(`Issuer mismatch: expected ${discoveryMetadata.issuer}, got ${callbackParams.iss}`);
+            }
+            // Create client assertion for authentication
+            const clientAssertion = await this.jwtHelper.generateClientAssertionJwt(discoveryMetadata.issuer);
+            // Exchange authorization code for tokens
+            const tokenResponse = await this.requestToken(discoveryMetadata.token_endpoint, callbackParams.code, codeVerifier, clientAssertion, xFapiInteractionId);
+            const tokenSet = new TokenSet(tokenResponse);
+            const jwks = await DiscoveryService.fetchJwks(discoveryMetadata.jwks_uri, this.httpClient);
+            await tokenSet.validate(jwks, discoveryMetadata.issuer, this.sdkConfig.data.client_id, nonce, discoveryMetadata.id_token_signing_alg_values_supported);
+            // Must call validate first before accessing claims
+            this.logger.info(`Retrieved tokenSet from auth server: ${authorisationServerId} - ${authServer.CustomerFriendlyName}, x-fapi-interaction-id: ${xFapiInteractionId}, txn: ${tokenSet.claims().txn}`);
+            this.logger.debug(`Tokens returned from: ${authorisationServerId} - ${authServer.CustomerFriendlyName}: ${JSON.stringify(tokenSet)} claims: ${JSON.stringify(tokenSet.claims())}`);
+            const consolidatedTokenSet = new ConsolidatedTokenSet(tokenSet, xFapiInteractionId);
+            // If using the OIDF test suite, need to make a call to userInfo when claims were successfully decoded
+            if (this.sdkConfig.data.enable_auto_compliance_verification) {
+                this.logger.warn('Auto compliance verification mode is enabled - calling UserInfo endpoint. This mode should only be enabled while performing OIDF conformance suite testing and will cause issues if used in production.');
+                if (!tokenSet.access_token) {
+                    throw new Error('Cannot call UserInfo: no access token present');
+                }
+                if (!discoveryMetadata.userinfo_endpoint) {
+                    throw new Error('Authorization server does not have a UserInfo endpoint');
+                }
+                // Call UserInfo endpoint for compliance
+                await this.callUserInfoForCompliance(discoveryMetadata.userinfo_endpoint, tokenSet.access_token, xFapiInteractionId);
+            }
+            return consolidatedTokenSet;
+        }
+        catch (err) {
+            this.logger.error(`Error retrieving tokens with authorisation server ${authorisationServerId}, x-fapi-interaction-id: ${xFapiInteractionId}`, err);
+            throw new Error(`Unable to retrieve tokens with authorisation server ${authorisationServerId}, x-fapi-interaction-id: ${xFapiInteractionId}`);
+        }
+    }
+    /**
+     * Validates the OAuth callback parameters.
+     *
+     * @param callbackParams - Callback parameters from redirect
+     * @param expectedState - Expected state value
+     * @throws Error if validation fails
+     */
+    validateCallbackParams(callbackParams, expectedState) {
+        // Check for error response
+        if (callbackParams.error) {
+            throw new Error(`Authorization failed: ${callbackParams.error}${callbackParams.error_description ? ` - ${callbackParams.error_description}` : ''}`);
+        }
+        // Validate code is present
+        if (!callbackParams.code) {
+            throw new Error('Authorization code missing from callback parameters');
+        }
+        // Validate state
+        if (!callbackParams.state) {
+            throw new Error('State parameter missing from callback parameters');
+        }
+        if (callbackParams.state !== expectedState) {
+            throw new Error(`State mismatch: expected ${expectedState}, got ${callbackParams.state}`);
+        }
+    }
+    /**
+     * Requests tokens from the token endpoint.
+     *
+     * @param tokenEndpoint - Token endpoint URL
+     * @param code - Authorization code from callback
+     * @param codeVerifier - PKCE code verifier
+     * @param clientAssertion - Client assertion JWT for authentication
+     * @param xFapiInteractionId - FAPI interaction ID
+     * @returns Token response
+     */
+    async requestToken(tokenEndpoint, code, codeVerifier, clientAssertion, xFapiInteractionId) {
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: this.sdkConfig.data.application_redirect_uri,
+            code_verifier: codeVerifier,
+            client_assertion: clientAssertion,
+            client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+        });
+        this.logger.debug(`Requesting tokens from: ${tokenEndpoint}`);
+        this.logger.debug(`  with body: ${body}`);
+        const response = await HttpClientExtensions.postForm(tokenEndpoint, body, {
+            agent: this.httpClient,
+            clientId: this.sdkConfig.data.client_id,
+            xFapiInteractionId,
+        });
+        return HttpClientExtensions.parseJsonResponse(response);
+    }
+    /**
+     * Calls the UserInfo endpoint for compliance verification.
+     *
+     * This is required by some conformance test suites.
+     *
+     * @param userinfoEndpoint - UserInfo endpoint URL
+     * @param accessToken - Access token
+     * @param xFapiInteractionId - FAPI interaction ID
+     */
+    async callUserInfoForCompliance(userinfoEndpoint, accessToken, xFapiInteractionId) {
+        try {
+            const response = await HttpClientExtensions.getWithToken(userinfoEndpoint, accessToken, {
+                agent: this.httpClient,
+                clientId: this.sdkConfig.data.client_id,
+                xFapiInteractionId,
+            });
+            const userInfo = await HttpClientExtensions.parseJsonResponse(response);
+            this.logger.debug(`UserInfo response: ${JSON.stringify(userInfo, null, 2)}`);
+            this.logger.info('UserInfo endpoint called successfully for compliance: ' + userinfoEndpoint);
+        }
+        catch (error) {
+            this.logger.warn(`UserInfo call failed (compliance verification): ${error instanceof Error ? error.message : String(error)}`);
+            // Don't throw - this is just for compliance, not critical
+        }
+    }
+}

package/endpoints/userinfo-endpoint.d.ts

@@ -0,0 +1,24 @@
+import { Agent } from 'undici';
+import { Logger } from 'winston';
+import { ParticipantsEndpoint } from './participants-endpoint';
+/**
+ * UserInfo Endpoint
+ *
+ * Handles calls to the OIDC UserInfo endpoint.
+ * Returns user claims using an access token.
+ */
+export declare class UserInfoEndpoint {
+    private readonly httpClient;
+    private readonly logger;
+    private readonly clientId;
+    private readonly participantsEndpoint;
+    constructor(httpClient: Agent, logger: Logger, clientId: string, participantsEndpoint: ParticipantsEndpoint);
+    /**
+     * Retrieves user information from the UserInfo endpoint.
+     *
+     * @param authorisationServerId - Authorization server id
+     * @param accessToken - Access token to authenticate the request
+     * @returns UserInfo claims
+     */
+    getUserInfo(authorisationServerId: string, accessToken: string): Promise<Record<string, unknown>>;
+}

package/endpoints/userinfo-endpoint.js

@@ -0,0 +1,50 @@
+import { DiscoveryService } from '../model/discovery-service.js';
+import { HttpClientExtensions } from '../http/http-client-extensions.js';
+import { generateXFapiInteractionId } from '../fapi/fapi-utils.js';
+/**
+ * UserInfo Endpoint
+ *
+ * Handles calls to the OIDC UserInfo endpoint.
+ * Returns user claims using an access token.
+ */
+export class UserInfoEndpoint {
+    constructor(httpClient, logger, clientId, participantsEndpoint) {
+        this.httpClient = httpClient;
+        this.logger = logger;
+        this.clientId = clientId;
+        this.participantsEndpoint = participantsEndpoint;
+    }
+    /**
+     * Retrieves user information from the UserInfo endpoint.
+     *
+     * @param authorisationServerId - Authorization server id
+     * @param accessToken - Access token to authenticate the request
+     * @returns UserInfo claims
+     */
+    async getUserInfo(authorisationServerId, accessToken) {
+        this.logger.info(`Fetching UserInfo for auth server: ${authorisationServerId}`);
+        const xFapiInteractionId = generateXFapiInteractionId();
+        try {
+            const authServer = await this.participantsEndpoint.getAuthServerDetails(authorisationServerId);
+            // Fetch discovery document
+            const discoveryMetadata = await DiscoveryService.fetchDiscoveryDocument(authServer.OpenIDDiscoveryDocument, this.httpClient);
+            if (!discoveryMetadata.userinfo_endpoint) {
+                throw new Error(`Authorization server ${authServer.AuthorisationServerId} does not have a UserInfo endpoint`);
+            }
+            // Call UserInfo endpoint
+            const response = await HttpClientExtensions.getWithToken(discoveryMetadata.userinfo_endpoint, accessToken, {
+                agent: this.httpClient,
+                clientId: this.clientId,
+                xFapiInteractionId,
+            });
+            const userInfo = await HttpClientExtensions.parseJsonResponse(response);
+            this.logger.info(`UserInfo retrieved successfully, x-fapi-interaction-id: ${xFapiInteractionId}`);
+            this.logger.debug(`UserInfo claims: ${JSON.stringify(userInfo, null, 2)}`);
+            return userInfo;
+        }
+        catch (err) {
+            this.logger.error(`Error calling user info authorisation server ${authorisationServerId}, x-fapi-interaction-id: ${xFapiInteractionId}`, err);
+            throw new Error(`Unable to  calling user info with authorisation server ${authorisationServerId}, x-fapi-interaction-id: ${xFapiInteractionId}`);
+        }
+    }
+}

package/fapi/fapi-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generates a unique x-fapi-interaction-id.
+ *
+ * @returns UUID string
+ */
+export declare const generateXFapiInteractionId: () => `${string}-${string}-${string}-${string}-${string}`;

package/fapi/fapi-utils.js

@@ -0,0 +1,9 @@
+import { randomUUID } from 'crypto';
+/**
+ * Generates a unique x-fapi-interaction-id.
+ *
+ * @returns UUID string
+ */
+export const generateXFapiInteractionId = () => {
+    return randomUUID();
+};

package/http/http-client-extensions.d.ts

@@ -0,0 +1,60 @@
+import { Agent, Dispatcher } from 'undici';
+export interface UndiciRequestInit extends RequestInit {
+    dispatcher?: Dispatcher;
+}
+export interface FetchOptions extends UndiciRequestInit {
+    agent?: Agent;
+}
+export interface FapiRequestOptions {
+    agent: Agent;
+    clientId: string;
+    xFapiInteractionId: string;
+    contentType?: string;
+    additionalHeaders?: Record<string, string>;
+}
+/**
+ * Utility functions for making HTTP requests with the configured mTLS client.
+ */
+export declare class HttpClientExtensions {
+    /**
+     * Creates standard headers for FAPI requests.
+     *
+     * @param options - Request configuration including client ID and interaction ID
+     * @returns Headers object with required FAPI headers
+     */
+    static createFapiHeaders(options: FapiRequestOptions): HeadersInit;
+    /**
+     * Makes a POST request with form-encoded body.
+     *
+     * @param url - Target URL
+     * @param body - Form data as URLSearchParams
+     * @param options - Request options including agent and headers
+     * @returns Response promise
+     */
+    static postForm(url: string, body: URLSearchParams, options: FapiRequestOptions): Promise<Response>;
+    /**
+     * Makes a GET request with FAPI headers.
+     *
+     * @param url - Target URL
+     * @param options - Request options including agent and headers
+     * @returns Response promise
+     */
+    static get(url: string, options: FapiRequestOptions): Promise<Response>;
+    /**
+     * Makes a GET request with Bearer token authentication.
+     *
+     * @param url - Target URL
+     * @param accessToken - Bearer access token
+     * @param options - Request options including agent and headers
+     * @returns Response promise
+     */
+    static getWithToken(url: string, accessToken: string, options: FapiRequestOptions): Promise<Response>;
+    /**
+     * Parses a JSON response body.
+     *
+     * @param response - Fetch response
+     * @returns Parsed JSON object
+     * @throws Error if response is not OK or JSON parsing fails
+     */
+    static parseJsonResponse<T = unknown>(response: Response): Promise<T>;
+}

package/http/http-client-extensions.js

@@ -0,0 +1,106 @@
+import { buildUserAgent } from '../utils/user-agent.js';
+/**
+ * Utility functions for making HTTP requests with the configured mTLS client.
+ */
+export class HttpClientExtensions {
+    /**
+     * Creates standard headers for FAPI requests.
+     *
+     * @param options - Request configuration including client ID and interaction ID
+     * @returns Headers object with required FAPI headers
+     */
+    static createFapiHeaders(options) {
+        const headers = {
+            'User-Agent': buildUserAgent(options.clientId),
+            'x-fapi-interaction-id': options.xFapiInteractionId,
+        };
+        if (options.contentType) {
+            headers['Content-Type'] = options.contentType;
+        }
+        if (options.additionalHeaders) {
+            Object.assign(headers, options.additionalHeaders);
+        }
+        return headers;
+    }
+    /**
+     * Makes a POST request with form-encoded body.
+     *
+     * @param url - Target URL
+     * @param body - Form data as URLSearchParams
+     * @param options - Request options including agent and headers
+     * @returns Response promise
+     */
+    static async postForm(url, body, options) {
+        const headers = this.createFapiHeaders({
+            ...options,
+            contentType: 'application/x-www-form-urlencoded',
+        });
+        return fetch(url, {
+            method: 'POST',
+            headers,
+            body: body.toString(),
+            dispatcher: options.agent, // undici uses 'dispatcher' instead of 'agent'
+            redirect: 'manual', // Don't follow redirects automatically
+        });
+    }
+    /**
+     * Makes a GET request with FAPI headers.
+     *
+     * @param url - Target URL
+     * @param options - Request options including agent and headers
+     * @returns Response promise
+     */
+    static async get(url, options) {
+        const headers = this.createFapiHeaders(options);
+        return fetch(url, {
+            method: 'GET',
+            headers,
+            dispatcher: options.agent, // undici uses 'dispatcher' instead of 'agent'
+            redirect: 'manual',
+        });
+    }
+    /**
+     * Makes a GET request with Bearer token authentication.
+     *
+     * @param url - Target URL
+     * @param accessToken - Bearer access token
+     * @param options - Request options including agent and headers
+     * @returns Response promise
+     */
+    static async getWithToken(url, accessToken, options) {
+        const headers = this.createFapiHeaders({
+            ...options,
+            additionalHeaders: {
+                ...options.additionalHeaders,
+                Authorization: `Bearer ${accessToken}`,
+            },
+        });
+        return fetch(url, {
+            method: 'GET',
+            headers,
+            dispatcher: options.agent, // undici uses 'dispatcher' instead of 'agent'
+            redirect: 'manual',
+        });
+    }
+    /**
+     * Parses a JSON response body.
+     *
+     * @param response - Fetch response
+     * @returns Parsed JSON object
+     * @throws Error if response is not OK or JSON parsing fails
+     */
+    static async parseJsonResponse(response) {
+        if (!response.ok) {
+            let errorDetails = '';
+            try {
+                const errorBody = await response.text();
+                errorDetails = errorBody ? `: ${errorBody}` : '';
+            }
+            catch {
+                // Ignore errors when reading error body
+            }
+            throw new Error(`HTTP request failed: ${response.status} ${response.statusText}${errorDetails}`);
+        }
+        return await response.json();
+    }
+}

package/http/http-client-factory.d.ts

@@ -0,0 +1,27 @@
+import { Agent } from 'undici';
+export interface HttpClientConfig {
+    transportKey: string | Buffer;
+    transportPem: string | Buffer;
+    caPem: string | Buffer;
+    clientId: string;
+}
+/**
+ * Factory for creating HTTP clients with mTLS support.
+ *
+ * This factory creates undici.Agent instances configured with:
+ * - Mutual TLS (mTLS) using transport certificates
+ * - CA certificate chain validation
+ * - Appropriate timeouts for OIDC/FAPI operations
+ */
+export declare class HttpClientFactory {
+    /**
+     * Creates an undici Agent configured for mTLS operations.
+     *
+     * undici.Agent is used instead of https.Agent because Node.js's
+     * native fetch API properly supports mTLS when using undici's Agent.
+     *
+     * @param config - Configuration containing certificates and client ID
+     * @returns Configured undici.Agent for use with fetch
+     */
+    static createClient(config: HttpClientConfig): Agent;
+}

package/http/http-client-factory.js

@@ -0,0 +1,45 @@
+import { Agent } from 'undici';
+import { rootCertificates } from 'node:tls';
+/**
+ * Factory for creating HTTP clients with mTLS support.
+ *
+ * This factory creates undici.Agent instances configured with:
+ * - Mutual TLS (mTLS) using transport certificates
+ * - CA certificate chain validation
+ * - Appropriate timeouts for OIDC/FAPI operations
+ */
+export class HttpClientFactory {
+    /**
+     * Creates an undici Agent configured for mTLS operations.
+     *
+     * undici.Agent is used instead of https.Agent because Node.js's
+     * native fetch API properly supports mTLS when using undici's Agent.
+     *
+     * @param config - Configuration containing certificates and client ID
+     * @returns Configured undici.Agent for use with fetch
+     */
+    static createClient(config) {
+        // Combine custom CA with system root certificates
+        const caCerts = [config.caPem, ...rootCertificates].join('\n');
+        return new Agent({
+            // mTLS client certificate and key
+            connect: {
+                cert: config.transportPem,
+                key: config.transportKey,
+                ca: caCerts,
+                rejectUnauthorized: true,
+                // Request certificate from server
+                requestCert: true,
+            },
+            // Timeout configuration (60 seconds)
+            bodyTimeout: 60000,
+            headersTimeout: 60000,
+            connectTimeout: 60000,
+            // Keep connections alive for performance
+            keepAliveTimeout: 30000,
+            keepAliveMaxTimeout: 60000,
+            // Connection pooling
+            connections: 50,
+        });
+    }
+}

package/model/callback-params.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OAuth 2.0 Authorization Response Parameters
+ *
+ * Parameters returned to the redirect URI after authorization.
+ */
+export interface CallbackParams {
+    /**
+     * The authorization code generated by the authorization server.
+     */
+    code?: string;
+    /**
+     * The state parameter from the authorization request.
+     */
+    state?: string;
+    /**
+     * The issuer identifier (OIDC extension).
+     */
+    iss?: string;
+    /**
+     * Error code if the request failed.
+     */
+    error?: string;
+    /**
+     * Human-readable error description.
+     */
+    error_description?: string;
+    /**
+     * URI identifying a human-readable web page with error information.
+     */
+    error_uri?: string;
+}

package/model/callback-params.js

@@ -0,0 +1 @@
+export {};