panda_pal 5.17.2 → 5.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d2cfdbfc9d2c60cc080b545d2ee582ce212623a45c286d8610b8ac5f6c1af37
-  data.tar.gz: 4918d3bee6808bfbf22e98e23f3cbedcd493d4ec7c946ac67e0c8ca5485d9eca
+  metadata.gz: a84b75147fd0b4ac07c4f0aafdda286b9e1f7a5cb16d64b8139e94b12ff82707
+  data.tar.gz: ff14468ea46d91e4aca58048366e9bd93a481ec985ccb87d29ca270d70bd2f18
 SHA512:
-  metadata.gz: 0e06e419047c6a29e1ed8f03966bae4c31ed9e5b57ad6953133b890f6dab407d384ea1f071e0c88e01f7a69ef790f9b132f98a973aa3602b6b902d4871722799
-  data.tar.gz: 6d19e0a9ea13914f8045d62525dd73dcb97aadfc780dc1c4907fe3b80df9483144d1cc3cc087d509aa7cfba344aa64aaa4b7bd36b05fea354201d7e387094db4
+  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/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.2'
+  VERSION = '5.18.0'
 end

data/lib/panda_pal.rb

@@ -13,11 +13,21 @@ module PandaPal
   class LtiNavigationInUse < StandardError;end
   class NotMounted < StandardError;end
 
+  class LtiServiceError < StandardError
+    attr_reader :status
+
+    def initialize(message = nil, status: nil)
+      super(message)
+      @status = status
+    end
+  end
+
   @@lti_navigation = {}
   @@lti_options = {}
   @@lti_properties = {}
   @@lti_environments = {}
   @@lti_custom_params = {}
+  @@lti_scopes = []
   @@extensions = {}
   @@lti_private_key = nil
 
@@ -53,6 +63,14 @@ module PandaPal
     @@lti_custom_params.deep_dup
   end
 
+  def self.lti_scopes=(scopes)
+    @@lti_scopes = Array(scopes).map(&:to_s)
+  end
+
+  def self.lti_scopes
+    @@lti_scopes.deep_dup
+  end
+
   def self.stage_navigation(navigation, options = {})
     warn "[DEPRECATION] `stage_navigation` is deprecated. Please use `stage_placement` instead."
     stage_placement(navigation, options)

data/panda_pal.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
   s.summary     = "LTI mountable engine"
   s.license     = "MIT"
 
