panda_pal 5.18.2 → 5.19.0.beta1

data/lib/panda_pal/helpers/controller_helper.rb

@@ -63,9 +63,17 @@ module PandaPal::Helpers
         return false
       end
 
+      # LTI 1.0 tools share the Organization's consumer key, so the tool comes
+      # from its (OAuth-signed) custom field instead of the key.
+      lti_tool = params[:"custom_#{PandaPal::TOOL_CUSTOM_FIELD}"]
+      unless PandaPal.lti_tool?(lti_tool)
+        render plain: 'Unrecognized LTI tool', status: :unauthorized
+        return false
+      end
+
       @organization.switch_tenant
 
-      start_panda_session!
+      start_panda_session!(tool: PandaPal.normalize_lti_tool!(lti_tool).to_s)
     end
 
     def validate_v1p3_launch
@@ -78,6 +86,15 @@ module PandaPal::Helpers
 
       client_id = decoded_jwt['aud']
       deployment_id = decoded_jwt['https://purl.imsglobal.org/spec/lti/claim/deployment_id']
+      lti_tool = PandaPal::DEFAULT_TOOL
+
+      # Each tool is its own Developer Key, so the client_id (signed, as `aud`)
+      # identifies both the Organization and the tool.
+      registration = PandaPal::LtiRegistration.for_launch(decoded_jwt['azp'].presence || Array(client_id).first, deployment_id)
+      if registration
+        @organization = registration.panda_pal_organization
+        lti_tool = registration.lti_tool
+      end
 
       if deployment_id.present?
         @organization ||= PandaPal::Organization.find_by(key: "#{client_id}/#{deployment_id}")
@@ -89,6 +106,7 @@ module PandaPal::Helpers
       params[:session_key] = params[:state]
 
       raise JSON::JWT::VerificationFailed, 'Unrecognized Organization' unless @organization.present?
+      raise JSON::JWT::VerificationFailed, 'Unrecognized LTI tool' unless PandaPal.lti_tool?(lti_tool)
       raise JSON::JWT::VerificationFailed, 'Organization does not trust platform' unless @organization.trusted_platform?(current_lti_platform)
 
       begin
@@ -111,6 +129,7 @@ module PandaPal::Helpers
 
       @current_session = login_session.dup
       @current_session.panda_pal_organization = @organization
+      @current_session.tool = lti_tool.to_s
       @current_session.save!
 
       @decoded_lti_jwt = decoded_jwt

data/lib/panda_pal/helpers/route_helper.rb

@@ -6,10 +6,17 @@ module PandaPal::Helpers::RouteHelper
     nav, to = options.first
     options[:to] = to
     options.delete nav
-    path = "#{base_path}/#{nav.to_s}"
 
     lti_options = options.delete(:lti_options) || {}
 
+    # Non-default tools get their own path segment, so the same placement can be
+    # declared once per tool without the routes colliding.
+    tool = options.delete(:tool) || lti_options[:tool]
+    tool = tool.presence&.to_sym || PandaPal::DEFAULT_TOOL
+    lti_options[:tool] = tool
+
+    path = tool == PandaPal::DEFAULT_TOOL ? "#{base_path}/#{nav.to_s}" : "#{base_path}/#{tool}/#{nav.to_s}"
+
     lti_options[:auto_launch] = options.delete(:auto_launch)
     # NB if lti_nav is outside an :organization_id scope, auto_launch defaults differently between 1.1 and 1.3 - 1.1 defaults off, 1.3 defaults on
     lti_options[:auto_launch] = true if lti_options[:auto_launch].nil? && (@scope[:path] || '').include?(':organization_id')

data/lib/panda_pal/helpers/session_replacement.rb

@@ -31,9 +31,9 @@ module PandaPal::Helpers
       current_session.try(:save)
     end
 
-    def start_panda_session!
+    def start_panda_session!(**attributes)
       raise "Session already started" if @current_session.present?
-      @current_session = PandaPal::Session.new(panda_pal_organization_id: current_organization&.id).tap do |session|
+      @current_session = PandaPal::Session.new(panda_pal_organization_id: current_organization&.id, **attributes).tap do |session|
         session.save!
       end
     end

data/lib/panda_pal/version.rb

@@ -1,3 +1,3 @@
 module PandaPal
-  VERSION = '5.18.2'
+  VERSION = '5.19.0.beta1'
 end

