rito 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b88f9486b198ec08703fb9124aaea6d20d8c7313488d61d06541d289b7caf8b
-  data.tar.gz: a5acab9fe9d2cd25ca2e1a64e674d3ffc61e7ce3ae46896e4947a8dc93c267a3
+  metadata.gz: 690356f1167c30f7662373519e4806837f61a9c63f9b5ebde867bd98d435176d
+  data.tar.gz: 9aabb8d8a1b21d828e37594b174d938898281e056994e384da1f0261bbb69d5d
 SHA512:
-  metadata.gz: 381057a97d7fd77f04f13cfcaa8e394d472dd1dbe4bafb7aef1ad8c696a681587c4ced5db2e93a1d1d120ca76ca7e603d7be701954e91b650f04a7d83d7d28c9
-  data.tar.gz: 783a2bdf9c817180d9caa160ec9429af4cf34a3df15b69382c5c653dc49cb5a1c909b87ef58277233c8990cfdfc588259892f8b776bc24ea11e22e64fe0ff55c
+  metadata.gz: 91ed7d221b18a711a3f4370fec9c65d6092c01048a202750c6108dadfcbb4baa2c83f58fbbe658bcdd6bd8c87380f8f54904abaca5ff62e7bc5470064658ee38
+  data.tar.gz: 5aac876d18b27fb577889e7218689c179bc04d5fcff5c0bb657d42292f0a7b9f88900e00e8613bd3b38013d1ebb1f7a664e4cdd9e372f8cac54b10742c68e166

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.0 (2026-09-05)
+
+- **Riot Sign On (RSO)**: new `Rito::RSO` module implementing the OAuth2
+  authorization code flow against `auth.riotgames.com`:
+  `authorization_url` (with generated CSRF state), `exchange_code`,
+  `refresh`, `userinfo`, and `verify_id_token` (RS256 signature +
+  iss/aud/exp validation via `/jwks.json`, with key-rotation-aware
+  refetch). Token requests support `client_secret` basic, a static
+  `client_assertion` (the RSO "100 year token"), or minted private-key
+  JWT client assertions from an RSA `private_key`. Zero new runtime
+  dependencies (stdlib `openssl`).
+
 ## 0.1.3 (2026-09-05)
 
 - CI: publish via `rubygems/release-gem` so releases carry a Sigstore

data/README.md

@@ -44,6 +44,81 @@ Rito.rate_limiter   # rate limit strategy (default: AdaptiveLimiter)
 client = Rito::Client.new(api_key: "RGAPI-...", region: :kr)
 ```
 
+## Riot Sign On (RSO)
+
+`Rito::RSO` implements the OAuth2 authorization code flow against
+`https://auth.riotgames.com`. Register a client with Riot first; the
+redirect URI must be on its allowlist.
+
+```ruby
+rso = Rito::RSO::Client.new(
+  client_id: ENV.fetch("RIOT_RSO_CLIENT_ID"),
+  client_secret: ENV.fetch("RIOT_RSO_CLIENT_SECRET"), # or client_assertion: / private_key:
+  redirect_uri: "https://app.example.com/oauth2-callback"
+)
+
+# 1. Send the player to Riot; persist request.state to compare on callback
+login = rso.authorization_url(login_hint: "na1|daguava")
+login.url     # => "https://auth.riotgames.com/authorize?..."
+login.state
+
+# 2. Exchange the ?code= query param from the callback for tokens
+tokens = rso.exchange_code(params[:code])
+tokens.access_token   # Bearer token for RSO resources (encrypted, opaque)
+tokens.id_token       # signed JWT identity token
+tokens.refresh_token  # signed JWT, self-contained
+tokens.expires_in     # 600
+
+# 3. Identify the player
+me = rso.userinfo(tokens.access_token)
+me.sub    # player sub claim
+me.cpid   # "NA1" when the cpid scope was requested
+
+# 4. Rotate when the access token expires
+tokens = rso.refresh(tokens.refresh_token)
+```
+
+Newer RSO clients authenticate with private-key JWT instead of a secret
+(the gem mints a fresh signed assertion per token request):
+
+```ruby
+rso = Rito::RSO::Client.new(
+  client_id: ENV.fetch("RIOT_RSO_CLIENT_ID"),
+  private_key: OpenSSL::PKey::RSA.new(ENV.fetch("RIOT_RSO_PRIVATE_KEY")),
+  redirect_uri: "https://app.example.com/oauth2-callback"
+)
+```
+
+or pass the pre-signed client assertion (the "100 year token") via
+`client_assertion:` and treat it like a password.
+
+### Verifying the ID token
+
+```ruby
+claims = rso.verify_id_token(tokens.id_token)
+claims["sub"] # => signature (RS256 via /jwks.json) + iss/aud/exp validated
+```
+
+`verify_id_token` caches the JWKS document and refetches it once when a
+`kid` is unknown (Riot rotates keypairs without disabling old ones).
+Any failure raises `Rito::RSO::InvalidToken`. Token and userinfo failures
+raise `Rito::RSO::OAuthError` with `.error_code` / `.error_description`.
+
+### RSO configuration
+
+```ruby
+Rito::RSO.client_id        # default: ENV["RIOT_RSO_CLIENT_ID"]
+Rito::RSO.client_secret    # default: ENV["RIOT_RSO_CLIENT_SECRET"]
+Rito::RSO.client_assertion # default: ENV["RIOT_RSO_CLIENT_ASSERTION"]
+Rito::RSO.private_key
+Rito::RSO.redirect_uri     # default: ENV["RIOT_RSO_REDIRECT_URI"]
+Rito::RSO.scope            # default: "openid" (add cpid / offline_access)
+```
+
+Per-instance kwargs override the module config. Token requests are never
+retried (authorization codes and refresh tokens are one-time), so handle
+failures explicitly.
+
 ## Routing values
 
 Endpoints declare whether they are platform-routed (`na1`, `kr`, ...) or

