atomic_lti 1.1.0

data/app/lib/atomic_lti/definitions.rb

@@ -0,0 +1,169 @@
+module AtomicLti
+  class Definitions
+    LTI_VERSION = "https://purl.imsglobal.org/spec/lti/claim/version".freeze
+    LAUNCH_PRESENTATION = "https://purl.imsglobal.org/spec/lti/claim/launch_presentation".freeze
+    DEPLOYMENT_ID = "https://purl.imsglobal.org/spec/lti/claim/deployment_id".freeze
+    MESSAGE_TYPE = "https://purl.imsglobal.org/spec/lti/claim/message_type".freeze
+
+    # Claims
+    CONTEXT_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/context".freeze
+    RESOURCE_LINK_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/resource_link".freeze
+    TOOL_PLATFORM_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/tool_platform".freeze
+    AGS_CLAIM = "https://purl.imsglobal.org/spec/lti-ags/claim/endpoint".freeze
+    BASIC_OUTCOME_CLAIM = "https://purl.imsglobal.org/spec/lti-bo/claim/basicoutcome".freeze
+
+    MENTOR_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/role_scope_mentor".freeze
+    ROLES_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/roles".freeze
+
+    CUSTOM_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/custom".freeze
+    EXTENSION_CLAIM = "http://www.ExamplePlatformVendor.com/session".freeze
+
+    LIS_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/lis".freeze
+    TARGET_LINK_URI_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/target_link_uri".freeze
+    LTI11_LEGACY_USER_ID_CLAIM = "https://purl.imsglobal.org/spec/lti/claim/lti11_legacy_user_id".freeze
+    DEEP_LINKING_CLAIM = "https://purl.imsglobal.org/spec/lti-dl/claim/deep_linking_settings".freeze
+    DEEP_LINKING_DATA_CLAIM = "https://purl.imsglobal.org/spec/lti-dl/claim/data".freeze
+    DEEP_LINKING_TOOL_MSG_CLAIM = "https://purl.imsglobal.org/spec/lti-dl/claim/msg".freeze
+    DEEP_LINKING_TOOL_LOG_CLAIM = "https://purl.imsglobal.org/spec/lti-dl/claim/log".freeze
+    CONTENT_ITEM_CLAIM = "https://purl.imsglobal.org/spec/lti-dl/claim/content_items".freeze
+    NAMES_AND_ROLES_CLAIM = "https://purl.imsglobal.org/spec/lti-nrps/claim/namesroleservice".freeze
+
+    NAMES_AND_ROLES_SERVICE_VERSIONS = ["2.0"].freeze
+
+    CALIPER_CLAIM = "https://purl.imsglobal.org/spec/lti-ces/claim/caliper-endpoint-service".freeze
+
+    TOOL_LAUNCH_CALIPER_CONTEXT = "http://purl.imsglobal.org/ctx/caliper/v1p1/ToolLaunchProfile-extension".freeze
+    TOOL_USE_CALIPER_CONTEXT = "http://purl.imsglobal.org/ctx/caliper/v1p1".freeze
+
+    # Scopes
+    AGS_SCOPE_LINE_ITEM = "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem".freeze
+    AGS_SCOPE_LINE_ITEM_READONLY = "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly".freeze
+    AGS_SCOPE_RESULT = "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly".freeze
+    AGS_SCOPE_SCORE = "https://purl.imsglobal.org/spec/lti-ags/scope/score".freeze
+    NAMES_AND_ROLES_SCOPE = "https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly".freeze
+    CALIPER_SCOPE = "https://purl.imsglobal.org/spec/lti-ces/v1p0/scope/send".freeze
+
+    STUDENT_SCOPE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Student".freeze
+    INSTRUCTOR_SCOPE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Instructor".freeze
+    LEARNER_SCOPE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Learner".freeze
+    MENTOR_SCOPE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Mentor".freeze
+    MENTOR_ROLE_SCOPE = "a62c52c02ba262003f5e".freeze
+
+    # Launch contexts
+    COURSE_CONTEXT = "http://purl.imsglobal.org/vocab/lis/v2/course#CourseOffering".freeze
+    ACCOUNT_CONTEXT = "Account".freeze
+
+    # Configuration
+    TOOL_CONFIGURATION = "https://purl.imsglobal.org/spec/lti-tool-configuration".freeze
+
+    # Specfies all available scopes.
+    def self.scopes
+      [
+        AGS_SCOPE_LINE_ITEM,
+        AGS_SCOPE_LINE_ITEM_READONLY,
+        AGS_SCOPE_RESULT,
+        AGS_SCOPE_SCORE,
+        NAMES_AND_ROLES_SCOPE,
+      ]
+    end
+
+    CANVAS_PUBLIC_LTI_KEYS_URL = "https://canvas.instructure.com/api/lti/security/jwks".freeze
+    CANVAS_OIDC_URL = "https://canvas.instructure.com/api/lti/authorize_redirect".freeze
+    CANVAS_AUTH_TOKEN_URL = "https://canvas.instructure.com/login/oauth2/token".freeze
+
+    CANVAS_BETA_PUBLIC_LTI_KEYS_URL = "https://canvas.beta.instructure.com/api/lti/security/jwks".freeze
+    CANVAS_BETA_AUTH_TOKEN_URL = "https://canvas.beta.instructure.com/login/oauth2/token".freeze
+    CANVAS_BETA_OIDC_URL = "https://canvas.beta.instructure.com/api/lti/authorize_redirect".freeze
+
+    CANVAS_SUBMISSION_TYPE = "https://canvas.instructure.com/lti/submission_type".freeze
+
+    # Roles
+    # Below are all the roles specified in the LTI 1.3 spec. (https://www.imsglobal.org/spec/lti/v1p3#role-vocabularies-0)
+    ## Core system roles
+    ADMINISTRATOR_SYSTEM_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/system/person#Administrator".freeze
+    NONE_SYSTEM_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/system/person#None".freeze
+    ## Non‑core system roles
+    ACCOUNT_ADMIN_SYSTEM_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/system/person#AccountAdmin".freeze
+    CREATOR_SYSTEM_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/system/person#Creator".freeze
+    SYS_ADMIN_SYSTEM_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/system/person#SysAdmin".freeze
+    SYS_SUPPORT_SYSTEM_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/system/person#SysSupport".freeze
+    USER_SYSTEM_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/system/person#User".freeze
+    ## Core institution roles
+    ADMINISTRATOR_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Administrator".freeze
+    FACULTY_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Faculty".freeze
+    GUEST_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Guest".freeze
+    NONE_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#None".freeze
+    OTHER_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Other".freeze
+    STAFF_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Staff".freeze
+    STUDENT_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Student".freeze
+    ## Non‑core institution roles
+    ALUMNI_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Alumni".freeze
+    INSTRUCTOR_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Instructor".freeze
+    LEARNER_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Learner".freeze
+    MEMBER_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Member".freeze
+    MENTOR_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Mentor".freeze
+    OBSERVER_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Observer".freeze
+    PROSPECTIVE_STUDENT_INSTITUTION_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/institution/person#ProspectiveStudent".freeze
+    ## Core context roles
+    ADMINISTRATOR_CONTEXT_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Administrator".freeze
+    CONTENT_DEVELOPER_CONTEXT_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/membership#ContentDeveloper".freeze
+    INSTRUCTOR_CONTEXT_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor".freeze
+    LEARNER_CONTEXT_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Learner".freeze
+    MENTOR_CONTEXT_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Mentor".freeze
+    ## Non‑core context roles
+    MANAGER_CONTEXT_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Manager".freeze
+    MEMBER_CONTEXT_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Member".freeze
+    OFFICER_CONTEXT_ROLE = "http://purl.imsglobal.org/vocab/lis/v2/membership#Officer".freeze
+
+    ADMINISTRATOR_ROLES = [
+      ADMINISTRATOR_SYSTEM_ROLE,
+      ACCOUNT_ADMIN_SYSTEM_ROLE,
+      ADMINISTRATOR_INSTITUTION_ROLE,
+      ADMINISTRATOR_CONTEXT_ROLE,
+    ].freeze
+
+    INSTRUCTOR_ROLES = [
+      INSTRUCTOR_INSTITUTION_ROLE,
+      INSTRUCTOR_CONTEXT_ROLE,
+    ].freeze
+
+    STUDENT_ROLES = [
+      STUDENT_INSTITUTION_ROLE,
+      LEARNER_CONTEXT_ROLE,
+    ].freeze
+
+    OBSERVER_ROLES = [
+      MENTOR_INSTITUTION_ROLE,
+      #NON_CREDIT_LEARNER,
+    ].freeze
+
+    def self.lms_host(payload)
+      host = if deep_link_launch?(payload)
+               payload.dig(AtomicLti::Definitions::DEEP_LINKING_CLAIM, "deep_link_return_url")
+             else
+               payload.dig(AtomicLti::Definitions::LAUNCH_PRESENTATION, "return_url")
+             end
+      UrlHelper.safe_host(host)
+    end
+
+    def self.lms_url(payload)
+      "https://#{lms_host(payload)}"
+    end
+
+    def self.deep_link_launch?(payload)
+      payload[AtomicLti::Definitions::MESSAGE_TYPE] == "LtiDeepLinkingRequest"
+    end
+
+    def self.names_and_roles_launch?(payload)
+      return false unless payload[AtomicLti::Definitions::NAMES_AND_ROLES_CLAIM]
+
+      payload[AtomicLti::Definitions::NAMES_AND_ROLES_CLAIM]["service_versions"] ==
+        AtomicLti::Definitions::NAMES_AND_ROLES_SERVICE_VERSIONS
+    end
+
+    def self.assignment_and_grades_launch?(payload)
+      payload[AtomicLti::Definitions::AGS_CLAIM]
+    end
+
+  end
+end