data/lib/panda_pal.rb

@@ -22,7 +22,20 @@ module PandaPal
     end
   end
 
-  @@lti_navigation = {}
+  # A single host app can publish more than one LTI tool (each its own Canvas
+  # Developer Key / tool config, with its own placements). Everything that
+  # isn't given an explicit tool belongs to DEFAULT_TOOL, so single-tool apps
+  # never need to know tools exist.
+  DEFAULT_TOOL = :default
+
+  # Custom field added to every non-default tool's config, so a launch (and an
+  # installed tool in Canvas) can be traced back to the tool it came from.
+  TOOL_CUSTOM_FIELD = 'panda_pal_tool'.freeze
+
+  class UnknownLtiTool < StandardError; end
+
+  @@lti_navigation = { DEFAULT_TOOL => {} }
+  @@lti_tools = {}
   @@lti_options = {}
   @@lti_properties = {}
   @@lti_environments = {}
@@ -59,8 +72,58 @@ module PandaPal
     @@lti_custom_params = custom_params.with_indifferent_access
   end
 
-  def self.lti_custom_params
-    @@lti_custom_params.deep_dup
+  def self.lti_custom_params(tool = DEFAULT_TOOL)
+    tool = normalize_lti_tool!(tool)
+    params = @@lti_custom_params.deep_dup
+    return params if tool == DEFAULT_TOOL
+
+    params.merge!(@@lti_tools[tool][:custom_params] || {})
+    params[TOOL_CUSTOM_FIELD] = tool.to_s
+    params
+  end
+
+  # Registers an additional LTI tool. `options` are merged over lti_options
+  # when building that tool's config (title, description, deep_link_redirect_url,
+  # ...), and `custom_params:` are merged over lti_custom_params.
+  #
+  #   PandaPal.define_tool(:translate, title: 'My LTI - Translate', custom_params: { ... })
+  #   PandaPal.stage_placement(:editor_button, tool: :translate, ...)
+  def self.define_tool(name, options = {})
+    name = name.to_sym
+    raise ArgumentError, "#{DEFAULT_TOOL} is configured through lti_options, not define_tool" if name == DEFAULT_TOOL
+
+    options = options.with_indifferent_access
+    tool = (@@lti_tools[name] ||= {})
+    tool[:custom_params] = (tool[:custom_params] || {}).merge(options.delete(:custom_params) || {}).with_indifferent_access
+    tool[:options] = (tool[:options] || {}).merge(options)
+    @@lti_navigation[name] ||= {}
+    name
+  end
+
+  def self.lti_tools
+    [DEFAULT_TOOL, *@@lti_tools.keys]
+  end
+
+  def self.lti_tool?(name)
+    return true if name.blank?
+    lti_tools.include?(name.to_sym)
+  end
+
+  # Blank means the default tool. Anything else must have been defined.
+  def self.normalize_lti_tool!(name)
+    return DEFAULT_TOOL if name.blank?
+    name = name.to_sym
+    raise UnknownLtiTool, "Unknown LTI tool '#{name}'" unless lti_tool?(name)
+    name
+  end
+
+  # lti_options as seen by one tool - its own options merged over the shared ones.
+  def self.lti_tool_options(tool = DEFAULT_TOOL)
+    tool = normalize_lti_tool!(tool)
+    opts = lti_options
+    return opts if tool == DEFAULT_TOOL
+
+    opts.with_indifferent_access.merge(@@lti_tools[tool][:options].deep_dup)
   end
 
   def self.lti_scopes=(scopes)
@@ -77,7 +140,12 @@ module PandaPal
   end
 
   def self.stage_placement(placement, options = {})
-    @@lti_navigation[placement] ||= {}
+    options = options.dup
+    tool = options.delete(:tool).presence&.to_sym || DEFAULT_TOOL
+    define_tool(tool) unless tool == DEFAULT_TOOL || @@lti_tools.key?(tool)
+
+    placements = (@@lti_navigation[tool] ||= {})
+    placements[placement] ||= {}
 
     if options.delete(:deep_linking)
       options = options.merge({
@@ -86,11 +154,12 @@ module PandaPal
       })
     end
 
-    @@lti_navigation[placement].merge!(options)
+    placements[placement].merge!(options)
   end
 