data/lib/rito/rso/client.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Rito
+  module RSO
+    class Client
+      attr_reader :provider, :client_id, :redirect_uri, :scope,
+                  :open_timeout, :timeout, :adapter
+
+      def initialize(provider: nil, client_id: nil, client_secret: nil, client_assertion: nil,
+                     private_key: nil, redirect_uri: nil, scope: nil,
+                     open_timeout: nil, timeout: nil, adapter: nil)
+        @provider = (provider || RSO.provider).delete_suffix('/')
+        @client_id = client_id || RSO.client_id
+        @redirect_uri = redirect_uri || RSO.redirect_uri
+        @scope = scope || RSO.scope || 'openid'
+        @credential = Credential.new(
+          client_secret: client_secret || RSO.client_secret,
+          client_assertion: client_assertion || RSO.client_assertion,
+          private_key: private_key || RSO.private_key
+        )
+        @open_timeout = open_timeout || Rito.open_timeout
+        @timeout = timeout || Rito.timeout
+        @adapter = adapter || Rito.adapter
+        @jwks_mutex = Mutex.new
+        @jwks = nil
+
+        validate!
+      end
+
+      def authorization_url(scope: @scope, state: nil, login_hint: nil, ui_locales: nil)
+        ensure_redirect_uri!
+        state ||= SecureRandom.hex(32)
+        params = {
+          'client_id' => @client_id,
+          'redirect_uri' => @redirect_uri,
+          'response_type' => 'code',
+          'scope' => scope,
+          'state' => state
+        }
+        params['login_hint'] = login_hint if login_hint
+        params['ui_locales'] = ui_locales if ui_locales
+        AuthorizationRequest.new(url: "#{@provider}/authorize?#{URI.encode_www_form(params)}", state: state)
+      end
+
+      def exchange_code(code)
+        request_token(grant_type: 'authorization_code', code: code, redirect_uri: @redirect_uri)
+      end
+
+      def refresh(refresh_token, scope: nil)
+        params = { grant_type: 'refresh_token', refresh_token: refresh_token }
+        params[:scope] = scope if scope
+        request_token(**params)
+      end
+
+      def userinfo(access_token)
+        response = http do
+          connection.get('/userinfo') do |req|
+            req.headers['Authorization'] = "Bearer #{access_token}"
+          end
+        end
+        raise_rso_error!(response, 'GET', '/userinfo') unless response.status == 200
+        Userinfo.from_api(response.body)
+      end
+
+      def jwks(force: false)
+        @jwks_mutex.synchronize do
+          @jwks = nil if force
+          @jwks ||= fetch_jwks
+        end
+      end
+
+      def verify_id_token(id_token, leeway: 60)
+        header = Jwt.header(id_token)
+        claims = Jwt.claims(id_token)
+        verify_signature!(id_token, header)
+        validate_claims!(claims, leeway)
+        claims
+      end
+
+      private
+
+      def request_token(params)
+        params = @credential.token_params(params, client_id: @client_id, aud: @provider)
+        response = http do
+          connection.post('/token') do |req|
+            req.headers['Authorization'] = @credential.authorization_header(@client_id) if @credential.basic?
+            req.body = params
+          end
+        end
+        raise_rso_error!(response, 'POST', '/token') unless response.status == 200
+        Tokens.from_api(response.body)
+      end
+
+      def fetch_jwks
+        response = http { connection.get('/jwks.json') }
+        raise_rso_error!(response, 'GET', '/jwks.json') unless response.status == 200
+        response.body
+      end
+
+      def verify_signature!(id_token, header)
+        raise InvalidToken, "unsupported alg: #{header['alg'].inspect}" unless header['alg'] == 'RS256'
+
+        key = signing_key_for(header['kid'])
+        segments = id_token.split('.')
+        signature = Jwt.base64url_decode(segments[2].to_s)
+        valid = key.verify(OpenSSL::Digest.new('SHA256'), signature, "#{segments[0]}.#{segments[1]}")
+        raise InvalidToken, 'invalid signature' unless valid
+      end
+
+      def signing_key_for(kid)
+        key = key_from_jwks(jwks, kid)
+        return key if key
+
+        # Keypairs can be rotated without disabling the old one, so a miss on
+        # a cached document triggers exactly one refresh.
+        key_from_jwks(jwks(force: true), kid) || raise(InvalidToken, "unknown kid: #{kid.inspect}")
+      end
+
+      def key_from_jwks(document, kid)
+        keys = document.is_a?(Hash) ? (document['keys'] || []) : []
+        jwk = keys.find { |key| key['kid'] == kid && key['kty'] == 'RSA' }
+        jwk && Jwks.public_key(jwk)
+      end
+
+      def validate_claims!(claims, leeway)
+        exp = claims['exp']
+        raise InvalidToken, 'missing exp claim' unless exp
+        raise InvalidToken, 'token expired' if exp + leeway < Time.now.to_i
+
+        raise InvalidToken, "unexpected issuer: #{claims['iss'].inspect}" unless claims['iss'] == @provider
+
+        aud = claims['aud']
+        audiences = aud.is_a?(Array) ? aud : [aud].compact
+        return if audiences.include?(@client_id)
+
+        raise InvalidToken, 'audience does not match client_id'
+      end
+
+      def raise_rso_error!(response, method, path)
+        body = parse_error_body(response.body)
+        detail = [body['error'], body['error_description']].compact.join(': ')
+        base = "#{response.status} #{method} #{@provider}#{path}"
+        raise OAuthError.new(
+          detail.empty? ? base : "#{base}: #{detail}",
+          error_code: body['error'],
+          error_description: body['error_description'],
+          response: response
+        )
+      end
+
+      def parse_error_body(body)
+        body = JSON.parse(body) if body.is_a?(String)
+        body.is_a?(Hash) ? body : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def http
+        yield
+      rescue Faraday::ConnectionFailed => e
+        raise Rito::ConnectionError.new("#{e.class}: #{e.message}", wrapped: e)
+      rescue Faraday::TimeoutError, Timeout::Error => e
+        raise Rito::TimeoutError.new("#{e.class}: #{e.message}", wrapped: e)
+      rescue Faraday::SSLError => e
+        raise Rito::SSLError.new("#{e.class}: #{e.message}", wrapped: e)
+      end
+
+      def connection
+        @connection ||= Faraday.new(@provider) do |f|
+          f.options.open_timeout = @open_timeout
+          f.options.timeout = @timeout
+          f.request :url_encoded
+          f.response :json, content_type: /\bjson$/
+          f.adapter @adapter
+        end
+      end
+
+      def ensure_redirect_uri!
+        raise ConfigError, 'redirect_uri is required' if @redirect_uri.to_s.empty?
+      end
+
+      def validate!
+        raise ConfigError, 'client_id is required' if @client_id.to_s.empty?
+      end
+    end
+  end
+end