data/app/lib/atomic_lti/exceptions.rb

@@ -0,0 +1,87 @@
+module AtomicLti
+  module Exceptions
+
+    # General exceptions
+    class AtomicLtiException < StandardError
+    end
+
+    class LineItemError < AtomicLtiException
+    end
+
+    class ConfigurationError < AtomicLtiException
+    end
+
+    class NamesAndRolesError < AtomicLtiException
+    end
+
+    class ScoreError < AtomicLtiException
+    end
+
+    class StateError < AtomicLtiException
+    end
+
+    class OpenIDStateError < AtomicLtiException
+    end
+
+    class OpenIDRedirectError < AtomicLtiException
+    end
+
+    class JwtIssueError < AtomicLtiException
+    end
+
+    class LineItemMissing < LineItemError
+    end
+
+    class RateLimitError < AtomicLtiException
+    end
+
+    class InvalidLTIVersion < AtomicLtiException
+      def initialize(msg="Invalid LTI version")
+        super(msg)
+      end
+    end
+
+    class NoLTIVersion < AtomicLtiException
+      def initialize(msg="No LTI Version provided")
+        super(msg)
+      end
+    end
+
+    class NoLTIToken < AtomicLtiException
+      def initialize(msg="No LTI token provided")
+        super(msg)
+      end
+    end
+
+    class InvalidLTIToken < AtomicLtiException
+      def initialize(msg="Invalid LTI token provided")
+        super(msg)
+      end
+    end
+
+    # Not found exceptions
+    class AtomicLtiNotFoundException < StandardError
+    end
+
+    class NoLTIDeployment < AtomicLtiNotFoundException
+      def initialize(iss:, deployment_id:)
+        msg="No LTI Deployment found for iss: #{iss} and deployment_id #{deployment_id}"
+        super(msg)
+      end
+    end
+
+    class NoLTIInstall < AtomicLtiNotFoundException
+      def initialize(iss:, deployment_id:)
+        msg="No LTI Install found for iss: #{iss} and deployment_id #{deployment_id}"
+        super(msg)
+      end
+    end
+
+    class NoLTIPlatform < AtomicLtiNotFoundException
+      def initialize(iss:, deployment_id:)
+        msg="No LTI Platform associated with the LTI Install. iss: #{iss} and deployment_id #{deployment_id}"
+        super(msg)
+      end
+    end
+  end
+end

