@lti-tool/core 0.9.0

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

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const CoreLtiClaimsSchema = z.object({
+  'https://purl.imsglobal.org/spec/lti/claim/message_type': z.union([
+    z.literal('LtiResourceLinkRequest'),
+    z.literal('LtiDeepLinkingRequest'),
+  ]),
+  'https://purl.imsglobal.org/spec/lti/claim/version': z.literal('1.3.0'),
+  'https://purl.imsglobal.org/spec/lti/claim/deployment_id': z.string(),
+  'https://purl.imsglobal.org/spec/lti/claim/target_link_uri': z.string(),
+  'https://purl.imsglobal.org/spec/lti/claim/roles': z.array(z.string()).optional(),
+});

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

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+export const ToolPlatformSchema = z
+  .object({
+    guid: z.string(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    url: z.string().optional(),
+    product_family_code: z.string().optional(),
+    contact_email: z.string().optional(),
+    version: z.string().optional(),
+  })
+  .optional();
+
+export const LaunchPresentationSchema = z
+  .object({
+    target: z.string().optional(),
+    url: z.string().optional(),
+    locale: z.string().optional(),
+  })
+  .optional();
+
+export const LisSchema = z
+  .object({
+    person_sourcedid: z.string().optional(),
+  })
+  .optional();

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

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const PrivacyClaimsSchema = z.object({
+  given_name: z.string(),
+  family_name: z.string(),
+  name: z.string(),
+  email: z.string(),
+});

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

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+export const AgsEndpointSchema = z
+  .object({
+    scope: z.array(z.string()),
+    lineitem: z.string().optional(),
+    lineitems: z.string().optional(),
+  })
+  .optional();
+
+export const NrpsServiceSchema = z
+  .object({
+    context_memberships_url: z.string(),
+    service_versions: z.array(z.string()).optional(),
+  })
+  .optional();
+
+export const DeepLinkingSettingsSchema = z
+  .object({
+    deep_link_return_url: z.string(),
+    accept_types: z.array(z.string()),
+    accept_presentation_document_targets: z.array(z.string()),
+    accept_media_types: z.string().optional(),
+    accept_multiple: z.boolean().optional(),
+    auto_create: z.boolean().optional(),
+    data: z.string().optional(),
+  })
+  .optional();

package/src/schemas/lti13/lti13JwtPayload.schema.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+import { BaseJwtClaimsSchema } from './claims/baseJwtClaims.schema.js';
+import { ContextSchema, ResourceLinkSchema } from './claims/contextClaims.schema.js';
+import { CoreLtiClaimsSchema } from './claims/coreLtiClaims.schema.js';
+import {
+  LaunchPresentationSchema,
+  LisSchema,
+  ToolPlatformSchema,
+} from './claims/platformClaims.schema.js';
+import { PrivacyClaimsSchema } from './claims/privacyClaims.schema.js';
+import {
+  AgsEndpointSchema,
+  DeepLinkingSettingsSchema,
+  NrpsServiceSchema,
+} from './claims/serviceClaims.schema.js';
+
+export const LTI13JwtPayloadSchema = BaseJwtClaimsSchema.extend(PrivacyClaimsSchema.shape)
+  .extend(CoreLtiClaimsSchema.shape)
+  .extend({
+    'https://purl.imsglobal.org/spec/lti/claim/resource_link': ResourceLinkSchema,
+    'https://purl.imsglobal.org/spec/lti/claim/context': ContextSchema,
+    'https://purl.imsglobal.org/spec/lti/claim/tool_platform': ToolPlatformSchema,
+    'https://purl.imsglobal.org/spec/lti/claim/lis': LisSchema,
+    'https://purl.imsglobal.org/spec/lti/claim/launch_presentation':
+      LaunchPresentationSchema,
+    'https://purl.imsglobal.org/spec/lti/claim/custom': z
+      .record(z.string(), z.string())
+      .optional(),
+    'https://purl.imsglobal.org/spec/lti-ags/claim/endpoint': AgsEndpointSchema,
+    'https://purl.imsglobal.org/spec/lti-nrps/claim/namesroleservice': NrpsServiceSchema,
+    'https://purl.imsglobal.org/spec/lti-dl/claim/deep_linking_settings':
+      DeepLinkingSettingsSchema,
+  });
+
+export type LTI13JwtPayload = z.infer<typeof LTI13JwtPayloadSchema>;

package/src/schemas/lti13/lti13Launch.schema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+export const LTI13LaunchSchema = z.object({
+  id_token: z.jwt(),
+  state: z.string(),
+});
+
+/**
+ * Schema for verifyLaunch method parameters - uses consistent camelCase naming
+ * for method parameters while LTI13LaunchSchema uses spec-compliant snake_case
+ */
+export const VerifyLaunchParamsSchema = z.object({
+  idToken: z.string().min(1, 'idToken is required'),
+  state: z.string().min(1, 'state is required'),
+});

package/src/schemas/lti13/lti13Login.schema.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+export const LTI13LoginSchema = z.object({
+  iss: z.string().min(1),
+  login_hint: z.string().min(1),
+  target_link_uri: z.url(),
+  client_id: z.string().min(1),
+  lti_deployment_id: z.string().min(1),
+  lti_message_hint: z.string().optional(),
+});
+
+/**
+ * Schema for handleLogin method parameters - extends LTI13LoginSchema
+ * with the additional launchUrl parameter needed for method calls
+ */
+export const HandleLoginParamsSchema = LTI13LoginSchema.extend({
+  launchUrl: z.union([z.url(), z.instanceof(URL)]),
+});

package/src/services/ags.service.ts

@@ -0,0 +1,92 @@
+import type { BaseLogger } from 'pino';
+
+import type { LTISession } from '../interfaces/ltiSession.js';
+import type { LTIStorage } from '../interfaces/ltiStorage.js';
+import type { ScoreSubmission } from '../schemas/lti13/ags/scoreSubmission.schema.js';
+import { getValidLaunchConfig } from '../utils/launchConfigValidation.js';
+
+import type { TokenService } from './token.service.js';
+
+/**
+ * Assignment and Grade Services (AGS) implementation for LTI 1.3.
+ * Provides methods to submit grades and scores back to the platform.
+ *
+ * @see https://www.imsglobal.org/spec/lti-ags/v2p0
+ */
+export class AGSService {
+  constructor(
+    private tokenService: TokenService,
+    private storage: LTIStorage,
+    private logger: BaseLogger,
+  ) {}
+
+  /**
+   * Submits a grade score to the platform using LTI Assignment and Grade Services.
+   *
+   * @param session - Active LTI session containing AGS endpoint configuration
+   * @param score - Score submission data including grade value and metadata
+   * @returns Promise resolving to the HTTP response from the platform
+   * @throws {Error} When AGS is not available for the session or submission fails
+   *
+   * @example
+   * ```typescript
+   * await agsService.submitScore(session, {
+   *   scoreGiven: 85,
+   *   scoreMaximum: 100,
+   *   comment: 'Great work!',
+   *   activityProgress: 'Completed',
+   *   gradingProgress: 'FullyGraded'
+   * });
+   * ```
+   */
+  async submitScore(session: LTISession, score: ScoreSubmission): Promise<Response> {
+    if (!session.services?.ags?.lineitem) {
+      throw new Error('AGS not available for this session');
+    }
+
+    // Get launch config to access token URL
+    const launchConfig = await getValidLaunchConfig(
+      this.storage,
+      session.platform.issuer,
+      session.platform.clientId,
+      session.platform.deploymentId,
+    );
+
+    const token = await this.tokenService.getBearerToken(
+      session.platform.clientId,
+      // Need to get token URL from platform storage
+      launchConfig.tokenUrl,
+      'https://purl.imsglobal.org/spec/lti-ags/scope/score',
+    );
+
+    const scorePayload = {
+      userId: score.userId,
+      scoreGiven: score.scoreGiven,
+      scoreMaximum: score.scoreMaximum,
+      comment: score.comment,
+      timestamp: score.timestamp || new Date().toISOString(),
+      activityProgress: score.activityProgress,
+      gradingProgress: score.gradingProgress,
+    };
+
+    const response = await fetch(`${session.services.ags.lineitem}/scores`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/vnd.ims.lis.v1.score+json',
+      },
+      body: JSON.stringify(scorePayload),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      this.logger.error(
+        { error, status: response.status, statusText: response.statusText },
+        'AGS score submission failed',
+      );
+      throw new Error(`AGS score submission failed: ${response.statusText}`);
+    }
+
+    return response;
+  }
+}