data/lib/rito/rso/credential.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Rito
+  module RSO
+    class Credential
+      ASSERTION_TTL = 300
+
+      def initialize(client_secret: nil, client_assertion: nil, private_key: nil)
+        provided = [client_secret, client_assertion, private_key].count { |value| value && !value.to_s.empty? }
+        raise ConfigError, 'provide only one of client_secret, client_assertion, or private_key' if provided > 1
+
+        @client_secret = client_secret
+        @client_assertion = client_assertion
+        @private_key = normalize_key(private_key)
+      end
+
+      def configured?
+        @client_secret || @client_assertion || @private_key
+      end
+
+      def basic?
+        !!@client_secret
+      end
+
+      def authorization_header(client_id)
+        "Basic #{["#{client_id}:#{@client_secret}"].pack('m0')}"
+      end
+
+      def token_params(params, client_id:, aud:)
+        unless configured?
+          raise ConfigError,
+                'client_secret, client_assertion, or private_key is required for token requests'
+        end
+
+        return params if @client_secret
+
+        params.merge(
+          client_assertion_type: JWT_BEARER_TYPE,
+          client_assertion: @client_assertion || mint_assertion(client_id, aud)
+        )
+      end
+
+      private
+
+      def mint_assertion(client_id, aud)
+        now = Time.now.to_i
+        Jwt.sign_rs256(
+          {
+            'iss' => client_id,
+            'sub' => client_id,
+            'aud' => aud,
+            'exp' => now + ASSERTION_TTL,
+            'iat' => now,
+            'jti' => SecureRandom.uuid
+          },
+          @private_key
+        )
+      end
+
+      def normalize_key(key)
+        return nil if key.nil? || key.to_s.empty?
+        return key if key.is_a?(OpenSSL::PKey::RSA)
+
+        OpenSSL::PKey::RSA.new(key)
+      rescue OpenSSL::PKey::PKeyError, ArgumentError
+        raise ConfigError, 'private_key is not a valid RSA key'
+      end
+    end
+  end
+end

