Add minimum viable platform-side LTI 1.3 resource link launch

[ottenhoff]

Summary

lti-tool is already useful for applications that need to act as an LTI 1.3 tool. CoursePorter has a second use case that needs the opposite side of the protocol: acting as an LTI platform/consumer for LTI links discovered inside imported IMS Common Cartridge / Canvas IMSCC packages.

CoursePorter imports and hosts course packages. IMSCC packages can include external tool / LTI resource links. Today those items are recognized but marked unsupported because launching them outside the original LMS requires platform-side LTI behavior.

This issue is a request to explore platform-side primitives in lti-tool so apps like CoursePorter can safely launch imported LTI resources instead of treating every cartridge LTI item as a manual replacement.

CoursePorter use case

A hosted course delivery platform imports an IMSCC package. During import it finds an item/resource that represents an LTI external tool, for example Canvas external_tool, Basic LTI, or an LTI 1.3 resource link. Later a learner launches the imported course from CoursePorter. CoursePorter needs to launch the third-party LTI tool from its own domain and state model.

In that flow CoursePorter is not the tool being launched by Canvas/Moodle/Sakai. CoursePorter is the platform initiating a launch into another tool.

Helpful platform-side capabilities

A useful platform-side package would provide typed primitives for:

• Registering and storing external LTI tool definitions that CoursePorter is allowed to launch.
• Representing platform-owned deployment/client/tool configuration for an external tool.
• Building LTI 1.3 login/initiation and launch payloads from platform context.
• Signing platform-originated ID tokens using WebCrypto-compatible keys.
• Publishing platform JWKS for external tools to verify CoursePorter launches.
• Mapping CoursePorter learner, course, assignment, attempt, and resource-link context into LTI claims.
• Encoding resource link IDs, custom params, roles, context claims, and target link URIs.
• Validating required tool configuration before launch and returning typed errors when configuration is missing.
• Supporting nonce/state/correlation records for platform-originated launch attempts.
• Keeping launch construction cookie-safe and iframe-safe for embedded course delivery.

LTI Advantage platform needs

For a complete CoursePorter integration, platform-side support would eventually need decisions or primitives for:

• AGS: receiving score/line-item calls from launched tools and mapping them to CoursePorter attempts/gradebook rows.
• NRPS: serving roster/membership responses for the CoursePorter assignment/course context.
• Deep Linking: optionally allowing an external tool to return selected content into an import or authoring workflow.
• Dynamic Registration: supporting external tools registering with CoursePorter as a platform, if that is in scope.

These do not all have to ship together, but the package boundary should make it clear which side of each service is implemented: tool-side client calls vs platform-side service endpoints.

IMS Common Cartridge specific needs

Imported cartridge LTI items often need normalization before launch. Helpful APIs would include:

• A normalized LTI resource-link DTO that can be produced from IMSCC/Canvas cartridge data.
• Detection helpers that distinguish Basic LTI links, LTI 1.3 links, and vendor-specific external tool descriptors where possible.
• A way to associate imported cartridge resource IDs with platform resource link IDs.
• Diagnostics for links that cannot be launched because the original LMS-held configuration is missing.

Desired design shape

This should probably be separate from the current tool-side API, for example:

• @lti-tool/platform for platform/consumer launch construction and service endpoints.
• Shared core schemas/constants where appropriate.
• Storage interfaces separate from the current LTIStorage if the data model differs.
• D1-compatible storage, but without requiring in-memory fallbacks for production.

The main thing CoursePorter needs is a loud, typed boundary: either we have enough platform/tool configuration to launch the imported LTI item correctly, or we produce an operator-facing diagnostic explaining what is missing.

Non-goals

• Do not fake successful LTI launches when issuer/client/deployment/key metadata is missing.
• Do not assume imported Canvas/Moodle/Sakai external tool links are launchable without explicit CoursePorter-side tool configuration.
• Do not blur tool-side APIs with platform-side APIs; callers need to know which protocol role they are implementing.

Why this matters

Without platform-side support, CoursePorter can use lti-tool to be launched by an LMS, but it still cannot safely launch third-party LTI tools found inside imported Common Cartridge packages. Platform-side primitives would make lti-tool useful for both directions of LTI integration.

[ottenhoff]

Scope update: this should start as a minimum viable platform-side LTI 1.3 resource link launch primitive, not a full platform implementation and not a Common Cartridge parser.

Near-term MVP:

• Accept explicit external tool configuration supplied by the application: login/initiation URL if needed, target link URI, client ID, deployment ID, and any tool-specific custom params.
• Accept explicit platform configuration: issuer, JWKS URL, signing key/key id, and platform identity metadata.
• Accept launch context supplied by the application: subject/user identity, roles, context/course, resource link, locale/presentation fields, and custom claims.
• Build and sign a valid LTI 1.3 LtiResourceLinkRequest ID token.
• Generate/persist launch state and nonce through a small platform-launch storage contract.
• Return a form-post payload or typed validation error.
• Provide a JWKS/public-key helper for the platform signing key if that can stay small.

Explicitly out of scope for this first pass:

• Common Cartridge / IMSCC / Canvas import vocabulary. CoursePorter or another importer should translate imported data into the generic LTI launch inputs.
• Basic LTI 1.1 support.
• AGS endpoints.
• NRPS endpoints.
• Deep Linking.
• Dynamic Registration.
• Tool discovery or guessing missing configuration.
• A general-purpose LMS/platform product.

Design direction: keep this in a clearly separated platform-side namespace/subpath so tool-side verification APIs and platform-side launch construction do not blur together. Reuse existing constants, schemas, signing/key helpers, Zod parsing patterns, and structured result/error style where they fit, but do not contort tool-side launch verification code into reverse-platform behavior.