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

package/src/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/src/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/src/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/src/integration/integration.test.d.ts

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

package/src/integration/integration.test.js

@@ -0,0 +1,30 @@
+import jsonPackage from '../../package.json';
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { config } from '../config.js';
+import RelyingPartyClientSdk from '../relying-party-client-sdk.js';
+describe('RelyingPartyClientSdk', () => {
+    it('should retrieve user agent and match details', async () => {
+        const version = jsonPackage.version;
+        const newConfig = {
+            ...config,
+            data: {
+                ...config.data,
+                registry_participants_uri: 'https://api.sandbox.connectid.com.au/useragent-responder/participants',
+            },
+        };
+        const participants = await new RelyingPartyClientSdk(newConfig).getParticipants();
+        const regex = /(.*?)\/(.*?)\s(\(.*?\))\s(\+.*)/;
+        const organisationName = participants[0].OrganisationName;
+        const match = organisationName.match(regex);
+        assert.ok(match, `Organisation name '${organisationName}' failed to match pattern '${regex.source}'`);
+        const namePart = match[1];
+        const versionPart = match[2];
+        const platformPart = match[3].trim();
+        const clientIdPart = match[4];
+        assert.strictEqual(namePart, 'cid-rp-nodejs-sdk');
+        assert.strictEqual(versionPart, version);
+        assert.match(platformPart, /\(.+; .+; .+\)/);
+        assert.strictEqual(clientIdPart, '+https://rp.directory.sandbox.connectid.com.au/openid_relying_party/280518db-9807-4824-b080-324d94b45f6a');
+    });
+});

package/src/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/src/model/callback-params.js

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

package/src/model/claims.d.ts

@@ -0,0 +1,100 @@
+import { JWTPayload } from 'jose';
+/**
+ * Address Claim as defined in OIDC Core spec.
+ */
+export interface AddressClaim {
+    formatted?: string;
+    street_address?: string;
+    locality?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+}
+/**
+ * Verified Claims structure for extended claims (ConnectID).
+ */
+export interface VerifiedClaims {
+    verification?: {
+        trust_framework?: {
+            value?: string;
+        };
+        time?: string;
+        verification_process?: string;
+        evidence?: unknown[];
+    };
+    claims?: {
+        [key: string]: unknown;
+        over16?: boolean;
+        over18?: boolean;
+        over21?: boolean;
+        over25?: boolean;
+        over65?: boolean;
+        beneficiary_account_au?: unknown;
+        beneficiary_account_au_payid?: unknown;
+        beneficiary_account_international?: unknown;
+        cba_loyalty?: unknown;
+    };
+}
+/**
+ * ID Token Claims
+ *
+ * Extends the standard JWT payload with OIDC-specific claims.
+ * Includes both standard OIDC claims and ConnectID extensions.
+ */
+export interface IdTokenClaims extends JWTPayload {
+    /**
+     * Subject identifier (unique user ID).
+     */
+    sub: string;
+    name?: string;
+    given_name?: string;
+    middle_name?: string;
+    family_name?: string;
+    nickname?: string;
+    preferred_username?: string;
+    profile?: string;
+    picture?: string;
+    website?: string;
+    email?: string;
+    email_verified?: boolean;
+    gender?: string;
+    birthdate?: string;
+    zoneinfo?: string;
+    locale?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: AddressClaim;
+    updated_at?: number;
+    /**
+     * Authentication time (Unix timestamp).
+     */
+    auth_time?: number;
+    /**
+     * Nonce value for replay protection.
+     */
+    nonce?: string;
+    /**
+     * Transaction identifier.
+     */
+    txn?: string;
+    /**
+     * Authentication Context Class Reference.
+     */
+    acr?: string;
+    /**
+     * Authentication Methods References.
+     */
+    amr?: string[];
+    /**
+     * Authorized party (client ID of the party to which the ID token was issued).
+     */
+    azp?: string;
+    /**
+     * Verified claims for extended attributes.
+     */
+    verified_claims?: VerifiedClaims;
+    /**
+     * Allows for additional custom claims.
+     */
+    [key: string]: unknown;
+}

package/src/model/claims.js

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

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