data/lib/rito/rso/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Rito
+  module RSO
+    class Error < Rito::Error; end
+
+    class OAuthError < Error
+      attr_reader :error_code, :error_description
+
+      def initialize(message = nil, error_code: nil, error_description: nil, response: nil)
+        @error_code = error_code
+        @error_description = error_description
+        super(message, response: response)
+      end
+    end
+
+    class InvalidToken < Error; end
+  end
+end

data/lib/rito/rso/jwks.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Rito
+  module RSO
+    module Jwks
+      module_function
+
+      def public_key(jwk)
+        raise InvalidToken, "unsupported key type: #{jwk['kty'].inspect}" unless jwk['kty'] == 'RSA'
+
+        modulus = OpenSSL::BN.new(Jwt.base64url_decode(jwk.fetch('n')), 2)
+        exponent = OpenSSL::BN.new(Jwt.base64url_decode(jwk.fetch('e')), 2)
+        sequence = OpenSSL::ASN1::Sequence.new(
+          [OpenSSL::ASN1::Integer.new(modulus), OpenSSL::ASN1::Integer.new(exponent)]
+        )
+        OpenSSL::PKey::RSA.new(sequence.to_der)
+      end
+    end
+  end
+end

data/lib/rito/rso/jwt.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Rito
+  module RSO
+    module Jwt
+      module_function
+
+      def header(jwt)
+        parse_segment(jwt, 0)
+      end
+
+      def claims(jwt)
+        parse_segment(jwt, 1)
+      end
+
+      def sign_rs256(payload_claims, key, header_claims: { 'alg' => 'RS256', 'typ' => 'JWT' })
+        signing_input = "#{encode(header_claims)}.#{encode(payload_claims)}"
+        signature = key.sign(OpenSSL::Digest.new('SHA256'), signing_input)
+        "#{signing_input}.#{base64url_encode(signature)}"
+      end
+
+      def base64url_encode(bytes)
+        [bytes].pack('m0').tr('+/', '-_').sub(/=+\z/, '')
+      end
+
+      def base64url_decode(str)
+        str.to_s.tr('-_', '+/').unpack1('m')
+      end
+
+      def encode(hash)
+        base64url_encode(JSON.generate(hash))
+      end
+
+      def parse_segment(jwt, index)
+        segments = jwt.to_s.split('.')
+        segment = segments[index]
+        raise InvalidToken, 'malformed JWT' if segment.to_s.empty?
+
+        JSON.parse(base64url_decode(segment))
+      rescue JSON::ParserError, ArgumentError
+        raise InvalidToken, 'malformed JWT'
+      end
+    end
+  end
+end

