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

package/src/model/issuer-metadata.d.ts

@@ -0,0 +1,165 @@
+/**
+ * OIDC Provider Metadata
+ *
+ * Represents the OpenID Connect Discovery document as defined in
+ * OpenID Connect Discovery 1.0.
+ *
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html
+ */
+export interface IssuerMetadata {
+    /**
+     * URL using the https scheme with no query or fragment component
+     * that the OP asserts as its Issuer Identifier.
+     */
+    issuer: string;
+    /**
+     * URL of the OP's OAuth 2.0 Authorization Endpoint.
+     */
+    authorization_endpoint: string;
+    /**
+     * URL of the OP's OAuth 2.0 Token Endpoint.
+     */
+    token_endpoint: string;
+    /**
+     * URL of the OP's JSON Web Key Set document.
+     */
+    jwks_uri: string;
+    /**
+     * URL of the OP's UserInfo Endpoint.
+     */
+    userinfo_endpoint?: string;
+    /**
+     * URL of the OP's Pushed Authorization Request Endpoint (RFC 9126).
+     */
+    pushed_authorization_request_endpoint?: string;
+    /**
+     * URL of the OP's Registration Endpoint.
+     */
+    registration_endpoint?: string;
+    /**
+     * URL that the OpenID Provider provides to revoke tokens.
+     */
+    revocation_endpoint?: string;
+    /**
+     * URL of the OP's Token Introspection Endpoint.
+     */
+    introspection_endpoint?: string;
+    /**
+     * URL of the OP's Logout Endpoint.
+     */
+    end_session_endpoint?: string;
+    /**
+     * MTLS endpoint aliases for certificate-bound tokens.
+     */
+    mtls_endpoint_aliases?: {
+        token_endpoint?: string;
+        revocation_endpoint?: string;
+        introspection_endpoint?: string;
+        userinfo_endpoint?: string;
+        pushed_authorization_request_endpoint?: string;
+    };
+    /**
+     * List of OAuth 2.0 response_type values that this OP supports.
+     */
+    response_types_supported?: string[];
+    /**
+     * List of OAuth 2.0 response_mode values that this OP supports.
+     */
+    response_modes_supported?: string[];
+    /**
+     * List of OAuth 2.0 grant types supported.
+     */
+    grant_types_supported?: string[];
+    /**
+     * List of the OAuth 2.0 scope values supported.
+     */
+    scopes_supported?: string[];
+    /**
+     * List of the Subject Identifier types supported.
+     */
+    subject_types_supported?: string[];
+    /**
+     * List of the JWS signing algorithms supported for the ID Token.
+     */
+    id_token_signing_alg_values_supported?: string[];
+    /**
+     * List of the JWS signing algorithms supported for Request Objects.
+     */
+    request_object_signing_alg_values_supported?: string[];
+    /**
+     * List of Client Authentication methods supported by the Token Endpoint.
+     */
+    token_endpoint_auth_methods_supported?: string[];
+    /**
+     * List of the JWS signing algorithms supported for Client Authentication.
+     */
+    token_endpoint_auth_signing_alg_values_supported?: string[];
+    /**
+     * List of Claim Names of the Claims that the OP MAY be able to supply values for.
+     */
+    claims_supported?: string[];
+    /**
+     * List of the Claim Types that the OP supports.
+     */
+    claim_types_supported?: string[];
+    /**
+     * Languages and scripts supported for values in Claims.
+     */
+    claims_locales_supported?: string[];
+    /**
+     * Languages and scripts supported for the UI.
+     */
+    ui_locales_supported?: string[];
+    /**
+     * URL of a page containing human-readable information about the OP's requirements.
+     */
+    service_documentation?: string;
+    /**
+     * URL that the OP provides for the Relying Party to read about policies.
+     */
+    op_policy_uri?: string;
+    /**
+     * URL that the OP provides for the Relying Party to read about terms of service.
+     */
+    op_tos_uri?: string;
+    /**
+     * Boolean value specifying whether the OP supports use of the claims parameter.
+     */
+    claims_parameter_supported?: boolean;
+    /**
+     * Boolean value specifying whether the OP supports use of the request parameter.
+     */
+    request_parameter_supported?: boolean;
+    /**
+     * Boolean value specifying whether the OP supports use of the request_uri parameter.
+     */
+    request_uri_parameter_supported?: boolean;
+    /**
+     * Boolean value specifying whether the OP requires request_uri values to be pre-registered.
+     */
+    require_request_uri_registration?: boolean;
+    /**
+     * URL of the authorization server's code_challenge_methods_supported.
+     */
+    code_challenge_methods_supported?: string[];
+    /**
+     * Boolean indicating support for TLS client certificate bound access tokens.
+     */
+    tls_client_certificate_bound_access_tokens?: boolean;
+    /**
+     * Boolean indicating whether PAR is required.
+     */
+    require_pushed_authorization_requests?: boolean;
+    /**
+     * ACR values supported.
+     */
+    acr_values_supported?: string[];
+    /**
+     * Boolean indicating whether signed request object is required.
+     */
+    require_signed_request_object?: boolean;
+    /**
+     * Allows for additional custom metadata fields.
+     */
+    [key: string]: unknown;
+}

