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

package/src/endpoints/pushed-authorisation-request-endpoint.d.ts

@@ -0,0 +1,87 @@
+import { Agent } from 'undici';
+import { Logger } from 'winston';
+import { RelyingPartyClientSdkConfig } from '../types.js';
+import { JwtHelper } from '../crypto/jwt-helper.js';
+import { ParticipantsEndpoint } from './participants-endpoint';
+/**
+ * Response from the Pushed Authorization Request endpoint.
+ */
+export interface PARResponse {
+    /**
+     * The full authorization URL to redirect the user to.
+     */
+    authUrl: string;
+    /**
+     * The PKCE code verifier (to be sent with token request).
+     */
+    codeVerifier: string;
+    /**
+     * The state parameter (for CSRF protection).
+     */
+    state: string;
+    /**
+     * The nonce parameter (for ID token validation).
+     */
+    nonce: string;
+    /**
+     * The fapi-interaction-id
+     */
+    xFapiInteractionId: string;
+}
+/**
+ * Pushed Authorization Request Endpoint
+ *
+ * Handles the PAR flow as defined in RFC 9126.
+ * Creates signed request objects and submits them to the PAR endpoint.
+ */
+export declare class PushedAuthorisationRequestEndpoint {
+    private readonly sdkConfig;
+    private readonly httpClient;
+    private readonly jwtHelper;
+    private readonly logger;
+    private readonly participantsEndpoint;
+    private static readonly EXTENDED_CLAIMS;
+    constructor(sdkConfig: RelyingPartyClientSdkConfig, httpClient: Agent, jwtHelper: JwtHelper, logger: Logger, participantsEndpoint: ParticipantsEndpoint);
+    /**
+     * Sends a Pushed Authorization Request to the authorization server.
+     *
+     * @param authServerId - Authorization server details
+     * @param essentialClaims - Claims that must be provided
+     * @param voluntaryClaims - Claims that are optional
+     * @param purpose - Purpose string for data sharing
+     * @returns PAR response with authorization URL and PKCE parameters
+     */
+    sendPushedAuthorisationRequest(authServerId: string, essentialClaims: string[], voluntaryClaims: string[], purpose: string): Promise<PARResponse>;
+    private generateRequest;
+    /**
+     * Generates the claims request object.
+     *
+     * Separates claims into basic and extended categories.
+     * Extended claims go into the verified_claims structure.
+     *
+     * @param essentialClaims - Claims that must be provided
+     * @param voluntaryClaims - Claims that are optional
+     * @returns Structured claims request
+     */
+    private generateClaimsRequest;
+    /**
+     * Sends the PAR request to the authorization server.
+     *
+     * @param parEndpoint - PAR endpoint URL
+     * @param requestJwt - Signed request JWT
+     * @param clientAssertion - Client assertion JWT for authentication
+     * @param xFapiInteractionId - FAPI interaction ID
+     * @returns PAR endpoint response
+     */
+    private sendPARRequest;
+    /**
+     * Constructs the authorization URL.
+     *
+     * Per RFC 9126, only client_id and request_uri should be included.
+     *
+     * @param authorizationEndpoint - Authorization endpoint URL
+     * @param requestUri - Request URI from PAR response
+     * @returns Full authorization URL
+     */
+    private constructAuthorizationUrl;
+}

package/src/endpoints/pushed-authorisation-request-endpoint.js

