panda_pal 5.17.2 → 5.18.1

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.1
 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