@@ -0,0 +1,74 @@
+import { IdTokenClaims } from './claims.js';
+import { TokenSet } from './token-set.js';
+import { ConsolidatedTokenSet as IConsolidatedTokenSet } from '../types.js';
+/**
+ * Consolidated Token Set
+ *
+ * Wraps a TokenSet and provides additional convenience methods
+ * for accessing token data and claims.
+ *
+ * Implements the ConsolidatedTokenSet interface from types.ts.
+ */
+export declare class ConsolidatedTokenSet implements IConsolidatedTokenSet {
+    private tokenSet;
+    readonly xFapiInteractionId: string;
+    /**
+     * Creates a new ConsolidatedTokenSet.
+     *
+     * @param tokenSet - Validated token set
+     * @param xFapiInteractionId - FAPI interaction ID from the response
+     */
+    constructor(tokenSet: TokenSet, xFapiInteractionId: string);
+    get access_token(): string | undefined;
+    get token_type(): string | undefined;
+    get expires_in(): number | undefined;
+    get refresh_token(): string | undefined;
+    get scope(): string | undefined;
+    get id_token(): string | undefined;
+    /**
+     * Checks if the access token has expired.
+     *
+     * @returns true if the token is expired, false otherwise
+     */
+    expired(): boolean;
+    /**
+     * Returns the parsed ID token claims.
+     *
+     * @returns Parsed and validated ID token claims
+     */
+    claims(): IdTokenClaims;
+    /**
+     * Returns consolidated claims with verified_claims merged into top level.
+     *
+     * This method extracts extended claims from the verified_claims structure
+     * and merges them into the top-level claims object for easier access.
+     *
+     * For example, if the ID token contains:
+     * ```json
+     * {
+     *   "sub": "12345",
+     *   "name": "John Doe",
+     *   "verified_claims": {
+     *     "claims": {
+     *       "over18": true,
+     *       "over21": false
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * This method will return:
+     * ```json
+     * {
+     *   "sub": "12345",
+     *   "name": "John Doe",
+     *   "over18": true,
+     *   "over21": false,
+     *   "verified_claims": { ... }
+     * }
+     * ```
+     *
+     * @returns Consolidated claims object
+     */
+    consolidatedClaims(): IdTokenClaims;
+}

package/src/model/consolidated-token-set.js

@@ -0,0 +1,100 @@
+/**
+ * Consolidated Token Set
+ *
+ * Wraps a TokenSet and provides additional convenience methods
+ * for accessing token data and claims.
+ *
+ * Implements the ConsolidatedTokenSet interface from types.ts.
+ */
+export class ConsolidatedTokenSet {
+    /**
+     * Creates a new ConsolidatedTokenSet.
+     *
+     * @param tokenSet - Validated token set
+     * @param xFapiInteractionId - FAPI interaction ID from the response
+     */
+    constructor(tokenSet, xFapiInteractionId) {
+        this.tokenSet = tokenSet;
+        this.xFapiInteractionId = xFapiInteractionId;
+    }
+    // Delegate token properties to underlying TokenSet
+    get access_token() {
+        return this.tokenSet.access_token;
+    }
+    get token_type() {
+        return this.tokenSet.token_type;
+    }
+    get expires_in() {
+        return this.tokenSet.expires_in;
+    }
+    get refresh_token() {
+        return this.tokenSet.refresh_token;
+    }
+    get scope() {
+        return this.tokenSet.scope;
+    }
+    get id_token() {
+        return this.tokenSet.id_token;
+    }
+    /**
+     * Checks if the access token has expired.
+     *
+     * @returns true if the token is expired, false otherwise
+     */
+    expired() {
+        return this.tokenSet.expired();
+    }
+    /**
+     * Returns the parsed ID token claims.
+     *
+     * @returns Parsed and validated ID token claims
+     */
+    claims() {
+        return this.tokenSet.claims();
+    }
+    /**
+     * Returns consolidated claims with verified_claims merged into top level.
+     *
+     * This method extracts extended claims from the verified_claims structure
+     * and merges them into the top-level claims object for easier access.
+     *
+     * For example, if the ID token contains:
+     * ```json
+     * {
+     *   "sub": "12345",
+     *   "name": "John Doe",
+     *   "verified_claims": {
+     *     "claims": {
+     *       "over18": true,
+     *       "over21": false
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * This method will return:
+     * ```json
+     * {
+     *   "sub": "12345",
+     *   "name": "John Doe",
+     *   "over18": true,
+     *   "over21": false,
+     *   "verified_claims": { ... }
+     * }
+     * ```
+     *
+     * @returns Consolidated claims object
+     */
+    consolidatedClaims() {
+        const claims = this.claims();
+        // If there are no verified_claims, return claims as-is
+        if (!claims.verified_claims?.claims) {
+            return claims;
+        }
+        // Merge verified_claims.claims into top level
+        return {
+            ...claims,
+            ...claims.verified_claims.claims,
+        };
+    }
+}

package/src/model/discovery-service.d.ts

