shakha 0.3.0 → 0.8.0

data/app/models/shakha/session.rb

@@ -5,12 +5,13 @@ 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) }
 
+    EXCHANGE_CODE_TTL = 60.seconds
+
     def expired?
       created_at < Shakha.config.session_lifetime.ago
     end
@@ -19,10 +20,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,84 @@
+# 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__)
+
+      desc "Installs Shakha — headless OAuth broker for Rails"
+
+      def copy_migration
+        migration_template "create_shakha_tables.rb.erb", "db/migrate/create_shakha_tables.rb"
+      end
+
+      def copy_initializer
+        template "shakha.rb.erb", "config/initializers/shakha.rb"
+      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?
+
+        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
+        say "     GOOGLE_CLIENT_ID", :cyan
+        say "     GOOGLE_CLIENT_SECRET", :cyan
+        say ""
+        say "  2. (Optional) GitHub:", :yellow
+        say "     GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET", :cyan
+        say ""
+        say "  3. For SPA: set ALLOWED_REDIRECT_ORIGINS", :yellow
+        say ""
+        say "  4. Run migrations:", :yellow
+        say "     bin/rails db:migrate", :cyan
+        say ""
+        say "  5. Google Cloud Console redirect URI:", :yellow
+        say "     #{origin}/auth/shakha/google/callback", :cyan
+        say ""
+        say "  6. GitHub OAuth App callback URL:", :yellow
+        say "     #{origin}/auth/shakha/github/callback", :cyan
+        say "  #{'─' * 50}", :green
+        say ""
+        say "  Tell your frontend dev:", :cyan
+        say "    Sign in:  #{origin}/auth/shakha/google"
+        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 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,39 @@
+# 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
+
+  # Google OAuth (required)
+  config.google_client_id     = ENV["GOOGLE_CLIENT_ID"]
+  config.google_client_secret = ENV["GOOGLE_CLIENT_SECRET"]
+
+  # GitHub OAuth (optional — remove from providers if unused)
+  config.github_client_id     = ENV["GITHUB_CLIENT_ID"]
+  config.github_client_secret = ENV["GITHUB_CLIENT_SECRET"]
+
+  # Enabled providers
+  # config.providers = [:google]                # Google only
+  config.providers = [:google, :github]          # Both
+
+  # 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/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,16 @@ 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"
+      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

data/lib/shakha/providers/base.rb

@@ -3,7 +3,7 @@
 module Shakha
   module Providers
     class Base
-      def authorize_url(state:, code_challenge:, redirect_uri:)
+      def authorize_url(state:, code_challenge:, redirect_uri:, nonce: nil)
         raise NotImplementedError
       end
 
@@ -11,7 +11,7 @@ module Shakha
         raise NotImplementedError
       end
 
-      def identity_from_response(token_response)
+      def identity_from_response(token_response, expected_nonce: nil)
         raise NotImplementedError
       end
 

data/lib/shakha/providers/github.rb

@@ -14,7 +14,9 @@ module Shakha
         :github
       end
 
