@lti-tool/core 0.9.0

package/dist/services/session.service.js

@@ -0,0 +1,103 @@
+/**
+ * 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) {
+    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 = {};
+    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 = [];
+    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/dist/services/token.service.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare class TokenService {
+    private keyPair;
+    private keyId;
+    /**
+     * 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(keyPair: CryptoKeyPair, keyId?: string);
+    /**
+     * 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
+     */
+    createClientAssertion(clientId: string, tokenUrl: string): Promise<string>;
+    /**
+     * 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
+     */
+    getBearerToken(clientId: string, tokenUrl: string, scope: string): Promise<string>;
+}
+//# sourceMappingURL=token.service.d.ts.map

package/dist/services/token.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.service.d.ts","sourceRoot":"","sources":["../../src/services/token.service.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qBAAa,YAAY;IAQrB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,KAAK;IARf;;;;;OAKG;gBAEO,OAAO,EAAE,aAAa,EACtB,KAAK,SAAS;IAGxB;;;;;;OAMG;IACG,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBhF;;;;;;;OAOG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC;CA0BnB"}

package/dist/services/token.service.js

@@ -0,0 +1,74 @@
+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 {
+    keyPair;
+    keyId;
+    /**
+     * 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(keyPair, keyId = 'main') {
+        this.keyPair = keyPair;
+        this.keyId = keyId;
+    }
+    /**
+     * 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, tokenUrl) {
+        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, tokenUrl, scope) {
+        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/dist/utils/launchConfigValidation.d.ts

@@ -0,0 +1,3 @@
+import type { LTILaunchConfig, LTIStorage } from '../interfaces/index.js';
+export declare function getValidLaunchConfig(storage: LTIStorage, iss: string, clientId: string, deploymentId: string): Promise<LTILaunchConfig>;
+//# sourceMappingURL=launchConfigValidation.d.ts.map

package/dist/utils/launchConfigValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launchConfigValidation.d.ts","sourceRoot":"","sources":["../../src/utils/launchConfigValidation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAE1E,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,CAAC,CAQ1B"}

package/dist/utils/launchConfigValidation.js

@@ -0,0 +1,7 @@
+export async function getValidLaunchConfig(storage, iss, clientId, deploymentId) {
+    const launchConfig = await storage.getLaunchConfig(iss, clientId, deploymentId);
+    if (!launchConfig) {
+        throw new Error('No valid launch config found');
+    }
+    return launchConfig;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@lti-tool/core",
+  "version": "0.9.0",
+  "description": "LTI 1.3 implementation for Node.js",
+  "keywords": [
+    "lti",
+    "lti13",
+    "education",
+    "edtech",
+    "serverless",
+    "nodejs"
+  ],
+  "author": "jamesjoplin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lti-tool/lti-tool.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/lti-tool/lti-tool#readme",
+  "bugs": {
+    "url": "https://github.com/lti-tool/lti-tool/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "jose": "^6.1.0",
+    "zod": "^4.1.11"
+  },
+  "peerDependencies": {
+    "pino": "^9.11.0"
+  },
+  "peerDependenciesMeta": {
+    "pino": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "pino": "^9.12.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces/index.js';
+export * from './schemas/index.js';
+export { LTITool } from './ltiTool.js';

package/src/interfaces/index.ts

@@ -0,0 +1,6 @@
+export type { LTIClient } from './ltiClient.js';
+export type { LTIConfig } from './ltiConfig.js';
+export type { LTIDeployment } from './ltiDeployment.js';
+export type { LTILaunchConfig } from './ltiLaunchConfig.js';
+export type { LTISession } from './ltiSession.js';
+export type { LTIStorage } from './ltiStorage.js';

package/src/interfaces/jwks.ts

@@ -0,0 +1,20 @@
+/**
+ * JSON Web Key Set (JWKS) structure as defined by RFC 7517.
+ * Used to expose public keys for JWT signature verification.
+ */
+export interface JWKS {
+  /** Array of JSON Web Key (JWK) objects */
+  keys: Array<{
+    /** Key usage - typically 'sig' for signature verification */
+    use: string;
+
+    /** Algorithm intended for use with this key - typically 'RS256' for LTI */
+    alg: string;
+
+    /** Key identifier used to match keys in JWT headers */
+    kid: string;
+
+    /** Additional JWK parameters (kty, n, e, etc.) as defined by RFC 7517 */
+    [key: string]: unknown;
+  }>;
+}

package/src/interfaces/ltiClient.ts

@@ -0,0 +1,24 @@
+import type { LTIDeployment } from './ltiDeployment';
+
+/**
+ * Represents an LTI (Learning Tools Interoperability) platform configuration.
+ * Contains all necessary endpoints and identifiers for LTI 1.3 integration.
+ */
+export interface LTIClient {
+  /** Unique identifier for the client */
+  id: string;
+  /** human-readable name for the platform */
+  name: string;
+  /** Platform issuer (unique identifier) */
+  iss: string;
+  /** Your app's client ID on this platform */
+  clientId: string;
+  /** Platform's auth endpoint */
+  authUrl: string;
+  /** Platform's token endpoint */
+  tokenUrl: string;
+  /** Platform's JWKS endpoint */
+  jwksUrl: string;
+  /** Array of deployment IDs associated with this platform */
+  deployments: LTIDeployment[];
+}

package/src/interfaces/ltiConfig.ts

@@ -0,0 +1,31 @@
+import type { Logger } from 'pino';
+
+import type { LTIStorage } from './ltiStorage.js';
+
+/**
+ * Configuration object for initializing an LTI Tool instance.
+ * Contains cryptographic keys, secrets, and storage adapter.
+ */
+export interface LTIConfig {
+  /** Secret key used for signing state JWTs during OIDC flow (minimum 32 bytes recommended) */
+  stateSecret: Uint8Array;
+
+  /** RSA key pair for signing JWTs and providing JWKS endpoint */
+  keyPair: CryptoKeyPair;
+
+  /** Storage adapter for persisting platforms, sessions, and nonces */
+  storage: LTIStorage;
+
+  /** Optional pino logger */
+  logger?: Logger;
+
+  /** Security configuration options */
+  security?: {
+    /** Key ID for JWKS and JWT signing (defaults to 'main') */
+    keyId?: string;
+    /** State JWT expiration time in seconds (defaults to 600 = 10 minutes) */
+    stateExpirationSeconds?: number;
+    /** Nonce expiration time in seconds (defaults to 600 = 10 minutes) */
+    nonceExpirationSeconds?: number;
+  };
+}

package/src/interfaces/ltiDeployment.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents a specific deployment of your LTI tool within a platform/LMS.
+ * Each platform can have multiple deployments (e.g., different courses, contexts).
+ */
+export interface LTIDeployment {
+  /** Internal stable UUID for this deployment configuration */
+  id: string;
+
+  /** LMS-provided deployment identifier used in LTI launch requests */
+  deploymentId: string;
+
+  /** Optional human-readable name for this deployment */
+  name?: string;
+
+  /** Optional description of what this deployment is used for */
+  description?: string;
+}

package/src/interfaces/ltiLaunchConfig.ts

@@ -0,0 +1,23 @@
+/**
+ * Configuration required for LTI 1.3 launch authentication flow.
+ * Contains platform endpoints and identifiers needed for OIDC authentication.
+ */
+export interface LTILaunchConfig {
+  /** Platform issuer URL that uniquely identifies the LMS */
+  iss: string;
+
+  /** OAuth2 client identifier assigned to your tool by the platform */
+  clientId: string;
+
+  /** Deployment identifier within the platform context */
+  deploymentId: string;
+
+  /** Platform's OIDC authentication endpoint URL */
+  authUrl: string;
+
+  /** Platform's OAuth2 token endpoint URL for service access */
+  tokenUrl: string;
+
+  /** Platform's JSON Web Key Set endpoint URL for JWT verification */
+  jwksUrl: string;
+}

package/src/interfaces/ltiSession.ts

@@ -0,0 +1,119 @@
+import type { JWTPayload } from 'jose';
+
+/**
+ * Represents an active LTI session containing user information, context data,
+ * and available services after successful launch verification.
+ */
+export interface LTISession {
+  /** Original JWT payload from the platform for reference */
+  jwtPayload: JWTPayload;
+
+  /** Unique session identifier (UUID) */
+  id: string;
+
+  /** User information extracted from LTI claims */
+  user: {
+    /** Unique user identifier from the platform */
+    id: string;
+    /** User's display name */
+    name?: string;
+    /** User's email address */
+    email?: string;
+    /** User's family/last name */
+    familyName?: string;
+    /** User's given/first name */
+    givenName?: string;
+    /** Array of LTI role URIs (e.g., 'http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor') */
+    roles: string[];
+  };
+
+  /** Course/context information */
+  context: {
+    /** Unique context identifier from the platform */
+    id: string;
+    /** Short context label (e.g., course code) */
+    label: string;
+    /** Full context title (e.g., course name) */
+    title: string;
+  };
+
+  /** Platform identification */
+  platform: {
+    /** Platform issuer URL */
+    issuer: string;
+    /** OAuth2 client identifier */
+    clientId: string;
+    /** Deployment identifier */
+    deploymentId: string;
+    /** Human-readable platform name */
+    name: string;
+  };
+
+  /** Launch target information */
+  launch: {
+    /** Target link URI where user should be directed */
+    target: string;
+  };
+
+  /** Resource link information (if applicable) */
+  resourceLink?: {
+    /** Unique resource link identifier */
+    id: string;
+    /** Resource link title */
+    title?: string;
+  };
+
+  /** Available LTI Advantage services */
+  services?: {
+    /** Assignment and Grade Services (AGS) configuration */
+    ags?: {
+      /** Single line item endpoint URL */
+      lineitem?: string;
+      /** Line items collection endpoint URL */
+      lineitems?: string;
+      /** Available AGS scopes */
+      scopes: string[];
+    };
+    /** Names and Role Provisioning Services (NRPS) configuration */
+    nrps?: {
+      /** Membership endpoint URL */
+      membershipUrl: string;
+      /** Supported NRPS versions */
+      versions: string[];
+    };
+    /** Deep Linking configuration */
+    deepLinking?: {
+      /** URL to return deep linking response */
+      returnUrl: string;
+      /** Accepted content types */
+      acceptTypes: string[];
+      /** Accepted presentation targets */
+      acceptPresentationDocumentTargets: string[];
+      /** Accepted media types */
+      acceptMediaTypes?: string;
+      /** Whether multiple items can be selected */
+      acceptMultiple: boolean;
+      /** Whether items should be auto-created */
+      autoCreate: boolean;
+      /** Platform-specific data to return */
+      data?: string;
+    };
+  };
+
+  /** Custom parameters passed from platform */
+  customParameters: Record<string, string>;
+
+  /** Convenience flags for role checking */
+  /** True if user has administrator privileges */
+  isAdmin: boolean;
+  /** True if user has instructor/teacher role */
+  isInstructor: boolean;
+  /** True if user has student/learner role */
+  isStudent: boolean;
+  /** True if Assignment and Grade Services are available */
+  isAssignmentAndGradesAvailable: boolean;
+  /** True if Deep Linking is available */
+  isDeepLinkingAvailable: boolean;
+  /** True if Names and Role Provisioning Services are available */
+  isNameAndRolesAvailable: boolean;
+}