package/src/services/session.service.ts

@@ -0,0 +1,115 @@
+import type { LTISession } from '../interfaces/ltiSession.js';
+import type { LTI13JwtPayload } from '../schemas/index.js';
+
+/**
+ * Creates an LTI session object from a validated LTI 1.3 JWT payload.
+ * Extracts user information, context data, and available services into a structured session.
+ *
+ * @param lti13JwtPayload - Validated LTI 1.3 JWT payload from successful launch
+ * @returns Complete LTI session object with user, context, and service information
+ */
+// oxlint-disable-next-line max-lines-per-function
+export function createSession(lti13JwtPayload: LTI13JwtPayload): LTISession {
+  const roles = lti13JwtPayload['https://purl.imsglobal.org/spec/lti/claim/roles'] || [];
+  const context = lti13JwtPayload['https://purl.imsglobal.org/spec/lti/claim/context'];
+  const platform =
+    lti13JwtPayload['https://purl.imsglobal.org/spec/lti/claim/tool_platform'];
+  const resourceLink =
+    lti13JwtPayload['https://purl.imsglobal.org/spec/lti/claim/resource_link'];
+  const customClaims =
+    lti13JwtPayload['https://purl.imsglobal.org/spec/lti/claim/custom'] || {};
+  const agsEndpoint =
+    lti13JwtPayload['https://purl.imsglobal.org/spec/lti-ags/claim/endpoint'];
+  const nrpsService =
+    lti13JwtPayload['https://purl.imsglobal.org/spec/lti-nrps/claim/namesroleservice'];
+  const deepLinkingSettings =
+    lti13JwtPayload['https://purl.imsglobal.org/spec/lti-dl/claim/deep_linking_settings'];
+
+  const isInstructor = roles.some((role) => role.includes('Instructor'));
+  const isStudent = roles.some((role) => role.includes('Learner'));
+  const isAdmin = roles.some((role) => role.includes('Administrator'));
+
+  const services: Record<string, unknown> = {};
+  if (agsEndpoint) {
+    services.ags = {
+      lineitem: agsEndpoint.lineitem,
+      lineitems: agsEndpoint.lineitems,
+      scopes: agsEndpoint.scope || [],
+    };
+  }
+  if (nrpsService) {
+    services.nrps = {
+      membershipUrl: nrpsService.context_memberships_url,
+      versions: nrpsService.service_versions || [],
+    };
+  }
+  if (deepLinkingSettings) {
+    services.deepLinking = {
+      returnUrl: deepLinkingSettings.deep_link_return_url,
+      acceptTypes: deepLinkingSettings.accept_types || [],
+      acceptPresentationDocumentTargets:
+        deepLinkingSettings.accept_presentation_document_targets || [],
+      acceptMediaTypes: deepLinkingSettings.accept_media_types,
+      autoCreate: deepLinkingSettings.auto_create,
+      data: deepLinkingSettings.data,
+    };
+  }
+
+  // Extract simplified roles
+  const simplifiedRoles: string[] = [];
+  for (const role of roles) {
+    if (role.includes('Instructor')) simplifiedRoles.push('instructor');
+    if (role.includes('Learner')) simplifiedRoles.push('student');
+    if (role.includes('Administrator')) simplifiedRoles.push('admin');
+    if (role.includes('ContentDeveloper')) simplifiedRoles.push('content-developer');
+    if (role.includes('Member')) simplifiedRoles.push('member');
+  }
+
+  // Remove duplicates
+  const uniqueRoles = [...new Set(simplifiedRoles)];
+
+  return {
+    jwtPayload: lti13JwtPayload,
+    id: crypto.randomUUID(),
+    user: {
+      id: lti13JwtPayload.sub,
+      name: lti13JwtPayload.name,
+      email: lti13JwtPayload.email,
+      familyName: lti13JwtPayload.family_name,
+      givenName: lti13JwtPayload.given_name,
+      roles: uniqueRoles,
+    },
+    context: {
+      id: context?.id || '',
+      label: context?.label || context?.id || '',
+      title: context?.title || '',
+    },
+    platform: {
+      issuer: lti13JwtPayload.iss,
+      clientId: Array.isArray(lti13JwtPayload.aud)
+        ? lti13JwtPayload.aud[0]
+        : lti13JwtPayload.aud,
+      deploymentId:
+        lti13JwtPayload['https://purl.imsglobal.org/spec/lti/claim/deployment_id'],
+      name: platform?.name || lti13JwtPayload.iss,
+    },
+    launch: {
+      target:
+        lti13JwtPayload['https://purl.imsglobal.org/spec/lti/claim/target_link_uri'],
+    },
+    resourceLink: resourceLink
+      ? {
+          id: resourceLink.id,
+          title: resourceLink.title,
+        }
+      : undefined,
+    customParameters: customClaims,
+    services: Object.keys(services).length > 0 ? services : undefined,
+    isAdmin,
+    isInstructor,
+    isStudent,
+    isAssignmentAndGradesAvailable: !!agsEndpoint,
+    isDeepLinkingAvailable: !!deepLinkingSettings,
+    isNameAndRolesAvailable: !!nrpsService,
+  };
+}

