@lti-tool/core 0.13.0 → 0.13.2

package/dist/ltiTool.js

@@ -10,6 +10,7 @@ import { DynamicRegistrationService } from './services/dynamicRegistration.servi
 import { NRPSService } from './services/nrps.service.js';
 import { createSession } from './services/session.service.js';
 import { TokenService } from './services/token.service.js';
+import { formatError } from './utils/errorFormatting.js';
 import { getValidLaunchConfig } from './utils/launchConfigValidation.js';
 /**
  * Main LTI 1.3 Tool implementation providing secure authentication, launch verification,
@@ -82,38 +83,29 @@ export class LTITool {
      * @throws {Error} When platform configuration is not found
      */
     async handleLogin(params) {
-        const validatedParams = HandleLoginParamsSchema.parse(params);
-        const nonce = crypto.randomUUID();
-        // Store nonce with expiration for replay attack prevention
-        const nonceExpirationSeconds = this.config.security?.nonceExpirationSeconds ?? 600;
-        const nonceExpiresAt = new Date(Date.now() + nonceExpirationSeconds * 1000);
-        await this.config.storage.storeNonce(nonce, nonceExpiresAt);
-        const state = await new SignJWT({
-            nonce,
-            iss: validatedParams.iss,
-            client_id: validatedParams.client_id,
-            target_link_uri: validatedParams.target_link_uri,
-            exp: Math.floor(Date.now() / 1000) +
-                (this.config.security?.stateExpirationSeconds ?? 600),
-        })
-            .setProtectedHeader({ alg: 'HS256' })
-            .sign(this.config.stateSecret);
-        const launchConfig = await getValidLaunchConfig(this.config.storage, validatedParams.iss, validatedParams.client_id, validatedParams.lti_deployment_id);
-        const authUrl = new URL(launchConfig.authUrl);
-        authUrl.searchParams.set('scope', 'openid');
-        authUrl.searchParams.set('response_type', 'id_token');
-        authUrl.searchParams.set('response_mode', 'form_post');
-        authUrl.searchParams.set('prompt', 'none');
-        authUrl.searchParams.set('client_id', validatedParams.client_id);
-        authUrl.searchParams.set('redirect_uri', validatedParams.launchUrl.toString());
-        authUrl.searchParams.set('login_hint', validatedParams.login_hint);
-        authUrl.searchParams.set('state', state);
-        authUrl.searchParams.set('nonce', nonce);
-        authUrl.searchParams.set('lti_deployment_id', validatedParams.lti_deployment_id);
-        if (validatedParams.lti_message_hint) {
-            authUrl.searchParams.set('lti_message_hint', validatedParams.lti_message_hint);
-        }
-        return authUrl.toString();
+        try {
+            const validatedParams = HandleLoginParamsSchema.parse(params);
+            const nonce = crypto.randomUUID();
+            // Store nonce with expiration for replay attack prevention
+            const nonceExpirationSeconds = this.config.security?.nonceExpirationSeconds ?? 600;
+            const nonceExpiresAt = new Date(Date.now() + nonceExpirationSeconds * 1000);
+            await this.config.storage.storeNonce(nonce, nonceExpiresAt);
+            const state = await new SignJWT({
+                nonce,
+                iss: validatedParams.iss,
+                client_id: validatedParams.client_id,
+                target_link_uri: validatedParams.target_link_uri,
+                exp: Math.floor(Date.now() / 1000) +
+                    (this.config.security?.stateExpirationSeconds ?? 600),
+            })
+                .setProtectedHeader({ alg: 'HS256' })
+                .sign(this.config.stateSecret);
+            const launchConfig = await getValidLaunchConfig(this.config.storage, validatedParams.iss, validatedParams.client_id, validatedParams.lti_deployment_id);
+            return buildAuthUrl(launchConfig, validatedParams, state, nonce);
+        }
+        catch (error) {
+            throw new Error(`[LTI] Login initiation failed for issuer '${params.iss}', client '${params.client_id}': ${formatError(error)}`);
+        }
     }
     /**
      * Verifies and validates an LTI 1.3 launch by checking JWT signatures, nonces, and claims.
@@ -131,39 +123,44 @@ export class LTITool {
      * @throws {Error} When verification fails for security reasons
      */
     async verifyLaunch(idToken, state) {
-        const validatedParams = VerifyLaunchParamsSchema.parse({ idToken, state });
-        // 1. UNVERIFIED - get issuer
-        const unverified = decodeJwt(validatedParams.idToken);
-        if (!unverified.iss) {
-            throw new Error('No issuer in token');
-        }
-        // 2. get the launchConfig so we can get the remote JWKS from our data store
-        const launchConfig = await getValidLaunchConfig(this.config.storage, unverified.iss, unverified.aud, unverified['https://purl.imsglobal.org/spec/lti/claim/deployment_id']);
-        // 3. Verify LMS JWT
-        let jwks = this.jwksCache.get(launchConfig.jwksUrl);
-        if (!jwks) {
-            jwks = createRemoteJWKSet(new URL(launchConfig.jwksUrl));
-            this.jwksCache.set(launchConfig.jwksUrl, jwks);
-        }
-        const { payload } = await jwtVerify(validatedParams.idToken, jwks);
-        // 4. Verify our state JWT
-        const { payload: stateData } = await jwtVerify(validatedParams.state, this.config.stateSecret);
-        // 5. Parse and validate LMS JWT
-        const validated = LTI13JwtPayloadSchema.parse(payload);
-        // 6. Verify client id matches (audience claim)
-        if (validated.aud !== launchConfig.clientId) {
-            throw new Error(`Invalid client_id: expected ${launchConfig.clientId}, got ${validated.aud}`);
-        }
-        // 7. Verify nonce matches
-        if (stateData.nonce !== validated.nonce) {
-            throw new Error('Nonce mismatch');
-        }
-        // 8. Check nonce hasn't been used before (prevent replay attacks)
-        const isValidNonce = await this.config.storage.validateNonce(validated.nonce);
-        if (!isValidNonce) {
-            throw new Error('Nonce has already been used or expired');
-        }
-        return validated;
+        try {
+            const validatedParams = VerifyLaunchParamsSchema.parse({ idToken, state });
+            // 1. UNVERIFIED - get issuer
+            const unverified = decodeJwt(validatedParams.idToken);
+            if (!unverified.iss) {
+                throw new Error('No issuer in token');
+            }
+            // 2. get the launchConfig so we can get the remote JWKS from our data store
+            const launchConfig = await getValidLaunchConfig(this.config.storage, unverified.iss, unverified.aud, unverified['https://purl.imsglobal.org/spec/lti/claim/deployment_id']);
+            // 3. Verify LMS JWT
+            let jwks = this.jwksCache.get(launchConfig.jwksUrl);
+            if (!jwks) {
+                jwks = createRemoteJWKSet(new URL(launchConfig.jwksUrl));
+                this.jwksCache.set(launchConfig.jwksUrl, jwks);
+            }
+            const { payload } = await jwtVerify(validatedParams.idToken, jwks);
+            // 4. Verify our state JWT
+            const { payload: stateData } = await jwtVerify(validatedParams.state, this.config.stateSecret);
+            // 5. Parse and validate LMS JWT
+            const validated = LTI13JwtPayloadSchema.parse(payload);
+            // 6. Verify client id matches (audience claim)
+            if (validated.aud !== launchConfig.clientId) {
+                throw new Error(`Invalid client_id: expected ${launchConfig.clientId}, got ${validated.aud}`);
+            }
+            // 7. Verify nonce matches
+            if (stateData.nonce !== validated.nonce) {
+                throw new Error('Nonce mismatch');
+            }
+            // 8. Check nonce hasn't been used before (prevent replay attacks)
+            const isValidNonce = await this.config.storage.validateNonce(validated.nonce);
+            if (!isValidNonce) {
+                throw new Error('Nonce has already been used or expired');
+            }
+            return validated;
+        }
+        catch (error) {
+            throw new Error(`[LTI] Launch verification failed: ${formatError(error)}`);
+        }
     }
     /**
      * Generates JSON Web Key Set (JWKS) containing the tool's public key for platform verification.
@@ -171,17 +168,22 @@ export class LTITool {
      * @returns JWKS object with the tool's public key for JWT signature verification
      */
     async getJWKS() {
-        const publicJwk = await exportJWK(this.config.keyPair.publicKey);
-        return {
-            keys: [
-                {
-                    ...publicJwk,
-                    use: 'sig',
-                    alg: 'RS256',
-                    kid: this.config.security?.keyId ?? 'main',
-                },
-            ],
-        };
+        try {
+            const publicJwk = await exportJWK(this.config.keyPair.publicKey);
+            return {
+                keys: [
+                    {
+                        ...publicJwk,
+                        use: 'sig',
+                        alg: 'RS256',
+                        kid: this.config.security?.keyId ?? 'main',
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`[LTI] JWKS generation failed: ${formatError(error)}`);
+        }
     }
     /**
      * Creates and stores a new LTI session from validated JWT payload.
@@ -190,9 +192,14 @@ export class LTITool {
      * @returns Created session object with user, context, and service information
      */
     async createSession(lti13JwtPayload) {
-        const session = createSession(lti13JwtPayload);
-        await this.config.storage.addSession(session);
-        return session;
+        try {
+            const session = createSession(lti13JwtPayload);
+            await this.config.storage.addSession(session);
+            return session;
+        }
+        catch (error) {
+            throw new Error(`[Session] Creation failed for user '${lti13JwtPayload.sub}': ${formatError(error)}`);
+        }
     }
     /**
      * Retrieves an existing LTI session by session ID.
@@ -201,8 +208,13 @@ export class LTITool {
      * @returns Session object if found, undefined otherwise
      */
     async getSession(sessionId) {
-        const validatedSessionId = SessionIdSchema.parse(sessionId);
-        return await this.config.storage.getSession(validatedSessionId);
+        try {
+            const validatedSessionId = SessionIdSchema.parse(sessionId);
+            return await this.config.storage.getSession(validatedSessionId);
+        }
+        catch (error) {
+            throw new Error(`[Session] Retrieval failed for ID '${sessionId}': ${formatError(error)}`);
+        }
     }
     /**
      * Submits a grade score to the platform using Assignment and Grade Services (AGS).
@@ -218,7 +230,12 @@ export class LTITool {
         if (!score) {
             throw new Error('score is required');
         }
-        await this.agsService.submitScore(session, score);
+        try {
+            await this.agsService.submitScore(session, score);
+        }
+        catch (error) {
+            throw new Error(`[AGS] Score submission failed for user '${score.userId}': ${formatError(error)}`);
+        }
     }
     /**
      * Retrieves all scores for a specific line item from the platform using Assignment and Grade Services (AGS).
@@ -237,9 +254,14 @@ export class LTITool {
         if (!session) {
             throw new Error('session is required');
         }
-        const response = await this.agsService.getScores(session);
-        const data = await response.json();
-        return ResultsSchema.parse(data);
+        try {
+            const response = await this.agsService.getScores(session);
+            const data = await response.json();
+            return ResultsSchema.parse(data);
+        }
+        catch (error) {
+            throw new Error(`[AGS] Scores retrieval failed for session '${session.id}': ${formatError(error)}`);
+        }
     }
     /**
      * Retrieves line items (gradebook columns) from the platform using Assignment and Grade Services (AGS).
@@ -252,9 +274,14 @@ export class LTITool {
         if (!session) {
             throw new Error('session is required');
         }
-        const response = await this.agsService.listLineItems(session);
-        const data = await response.json();
-        return LineItemsSchema.parse(data);
+        try {
+            const response = await this.agsService.listLineItems(session);
+            const data = await response.json();
+            return LineItemsSchema.parse(data);
+        }
+        catch (error) {
+            throw new Error(`[AGS] Line items listing failed for session '${session.id}': ${formatError(error)}`);
+        }
     }
     /**
      * Retrieves a specific line item (gradebook column) from the platform using Assignment and Grade Services (AGS).
@@ -267,9 +294,14 @@ export class LTITool {
         if (!session) {
             throw new Error('session is required');
         }
-        const response = await this.agsService.getLineItem(session);
-        const data = await response.json();
-        return LineItemSchema.parse(data);
+        try {
+            const response = await this.agsService.getLineItem(session);
+            const data = await response.json();
+            return LineItemSchema.parse(data);
+        }
+        catch (error) {
+            throw new Error(`[AGS] Line item retrieval failed for session '${session.id}': ${formatError(error)}`);
+        }
     }
     /**
      * Creates a new line item (gradebook column) on the platform using Assignment and Grade Services (AGS).
@@ -297,9 +329,14 @@ export class LTITool {
         if (!createLineItem) {
             throw new Error('createLineItem is required');
         }
-        const response = await this.agsService.createLineItem(session, createLineItem);
-        const data = await response.json();
-        return LineItemSchema.parse(data);
+        try {
+            const response = await this.agsService.createLineItem(session, createLineItem);
+            const data = await response.json();
+            return LineItemSchema.parse(data);
+        }
+        catch (error) {
+            throw new Error(`[AGS] Line item creation failed for '${createLineItem.label}': ${formatError(error)}`);
+        }
     }
     /**
      * Updates an existing line item (gradebook column) on the platform using Assignment and Grade Services (AGS).
@@ -316,9 +353,14 @@ export class LTITool {
         if (!updateLineItem) {
             throw new Error('lineItem is required');
         }
-        const response = await this.agsService.updateLineItem(session, updateLineItem);
-        const data = await response.json();
-        return LineItemSchema.parse(data);
+        try {
+            const response = await this.agsService.updateLineItem(session, updateLineItem);
+            const data = await response.json();
+            return LineItemSchema.parse(data);
+        }
+        catch (error) {
+            throw new Error(`[AGS] Line item update failed for '${updateLineItem.label}': ${formatError(error)}`);
+        }
     }
     /**
      * Deletes a line item (gradebook column) from the platform using Assignment and Grade Services (AGS).
@@ -330,7 +372,12 @@ export class LTITool {
         if (!session) {
             throw new Error('session is required');
         }
-        await this.agsService.deleteLineItem(session);
+        try {
+            await this.agsService.deleteLineItem(session);
+        }
+        catch (error) {
+            throw new Error(`[AGS] Line item deletion failed for session '${session.id}': ${formatError(error)}`);
+        }
     }
     /**
      * Retrieves course/context members using Names and Role Provisioning Services (NRPS).
@@ -351,22 +398,27 @@ export class LTITool {
         if (!session) {
             throw new Error('session is required');
         }
-        const response = await this.nrpsService.getMembers(session);
-        const data = await response.json();
-        const validated = NRPSContextMembershipResponseSchema.parse(data);
-        // Transform to clean camelCase format
-        return validated.members.map((member) => ({
-            status: member.status,
-            name: member.name,
-            picture: member.picture,
-            givenName: member.given_name,
-            familyName: member.family_name,
-            middleName: member.middle_name,
-            email: member.email,
-            userId: member.user_id,
-            lisPersonSourcedId: member.lis_person_sourcedid,
-            roles: member.roles,
-        }));
+        try {
+            const response = await this.nrpsService.getMembers(session);
+            const data = await response.json();
+            const validated = NRPSContextMembershipResponseSchema.parse(data);
+            // Transform to clean camelCase format
+            return validated.members.map((member) => ({
+                status: member.status,
+                name: member.name,
+                picture: member.picture,
+                givenName: member.given_name,
+                familyName: member.family_name,
+                middleName: member.middle_name,
+                email: member.email,
+                userId: member.user_id,
+                lisPersonSourcedId: member.lis_person_sourcedid,
+                roles: member.roles,
+            }));
+        }
+        catch (error) {
+            throw new Error(`[NRPS] Members retrieval failed for session '${session.id}': ${formatError(error)}`);
+        }
     }
     /**
      * Creates a Deep Linking response with selected content items.
@@ -396,7 +448,12 @@ export class LTITool {
         if (!contentItems) {
             throw new Error('contentItems is required');
         }
-        return await this.deepLinkingService.createResponse(session, contentItems);
+        try {
+            return await this.deepLinkingService.createResponse(session, contentItems);
+        }
+        catch (error) {
+            throw new Error(`[Deep Linking] Response creation failed for session '${session.id}': ${formatError(error)}`);
+        }
     }
     /**
      * Fetches and validates the OpenID Connect configuration from an LTI platform during dynamic registration.
@@ -419,7 +476,12 @@ export class LTITool {
         if (!this.dynamicRegistrationService) {
             throw new Error('Dynamic registration service is not configured');
         }
-        return await this.dynamicRegistrationService.fetchPlatformConfiguration(registrationRequest);
+        try {
+            return await this.dynamicRegistrationService.fetchPlatformConfiguration(registrationRequest);
+        }
+        catch (error) {
+            throw new Error(`[Dynamic Registration] Platform configuration fetch failed: ${formatError(error)}`);
+        }
     }
     /**
      * Initiates LTI 1.3 dynamic registration by fetching platform configuration and generating registration form.
@@ -434,7 +496,12 @@ export class LTITool {
         if (!this.dynamicRegistrationService) {
             throw new Error('Dynamic registration service is not configured');
         }
-        return await this.dynamicRegistrationService.initiateDynamicRegistration(registrationRequest, requestPath);
+        try {
+            return await this.dynamicRegistrationService.initiateDynamicRegistration(registrationRequest, requestPath);
+        }
+        catch (error) {
+            throw new Error(`[Dynamic Registration] Initiation failed: ${formatError(error)}`);
+        }
     }
     /**
      * Completes LTI 1.3 dynamic registration by processing form submission and storing client configuration.
@@ -446,9 +513,14 @@ export class LTITool {
      */
     async completeDynamicRegistration(dynamicRegistrationForm) {
         if (!this.dynamicRegistrationService) {
-            throw new Error('Dynmaic registration service is not configured');
+            throw new Error('Dynamic registration service is not configured');
+        }
+        try {
+            return await this.dynamicRegistrationService.completeDynamicRegistration(dynamicRegistrationForm);
+        }
+        catch (error) {
+            throw new Error(`[Dynamic Registration] Completion failed: ${formatError(error)}`);
         }
-        return await this.dynamicRegistrationService.completeDynamicRegistration(dynamicRegistrationForm);
     }
     // Client management
     /**
@@ -457,7 +529,12 @@ export class LTITool {
      * @returns Array of client configurations (without deployment details)
      */
     async listClients() {
-        return await this.config.storage.listClients();
+        try {
+            return await this.config.storage.listClients();
+        }
+        catch (error) {
+            throw new Error(`[Client] Listing failed: ${formatError(error)}`);
+        }
     }
     /**
      * Updates an existing client configuration.
@@ -466,8 +543,13 @@ export class LTITool {
      * @param client - Partial client object with fields to update
      */
     async updateClient(clientId, client) {
-        const validated = UpdateClientSchema.parse(client);
-        return await this.config.storage.updateClient(clientId, validated);
+        try {
+            const validated = UpdateClientSchema.parse(client);
+            return await this.config.storage.updateClient(clientId, validated);
+        }
+        catch (error) {
+            throw new Error(`[Client] Update failed for ID '${clientId}': ${formatError(error)}`);
+        }
     }
     /**
      * Retrieves a specific client configuration by ID.
@@ -476,7 +558,12 @@ export class LTITool {
      * @returns Client configuration if found, undefined otherwise
      */
     async getClientById(clientId) {
-        return await this.config.storage.getClientById(clientId);
+        try {
+            return await this.config.storage.getClientById(clientId);
+        }
+        catch (error) {
+            throw new Error(`[Client] Retrieval failed for ID '${clientId}': ${formatError(error)}`);
+        }
     }
     /**
      * Adds a new LTI client platform configuration.
@@ -485,8 +572,13 @@ export class LTITool {
      * @returns The generated client ID
      */
     async addClient(client) {
-        const validated = AddClientSchema.parse(client);
-        return await this.config.storage.addClient(validated);
+        try {
+            const validated = AddClientSchema.parse(client);
+            return await this.config.storage.addClient(validated);
+        }
+        catch (error) {
+            throw new Error(`[Client] Creation failed for issuer '${client.iss}': ${formatError(error)}`);
+        }
     }
     /**
      * Removes a client configuration and all its deployments.
@@ -494,7 +586,12 @@ export class LTITool {
      * @param clientId - Unique client identifier
      */
     async deleteClient(clientId) {
-        return await this.config.storage.deleteClient(clientId);
+        try {
+            return await this.config.storage.deleteClient(clientId);
+        }
+        catch (error) {
+            throw new Error(`[Client] Deletion failed for ID '${clientId}': ${formatError(error)}`);
+        }
     }
     // Deployment management
     /**
@@ -504,7 +601,12 @@ export class LTITool {
      * @returns Array of deployment configurations for the client
      */
     async listDeployments(clientId) {
-        return await this.config.storage.listDeployments(clientId);
+        try {
+            return await this.config.storage.listDeployments(clientId);
+        }
+        catch (error) {
+            throw new Error(`[Deployment] Listing failed for client '${clientId}': ${formatError(error)}`);
+        }
     }
     /**
      * Retrieves a specific deployment configuration.
@@ -514,7 +616,12 @@ export class LTITool {
      * @returns Deployment configuration if found, undefined otherwise
      */
     async getDeployment(clientId, deploymentId) {
-        return await this.config.storage.getDeployment(clientId, deploymentId);
+        try {
+            return await this.config.storage.getDeployment(clientId, deploymentId);
+        }
+        catch (error) {
+            throw new Error(`[Deployment] Retrieval failed for client '${clientId}', deployment '${deploymentId}': ${formatError(error)}`);
+        }
     }
     /**
      * Adds a new deployment to an existing client.
@@ -524,7 +631,12 @@ export class LTITool {
      * @returns The generated deployment ID
      */
     async addDeployment(clientId, deployment) {
-        return await this.config.storage.addDeployment(clientId, deployment);
+        try {
+            return await this.config.storage.addDeployment(clientId, deployment);
+        }
+        catch (error) {
+            throw new Error(`[Deployment] Creation failed for client '${clientId}': ${formatError(error)}`);
+        }
     }
     /**
      * Updates an existing deployment configuration.
@@ -534,7 +646,12 @@ export class LTITool {
      * @param deployment - Partial deployment object with fields to update
      */
     async updateDeployment(clientId, deploymentId, deployment) {
-        return await this.config.storage.updateDeployment(clientId, deploymentId, deployment);
+        try {
+            return await this.config.storage.updateDeployment(clientId, deploymentId, deployment);
+        }
+        catch (error) {
+            throw new Error(`Deployment update failed for client '${clientId}' and deployment '${deploymentId}': ${formatError(error)}`);
+        }
     }
     /**
      * Removes a deployment from a client.
@@ -543,7 +660,12 @@ export class LTITool {
      * @param deploymentId - Deployment identifier to remove
      */
     async deleteDeployment(clientId, deploymentId) {
-        return await this.config.storage.deleteDeployment(clientId, deploymentId);
+        try {
+            return await this.config.storage.deleteDeployment(clientId, deploymentId);
+        }
+        catch (error) {
+            throw new Error(`[Deployment] Deletion failed for client '${clientId}', deployment '${deploymentId}': ${formatError(error)}`);
+        }
     }
     // Dynamic Registration Session Management
     /**
@@ -554,7 +676,12 @@ export class LTITool {
      * @param session - Registration session data including platform config and tokens
      */
     async setRegistrationSession(sessionId, session) {
-        return await this.config.storage.setRegistrationSession(sessionId, session);
+        try {
+            return await this.config.storage.setRegistrationSession(sessionId, session);
+        }
+        catch (error) {
+            throw new Error(`[Dynamic Registration] Session storage failed for ID '${sessionId}': ${formatError(error)}`);
+        }
     }
     /**
      * Retrieves a registration session by its ID for validation during completion.
@@ -564,7 +691,12 @@ export class LTITool {
      * @returns Registration session if found and not expired, undefined otherwise
      */
     async getRegistrationSession(sessionId) {
-        return await this.config.storage.getRegistrationSession(sessionId);
+        try {
+            return await this.config.storage.getRegistrationSession(sessionId);
+        }
+        catch (error) {
+            throw new Error(`[Dynamic Registration] Session retrieval failed for ID '${sessionId}': ${formatError(error)}`);
+        }
     }
     /**
      * Removes a registration session from storage after completion or expiration.
@@ -573,6 +705,37 @@ export class LTITool {
      * @param sessionId - Unique session identifier to delete
      */
     async deleteRegistrationSession(sessionId) {
-        return await this.config.storage.deleteRegistrationSession(sessionId);
+        try {
+            return await this.config.storage.deleteRegistrationSession(sessionId);
+        }
+        catch (error) {
+            throw new Error(`[Dynamic Registration] Session deletion failed for ID '${sessionId}': ${formatError(error)}`);
+        }
+    }
+}
+/**
+ * Builds the authorization URL for LTI 1.3 OIDC authentication flow.
+ *
+ * @param launchConfig - Launch configuration containing auth endpoints
+ * @param validatedParams - Validated login parameters
+ * @param state - State JWT for CSRF protection
+ * @param nonce - Nonce for replay attack prevention
+ * @returns Complete authorization URL with all required parameters
+ */
+function buildAuthUrl(launchConfig, validatedParams, state, nonce) {
+    const authUrl = new URL(launchConfig.authUrl);
+    authUrl.searchParams.set('scope', 'openid');
+    authUrl.searchParams.set('response_type', 'id_token');
+    authUrl.searchParams.set('response_mode', 'form_post');
+    authUrl.searchParams.set('prompt', 'none');
+    authUrl.searchParams.set('client_id', validatedParams.client_id);
+    authUrl.searchParams.set('redirect_uri', validatedParams.launchUrl.toString());
+    authUrl.searchParams.set('login_hint', validatedParams.login_hint);
+    authUrl.searchParams.set('state', state);
+    authUrl.searchParams.set('nonce', nonce);
+    authUrl.searchParams.set('lti_deployment_id', validatedParams.lti_deployment_id);
+    if (validatedParams.lti_message_hint) {
+        authUrl.searchParams.set('lti_message_hint', validatedParams.lti_message_hint);
     }
+    return authUrl.toString();
 }