standard_id 0.1.0

data/db/migrate/20250903063000_create_standard_id_authorization_codes.rb

@@ -0,0 +1,46 @@
+class CreateStandardIdAuthorizationCodes < ActiveRecord::Migration[8.0]
+  def change
+    create_table :standard_id_authorization_codes, id: primary_key_type do |t|
+      # Link to account when available (can be nil for pre-auth flows)
+      t.references :account, null: true, foreign_key: true, index: true, type: foreign_key_type
+
+      # Opaque auth code hash (SHA256 of the plaintext code), unique for lookup
+      t.string :code_hash, null: false
+
+      # OAuth client binding and redirect URI binding
+      t.string :client_id, null: false
+      t.text :redirect_uri, null: false
+
+      # Optional OAuth/OIDC extras
+      t.string :scope
+      t.string :audience
+      t.string :nonce
+
+      # PKCE
+      t.string :code_challenge
+      t.string :code_challenge_method
+
+      # Lifecycle
+      t.datetime :issued_at, null: false
+      t.datetime :expires_at, null: false
+      t.datetime :consumed_at
+
+      # Provider and custom metadata if needed
+      if connection.adapter_name.downcase.include?("postgres")
+        t.jsonb :metadata, default: {}, null: false
+        t.index :metadata, using: :gin
+      else
+        t.json :metadata, default: {}, null: false
+      end
+
+      t.timestamps
+
+      # Indexes
+      t.index :code_hash, unique: true
+      t.index [:client_id, :expires_at]
+      t.index [:account_id, :expires_at]
+      t.index :expires_at
+      t.index :consumed_at
+    end
+  end
+end

data/db/migrate/20250903135906_create_standard_id_passwordless_challenges.rb

@@ -0,0 +1,22 @@
+class CreateStandardIdPasswordlessChallenges < ActiveRecord::Migration[8.0]
+  def change
+    create_table :standard_id_passwordless_challenges do |t|
+      t.string :connection_type, null: false
+
+      t.string :username, null: false
+      t.string :code, null: false
+
+      t.datetime :expires_at, null: false
+      t.datetime :used_at
+
+      t.string :ip_address
+      t.text :user_agent
+
+      t.timestamps
+    end
+
+    add_index :standard_id_passwordless_challenges, [:connection_type, :username, :code], name: "index_passwordless_challenges_on_lookup"
+    add_index :standard_id_passwordless_challenges, :expires_at
+    add_index :standard_id_passwordless_challenges, :used_at
+  end
+end

data/lib/generators/standard_id/install/install_generator.rb

@@ -0,0 +1,14 @@
+require "rails/generators"
+
+module StandardId
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Creates a StandardId initializer at config/initializers/standard_id.rb"
+
+      def create_initializer_file
+        template "standard_id.rb", "config/initializers/standard_id.rb"
+      end
+    end
+  end
+end

data/lib/generators/standard_id/install/templates/standard_id.rb

@@ -0,0 +1,11 @@
+# StandardId configuration
+# Generated by: rails g standard_id:install
+
+StandardId.configure do |c|
+  # Set to the String name of your account model (e.g., "User" or "Account")
+  c.account_class_name = "User"
+
+  # Optional: customize cache store and logger used internally by StandardId
+  # c.cache_store = Rails.cache
+  # c.logger = Rails.logger
+end

data/lib/standard_id/api/authentication_guard.rb

@@ -0,0 +1,20 @@
+module StandardId
+  module Api
+    class AuthenticationGuard
+      def require_session!(session_manager)
+        api_session = session_manager.current_session
+
+        if api_session.blank?
+          raise StandardId::NotAuthenticatedError, "Invalid or missing access token"
+        elsif api_session.respond_to?(:expired?) && api_session.expired?
+          raise StandardId::ExpiredSessionError, "Session has expired"
+        elsif api_session.respond_to?(:revoked?) && api_session.revoked?
+          session_manager.clear_session!
+          raise StandardId::RevokedSessionError, "Session has been revoked"
+        end
+
+        api_session
+      end
+    end
+  end
+end

