@lti-tool/core 0.9.0

package/src/interfaces/ltiStorage.ts

@@ -0,0 +1,161 @@
+import type { LTIClient } from './ltiClient.js';
+import type { LTIDeployment } from './ltiDeployment.js';
+import type { LTILaunchConfig } from './ltiLaunchConfig.js';
+import type { LTISession } from './ltiSession.js';
+
+/**
+ * Storage interface for persisting LTI Client configurations, user sessions, and security nonces.
+ * Implement this interface to use different storage backends (memory, database, Redis, etc.).
+ */
+export interface LTIStorage {
+  // Client management
+
+  /**
+   * Retrieves all clients configured in the system.
+   *
+   * @returns Array of all client configurations
+   */
+  listClients(): Promise<Omit<LTIClient, 'deployments'>[]>;
+
+  /**
+   * Retrieves client configuration by its unique id.
+   *
+   * @param clientId - Unique client identifier
+   * @returns Client configuration if found, undefined otherwise
+   */
+  getClientById(clientId: string): Promise<LTIClient | undefined>;
+
+  /**
+   * Adds a new client configuration to storage.
+   *
+   * @param client - Partial client configuration object
+   */
+  addClient(client: Omit<LTIClient, 'id' | 'deployments'>): Promise<string>;
+
+  /**
+   * Updates an existing client configuration.
+   *
+   * @param clientId - Unique client identifier
+   * @param client - Partial client object with fields to update
+   */
+  updateClient(
+    clientId: string,
+    client: Partial<Omit<LTIClient, 'id' | 'deployments'>>,
+  ): Promise<void>;
+
+  /**
+   * Removes a client configuration from storage.
+   *
+   * @param clientId - Unique client identifier
+   */
+  deleteClient(clientId: string): Promise<void>;
+
+  // Deployment management
+
+  /**
+   * Lists all deployments for a specific client.
+   *
+   * @param clientId - Client identifier
+   * @returns Array of deployment configurations
+   */
+  listDeployments(clientId: string): Promise<LTIDeployment[]>;
+
+  /**
+   * Retrieves deployment configuration by client ID and deployment ID (admin use).
+   *
+   * @param clientId - Unique client identifier
+   * @param deploymentId - Deployment identifier
+   * @returns Deployment configuration if found, undefined otherwise
+   */
+  getDeployment(
+    clientId: string,
+    deploymentId: string,
+  ): Promise<LTIDeployment | undefined>;
+
+  /**
+   * Adds a new deployment to an existing client.
+   *
+   * @param clientId - Client identifier
+   * @param deployment - Deployment configuration to add
+   */
+  addDeployment(clientId: string, deployment: Omit<LTIDeployment, 'id'>): Promise<string>;
+
+  /**
+   * Updates an existing deployment configuration.
+   * @param clientId - Client identifier
+   * @param deploymentId - Deployment identifier to update
+   * @param deployment - Partial deployment object with fields to update
+   */
+  updateDeployment(
+    clientId: string,
+    deploymentId: string,
+    deployment: Partial<LTIDeployment>,
+  ): Promise<void>;
+
+  /**
+   * Removes a deployment from a Client.
+   *
+   * @param clientId - Client identifier
+   * @param deploymentId - Deployment identifier to remove
+   */
+  deleteDeployment(clientId: string, deploymentId: string): Promise<void>;
+
+  // Session management
+
+  /**
+   * Retrieves an active user session by session ID.
+   *
+   * @param sessionId - Unique session identifier (typically a UUID)
+   * @returns Session object if found and valid, undefined otherwise
+   */
+  getSession(sessionId: string): Promise<LTISession | undefined>;
+
+  /**
+   * Stores a new user session after successful LTI launch.
+   *
+   * @param session - Complete session object with user, context, and service data
+   * @returns The session ID for reference
+   */
+  addSession(session: LTISession): Promise<string>;
+
+  // Nonce validation (prevent replay attacks)
+
+  /**
+   * Stores a nonce with expiration time for replay attack prevention.
+   *
+   * @param nonce - Unique nonce value (typically a UUID)
+   * @param expiresAt - When this nonce should be considered expired
+   */
+  storeNonce(nonce: string, expiresAt: Date): Promise<void>;
+
+  /**
+   * Validates a nonce and marks it as used to prevent replay attacks.
+   *
+   * @param nonce - Nonce value to validate
+   * @returns true if nonce is valid and unused, false if already used or expired
+   */
+  validateNonce(nonce: string): Promise<boolean>;
+
+  // Launch configuration management
+
+  /**
+   * Retrieves launch configuration for LTI authentication flow.
+   *
+   * @param iss - Platform issuer URL (identifies the LMS)
+   * @param clientId - OAuth2 client identifier for this tool
+   * @param deploymentId - Deployment identifier within the platform
+   * @returns Launch configuration if found, undefined otherwise
+   */
+  getLaunchConfig(
+    iss: string,
+    clientId: string,
+    deploymentId: string,
+  ): Promise<LTILaunchConfig | undefined>;
+
+  /**
+   * Stores launch configuration for platform authentication.
+   *
+   * @param launchConfig - Complete launch configuration with auth URLs and keys
+   */
+  saveLaunchConfig(launchConfig: LTILaunchConfig): Promise<void>;
+}

