panda_pal 5.15.1.beta3 → 5.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fb9b051afba3b9befb9e505f2c8d6bd8f595112ceea1778af4ea0190220d9a5
-  data.tar.gz: 7368671098738bbd1229c0329d9919e48d675357fcf4d13db9e3d408ed1b03f0
+  metadata.gz: c78eb783dcf56cb075ce23d1218500128e6ac1ac58c3049bcfa13f6409835554
+  data.tar.gz: bb555a130fdab3e1805013700e04bddfe24a6c3460750ac2201a06f9dfe96c1d
 SHA512:
-  metadata.gz: 24151b3bfe982fb78ff9093141482bcb0d065f1ca1a462c0ba252fb1a4e987f8001ea06bb8fc79258d93adf448db7bd67e24aaa5bd4f6b21608bac4b34250b97
-  data.tar.gz: e8d9921e233f328b1d96efda77fa8a1520052562ff942f4a759f4d6c3d386f7de0c6effd5edf2b5c1a216eab9c47b1d2ce276bdf9ca143ef9f3ddfe041680013
+  metadata.gz: 5378ea91ce63e263dc93368f4d87cec35a14273b74f37452cec2b1dea67ff8bbb3a261e609bbc550bbcc4f08dac8c1de09e387e6ec8691e3d4901ac7b2af1e0a
+  data.tar.gz: aef30aa2d98b20f502a9274ce31c5bf17e66111c8a628cd61ce2765c06ef7fe280af459069a3fafe0a13aa885e9ba915f048553f14714e3ad274537b7bd4cfe3

data/README.md

@@ -149,6 +149,42 @@ end
 the defined action. Setting it to `false` indicates that the defined action handles launch validation and setup itself (this has been the legacy approach).
 Because `auto_launch: false` is most similar to the previous behavior, it is the default for LTI 1.0/1.1 LTIs. For LTI 1.3 LTIs, `auto_launch: true` is the default. If not specified and `:organization_id` is detected in the Route Path, `auto_launch` will be set to `true`
 
+## Deep Linking (LTI 1.3)
+
+PandaPal provides comprehensive support for LTI 1.3 Deep Linking, allowing tools to be configured for content selection that can be placed directly into Canvas courses.
+
+### Quick Start
+
+1. **Configure placements** in your LTI initializer:
+```ruby
+# config/initializers/lti.rb
+PandaPal.stage_placement(:content_selection, {
+  deep_linking: true,
+  deep_link_redirect_url: :content_selection_url,
+  text: 'Select Content',
+  enabled: true
+})
+```
+
+2. **Include helpers** in your controller and build content items:
+```ruby
+class ContentSelectionController < ApplicationController
+  include PandaPal::DeepLinkingHelpers
+
+  def create
+    content_items = [
+      build_link_content_item(
+        url: launch_url_for_content(params[:content_id]),
+        title: 'Selected Content'
+      )
+    ]
+    render_deep_linking_response(content_items)
+  end
+end
+```
+
+**For complete configuration options, implementation examples, helper method documentation, and troubleshooting, see [DEEP_LINKING.md](DEEP_LINKING.md).**
+
 ## Implementating data segregation
 This engine uses Apartment to keep data segregated between installations of the implementing LTI tool.
 By default, it does this by inspecting the path of the request, and matching URLs containing `orgs` or `organizations`,
@@ -457,7 +493,7 @@ data_type: If specified, and a settings hash contains this attribute, attribute
            use `class` to determine data type.  For example:  30.minutes.class.to_s => "ActiveSupport::Duration"
 
 ## Bridge vs Canvas
-As of 3.2.0, the LTI XML config can have subtle differences based on whether your platform is bridge, or canvas. 
+As of 3.2.0, the LTI XML config can have subtle differences based on whether your platform is bridge, or canvas.
 This is determined by `PandaPal.lti_options[:platform]`.
 Set this to `platform: 'canvas.instructure.com'` (default)
 OR `platform: 'bridgeapp.com'`