data/lib/standard_id/api/session_manager.rb

@@ -0,0 +1,39 @@
+module StandardId
+  module Api
+    class SessionManager
+      def initialize(token_manager, request:)
+        @token_manager = token_manager
+        @request = request
+      end
+
+      def current_session
+        @current_session ||= load_current_session
+      end
+
+      def current_account
+        return unless current_session
+        @current_account ||= StandardId.config.account_class.find_by(id: current_session.account_id)
+      end
+
+      def revoke_current_session!
+        clear_session!
+      end
+
+      def clear_session!
+        @current_session = nil
+        @current_account = nil
+      end
+
+      private
+
+      def load_current_session
+        return @current_session if @current_session.present?
+
+        jwt_session = @token_manager.verify_jwt_token
+        return unless jwt_session&.active?
+
+        @current_session = jwt_session
+      end
+    end
+  end
+end

data/lib/standard_id/api/token_manager.rb

@@ -0,0 +1,50 @@
+module StandardId
+  module Api
+    class TokenManager
+      attr_reader :request
+
+      def initialize(request)
+        @request = request
+      end
+
+      def create_device_session(account, device_id: nil, device_agent: nil)
+        StandardId::DeviceSession.create!(
+          account:,
+          ip_address: @request.remote_ip,
+          device_id: device_id || SecureRandom.uuid,
+          device_agent: device_agent || @request.user_agent,
+          expires_at: 30.days.from_now # TODO: make this configurable
+        )
+      end
+
+      def create_service_session(account, service_name:, service_version:, owner:, metadata: {})
+        StandardId::ServiceSession.create!(
+          account:,
+          owner:,
+          ip_address: @request.remote_ip,
+          service_name:,
+          service_version:,
+          metadata: metadata || {},
+          expires_at: StandardId::ServiceSession.default_expiry
+        )
+      end
+
+      def bearer_token
+        return @bearer_token if @bearer_token.present?
+
+        auth_header = @request.headers["Authorization"]
+        return unless auth_header&.start_with?("Bearer ")
+
+        @bearer_token = auth_header.split(" ", 2).last
+      end
+
+      def verify_jwt_token(token: bearer_token)
+        StandardId::JwtService.decode_session(token)
+      end
+
+      def generate_lookup_hash(token)
+        Digest::SHA256.hexdigest("#{token}:#{Rails.application.secret_key_base}")
+      end
+    end
+  end
+end

data/lib/standard_id/api_engine.rb

@@ -0,0 +1,7 @@
+module StandardId
+  class ApiEngine < ::Rails::Engine
+    isolate_namespace StandardId
+
+    paths["config/routes.rb"] = "config/routes/api.rb"
+  end
+end

data/lib/standard_id/config.rb