package/src/ltiTool.ts

@@ -0,0 +1,394 @@
+import { SignJWT, createRemoteJWKSet, decodeJwt, exportJWK, jwtVerify } from 'jose';
+import type { Logger } from 'pino';
+
+import type { JWKS } from './interfaces/jwks.js';
+import type { LTIClient } from './interfaces/ltiClient.js';
+import type { LTIConfig } from './interfaces/ltiConfig.js';
+import type { LTIDeployment } from './interfaces/ltiDeployment.js';
+import type { LTISession } from './interfaces/ltiSession.js';
+import { AddClientSchema, UpdateClientSchema } from './schemas/client.schema.js';
+import {
+  HandleLoginParamsSchema,
+  type LTI13JwtPayload,
+  LTI13JwtPayloadSchema,
+  SessionIdSchema,
+  VerifyLaunchParamsSchema,
+} from './schemas/index.js';
+import type { ScoreSubmission } from './schemas/lti13/ags/scoreSubmission.schema.js';
+import { AGSService } from './services/ags.service.js';
+import { createSession } from './services/session.service.js';
+import { TokenService } from './services/token.service.js';
+import { getValidLaunchConfig } from './utils/launchConfigValidation.js';
+
+/**
+ * Main LTI 1.3 Tool implementation providing secure authentication, launch verification,
+ * and LTI Advantage services integration.
+ *
+ * @example
+ * ```typescript
+ * const ltiTool = new LTITool({
+ *   stateSecret: new TextEncoder().encode('your-secret'),
+ *   keyPair: await generateKeyPair('RS256'),
+ *   storage: new MemoryStorage()
+ * });
+ *
+ * // Handle login initiation
+ * const authUrl = await ltiTool.handleLogin({
+ *   client_id: 'your-client-id',
+ *   iss: 'https://platform.example.com',
+ *   launchUrl: 'https://yourtool.com/lti/launch',
+ *   login_hint: 'user123',
+ *   target_link_uri: 'https://yourtool.com/content',
+ *   lti_deployment_id: 'deployment123'
+ * });
+ * ```
+ */
+export class LTITool {
+  /** Cache for JWKS remote key sets to improve performance */
+  private jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+  private logger: Logger;
+  private tokenService: TokenService;
+  private agsService: AGSService;
+
+  /**
+   * Creates a new LTI Tool instance.
+   *
+   * @param config - Configuration object containing secrets, keys, and storage adapter
+   */
+  constructor(private config: LTIConfig) {
+    this.logger =
+      config.logger ??
+      ({
+        debug: () => {},
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+      } as unknown as Logger);
+
+    this.tokenService = new TokenService(
+      this.config.keyPair,
+      this.config.security?.keyId ?? 'main',
+    );
+    this.agsService = new AGSService(this.tokenService, this.config.storage, this.logger);
+  }
+
+  /**
+   * Handles LTI 1.3 login initiation by generating state/nonce and redirecting to platform auth.
+   *
+   * @param params - Login parameters from the platform
+   * @param params.client_id - OAuth2 client identifier for this tool
+   * @param params.iss - Platform issuer URL (identifies the LMS)
+   * @param params.launchUrl - URL where platform will POST the id_token after auth
+   * @param params.login_hint - Platform-specific user identifier hint
+   * @param params.target_link_uri - Final destination URL after successful launch
+   * @param params.lti_deployment_id - Deployment identifier within the platform
+   * @param params.lti_message_hint - Optional platform-specific message context
+   * @returns Authorization URL to redirect user to for authentication
+   * @throws {Error} When platform configuration is not found
+   */
+  async handleLogin(params: {
+    client_id: string;
+    iss: string;
+    launchUrl: URL | string;
+    login_hint: string;
+    target_link_uri: string;
+    lti_deployment_id: string;
+    lti_message_hint?: string;
+  }): Promise<string> {
+    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();
+  }
+
+  /**
+   * Verifies and validates an LTI 1.3 launch by checking JWT signatures, nonces, and claims.
+   *
+   * Performs comprehensive security validation including:
+   * - JWT signature verification using platform's JWKS
+   * - State JWT verification to prevent CSRF
+   * - Nonce validation to prevent replay attacks
+   * - Client ID and deployment ID verification
+   * - LTI 1.3 claim structure validation
+   *
+   * @param idToken - JWT id_token received from platform after authentication
+   * @param state - State JWT that was generated during login initiation
+   * @returns Validated and parsed LTI 1.3 JWT payload
+   * @throws {Error} When verification fails for security reasons
+   */
+  async verifyLaunch(idToken: string, state: string): Promise<LTI13JwtPayload> {
+    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 as string,
+      unverified['https://purl.imsglobal.org/spec/lti/claim/deployment_id'] as string,
+    );
+
+    // 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;
+  }
+
+  /**
+   * Generates JSON Web Key Set (JWKS) containing the tool's public key for platform verification.
+   *
+   * @returns JWKS object with the tool's public key for JWT signature verification
+   */
+  async getJWKS(): Promise<JWKS> {
+    const publicJwk = await exportJWK(this.config.keyPair.publicKey);
+    return {
+      keys: [
+        {
+          ...publicJwk,
+          use: 'sig',
+          alg: 'RS256',
+          kid: this.config.security?.keyId ?? 'main',
+        },
+      ],
+    };
+  }
+
+  /**
+   * Creates and stores a new LTI session from validated JWT payload.
+   *
+   * @param lti13JwtPayload - Validated LTI 1.3 JWT payload from successful launch
+   * @returns Created session object with user, context, and service information
+   */
+  async createSession(lti13JwtPayload: LTI13JwtPayload): Promise<LTISession> {
+    const session = createSession(lti13JwtPayload);
+    await this.config.storage.addSession(session);
+    return session;
+  }
+
+  /**
+   * Retrieves an existing LTI session by session ID.
+   *
+   * @param sessionId - Unique session identifier
+   * @returns Session object if found, undefined otherwise
+   */
+  async getSession(sessionId: string): Promise<LTISession | undefined> {
+    const validatedSessionId = SessionIdSchema.parse(sessionId);
+    return await this.config.storage.getSession(validatedSessionId);
+  }
+
+  /**
+   * Submits a grade score to the platform using Assignment and Grade Services (AGS).
+   *
+   * @param session - Active LTI session containing AGS service endpoints
+   * @param score - Score submission data including grade value and user ID
+   * @returns Result of the score submission
+   * @throws {Error} When AGS is not available or submission fails
+   */
+  async submitScore(session: LTISession, score: ScoreSubmission): Promise<Response> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+    if (!score) {
+      throw new Error('score is required');
+    }
+    return await this.agsService.submitScore(session, score);
+  }
+
+  // Client management
+
+  /**
+   * Retrieves all configured LTI client platforms.
+   *
+   * @returns Array of client configurations (without deployment details)
+   */
+  async listClients(): Promise<Omit<LTIClient, 'deployments'>[]> {
+    return await this.config.storage.listClients();
+  }
+
+  /**
+   * Updates an existing client configuration.
+   *
+   * @param clientId - Unique client identifier
+   * @param client - Partial client object with fields to update
+   */
+  async updateClient(
+    clientId: string,
+    client: Partial<Omit<LTIClient, 'id' | 'deployments'>>,
+  ): Promise<void> {
+    const validated = UpdateClientSchema.parse(client);
+    return await this.config.storage.updateClient(clientId, validated);
+  }
+
+  /**
+   * Retrieves a specific client configuration by ID.
+   *
+   * @param clientId - Unique client identifier
+   * @returns Client configuration if found, undefined otherwise
+   */
+  async getClientById(clientId: string): Promise<LTIClient | undefined> {
+    return await this.config.storage.getClientById(clientId);
+  }
+
+  /**
+   * Adds a new LTI client platform configuration.
+   *
+   * @param client - Client configuration (ID will be auto-generated)
+   * @returns The generated client ID
+   */
+  async addClient(client: Omit<LTIClient, 'id' | 'deployments'>): Promise<string> {
+    const validated = AddClientSchema.parse(client);
+    return await this.config.storage.addClient(validated);
+  }
+
+  /**
+   * Removes a client configuration and all its deployments.
+   *
+   * @param clientId - Unique client identifier
+   */
+  async deleteClient(clientId: string): Promise<void> {
+    return await this.config.storage.deleteClient(clientId);
+  }
+
+  // Deployment management
+
+  /**
+   * Lists all deployments for a specific client platform.
+   *
+   * @param clientId - Client identifier
+   * @returns Array of deployment configurations for the client
+   */
+  async listDeployments(clientId: string): Promise<LTIDeployment[]> {
+    return await this.config.storage.listDeployments(clientId);
+  }
+
+  /**
+   * Retrieves a specific deployment configuration.
+   *
+   * @param clientId - Client identifier
+   * @param deploymentId - Deployment identifier
+   * @returns Deployment configuration if found, undefined otherwise
+   */
+  async getDeployment(
+    clientId: string,
+    deploymentId: string,
+  ): Promise<LTIDeployment | undefined> {
+    return await this.config.storage.getDeployment(clientId, deploymentId);
+  }
+
+  /**
+   * Adds a new deployment to an existing client.
+   *
+   * @param clientId - Client identifier
+   * @param deployment - Deployment configuration to add
+   * @returns The generated deployment ID
+   */
+  async addDeployment(
+    clientId: string,
+    deployment: Omit<LTIDeployment, 'id'>,
+  ): Promise<string> {
+    return await this.config.storage.addDeployment(clientId, deployment);
+  }
+
+  /**
+   * Updates an existing deployment configuration.
+   *
+   * @param clientId - Client identifier
+   * @param deploymentId - Deployment identifier
+   * @param deployment - Partial deployment object with fields to update
+   */
+  async updateDeployment(
+    clientId: string,
+    deploymentId: string,
+    deployment: Partial<LTIDeployment>,
+  ): Promise<void> {
+    return await this.config.storage.updateDeployment(clientId, deploymentId, deployment);
+  }
+
+  /**
+   * Removes a deployment from a client.
+   *
+   * @param clientId - Client identifier
+   * @param deploymentId - Deployment identifier to remove
+   */
+  async deleteDeployment(clientId: string, deploymentId: string): Promise<void> {
+    return await this.config.storage.deleteDeployment(clientId, deploymentId);
+  }
+}