@@ -490,7 +526,7 @@ You will want to watch out for a few scenarios:
 2) Use the `Authorization` header with `token={session_key}` to send your
    PandaPal session info into api calls.
 3) If you use `link_to` and navigate in your LTI (apps that are not single page)
-   make sure you include the `link_nonce` like so: 
+   make sure you include the `link_nonce` like so:
     ```ruby
       link_to "Link Name", somewhere_else_path(arg, session_token: link_nonce)
     ```

data/app/controllers/panda_pal/lti_v1_p3_controller.rb

@@ -6,7 +6,7 @@ module PandaPal
       skip_before_action :verify_authenticity_token, raise: false
     end
 
-    before_action ->{ validate_launch!(version: :v1p3) }, only: [:resource_link_request]
+    before_action ->{ validate_launch!(version: :v1p3) }, only: [:resource_link_request, :deep_link_request]
     before_action :enforce_environment!, only: [:resource_link_request]
 
     # Redirect to beta/test as necessary
@@ -40,7 +40,7 @@ module PandaPal
     end
 
     def resource_link_request
-      ltype = @decoded_lti_jwt['https://www.instructure.com/placement']
+      ltype = @decoded_lti_jwt[LtiConstants::Canvas::PLACEMENT]
 
       if ltype
         current_session.data.merge!({
@@ -54,6 +54,32 @@ module PandaPal
       end
     end
 
+    def deep_link_request
+      message_type = @decoded_lti_jwt[LtiConstants::Claims::MESSAGE_TYPE]
+
+      unless message_type == LtiConstants::MessageTypes::DEEP_LINKING_REQUEST
+        render plain: 'Not a Deep Linking request', status: :bad_request
+        return
+      end
+
+      # Store deep linking session data
+      current_session.data.merge!({
+        lti_version: 'v1p3',
+        lti_launch_placement: 'deep_linking',
+        launch_url_params: request.query_parameters.to_h,
+        launch_params: @decoded_lti_jwt,
+        deep_link_return_url: @decoded_lti_jwt[LtiConstants::DeepLinking::DEEP_LINKING_SETTINGS][LtiConstants::DeepLinkingSettings::DEEP_LINK_RETURN_URL],
+        deep_link_data: @decoded_lti_jwt[LtiConstants::DeepLinking::DATA]
+      })
+
+      redirect_url = LaunchUrlHelpers.deep_link_redirect_url(request)
+      if redirect_url
+        redirect_with_session_to(redirect_url, route_context: main_app)
+      else
+        render plain: 'Deep linking redirect URL not configured. Please configure deep_link_redirect_url in your placement or global LTI options.', status: :internal_server_error
+      end
+    end
+
     def tool_config
       if PandaPal.lti_environments.empty?
         render plain: 'Domains must be set in lti_environments'
@@ -71,7 +97,6 @@ module PandaPal
           target_link_uri: LaunchUrlHelpers.absolute_launch_url(
             k.to_sym,
             host: parsed_request_url,
-            launch_handler: v1p3_resource_link_request_path,
             default_auto_launch: true
           ),
         })

data/app/lib/panda_pal/deep_linking_helpers.rb