data/lib/rito/rso/models.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Rito
+  module RSO
+    Tokens = Data.define(
+      :access_token, :id_token, :refresh_token, :token_type, :scope,
+      :expires_in, :sub_sid, :raw
+    ) do
+      def self.from_api(hash)
+        new(
+          access_token: hash['access_token'],
+          id_token: hash['id_token'],
+          refresh_token: hash['refresh_token'],
+          token_type: hash['token_type'],
+          scope: hash['scope'],
+          expires_in: hash['expires_in'],
+          sub_sid: hash['sub_sid'],
+          raw: hash.freeze
+        )
+      end
+
+      def id_token_claims
+        Jwt.claims(id_token) if id_token
+      end
+
+      def refresh_token_claims
+        Jwt.claims(refresh_token) if refresh_token
+      end
+    end
+
+    Userinfo = Data.define(:sub, :cpid, :raw) do
+      def self.from_api(hash)
+        new(sub: hash['sub'], cpid: hash['cpid'], raw: hash.freeze)
+      end
+    end
+
+    AuthorizationRequest = Data.define(:url, :state)
+  end
+end

data/lib/rito/rso.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'securerandom'
+
+module Rito
+  module RSO
+    JWT_BEARER_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+
+    class << self
+      attr_accessor :provider, :client_id, :client_secret, :client_assertion,
+                    :private_key, :redirect_uri, :scope
+    end
+
+    self.provider = 'https://auth.riotgames.com'
+    self.client_id = ENV['RIOT_RSO_CLIENT_ID']
+    self.client_secret = ENV['RIOT_RSO_CLIENT_SECRET']
+    self.client_assertion = ENV['RIOT_RSO_CLIENT_ASSERTION']
+    self.private_key = nil
+    self.redirect_uri = ENV['RIOT_RSO_REDIRECT_URI']
+    self.scope = 'openid'
+  end
+end
+
+require_relative 'rso/errors'
+require_relative 'rso/jwt'
+require_relative 'rso/jwks'
+require_relative 'rso/models'
+require_relative 'rso/credential'
+require_relative 'rso/client'

data/lib/rito/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rito
-  VERSION = '0.1.3'
+  VERSION = '0.2.0'
 end

data/lib/rito.rb

@@ -24,6 +24,7 @@ require_relative 'rito/middleware/riot_errors'
 require_relative 'rito/connection'
 require_relative 'rito/instrumentation'
 require_relative 'rito/client'
+require_relative 'rito/rso'
 require_relative 'rito/models/account'
 require_relative 'rito/models/summoner'
 require_relative 'rito/models/match'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rito
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - kodbilenadam
@@ -82,6 +82,13 @@ files:
 - lib/rito/rate_limiting/null_limiter.rb
 - lib/rito/rate_limiting/redis_limiter.rb
 - lib/rito/routing.rb
+- lib/rito/rso.rb
+- lib/rito/rso/client.rb
+- lib/rito/rso/credential.rb
+- lib/rito/rso/errors.rb
+- lib/rito/rso/jwks.rb
+- lib/rito/rso/jwt.rb
+- lib/rito/rso/models.rb
 - lib/rito/version.rb
 homepage: https://github.com/kodbilenadam/rito
 licenses: