shakha 0.3.0 → 0.9.0

data/app/controllers/shakha/auth_controller.rb

@@ -6,11 +6,11 @@ require "uri"
 module Shakha
   class AuthController < ApplicationController
     include PKCEMixin
+    include RateLimiter
 
-    skip_before_action :verify_authenticity_token, only: [:callback]
+    skip_before_action :verify_authenticity_token, only: [ :callback ]
 
     def new
-      @client = find_or_create_client
       @return_to = sanitize_return_to(params[:return_to])
       @providers = Shakha.config.providers
     end
@@ -19,11 +19,11 @@ module Shakha
       provider = resolve_provider
       pkce = create_pkce_bundle
 
-      redirect_uri = "#{Shakha.config.app_origin}/auth/shakha/#{provider.provider_name}/callback"
       auth_url = provider.authorize_url(
         state: pkce[:state],
         code_challenge: pkce[:challenge],
-        redirect_uri: redirect_uri
+        redirect_uri: callback_redirect_uri(provider),
+        nonce: pkce[:nonce]
       )
 
       redirect_to auth_url, allow_other_host: true
@@ -36,26 +36,34 @@ module Shakha
       token_response = provider.exchange_code(
         code: params[:code],
         code_verifier: pkce_result[:verifier],
-        redirect_uri: "#{Shakha.config.app_origin}/auth/shakha/#{provider.provider_name}/callback"
+        redirect_uri: callback_redirect_uri(provider)
       )
 
-      identity = provider.identity_from_response(token_response)
+      identity = provider.identity_from_response(token_response, expected_nonce: pkce_result[:nonce])
       user = find_or_create_user(provider.provider_name, identity)
       session_record = create_session(user)
       set_session_cookie(session_record)
-      redirect_to build_return_url(pkce_result[:return_to], session_record)
+      ActiveSupport::Notifications.instrument(
+        "shakha.sign_in",
+        user_id: user.id, provider: provider.provider_name, ip: request.remote_ip
+      )
+      redirect_to build_return_url(pkce_result[:return_to], session_record), allow_other_host: true
 
     rescue PKCEError, OAuthError => e
       handle_auth_failure(e, pkce_result)
     end
 
     def destroy
-      current_session&.destroy
+      if current_session
+        ActiveSupport::Notifications.instrument("shakha.sign_out", user_id: current_session.user_id)
+        current_session.destroy
+      end
       cookies.delete(:shakha_session_token)
 
-      respond_to do |format|
-        format.html { redirect_to params[:return_to].presence || "/" }
-        format.json { render json: { status: "signed_out" } }
+      if request.format.json?
+        render json: { status: "signed_out" }
+      else
+        redirect_to params[:return_to].presence || "/"
       end
     end
 
@@ -66,26 +74,35 @@ module Shakha
     private
 
     def resolve_provider
-      provider_name = (params[:provider] || :google).to_sym
-      Shakha::Providers.resolve(provider_name)
+      name = (params[:provider] || :google).to_sym
+      raise ProviderNotFound, name.to_s unless Shakha.config.providers.include?(name)
+
+      Shakha::Providers.resolve(name)
+    end
+
+    # Built from the engine's actual mount point, so Shakha works no matter
+    # where the host app mounts it.
+    def callback_redirect_uri(provider)
+      origin = URI.parse(Shakha.config.app_origin)
+      callback_url(provider: provider.provider_name,
+                   host: origin.host, port: origin.port, protocol: origin.scheme)
     end
 
     def find_or_create_user(provider_name, identity)
-      Shakha::User.find_or_create_by!(
+      user = Shakha::User.find_or_initialize_by(
         provider: provider_name.to_s,
         uid: identity[:uid]
-      ) do |user|
-        user.client = find_or_create_client
-        user.email = identity[:email]
-        user.name = identity[:name]
-        user.picture = identity[:picture]
-      end
+      )
+      user.email = identity[:email]
+      user.name = identity[:name]
+      user.picture = identity[:picture]
+      user.save!
+      user
     end
 
     def create_session(user)
       Shakha::Session.create!(
         user: user,
-        client: find_or_create_client,
         ip_address: request.remote_ip,
         user_agent: request.user_agent
       )
@@ -104,19 +121,30 @@ module Shakha
     def build_return_url(return_to, session_record)
       uri = URI.parse(return_to || "/")
       existing = URI.decode_www_form(uri.query || "").to_h
-      existing["token"] = session_record.token
-      existing["expires_at"] = session_record.expires_at.iso8601
+
+      if Shakha.config.redirect_token_delivery == :token
+        existing["token"] = session_record.token
+        existing["expires_at"] = session_record.expires_at.iso8601
+      else
+        existing["code"] = session_record.generate_exchange_code!
+      end
+
       uri.query = URI.encode_www_form(existing)
       uri.to_s
     end
 
     def handle_auth_failure(exception, pkce_result)
+      ActiveSupport::Notifications.instrument(
+        "shakha.auth_failure",
+        provider: params[:provider]&.to_sym, error: exception.class.name
+      )
       return_to = pkce_result&.dig(:return_to) || "/"
 
       if request.format.json? || api_request?
         render json: { error: user_facing_error(exception) }, status: :unauthorized
       else
-        redirect_to "#{return_to}?error=#{URI.encode_www_form_component(user_facing_error(exception))}"
+        redirect_to "#{return_to}?error=#{URI.encode_www_form_component(user_facing_error(exception))}",
+                    allow_other_host: true
       end
     end
 
@@ -145,14 +173,6 @@ module Shakha
       Shakha.config.allowed_redirect_origins&.include?(origin) || false
     end
 
-    def find_or_create_client
-      origin = request.origin || Shakha.config.app_origin
-      origin_uri = URI.parse(origin).origin
-      Shakha::Client.find_or_create_by!(origin: origin_uri) do |client|
-        client.name = URI.parse(origin).host
-      end
-    end
-
     def user_facing_error(exception)
       case exception
       when PKCEError then "Authentication failed. Please try again."

data/app/controllers/shakha/session_controller.rb

@@ -2,6 +2,19 @@
 
 module Shakha
   class SessionController < ApplicationController
+    skip_before_action :verify_authenticity_token, only: :exchange
+
+    # POST /session/exchange — swap a one-time code for the session token.
+    def exchange
+      session_record = Shakha::Session.exchange(params[:code])
+      if session_record
+        render json: { token: session_record.token,
+                       expires_at: session_record.expires_at.iso8601 }
+      else
+        render json: { error: "Invalid or expired code" }, status: :unauthorized
+      end
+    end
+
     def show
       unless signed_in?
         return render json: { error: "Authentication required" }, status: :unauthorized

data/app/controllers/shakha/sessions_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Shakha
+  class SessionsController < ApplicationController
+    before_action :authenticate!
+
+    # GET /sessions — the current user's active sessions, newest first.
+    def index
+      sessions = Shakha::Session.for(current_user).map do |session_record|
+        {
+          id: session_record.id,
+          ip_address: session_record.ip_address,
+          user_agent: session_record.user_agent,
+          created_at: session_record.created_at.iso8601,
+          current: session_record.id == current_session.id
+        }
+      end
+
+      render json: { sessions: sessions }
+    end
+
+    # DELETE /sessions/:id — revoke one of the current user's sessions.
+    def destroy
+      session_record = Shakha::Session.for(current_user).find_by(id: params[:id])
+      return render json: { error: "Session not found" }, status: :not_found unless session_record
+
+      session_record.destroy
+      cookies.delete(:shakha_session_token) if session_record.id == current_session.id
+
+      render json: { status: "revoked" }
+    end
+  end
+end

data/app/models/shakha/session.rb

@@ -5,12 +5,17 @@ module Shakha
     self.table_name = "shakha_sessions"
 
     belongs_to :user, class_name: "Shakha::User", optional: true
-    belongs_to :client, class_name: "Shakha::Client"
 
     before_create :generate_token
 
     scope :active, -> { where("created_at > ?", Shakha.config.session_lifetime.ago) }
 