package/src/model/issuer-metadata.js

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

package/src/model/jwks.d.ts

@@ -0,0 +1,12 @@
+import { JWK } from 'jose';
+/**
+ * JSON Web Key Set
+ *
+ * A set of JSON Web Keys as defined in RFC 7517.
+ */
+export interface JWKSet {
+    /**
+     * Array of JSON Web Key values.
+     */
+    keys: JWK[];
+}

package/src/model/jwks.js

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

package/src/model/token-response.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OAuth 2.0 Token Response
+ *
+ * Represents the response from the token endpoint as defined in RFC 6749.
+ */
+export interface TokenResponse {
+    /**
+     * The access token issued by the authorization server.
+     */
+    access_token?: string;
+    /**
+     * The type of token issued (typically "Bearer").
+     */
+    token_type?: string;
+    /**
+     * The lifetime in seconds of the access token.
+     */
+    expires_in?: number;
+    /**
+     * The refresh token for obtaining new access tokens.
+     */
+    refresh_token?: string;
+    /**
+     * The scope of the access token.
+     */
+    scope?: string;
+    /**
+     * The ID token (OIDC extension to OAuth 2.0).
+     */
+    id_token?: string;
+}

package/src/model/token-response.js

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

package/src/model/token-set.d.ts

@@ -0,0 +1,73 @@
+import { IdTokenClaims } from './claims.js';
+import { TokenResponse } from './token-response.js';
+import { JWKSet } from './jwks.js';
+/**
+ * Token Set
+ *
+ * Represents an OAuth 2.0 / OIDC token response with validation capabilities.
+ * Handles ID token validation and claims extraction.
+ */
+export declare class TokenSet {
+    readonly access_token?: string;
+    readonly token_type?: string;
+    readonly expires_in?: number;
+    readonly refresh_token?: string;
+    readonly scope?: string;
+    readonly id_token?: string;
+    private idTokenClaims?;
+    private jwtPayload?;
+    private tokenIssuedAt;
+    /**
+     * Creates a new TokenSet from a token response.
+     *
+     * @param tokenResponse - Raw token response from the token endpoint
+     */
+    constructor(tokenResponse: TokenResponse);
+    /**
+     * 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
+     */
+    validate(jwks: JWKSet, expectedIssuer: string, expectedAudience: string, expectedNonce: string, allowedAlgorithms?: string[]): Promise<void>;
+    /**
+     * 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(): IdTokenClaims;
+    /**
+     * Checks if the access token has expired.
+     *
+     * @returns true if the token is expired, false otherwise
+     */
+    expired(): boolean;
+    /**
+     * 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
+     */
+    private selectKey;
+}

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;
+}