@@ -0,0 +1,69 @@
+module StandardId
+  # Manages configuration for the StandardId engine
+  #
+  # Usage:
+  #   StandardId.configure do |config|
+  #     config.account_class_name = "User"
+  #     config.cache_store = ActiveSupport::Cache::MemoryStore.new
+  #     config.logger = Rails.logger
+  #     config.allowed_post_logout_redirect_uris = ["https://example.com/logout"]
+  #   end
+  class Config
+    # The name of the Account model class as a String, e.g. "User" or "Account"
+    attr_accessor :account_class_name
+
+    # Optional cache store and logger, used by StandardId.cache_store and StandardId.logger
+    attr_accessor :cache_store, :logger
+
+    # OAuth issuer identifier for ID tokens
+    attr_accessor :issuer
+
+    # Optional login URL for redirecting unauthenticated browser requests
+    # Example: "/login" or a full URL like "https://app.example.com/login"
+    # If set, Authorization endpoints can redirect to this path with a redirect_uri param
+    attr_accessor :login_url
+
+    # Social login provider credentials
+    attr_accessor :google_client_id, :google_client_secret
+    attr_accessor :apple_client_id, :apple_client_secret, :apple_private_key, :apple_key_id, :apple_team_id
+
+    # Passwordless authentication callbacks
+    # These should be callable objects (procs/lambdas) that accept (recipient, code) parameters
+    attr_accessor :passwordless_email_sender, :passwordless_sms_sender
+
+    # Allowed post-logout redirect URIs for OIDC logout endpoint
+    # If empty or nil, no redirects are allowed and the endpoint will return a JSON message
+    # If provided, the post_logout_redirect_uri must exactly match one of the values in this list
+    attr_accessor :allowed_post_logout_redirect_uris
+
+    # Layout name to use for StandardId Web controllers.
+    # If nil, controllers should default to "application" (host app or dummy app).
+    # Examples: "application", "standard_id/web/application", "my_custom_layout"
+    attr_accessor :web_layout
+
+    def initialize
+      @account_class_name = nil
+      @cache_store = nil
+      @logger = nil
+      @issuer = nil
+      @login_url = nil
+      @google_client_id = nil
+      @google_client_secret = nil
+      @apple_client_id = nil
+      @apple_client_secret = nil
+      @apple_private_key = nil
+      @apple_key_id = nil
+      @apple_team_id = nil
+      @passwordless_email_sender = nil
+      @passwordless_sms_sender = nil
+      @allowed_post_logout_redirect_uris = []
+      @web_layout = nil
+    end
+
+    def account_class
+      account_class_name.constantize
+    rescue NameError
+      raise NameError, "Could not find account class: #{account_class_name}. Please set a valid class name using `StandardId.configure { |c| c.account_class_name = 'YourAccountClass' }`"
+    end
+  end
+end

data/lib/standard_id/engine.rb

@@ -0,0 +1,5 @@
+module StandardId
+  class Engine < ::Rails::Engine
+    isolate_namespace StandardId
+  end
+end

data/lib/standard_id/errors.rb

@@ -0,0 +1,55 @@
+module StandardId
+  class NotAuthenticatedError < StandardError; end
+
+  class InvalidSessionError < StandardError; end
+  class ExpiredSessionError < InvalidSessionError; end
+  class RevokedSessionError < InvalidSessionError; end
+
+  class OAuthError < StandardError
+    def oauth_error_code
+      :invalid_request
+    end
+
+    def http_status
+      :bad_request
+    end
+  end
+
+  class UnsupportedGrantTypeError < OAuthError
+    def oauth_error_code = :unsupported_grant_type
+  end
+
+  class MissingClientSecretCredentialsError < OAuthError
+    def oauth_error_code = :invalid_request
+  end
+
+  class InvalidClientSecretCredentialsError < OAuthError
+    def oauth_error_code = :invalid_client
+    def http_status = :unauthorized
+  end
+
+  class InvalidRequestError < OAuthError
+    def oauth_error_code = :invalid_request
+  end
+
+  class InvalidClientError < OAuthError
+    def oauth_error_code = :invalid_client
+    def http_status = :unauthorized
+  end
+
+  class InvalidGrantError < OAuthError
+    def oauth_error_code = :invalid_grant
+  end
+
+  class InvalidScopeError < OAuthError
+    def oauth_error_code = :invalid_scope
+  end
+
+  class UnauthorizedClientError < OAuthError
+    def oauth_error_code = :unauthorized_client
+  end
+
+  class UnsupportedResponseTypeError < OAuthError
+    def oauth_error_code = :unsupported_response_type
+  end
+end

data/lib/standard_id/jwt_service.rb

