panda_pal 5.17.1 → 5.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f32b5b78d11428c9f4be64fc963ae2fac80cae44abfd66dcda0f39be8b17006
-  data.tar.gz: cb494809a3aa72956b16bad0b7b17ba095156a1c4a7fa7261a51738d92442630
+  metadata.gz: a84b75147fd0b4ac07c4f0aafdda286b9e1f7a5cb16d64b8139e94b12ff82707
+  data.tar.gz: ff14468ea46d91e4aca58048366e9bd93a481ec985ccb87d29ca270d70bd2f18
 SHA512:
-  metadata.gz: 7819962aa331b91ae3b6ad0d95fdb8e5bf314d691cdaa4f120a1f12b199d26c916a811b9f071b9fd73802c8893ae70b6a6158a7ea9457b602f1ea2aa496d4092
-  data.tar.gz: 5cfd2d2f902e658968b3ce2ce2495c5a58e605071db2c97436186b2893f178d2c198856ac42acd9371f6462d108a2a959834958b84ad1fa9d4f9c0740686cc93
+  metadata.gz: 8c885e4859fd35e5ec7f902ccf3edbe097485485e2907a7ecad04a4369d22cd0c5b7d22316dfa9d9e9d205b349ff26a06462baa87c13563a0599e6b6cdfa135c
+  data.tar.gz: 8d91973e5c67bc16fdca3a4cb0b9493afc35d5d823f221caee125e1db1042915bd68f21a30d78e65bd81b472f315203fb64ae22a601be5109aad2ddf1b6e162f

data/AGS.md