+    def self.for(user)
+      active.where(user: user).order(created_at: :desc, id: :desc)
+    end
+
+    EXCHANGE_CODE_TTL = 60.seconds
+
     def expired?
       created_at < Shakha.config.session_lifetime.ago
     end
@@ -19,10 +24,34 @@ module Shakha
       created_at + Shakha.config.session_lifetime
     end
 
+    # Issues a short-lived, single-use code the frontend swaps for the session
+    # token, so the token itself never travels in a redirect URL.
+    def generate_exchange_code!
+      update_columns(
+        exchange_code: SecureRandom.urlsafe_base64(32),
+        exchange_code_expires_at: EXCHANGE_CODE_TTL.from_now
+      )
+      exchange_code
+    end
+
+    # Redeems a code for its session, atomically clearing it so a code can be
+    # used at most once even under concurrent requests.
+    def self.exchange(code)
+      return nil if code.blank?
+
+      session = active.where(exchange_code: code)
+                      .where("exchange_code_expires_at > ?", Time.current).first
+      return nil unless session
+
+      claimed = where(id: session.id).where.not(exchange_code: nil)
+                .update_all(exchange_code: nil, exchange_code_expires_at: nil)
+      claimed == 1 ? session : nil
+    end
+
     private
 
     def generate_token
       self.token ||= SecureRandom.urlsafe_base64(32)
     end
   end
-end
+end

data/app/models/shakha/user.rb

@@ -4,12 +4,10 @@ module Shakha
   class User < ::ApplicationRecord
     self.table_name = "shakha_users"
 
-    belongs_to :client, class_name: "Shakha::Client"
     has_many :sessions, class_name: "Shakha::Session", dependent: :destroy
 
     validates :provider, presence: true
     validates :uid, presence: true
     validates :uid, uniqueness: { scope: :provider }
-    validates :email, uniqueness: { scope: :client_id }, allow_blank: true
   end
-end
+end

data/app/views/shakha/auth/new.html.erb

@@ -1,4 +1,4 @@
-<% content_for :title, "Sign in — #{@client&.name || 'Shakha'}" %>
+<% content_for :title, "Sign in — #{Shakha.config.app_name}" %>
 
 <div class="sh-layout sh-animate-fade">
   <div class="sh-card sh-animate-slide">
@@ -6,18 +6,18 @@
       <div class="sh-brand">
         <div class="sh-brand__icon">S</div>
         <div>
-          <div class="sh-brand__name"><%= @client&.name || "Shakha" %></div>
+          <div class="sh-brand__name"><%= Shakha.config.app_name %></div>
           <div class="sh-brand__subtitle">Secure authentication</div>
         </div>
       </div>
 
       <h1 class="sh-heading sh-heading--center">Welcome back</h1>
-      <p class="sh-subheading">Sign in to continue to <%= @client&.name || "your app" %></p>
+      <p class="sh-subheading">Sign in to continue to <%= Shakha.config.app_name %></p>
     </div>
 
     <div class="sh-card__body">
       <% @providers.each do |provider| %>
-        <%= link_to shakha.send("#{provider}_authorize_path"),
+        <%= link_to "/auth/shakha/#{provider}",
                     class: "sh-btn sh-btn--#{provider}",
                     data: { turbo: false } do %>
           Continue with <%= provider.to_s.titleize %>

data/app/views/shakha/layouts/shakha.html.erb