-  def self.lti_paths
-    @@lti_navigation.deep_dup
+  def self.lti_paths(tool = DEFAULT_TOOL)
+    tool = normalize_lti_tool!(tool)
+    (@@lti_navigation[tool] || {}).deep_dup
   end
 
   def self.lti_private_key
@@ -157,9 +226,12 @@ module PandaPal
   end
 
   def self.validate_lti_navigation(errors = [])
-    @@lti_navigation.each do |k, v|
-      next if v[:route_helper_key]
-      errors << "lti navigation '#{k}' does not have a Route!" unless (LaunchUrlHelpers.launch_url(k) rescue nil)
+    @@lti_navigation.each do |tool, placements|
+      placements.each do |k, v|
+        next if v[:route_helper_key]
+        label = tool == DEFAULT_TOOL ? "'#{k}'" : "'#{k}' (tool '#{tool}')"
+        errors << "lti navigation #{label} does not have a Route!" unless (LaunchUrlHelpers.launch_url(k, tool: tool) rescue nil)
+      end
     end
     errors
   end

data/panda_pal.gemspec

@@ -27,5 +27,6 @@ Gem::Specification.new do |s|
   s.add_dependency 'attr_encrypted', '~> 4.2'
   s.add_dependency 'secure_headers', '>= 6.1', '< 8'
   s.add_dependency 'jwt'
+  s.add_dependency 'json-jwt', '>= 1.15' # LTI 1.3 id_token decoding/verification (validate_v1p3_launch)
   s.add_dependency 'httparty'
 end

data/spec/controllers/panda_pal/lti_v1_p0_controller_spec.rb

@@ -7,7 +7,7 @@ RSpec.describe "PandaPal::LtiV1P0Controller", type: :request do
   # Signs a full LTI v1p0 launch params hash the same way an LMS (Tool Consumer)
   # would, using the platform-side half of the very same `ims-lti` gem that
   # PandaPal uses on the tool-provider side to validate incoming launches.
-  def signed_launch_params(secret:, timestamp: Time.now.to_i, launch_type: 'panda_pal')
+  def signed_launch_params(secret:, timestamp: Time.now.to_i, launch_type: 'panda_pal', custom: {})
     consumer = IMS::LTI::ToolConsumer.new(organization.key, secret, {
       'resource_link_id' => 'test-resource-link-id',
     })
@@ -17,9 +17,14 @@ RSpec.describe "PandaPal::LtiV1P0Controller", type: :request do
     # params, so it must be included in the signed payload or the signature
     # PandaPal recomputes on the real request body won't match.
     consumer.set_non_spec_param('launch_type', launch_type)
+    custom.each { |k, v| consumer.set_custom_param(k.to_s, v) }
     consumer.generate_launch_data
   end
 
+  def launched_session
+    organization.switch_tenant { PandaPal::Session.order(:id).last }
+  end
+
   after do
     # `validate_v1p0_launch` permanently switches the Apartment tenant to the
     # organization's schema on a successful launch (PandaPal::Organization
@@ -47,6 +52,40 @@ RSpec.describe "PandaPal::LtiV1P0Controller", type: :request do
       end
     end
 
+    context 'tools', :isolated_lti_config do
+      before do
+        # Only the translate tool routes editor_button anywhere real (the mount
+        # point) - the default tool would fall back to a missing editor_button_url.
+        PandaPal.stage_placement(:editor_button, tool: :translate, url: :panda_pal)
+      end
+
+      it 'records the default tool for a launch with no tool custom field' do
+        post panda_pal.v1p0_launch_path(host: 'www.example.com'), params: signed_launch_params(secret: organization.secret)
+
+        expect(response).to have_http_status(:found)
+        expect(launched_session.lti_tool).to eq(PandaPal::DEFAULT_TOOL)
+      end
+
+      it "routes by the signed tool custom field and records the tool on the session" do
+        params = signed_launch_params(secret: organization.secret, launch_type: 'editor_button', custom: { PandaPal::TOOL_CUSTOM_FIELD => 'translate' })
+
+        post panda_pal.v1p0_launch_path(host: 'www.example.com'), params: params
+
+        expect(response).to have_http_status(:found)
+        expect(response.headers['Location']).to include('/panda_pal')
+        expect(launched_session.lti_tool).to eq(:translate)
+      end
+
+      it 'rejects a launch naming a tool that was never defined' do
+        params = signed_launch_params(secret: organization.secret, custom: { PandaPal::TOOL_CUSTOM_FIELD => 'nope' })
+
+        post panda_pal.v1p0_launch_path(host: 'www.example.com'), params: params
+
+        expect(response).to have_http_status(:unauthorized)
+        expect(response.body).to eq('Unrecognized LTI tool')
+      end
+    end
+
     context 'with an invalid signature (wrong secret used to sign)' do
       it 'renders 401 with the failure body' do
         params = signed_launch_params(secret: 'not-the-real-secret')
