iden 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a3b382bc495c147f8a4c8ce0714d30be1c5e46cf329314ec2415be0b577e0d1
+  data.tar.gz: 2ffe77bca1bea7346d67a67745f31766f9ce735aae86425a8799f5105287d19c
+SHA512:
+  metadata.gz: 41af1d79582ca7b286b18dbf98ebdc1c706a84940a00d9487e3b20987dd39923bd2ef5bb9c102c795e84dfb539950874a7788b10bf74b8206de42eef09edc64b
+  data.tar.gz: 95609ca87e5d18ac50049d26888c1048688017715aea527b50d5e1ba87778da18782ccec600255daf6967069bf17b10eb4422c73443a32786235bfdc8668605c

data/README.md

@@ -0,0 +1,36 @@
+# iden Ruby SDK
+
+Current iden release: **0.0.1**. Install `iden` from RubyGems.
+
+> This project is derived from the [Logto Ruby SDK](https://github.com/logto-io/ruby). The `Logto` Ruby module is intentionally retained for source compatibility.
+
+[![Version](https://img.shields.io/gem/v/iden)][RubyGems]
+[![Downloads](https://img.shields.io/gem/dt/iden)][RubyGems]
+[![iden](https://img.shields.io/badge/for-iden-5B5CF6)][Website]
+[![Discord](https://img.shields.io/badge/discord-join-5865f2?logo=discord)][Discord]
+
+This is the Ruby SDK for iden. It provides a simple way to integrate iden with your Ruby applications.
+
+This SDK is designed as framework-agnostic, so it can be used with any Ruby web framework. Check out our [docs](https://docs.logto.io/quick-starts/ruby/) for more information.
+
+## Installation
+
+```bash
+bundle add iden
+```
+
+Or whatever your preferred method of adding gems is.
+
+## Sample
+
+A sample Ruby on Rails application is available [here](https://github.com/ryan-iden/ruby/tree/HEAD/logto-sample).
+
+## Resources
+
+- [Documentation](https://docs.logto.io/quick-starts/ruby/)
+- [Website][Website]
+- [Discord][Discord]
+
+[RubyGems]: https://rubygems.org/gems/iden
+[Website]: https://github.com/ryan-iden/iden
+[Discord]: https://discord.gg/vRvwuwgpVX

data/lib/logto/client/errors.rb

@@ -0,0 +1,15 @@
+require_relative "../core/errors"
+
+class LogtoError
+  # Raise when the session is not found in the storage.
+  class SessionNotFoundError < LogtoError
+  end
+
+  # Raise when the session is found but the parameters are mismatched.
+  class SessionMismatchError < LogtoError
+  end
+
+  # Raise when the session is found but the callback URI contains an error parameter.
+  class ServerCallbackError < LogtoError
+  end
+end

data/lib/logto/client/index.rb

@@ -0,0 +1,314 @@
+require "jwt"
+require_relative "index_constants"
+require_relative "index_types"
+require_relative "index_storage"
+require_relative "errors"
+
+# The main client class for the Logto client.
+#
+# It provides the main functionalities for the client to interact with the Logto server.
+#
+# @attr_reader config [LogtoClient::Config] The configuration object for the Logto client.
+class LogtoClient
+  attr_reader :config
+
+  # @param config [LogtoClient::Config] The configuration object for the Logto client.
+  # @param navigate [Proc] The navigation function to be used for the sign-in experience.
+  #   It should accept a URI string as the only argument. You can use the `redirect_to` method in Rails.
+  #   @example
+  #     ->(uri) { redirect_to(uri, allow_other_host: true) }
+  # @param storage [LogtoClient::AbstractStorage] The storage object for the Logto client.
+  #   You can use the `LogtoClient::SessionStorage` for Rails applications.
+  #   @example
+  #     LogtoClient::SessionStorage.new(session)
+  # @param cache [LogtoClient::AbstractStorage] The cache object for the Logto client.
+  #   By default, it will use the Rails cache.
+  def initialize(config:, navigate:, storage:, cache: RailsCacheStorage.new(app_id: config.app_id))
+    raise ArgumentError, "Config must be a LogtoClient::Config" unless config.is_a?(LogtoClient::Config)
+    raise ArgumentError, "Navigate must be a Proc" unless navigate.is_a?(Proc)
+    raise ArgumentError, "Storage must be a LogtoClient::AbstractStorage" unless storage.is_a?(LogtoClient::AbstractStorage)
+    @config = config
+    @navigate = navigate
+    @storage = storage
+    @cache = cache
+    @core = LogtoCore.new(endpoint: @config.endpoint, cache: cache)
+    # A local access token map cache
+    @access_token_map = @storage.get(STORAGE_KEY[:access_token_map]) || {}
+  end
+
+  # Triggers the sign-in experience.
+  #
+  # @param redirect_uri [String] The redirect URI that the user will be redirected to after the sign-in experience is completed.
+  # @param first_screen [String] The first screen that the user will see in the sign-in experience. Can be `sign_in`, `register`, `reset_password`, `single_sign_on`, `identifier:sign_in` or `identifier:register`.
+  # @param identifiers [Array<String>] The identifiers to be used for the first screen, only effective when `first_screen` is `identifier:sign_in`, `identifier:register`, or `reset_password`. Available options are `email`, `phone`, `username`.
+  # @param login_hint [String] The login hint to be used for the sign-in experience.
+  # @param direct_sign_in [Hash] The direct sign-in configuration to be used for the sign-in experience. It should contain the `method` and `target` keys.
+  # @param post_redirect_uri [String] The URI that the user will be redirected to after the redirect URI has successfully handled the sign-in callback.
+  # @param extra_params [Hash] Extra parameters to be used for the sign-in experience.
+  def sign_in(redirect_uri:, first_screen: nil, identifiers: nil, login_hint: nil, direct_sign_in: nil, post_redirect_uri: nil, extra_params: nil)
+    code_verifier = LogtoUtils.generate_code_verifier
+    code_challenge = LogtoUtils.generate_code_challenge(code_verifier)
+
+    state = LogtoUtils.generate_state
+    sign_in_uri = @core.generate_sign_in_uri(
+      client_id: @config.app_id,
+      redirect_uri: redirect_uri,
+      code_challenge: code_challenge,
+      state: state,
+      scopes: @config.scopes,
+      resources: @config.resources,
+      prompt: @config.prompt,
+      first_screen: first_screen,
+      identifiers: identifiers,
+      login_hint: login_hint,
+      direct_sign_in: direct_sign_in,
+      extra_params: extra_params
+    )
+
+    save_sign_in_session(SignInSession.new(
+      redirect_uri: redirect_uri,
+      code_verifier: code_verifier,
+      state: state,
+      post_redirect_uri: post_redirect_uri
+    ))
+    clear_all_tokens
+
+    @navigate.call(sign_in_uri)
+  end
+
+  # Start the sign-out flow with the specified redirect URI. The URI must be
+  # registered in the Logto Console.
+  #
+  # It will also revoke all the tokens and clean up the storage.
+  #
+  # The user will be redirected to that URI after the sign-out flow is completed.
+  # If the `post_logout_redirect_uri` is not specified, the user will be redirected
+  # to a default page.
+  #
+  # @param post_logout_redirect_uri [String] The URI that the user will be redirected to after the sign-out flow is completed.
+  def sign_out(post_logout_redirect_uri: nil)
+    if refresh_token
+      @core.revoke_token(client_id: @config.app_id, client_secret: @config.app_secret, token: refresh_token)
+    end
+
+    uri = @core.generate_sign_out_uri(
+      client_id: @config.app_id, post_logout_redirect_uri: post_logout_redirect_uri
+    )
+    clear_all_tokens
+    @navigate.call(uri)
+  end
+
+  # Handle the sign-in callback from the redirect URI.
+  #
+  # @param url [String] The URL of the callback from the redirect URI. It should contain the query parameters.
+  # @return [String, nil] The URI that the user will be redirected to after the redirect URI has successfully handled the sign-in callback.
+  #   It should be the same as the `post_redirect_uri` in the `sign_in` method. If it was not set, no redirection will happen.
+  def handle_sign_in_callback(url:)
+    query_params = URI.decode_www_form(URI(url).query).to_h
+    data = @storage.get(STORAGE_KEY[:sign_in_session])
+    raise LogtoError::SessionNotFoundError, "No sign-in session found" unless data
+
+    error = query_params[LogtoCore::QUERY_KEY[:error]]
+    error_description = query_params[LogtoCore::QUERY_KEY[:error_description]]
+    raise LogtoError::ServerCallbackError, "Error: #{error}, Description: #{error_description}" if error
+
+    current_session = data.is_a?(SignInSession) ? data : SignInSession.new(**data)
+    # A loose URI check here
+    raise LogtoError::SessionMismatchError, "Redirect URI mismatch" unless url.start_with?(current_session.redirect_uri)
+    raise LogtoError::SessionMismatchError, "No state found in query parameters" unless query_params[LogtoCore::QUERY_KEY[:state]]
+    raise LogtoError::SessionMismatchError, "Session state mismatch" unless current_session.state == query_params[LogtoCore::QUERY_KEY[:state]]
+    raise LogtoError::SessionMismatchError, "No code found in query parameters" unless query_params[LogtoCore::QUERY_KEY[:code]]
+
+    token_response = @core.fetch_token_by_authorization_code(
+      client_id: @config.app_id,
+      client_secret: @config.app_secret,
+      redirect_uri: current_session.redirect_uri,
+      code_verifier: current_session.code_verifier,
+      code: query_params[LogtoCore::QUERY_KEY[:code]]
+    )
+
+    verify_jwt(token: token_response[:id_token])
+    handle_token_response(token_response, resource: nil)
+    clear_sign_in_session
+
+    @navigate.call(current_session.post_redirect_uri)
+    current_session.post_redirect_uri
+  end
+
+  # Verify the JWT token with the configured client ID and the OIDC issuer.
+  #
+  # @param token [String] The JWT token to be verified.
+  def verify_jwt(token:)
+    raise ArgumentError, "Token must be a string" unless token.is_a?(String)
+
+    JWT.decode(
+      token,
+      nil,
+      true,
+      # List our current and future possibilities. It could use the `alg` header from the token,
+      # but it will be tricky to handle the case of caching.
+      algorithms: ["RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "ES256K"],
+      jwks: fetch_jwks,
+      iss: @core.oidc_config[:issuer],
+      verify_iss: true,
+      aud: @config.app_id,
+      verify_aud: true
+    )
+  end
+
+  # Get the raw ID token from the storage.
+  #
+  # @return [String, nil] The raw ID token.
+  def id_token
+    @storage.get(STORAGE_KEY[:id_token])
+  end
+
+  # Get the ID token claims from the storage.
+  # It will return nil if the ID token is not found.
+  #
+  # @return [LogtoCore::IdTokenClaims, nil] The ID token claims.
+  def id_token_claims
+    return nil unless (token = id_token)
+    LogtoUtils.parse_json_safe(JWT.decode(token, nil, false).first, LogtoCore::IdTokenClaims)
+  end
+
+  # Get the access token for the specified resource and organization ID. If both are nil,
+  # it will return the opaque access token for the OpenID Connect UserInfo endpoint.
+  #
+  # If the access token is not found or expired, it will try to use the refresh token to
+  # fetch a new access token, if possible.
+  #
+  # @param resource [String, nil] The resource to be accessed.
+  # @param organization_id [String, nil] The organization ID to be accessed.
+  # @return [String, nil] The access token.
+  def access_token(resource: nil, organization_id: nil)
+    raise LogtoError::NotAuthenticatedError, "Not authenticated" unless is_authenticated?
+    key = LogtoUtils.build_access_token_key(resource: resource, organization_id: organization_id)
+    token = @access_token_map[key]
+
+    # Give it some leeway
+    if token&.[]("expires_at")&.> Time.now + 10
+      return token["token"]
+    end
+
+    @access_token_map.delete(key)
+    return nil unless refresh_token
+
+    # Try to use refresh token to fetch a new access token
+    token_response = @core.fetch_token_by_refresh_token(
+      client_id: @config.app_id,
+      client_secret: @config.app_secret,
+      refresh_token: refresh_token,
+      resource: resource,
+      organization_id: organization_id
+    )
+    handle_token_response(token_response, resource: resource, organization_id: organization_id)
+    token_response[:access_token]
+  end
+
+  # Get the access token claims for the specified resource and organization ID. If both are nil,
+  # an ArgumentError will be raised.
+  #
+  # @param resource [String, nil] The resource to be accessed.
+  # @param organization_id [String, nil] The organization ID to be accessed.
+  # @return [LogtoCore::AccessTokenClaims, nil] The access token claims.
+  def access_token_claims(resource: nil, organization_id: nil)
+    raise ArgumentError, "Resource and organization ID cannot be nil at the same time" if
+      resource.nil? && organization_id.nil?
+    return nil unless (token = access_token(resource: resource, organization_id: organization_id))
+    LogtoUtils.parse_json_safe(
+      JWT.decode(token, nil, false).first,
+      LogtoCore::AccessTokenClaims
+    )
+  end
+
+  # Fetch the user information from the OpenID Connect UserInfo endpoint.
+  #
+  # @return [LogtoCore::UserInfoResponse] The user information.
+  def fetch_user_info
+    @core.fetch_user_info(access_token: access_token)
+  end
+
+  # Get the raw refresh token from the storage.
+  #
+  # @return [String, nil] The raw refresh token.
+  def refresh_token
+    @storage.get(STORAGE_KEY[:refresh_token])
+  end
+
+  # Check if the client is authenticated by checking if the ID token is present.
+  #
+  # @return [Boolean] Whether the client is authenticated.
+  def is_authenticated?
+    id_token ? true : false
+  end
+
+  # Clear all the tokens from the storage.
+  #
+  # It will also clear the access token map cache.
+  def clear_all_tokens
+    @access_token_map = {}
+    @storage.remove(STORAGE_KEY[:access_token_map])
+    @storage.remove(STORAGE_KEY[:id_token])
+    @storage.remove(STORAGE_KEY[:refresh_token])
+  end
+
+  protected
+
+  def handle_token_response(response, resource:, organization_id: nil)
+    raise ArgumentError, "Response must be a TokenResponse" unless response.is_a?(LogtoCore::TokenResponse)
+    response[:refresh_token] && save_refresh_token(response[:refresh_token])
+    response[:id_token] && save_id_token(response[:id_token])
+    # The response should have access token
+    save_access_token(
+      key: LogtoUtils.build_access_token_key(resource: resource, organization_id: organization_id),
+      token: LogtoCore::AccessToken.new(
+        token: response[:access_token],
+        scope: response[:scope],
+        expires_at: Time.now + response[:expires_in].to_i
+      )
+    )
+  end
+
+  def save_refresh_token(token)
+    raise ArgumentError, "Token must be a String" unless token.is_a?(String)
+    @storage.set(STORAGE_KEY[:refresh_token], token)
+  end
+
+  def save_id_token(token)
+    raise ArgumentError, "Token must be a String" unless token.is_a?(String)
+    @storage.set(STORAGE_KEY[:id_token], token)
+  end
+
+  def save_access_token(key:, token:)
+    raise ArgumentError, "Token must be an AccessToken" unless token.is_a?(LogtoCore::AccessToken)
+    @access_token_map[key] = token
+    @storage.set(STORAGE_KEY[:access_token_map], @access_token_map)
+  end
+
+  def save_sign_in_session(data)
+    raise ArgumentError, "Data must be a SignInSession" unless data.is_a?(SignInSession)
+    @storage.set(STORAGE_KEY[:sign_in_session], data)
+  end
+
+  def clear_sign_in_session
+    @storage.remove(STORAGE_KEY[:sign_in_session])
+  end
+
+  def fetch_jwks(options = {})
+    if options[:kid_not_found] && ((@cache&.get("jwks_last_update") || 0) < Time.now.to_i - 300)
+      @cache&.remove("jwks")
+    end
+
+    jwks_hash = @cache&.get("jwks") || begin
+      response = JSON.parse(Net::HTTP.get(URI.parse(@core.oidc_config[:jwks_uri])))
+      @cache&.set("jwks", response)
+      @cache&.set("jwks_last_update", Time.now.to_i)
+      response
+    end
+
+    jwks = JWT::JWK::Set.new(jwks_hash)
+    jwks.select! { |key| key[:use] == "sig" } # Signing Keys only
+    jwks
+  end
+end

data/lib/logto/client/index_constants.rb

@@ -0,0 +1,8 @@
+class LogtoClient
+  STORAGE_KEY = {
+    id_token: "id_token",
+    refresh_token: "refresh_token",
+    access_token_map: "access_token_map",
+    sign_in_session: "sign_in_session"
+  }
+end

data/lib/logto/client/index_storage.rb

@@ -0,0 +1,77 @@
+class LogtoClient
+  # :nocov:
+
+  # An abstract class for storing data.
+  #
+  # This class is used by the Logto client to store the session and token data.
+  #
+  # @abstract
+  class AbstractStorage
+    def initialize
+      raise NotImplementedError
+    end
+
+    def get(key)
+      raise NotImplementedError
+    end
+
+    def set(key, value)
+      raise NotImplementedError
+    end
+
+    def remove(key)
+      raise NotImplementedError
+    end
+  end
+  # :nocov:
+
+  # A storage class that stores data in Rails session.
+  class SessionStorage < AbstractStorage
+    def initialize(session, app_id: nil)
+      @session = session
+      @app_id = app_id
+    end
+
+    def get(key)
+      @session[get_session_key(key)]
+    end
+
+    def set(key, value)
+      @session[get_session_key(key)] = value
+    end
+
+    def remove(key)
+      @session.delete(get_session_key(key))
+    end
+
+    protected
+
+    def get_session_key(key)
+      "logto_#{@app_id || "default"}_#{key}"
+    end
+  end
+
+  class RailsCacheStorage < AbstractStorage
+    def initialize(app_id: nil)
+      @app_id = app_id
+    end
+
+    def get(key)
+      Rails.cache.read(getCacheKey(key))
+    end
+
+    def set(key, value)
+      Rails.cache.write(getCacheKey(key), value, force: true)
+    end
+
+    def remove(key)
+      Rails.cache.delete(getCacheKey(key))
+    end
+
+    protected
+
+    def getCacheKey(key)
+      "logto_cache_#{@app_id || "default"}_#{key}"
+    end
+  end
+end

data/lib/logto/client/index_types.rb

@@ -0,0 +1,53 @@
+require_relative "../core"
+require_relative "../core/utils"
+
+class LogtoClient
+  # The configuration object for the Logto client.
+  #
+  # @attr [URI] endpoint The endpoint for the Logto server, you can get it from the integration guide
+  #   or the team settings page of the Logto Console.
+  #   @example
+  #     'https://foo.logto.app'
+  # @attr [String] app_id The client ID of your application, you can get it from the integration guide
+  #   or the application details page of the Logto Console.
+  # @attr [String] app_secret The client secret of your application, you can get it from the application
+  #   details page of the Logto Console.
+  # @attr [Array<String>] scopes The scopes (permissions) that your application needs to access.
+  #   Scopes that will be added by default: `openid`, `offline_access` and `profile`.
+  #   If resources are specified, scopes will be applied to every resource.
+  #
+  #   See {https://docs.logto.io/quick-starts/rails/#scopes-and-claims Scopes and claims}
+  #   for more information of available scopes for user information.
+  # @attr [Array<String>] resources The API resources that your application needs to access. You can specify
+  #   multiple resources by providing an array of strings.
+  #
+  #   See {https://docs.logto.io/docs/recipes/rbac RBAC} to learn more about how to use role-based access control (RBAC) to protect API resources.
+  # @attr [Array<String>] prompt The prompt parameter to be used for the authorization request.
+  class Config
+    attr_reader :endpoint, :app_id, :app_secret, :scopes, :resources, :prompt
+
+    # @param endpoint [String, URI] The endpoint for the Logto server.
+    # @param app_id [String] The client ID of your application.
+    # @param app_secret [String] The client secret of your application.
+    # @param scopes [Array<String>] The scopes that your application needs to access.
+    # @param resources [Array<String>] The API resources that your application needs to access.
+    # @param prompt [String, Array<String>] The prompt parameter to be used for the authorization request.
+    # @param include_reserved_scopes [Boolean] Whether to include reserved scopes (`openid`, `offline_access` and `profile`) in the scopes.
+    def initialize(endpoint:, app_id:, app_secret:, scopes: [], resources: [], prompt: LogtoCore::PROMPT[:consent], include_reserved_scopes: true)
+      raise ArgumentError, "Scopes must be an array" if scopes && !scopes.is_a?(Array)
+      raise ArgumentError, "Resources must be an array" if resources && !resources.is_a?(Array)
+      raise ArgumentError, "Endpoint must not be empty" if endpoint.nil? || endpoint == ""
+
+      computed_scopes = include_reserved_scopes ? LogtoUtils.with_reserved_scopes(scopes) : scopes
+
+      @endpoint = endpoint.is_a?(URI) ? endpoint : URI.parse(endpoint)
+      @app_id = app_id
+      @app_secret = app_secret
+      @scopes = computed_scopes
+      @resources = computed_scopes.include?(LogtoCore::USER_SCOPE[:organizations]) ? ([LogtoCore::RESERVED_RESOURCE[:organization]] + resources).uniq : resources
+      @prompt = prompt.is_a?(Array) ? prompt : [prompt]
+    end
+  end
+
+  SignInSession = Struct.new(:redirect_uri, :code_verifier, :state, :post_redirect_uri, keyword_init: true)
+end

data/lib/logto/client.rb

@@ -0,0 +1 @@
+require_relative "client/index"

data/lib/logto/core/errors.rb

@@ -0,0 +1,35 @@
+# The base class for all errors in the Logto SDK.
+class LogtoError < StandardError
+  def initialize(message)
+    super
+  end
+
+  # The base class for response errors from Logto server.
+  #
+  # @attr [Net::HTTPResponse, nil] response The response object that caused this error.
+  class ResponseError < LogtoError
+    attr_reader :response
+
+    def initialize(message, response: nil)
+      raise ArgumentError, "response must be a Net::HTTPResponse or nil" unless response.nil? || response.is_a?(Net::HTTPResponse)
+      super(message)
+      @response = response
+    end
+  end
+
+  # Raise when token response is invalid.
+  class TokenError < ResponseError
+  end
+
+  # Raise when revocation response is invalid.
+  class RevocationError < ResponseError
+  end
+
+  # Raise when the userinfo response is invalid.
+  class UserInfoError < ResponseError
+  end
+
+  # Raise when the current user is not authenticated but the operation requires authentication.
+  class NotAuthenticatedError < LogtoError
+  end
+end

data/lib/logto/core/index.rb

@@ -0,0 +1,172 @@
+require "net/http"
+require "uri"
+require "jwt"
+require_relative "index_types"
+require_relative "index_constants"
+require_relative "utils"
+require_relative "errors"
+
+class LogtoCore
+  attr_reader :endpoint, :oidc_config
+
+  def initialize(endpoint:, cache: nil)
+    @endpoint = endpoint
+    @cache = cache
+    @oidc_config = fetch_oidc_config
+  end
+
+  def revoke_token(client_id:, client_secret:, token:)
+    response = Net::HTTP.post_form(
+      URI.parse(oidc_config.revocation_endpoint),
+      {
+        QUERY_KEY[:token] => token,
+        QUERY_KEY[:client_id] => client_id,
+        QUERY_KEY[:client_secret] => client_secret
+      }
+    )
+
+    raise LogtoError::RevocationError.new(response.message, response: response) unless
+      response.is_a?(Net::HTTPSuccess)
+  end
+
+  def fetch_token_by_authorization_code(client_id:, client_secret:, redirect_uri:, code_verifier:, code:, resource: nil)
+    parameters = {
+      QUERY_KEY[:client_id] => client_id,
+      QUERY_KEY[:client_secret] => client_secret,
+      QUERY_KEY[:code] => code,
+      QUERY_KEY[:code_verifier] => code_verifier,
+      QUERY_KEY[:redirect_uri] => redirect_uri,
+      QUERY_KEY[:grant_type] => TOKEN_GRANT_TYPE[:authorization_code]
+    }
+    parameters[QUERY_KEY[:resource]] = resource if resource
+
+    response = Net::HTTP.post_form(
+      URI.parse(oidc_config.token_endpoint),
+      parameters
+    )
+
+    raise LogtoError::TokenError.new(response.message, response: response) unless
+      response.is_a?(Net::HTTPSuccess)
+
+    LogtoUtils.parse_json_safe(response.body, TokenResponse)
+  end
+
+  def fetch_token_by_refresh_token(client_id:, client_secret:, refresh_token:, resource: nil, organization_id: nil, scopes: nil)
+    raise ArgumentError, "Scopes must be an array" if scopes && !scopes.is_a?(Array)
+
+    parameters = {
+      QUERY_KEY[:client_id] => client_id,
+      QUERY_KEY[:client_secret] => client_secret,
+      QUERY_KEY[:refresh_token] => refresh_token,
+      QUERY_KEY[:grant_type] => TOKEN_GRANT_TYPE[:refresh_token]
+    }
+    parameters[QUERY_KEY[:resource]] = resource if resource
+    parameters[QUERY_KEY[:organization_id]] = organization_id if organization_id
+    parameters[QUERY_KEY[:scope]] = scopes.join(" ") if scopes&.any?
+
+    response = Net::HTTP.post_form(
+      URI.parse(oidc_config.token_endpoint),
+      parameters
+    )
+
+    raise LogtoError::TokenError.new(response.message, response: response) unless
+      response.is_a?(Net::HTTPSuccess)
+    LogtoUtils.parse_json_safe(response.body, TokenResponse)
+  end
+
+  def fetch_user_info(access_token:)
+    uri = URI.parse(oidc_config.userinfo_endpoint)
+    request = Net::HTTP::Get.new(uri)
+    request["Authorization"] = "Bearer #{access_token}"
+
+    response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+      http.request(request)
+    end
+
+    raise LogtoError::UserInfoError.new(response.message, response: response) unless
+      response.is_a?(Net::HTTPSuccess)
+    LogtoUtils.parse_json_safe(response.body, UserInfoResponse)
+  end
+
+  def generate_sign_in_uri(
+    client_id:,
+    redirect_uri:,
+    code_challenge:,
+    state:,
+    scopes: nil,
+    resources: nil,
+    prompt: nil,
+    first_screen: nil,
+    identifiers: nil,
+    interaction_mode: nil,
+    login_hint: nil,
+    direct_sign_in: nil,
+    extra_params: nil,
+    include_reserved_scopes: true
+  )
+    parameters = {
+      QUERY_KEY[:client_id] => client_id,
+      QUERY_KEY[:redirect_uri] => redirect_uri,
+      QUERY_KEY[:code_challenge] => code_challenge,
+      QUERY_KEY[:code_challenge_method] => CODE_CHALLENGE_METHOD[:S256],
+      QUERY_KEY[:state] => state,
+      QUERY_KEY[:response_type] => "code"
+    }
+
+    parameters[QUERY_KEY[:prompt]] = prompt&.any? ? prompt.join(" ") : PROMPT[:consent]
+
+    computed_scopes = include_reserved_scopes ? LogtoUtils.with_reserved_scopes(scopes).join(" ") : scopes&.join(" ")
+    parameters[QUERY_KEY[:scope]] = computed_scopes if computed_scopes
+
+    parameters[QUERY_KEY[:login_hint]] = login_hint if login_hint
+
+    if direct_sign_in
+      parameters[QUERY_KEY[:direct_sign_in]] = "#{direct_sign_in[:method]}:#{direct_sign_in[:target]}"
+    end
+
+    parameters[QUERY_KEY[:resource]] = resources if resources&.any?
+
+    if first_screen
+      parameters[QUERY_KEY[:first_screen]] = first_screen
+    elsif interaction_mode
+      parameters[QUERY_KEY[:interaction_mode]] = interaction_mode
+    end
+
+    parameters[QUERY_KEY[:identifier]] = identifiers.join(" ") if identifiers&.any?
+
+    extra_params&.each do |key, value|
+      parameters[key] = value
+    end
+
+    parameters.each_key do |key|
+      raise ArgumentError, "Parameters contain nil key, please check the input" if key.nil?
+    end
+
+    uri = URI.parse(oidc_config.authorization_endpoint)
+    uri.query = URI.encode_www_form(parameters)
+    uri.to_s
+  end
+
+  def generate_sign_out_uri(client_id:, post_logout_redirect_uri: nil)
+    parameters = {
+      QUERY_KEY[:client_id] => client_id
+    }
+    parameters[QUERY_KEY[:post_logout_redirect_uri]] = post_logout_redirect_uri if post_logout_redirect_uri
+
+    uri = URI.parse(oidc_config.end_session_endpoint)
+    uri.query = URI.encode_www_form(parameters)
+    uri.to_s
+  end
+
+  protected
+
+  # Function to fetch OIDC config from a Logto endpoint
+  def fetch_oidc_config
+    config_hash = @cache&.get("oidc_config") || begin
+      response = Net::HTTP.get(URI.join(endpoint, DISCOVERY_PATH))
+      @cache&.set("oidc_config", response)
+      response
+    end
+    LogtoUtils.parse_json_safe(config_hash, OidcConfigResponse)
+  end
+end

data/lib/logto/core/index_constants.rb

@@ -0,0 +1,79 @@
+class LogtoCore
+  DISCOVERY_PATH = "/oidc/.well-known/openid-configuration"
+
+  QUERY_KEY = {
+    client_id: "client_id",
+    client_secret: "client_secret",
+    token: "token",
+    code: "code",
+    code_verifier: "code_verifier",
+    code_challenge: "code_challenge",
+    code_challenge_method: "code_challenge_method",
+    prompt: "prompt",
+    redirect_uri: "redirect_uri",
+    post_logout_redirect_uri: "post_logout_redirect_uri",
+    grant_type: "grant_type",
+    refresh_token: "refresh_token",
+    scope: "scope",
+    state: "state",
+    response_type: "response_type",
+    resource: "resource",
+    organization_id: "organization_id",
+    login_hint: "login_hint",
+    direct_sign_in: "direct_sign_in",
+    first_screen: "first_screen",
+    identifier: "identifier",
+    interaction_mode: "interaction_mode",
+    error: "error",
+    error_description: "error_description"
+  }
+
+  TOKEN_GRANT_TYPE = {
+    authorization_code: "authorization_code",
+    refresh_token: "refresh_token"
+  }
+
+  CODE_CHALLENGE_METHOD = {
+    S256: "S256"
+  }
+
+  PROMPT = {
+    login: "login",
+    none: "none",
+    consent: "consent",
+    select_account: "select_account"
+  }
+
+  # Scopes that reserved by Logto, which will be added to the auth request automatically.
+  RESERVED_SCOPE = {
+    openid: "openid",
+    offline_access: "offline_access",
+    profile: "profile"
+  }
+
+  # Scopes for ID Token and Userinfo Endpoint.
+  USER_SCOPE = {
+    # Scope for basic user ingo.
+    profile: "profile",
+    # Scope for email address.
+    email: "email",
+    # Scope for phone number.
+    phone: "phone",
+    # Scope for user's custom data.
+    custom_data: "custom_data",
+    # Scope for user's social identity details.
+    identities: "identities",
+    # Scope for user's roles.
+    roles: "roles",
+    # Scope for user's organization IDs and perform organization token grant per {https://github.com/logto-io/rfcs RFC 0001}.
+    organizations: "urn:logto:scope:organizations",
+    # Scope for user's organization roles per {https://github.com/logto-io/rfcs RFC 0001}.
+    organization_roles: "urn:logto:scope:organization_roles"
+  }
+
+  # Resources that reserved by Logto, which cannot be defined by users.
+  RESERVED_RESOURCE = {
+    # The resource for organization template per {https://github.com/logto-io/rfcs RFC 0001}.
+    organization: "urn:logto:resource:organizations"
+  }
+end

data/lib/logto/core/index_types.rb

@@ -0,0 +1,93 @@
+require "net/http"
+require "json"
+require_relative "utils"
+
+class LogtoCore
+  # The non-exhaustive list of keys that return from the {https://openid.net/specs/openid-connect-discovery-1_0.html OpenID Connect Discovery} endpoint.
+  OidcConfigResponse = Struct.new(
+    :authorization_endpoint,
+    :token_endpoint,
+    :userinfo_endpoint,
+    :end_session_endpoint,
+    :revocation_endpoint,
+    :jwks_uri,
+    :issuer,
+    :unknown_keys,
+    keyword_init: true
+  )
+
+  # The response from the {https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint Token Endpoint} when fetching a token.
+  TokenResponse = Struct.new(
+    :access_token,
+    :refresh_token,
+    :id_token,
+    :scope,
+    :token_type,
+    :expires_in,
+    :unknown_keys,
+    keyword_init: true
+  )
+
+  # The claims that are returned in the {https://openid.net/specs/openid-connect-core-1_0.html#IDToken ID Token}.
+  #
+  # @attr [String] iss The issuer of this token.
+  # @attr [String] sub The subject (user ID) of this token.
+  # @attr [String] aud The audience (client ID) of this token.
+  # @attr [Integer] exp The expiration time of this token.
+  # @attr [Integer] iat The time at which this token was issued.
+  # @attr [String, nil] at_hash The access token hash value.
+  # @attr [String, nil] name The full name of the user.
+  # @attr [String, nil] username The username of the user.
+  # @attr [String, nil] picture The URL of the user's profile picture.
+  # @attr [String, nil] email The email address of the user.
+  # @attr [Boolean] email_verified Whether the user's email address has been verified.
+  # @attr [String, nil] phone_number The phone number of the user.
+  # @attr [Boolean] phone_number_verified Whether the user's phone number has been verified.
+  # @attr [Array<String>] organizations The organization IDs that the user has membership in.
+  # @attr [Array<String>] organization_roles All organization roles that the user has.
+  #   The format is `[organizationId]:[roleName]`.
+  #
+  #   Note that not all organizations are included in this list, only the ones that the user has roles in.
+  #   @example
+  #     ['org1:admin', 'org2:member'] # The user is an admin of org1 and a member of org2.
+  # @attr [Array<String>] roles The roles that the user has for API resources.
+  IdTokenClaims = Struct.new(
+    :iss, :sub, :aud, :exp, :iat, :at_hash, :name, :username, :picture,
+    :email, :email_verified, :phone_number, :phone_number_verified,
+    :organizations, :organization_roles, :roles, :unknown_keys,
+    keyword_init: true
+  )
+
+  # The claims that are returned in the {https://openid.net/specs/openid-connect-core-1_0.html#UserInfo UserInfo} response.
+  #
+  # @see IdTokenClaims for the common claims that are returned in the ID token.
+  #
+  # @attr [Hash] custom_data The custom data that is stored in the user profile.
+  # @attr [Hash] identities The social sign-in identities that are linked to the user.
+  UserInfoResponse = Struct.new(
+    *IdTokenClaims.members, :custom_data, :identities,
+    keyword_init: true
+  )
+
+  # The claims that are returned in the access token.
+  #
+  # @attr [String] jti The JWT ID of this token.
+  # @attr [String] iss The issuer of this token.
+  # @attr [String] sub The subject (user ID or client ID) of this token.
+  # @attr [String] aud The audience (API resource or organization ID) of this token.
+  # @attr [Integer] exp The expiration time of this token.
+  # @attr [Integer] iat The time at which this token was issued.
+  # @attr [String, nil] client_id The client ID that this token was issued to.
+  # @attr [String] scope The scopes that this token has.
+  AccessTokenClaims = Struct.new(
+    :jti, :iss, :sub, :aud, :exp, :iat, :client_id, :scope, :unknown_keys,
+    keyword_init: true
+  )
+
+  # The structured access token.
+  #
+  # @attr [String] token The access token string.
+  # @attr [String] scope The scopes that this token has.
+  # @attr [Integer] expires_at The epoch timestamp when this token will expire.
+  AccessToken = Struct.new(:token, :scope, :expires_at, keyword_init: true)
+end

data/lib/logto/core/utils.rb

@@ -0,0 +1,46 @@
+require "json"
+require "securerandom"
+require_relative "index_constants"
+
+module LogtoUtils
+  # Parses a JSON string and maps it to a given Struct class, handling unknown keys.
+  #
+  # @param json_str_or_hash [String, Hash] The JSON string or hash to be parsed.
+  # @param struct_class [Class] The Struct class to map the JSON data to. The strcut class must have a
+  #   `:unknown_keys` member and a `keyword_init: true` keyword argument.
+  # @return [Struct] An instance of the given Struct class populated with known keys and a hash of unknown keys.
+  def self.parse_json_safe(json_str_or_hash, struct_class)
+    data = json_str_or_hash.is_a?(String) ? JSON.parse(json_str_or_hash) : json_str_or_hash
+    known_keys = struct_class.members - [:unknown_keys]
+    known_data = data.select { |key, _| known_keys.include?(key.to_sym) }
+    unknown_data = data.reject { |key, _| known_keys.include?(key.to_sym) }
+    struct_class.new(**known_data, unknown_keys: unknown_data)
+  end
+
+  # @param scopes [Array<String>, nil] The scopes to be added reserved scopes to.
+  # @return [Array<String>] The scopes with reserved scopes added.
+  # @example
+  #   LogtoUtils.with_reserved_scopes(['foo', 'bar'])
+  #   # => ['foo', 'bar', 'openid', 'offline_access', 'profile']
+  def self.with_reserved_scopes(scopes)
+    unique_scopes = scopes || []
+    unique_scopes += LogtoCore::RESERVED_SCOPE.values
+    unique_scopes.uniq
+  end
+
+  def self.generate_code_verifier
+    SecureRandom.urlsafe_base64(32)
+  end
+
+  def self.generate_code_challenge(code_verifier)
+    Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier)).tr("=", "")
+  end
+
+  def self.generate_state
+    SecureRandom.urlsafe_base64(32)
+  end
+
+  def self.build_access_token_key(resource:, organization_id: nil)
+    "#{organization_id ? "##{organization_id}" : ""}:#{resource || "default"}"
+  end
+end

data/lib/logto/core.rb

@@ -0,0 +1 @@
+require_relative "core/index"

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: iden
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- ryan-iden
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: Ruby authentication and authorization SDK for iden.
+email: wangsiyuan19990317@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/logto/client.rb
+- lib/logto/client/errors.rb
+- lib/logto/client/index.rb
+- lib/logto/client/index_constants.rb
+- lib/logto/client/index_storage.rb
+- lib/logto/client/index_types.rb
+- lib/logto/core.rb
+- lib/logto/core/errors.rb
+- lib/logto/core/index.rb
+- lib/logto/core/index_constants.rb
+- lib/logto/core/index_types.rb
+- lib/logto/core/utils.rb
+homepage: https://github.com/ryan-iden/ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ryan-iden/ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: The iden SDK for Ruby.
+test_files: []