@@ -4,7 +4,7 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title><%= yield(:title).presence || "Shakha" %></title>
-  <%= stylesheet_link_tag "shakha", "data-turbo-track": "reload" %>
+  <style><%= Shakha::Engine.root.join("app/assets/stylesheets/shakha.css").read.html_safe %></style>
   <%= csrf_meta_tags %>
   <meta name="theme-color" content="#0f0f23" media="(prefers-color-scheme: dark)">
   <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module Shakha
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      source_root File.expand_path("templates", __dir__)
+
+      BUILT_IN_PROVIDERS = %w[google github].freeze
+
+      desc "Installs Shakha — headless OAuth broker for Rails"
+
+      class_option :providers, type: :string, default: "google,github",
+                               desc: "Comma-separated providers to configure (#{BUILT_IN_PROVIDERS.join(', ')})"
+
+      def validate_providers
+        unknown = providers - BUILT_IN_PROVIDERS
+        raise Thor::Error, "Unknown provider(s): #{unknown.join(', ')}. Choose from: #{BUILT_IN_PROVIDERS.join(', ')}" if unknown.any?
+        raise Thor::Error, "--providers must name at least one provider" if providers.empty?
+      end
+
+      def copy_migration
+        migration_template "create_shakha_tables.rb.erb", "db/migrate/create_shakha_tables.rb"
+      end
+
+      def copy_initializer
+        path = "config/initializers/shakha.rb"
+        if File.exist?(File.join(destination_root, path)) && !options[:force]
+          say_status :exist, path, :blue
+          return
+        end
+
+        template "shakha.rb.erb", path
+      end
+
+      def inject_application_controller
+        path = "app/controllers/application_controller.rb"
+        full_path = File.join(destination_root, path)
+        return unless File.exist?(full_path)
+        return if File.read(full_path).include?("Shakha::ControllerHelpers")
+
+        inject_into_class path, "ApplicationController", "  include Shakha::ControllerHelpers\n"
+        say_status :insert, "ApplicationController -> include Shakha::ControllerHelpers", :green
+      end
+
+      def enable_cookies_for_api_mode
+        return unless api_only_app?
+        return if File.read(File.join(destination_root, "config/application.rb")).include?("ActionDispatch::Cookies")
+
+        application "config.middleware.use ActionDispatch::Cookies"
+        say_status :insert, "config/application.rb -> ActionDispatch::Cookies (API mode)", :green
+      end
+
+      def print_post_install
+        origin = Shakha.config.app_origin || "http://localhost:3000"
+
+        say ""
+        say "  Shakha installed!", :green
+        say "  #{'─' * 50}", :green
+        say ""
+        say "  1. Set environment variables:", :yellow
+        providers.each do |provider|
+          say "     #{provider.upcase}_CLIENT_ID / #{provider.upcase}_CLIENT_SECRET", :cyan
+        end
+        say ""
+        say "  2. For SPA: set ALLOWED_REDIRECT_ORIGINS", :yellow
+        say ""
+        say "  3. Run migrations:", :yellow
+        say "     bin/rails db:migrate", :cyan
+        say ""
+        say "  4. OAuth app redirect / callback URLs:", :yellow
+        providers.each do |provider|
+          say "     #{origin}/auth/shakha/#{provider}/callback", :cyan
+        end
+        say "  #{'─' * 50}", :green
+        say ""
+        say "  Tell your frontend dev:", :cyan
+        say "    Sign in:  #{origin}/auth/shakha/#{providers.first}"
+        say "    Session:  GET #{origin}/auth/shakha/session"
+        say "    Auth:     Authorization: Bearer <token>"
+        say "    Sign out: DELETE #{origin}/auth/shakha/sign_out"
+        say ""
+      end
+
+      private
+
+      def providers
+        @providers ||= options[:providers].to_s.split(",").map { |p| p.strip.downcase }.reject(&:empty?).uniq
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      def api_only_app?
+        path = File.join(destination_root, "config/application.rb")
+        File.exist?(path) && File.read(path).include?("config.api_only = true")
+      end
+    end
+  end
+end

data/lib/generators/shakha/install/templates/create_shakha_tables.rb.erb

@@ -0,0 +1,27 @@
+class CreateShakhaTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :shakha_users do |t|
+      t.string :provider, null: false
+      t.string :uid, null: false
+      t.string :email
+      t.string :name
+      t.string :picture
+      t.timestamps
+      t.index [:provider, :uid], unique: true
+      t.index :email
+    end
+
+    create_table :shakha_sessions do |t|
+      t.references :user, foreign_key: { to_table: :shakha_users }
+      t.string :token, null: false
+      t.string :exchange_code
+      t.datetime :exchange_code_expires_at
+      t.string :ip_address
+      t.string :user_agent
+      t.timestamps
+      t.index :token, unique: true
+      t.index :exchange_code, unique: true
+      t.index :created_at
+    end
+  end
+end