@@ -107,4 +146,49 @@ RSpec.describe "PandaPal::LtiV1P0Controller", type: :request do
       post panda_pal.v1p0_launch_path(host: 'www.example.com'), params: {}, headers: { 'User-Agent' => chrome_user_agent }
     end
   end
+
+  describe 'GET /v1p0/config', :isolated_lti_config do
+    before do
+      PandaPal.lti_environments = { domain: 'tool.example.com' }
+      PandaPal.lti_options = { title: 'Shared Title' }
+      PandaPal.stage_placement(:course_navigation, url: :panda_pal, text: 'Settings')
+      PandaPal.define_tool(:translate, title: 'Translate Title')
+      PandaPal.stage_placement(:editor_button, tool: :translate, url: :panda_pal, text: 'Translate')
+    end
+
+    def ext_param(doc, name)
+      doc.at_xpath("//lticm:property[@name='#{name}'] | //lticm:options[@name='#{name}']", 'lticm' => 'http://www.imsglobal.org/xsd/imslticm_v1p0')
+    end
+
+    it "serves only the default tool's placements without a tool param" do
+      get '/panda_pal/v1p0/config'
+
+      doc = Nokogiri::XML(response.body)
+      expect(response).to have_http_status(:ok)
+      expect(doc.at_xpath('//blti:title', 'blti' => 'http://www.imsglobal.org/xsd/imsbasiclti_v1p0').text).to eq('Shared Title')
+      expect(ext_param(doc, 'course_navigation')).to be_present
+      expect(ext_param(doc, 'editor_button')).to be_nil
+      expect(response.body).not_to include(PandaPal::TOOL_CUSTOM_FIELD)
+    end
+
+    it "serves the requested tool's title, placements, and tool custom field" do
+      get '/panda_pal/v1p0/config', params: { tool: 'translate' }
+
+      doc = Nokogiri::XML(response.body)
+      expect(response).to have_http_status(:ok)
+      expect(doc.at_xpath('//blti:title', 'blti' => 'http://www.imsglobal.org/xsd/imsbasiclti_v1p0').text).to eq('Translate Title')
+      expect(ext_param(doc, 'editor_button')).to be_present
+      expect(ext_param(doc, 'course_navigation')).to be_nil
+
+      custom = doc.at_xpath("//blti:custom/lticm:property[@name='#{PandaPal::TOOL_CUSTOM_FIELD}']",
+        'blti' => 'http://www.imsglobal.org/xsd/imsbasiclti_v1p0', 'lticm' => 'http://www.imsglobal.org/xsd/imslticm_v1p0')
+      expect(custom&.text).to eq('translate')
+    end
+
+    it 'renders 404 for an unknown tool' do
+      get '/panda_pal/v1p0/config', params: { tool: 'nope' }
+
+      expect(response).to have_http_status(:not_found)
+    end
+  end
 end

data/spec/controllers/panda_pal/lti_v1_p3_tools_spec.rb

