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

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

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