class WarpEngine::DeviceGrantService

The device authorization flow: a client asks for a grant, the user approves its code in the browser, and the client polls until it receives a catalog WarpEngine::ApplicationToken. Every step but revoke and verification_url needs the identity integration (WarpEngine.identity_configured?).

Public Instance Methods

approve (user_code:, subject:)

Source

# File app/services/warp_engine/device_grant_service.rb, line 46
def approve(user_code:, subject:)
  ensure_configured!

  grant = WarpEngine::DeviceGrant.find_pending_by_user_code(user_code)
  raise UnknownCode if grant.nil?

  ActiveRecord::Base.transaction do
    token = WarpEngine::ApplicationToken.create!(
      name: grant.client_name.presence || "Client",
      owner_type: WarpEngine.config.access_token_owner_class,
      owner_id: subject.id,
      scopes: [ WarpEngine::ApplicationToken::CATALOG_SCOPE ]
    )
    grant.update!(
      subject_type: WarpEngine.config.access_token_owner_class,
      subject_id: subject.id,
      application_token: token,
      issued_token: token.plain_token,
      approved_at: Time.current
    )
  end

  grant
end

Approves the pending grant user_code for subject (an instance of WarpEngine.config.access_token_owner_class): in one transaction it creates a catalog-scoped WarpEngine::ApplicationToken owned by the subject, named after the client, and stores it on the grant for the next poll. Returns the grant. Raises UnknownCode and NotConfigured.

deny (user_code:)

Source

# File app/services/warp_engine/device_grant_service.rb, line 73
def deny(user_code:)
  ensure_configured!

  grant = WarpEngine::DeviceGrant.find_pending_by_user_code(user_code)
  raise UnknownCode if grant.nil?

  grant.update!(denied_at: Time.current)
  grant
end

Marks the pending grant user_code denied. Returns the grant. Raises UnknownCode and NotConfigured.

poll (device_code:)

Source

# File app/services/warp_engine/device_grant_service.rb, line 28
def poll(device_code:)
  ensure_configured!

  grant = WarpEngine::DeviceGrant.find_by(device_code: device_code.to_s)
  raise UnknownCode if grant.nil?

  return [ grant.state, nil ] unless grant.state == :approved

  plain = grant.issued_token
  grant.update_columns(issued_token: nil) if plain.present?
  [ :approved, plain ]
end

Reports the state of the grant device_code.

Returns [state, nil] while the grant is :pending, :denied or :expired, and [:approved, token] once approved. The plain token is handed out once: it is cleared from the grant on this call, so later polls return [:approved, nil]. Raises UnknownCode and NotConfigured.

request (client_name:)

Source

# File app/services/warp_engine/device_grant_service.rb, line 15
def request(client_name:)
  ensure_configured!

  WarpEngine::DeviceGrant.create!(client_name: client_name.presence&.truncate(128))
end

Creates a pending WarpEngine::DeviceGrant for the client client_name (truncated to 128 characters, blank allowed). Returns the grant. Raises NotConfigured.

revoke (token:)

Source

# File app/services/warp_engine/device_grant_service.rb, line 85
def revoke(token:)
  return false if token.nil?

  token.revoke!
  true
end

Revokes (soft-deletes) the WarpEngine::ApplicationToken token. Returns false when token is nil, true otherwise.

verification_url (base_url: nil)

Source

# File app/services/warp_engine/device_grant_service.rb, line 95
def verification_url(base_url: nil)
  configured = WarpEngine.config.identity_verification_url.presence || "/devices"
  return configured if configured.start_with?("http://", "https://")
  return configured if base_url.blank?

  "#{base_url.to_s.chomp('/')}/#{configured.delete_prefix('/')}"
end

The URL where the user approves a code: WarpEngine.config.identity_verification_url, or /devices by default. A relative path is joined to base_url when one is given.