@@ -0,0 +1,144 @@
+require 'spec_helper'
+require 'json/jwt'
+
+RSpec.describe "PandaPal::LtiV1P3Controller tools", type: :request, isolated_lti_config: true do
+  let(:organization) { create(:panda_pal_organization, key: '10000000000001') }
+  let(:issuer) { 'https://canvas.instructure.com' }
+  let(:platform_key) { OpenSSL::PKey::RSA.new(2048) }
+  let(:platform_jwk) { JSON::JWK.new(platform_key.public_key) }
+
+  before do
+    PandaPal.lti_environments = { domain: 'tool.example.com' }
+    PandaPal.lti_options = { title: 'Shared Title' }
+    PandaPal.stage_placement(:course_navigation, text: 'Settings')
+    PandaPal.define_tool(:translate, title: 'Translate Title')
+    # Only the translate tool routes editor_button anywhere real (the mount
+    # point) - the default tool would fall back to a missing editor_button_url.
+    PandaPal.stage_placement(:editor_button, tool: :translate, url: :panda_pal, text: 'Translate')
+  end
+
+  after { Apartment::Tenant.reset }
+
+  describe 'GET /v1p3/config' do
+    it "serves only the default tool's placements without a tool param" do
+      get '/panda_pal/v1p3/config'
+
+      body = JSON.parse(response.body)
+      placements = body.dig('extensions', 0, 'settings', 'placements').map { |p| p['placement'] }
+
+      expect(body['title']).to eq('Shared Title')
+      expect(placements).to eq(['course_navigation'])
+      expect(body['custom_fields']).not_to have_key(PandaPal::TOOL_CUSTOM_FIELD)
+    end
+
+    it "serves the requested tool's title, placements, and tool custom field" do
+      get '/panda_pal/v1p3/config', params: { tool: 'translate' }
+
+      body = JSON.parse(response.body)
+      placements = body.dig('extensions', 0, 'settings', 'placements')
+
+      expect(body['title']).to eq('Translate Title')
+      expect(placements.map { |p| p['placement'] }).to eq(['editor_button'])
+      expect(placements[0]['target_link_uri']).to include('/panda_pal/v1p3/resource_link_request?launch_type=editor_button')
+      expect(body['custom_fields'][PandaPal::TOOL_CUSTOM_FIELD]).to eq('translate')
+    end
+
+    it 'renders 404 for an unknown tool' do
+      get '/panda_pal/v1p3/config', params: { tool: 'nope' }
+
+      expect(response).to have_http_status(:not_found)
+    end
+  end
+
+  describe 'POST /v1p3/resource_link_request' do
+    let(:nonce) { SecureRandom.uuid }
+
+    let!(:login_session) do
+      # What LtiV1P3Controller#login leaves behind in the public schema.
+      PandaPal::Session.create!(panda_pal_organization_id: 0, data: {
+        lti_platform: PandaPal::Platform::Canvas.new(iss: issuer).serialize,
+        lti_oauth_nonce: nonce,
+      })
+    end
+
+    before do
+      allow_any_instance_of(PandaPal::Platform::Canvas).to receive(:public_jwks).and_return(JSON::JWK::Set.new(platform_jwk))
+      # Launch validation records nonces in Rails.cache - keep them in memory
+      # rather than in the dummy app's file store.
+      allow(Rails).to receive(:cache).and_return(ActiveSupport::Cache::MemoryStore.new)
+    end
+
+    def id_token(client_id:, deployment_id: 'dep-1', placement: 'editor_button')
+      claims = {
+        iss: issuer,
+        aud: client_id,
+        sub: 'user-1',
+        nonce: nonce,
+        iat: Time.now.to_i,
+        exp: Time.now.to_i + 300,
+        PandaPal::LtiConstants::Claims::DEPLOYMENT_ID => deployment_id,
+        PandaPal::LtiConstants::Claims::MESSAGE_TYPE => 'LtiResourceLinkRequest',
+        PandaPal::LtiConstants::Canvas::PLACEMENT => placement,
+      }
+      jwt = JSON::JWT.new(claims)
+      jwt.kid = platform_jwk[:kid]
+      jwt.sign(platform_key, :RS256).to_s
+    end
+
+    def launch!(**token_opts)
+      post '/panda_pal/v1p3/resource_link_request', params: { id_token: id_token(**token_opts), state: login_session.session_key }
+    end
+
+    def launched_session
+      organization.switch_tenant { PandaPal::Session.order(:id).last }
+    end
+
+    it "resolves a registered tool's client_id to its organization and routes by that tool" do
+      organization.lti_registrations.create!(tool: 'translate', client_id: '10000000000002')
+
+      launch!(client_id: '10000000000002')
+
+      expect(response).to have_http_status(:found)
+      expect(response.headers['Location']).to include('/panda_pal')
+      expect(launched_session.lti_tool).to eq(:translate)
+      expect(launched_session.panda_pal_organization).to eq(organization)
+    end
+
+    it 'prefers a deployment-specific registration' do
+      other_org = create(:panda_pal_organization)
+      other_org.lti_registrations.create!(tool: 'translate', client_id: '10000000000002')
+      organization.lti_registrations.create!(tool: 'translate', client_id: '10000000000002', deployment_id: 'dep-1')
+
+      launch!(client_id: '10000000000002', deployment_id: 'dep-1')
+
+      expect(response).to have_http_status(:found)
+      expect(launched_session.panda_pal_organization).to eq(organization)
+    end
+
+    it "still resolves the organization's own key as the default tool" do
+      PandaPal.stage_placement(:course_navigation, url: :panda_pal)
+
+      launch!(client_id: organization.key, placement: 'course_navigation')
+
+      expect(response).to have_http_status(:found)
+      expect(launched_session.lti_tool).to eq(PandaPal::DEFAULT_TOOL)
+    end
+
+    it 'rejects a registration whose tool is no longer defined' do
+      registration = organization.lti_registrations.create!(tool: 'translate', client_id: '10000000000002')
+      registration.update_column(:tool, 'removed')
+
+      launch!(client_id: '10000000000002')
+
+      expect(response).to have_http_status(:unauthorized)
+      expect(response.body).to include('Unrecognized LTI tool')
+    end
+
+    it 'rejects an unregistered client_id' do
+      launch!(client_id: '99999')
+
+      expect(response).to have_http_status(:unauthorized)
+      expect(response.body).to include('Unrecognized Organization')
+    end
+  end
+end