data/lib/generators/shakha/install/templates/shakha.rb.erb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+Shakha.setup do |config|
+  # Your Rails app's origin
+  config.app_origin = ENV.fetch("APP_ORIGIN", "http://localhost:3000")
+
+  # Name shown on the built-in sign-in page (Rails monolith flow)
+  # config.app_name = "My App"
+
+  # Allowed frontend origins for the SPA redirect
+  config.allowed_redirect_origins = ENV.fetch("ALLOWED_REDIRECT_ORIGINS", "").split(",")
+
+  # How the session token reaches the frontend after OAuth (default:
+  # :exchange_code). With :exchange_code the callback redirects with a
+  # one-time ?code=..., which the frontend swaps for the token:
+  #   POST /auth/shakha/session/exchange  { "code": "..." }
+  #     -> { "token": "...", "expires_at": "..." }
+  # Set :token to put the token directly in the redirect URL instead
+  # (simpler, but the token is exposed in history/logs/Referer).
+  # config.redirect_token_delivery = :token
+
+<% if providers.include?("google") -%>
+  # Google OAuth
+  config.google_client_id     = ENV["GOOGLE_CLIENT_ID"]
+  config.google_client_secret = ENV["GOOGLE_CLIENT_SECRET"]
+
+<% end -%>
+<% if providers.include?("github") -%>
+  # GitHub OAuth
+  config.github_client_id     = ENV["GITHUB_CLIENT_ID"]
+  config.github_client_secret = ENV["GITHUB_CLIENT_SECRET"]
+
+<% end -%>
+  # Enabled providers
+  config.providers = [ <%= providers.map { |p| ":#{p}" }.join(", ") %> ]
+
+  # Session lifetime (default: 30 days)
+  # config.session_lifetime = 30.days
+
+  # Rate limiting (default: false)
+  # config.rate_limiting_enabled = true
+end

data/lib/shakha/config.rb

@@ -3,6 +3,7 @@
 module Shakha
   class Config
     attr_accessor :app_origin,
+                  :app_name,
                   :google_client_id,
                   :google_client_secret,
                   :github_client_id,
@@ -10,12 +11,15 @@ module Shakha
                   :providers,
                   :session_lifetime,
                   :rate_limiting_enabled,
-                  :allowed_redirect_origins
+                  :allowed_redirect_origins,
+                  :redirect_token_delivery
 
     def initialize
+      @app_name = "Shakha"
       @session_lifetime = 30.days
       @rate_limiting_enabled = false
-      @providers = [:google]
+      @providers = [ :google ]
+      @redirect_token_delivery = :exchange_code
     end
   end
 end

data/lib/shakha/config_validator.rb

@@ -2,12 +2,21 @@
 
 module Shakha
   module ConfigValidator
+    BUILT_IN_CREDENTIALS = {
+      google: %i[google_client_id google_client_secret],
+      github: %i[github_client_id github_client_secret]
+    }.freeze
+
     class << self
       def validate!(config)
         missing = []
         missing << "APP_ORIGIN" unless config.app_origin.present?
-        missing << "GOOGLE_CLIENT_ID" unless config.google_client_id.present?
-        missing << "GOOGLE_CLIENT_SECRET" unless config.google_client_secret.present?
+
+        Array(config.providers).each do |provider|
+          BUILT_IN_CREDENTIALS.fetch(provider.to_sym, []).each do |attr|
+            missing << attr.to_s.upcase unless config.public_send(attr).present?
+          end
+        end
 
         unless missing.empty?
           message = "Shakha: missing required configuration: #{missing.join(', ')}"

data/lib/shakha/controller_helpers.rb