package/src/services/token.service.ts

@@ -0,0 +1,84 @@
+import { SignJWT } from 'jose';
+
+/**
+ * Service for handling OAuth2 client credentials flow and JWT client assertions.
+ * Used for obtaining bearer tokens to access LTI Advantage services (AGS, NRPS, etc.).
+ *
+ * Implements RFC 7523 (JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants)
+ * as required by LTI 1.3 security framework.
+ */
+export class TokenService {
+  /**
+   * Creates a new TokenService instance.
+   *
+   * @param keyPair - RSA key pair for signing client assertion JWTs (must be RS256 compatible)
+   * @param keyId - Key identifier for JWT header, should match JWKS key ID (defaults to 'main')
+   */
+  constructor(
+    private keyPair: CryptoKeyPair,
+    private keyId = 'main',
+  ) {}
+
+  /**
+   * Creates a JWT client assertion for OAuth2 client credentials flow.
+   *
+   * @param clientId - OAuth2 client identifier
+   * @param tokenUrl - Platform's token endpoint URL
+   * @returns Signed JWT client assertion
+   */
+  async createClientAssertion(clientId: string, tokenUrl: string): Promise<string> {
+    return await new SignJWT({
+      iss: clientId,
+      sub: clientId,
+      aud: tokenUrl,
+      iat: Math.floor(Date.now() / 1000),
+      exp: Math.floor(Date.now() / 1000) + 300,
+      jti: crypto.randomUUID(),
+    })
+      .setProtectedHeader({
+        alg: 'RS256',
+        kid: this.keyId,
+        typ: 'JWT',
+      })
+      .sign(this.keyPair.privateKey);
+  }
+
+  /**
+   * Obtains an OAuth2 bearer token using client credentials flow with JWT assertion.
+   *
+   * @param clientId - OAuth2 client identifier
+   * @param tokenUrl - Platform's token endpoint URL
+   * @param scope - Requested OAuth2 scope (e.g., AGS score scope)
+   * @returns Bearer access token for API calls
+   */
+  async getBearerToken(
+    clientId: string,
+    tokenUrl: string,
+    scope: string,
+  ): Promise<string> {
+    const assertion = await this.createClientAssertion(clientId, tokenUrl);
+
+    const response = await fetch(tokenUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'client_credentials',
+        client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+        client_assertion: assertion,
+        scope,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Token request failed: ${response.status} ${response.statusText}`);
+    }
+
+    const tokenData = await response.json();
+
+    if (!tokenData.access_token) {
+      throw new Error('Token response missing access_token');
+    }
+
+    return tokenData.access_token;
+  }
+}

package/src/utils/launchConfigValidation.ts

@@ -0,0 +1,16 @@
+import type { LTILaunchConfig, LTIStorage } from '../interfaces/index.js';
+
+export async function getValidLaunchConfig(
+  storage: LTIStorage,
+  iss: string,
+  clientId: string,
+  deploymentId: string,
+): Promise<LTILaunchConfig> {
+  const launchConfig = await storage.getLaunchConfig(iss, clientId, deploymentId);
+
+  if (!launchConfig) {
+    throw new Error('No valid launch config found');
+  }
+
+  return launchConfig;
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}