package/src/schemas/client.schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+import { DeploymentSchema } from './deployment.schema';
+
+export const ClientSchema = z.object({
+  id: z.uuid().describe('Internal stable UUID for the client'),
+  name: z.string().min(1).describe('human-readable name for the platform'),
+  iss: z.url().describe('Platform issuer (unique identifier)'),
+  clientId: z.string().min(1).describe("Your app's client ID on this platform"),
+  authUrl: z.url().describe("Platform's auth endpoint"),
+  tokenUrl: z.url().describe("Platform's token endpoint"),
+  jwksUrl: z.url().describe("Platform's JWKS endpoint"),
+  deployments: z.array(DeploymentSchema),
+});
+
+export const AddClientSchema = ClientSchema.omit({ id: true, deployments: true });
+export const UpdateClientSchema = ClientSchema.omit({ id: true, deployments: true });

package/src/schemas/common.schema.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+
+/**
+ * Common validation schemas used across the LTI tool
+ */
+
+export const SessionIdSchema = z.string().min(1, 'sessionId is required');

package/src/schemas/deployment.schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const DeploymentSchema = z.object({
+  id: z.uuid().describe('Internal stable UUID for this deployment configuration'),
+  deploymentId: z.string().min(1).describe('LMS-provided deployment identifier'),
+  name: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Optional human-readable name for the deployment'),
+  description: z.string().optional().describe('Optional description of the deployment'),
+});