@@ -0,0 +1,197 @@
+# Assignment and Grade Services (LTI 1.3)
+
+This document explains how to post scores and read line items and results through LTI Advantage
+Assignment and Grade Services (AGS) in your PandaPal application. AGS replaces the LTI 1.1 Basic
+Outcomes passback (`PandaPal::Jobs::GradePassbackJob`) for LTI 1.3 launches.
+
+## Configuration
+
+### 1. Request the AGS scopes in the tool configuration
+
+The scopes you declare are published as `scopes` in the generated `/v1p3/config` JSON, which
+Canvas copies onto the Developer Key when the tool is installed or updated.
+
+```ruby
+# config/initializers/lti.rb
+PandaPal.lti_scopes = [
+  PandaPal::LtiConstants::AgsScopes::SCORE,
+  PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY,
+  PandaPal::LtiConstants::AgsScopes::RESULT_READONLY,
+]
+```
+
+`PandaPal.lti_scopes` defaults to `[]`, so tools that do not set it publish exactly the same
+configuration as before.
+
+Available scope constants (`PandaPal::LtiConstants::AgsScopes`):
+
+| Constant | Scope | Needed for |
+|----------|-------|------------|
+| `SCORE` | `https://purl.imsglobal.org/spec/lti-ags/scope/score` | `post_score` |
+| `LINEITEM_READONLY` | `https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly` | `line_items`, `line_item` |
+| `LINEITEM` | `https://purl.imsglobal.org/spec/lti-ags/scope/lineitem` | `line_items`, `line_item` (full line item management) |
+| `RESULT_READONLY` | `https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly` | `results` |
+| `ALL` | all of the above | |
+
+### 2. Update the Developer Key
+
+Existing installs keep the scopes stored on their Developer Key. After changing `lti_scopes`,
+push the new configuration to Canvas, for example with
+`org.install_lti(host: ..., exists: :update)`, or edit the Developer Key's scopes by hand.
+
+Canvas only includes the AGS claim in a launch when the Developer Key has the scopes and the
+launch comes from a graded placement (an assignment, or a Deep Linking item created with a
+`lineItem`).
+
+## Posting a score
+
+Include `PandaPal::AgsHelpers` in the controller that handles the launched session, then call
+`ags_client`:
+
+```ruby
+class QuizController < ApplicationController
+  include PandaPal::AgsHelpers
+
+  def submit
+    ags_client.post_score(score_given: 8, score_maximum: 10)
+  rescue PandaPal::LtiServiceError => e
+    Rails.logger.error("AGS passback failed: #{e.message} (#{e.status})")
+    render plain: 'Could not record your grade', status: :bad_gateway
+  end
+end
+```
+
+`ags_client` is `current_session.ags_client`, so the same client is available anywhere you hold a
+`PandaPal::Session`.
+
+`post_score` sends a `POST <lineitem>/scores` with `Content-Type:
+application/vnd.ims.lis.v1.score+json` and the body:
+
+```json
+{
+  "userId": "<the launch sub>",
+  "scoreGiven": 8,
+  "scoreMaximum": 10,
+  "activityProgress": "Completed",
+  "gradingProgress": "FullyGraded",
+  "timestamp": "2026-09-30T12:00:00.123Z"
+}
+```
+
+Options:
+
+| Keyword | Default | Notes |
+|---------|---------|-------|
+| `score_given` | `nil` | Omitted from the body when `nil` (for example to report progress only). |
+| `score_maximum` | `nil` | Required when `score_given` is set. |
+| `user_id` | the launch `sub` | The AGS `userId`. |
+| `lineitem` | the launch `lineitem` | Any line item URL; its query string is kept. |
+| `activity_progress` | `'Completed'` | `Initialized`, `Started`, `InProgress`, `Submitted`, `Completed`. |
+| `grading_progress` | `'FullyGraded'` | `FullyGraded`, `Pending`, `PendingManual`, `Failed`, `NotReady`. |
+| `comment` | `nil` | Omitted when `nil`. |
+| `timestamp` | `Time.now` | Sent as UTC ISO 8601 with milliseconds. |
+| any other keyword | | Merged into the body as is, for example Canvas's `'https://canvas.instructure.com/lti/submission': { new_submission: true }`. |
+
+It returns the parsed JSON response (Canvas answers with a `resultUrl`), or `nil` for an empty body.
+
+## Reading line items and results
+
+```ruby
+ags_client.line_items                                 # GET <lineitems>, every page
+ags_client.line_items(resource_link_id: 'abc', tag: 'grade', limit: 50)
+ags_client.line_item                                  # GET <launch lineitem>
+ags_client.line_item('https://canvas.example.com/api/lti/courses/1/line_items/9')
+ags_client.results                                    # GET <lineitem>/results, every page
+ags_client.results(user_id: 'sub-uuid', limit: 10)
+```
+
+The list calls follow `Link: <...>; rel="next"` headers and return one array. A `next` link on a
+different scheme, host or port than the first page is not followed, so the service token is
+never sent off the platform. Paging stops after 100 pages.
+
+`line_items` and `line_item` use the `lineitem.readonly` scope when the launch granted it and
+fall back to `lineitem`.
+
+## Outside a request (background jobs)
+
+The client needs the platform, the client_id and the AGS claim. A session is the simplest thing
+to hand a job:
+
+```ruby
+class PostScoreJob < ApplicationJob
+  def perform(session_id, score)
+    session = PandaPal::Session.find(session_id)
+    session.ags_client.post_score(score_given: score, score_maximum: 100)
+  end
+end
+```
+
+Or build it from stored launch claims, or entirely from explicit values:
+
+```ruby
+PandaPal::AgsClient.from_launch(launch_params, platform: platform)
+
+PandaPal::AgsClient.new(
+  platform: PandaPal::Platform::Canvas.new(iss: 'https://canvas.instructure.com'),
+  client_id: '10000000000042',
+  scopes: [PandaPal::LtiConstants::AgsScopes::SCORE],
+  lineitem: 'https://canvas.example.com/api/lti/courses/1/line_items/7',
+  user_id: 'sub-uuid',
+)
+```
+
+`scopes` is required: the client refuses any call the scopes do not cover, before it requests a
+token.
+
+## Service access tokens
+
+Every AGS call is authorized with an OAuth 2 client_credentials token from the platform's
+`grant_url` (`/login/oauth2/token` on Canvas). `PandaPal::Platform` handles this, and it is
+usable for other LTI Advantage services too:
+
+```ruby
+platform = current_session.lti_platform
+platform.service_access_token(client_id: client_id, scopes: [scope])        # String
+platform.service_access_token(client_id: client_id, scopes: [scope], force: true)
+platform.expire_service_access_token(client_id: client_id, scopes: [scope])
+platform.service_request(:get, url, client_id: client_id, scopes: [scope], headers: { 'Accept' => '...' })
+```
+
+- The token request posts `grant_type=client_credentials`,
+  `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer`, the requested
+  scopes space-separated, and a `client_assertion` JWT (`iss` and `sub` are the client_id, `aud`
+  is the `grant_url`, with `iat`, `exp` five minutes later and a random `jti`). The assertion is
+  signed RS256 with `PandaPal.lti_private_key`, with `kid` set to `PandaPal.jwk.kid`, so it
+  verifies against the tool's `/v1p3/public_jwks`.
+- Tokens are cached in `Rails.cache` for `expires_in` less one minute (one hour less a minute when
+  the platform omits `expires_in`), keyed by a SHA-256 of the grant URL, client_id and scope set.
+  Use a shared cache store (Redis, Memcached) in production so every process reuses the token.
+- `service_request` sends `Authorization: Bearer <token>`. When a cached token is answered with a
+  401, it drops that token, fetches a new one and retries once. A freshly issued token that gets a
+  401 is not retried.
+- Every request is bounded by `Platform::SERVICE_HTTP_OPTIONS` (5 second open, 15 second read and
+  write timeouts). Network failures raise `PandaPal::LtiServiceError`.
+
+## Errors
+
+All errors descend from `PandaPal::LtiServiceError`, which carries the HTTP `status` when there
+was one. Messages never include the token, the client assertion or the response body.
+
+| Error | Raised when |
+|-------|-------------|
+| `PandaPal::AgsClient::NotGranted` | The launch did not grant the scope, or carried no `lineitem` / `lineitems` URL, or there is no user id. Raised before any HTTP request. |
+| `PandaPal::AgsClient::Error` | No platform or client_id, or an AGS URL that is not http(s). |
+| `PandaPal::AgsClient::RequestFailed` | An AGS call answered non-2xx, or with a body that is not JSON. |
+| `PandaPal::Platform::ServiceTokenError` | The token request answered non-2xx, or without an `access_token`. |
+| `PandaPal::LtiServiceError` | A timeout, connection or TLS failure. |
+
+## Troubleshooting
+
+- **`NotGranted` on every call**: the launch has no `https://purl.imsglobal.org/spec/lti-ags/claim/endpoint`
+  claim. Check that the Developer Key has the scopes (see `/v1p3/config`) and that the tool was
+  launched from an assignment.
+- **`ServiceTokenError` with status 400 or 401**: the Developer Key does not allow the requested
+  scope, the client_id is wrong, or Canvas cannot verify the assertion against the tool's public
+  JWKS (check `LTI_PRIVATE_KEY` matches the key Canvas has).
+- **`RequestFailed` on `post_score`**: check `e.status` and the platform logs. The `userId` must be
+  the launch `sub` of a user enrolled in the course, and `scoreMaximum` must accompany `scoreGiven`.