@@ -0,0 +1,98 @@
+module PandaPal
+  module DeepLinkingHelpers
+    # Build a link content item
+    def build_link_content_item(url:, title: nil, text: nil, icon: nil, thumbnail: nil, **options)
+      content_item = {
+        type: 'link',
+        url: url,
+        title: title
+      }
+      content_item[:text] = text if text.present?
+      content_item[:icon] = icon if icon.present?
+      content_item[:thumbnail] = thumbnail if thumbnail.present?
+      content_item.merge(options)
+    end
+
+    # Build a file content item
+    def build_file_content_item(url:, title: nil, text: nil, media_type: nil, icon: nil, **options)
+      content_item = {
+        type: 'file',
+        url: url,
+        title: title
+      }
+      content_item[:text] = text if text.present?
+      content_item[:mediaType] = media_type if media_type.present?
+      content_item[:icon] = icon if icon.present?
+      content_item.merge(options)
+    end
+
+    # Build an HTML content item
+    def build_html_content_item(html:, title: nil, text: nil, **options)
+      content_item = {
+        type: 'html',
+        html: html,
+        title: title
+      }
+      content_item[:text] = text if text.present?
+      content_item.merge(options)
+    end
+
+    # Render the deep linking response
+    # This builds the JWT and renders the auto-submit form
+    def render_deep_linking_response(content_items, custom_data: {})
+      deep_link_return_url = current_session[:deep_link_return_url]
+      deep_link_data = current_session[:deep_link_data]
+
+      unless deep_link_return_url.present?
+        render plain: 'No deep linking session found. Please ensure you accessed this through a proper deep linking flow.', status: :bad_request
+        return
+      end
+
+      # Build custom deep link data - merge Canvas data with custom data
+      launch_params = current_session[:launch_params]
+      merged_custom_data = (deep_link_data || {}).merge({
+        selection_time: Time.now.iso8601,
+        selected_by: launch_params&.dig('sub') || 'unknown'
+      }).merge(custom_data)
+
+      # Build the JWT response
+      jwt = build_deep_link_jwt(content_items, merged_custom_data)
+
+      # Set up the auto-submit form
+      @form_action = deep_link_return_url
+      @method = :post
+      @form_data = { JWT: jwt }
+
+      render partial: 'panda_pal/partials/auto_submit_form'
+    end
+
+    private
+
+    def build_deep_link_jwt(content_items, custom_deep_link_data)
+      # Get issuer (client_id) and audience from session
+      launch_params = current_session[:launch_params]
+      issuer = launch_params&.dig('aud') || current_organization.key
+      audience = launch_params&.dig('iss')
+
+      unless audience.present?
+        raise StandardError, 'Unable to determine audience for deep linking response'
+      end
+
+      deep_link_jwt_payload = {
+        iss: issuer,
+        aud: audience,
+        iat: Time.now.to_i,
+        exp: Time.now.to_i + 600,
+        nonce: SecureRandom.uuid,
+        PandaPal::LtiConstants::Claims::MESSAGE_TYPE => PandaPal::LtiConstants::MessageTypes::DEEP_LINKING_RESPONSE,
+        PandaPal::LtiConstants::Claims::VERSION => PandaPal::LtiConstants::Versions::V1_3,
+        PandaPal::LtiConstants::DeepLinking::CONTENT_ITEMS => content_items,
+        PandaPal::LtiConstants::DeepLinking::DATA => custom_deep_link_data,
+      }
+
+      require 'json/jwt'
+      jwk = JSON::JWK.new(PandaPal.lti_private_key)
+      JSON::JWT.new(deep_link_jwt_payload).sign(jwk, :RS256).to_s
+    end
+  end
+end

data/app/lib/panda_pal/launch_url_helpers.rb

@@ -2,6 +2,13 @@ module PandaPal
   module LaunchUrlHelpers
     def self.absolute_launch_url(launch_type, host: uri_host, launch_handler: nil, default_auto_launch: false)
       opts = PandaPal.lti_paths[launch_type]
+
+      if launch_handler.nil? && opts.present?
+        launch_handler = opts[:message_type] == PandaPal::LtiConstants::MessageTypes::DEEP_LINKING_REQUEST ?
+                        :v1p3_deep_link_request_path :
+                        :v1p3_resource_link_request_path
+      end
+
       auto_launch = opts[:auto_launch] != nil ? opts[:auto_launch] : default_auto_launch
       auto_launch = auto_launch && launch_handler.present?
 
@@ -100,5 +107,35 @@ module PandaPal
       engine = key_bits[0] == 'MainApp' ? Rails.application : (key_bits[0].constantize)::Engine
       engine.routes.url_helpers.send(key_bits[1], *arguments, **kwargs)
     end