package/src/schemas/index.ts

@@ -0,0 +1,10 @@
+export { SessionIdSchema } from './common.schema.js';
+export {
+  LTI13JwtPayloadSchema,
+  type LTI13JwtPayload,
+} from './lti13/lti13JwtPayload.schema.js';
+export {
+  LTI13LaunchSchema,
+  VerifyLaunchParamsSchema,
+} from './lti13/lti13Launch.schema.js';
+export { HandleLoginParamsSchema, LTI13LoginSchema } from './lti13/lti13Login.schema.js';

package/src/schemas/lti13/ags/scoreSubmission.schema.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+
+/**
+ * Schema for submitting grades via LTI Assignment and Grade Services (AGS).
+ * Validates score data according to LTI AGS v2.0 specification.
+ *
+ * @see https://www.imsglobal.org/spec/lti-ags/v2p0/#score-publish-service
+ */
+export const ScoreSubmissionSchema = z.object({
+  /** Points awarded to the student (must be non-negative) */
+  scoreGiven: z.number().min(0),
+
+  /** Maximum possible points for this assignment (must be non-negative) */
+  scoreMaximum: z.number().min(0),
+
+  /** Optional feedback comment to display to the student */
+  comment: z.string().optional(),
+
+  /** User ID to submit score for (optional - defaults to session user if not provided) */
+  userId: z.string().optional(),
+
+  /** Timestamp when score was generated (optional - defaults to current time) */
+  timestamp: z.iso.datetime().optional(),
+
+  /**
+   * Student's progress on the activity itself.
+   * - Initialized: Student has started but not made progress
+   * - Started: Student has begun working
+   * - InProgress: Student is actively working
+   * - Submitted: Student has submitted work for review
+   * - Completed: Student has finished the activity
+   */
+  activityProgress: z
+    .enum(['Initialized', 'Started', 'InProgress', 'Submitted', 'Completed'])
+    .default('Completed'),
+
+  /**
+   * Instructor's progress on grading the submission.
+   * - NotReady: Submission not ready for grading
+   * - Failed: Grading failed due to error
+   * - Pending: Awaiting automatic grading
+   * - PendingManual: Awaiting manual grading
+   * - FullyGraded: Grading is complete
+   */
+  gradingProgress: z
+    .enum(['NotReady', 'Failed', 'Pending', 'PendingManual', 'FullyGraded'])
+    .default('FullyGraded'),
+});
+
+/**
+ * Type representing a validated score submission for LTI AGS.
+ * Contains grade data and metadata to be sent to the platform.
+ */
+export type ScoreSubmission = z.infer<typeof ScoreSubmissionSchema>;

package/src/schemas/lti13/claims/baseJwtClaims.schema.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+
+export const BaseJwtClaimsSchema = z.object({
+  iss: z.string(),
+  sub: z.string(),
+  aud: z.union([z.string(), z.array(z.string())]),
+  exp: z.number(),
+  iat: z.number(),
+  nbf: z.number().optional(),
+  nonce: z.string(),
+});

package/src/schemas/lti13/claims/contextClaims.schema.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+export const ResourceLinkSchema = z
+  .object({
+    id: z.string(),
+    title: z.string().optional(),
+  })
+  .optional();
+
+export const ContextSchema = z
+  .object({
+    id: z.string(),
+    label: z.string().optional(),
+    title: z.string().optional(),
+  })
+  .optional();