@@ -0,0 +1,50 @@
+require "jwt"
+
+module StandardId
+  class JwtService
+    ALGORITHM = "HS256"
+    Session = Struct.new(:account_id, :client_id, :scopes, :grant_type, keyword_init: true) do
+      def active?
+        true
+      end
+    end
+
+    def self.encode(payload, expires_in: 1.hour)
+      payload[:exp] = expires_in.from_now.to_i
+      payload[:iat] = Time.current.to_i
+
+      JWT.encode(payload, secret_key, ALGORITHM)
+    end
+
+    def self.decode(token)
+      decoded = JWT.decode(token, secret_key, true, { algorithm: ALGORITHM })
+      decoded.first.with_indifferent_access
+    rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIatError
+      nil
+    end
+
+    def self.decode_session(token)
+      payload = decode(token)
+      return unless payload
+
+      scopes = if payload[:scope].is_a?(String)
+        payload[:scope].split(" ")
+      else
+        Array(payload[:scope]).compact
+      end
+
+      Session.new(
+        account_id: payload[:sub],
+        client_id: payload[:client_id],
+        scopes: scopes,
+        grant_type: payload[:grant_type]
+      )
+    end
+
+    private
+
+    def self.secret_key
+      Rails.application.secret_key_base
+    end
+  end
+end

data/lib/standard_id/oauth/authorization_code_authorization_flow.rb

@@ -0,0 +1,47 @@
+module StandardId
+  module Oauth
+    class AuthorizationCodeAuthorizationFlow < AuthorizationFlow
+      expect_params :client_id, :audience
+      permit_params :scope, :redirect_uri, :state, :connection, :prompt, :organization, :invitation, :code_challenge, :code_challenge_method
+
+      private
+
+      def generate_authorization_response
+        subflow_for(params).call
+      end
+
+      def subflow_for(flow_params)
+        builders = {
+          social: -> do
+            Subflows::SocialLoginGrant.new(
+              **common_subflow_params(flow_params),
+              connection: flow_params[:connection],
+              base_url: request.base_url
+            )
+          end,
+          traditional: -> do
+            Subflows::TraditionalCodeGrant.new(
+              **common_subflow_params(flow_params),
+              current_account: current_account
+            )
+          end
+        }
+
+        key = flow_params[:connection].present? ? :social : :traditional
+        builders.fetch(key).call
+      end
+
+      def common_subflow_params(flow_params)
+        {
+          client_id: flow_params[:client_id],
+          redirect_uri: redirect_uri,
+          scope: scope,
+          audience: audience,
+          state: state,
+          code_challenge: flow_params[:code_challenge],
+          code_challenge_method: flow_params[:code_challenge_method]
+        }
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/authorization_code_flow.rb

@@ -0,0 +1,53 @@
+module StandardId
+  module Oauth
+    class AuthorizationCodeFlow < TokenGrantFlow
+      expect_params :client_id, :client_secret, :code
+      permit_params :redirect_uri, :code_verifier
+
+      def authenticate!
+        @credential = validate_client_secret!(params[:client_id], params[:client_secret])
+
+        @authorization_code = find_authorization_code(params[:code])
+        unless @authorization_code&.valid_for_client?(params[:client_id])
+          raise StandardId::InvalidGrantError, "Invalid or expired authorization code"
+        end
+
+        if params[:redirect_uri].present? && @authorization_code.redirect_uri != params[:redirect_uri]
+          raise StandardId::InvalidGrantError, "Redirect URI mismatch"
+        end
+
+        unless @authorization_code.pkce_valid?(params[:code_verifier])
+          raise StandardId::InvalidGrantError, "Invalid PKCE code_verifier"
+        end
+
+        @authorization_code.mark_as_used!
+      end
+
+      private
+
+      def subject_id
+        @authorization_code.account_id
+      end
+
+      def client_id
+        @credential.client_id
+      end
+
+      def token_scope
+        @authorization_code.scope
+      end
+
+      def grant_type
+        "authorization_code"
+      end
+
+      def supports_refresh_token?
+        true
+      end
+
+      def find_authorization_code(code)
+        StandardId::AuthorizationCode.lookup(code)
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/authorization_flow.rb