@@ -7,7 +7,7 @@ module Shakha
     extend ActiveSupport::Concern
 
     included do
-      helper_method :current_user, :current_session, :signed_in?
+      helper_method :current_session, :current_user, :signed_in? if respond_to?(:helper_method)
     end
 
     private
@@ -28,13 +28,15 @@ module Shakha
     def authenticate!
       return if signed_in?
 
-      respond_to do |format|
-        format.html { redirect_to shakha.new_auth_path(return_to: request.fullpath) }
-        format.json { render json: { error: "Authentication required" }, status: :unauthorized }
+      if request.format.json?
+        render json: { error: "Authentication required" }, status: :unauthorized
+      else
+        redirect_to "/auth/shakha?return_to=#{CGI.escape(request.fullpath)}"
       end
     end
 
     def find_session_from_cookie
+      return unless respond_to?(:cookies)
       token = cookies.encrypted[:shakha_session_token]
       return unless token
       Shakha::Session.active.find_by(token: token)

data/lib/shakha/engine.rb

@@ -11,13 +11,18 @@ module Shakha
     routes do
       root to: "auth#new"
 
-      get  ":provider/authorize" => "auth#authorize"
-      get  ":provider/callback"  => "auth#callback"
-      delete "sign_out"           => "auth#destroy"
-      get  "error"                => "auth#error"
+      # Static routes MUST come before dynamic :provider routes
+      get  "session"          => "session#show"
+      get  "session/check"    => "session#check"
+      post "session/exchange" => "session#exchange"
+      get    "sessions"       => "sessions#index",   defaults: { format: :json }
+      delete "sessions/:id"   => "sessions#destroy", defaults: { format: :json }, as: :revoke_session
+      delete "sign_out"       => "auth#destroy"
+      get "error"             => "auth#error"
 
-      get  "session"        => "session#show"
-      get  "session/check"  => "session#check"
+      # Dynamic provider routes
+      get ":provider"          => "auth#authorize", as: :authorize
+      get ":provider/callback" => "auth#callback",  as: :callback
     end
   end
-end
+end

data/lib/shakha/error_handler.rb

@@ -8,6 +8,7 @@ module Shakha
 
     included do
       rescue_from ActiveRecord::RecordNotFound, with: :not_found
+      rescue_from Shakha::ProviderNotFound, with: :provider_not_found
       rescue_from Shakha::PKCEError, with: :bad_request
       rescue_from Shakha::OAuthError, with: :bad_gateway
     end
@@ -18,6 +19,10 @@ module Shakha
       render json: { error: exception.message }, status: :not_found
     end
 
+    def provider_not_found(_exception)
+      render json: { error: "Unknown provider" }, status: :not_found
+    end
+
     def unauthorized(exception)
       render json: { error: "Unauthorized" }, status: :unauthorized
     end
@@ -31,4 +36,4 @@ module Shakha
       render json: { error: "Authentication service unavailable" }, status: :bad_gateway
     end
   end
-end
+end

data/lib/shakha/pkce.rb

@@ -14,7 +14,7 @@ module Shakha
 
     class << self
       def generate_code_verifier
-        SecureRandom.urlsafe_base64(CODE_VERIFIER_LENGTH, padding: false)
+        SecureRandom.urlsafe_base64(CODE_VERIFIER_LENGTH, false)
       end
 
       def generate_code_challenge(verifier)
@@ -32,7 +32,9 @@ module Shakha
       challenge = PKCEMixin.generate_code_challenge(verifier)
       state = SecureRandom.urlsafe_base64(32)
       nonce = SecureRandom.urlsafe_base64(32)
-      return_to = params[:return_to] || "/"
+      # sanitize_return_to is provided by the including controller (AuthController);
+      # validating here means the stored return_to is always safe to redirect to.
+      return_to = sanitize_return_to(params[:return_to])
 
       pkce_record = {
         verifier: verifier,
@@ -81,5 +83,4 @@ module Shakha
   end
 
   class PKCEError < StandardError; end
-  class GoogleOAuthError < StandardError; end
-end
+end