data/README.md

@@ -213,6 +213,29 @@ lti_nav content_launch: 'content#launch'
 
 **For complete configuration options, implementation examples, helper method documentation, and troubleshooting, see [DEEP_LINKING.md](DEEP_LINKING.md).**
 
+## Assignment and Grade Services (LTI 1.3)
+
+PandaPal can post scores and read line items and results through LTI Advantage AGS.
+
+1. **Request the scopes** in your LTI initializer (published in `/v1p3/config`):
+```ruby
+# config/initializers/lti.rb
+PandaPal.lti_scopes = [PandaPal::LtiConstants::AgsScopes::SCORE]
+```
+
+2. **Post a score** from a controller serving the launched session:
+```ruby
+class QuizController < ApplicationController
+  include PandaPal::AgsHelpers
+
+  def submit
+    ags_client.post_score(score_given: 8, score_maximum: 10)
+  end
+end
+```
+
+**For scopes, line items, results, service tokens, background jobs and error handling, see [AGS.md](AGS.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`,

data/app/controllers/panda_pal/lti_v1_p3_controller.rb

@@ -105,7 +105,7 @@ module PandaPal
 
       config_json = {
         title: PandaPal.lti_options[:title],
-        scopes: [],
+        scopes: PandaPal.lti_scopes,
         public_jwk_url: v1p3_public_jwks_url,
         description: PandaPal.lti_options[:description] || 'PandaPal LTI',
         target_link_uri: v1p3_resource_link_request_url, #app_url(:resource_link_request, request),

data/app/lib/panda_pal/ags_client.rb

@@ -0,0 +1,197 @@
+module PandaPal
+  class AgsClient
+    class Error < LtiServiceError; end
+    class NotGranted < Error; end
+    class RequestFailed < Error; end
+
+    SCOPES = LtiConstants::AgsScopes
+    MEDIA_TYPES = LtiConstants::AgsMediaTypes
+    MAX_PAGES = 100
+
+    attr_reader :platform, :client_id, :lineitem, :lineitems, :scopes, :user_id
+
+    def self.for_session(session)
+      launch = (session.launch_params || {}).to_h.with_indifferent_access
+      org_client_id = session.panda_pal_organization&.key.to_s.split('/').first
+
+      from_launch(launch, platform: session.lti_platform, client_id: launch_client_id(launch).presence || org_client_id)
+    end
+
+    def self.from_launch(launch, platform:, client_id: nil)
+      launch = launch.to_h.with_indifferent_access
+      endpoint = launch[LtiConstants::Ags::ENDPOINT] || {}
+
+      new(
+        platform: platform,
+        client_id: client_id.presence || launch_client_id(launch),
+        lineitem: endpoint['lineitem'],
+        lineitems: endpoint['lineitems'],
+        scopes: endpoint['scope'],
+        user_id: launch['sub'],
+      )
+    end
+
+    def self.launch_client_id(launch)
+      launch['azp'].presence || Array(launch['aud']).first
+    end
+
+    def initialize(platform:, client_id:, scopes:, lineitem: nil, lineitems: nil, user_id: nil)
+      @platform = platform
+      @client_id = client_id
+      @lineitem = lineitem.presence
+      @lineitems = lineitems.presence
+      @scopes = Array(scopes).map(&:to_s)
+      @user_id = user_id
+    end
+
+    def granted?(*required)
+      required.flatten.all? { |scope| scopes.include?(scope) }
+    end
+
+    def post_score(score_given: nil, score_maximum: nil, user_id: self.user_id, lineitem: self.lineitem,
+                   activity_progress: 'Completed', grading_progress: 'FullyGraded', comment: nil,
+                   timestamp: Time.now, **extra)
+      require_scope!(SCOPES::SCORE)
+      raise ArgumentError, 'score_maximum is required when score_given is set' if !score_given.nil? && score_maximum.nil?
+      raise NotGranted, 'no AGS userId: pass user_id or launch with a sub claim' if user_id.blank?
+
+      body = {
+        userId: user_id,
+        scoreGiven: score_given,
+        scoreMaximum: score_maximum,
+        activityProgress: activity_progress,
+        gradingProgress: grading_progress,
+        timestamp: timestamp.to_time.getutc.iso8601(3),
+        comment: comment,
+      }.compact.merge(extra)
+
+      response = request(:post, child_url(require_lineitem!(lineitem), 'scores'), SCOPES::SCORE,
+        headers: { 'Content-Type' => MEDIA_TYPES::SCORE },
+        body: JSON.generate(body))
+      parse(response)
+    end
+
+    def line_items(**filters)
+      scope = read_line_item_scope!
+      raise NotGranted, 'launch carried no AGS lineitems URL' if lineitems.blank?
+
+      paginate(with_query(lineitems, filters), scope, MEDIA_TYPES::LINEITEM_CONTAINER)
+    end
+
+    def line_item(url = lineitem)
+      scope = read_line_item_scope!
+      response = request(:get, validate_url!(require_lineitem!(url)).to_s, scope,
+        headers: { 'Accept' => MEDIA_TYPES::LINEITEM })
+      parse(response)
+    end
+
+    def results(lineitem: self.lineitem, user_id: nil, limit: nil)
+      require_scope!(SCOPES::RESULT_READONLY)
+      url = with_query(child_url(require_lineitem!(lineitem), 'results'), user_id: user_id, limit: limit)
+      paginate(url, SCOPES::RESULT_READONLY, MEDIA_TYPES::RESULT_CONTAINER)
+    end
+
+    private
+
+    def require_scope!(scope)
+      raise NotGranted, "launch did not grant the AGS scope #{scope}" unless granted?(scope)
+    end
+
+    def read_line_item_scope!
+      return SCOPES::LINEITEM_READONLY if granted?(SCOPES::LINEITEM_READONLY)
+      return SCOPES::LINEITEM if granted?(SCOPES::LINEITEM)
+
+      raise NotGranted, "launch did not grant the AGS scope #{SCOPES::LINEITEM_READONLY} or #{SCOPES::LINEITEM}"
+    end
+
+    def require_lineitem!(url)
+      raise NotGranted, 'launch carried no AGS lineitem' if url.blank?
+
+      url
+    end
+
+    def request(method, url, scope, **options)
+      raise Error, 'no LTI platform to request an AGS token from' if platform.nil?
+      raise Error, 'no client_id to request an AGS token for' if client_id.blank?
+
+      response = platform.service_request(method, url, client_id: client_id, scopes: [scope], **options)
+      raise RequestFailed.new("AGS #{method.to_s.upcase} answered #{response.code}", status: response.code) unless response.success?
+
+      response
+    end
+
+    def paginate(url, scope, media_type)
+      items = []
+      origin = origin_of(url)
+
+      MAX_PAGES.times do
+        response = request(:get, url, scope, headers: { 'Accept' => media_type })
+        page = parse(response)
+        items.concat(Array.wrap(page))
+
+        next_url = next_link(response)
+        return items if next_url.nil?
+
+        url = URI.join(url, next_url).to_s
+        return items if origin_of(url) != origin
+      end
+
+      items
+    end
+
+    def parse(response)
+      body = response.body.to_s
+      return nil if body.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise RequestFailed.new('AGS response was not JSON', status: response.code)
+    end
+
+    def next_link(response)
+      header = response.headers && response.headers['link']
+      return nil if header.blank?
+
+      Array(header).join(',').split(',').each do |part|
+        match = part.match(/<([^>]+)>\s*;(.*)/)
+        next unless match && match[2] =~ /rel="?next"?/
+
+        return match[1]
+      end
+
+      nil
+    end
+
+    def child_url(url, segment)
+      uri = validate_url!(url)
+      uri.path = "#{uri.path.chomp('/')}/#{segment}"
+      uri.to_s
+    end
+
+    def with_query(url, params)
+      params = params.compact.transform_keys(&:to_s)
+      uri = validate_url!(url)
+      return uri.to_s if params.empty?
+
+      query = Rack::Utils.parse_query(uri.query).merge(params.transform_values(&:to_s))
+      uri.query = Rack::Utils.build_query(query)
+      uri.to_s
+    end
+
+    def validate_url!(url)
+      uri = URI.parse(url.to_s)
+      raise Error, 'AGS URL is not an http(s) URL' unless uri.is_a?(URI::HTTP) && uri.host.present?
+
+      uri
+    rescue URI::InvalidURIError
+      raise Error, 'AGS URL is not an http(s) URL'
+    end
+
+    def origin_of(url)
+      uri = URI.parse(url.to_s)
+      [uri.scheme, uri.host, uri.port]
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/app/lib/panda_pal/ags_helpers.rb

@@ -0,0 +1,7 @@
+module PandaPal
+  module AgsHelpers
+    def ags_client
+      current_session.ags_client
+    end
+  end
+end

data/app/models/panda_pal/platform.rb

@@ -23,6 +23,35 @@ module PandaPal
       nil
     end
 
+    class ServiceTokenError < LtiServiceError; end
+
+    CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'.freeze
+    CLIENT_ASSERTION_LIFETIME = 5.minutes
+    SERVICE_TOKEN_DEFAULT_LIFETIME = 1.hour
+    SERVICE_TOKEN_EXPIRY_MARGIN = 1.minute
+    SERVICE_HTTP_OPTIONS = { open_timeout: 5, read_timeout: 15, write_timeout: 15 }.freeze
+    SERVICE_NETWORK_ERRORS = [
+      Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, SocketError, SystemCallError,
+      OpenSSL::SSL::SSLError, HTTParty::Error,
+    ].freeze
+
+    def service_access_token(client_id:, scopes:, force: false)
+      fetch_service_access_token(client_id, scopes, force: force).first
+    end
+
+    def expire_service_access_token(client_id:, scopes:)
+      Rails.cache.delete(service_token_cache_key(client_id, scopes))
+    end
+
+    def service_request(method, url, client_id:, scopes:, headers: {}, **options)
+      token, cached = fetch_service_access_token(client_id, scopes)
+      response = authorized_service_request(method, url, token, headers, options)
+      return response unless response.code == 401 && cached
+
+      token, = fetch_service_access_token(client_id, scopes, force: true)
+      authorized_service_request(method, url, token, headers, options)
+    end
+
     def self.from_serialized(ser)
       cls = ser[:platform_class].safe_constantize
       cls.deserialize(ser)
@@ -83,6 +112,81 @@ module PandaPal
       end
     end
 
+    private
+
+    def fetch_service_access_token(client_id, scopes, force: false)
+      cache_key = service_token_cache_key(client_id, scopes)
+
+      unless force
+        cached = Rails.cache.read(cache_key)
+        return [cached, true] if cached.present?
+      end
+
+      [request_service_access_token(client_id, scopes, cache_key), false]
+    end
+
+    def request_service_access_token(client_id, scopes, cache_key)
+      response = http_service_request(:post, grant_url, 'token request', body: {
+        grant_type: 'client_credentials',
+        client_assertion_type: CLIENT_ASSERTION_TYPE,
+        client_assertion: service_client_assertion(client_id),
+        scope: normalize_service_scopes(scopes).join(' '),
+      })
+
+      raise ServiceTokenError.new("token request answered #{response.code}", status: response.code) unless response.success?
+
+      parsed = parse_service_json(response.body)
+      token = parsed['access_token'] if parsed.is_a?(Hash)
+      raise ServiceTokenError.new('token response carried no access_token', status: response.code) unless token.is_a?(String) && token.present?
+
+      expires_in = parsed['expires_in'].to_i
+      lifetime = expires_in.positive? ? expires_in.seconds : SERVICE_TOKEN_DEFAULT_LIFETIME
+      ttl = lifetime - SERVICE_TOKEN_EXPIRY_MARGIN
+      Rails.cache.write(cache_key, token, expires_in: ttl) if ttl.positive?
+
+      token
+    end
+
+    def authorized_service_request(method, url, token, headers, options)
+      http_service_request(method, url, "#{method.to_s.upcase} request",
+        headers: headers.merge('Authorization' => "Bearer #{token}"), **options)
+    end
+
+    def http_service_request(method, url, label, **options)
+      HTTParty.send(method, url, **SERVICE_HTTP_OPTIONS, **options)
+    rescue *SERVICE_NETWORK_ERRORS => e
+      raise LtiServiceError, "#{label} failed: #{e.class}"
+    end
+
+    def parse_service_json(body)
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def service_client_assertion(client_id)
+      jwk = PandaPal.jwk
+      now = Time.now.to_i
+      claims = {
+        iss: client_id,
+        sub: client_id,
+        aud: grant_url,
+        iat: now,
+        exp: now + CLIENT_ASSERTION_LIFETIME.to_i,
+        jti: SecureRandom.uuid,
+      }
+      JWT.encode(claims, jwk.signing_key, jwk[:alg], kid: jwk[:kid])
+    end
+
+    def normalize_service_scopes(scopes)
+      Array(scopes).map(&:to_s).reject(&:blank?).uniq.sort
+    end
+
+    def service_token_cache_key(client_id, scopes)
+      digest = Digest::SHA256.hexdigest([grant_url, client_id.to_s, *normalize_service_scopes(scopes)].join("\n"))
+      "panda_pal/lti_service_tokens/#{digest}"
+    end
+
     protected
 
     def self.find_org_setting(paths, org = current_organization)

data/app/models/panda_pal/session.rb

@@ -203,6 +203,10 @@ module PandaPal
       @lti_platform ||= Platform.from_serialized(data[:lti_platform])
     end
 
+    def ags_client
+      @ags_client ||= AgsClient.for_session(self)
+    end
+
     def lti_launch_placement
       launch_params['https://www.instructure.com/placement'] || launch_params[:launch_type]
     end

data/config/initializers/apartment.rb

@@ -148,10 +148,7 @@ 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
 
-        unless ActiveRecord::Base.connected?
-          Apartment.establish_connection multi_tenantify(tenant, false)
-          Apartment.connection.verify!
-        end
+        establish_connection_pool(tenant) unless connection_pool_registered?
 
         Apartment.connection.enable_query_cache! if query_cache_enabled
 
@@ -171,6 +168,25 @@ module Apartment
 
       protected
 
+      ESTABLISH_CONNECTION_LOCK = Mutex.new
+
+      def connection_pool_registered?
+        !ActiveRecord::Base.connection_handler.retrieve_connection_pool(
+          ActiveRecord::Base.connection_specification_name,
+          role: ActiveRecord::Base.current_role,
+          shard: ActiveRecord::Base.current_shard,
+        ).nil?
+      end
+
+      def establish_connection_pool(tenant)
+        ESTABLISH_CONNECTION_LOCK.synchronize do
+          next if connection_pool_registered?
+
+          Apartment.establish_connection multi_tenantify(tenant, false)
+          Apartment.connection.verify!
+        end
+      end
+
       def persistent_schemas
         map_to_schemas(super)
       end

data/lib/panda_pal/lti_constants.rb

@@ -19,6 +19,25 @@ module PandaPal
       DEEP_LINKING_SETTINGS = 'https://purl.imsglobal.org/spec/lti-dl/claim/deep_linking_settings'.freeze
     end
 
+    module Ags
+      ENDPOINT = 'https://purl.imsglobal.org/spec/lti-ags/claim/endpoint'.freeze
+    end
+
+    module AgsScopes
+      LINEITEM = 'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'.freeze
+      LINEITEM_READONLY = 'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly'.freeze
+      RESULT_READONLY = 'https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly'.freeze
+      SCORE = 'https://purl.imsglobal.org/spec/lti-ags/scope/score'.freeze
+      ALL = [LINEITEM, LINEITEM_READONLY, RESULT_READONLY, SCORE].freeze
+    end
+
+    module AgsMediaTypes
+      LINEITEM = 'application/vnd.ims.lis.v2.lineitem+json'.freeze
+      LINEITEM_CONTAINER = 'application/vnd.ims.lis.v2.lineitemcontainer+json'.freeze
+      RESULT_CONTAINER = 'application/vnd.ims.lis.v2.resultcontainer+json'.freeze
+      SCORE = 'application/vnd.ims.lis.v1.score+json'.freeze
+    end
+
     # Canvas-specific Claims
     module Canvas
       PLACEMENT = 'https://www.instructure.com/placement'.freeze

data/lib/panda_pal/version.rb

@@ -1,3 +1,3 @@
 module PandaPal
-  VERSION = '5.17.1'
+  VERSION = '5.18.0'
 end