-  s.files = Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md", "panda_pal.gemspec"]
+  s.files = Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md", "AGS.md", "panda_pal.gemspec"]
   s.test_files = Dir["spec/**/*"].reject{|f| f =~ /\/log\//}
 
   s.add_dependency "rails", ">= 4.2"

data/spec/controllers/panda_pal/lti_v1_p3_controller_spec.rb

@@ -75,4 +75,34 @@ RSpec.describe "PandaPal::LtiV1P3Controller", type: :request do
       expect(hidden_fields['nonce']).not_to be_blank
     end
   end
+
+  describe 'GET /v1p3/config' do
+    before { PandaPal.lti_environments = { domain: 'tool.example.com' } }
+
+    after do
+      PandaPal.lti_environments = {}
+      PandaPal.lti_scopes = []
+    end
+
+    it 'publishes no scopes by default' do
+      get "/panda_pal/v1p3/config"
+
+      expect(response).to have_http_status(:ok)
+      expect(JSON.parse(response.body)['scopes']).to eq([])
+    end
+
+    it 'publishes the configured PandaPal.lti_scopes' do
+      PandaPal.lti_scopes = [
+        PandaPal::LtiConstants::AgsScopes::SCORE,
+        PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY,
+      ]
+
+      get "/panda_pal/v1p3/config"
+
+      expect(JSON.parse(response.body)['scopes']).to eq([
+        'https://purl.imsglobal.org/spec/lti-ags/scope/score',
+        'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly',
+      ])
+    end
+  end
 end

data/spec/lib/panda_pal/ags_client_spec.rb

@@ -0,0 +1,385 @@
+require 'spec_helper'
+
+RSpec.describe PandaPal::AgsClient do
+  let(:platform) { PandaPal::Platform::Canvas.new(iss: 'https://canvas.instructure.com') }
+  let(:client_id) { '10000000000042' }
+  let(:lineitem) { 'https://canvas.example.com/api/lti/courses/1/line_items/7' }
+  let(:lineitems) { 'https://canvas.example.com/api/lti/courses/1/line_items' }
+  let(:scopes) { PandaPal::LtiConstants::AgsScopes::ALL }
+  let(:user_id) { 'launch-sub-uuid' }
+
+  subject(:client) do
+    described_class.new(platform: platform, client_id: client_id, scopes: scopes,
+      lineitem: lineitem, lineitems: lineitems, user_id: user_id)
+  end
+
+  def http_response(code, body = '', headers = {})
+    double('HTTParty::Response', code: code, success?: (200..299).cover?(code), body: body, headers: headers)
+  end
+
+  def expect_service_request(method, url, scope, response, **options)
+    expect(platform).to receive(:service_request)
+      .with(method, url, client_id: client_id, scopes: [scope], **options)
+      .and_return(response)
+  end
+
+  describe '.from_launch' do
+    let(:launch) do
+      {
+        'sub' => user_id,
+        'aud' => client_id,
+        PandaPal::LtiConstants::Ags::ENDPOINT => {
+          'scope' => [PandaPal::LtiConstants::AgsScopes::SCORE],
+          'lineitem' => lineitem,
+          'lineitems' => lineitems,
+        },
+      }
+    end
+
+    it 'reads the AGS endpoint claim, the sub and the client_id' do
+      built = described_class.from_launch(launch, platform: platform)
+
+      expect(built.platform).to eq(platform)
+      expect(built.client_id).to eq(client_id)
+      expect(built.user_id).to eq(user_id)
+      expect(built.lineitem).to eq(lineitem)
+      expect(built.lineitems).to eq(lineitems)
+      expect(built.scopes).to eq([PandaPal::LtiConstants::AgsScopes::SCORE])
+    end
+
+    it 'prefers azp over an aud array' do
+      built = described_class.from_launch(launch.merge('aud' => ['other', client_id], 'azp' => client_id), platform: platform)
+
+      expect(built.client_id).to eq(client_id)
+    end
+
+    it 'grants nothing when the launch has no AGS claim' do
+      built = described_class.from_launch(launch.except(PandaPal::LtiConstants::Ags::ENDPOINT), platform: platform)
+
+      expect(built.scopes).to eq([])
+      expect(built.lineitem).to be_nil
+      expect { built.post_score(score_given: 1, score_maximum: 1) }.to raise_error(described_class::NotGranted)
+    end
+  end
+
+  describe '.for_session and Session#ags_client' do
+    let(:organization) { create(:panda_pal_organization, key: "#{client_id}/deployment-1") }
+    let(:session) do
+      PandaPal::Session.new(panda_pal_organization: organization, data: {
+        lti_platform: platform.serialize,
+        launch_params: {
+          'sub' => user_id,
+          'aud' => client_id,
+          PandaPal::LtiConstants::Ags::ENDPOINT => { 'scope' => scopes, 'lineitem' => lineitem, 'lineitems' => lineitems },
+        },
+      })
+    end
+
+    it 'builds a client from the session launch_params and lti_platform' do
+      built = session.ags_client
+
+      expect(built).to be_a(described_class)
+      expect(built.platform).to be_a(PandaPal::Platform::Canvas)
+      expect(built.platform.grant_url).to eq(platform.grant_url)
+      expect(built.client_id).to eq(client_id)
+      expect(built.lineitem).to eq(lineitem)
+      expect(built.user_id).to eq(user_id)
+      expect(built.scopes).to eq(scopes)
+      expect(session.ags_client).to be(built)
+    end
+
+    it 'falls back to the client_id half of the organization key when the launch has no aud' do
+      session.data[:launch_params].delete('aud')
+
+      expect(described_class.for_session(session).client_id).to eq(client_id)
+    end
+
+    it 'is exposed to controllers through PandaPal::AgsHelpers' do
+      host = Class.new do
+        include PandaPal::AgsHelpers
+
+        attr_reader :current_session
+
+        def initialize(session)
+          @current_session = session
+        end
+      end
+
+      expect(host.new(session).ags_client).to be(session.ags_client)
+    end
+  end
+
+  describe '#post_score' do
+    let(:scores_url) { "#{lineitem}/scores" }
+
+    it 'posts the AGS score media type to the lineitem scores endpoint for the launch sub' do
+      captured = nil
+      expect(platform).to receive(:service_request) do |method, url, **options|
+        captured = { method: method, url: url, options: options }
+        http_response(200, '{"resultUrl":"https://canvas.example.com/results/1"}')
+      end
+
+      timestamp = Time.utc(2026, 9, 30, 12, 0, 0, 123_456)
+      result = client.post_score(score_given: 8, score_maximum: 10, timestamp: timestamp)
+
+      expect(result).to eq('resultUrl' => 'https://canvas.example.com/results/1')
+      expect(captured[:method]).to eq(:post)
+      expect(captured[:url]).to eq(scores_url)
+      expect(captured[:options][:client_id]).to eq(client_id)
+      expect(captured[:options][:scopes]).to eq([PandaPal::LtiConstants::AgsScopes::SCORE])
+      expect(captured[:options][:headers]).to eq('Content-Type' => 'application/vnd.ims.lis.v1.score+json')
+      expect(JSON.parse(captured[:options][:body])).to eq(
+        'userId' => user_id,
+        'scoreGiven' => 8,
+        'scoreMaximum' => 10,
+        'activityProgress' => 'Completed',
+        'gradingProgress' => 'FullyGraded',
+        'timestamp' => '2026-09-30T12:00:00.123Z',
+      )
+    end
+
+    it 'includes a comment, overrides and extra fields when given' do
+      other_user = SecureRandom.uuid
+      body = nil
+      allow(platform).to receive(:service_request) { |*, **options| body = JSON.parse(options[:body]); http_response(204) }
+
+      result = client.post_score(score_given: 1, score_maximum: 1, comment: 'Well done', user_id: other_user,
+        activity_progress: 'Submitted', grading_progress: 'Pending',
+        'https://canvas.instructure.com/lti/submission': { new_submission: true })
+
+      expect(result).to be_nil
+      expect(body).to include(
+        'userId' => other_user,
+        'comment' => 'Well done',
+        'activityProgress' => 'Submitted',
+        'gradingProgress' => 'Pending',
+        'https://canvas.instructure.com/lti/submission' => { 'new_submission' => true },
+      )
+    end
+
+    it 'omits scoreGiven and scoreMaximum when no score is given' do
+      body = nil
+      allow(platform).to receive(:service_request) { |*, **options| body = JSON.parse(options[:body]); http_response(200, '{}') }
+
+      client.post_score(activity_progress: 'Started', grading_progress: 'NotReady')
+
+      expect(body.keys).not_to include('scoreGiven', 'scoreMaximum')
+    end
+
+    it 'keeps a lineitem query string after the scores segment' do
+      with_query = described_class.new(platform: platform, client_id: client_id, scopes: scopes, user_id: user_id,
+        lineitem: 'https://canvas.example.com/api/lti/courses/1/line_items/7?type_id=abc&x=1')
+      expect(platform).to receive(:service_request)
+        .with(:post, 'https://canvas.example.com/api/lti/courses/1/line_items/7/scores?type_id=abc&x=1', anything)
+        .and_return(http_response(200, '{}'))
+
+      with_query.post_score(score_given: 1, score_maximum: 1)
+    end
+
+    it 'does not double a trailing slash' do
+      expect(platform).to receive(:service_request).with(:post, scores_url, anything).and_return(http_response(200, '{}'))
+
+      described_class.new(platform: platform, client_id: client_id, scopes: scopes, user_id: user_id, lineitem: "#{lineitem}/")
+        .post_score(score_given: 1, score_maximum: 1)
+    end
+
+    it 'refuses before any request when the score scope was not granted' do
+      expect(platform).not_to receive(:service_request)
+
+      limited = described_class.new(platform: platform, client_id: client_id, lineitem: lineitem, user_id: user_id,
+        scopes: [PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY])
+
+      expect { limited.post_score(score_given: 1, score_maximum: 1) }
+        .to raise_error(described_class::NotGranted, %r{scope/score})
+    end
+
+    it 'refuses before any request when the launch carried no lineitem' do
+      expect(platform).not_to receive(:service_request)
+
+      no_lineitem = described_class.new(platform: platform, client_id: client_id, scopes: scopes, user_id: user_id)
+
+      expect { no_lineitem.post_score(score_given: 1, score_maximum: 1) }
+        .to raise_error(described_class::NotGranted, /no AGS lineitem/)
+    end
+
+    it 'refuses a lineitem that is not an http(s) URL' do
+      expect(platform).not_to receive(:service_request)
+
+      bad = described_class.new(platform: platform, client_id: client_id, scopes: scopes, user_id: user_id, lineitem: 'javascript:alert(1)')
+
+      expect { bad.post_score(score_given: 1, score_maximum: 1) }.to raise_error(described_class::Error, /http\(s\)/)
+    end
+
+    it 'refuses when there is no user id' do
+      expect(platform).not_to receive(:service_request)
+
+      expect { client.post_score(score_given: 1, score_maximum: 1, user_id: nil) }
+        .to raise_error(described_class::NotGranted, /userId/)
+    end
+
+    it 'requires score_maximum alongside score_given' do
+      expect { client.post_score(score_given: 1) }.to raise_error(ArgumentError)
+    end
+
+    it 'refuses when there is no platform' do
+      no_platform = described_class.new(platform: nil, client_id: client_id, scopes: scopes, user_id: user_id, lineitem: lineitem)
+
+      expect { no_platform.post_score(score_given: 1, score_maximum: 1) }.to raise_error(described_class::Error, /platform/)
+    end
+
+    it 'raises RequestFailed with the status on a non-2xx answer' do
+      allow(platform).to receive(:service_request).and_return(http_response(422, '{"errors":"bad"}'))
+
+      expect { client.post_score(score_given: 1, score_maximum: 1) }
+        .to raise_error(described_class::RequestFailed) { |error|
+          expect(error.status).to eq(422)
+          expect(error).to be_a(PandaPal::LtiServiceError)
+        }
+    end
+  end
+
+  describe '#line_items' do
+    let(:container) { PandaPal::LtiConstants::AgsMediaTypes::LINEITEM_CONTAINER }
+    let(:readonly) { PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY }
+
+    it 'lists line items with the container media type and the read-only scope' do
+      expect_service_request(:get, lineitems, readonly,
+        http_response(200, [{ 'id' => lineitem, 'label' => 'Quiz' }].to_json),
+        headers: { 'Accept' => container })
+
+      expect(client.line_items).to eq([{ 'id' => lineitem, 'label' => 'Quiz' }])
+    end
+
+    it 'adds filters to the query string' do
+      expect_service_request(:get, "#{lineitems}?resource_link_id=rl-1&tag=grade", readonly,
+        http_response(200, '[]'), headers: { 'Accept' => container })
+
+      expect(client.line_items(resource_link_id: 'rl-1', tag: 'grade', resource_id: nil)).to eq([])
+    end
+
+    it 'follows rel="next" links on the same origin' do
+      page_two = "#{lineitems}?page=2"
+      expect_service_request(:get, lineitems, readonly,
+        http_response(200, '[{"id":"a"}]', { 'link' => %(<#{page_two}>; rel="next", <#{lineitems}?page=9>; rel="last") }),
+        headers: { 'Accept' => container })
+      expect_service_request(:get, page_two, readonly, http_response(200, '[{"id":"b"}]'), headers: { 'Accept' => container })
+
+      expect(client.line_items.map { |item| item['id'] }).to eq(%w[a b])
+    end
+
+    it 'does not follow a next link to another origin' do
+      expect_service_request(:get, lineitems, readonly,
+        http_response(200, '[{"id":"a"}]', { 'link' => '<https://attacker.example.com/steal>; rel="next"' }),
+        headers: { 'Accept' => container })
+
+      expect(client.line_items.map { |item| item['id'] }).to eq(%w[a])
+    end
+
+    it 'uses the lineitem scope when only that was granted' do
+      full = described_class.new(platform: platform, client_id: client_id, lineitems: lineitems,
+        scopes: [PandaPal::LtiConstants::AgsScopes::LINEITEM])
+      expect_service_request(:get, lineitems, PandaPal::LtiConstants::AgsScopes::LINEITEM,
+        http_response(200, '[]'), headers: { 'Accept' => container })
+
+      full.line_items
+    end
+
+    it 'refuses when no line item scope was granted' do
+      expect(platform).not_to receive(:service_request)
+
+      score_only = described_class.new(platform: platform, client_id: client_id, lineitems: lineitems,
+        scopes: [PandaPal::LtiConstants::AgsScopes::SCORE])
+
+      expect { score_only.line_items }.to raise_error(described_class::NotGranted, /lineitem/)
+    end
+
+    it 'refuses when the launch carried no lineitems URL' do
+      expect(platform).not_to receive(:service_request)
+
+      no_container = described_class.new(platform: platform, client_id: client_id, scopes: scopes)
+
+      expect { no_container.line_items }.to raise_error(described_class::NotGranted, /lineitems URL/)
+    end
+  end
+
+  describe '#line_item' do
+    it 'gets the launch lineitem with the lineitem media type' do
+      expect_service_request(:get, lineitem, PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY,
+        http_response(200, { 'id' => lineitem, 'scoreMaximum' => 10 }.to_json),
+        headers: { 'Accept' => PandaPal::LtiConstants::AgsMediaTypes::LINEITEM })
+
+      expect(client.line_item).to eq('id' => lineitem, 'scoreMaximum' => 10)
+    end
+
+    it 'gets an explicit lineitem URL' do
+      other = "#{lineitems}/99"
+      expect_service_request(:get, other, PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY,
+        http_response(200, '{"id":"99"}'), headers: { 'Accept' => PandaPal::LtiConstants::AgsMediaTypes::LINEITEM })
+
+      expect(client.line_item(other)).to eq('id' => '99')
+    end
+
+    it 'raises RequestFailed when the body is not JSON' do
+      allow(platform).to receive(:service_request).and_return(http_response(200, '<html>'))
+
+      expect { client.line_item }.to raise_error(described_class::RequestFailed, /not JSON/)
+    end
+  end
+
+  describe '#results' do
+    let(:results_url) { "#{lineitem}/results" }
+    let(:container) { PandaPal::LtiConstants::AgsMediaTypes::RESULT_CONTAINER }
+    let(:result_scope) { PandaPal::LtiConstants::AgsScopes::RESULT_READONLY }
+
+    it 'reads the lineitem results with the result container media type' do
+      expect_service_request(:get, results_url, result_scope,
+        http_response(200, [{ 'userId' => user_id, 'resultScore' => 8 }].to_json), headers: { 'Accept' => container })
+
+      expect(client.results).to eq([{ 'userId' => user_id, 'resultScore' => 8 }])
+    end
+
+    it 'filters by user_id and limit, keeping an existing query string' do
+      with_query = described_class.new(platform: platform, client_id: client_id, scopes: scopes,
+        lineitem: "#{lineitem}?type_id=abc")
+      expect_service_request(:get, "#{results_url}?type_id=abc&user_id=#{user_id}&limit=5", result_scope,
+        http_response(200, '[]'), headers: { 'Accept' => container })
+
+      expect(with_query.results(user_id: user_id, limit: 5)).to eq([])
+    end
+
+    it 'refuses when the result scope was not granted' do
+      expect(platform).not_to receive(:service_request)
+
+      score_only = described_class.new(platform: platform, client_id: client_id, lineitem: lineitem,
+        scopes: [PandaPal::LtiConstants::AgsScopes::SCORE])
+
+      expect { score_only.results }.to raise_error(described_class::NotGranted, /result\.readonly/)
+    end
+  end
+
+  describe 'end to end through the platform token' do
+    let(:rsa_key) { OpenSSL::PKey::RSA.new(2048) }
+
+    before do
+      PandaPal.lti_private_key = rsa_key
+      PandaPal.jwk = nil
+      allow(Rails).to receive(:cache).and_return(ActiveSupport::Cache::MemoryStore.new)
+    end
+
+    after do
+      PandaPal.lti_private_key = nil
+      PandaPal.jwk = nil
+    end
+
+    it 'requests only the score scope and posts with the issued bearer token' do
+      expect(HTTParty).to receive(:post).with(platform.grant_url, hash_including(
+        body: hash_including(grant_type: 'client_credentials', scope: PandaPal::LtiConstants::AgsScopes::SCORE)
+      )).and_return(http_response(200, '{"access_token":"issued","expires_in":3600}'))
+      expect(HTTParty).to receive(:post).with("#{lineitem}/scores", hash_including(
+        headers: { 'Content-Type' => 'application/vnd.ims.lis.v1.score+json', 'Authorization' => 'Bearer issued' }
+      )).and_return(http_response(200, '{}'))
+
+      client.post_score(score_given: 1, score_maximum: 1)
+    end
+  end
+end

data/spec/models/panda_pal/platform_spec.rb

@@ -148,5 +148,202 @@ module PandaPal
         expect(restored.jwks_url).to eq(platform.jwks_url)
       end
     end
+    describe 'LTI Advantage service tokens' do
+      let(:rsa_key) { OpenSSL::PKey::RSA.new(2048) }
+      let(:platform) { Platform::Canvas.new(iss: 'https://canvas.instructure.com') }
+      let(:grant_url) { 'https://sso.canvaslms.com/login/oauth2/token' }
+      let(:client_id) { '10000000000042' }
+      let(:score_scope) { LtiConstants::AgsScopes::SCORE }
+      let(:cache) { ActiveSupport::Cache::MemoryStore.new }
+
+      before do
+        PandaPal.lti_private_key = rsa_key
+        PandaPal.jwk = nil
+        allow(Rails).to receive(:cache).and_return(cache)
+      end
+
+      after do
+        PandaPal.lti_private_key = nil
+        PandaPal.jwk = nil
+      end
+
+      def http_response(code, body = '', headers = {})
+        double('HTTParty::Response', code: code, success?: (200..299).cover?(code), body: body, headers: headers)
+      end
+
+      def token_response(token, expires_in: 3600)
+        http_response(200, { access_token: token, token_type: 'Bearer', expires_in: expires_in }.to_json)
+      end
+
+      describe '#service_access_token' do
+        it 'posts a client_credentials grant with an RS256 client assertion signed by the tool key' do
+          captured = nil
+          allow(HTTParty).to receive(:post) do |url, **options|
+            captured = { url: url, options: options }
+            token_response('service-token')
+          end
+
+          token = platform.service_access_token(client_id: client_id, scopes: [score_scope])
+
+          expect(token).to eq('service-token')
+          expect(captured[:url]).to eq(grant_url)
+
+          body = captured[:options][:body]
+          expect(body[:grant_type]).to eq('client_credentials')
+          expect(body[:client_assertion_type]).to eq('urn:ietf:params:oauth:client-assertion-type:jwt-bearer')
+          expect(body[:scope]).to eq(score_scope)
+
+          payload, header = JWT.decode(body[:client_assertion], rsa_key.public_key, true, algorithm: 'RS256')
+          expect(header['alg']).to eq('RS256')
+          expect(header['kid']).to eq(PandaPal.jwk.kid)
+          expect(payload['iss']).to eq(client_id)
+          expect(payload['sub']).to eq(client_id)
+          expect(payload['aud']).to eq(grant_url)
+          expect(payload['jti']).to be_present
+          expect(payload['exp'] - payload['iat']).to eq(300)
+          expect(payload['iat']).to be_within(5).of(Time.now.to_i)
+        end
+
+        it 'joins several scopes with spaces' do
+          expect(HTTParty).to receive(:post).with(grant_url, hash_including(
+            body: hash_including(scope: [LtiConstants::AgsScopes::LINEITEM_READONLY, score_scope].sort.join(' '))
+          )).and_return(token_response('service-token'))
+
+          platform.service_access_token(client_id: client_id, scopes: [score_scope, LtiConstants::AgsScopes::LINEITEM_READONLY])
+        end
+
+        it 'bounds the request with timeouts' do
+          expect(HTTParty).to receive(:post).with(grant_url, hash_including(open_timeout: 5, read_timeout: 15))
+            .and_return(token_response('service-token'))
+
+          platform.service_access_token(client_id: client_id, scopes: [score_scope])
+        end
+
+        it 'reuses the cached token for the same client and scopes' do
+          expect(HTTParty).to receive(:post).once.and_return(token_response('service-token'))
+
+          2.times { expect(platform.service_access_token(client_id: client_id, scopes: [score_scope])).to eq('service-token') }
+        end
+
+        it 'requests a separate token for a different scope set' do
+          expect(HTTParty).to receive(:post).twice.and_return(token_response('score-token'), token_response('lineitem-token'))
+
+          expect(platform.service_access_token(client_id: client_id, scopes: [score_scope])).to eq('score-token')
+          expect(platform.service_access_token(client_id: client_id, scopes: [LtiConstants::AgsScopes::LINEITEM])).to eq('lineitem-token')
+        end
+
+        it 'caches the token for its expires_in less a minute' do
+          allow(HTTParty).to receive(:post).and_return(token_response('service-token', expires_in: 600))
+          expect(cache).to receive(:write).with(kind_of(String), 'service-token', expires_in: 540.seconds).and_call_original
+
+          platform.service_access_token(client_id: client_id, scopes: [score_scope])
+        end
+
+        it 'does not cache the key under the token or the assertion' do
+          allow(HTTParty).to receive(:post).and_return(token_response('service-token'))
+          expect(cache).to receive(:write).with(%r{\Apanda_pal/lti_service_tokens/[0-9a-f]{64}\z}, anything, anything)
+
+          platform.service_access_token(client_id: client_id, scopes: [score_scope])
+        end
+
+        it 'fetches a new token when forced' do
+          expect(HTTParty).to receive(:post).twice.and_return(token_response('first'), token_response('second'))
+
+          platform.service_access_token(client_id: client_id, scopes: [score_scope])
+          expect(platform.service_access_token(client_id: client_id, scopes: [score_scope], force: true)).to eq('second')
+        end
+
+        it 'raises ServiceTokenError with the status, without echoing the response body, on a non-2xx answer' do
+          allow(HTTParty).to receive(:post).and_return(http_response(400, '{"error":"invalid_client","assertion":"secret-assertion"}'))
+
+          expect {
+            platform.service_access_token(client_id: client_id, scopes: [score_scope])
+          }.to raise_error(Platform::ServiceTokenError) { |error|
+            expect(error.status).to eq(400)
+            expect(error.message).to eq('token request answered 400')
+            expect(error).to be_a(PandaPal::LtiServiceError)
+          }
+        end
+
+        it 'raises ServiceTokenError when the response has no access_token' do
+          allow(HTTParty).to receive(:post).and_return(http_response(200, '{"token_type":"Bearer"}'))
+
+          expect {
+            platform.service_access_token(client_id: client_id, scopes: [score_scope])
+          }.to raise_error(Platform::ServiceTokenError, /no access_token/)
+        end
+
+        it 'wraps network errors in LtiServiceError' do
+          allow(HTTParty).to receive(:post).and_raise(Net::OpenTimeout)
+
+          expect {
+            platform.service_access_token(client_id: client_id, scopes: [score_scope])
+          }.to raise_error(PandaPal::LtiServiceError, 'token request failed: Net::OpenTimeout')
+        end
+
+        it 'uses the Generic platform grant_url' do
+          generic = Platform::Generic.from_urls('https://lms.example.com', grant: '/oauth/token')
+          expect(HTTParty).to receive(:post).with('https://lms.example.com/oauth/token', anything).and_return(token_response('generic-token'))
+
+          expect(generic.service_access_token(client_id: client_id, scopes: [score_scope])).to eq('generic-token')
+        end
+      end
+
+      describe '#expire_service_access_token' do
+        it 'drops the cached token so the next call requests a new one' do
+          expect(HTTParty).to receive(:post).twice.and_return(token_response('first'), token_response('second'))
+
+          platform.service_access_token(client_id: client_id, scopes: [score_scope])
+          platform.expire_service_access_token(client_id: client_id, scopes: [score_scope])
+
+          expect(platform.service_access_token(client_id: client_id, scopes: [score_scope])).to eq('second')
+        end
+      end
+
+      describe '#service_request' do
+        let(:url) { 'https://canvas.example.com/api/lti/courses/1/line_items/2/scores' }
+
+        it 'sends the bearer token with the given headers and body' do
+          allow(HTTParty).to receive(:post).with(grant_url, anything).and_return(token_response('service-token'))
+          expect(HTTParty).to receive(:post).with(url, hash_including(
+            headers: { 'Content-Type' => 'application/json', 'Authorization' => 'Bearer service-token' },
+            body: '{}',
+            open_timeout: 5,
+          )).and_return(http_response(200))
+
+          response = platform.service_request(:post, url, client_id: client_id, scopes: [score_scope],
+            headers: { 'Content-Type' => 'application/json' }, body: '{}')
+
+          expect(response.code).to eq(200)
+        end
+
+        it 'retries once with a new token when a cached token is refused with a 401' do
+          cache.write(platform.send(:service_token_cache_key, client_id, [score_scope]), 'stale-token')
+          expect(HTTParty).to receive(:post).with(grant_url, anything).once.and_return(token_response('fresh-token'))
+          expect(HTTParty).to receive(:post).with(url, hash_including(headers: { 'Authorization' => 'Bearer stale-token' })).and_return(http_response(401))
+          expect(HTTParty).to receive(:post).with(url, hash_including(headers: { 'Authorization' => 'Bearer fresh-token' })).and_return(http_response(200))
+
+          response = platform.service_request(:post, url, client_id: client_id, scopes: [score_scope])
+
+          expect(response.code).to eq(200)
+          expect(cache.read(platform.send(:service_token_cache_key, client_id, [score_scope]))).to eq('fresh-token')
+        end
+
+        it 'does not retry when a freshly issued token is refused' do
+          expect(HTTParty).to receive(:post).with(grant_url, anything).once.and_return(token_response('fresh-token'))
+          expect(HTTParty).to receive(:post).with(url, anything).once.and_return(http_response(401))
+
+          expect(platform.service_request(:post, url, client_id: client_id, scopes: [score_scope]).code).to eq(401)
+        end
+
+        it 'returns the second 401 when the refreshed token is refused too' do
+          cache.write(platform.send(:service_token_cache_key, client_id, [score_scope]), 'stale-token')
+          allow(HTTParty).to receive(:post).with(grant_url, anything).and_return(token_response('fresh-token'))
+          expect(HTTParty).to receive(:post).with(url, anything).twice.and_return(http_response(401))
+
+          expect(platform.service_request(:post, url, client_id: client_id, scopes: [score_scope]).code).to eq(401)
+        end
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: panda_pal
 version: !ruby/object:Gem::Version
-  version: 5.17.2
+  version: 5.18.0
 platform: ruby
 authors:
 - Instructure CustomDev
@@ -133,6 +133,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGS.md
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -151,6 +152,8 @@ 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/ags_client.rb
+- app/lib/panda_pal/ags_helpers.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
@@ -209,6 +212,7 @@ files:
 - spec/internal/config/storage.yml
 - spec/internal/db/schema.rb
 - spec/jobs/panda_pal/jobs/grade_passback_job_spec.rb
+- spec/lib/panda_pal/ags_client_spec.rb
 - spec/lib/panda_pal/helpers/secure_headers_spec.rb
 - spec/lib/panda_pal/helpers/session_replacement_spec.rb
 - spec/models/panda_pal/api_call_spec.rb
@@ -254,6 +258,7 @@ test_files:
 - spec/internal/config/storage.yml
 - spec/internal/db/schema.rb
 - spec/jobs/panda_pal/jobs/grade_passback_job_spec.rb
+- spec/lib/panda_pal/ags_client_spec.rb
 - spec/lib/panda_pal/helpers/secure_headers_spec.rb
 - spec/lib/panda_pal/helpers/session_replacement_spec.rb
 - spec/models/panda_pal/api_call_spec.rb