@@ -0,0 +1,46 @@
+import { Agent } from 'undici';
+import { IssuerMetadata } from './issuer-metadata.js';
+import { JWKSet } from './jwks.js';
+/**
+ * Service for fetching OIDC discovery documents and JWKS.
+ *
+ * Handles fetching and parsing of OpenID Connect discovery documents
+ * and JSON Web Key Sets from authorization servers.
+ */
+export declare class DiscoveryService {
+    /**
+     * Fetches and parses an OIDC discovery document.
+     *
+     * @param discoveryUrl - URL to the .well-known/openid-configuration endpoint
+     * @param httpAgent - Optional undici Agent for mTLS
+     * @returns Parsed issuer metadata
+     * @throws Error if the discovery document cannot be fetched or parsed
+     */
+    static fetchDiscoveryDocument(discoveryUrl: string, httpAgent?: Agent): Promise<IssuerMetadata>;
+    /**
+     * Fetches and parses a JWKS document.
+     *
+     * @param jwksUri - URL to the JWKS endpoint
+     * @param httpAgent - Optional HTTPS agent for mTLS
+     * @returns Parsed JWKS
+     * @throws Error if the JWKS cannot be fetched or parsed
+     */
+    static fetchJwks(jwksUri: string, httpAgent?: Agent): Promise<JWKSet>;
+    /**
+     * Validates that required discovery document fields are present.
+     *
+     * @param metadata - Discovery document to validate
+     * @throws Error if required fields are missing
+     */
+    private static validateDiscoveryDocument;
+    /**
+     * Applies mtls_endpoint_aliases to override standard endpoints.
+     *
+     * If mtls_endpoint_aliases are present, they should be used instead of
+     * the standard endpoints for certificate-bound operations.
+     *
+     * @param metadata - Original discovery metadata
+     * @returns Metadata with mTLS aliases applied
+     */
+    private static applyMtlsAliases;
+}

package/src/model/discovery-service.js

@@ -0,0 +1,112 @@
+/**
+ * Service for fetching OIDC discovery documents and JWKS.
+ *
+ * Handles fetching and parsing of OpenID Connect discovery documents
+ * and JSON Web Key Sets from authorization servers.
+ */
+export class DiscoveryService {
+    /**
+     * Fetches and parses an OIDC discovery document.
+     *
+     * @param discoveryUrl - URL to the .well-known/openid-configuration endpoint
+     * @param httpAgent - Optional undici Agent for mTLS
+     * @returns Parsed issuer metadata
+     * @throws Error if the discovery document cannot be fetched or parsed
+     */
+    static async fetchDiscoveryDocument(discoveryUrl, httpAgent) {
+        try {
+            const response = await fetch(discoveryUrl, {
+                method: 'GET',
+                headers: {
+                    Accept: 'application/json',
+                },
+                dispatcher: httpAgent, // undici uses 'dispatcher' instead of 'agent'
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch discovery document: ${response.status} ${response.statusText}`);
+            }
+            const metadata = (await response.json());
+            // Validate required fields
+            this.validateDiscoveryDocument(metadata);
+            // Apply mtls_endpoint_aliases if present
+            return this.applyMtlsAliases(metadata);
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch discovery document from ${discoveryUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Fetches and parses a JWKS document.
+     *
+     * @param jwksUri - URL to the JWKS endpoint
+     * @param httpAgent - Optional HTTPS agent for mTLS
+     * @returns Parsed JWKS
+     * @throws Error if the JWKS cannot be fetched or parsed
+     */
+    static async fetchJwks(jwksUri, httpAgent) {
+        try {
+            const response = await fetch(jwksUri, {
+                method: 'GET',
+                headers: {
+                    Accept: 'application/json',
+                },
+                dispatcher: httpAgent, // undici uses 'dispatcher' instead of 'agent'
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch JWKS: ${response.status} ${response.statusText}`);
+            }
+            const jwks = (await response.json());
+            // Validate JWKS structure
+            if (!jwks.keys || !Array.isArray(jwks.keys)) {
+                throw new Error('Invalid JWKS: missing or invalid keys array');
+            }
+            return jwks;
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch JWKS from ${jwksUri}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Validates that required discovery document fields are present.
+     *
+     * @param metadata - Discovery document to validate
+     * @throws Error if required fields are missing
+     */
+    static validateDiscoveryDocument(metadata) {
+        const requiredFields = [
+            'issuer',
+            'authorization_endpoint',
+            'token_endpoint',
+            'jwks_uri',
+        ];
+        for (const field of requiredFields) {
+            if (!metadata[field]) {
+                throw new Error(`Discovery document missing required field: ${field}`);
+            }
+        }
+    }
+    /**
+     * Applies mtls_endpoint_aliases to override standard endpoints.
+     *
+     * If mtls_endpoint_aliases are present, they should be used instead of
+     * the standard endpoints for certificate-bound operations.
+     *
+     * @param metadata - Original discovery metadata
+     * @returns Metadata with mTLS aliases applied
+     */
+    static applyMtlsAliases(metadata) {
+        if (!metadata.mtls_endpoint_aliases) {
+            return metadata;
+        }
+        const aliases = metadata.mtls_endpoint_aliases;
+        return {
+            ...metadata,
+            token_endpoint: aliases.token_endpoint || metadata.token_endpoint,
+            pushed_authorization_request_endpoint: aliases.pushed_authorization_request_endpoint ||
+                metadata.pushed_authorization_request_endpoint,
+            userinfo_endpoint: aliases.userinfo_endpoint || metadata.userinfo_endpoint,
+            revocation_endpoint: aliases.revocation_endpoint || metadata.revocation_endpoint,
+            introspection_endpoint: aliases.introspection_endpoint || metadata.introspection_endpoint,
+        };
+    }
+}