+
+    def self.deep_link_redirect_url(request)
+      # Try placement-specific configuration first
+      launch_type = request.query_parameters['launch_type']&.to_sym
+      return global_configuration_url unless launch_type
+
+      placement_config = PandaPal.lti_paths[launch_type]
+      return global_configuration_url unless deep_linking_placement?(placement_config)
+
+      # Check for explicit deep_link_redirect_url configuration
+      redirect_url = placement_config[:deep_link_redirect_url]
+      return normalize_redirect_url(redirect_url) if redirect_url.present?
+
+      # Fall back to global configuration
+      global_configuration_url
+    end
+
+    def self.global_configuration_url
+      redirect_url = PandaPal.lti_options[:deep_link_redirect_url]
+      normalize_redirect_url(redirect_url) if redirect_url.present?
+    end
+
+    def self.deep_linking_placement?(placement_config)
+      placement_config&.dig(:message_type) == PandaPal::LtiConstants::MessageTypes::DEEP_LINKING_REQUEST
+    end
+
+    def self.normalize_redirect_url(url)
+      return nil unless url.present?
+      url.is_a?(Symbol) ? url : url.to_sym
+    end
   end
 end

data/app/models/panda_pal/session.rb

@@ -199,7 +199,7 @@ module PandaPal
     def custom_lti_params
       @custom_lti_params ||= begin
         # LT 1.3
-        custom_params = launch_params["https://purl.imsglobal.org/spec/lti/claim/custom"]
+        custom_params = launch_params[PandaPal::LtiConstants::Claims::CUSTOM]
         return custom_params if custom_params.present?
 
         # LTI 1.0/1.1

data/config/initializers/apartment.rb

@@ -10,29 +10,25 @@ require "apartment/adapters/postgresql_adapter"
 module Apartment
   SHARD_PREFIXES = ["SHARD_DB", "HEROKU_POSTGRESQL"]
 
-  class << self
-    def_delegators :connection_class, :connected?
+  def self.shard_configurations
+    $shard_configurations ||= begin
+      shard_to_env = {}
 
-    def shard_configurations
-      $shard_configurations ||= begin
-        shard_to_env = {}
+      base_config = ActiveRecord::Base.configurations.find_db_config(Rails.env).configuration_hash
 
