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

package/src/model/token-set.js

@@ -0,0 +1,179 @@
+import { jwtVerify, decodeProtectedHeader, importJWK } from 'jose';
+/**
+ * Token Set
+ *
+ * Represents an OAuth 2.0 / OIDC token response with validation capabilities.
+ * Handles ID token validation and claims extraction.
+ */
+export class TokenSet {
+    /**
+     * Creates a new TokenSet from a token response.
+     *
+     * @param tokenResponse - Raw token response from the token endpoint
+     */
+    constructor(tokenResponse) {
+        this.access_token = tokenResponse.access_token;
+        this.token_type = tokenResponse.token_type;
+        this.expires_in = tokenResponse.expires_in;
+        this.refresh_token = tokenResponse.refresh_token;
+        this.scope = tokenResponse.scope;
+        this.id_token = tokenResponse.id_token;
+        this.tokenIssuedAt = Math.floor(Date.now() / 1000);
+    }
+    /**
+     * Validates the ID token.
+     *
+     * Performs the following validations:
+     * - Algorithm validation against allowed algorithms
+     * - Signature verification using JWKS
+     * - Issuer validation
+     * - Audience validation
+     * - Nonce validation
+     * - Timestamp validation (iat, exp)
+     *
+     * @param jwks - JSON Web Key Set for signature verification
+     * @param expectedIssuer - Expected issuer claim value
+     * @param expectedAudience - Expected audience claim value
+     * @param expectedNonce - Expected nonce value
+     * @param allowedAlgorithms - Optional list of allowed signing algorithms from discovery document
+     * @throws Error if validation fails
+     */
+    async validate(jwks, expectedIssuer, expectedAudience, expectedNonce, allowedAlgorithms) {
+        if (!this.id_token) {
+            throw new Error('No id_token to validate');
+        }
+        try {
+            // Decode header to check algorithm before verification
+            const header = decodeProtectedHeader(this.id_token);
+            // Validate algorithm if allowed algorithms are provided
+            if (allowedAlgorithms && allowedAlgorithms.length > 0) {
+                if (!header.alg) {
+                    throw new Error('ID token missing alg in header');
+                }
+                const isAllowed = allowedAlgorithms.some((alg) => alg.toLowerCase() === header.alg.toLowerCase());
+                if (!isAllowed) {
+                    throw new Error(`ID token algorithm '${header.alg}' is not one of the allowed algorithms: ${allowedAlgorithms.join(', ')}`);
+                }
+            }
+            // Select the appropriate key from JWKS
+            const key = await this.selectKey(jwks);
+            // Verify signature and standard claims
+            const { payload } = await jwtVerify(this.id_token, key, {
+                issuer: expectedIssuer,
+                audience: expectedAudience,
+                algorithms: ['PS256', 'RS256'], // Accept both algorithms
+            });
+            // Validate nonce
+            if (payload.nonce !== expectedNonce) {
+                throw new Error(`Nonce mismatch: expected ${expectedNonce}, got ${payload.nonce}`);
+            }
+            // Validate audience claim per OpenID Connect Core 3.1.3.7
+            // If aud is an array, all audiences must be trusted (only our client ID is trusted)
+            // and azp claim should be present
+            if (Array.isArray(payload.aud)) {
+                // Check if all audiences are trusted (only client ID is trusted)
+                const untrustedAudiences = payload.aud.filter((aud) => aud !== expectedAudience);
+                if (untrustedAudiences.length > 0) {
+                    throw new Error(`ID token contains untrusted audiences: ${untrustedAudiences.join(', ')}`);
+                }
+                // Per OIDC spec clause 4: if multiple audiences, azp should be present
+                if (payload.aud.length > 1 && !payload.azp) {
+                    throw new Error('ID token contains multiple audiences but azp claim is missing');
+                }
+            }
+            // Validate required claims are present
+            const now = Math.floor(Date.now() / 1000);
+            if (!payload.iat) {
+                throw new Error('ID token missing iat claim');
+            }
+            if (!payload.exp) {
+                throw new Error('ID token missing exp claim');
+            }
+            // Validate iat (must not be more than 10 minutes old per Java SDK)
+            if (now - payload.iat > 600) {
+                throw new Error(`ID token iat is too old: issued at ${payload.iat}, current time ${now}`);
+            }
+            // Validate exp (must not be more than 5 minutes in the past - clock skew tolerance)
+            if (payload.exp < now - 300) {
+                throw new Error(`ID token expired more than 5 minutes ago: exp ${payload.exp}, current time ${now}`);
+            }
+            // Store validated claims
+            this.jwtPayload = payload;
+            this.idTokenClaims = payload;
+        }
+        catch (error) {
+            throw new Error(`ID token validation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Returns the parsed ID token claims.
+     *
+     * Must call validate() first.
+     *
+     * @returns Parsed and validated ID token claims
+     * @throws Error if token has not been validated
+     */
+    claims() {
+        if (!this.idTokenClaims) {
+            throw new Error('ID token has not been validated. Call validate() first.');
+        }
+        return this.idTokenClaims;
+    }
+    /**
+     * Checks if the access token has expired.
+     *
+     * @returns true if the token is expired, false otherwise
+     */
+    expired() {
+        if (!this.expires_in) {
+            // If no expires_in, assume token doesn't expire
+            return false;
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const expiresAt = this.tokenIssuedAt + this.expires_in;
+        return now >= expiresAt;
+    }
+    /**
+     * Selects the appropriate key from JWKS for verification.
+     *
+     * Matches based on:
+     * - kid (key ID)
+     * - alg (algorithm)
+     * - use (key usage - should be 'sig')
+     *
+     * @param jwks - JSON Web Key Set
+     * @returns Imported crypto key for verification
+     * @throws Error if no matching key is found
+     */
+    async selectKey(jwks) {
+        if (!this.id_token) {
+            throw new Error('No id_token present');
+        }
+        // Decode header to get kid and alg
+        const header = decodeProtectedHeader(this.id_token);
+        if (!header.kid) {
+            throw new Error('ID token missing kid in header');
+        }
+        // Find matching key
+        const matchingKey = jwks.keys.find((key) => {
+            // Match by kid (required)
+            if (key.kid !== header.kid) {
+                return false;
+            }
+            // Match by alg if present in key
+            if (key.alg && key.alg !== header.alg) {
+                return false;
+            }
+            // Match by use if present (should be 'sig' for signing)
+            if (key.use && key.use !== 'sig') {
+                return false;
+            }
+            return true;
+        });
+        if (!matchingKey) {
+            throw new Error(`No matching key found in JWKS for kid: ${header.kid}, alg: ${header.alg}`);
+        }
+        // Import the JWK for verification
+        return importJWK(matchingKey, header.alg);
+    }
+}

package/src/relying-party-client-sdk.d.ts

@@ -0,0 +1,68 @@
+import { CallbackParams, ConsolidatedTokenSet, Participant, RelyingPartyClientSdkConfig } from './types.js';
+export default class RelyingPartyClientSdk {
+    private readonly logger;
+    private config;
+    private readonly purpose;
+    private readonly participantsEndpoint;
+    private readonly pushedAuthorisationRequestEndpoint;
+    private readonly retrieveTokenEndpoint;
+    private readonly userInfoEndpoint;
+    private readonly httpClient;
+    private readonly jwtHelper;
+    constructor(config: RelyingPartyClientSdkConfig);
+    /**
+     * Get the list of participating identity providers within the scheme.
+     *
+     * Applies filtering based on SDK configuration.
+     *
+     * @returns List of participants
+     */
+    getParticipants(): Promise<Participant[]>;
+    /**
+     * Get the list of fallback provider participants.
+     *
+     * @returns List of fallback provider participants
+     */
+    getFallbackProviderParticipants(): Promise<Participant[]>;
+    /**
+     * Sends a Pushed Authorization Request (PAR).
+     *
+     * @param authServerId - Authorization server ID
+     * @param essentialClaims - Claims that must be provided
+     * @param voluntaryClaims - Claims that are optional
+     * @param purpose - Purpose string for data sharing
+     * @returns Object containing authorization URL and PKCE parameters
+     */
+    sendPushedAuthorisationRequest(authServerId: string, essentialClaims: string[], voluntaryClaims?: string[], purpose?: string): Promise<{
+        authUrl: string;
+        codeVerifier: string;
+        state: string;
+        nonce: string;
+        xFapiInteractionId: string;
+    }>;
+    /**
+     * Retrieves tokens using an authorisation code.
+     *
+     * @param authorisationServerId - Authorisation server ID
+     * @param requestParams - OAuth callback parameters
+     * @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, requestParams: CallbackParams, codeVerifier: string, state: string, nonce: string): Promise<ConsolidatedTokenSet>;
+    /**
+     * Retrieves user information from the UserInfo endpoint.
+     *
+     * @param authorisationServerId - Authorization server ID
+     * @param accessToken - Access token
+     * @returns UserInfo claims
+     */
+    getUserInfo(authorisationServerId: string, accessToken: string): Promise<Record<string, unknown>>;
+    /**
+     * Gets the current date (for testing purposes).
+     *
+     * @returns Current date
+     */
+    getCurrentDate(): Date;
+}

package/src/relying-party-client-sdk.js

@@ -0,0 +1,150 @@
+import { getCertificate } from './utils/cert-utils.js';
+import { getLogger } from './logger.js';
+import ParticipantFilters from './filter/participant-filters.js';
+import { illegalPurposeChars, isValidCertificate, validatePurpose } from './validator.js';
+import { CryptoLoader } from './crypto/crypto-loader.js';
+import { JwtHelper } from './crypto/jwt-helper.js';
+import { HttpClientFactory } from './http/http-client-factory.js';
+import { ParticipantsEndpoint } from './endpoints/participants-endpoint.js';
+import { PushedAuthorisationRequestEndpoint } from './endpoints/pushed-authorisation-request-endpoint.js';
+import { RetrieveTokenEndpoint } from './endpoints/retrieve-token-endpoint.js';
+import { UserInfoEndpoint } from './endpoints/userinfo-endpoint.js';
+export default class RelyingPartyClientSdk {
+    constructor(config) {
+        this.purpose = 'verifying your identity';
+        this.config = config;
+        // Validate certificates
+        if (!isValidCertificate(this.config.data.transport_key, this.config.data.transport_key_content)) {
+            throw new Error('Either transport_key or transport_key_content must be provided');
+        }
+        if (!isValidCertificate(this.config.data.transport_pem, this.config.data.transport_pem_content)) {
+            throw new Error('Either transport_pem or transport_pem_content must be provided');
+        }
+        if (!isValidCertificate(this.config.data.signing_key, this.config.data.signing_key_content)) {
+            throw new Error('Either signing_key or signing_key_content must be provided');
+        }
+        if (!isValidCertificate(this.config.data.ca_pem, this.config.data.ca_pem_content)) {
+            throw new Error('Either ca_pem or ca_pem_content must be provided');
+        }
+        this.logger = getLogger(this.config.data.log_level);
+        this.logger.info(`Creating RelyingPartyClientSdk - version ${process.env.SDK_VERSION}`);
+        // Validate and set purpose
+        if (this.config.data.purpose) {
+            const purposeValidation = validatePurpose(this.config.data.purpose);
+            if (purposeValidation === 'INVALID_LENGTH') {
+                this.logger.warn('Purpose must be between 3 and 300 characters');
+                throw new Error(`Invalid purpose supplied in config: ${this.config.data.purpose}`);
+            }
+            if (purposeValidation === 'INVALID_CHARACTERS') {
+                this.logger.warn(`Purpose cannot contain any of the following characters: ${illegalPurposeChars.join(',')}, purpose supplied: [${this.config.data.purpose}]`);
+                throw new Error(`Invalid purpose supplied in config: ${this.config.data.purpose}`);
+            }
+            this.purpose = this.config.data.purpose;
+            this.logger.info(`Using default purpose supplied in config: ${this.purpose}`);
+        }
+        else {
+            this.logger.info(`Using built-in default purpose: ${this.purpose}`);
+        }
+        // Log filtering configuration
+        if (this.config.data.include_uncertified_participants) {
+            this.logger.info('Identity provider list will not be filtered as include_uncertified_participants=true');
+        }
+        else {
+            if (this.config.data.required_claims) {
+                this.logger.info(`Identity provider list will be filtered for participants that support the following claims: ${JSON.stringify(this.config.data.required_claims)}`);
+            }
+            if (this.config.data.required_participant_certifications) {
+                this.logger.info(`Identity provider list will be filtered for participants that support the following certifications: ${JSON.stringify(this.config.data.required_participant_certifications)}`);
+            }
+        }
+        // Log certificate source
+        this.logger.info(`Using ${this.config.data.transport_key_content ? 'transport_key_content' : 'transport_key'} config prop`);
+        this.logger.info(`Using ${this.config.data.transport_pem_content ? 'transport_pem_content' : 'transport_pem'} config prop`);
+        this.logger.info(`Using ${this.config.data.ca_pem_content ? 'ca_pem_content' : 'ca_pem'} config prop`);
+        this.logger.info(`Using ${this.config.data.signing_key_content ? 'signing_key_content' : 'signing_key'} config prop`);
+        // Initialize crypto
+        const signingKeyObject = CryptoLoader.loadPrivateKey(getCertificate(this.config.data.signing_key, this.config.data.signing_key_content));
+        // Initialize JWT helper
+        this.jwtHelper = new JwtHelper(signingKeyObject, this.config.data.signing_kid, this.config.data.client_id);
+        // Initialize HTTP client
+        this.httpClient = HttpClientFactory.createClient({
+            transportKey: getCertificate(this.config.data.transport_key, this.config.data.transport_key_content),
+            transportPem: getCertificate(this.config.data.transport_pem, this.config.data.transport_pem_content),
+            caPem: getCertificate(this.config.data.ca_pem, this.config.data.ca_pem_content),
+            clientId: this.config.data.client_id,
+        });
+        // Initialize endpoints
+        this.participantsEndpoint = new ParticipantsEndpoint(this.config, new ParticipantFilters(), this.httpClient, this.logger, () => this.getCurrentDate());
+        this.pushedAuthorisationRequestEndpoint = new PushedAuthorisationRequestEndpoint(this.config, this.httpClient, this.jwtHelper, this.logger, this.participantsEndpoint);
+        this.retrieveTokenEndpoint = new RetrieveTokenEndpoint(this.config, this.httpClient, this.jwtHelper, this.logger, this.participantsEndpoint);
+        this.userInfoEndpoint = new UserInfoEndpoint(this.httpClient, this.logger, this.config.data.client_id, this.participantsEndpoint);
+    }
+    /**
+     * Get the list of participating identity providers within the scheme.
+     *
+     * Applies filtering based on SDK configuration.
+     *
+     * @returns List of participants
+     */
+    async getParticipants() {
+        return this.participantsEndpoint.getParticipants();
+    }
+    /**
+     * Get the list of fallback provider participants.
+     *
+     * @returns List of fallback provider participants
+     */
+    async getFallbackProviderParticipants() {
+        return this.participantsEndpoint.getFallbackProviderParticipants();
+    }
+    /**
+     * Sends a Pushed Authorization Request (PAR).
+     *
+     * @param authServerId - Authorization server ID
+     * @param essentialClaims - Claims that must be provided
+     * @param voluntaryClaims - Claims that are optional
+     * @param purpose - Purpose string for data sharing
+     * @returns Object containing authorization URL and PKCE parameters
+     */
+    async sendPushedAuthorisationRequest(authServerId, essentialClaims, voluntaryClaims = [], purpose = this.purpose) {
+        const { authUrl, codeVerifier, state, nonce, xFapiInteractionId } = await this.pushedAuthorisationRequestEndpoint.sendPushedAuthorisationRequest(authServerId, essentialClaims, voluntaryClaims, purpose);
+        return {
+            authUrl,
+            codeVerifier,
+            state,
+            nonce,
+            xFapiInteractionId,
+        };
+    }
+    /**
+     * Retrieves tokens using an authorisation code.
+     *
+     * @param authorisationServerId - Authorisation server ID
+     * @param requestParams - OAuth callback parameters
+     * @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, requestParams, codeVerifier, state, nonce) {
+        return this.retrieveTokenEndpoint.retrieveTokens(authorisationServerId, requestParams, codeVerifier, state, nonce);
+    }
+    /**
+     * Retrieves user information from the UserInfo endpoint.
+     *
+     * @param authorisationServerId - Authorization server ID
+     * @param accessToken - Access token
+     * @returns UserInfo claims
+     */
+    async getUserInfo(authorisationServerId, accessToken) {
+        return this.userInfoEndpoint.getUserInfo(authorisationServerId, accessToken);
+    }
+    /**
+     * Gets the current date (for testing purposes).
+     *
+     * @returns Current date
+     */
+    getCurrentDate() {
+        return new Date();
+    }
+}