@@ -0,0 +1,91 @@
+module StandardId
+  module Oauth
+    class AuthorizationFlow < BaseRequestFlow
+      attr_reader :params, :request, :current_account
+
+      def initialize(params, request, current_account: nil)
+        @params = params
+        @request = request
+        @current_account = current_account
+      end
+
+      class << self
+        def extra_permitted_keys
+          [:response_type]
+        end
+      end
+
+      def execute
+        validate_params!
+        authenticate_client!
+        generate_authorization_response
+      end
+
+      private
+
+      def validate_params!
+        if params[:response_type].blank?
+          raise StandardId::InvalidRequestError, "The response_type parameter is required"
+        end
+
+        if params[:client_id].blank?
+          raise StandardId::InvalidRequestError, "The client_id parameter is required"
+        end
+      end
+
+      def authenticate_client!
+        @client = StandardId::ClientApplication.active.find_by(client_id: params[:client_id])
+        unless @client
+          raise StandardId::InvalidClientError, "Invalid client_id"
+        end
+
+        # TODO: support for secret key rotation
+        # Maintain @client_credential for downstream compatibility (select any active secret)
+        @client_credential = @client.primary_client_secret
+
+        if params[:redirect_uri].present? && !@client.valid_redirect_uri?(params[:redirect_uri])
+          raise StandardId::InvalidRequestError, "Invalid redirect_uri"
+        end
+      end
+
+      def generate_authorization_response
+        raise NotImplementedError, "Subclasses must implement generate_authorization_response"
+      end
+
+      def build_redirect_uri(base_uri, params_hash)
+        uri = URI.parse(base_uri)
+        query_params = URI.decode_www_form(uri.query || "")
+
+        params_hash.each do |key, value|
+          query_params << [key.to_s, value.to_s] if value.present?
+        end
+
+        uri.query = URI.encode_www_form(query_params)
+        uri.to_s
+      end
+
+      def build_fragment_uri(base_uri, params_hash)
+        uri = URI.parse(base_uri)
+        fragment_params = params_hash.compact.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
+        uri.fragment = fragment_params
+        uri.to_s
+      end
+
+      def redirect_uri
+        params[:redirect_uri] || @client&.redirect_uris_array&.first
+      end
+
+      def state
+        params[:state]
+      end
+
+      def scope
+        params[:scope]
+      end
+
+      def audience
+        params[:audience]
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/base_request_flow.rb

@@ -0,0 +1,43 @@
+module StandardId
+  module Oauth
+    # Shared base for all OAuth flows to handle params DSL and request context
+    # Used by both token grant flows and authorization endpoint flows
+    class BaseRequestFlow
+      attr_reader :params, :request, :current_account
+
+      def initialize(params, request, current_account: nil)
+        @params = params
+        @request = request
+        @current_account = current_account
+      end
+
+      class << self
+        def expect_params(*keys)
+          @expected_params ||= []
+          @expected_params |= keys.flatten.map! { |k| k.to_sym }
+        end
+
+        def permit_params(*keys)
+          @permitted_params ||= []
+          @permitted_params |= keys.flatten.map! { |k| k.to_sym }
+        end
+
+        def expected_params
+          Array(@expected_params).dup
+        end
+
+        # Subclasses can append additional keys by overriding extra_permitted_keys
+        def permitted_params
+          exp = expected_params
+          perm = Array(@permitted_params)
+          configured = (exp + perm + Array(extra_permitted_keys)).uniq
+          configured
+        end
+
+        def extra_permitted_keys
+          []
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/client_credentials_flow.rb

@@ -0,0 +1,38 @@
+module StandardId
+  module Oauth
+    class ClientCredentialsFlow < TokenGrantFlow
+      expect_params :client_id, :client_secret, :audience
+      permit_params :organization
+
+      def authenticate!
+        @credential = validate_client_secret!(params[:client_id], params[:client_secret])
+      end
+
+      private
+
+      def subject_id
+        @credential.account_id
+      end
+
+      def client_id
+        @credential.client_id
+      end
+
+      def token_scope
+        @credential.scopes
+      end
+
+      def grant_type
+        "client_credentials"
+      end
+
+      def audience
+        params[:audience]
+      end
+
+      def token_expiry
+        1.hour
+      end
+    end
+  end
+end