data/app/lib/atomic_lti/lti.rb

@@ -0,0 +1,94 @@
+module AtomicLti
+  class Lti
+
+    def self.validate!(decoded_token, requested_target_link_uri = nil, validate_target_link_url = false)
+      if decoded_token.blank?
+        raise AtomicLti::Exceptions::InvalidLTIToken
+      end
+
+      errors = []
+
+      if decoded_token["iss"].blank?
+        errors.push("LTI token is missing required field iss")
+      end
+
+      if decoded_token["sub"].blank?
+        errors.push("LTI token is missing required field sub")
+      end
+
+      if decoded_token[AtomicLti::Definitions::DEPLOYMENT_ID].blank?
+        errors.push(
+          "LTI token is missing required field #{AtomicLti::Definitions::DEPLOYMENT_ID}"
+        )
+      end
+
+      if decoded_token[AtomicLti::Definitions::MESSAGE_TYPE].blank?
+        errors.push(
+          "LTI token is missing required claim #{AtomicLti::Definitions::MESSAGE_TYPE}"
+        )
+      end
+
+      if decoded_token[AtomicLti::Definitions::MESSAGE_TYPE] === "LtiResourceLinkRequest"
+        errors.concat(validate_resource_link_request(decoded_token, requested_target_link_uri, validate_target_link_url))
+      end
+
+      if decoded_token[AtomicLti::Definitions::ROLES_CLAIM].blank?
+        errors.push(
+          "LTI token is missing required claim #{AtomicLti::Definitions::ROLES_CLAIM}"
+        )
+      end
+
+      if errors.length > 0
+        raise AtomicLti::Exceptions::InvalidLTIToken.new(errors.join(" "))
+      end
+
+      if decoded_token[AtomicLti::Definitions::LTI_VERSION].blank?
+        raise AtomicLti::Exceptions::NoLTIVersion
+      end
+
+      raise AtomicLti::Exceptions::InvalidLTIVersion unless valid_version?(decoded_token)
+
+      true
+    end
+
+    def self.validate_resource_link_request(decoded_token, requested_target_link_uri = nil, validate_target_link_url = false)
+      errors = []
+
+      if decoded_token[AtomicLti::Definitions::TARGET_LINK_URI_CLAIM].blank?
+        errors.push(
+          "LTI token is missing required claim #{AtomicLti::Definitions::TARGET_LINK_URI_CLAIM}"
+        )
+      end
+
+      # Validate that we are at the target_link_uri
+      target_link_uri = decoded_token[AtomicLti::Definitions::TARGET_LINK_URI_CLAIM]
+      if validate_target_link_url && target_link_uri != requested_target_link_uri
+        errors.push(
+          "LTI token target link uri '#{target_link_uri}' doesn't match url '#{requested_target_link_uri}'"
+        )
+      end
+
+      if decoded_token[AtomicLti::Definitions::RESOURCE_LINK_CLAIM].blank?
+        errors.push(
+          "LTI token is missing required claim #{AtomicLti::Definitions::RESOURCE_LINK_CLAIM}"
+        )
+      end
+
+      if decoded_token.dig(AtomicLti::Definitions::RESOURCE_LINK_CLAIM, "id").blank?
+        errors.push(
+          "LTI token is missing required field id from the claim #{AtomicLti::Definitions::RESOURCE_LINK_CLAIM}"
+        )
+      end
+
+      errors
+    end
+
+    def self.valid_version?(decoded_token)
+      if decoded_token[AtomicLti::Definitions::LTI_VERSION]
+        decoded_token[AtomicLti::Definitions::LTI_VERSION].starts_with?("1.3")
+      else
+        false
+      end
+    end
+  end
+end