-        base_config = ActiveRecord::Base.configurations.find_db_config(Rails.env).configuration_hash
+      ENV.keys.each do |k|
+        m = /^(#{SHARD_PREFIXES.join("|")})_(\w+)_URL$/.match(k)
+        next unless m
 
-        ENV.keys.each do |k|
-          m = /^(#{SHARD_PREFIXES.join("|")})_(\w+)_URL$/.match(k)
-          next unless m
-
-          url = ENV[k]
-          shardcfg = ActiveRecord::Base.configurations.resolve(url).configuration_hash
-          shardcfg = base_config.merge(shardcfg || {})
-          shard_to_env[m[2].downcase] = shardcfg
-        end
+        url = ENV[k]
+        shardcfg = ActiveRecord::Base.configurations.resolve(url).configuration_hash
+        shardcfg = base_config.merge(shardcfg || {})
+        shard_to_env[m[2].downcase] = shardcfg
+      end
 
-        shard_to_env.freeze unless Rails.env.test?
+      shard_to_env.freeze unless Rails.env.test?
 
-        shard_to_env
-      end
+      shard_to_env
     end
   end
 
@@ -124,12 +120,14 @@ module Apartment
 
         raise ActiveRecord::StatementInvalid, "PandaPal/Apartment Mutli-DB support does not currently support DB roles" if ActiveRecord::Base.current_role != ActiveRecord::Base.default_role
 
-        shard, schema = Apartment::Tenant.split_tenant(@current)
-        Apartment.establish_connection(multi_tenantify(tenant, false)) if shard != "default"
-        Apartment.connection.verify!
+        unless ActiveRecord::Base.connected?
+          Apartment.establish_connection multi_tenantify(tenant, false)
+          Apartment.connection.verify!
+        end
+
         Apartment.connection.enable_query_cache! if query_cache_enabled
 
-        raise ActiveRecord::StatementInvalid, "Could not find schema for tenant \"#{tenant}\": (#{tenant_schemas.inspect})" unless schema_exists?(tenant_schemas)
+        raise ActiveRecord::StatementInvalid, "Could not find schema for tenant #{tenant} (#{tenant_schemas.inspect})" unless schema_exists?(tenant_schemas)
 
         Apartment.connection.schema_search_path = full_search_path
       rescue *rescuable_exceptions => e
@@ -152,14 +150,6 @@ module Apartment
           schema
         end
       end
-
-      def raise_schema_connect_to_new(tenant, exception)
-        shard, schema = Tenant.split_tenant(tenant)
-        raise TenantNotFound, <<~EXCEPTION_MESSAGE
-          Could not set search path to schemas, they may be invalid: "#{schema}" #{full_search_path}.
-          Original error: #{exception.class}: #{exception}
-        EXCEPTION_MESSAGE
-      end
     end
   end
 
@@ -220,7 +210,7 @@ Apartment.configure do |config|
       shard_configurations = Apartment.shard_configurations
 
       PandaPal::Organization.all.to_a.each_with_object({}) do |org, hash|
-        shard = org.shard.to_s || "default"
+        shard = org.shard || "default"
         hash[org.tenant_name] = shard == "default" ? base_config : shard_configurations[shard.downcase]
       end
     else

data/config/routes.rb

@@ -14,6 +14,7 @@ PandaPal::Engine.routes.draw do
     post '/oidc_login' => 'lti_v1_p3#login'
     get '/oidc_login' => 'lti_v1_p3#login'
     post '/resource_link_request' => 'lti_v1_p3#resource_link_request'
+    post '/deep_link_request' => 'lti_v1_p3#deep_link_request'
     get '/public_jwks' => 'lti_v1_p3#public_jwks'
   end
 end

data/db/migrate/20250401214421_rename_session_session_key.rb

@@ -1,4 +1,4 @@
-class RenameSessionSessionKey < PandaPal::MiscHelper::MigrationClass
+class RenameSessionSessionKey < ActiveRecord::Migration[7.1]
   def change
     rename_column :panda_pal_sessions, :session_key, :session_secret
   end

data/lib/panda_pal/lti_constants.rb

@@ -0,0 +1,48 @@
+module PandaPal
+  module LtiConstants
+    # LTI 1.3 Standard Claims
+    module Claims
+      MESSAGE_TYPE = 'https://purl.imsglobal.org/spec/lti/claim/message_type'.freeze
+      VERSION = 'https://purl.imsglobal.org/spec/lti/claim/version'.freeze
+      DEPLOYMENT_ID = 'https://purl.imsglobal.org/spec/lti/claim/deployment_id'.freeze
+      TARGET_LINK_URI = 'https://purl.imsglobal.org/spec/lti/claim/target_link_uri'.freeze
+      CONTEXT = 'https://purl.imsglobal.org/spec/lti/claim/context'.freeze
+      RESOURCE_LINK = 'https://purl.imsglobal.org/spec/lti/claim/resource_link'.freeze
+      ROLES = 'https://purl.imsglobal.org/spec/lti/claim/roles'.freeze
+      CUSTOM = 'https://purl.imsglobal.org/spec/lti/claim/custom'.freeze
+    end
+
+    # LTI Deep Linking Claims
+    module DeepLinking
+      CONTENT_ITEMS = 'https://purl.imsglobal.org/spec/lti-dl/claim/content_items'.freeze
+      DATA = 'https://purl.imsglobal.org/spec/lti-dl/claim/data'.freeze
+      DEEP_LINKING_SETTINGS = 'https://purl.imsglobal.org/spec/lti-dl/claim/deep_linking_settings'.freeze
+    end
+
+    # Canvas-specific Claims
+    module Canvas
+      PLACEMENT = 'https://www.instructure.com/placement'.freeze
+    end
+
+    # LTI Message Types
+    module MessageTypes
+      DEEP_LINKING_REQUEST = 'LtiDeepLinkingRequest'.freeze
+      DEEP_LINKING_RESPONSE = 'LtiDeepLinkingResponse'.freeze
+      RESOURCE_LINK_REQUEST = 'LtiResourceLinkRequest'.freeze
+    end
+
+    # LTI Versions
+    module Versions
+      V1_3 = '1.3.0'.freeze
+    end
+
+    # Deep Linking Settings Keys
+    module DeepLinkingSettings
+      DEEP_LINK_RETURN_URL = 'deep_link_return_url'.freeze
+      ACCEPT_TYPES = 'accept_types'.freeze
+      ACCEPT_PRESENTATION_DOCUMENT_TARGETS = 'accept_presentation_document_targets'.freeze
+      ACCEPT_MEDIA_TYPES = 'accept_media_types'.freeze
+      AUTO_CREATE = 'auto_create'.freeze
+    end
+  end
+end

data/lib/panda_pal/version.rb

@@ -1,3 +1,3 @@
 module PandaPal
-  VERSION = "5.15.1.beta3"
+  VERSION = "5.16.0"
 end

data/lib/panda_pal.rb

@@ -1,6 +1,7 @@
 require "panda_pal/engine"
 require 'panda_pal/plugins'
 require 'panda_pal/helpers'
+require 'panda_pal/lti_constants'
 require 'oauth/request_proxy/rack_request'
 require 'oauth/request_proxy/action_dispatch_request'
 
@@ -50,9 +51,22 @@ module PandaPal
     @@lti_custom_params.deep_dup
   end
 
-  def self.stage_navigation(navigation, options)
-    @@lti_navigation[navigation] ||= {}
-    @@lti_navigation[navigation].merge!(options)
+  def self.stage_navigation(navigation, options = {})
+    warn "[DEPRECATION] `stage_navigation` is deprecated. Please use `stage_placement` instead."
+    stage_placement(navigation, options)
+  end
+
+  def self.stage_placement(placement, options = {})
+    @@lti_navigation[placement] ||= {}
+
+    if options.delete(:deep_linking)
+      options = options.merge({
+        message_type: LtiConstants::MessageTypes::DEEP_LINKING_REQUEST,
+        route_helper_key: :deep_link_request
+      })
+    end
+
+    @@lti_navigation[placement].merge!(options)
   end
 
   def self.lti_paths
@@ -70,7 +84,7 @@ module PandaPal
   end
 
   def self.lti_private_key=(v)
-    @@lti_private_key = k
+    @@lti_private_key = v
   end
 
   def self.register_extension(type, modul)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: panda_pal
 version: !ruby/object:Gem::Version
-  version: 5.15.1.beta3
+  version: 5.16.0
 platform: ruby
 authors:
 - Instructure CustomDev
@@ -159,6 +159,7 @@ files:
 - app/lib/lti_xml/base_platform.rb
 - app/lib/lti_xml/bridge_platform.rb
 - app/lib/lti_xml/canvas_platform.rb
+- app/lib/panda_pal/deep_linking_helpers.rb
 - app/lib/panda_pal/launch_url_helpers.rb
 - app/lib/panda_pal/lti_jwt_validator.rb
 - app/models/panda_pal/api_call.rb
@@ -197,6 +198,7 @@ files:
 - lib/panda_pal/helpers/route_helper.rb
 - lib/panda_pal/helpers/secure_headers.rb
 - lib/panda_pal/helpers/session_replacement.rb
+- lib/panda_pal/lti_constants.rb
 - lib/panda_pal/plugins.rb
 - lib/panda_pal/spec_helper.rb
 - lib/panda_pal/version.rb