@@ -0,0 +1,192 @@
+import { PkceHelper } from '../crypto/pkce-helper.js';
+import { DiscoveryService } from '../model/discovery-service.js';
+import { HttpClientExtensions } from '../http/http-client-extensions.js';
+import { illegalPurposeChars, validatePurpose } from '../validator.js';
+import { generateXFapiInteractionId } from '../fapi/fapi-utils.js';
+/**
+ * Pushed Authorization Request Endpoint
+ *
+ * Handles the PAR flow as defined in RFC 9126.
+ * Creates signed request objects and submits them to the PAR endpoint.
+ */
+export class PushedAuthorisationRequestEndpoint {
+    constructor(sdkConfig, httpClient, jwtHelper, logger, participantsEndpoint) {
+        this.sdkConfig = sdkConfig;
+        this.httpClient = httpClient;
+        this.jwtHelper = jwtHelper;
+        this.logger = logger;
+        this.participantsEndpoint = participantsEndpoint;
+    }
+    /**
+     * Sends a Pushed Authorization Request to the authorization server.
+     *
+     * @param authServerId - Authorization server details
+     * @param essentialClaims - Claims that must be provided
+     * @param voluntaryClaims - Claims that are optional
+     * @param purpose - Purpose string for data sharing
+     * @returns PAR response with authorization URL and PKCE parameters
+     */
+    async sendPushedAuthorisationRequest(authServerId, essentialClaims, voluntaryClaims, purpose) {
+        // Validate purpose
+        const purposeValidation = validatePurpose(purpose);
+        if (purposeValidation === 'INVALID_LENGTH') {
+            this.logger.warn('Purpose must be between 3 and 300 characters');
+            throw new Error(`Invalid purpose for supplied for PAR: ${purpose}`);
+        }
+        if (purposeValidation === 'INVALID_CHARACTERS') {
+            this.logger.warn(`Purpose cannot contain any of the following characters: ${illegalPurposeChars.join(',')}, purpose supplied: [${purpose}]`);
+            throw new Error(`Invalid purpose for supplied for PAR: ${purpose}`);
+        }
+        const xFapiInteractionId = generateXFapiInteractionId();
+        try {
+            const essentialClaimsWithTxn = [...new Set([...essentialClaims, 'txn'])];
+            const claimsRequest = this.generateClaimsRequest(essentialClaims, voluntaryClaims);
+            const authServer = await this.participantsEndpoint.getAuthServerDetails(authServerId);
+            const { authUrl, codeVerifier, state, nonce } = await this.generateRequest(authServer, claimsRequest, purpose, xFapiInteractionId);
+            this.logger.info(`Sent PAR to auth server: ${authServer.AuthorisationServerId} - ${authServer.CustomerFriendlyName}, essential claims: ${essentialClaimsWithTxn}, voluntary claims: ${voluntaryClaims}, x-fapi-interaction-id: ${xFapiInteractionId}`);
+            return {
+                authUrl,
+                codeVerifier: codeVerifier,
+                state,
+                nonce,
+                xFapiInteractionId,
+            };
+        }
+        catch (err) {
+            this.logger.error(`Error sending pushed authorisation request to authorisation server ${authServerId}, x-fapi-interaction-id: ${xFapiInteractionId}.`, err);
+            throw new Error(`Unable to send pushed authorisation request to ${authServerId}, x-fapi-interaction-id: ${xFapiInteractionId} - ${err}`);
+        }
+    }
+    async generateRequest(authServer, claimsRequest, purpose, xFapiInteractionId) {
+        // Fetch discovery document
+        const discoveryMetadata = await DiscoveryService.fetchDiscoveryDocument(authServer.OpenIDDiscoveryDocument, this.httpClient);
+        if (!discoveryMetadata.pushed_authorization_request_endpoint) {
+            throw new Error(`Authorization server ${authServer.AuthorisationServerId} does not support PAR`);
+        }
+        // Generate PKCE parameters
+        const state = PkceHelper.generateState();
+        const nonce = PkceHelper.generateNonce();
+        const codeVerifier = PkceHelper.generateCodeVerifier();
+        const codeChallenge = PkceHelper.generateCodeChallenge(codeVerifier);
+        this.logger.debug(`Generated PKCE parameters - state: ${state.substring(0, 10)}..., nonce: ${nonce.substring(0, 10)}...`);
+        this.logger.debug(`Claims request: ${JSON.stringify(claimsRequest, null, 2)}`);
+        // Create signed request JWT
+        const requestJwt = await this.jwtHelper.generateRequestJwt({
+            issuer: this.sdkConfig.data.client_id,
+            audience: discoveryMetadata.issuer,
+            redirectUri: this.sdkConfig.data.application_redirect_uri,
+            scope: 'openid',
+            responseType: 'code',
+            codeChallenge,
+            codeChallengeMethod: 'S256',
+            state,
+            nonce,
+            claims: claimsRequest,
+            purpose,
+            prompt: 'consent',
+        });
+        // Create client assertion for authentication
+        const clientAssertion = await this.jwtHelper.generateClientAssertionJwt(discoveryMetadata.issuer);
+        // Send PAR request
+        const parResponse = await this.sendPARRequest(discoveryMetadata.pushed_authorization_request_endpoint, requestJwt, clientAssertion, xFapiInteractionId);
+        this.logger.info(`PAR request successful, request_uri: ${parResponse.request_uri}, expires_in: ${parResponse.expires_in}s`);
+        // Construct authorization URL
+        // RFC 9126: Only client_id and request_uri should be sent
+        const authUrl = this.constructAuthorizationUrl(discoveryMetadata.authorization_endpoint, parResponse.request_uri);
+        this.logger.debug(`Authorization URL: ${authUrl}`);
+        return {
+            authUrl,
+            codeVerifier: codeVerifier,
+            state,
+            nonce,
+        };
+    }
+    /**
+     * Generates the claims request object.
+     *
+     * Separates claims into basic and extended categories.
+     * Extended claims go into the verified_claims structure.
+     *
+     * @param essentialClaims - Claims that must be provided
+     * @param voluntaryClaims - Claims that are optional
+     * @returns Structured claims request
+     */
+    generateClaimsRequest(essentialClaims, voluntaryClaims) {
+        // Remove duplicates (essential takes precedence)
+        const filteredVoluntary = voluntaryClaims.filter((c) => !essentialClaims.includes(c));
+        // Partition claims into basic and extended
+        const essentialExtended = essentialClaims.filter((c) => PushedAuthorisationRequestEndpoint.EXTENDED_CLAIMS.includes(c));
+        const essentialBasic = essentialClaims.filter((c) => !PushedAuthorisationRequestEndpoint.EXTENDED_CLAIMS.includes(c));
+        const voluntaryExtended = filteredVoluntary.filter((c) => PushedAuthorisationRequestEndpoint.EXTENDED_CLAIMS.includes(c));
+        const voluntaryBasic = filteredVoluntary.filter((c) => !PushedAuthorisationRequestEndpoint.EXTENDED_CLAIMS.includes(c));
+        const claimsRequest = { id_token: {} };
+        // Add basic claims directly to id_token
+        essentialBasic.forEach((claim) => {
+            claimsRequest.id_token[claim] = { essential: true };
+        });
+        voluntaryBasic.forEach((claim) => {
+            claimsRequest.id_token[claim] = { essential: false };
+        });
+        // Add extended claims to verified_claims structure
+        if (essentialExtended.length > 0 || voluntaryExtended.length > 0) {
+            claimsRequest.id_token.verified_claims = {
+                verification: {
+                    trust_framework: { value: 'au_connectid' },
+                },
+                claims: {},
+            };
+            essentialExtended.forEach((claim) => {
+                claimsRequest.id_token.verified_claims.claims[claim] = {
+                    essential: true,
+                };
+            });
+            voluntaryExtended.forEach((claim) => {
+                claimsRequest.id_token.verified_claims.claims[claim] = {
+                    essential: false,
+                };
+            });
+        }
+        return claimsRequest;
+    }
+    /**
+     * Sends the PAR request to the authorization server.
+     *
+     * @param parEndpoint - PAR endpoint URL
+     * @param requestJwt - Signed request JWT
+     * @param clientAssertion - Client assertion JWT for authentication
+     * @param xFapiInteractionId - FAPI interaction ID
+     * @returns PAR endpoint response
+     */
+    async sendPARRequest(parEndpoint, requestJwt, clientAssertion, xFapiInteractionId) {
+        const body = new URLSearchParams({
+            request: requestJwt,
+            client_assertion: clientAssertion,
+            client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+        });
+        this.logger.debug(`Sending PAR request to: ${parEndpoint}`);
+        this.logger.debug(`  with body: ${body}`);
+        const response = await HttpClientExtensions.postForm(parEndpoint, body, {
+            agent: this.httpClient,
+            clientId: this.sdkConfig.data.client_id,
+            xFapiInteractionId,
+        });
+        return HttpClientExtensions.parseJsonResponse(response);
+    }
+    /**
+     * Constructs the authorization URL.
+     *
+     * Per RFC 9126, only client_id and request_uri should be included.
+     *
+     * @param authorizationEndpoint - Authorization endpoint URL
+     * @param requestUri - Request URI from PAR response
+     * @returns Full authorization URL
+     */
+    constructAuthorizationUrl(authorizationEndpoint, requestUri) {
+        const url = new URL(authorizationEndpoint);
+        url.searchParams.set('client_id', this.sdkConfig.data.client_id);
+        url.searchParams.set('request_uri', requestUri);
+        return url.toString();
+    }
+}
+// Extended claims list for ConnectID
+PushedAuthorisationRequestEndpoint.EXTENDED_CLAIMS = ['over16', 'over18', 'over21', 'over25', 'over65', 'beneficiary_account_au', 'beneficiary_account_au_payid', 'beneficiary_account_international', 'cba_loyalty'];

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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>;
+}