data/app/lib/atomic_lti/open_id.rb

@@ -0,0 +1,22 @@
+module AtomicLti
+  class OpenId
+    def self.validate_open_id_state(state)
+      state = AtomicLti::AuthToken.decode(state)[0]
+      if open_id_state = AtomicLti::OpenIdState.find_by(nonce: state["nonce"])
+        open_id_state.destroy
+        true
+      else
+        false
+      end
+    rescue StandardError => e
+      Rails.logger.info("Error decoding token: #{e} - #{e.backtrace}")
+      false
+    end
+
+    def self.state
+      nonce = SecureRandom.hex(64)
+      AtomicLti::OpenIdState.create!(nonce: nonce)
+      AtomicLti::AuthToken.issue_token({ nonce: nonce })
+    end
+  end
+end

data/app/lib/atomic_lti/params.rb

@@ -0,0 +1,135 @@
+module AtomicLti
+  # This is for extracting data from the lti jwt in more human-readable ways
+  class Params
+    attr_reader :token
+
+    def initialize(lti_token)
+      @token = lti_token.with_indifferent_access
+    end
+
+    def lti_advantage?
+      true
+    end
+
+    def deployment_id
+      token[AtomicLti::Definitions::DEPLOYMENT_ID]
+    end
+
+    def iss
+      token[:iss]
+    end
+
+    def version
+      token[AtomicLti::Definitions::LTI_VERSION]
+    end
+
+    def client_id
+      token[:aud]
+    end
+
+    def context_data
+      token[AtomicLti::Definitions::CONTEXT_CLAIM] || {}
+    end
+
+    def launch_context
+      # This is an array, I'm not sure what it means to have more than one
+      # value. In courses and accounts there's only one value
+      contexts = context_data[:type] || []
+      if contexts.include? AtomicLti::Definitions::COURSE_CONTEXT
+        "COURSE"
+      elsif contexts.include? AtomicLti::Definitions::ACCOUNT_CONTEXT
+        "ACCOUNT"
+      else
+        "UNKNOWN"
+      end
+    end
+
+    def context_id
+      context_data[:id]
+    end
+
+    def resource_link_data
+      token[AtomicLti::Definitions::RESOURCE_LINK_CLAIM] || {}
+    end
+
+    def resource_link_title
+      resource_link_data[:title]
+    end
+
+    def lis_data
+      token[AtomicLti::Definitions::LIS_CLAIM] || {}
+    end
+
+    def tool_platform_data
+      token[AtomicLti::Definitions::TOOL_PLATFORM_CLAIM] || {}
+    end
+
+    def product_family_code
+      tool_platform_data[:product_family_code]
+    end
+
+    def tool_consumer_instance_guid
+      tool_platform_data[:guid]
+    end
+
+    def tool_consumer_instance_name
+      tool_platform_data[:name]
+    end
+
+    def launch_presentation_data
+      token[AtomicLti::Definitions::LAUNCH_PRESENTATION] || {}
+    end
+
+    def launch_locale
+      launch_presentation_data[:locale]
+    end
+
+    def ags_data
+      token[AtomicLti::Definitions::AGS_CLAIM] || {}
+    end
+
+    def deep_linking_data
+      token[AtomicLti::Definitions::DEEP_LINKING_DATA_CLAIM] || {}
+    end
+
+    def deep_linking_claim
+      token[AtomicLti::Definitions::DEEP_LINKING_CLAIM]
+    end
+
+    def message_type
+      token[AtomicLti::Definitions::MESSAGE_TYPE]
+    end
+
+    def is_deep_link
+      AtomicLti::Definitions.deep_link_launch?(token)
+    end
+
+    # This extracts the custom parameters from the jwt token from the lti launch
+    # These values must be added to the developer key under "Custom Fields"
+    # for example: canvas_course_id=$Canvas.course.id
+    def custom_data
+      token[AtomicLti::Definitions::CUSTOM_CLAIM]&.reject { |_, s| s.to_s.start_with?("$Canvas") } || {}
+    end
+
+    def canvas_course_id
+      custom_data[:canvas_course_id]
+    end
+
+    def canvas_section_ids
+      custom_data[:canvas_section_ids]
+    end
+
+    def canvas_account_id
+      custom_data[:canvas_account_id]
+    end
+
+    def canvas_course_name
+      custom_data[:canvas_course_name]
+    end
+
+    def canvas_assignment_id
+      custom_data[:canvas_assignment_id]
+    end
+
+  end
+end