data/spec/lib/panda_pal/lti_tools_spec.rb

@@ -0,0 +1,153 @@
+require 'spec_helper'
+
+RSpec.describe 'PandaPal LTI tools', :isolated_lti_config do
+  before do
+    PandaPal.lti_options = { title: 'Shared Title', description: 'Shared description' }
+    PandaPal.lti_custom_params = { custom_canvas_user_id: '$Canvas.user.id' }
+  end
+
+  describe '.stage_placement' do
+    it 'stages placements on the default tool when no tool is given' do
+      PandaPal.stage_placement(:course_navigation, text: 'Default')
+
+      expect(PandaPal.lti_paths.keys).to eq([:course_navigation])
+      expect(PandaPal.lti_paths(PandaPal::DEFAULT_TOOL)[:course_navigation]).to eq(text: 'Default')
+    end
+
+    it 'keeps the same placement separate per tool' do
+      PandaPal.stage_placement(:editor_button, text: 'Default')
+      PandaPal.stage_placement(:editor_button, tool: :translate, text: 'Translate')
+
+      expect(PandaPal.lti_paths[:editor_button]).to eq(text: 'Default')
+      expect(PandaPal.lti_paths(:translate)[:editor_button]).to eq(text: 'Translate')
+    end
+
+    it 'implicitly defines a tool it has not seen yet' do
+      PandaPal.stage_placement(:editor_button, tool: :translate)
+
+      expect(PandaPal.lti_tools).to eq([PandaPal::DEFAULT_TOOL, :translate])
+    end
+
+    it 'does not mutate the options hash it is given' do
+      options = { tool: :translate, deep_linking: true }
+      PandaPal.stage_placement(:editor_button, options)
+
+      expect(options).to eq(tool: :translate, deep_linking: true)
+      expect(PandaPal.lti_paths(:translate)[:editor_button][:route_helper_key]).to eq(:deep_link_request)
+    end
+  end
+
+  describe '.define_tool' do
+    it 'refuses to redefine the default tool' do
+      expect { PandaPal.define_tool(PandaPal::DEFAULT_TOOL, title: 'x') }.to raise_error(ArgumentError)
+    end
+
+    it 'merges its options over lti_options' do
+      PandaPal.define_tool(:translate, title: 'Translate')
+
+      options = PandaPal.lti_tool_options(:translate)
+      expect(options[:title]).to eq('Translate')
+      expect(options[:description]).to eq('Shared description')
+      expect(PandaPal.lti_tool_options[:title]).to eq('Shared Title')
+    end
+
+    it 'merges its custom params over lti_custom_params and tags them with the tool' do
+      PandaPal.define_tool(:translate, custom_params: { mode: 'translate' })
+
+      expect(PandaPal.lti_custom_params(:translate)).to eq(
+        'custom_canvas_user_id' => '$Canvas.user.id',
+        'mode' => 'translate',
+        PandaPal::TOOL_CUSTOM_FIELD => 'translate',
+      )
+    end
+
+    it 'leaves the default tool custom params untouched' do
+      PandaPal.define_tool(:translate, custom_params: { mode: 'translate' })
+
+      expect(PandaPal.lti_custom_params).to eq('custom_canvas_user_id' => '$Canvas.user.id')
+    end
+  end
+
+  describe '.normalize_lti_tool!' do
+    it 'treats blank as the default tool' do
+      expect(PandaPal.normalize_lti_tool!(nil)).to eq(PandaPal::DEFAULT_TOOL)
+      expect(PandaPal.normalize_lti_tool!('')).to eq(PandaPal::DEFAULT_TOOL)
+    end
+
+    it 'accepts defined tools by string or symbol' do
+      PandaPal.define_tool(:translate)
+
+      expect(PandaPal.normalize_lti_tool!('translate')).to eq(:translate)
+    end
+
+    it 'raises for tools that were never defined' do
+      expect { PandaPal.normalize_lti_tool!(:nope) }.to raise_error(PandaPal::UnknownLtiTool)
+      expect { PandaPal.lti_paths(:nope) }.to raise_error(PandaPal::UnknownLtiTool)
+    end
+  end
+
+  describe PandaPal::LaunchUrlHelpers do
+    it 'resolves launch routes from the given tool' do
+      PandaPal.stage_placement(:editor_button, url: :default_editor)
+      PandaPal.stage_placement(:editor_button, tool: :translate, url: :translate_editor)
+
+      expect(described_class.launch_route(:editor_button)).to eq(:default_editor)
+      expect(described_class.launch_route(:editor_button, tool: :translate)).to eq(:translate_editor)
+    end
+
+    it 'resolves deep link redirects from the given tool' do
+      PandaPal.stage_placement(:editor_button, deep_linking: true, deep_link_redirect_url: :default_picker)
+      PandaPal.stage_placement(:editor_button, tool: :translate, deep_linking: true, deep_link_redirect_url: :translate_picker)
+
+      request = double(query_parameters: { 'launch_type' => 'editor_button' })
+
+      expect(described_class.deep_link_redirect_url(request)).to eq(:default_picker)
+      expect(described_class.deep_link_redirect_url(request, tool: :translate)).to eq(:translate_picker)
+    end
+
+    it "falls back to the tool's own deep_link_redirect_url option" do
+      PandaPal.lti_options = { deep_link_redirect_url: :shared_picker }
+      PandaPal.define_tool(:translate, deep_link_redirect_url: :translate_picker)
+
+      request = double(query_parameters: {})
+
+      expect(described_class.deep_link_redirect_url(request)).to eq(:shared_picker)
+      expect(described_class.deep_link_redirect_url(request, tool: :translate)).to eq(:translate_picker)
+    end
+
+    it 'only adds a tool query param for non-default tools' do
+      PandaPal.define_tool(:translate)
+
+      expect(described_class.tool_config_params(nil)).to eq({})
+      expect(described_class.tool_config_params(:translate)).to eq(tool: 'translate')
+    end
+  end
+
+  describe 'lti_nav' do
+    # A throwaway route set, so the dummy app's own routes stay untouched.
+    let(:routes) { ActionDispatch::Routing::RouteSet.new }
+
+    def paths
+      routes.routes.map { |r| r.path.spec.to_s.sub('(.:format)', '') }.uniq
+    end
+
+    it "nests a non-default tool's placement under the tool name" do
+      routes.draw do
+        lti_nav editor_button: 'lti#editor_button'
+        lti_nav editor_button: 'lti#translate', tool: :translate
+      end
+
+      expect(paths).to contain_exactly('/panda_pal/editor_button', '/panda_pal/translate/editor_button')
+      expect(PandaPal.lti_paths[:editor_button][:route_helper_key]).to eq('panda_pal_editor_button')
+      expect(PandaPal.lti_paths(:translate)[:editor_button][:route_helper_key]).to eq('panda_pal_translate_editor_button')
+    end
+  end
+
+  describe '.validate_lti_navigation' do
+    it "reports a non-default tool's placement that has no route" do
+      PandaPal.stage_placement(:editor_button, tool: :translate, url: :no_such_route)
+
+      expect(PandaPal.validate_lti_navigation).to include("lti navigation 'editor_button' (tool 'translate') does not have a Route!")
+    end
+  end
+end