-      def authorize_url(state:, code_challenge:, redirect_uri:)
+      # GitHub OAuth has no nonce concept; the keyword is accepted for a
+      # uniform provider interface and ignored.
+      def authorize_url(state:, code_challenge:, redirect_uri:, nonce: nil)
         params = {
           client_id: Shakha.config.github_client_id,
           redirect_uri: redirect_uri,
@@ -36,7 +38,7 @@ module Shakha
         JSON.parse(response.body)
       end
 
-      def identity_from_response(token_response)
+      def identity_from_response(token_response, expected_nonce: nil)
         access_token = token_response["access_token"]
         raise OAuthError, "No access_token received" unless access_token
 

data/lib/shakha/providers/google.rb

@@ -13,7 +13,7 @@ module Shakha
         :google
       end
 
-      def authorize_url(state:, code_challenge:, redirect_uri:)
+      def authorize_url(state:, code_challenge:, redirect_uri:, nonce: nil)
         params = {
           client_id: Shakha.config.google_client_id,
           redirect_uri: redirect_uri,
@@ -24,7 +24,7 @@ module Shakha
           state: state,
           access_type: "offline",
           prompt: "consent",
-          nonce: SecureRandom.urlsafe_base64(32)
+          nonce: nonce
         }
 
         "#{AUTHORIZE_URL}?#{URI.encode_www_form(params)}"
@@ -43,11 +43,15 @@ module Shakha
         JSON.parse(response.body)
       end
 
-      def identity_from_response(token_response)
+      def identity_from_response(token_response, expected_nonce: nil)
         id_token = token_response["id_token"]
         raise OAuthError, "No id_token received" unless id_token
 
+        # Signature is not re-verified: the token comes directly from Google's
+        # token endpoint over a TLS connection we initiated, so its provenance
+        # is the transport. The claims below still need checking.
         payload = JWT.decode(id_token, nil, false)[0]
+        verify_claims!(payload, expected_nonce)
 
         {
           provider: :google,
@@ -64,6 +68,25 @@ module Shakha
 
       private
 
+      VALID_ISSUERS = [ "https://accounts.google.com", "accounts.google.com" ].freeze
+
+      def verify_claims!(payload, expected_nonce)
+        unless VALID_ISSUERS.include?(payload["iss"])
+          raise OAuthError, "ID token issuer mismatch"
+        end
+
+        unless payload["aud"] == Shakha.config.google_client_id
+          raise OAuthError, "ID token audience mismatch"
+        end
+
+        raise OAuthError, "ID token expired" if payload["exp"].to_i <= Time.now.to_i
+
+        if expected_nonce.present? &&
+           !ActiveSupport::SecurityUtils.secure_compare(payload["nonce"].to_s, expected_nonce)
+          raise OAuthError, "ID token nonce mismatch"
+        end
+      end
+
       def http_post(url, body)
         uri = URI.parse(url)
         http = Net::HTTP.new(uri.host, uri.port)

data/lib/shakha/rate_limiter.rb

@@ -5,8 +5,8 @@ module Shakha
     extend ActiveSupport::Concern
 
     included do
-      before_action :check_rate_limit_authorize, only: [:authorize]
-      before_action :check_rate_limit_token, only: [:token]
+      before_action :check_rate_limit_authorize, only: [ :authorize ]
+      before_action :check_rate_limit_callback, only: [ :callback ]
     end
 
     private
@@ -15,15 +15,15 @@ module Shakha
       check_rate_limit("authorize", max: 20, period: 1.minute)
     end
 
-    def check_rate_limit_token
-      check_rate_limit("token", max: 10, period: 1.minute)
+    def check_rate_limit_callback
+      check_rate_limit("callback", max: 10, period: 1.minute)
     end
 
     def check_rate_limit(key, max:, period:)
       return unless Shakha.config.rate_limiting_enabled
 
       cache_key = "shakha-rate:#{key}:#{request.remote_ip}"
-      count = Rails.cache.increment(cache_key, 1, expires_in: period.seconds)
+      count = Rails.cache.increment(cache_key, 1, expires_in: period.seconds) || 1
 
       if count > max
         render json: { error: "Too many requests. Try again later." }, status: :too_many_requests

data/lib/shakha/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Shakha
-  VERSION = "0.3.0"
-end
+  VERSION = "0.8.0"
+end

data/lib/shakha.rb

@@ -24,4 +24,5 @@ module Shakha
   class ConfigurationError < StandardError; end
   class PKCEError < StandardError; end
   class OAuthError < StandardError; end
-end
+  class ProviderNotFound < StandardError; end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakha
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Asrat
@@ -13,16 +13,22 @@ dependencies:
   name: jwt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.10.3
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.10.3
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -64,25 +70,26 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '10'
 description: |
-  Shakha is a headless authentication broker gem for Rails that handles Google OAuth 2.0
-  with PKCE security. It provides domain-scoped user identifiers via pairwise subjects,
-  ensuring the same Google account gets different IDs across different applications.
-
-  Built DHH-style: database sessions (no Redis), Turbo native (zero JS), and a single
-  "Continue with Google" button. Works as an embedded Rails engine or standalone service.
+  Shakha is a headless OAuth broker engine for Rails APIs and monoliths.
+  Your frontend does a single redirect; Shakha runs the OAuth dance
+  (PKCE, state) against Google or GitHub, stores a revocable
+  database-backed session, and redirects back with a session token usable
+  via encrypted cookie or Authorization: Bearer. No JWTs issued, no Redis,
+  no frontend SDK. Pre-1.0: APIs and security posture still evolving.
 email:
-- asrat@example.com
+- asratextras77@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
+- SECURITY.md
 - app/assets/stylesheets/shakha.css
 - app/controllers/shakha/application_controller.rb
 - app/controllers/shakha/auth_controller.rb
 - app/controllers/shakha/session_controller.rb
-- app/models/shakha/client.rb
 - app/models/shakha/session.rb
 - app/models/shakha/user.rb
 - app/views/shakha/auth/callback.html.erb
@@ -90,9 +97,9 @@ files:
 - app/views/shakha/auth/new.html.erb
 - app/views/shakha/errors/show.html.erb
 - app/views/shakha/layouts/shakha.html.erb
-- lib/generators/shakha/install_generator.rb
-- lib/generators/shakha/templates/initializer.rb.erb
-- lib/generators/shakha/templates/migration.rb.erb
+- lib/generators/shakha/install/install_generator.rb
+- lib/generators/shakha/install/templates/create_shakha_tables.rb.erb
+- lib/generators/shakha/install/templates/shakha.rb.erb
 - lib/shakha.rb
 - lib/shakha/config.rb
 - lib/shakha/config_validator.rb
@@ -106,11 +113,15 @@ files:
 - lib/shakha/providers/google.rb
 - lib/shakha/rate_limiter.rb
 - lib/shakha/version.rb
-homepage: https://shakha.dev
+homepage: https://github.com/Asrat77/shakha
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://shakha.dev
+  homepage_uri: https://github.com/Asrat77/shakha
+  source_code_uri: https://github.com/Asrat77/shakha
+  changelog_uri: https://github.com/Asrat77/shakha/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Asrat77/shakha/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -127,5 +138,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Headless Google OAuth broker with PKCE, pairwise subjects, and zero JavaScript
+summary: SPA-first OAuth session broker for Rails — one redirect, one token, done
 test_files: []

data/app/models/shakha/client.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Shakha
-  class Client < ::ApplicationRecord
-    self.table_name = "shakha_clients"
-
-    has_many :sessions, class_name: "Shakha::Session", dependent: :restrict_with_error
-    has_many :users, class_name: "Shakha::User", dependent: :nullify
-
-    validates :origin, presence: true, uniqueness: true
-
-    def self.find_by_origin!(origin)
-      find_by!(origin: URI.parse(origin).origin)
-    end
-  end
-end