data/app/lib/atomic_lti/services/base.rb

@@ -0,0 +1,38 @@
+module AtomicLti
+  module Services
+    class Base
+
+      def initialize(lti_token: nil, iss: nil, deployment_id: nil)
+
+        token_iss = nil
+        token_deployment_id = nil
+
+        if lti_token.present?
+          token_iss = lti_token.dig('iss')
+          token_deployment_id = lti_token.dig(AtomicLti::Definitions::DEPLOYMENT_ID)
+        end
+
+        @lti_token = lti_token
+        @iss = iss || token_iss
+        @deployment_id = deployment_id || token_deployment_id
+      end
+
+      def headers(options = {})
+        @token ||= AtomicLti::Authorization.request_token(iss: @iss, deployment_id: @deployment_id)
+        {
+          "Authorization" => "Bearer #{@token['access_token']}",
+        }.merge(options)
+      end
+
+      def get_next_url(response)
+        link = response.headers["link"]
+        return nil if link.blank?
+
+        if url = link.split(",").detect { |l| l.split(";")[1].strip == 'rel="next"' }
+          url.split(";")[0].gsub(/[\<\>\s]/, "")
+        end
+      end
+
+    end
+  end
+end

data/app/lib/atomic_lti/services/line_items.rb

@@ -0,0 +1,90 @@
+module AtomicLti
+  module Services
+    # Canvas API docs https://canvas.instructure.com/doc/api/line_items.html
+    class LineItems < AtomicLti::Services::Base
+
+      def endpoint(lti_token)
+        url = lti_token.dig(AtomicLti::Definitions::AGS_CLAIM, "lineitems")
+        raise AtomicLti::Exceptions::LineItemError, "Unable to access line items" unless url.present?
+        url
+      end
+
+      # Helper method to generate a default set of attributes
+      def self.generate(
+        label:,
+        max_score:,
+        start_date_time: nil,
+        end_date_time: nil,
+        resource_id: nil,
+        tag: nil,
+        resource_link_id: nil,
+        external_tool_url: nil
+      )
+        attrs = {
+          scoreMaximum: max_score,
+          label: label,
+          resourceId: resource_id,
+          tag: tag,
+          startDateTime: start_date_time,
+          endDateTime: end_date_time,
+        }
+        attrs["resourceLinkId"] = resource_link_id if resource_link_id
+        if external_tool_url
+          attrs[AtomicLti::Definitions::CANVAS_SUBMISSION_TYPE] = {
+            type: "external_tool",
+            external_tool_url: external_tool_url,
+          }
+        end
+        attrs
+      end
+
+      def generate(attrs)
+        self.class.generate(**attrs)
+      end
+
+      def self.can_manage_line_items?(lti_token)
+        lti_token.dig(AtomicLti::Definitions::AGS_CLAIM, "scope")&.
+          include?(AtomicLti::Definitions::AGS_SCOPE_LINE_ITEM)
+      end
+
+      def self.can_query_line_items?(lti_token)
+        can_manage_line_items?(lti_token) ||
+          lti_token.dig(AtomicLti::Definitions::AGS_CLAIM, "scope").
+            include?(AtomicLti::Definitions::AGS_SCOPE_LINE_ITEM_READONLY)
+      end
+
+      # List line items
+      # Canvas: https://canvas.beta.instructure.com/doc/api/line_items.html#method.lti/ims/line_items.index
+      def list(query = {})
+        accept = { "Accept" => "application/vnd.ims.lis.v2.lineitemcontainer+json" }
+        HTTParty.get(endpoint(@lti_token), headers: headers(accept), query: query)
+      end
+
+      # Get a specific line item
+      # https://canvas.beta.instructure.com/doc/api/line_items.html#method.lti/ims/line_items.show
+      def show(line_item_url)
+        accept = { "Accept" => "application/vnd.ims.lis.v2.lineitem+json" }
+        HTTParty.get(line_item_url, headers: headers(accept))
+      end
+
+      # Create a line item
+      # https://www.imsglobal.org/spec/lti-ags/v2p0/#creating-a-new-line-item
+      # Canvas: https://canvas.beta.instructure.com/doc/api/line_items.html#method.lti/ims/line_items.create
+      def create(attrs = nil)
+        content_type = { "Content-Type" => "application/vnd.ims.lis.v2.lineitem+json" }
+        HTTParty.post(endpoint(@lti_token), body: JSON.dump(attrs), headers: headers(content_type))
+      end
+
+      # Update a line item
+      # Canvas: https://canvas.beta.instructure.com/doc/api/line_items.html#method.lti/ims/line_items.update
+      def update(line_item_url, attrs)
+        content_type = { "Content-Type" => "application/vnd.ims.lis.v2.lineitem+json" }
+        HTTParty.put(line_item_url, body: JSON.dump(attrs), headers: headers(content_type))
+      end
+
+      def delete(line_item_url)
+        HTTParty.delete(line_item_url, headers: headers)
+      end
+    end
+  end
+end