shakha 0.1.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82e8c2eda1b9b817ce681d22f4e5a331d15e0c59588c972067d1fa432db03b62
-  data.tar.gz: 979e1a3513ac57e1b1d6a81fffd954c1fb911fbb8d0cca729b65ce161bbe9f44
+  metadata.gz: 2b5eb8fae72d4a779316f8266fc29f1078bf5b31c11a5d90ae922f46d3e37928
+  data.tar.gz: 95bc2e261d8a08c818ad75b4beefc8e5a4fa97802ef5cf28afdfbe7a895cdcc1
 SHA512:
-  metadata.gz: 80529b985eb5d490eada76a0829a9aa3311ec30af375c83b4f33ef0cb5e2399e4b1f75242bb8d5ee843e8b49d583da36ac84f53d0953b33d96868bf80dd9bb33
-  data.tar.gz: 15777157e9a5fb3746019943f760b57ef92a9b10680056d0178f65d42392ed0391da8f1c3bf72c90e5c32d2c6110dac3420a8e1062cc0cf3d999b50309888c3d
+  metadata.gz: 0ee17e65c726cb0564e720fb73648b74567fcfb1edae5befbd14a16942ca877d5c007cfc8b622fed8c949211de3bf5b792fdff1190482bfdd414351b451e6204
+  data.tar.gz: 2205e02b9c9ebde26def46da665011571a5071a50bd79eaf6bb2d7075aed353d2d3b52eff1d6986113bf612ce2a6e2244e200e53b4aadf2b4c7fba8020ed354b

data/README.md

@@ -1,22 +1,72 @@
 # Shakha
 
-Minimal auth broker for Google OAuth with PKCE and pairwise subjects.
+Headless Google OAuth broker for Rails — PKCE, pairwise subjects, zero JavaScript.
 
-## Installation
+Same Google account, different IDs per application. Built DHH-style: database sessions, Turbo native, single "Continue with Google" button.
 
-Add to your Gemfile:
+## Installation
 
 ```ruby
 gem "shakha"
 ```
 
-Run the installer:
+Run the migration:
 
 ```bash
-rails generate shakha:install
+bin/rails generate migration CreateShakhaTables
+```
+
+```ruby
+class CreateShakhaTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :shakha_clients do |t|
+      t.string :name, null: false
+      t.string :origin, null: false
+      t.timestamps
+      t.index :origin, unique: true
+    end
+
+    create_table :shakha_users do |t|
+      t.references :client, null: false, foreign_key: { to_table: :shakha_clients }
+      t.string :pairwise_sub, null: false
+      t.string :email
+      t.string :name
+      t.string :picture
+      t.timestamps
+      t.index :pairwise_sub, unique: true
+      t.index :email
+    end
+
+    create_table :shakha_sessions do |t|
+      t.references :user, foreign_key: { to_table: :shakha_users }
+      t.references :client, null: false, foreign_key: { to_table: :shakha_clients }
+      t.string :token, null: false
+      t.string :jti, null: false
+      t.timestamps
+      t.index :token, unique: true
+      t.index :jti, unique: true
+      t.index :created_at
+    end
+  end
+end
+```
+
+## Configuration
+
+Create `config/initializers/shakha.rb`:
+
+```ruby
+Shakha.setup do |config|
+  config.app_origin = ENV.fetch("SHAKHA_APP_ORIGIN", "http://localhost:3000")
+  config.service_url = ENV["SHAKHA_SERVICE_URL"]        # omit for embedded mode
+  config.service_secret = ENV["SHAKHA_SERVICE_SECRET"]
+  config.google_client_id = ENV["GOOGLE_CLIENT_ID"]
+  config.google_client_secret = ENV["GOOGLE_CLIENT_SECRET"]
+  config.session_lifetime = 30.days
+end
 ```
 
-Set environment variables:
+Environment variables:
 
 ```bash
 export SHAKHA_APP_ORIGIN="https://yourapp.com"
@@ -25,60 +75,67 @@ export GOOGLE_CLIENT_ID="your-google-client-id"
 export GOOGLE_CLIENT_SECRET="your-google-client-secret"
 ```
 
-## Configuration
-
-See `config/initializers/shakha.rb` for all options.
+Google Cloud Console redirect URI: `https://yourapp.com/auth/shakha/callback`
 
 ## Usage
 
 ### Sign In
 
-Redirect users to sign in:
-
 ```erb
 <%= link_to "Sign in with Google", shakha.new_auth_path %>
 ```
 
-### Current User
-
-In controllers:
+### Protect Routes
 
 ```ruby
 class ApplicationController < ActionController::Base
   include Shakha::ControllerHelpers
+  before_action :authenticate!
 end
 ```
 
+### Current User
+
 ```ruby
 current_user        # Shakha::User or nil
-current_session    # Shakha::Session or nil
-signed_in?         # boolean
-authenticate!      # redirect to login if not signed in
+current_session     # Shakha::Session or nil
+signed_in?          # boolean
+authenticate!       # redirects to login if not signed in
 ```
 
-### Protect Routes
+### Sign Out
 
-```ruby
-class PostsController < ApplicationController
-  before_action :authenticate!
-end
+```erb
+<%= link_to "Sign out", shakha.session_path, data: { turbo_method: :delete } %>
 ```
 
 ### JWT Verification (API Mode)
 
 ```ruby
 payload = Shakha.verify_token(id_token)
-user_id = payload[:sub]
+user_id = payload[:pairwise_sub]
 ```
 
 ## Architecture
 
 - **PKCE** — S256 code challenges on every flow
-- **Pairwise subjects** — domain-scoped user identifiers
-- **ES256 JWTs** — signed with JWKS endpoint
+- **Pairwise subjects** — domain-scoped user identifiers (HMAC-SHA256)
+- **ES256 JWTs** — signed with JWKS endpoint at `.well-known/jwks.json`
+- **OpenID Connect** — `.well-known/openid-configuration` endpoint
 - **Database sessions** — DHH-style, no Redis
-- **Turbo native** — zero JS needed
+- **Turbo native** — zero JavaScript needed
+- **Embedded or standalone** — runs as Rails engine or headless service
+
+## Modes
+
+### Embedded (default)
+
+Mount in your Rails app. Routes served at `/auth/shakha`. Uses the app's own `shakha_clients` table with a single client auto-created on first request.
+
+### Service (multi-tenant)
+
+Set `SHAKHA_SERVICE_URL` and register each app's origin in `shakha_clients`. Each app gets different pairwise subjects for the same Google user.
 
 ## License
 
-MIT
+MIT

data/app/controllers/shakha/application_controller.rb

@@ -4,6 +4,8 @@ module Shakha
   class ApplicationController < ActionController::Base
     include ErrorHandler
     include ControllerHelpers
+    include RateLimiter
+    include Auditable
 
     protect_from_forgery with: :exception
 

data/app/controllers/shakha/auth_controller.rb

@@ -11,10 +11,11 @@ module Shakha
 
     def new
       @client = find_or_create_client
-      @return_to = params[:return_to] || "/"
+      @return_to = sanitize_return_to(params[:return_to])
     end
 
     def authorize
+      params[:return_to] = sanitize_return_to(params[:return_to])
       pkce = create_pkce_bundle
       @client = find_or_create_client
 
@@ -27,7 +28,12 @@ module Shakha
       pkce_result = verify_pkce!(params[:code], params[:state])
       exchange_code_for_tokens(params[:code], pkce_result[:verifier], pkce_result[:return_to])
     rescue PKCEError, GoogleOAuthError => e
-      redirect_to "/auth/shakha/error?message=#{URI.encode_www_form_component(e.message)}"
+      ActiveSupport::Notifications.instrument("shakha.sign_in_failed", {
+        reason: e.class.name,
+        ip: request.remote_ip
+      })
+      Rails.logger.warn("[Shakha] Auth error: #{e.class}: #{e.message}")
+      redirect_to "/auth/shakha/error?message=#{URI.encode_www_form_component(user_facing_error(e))}"
     end
 
     def token
@@ -54,13 +60,52 @@ module Shakha
 
     private
 
+    def sanitize_return_to(raw)
+      return "/" if raw.blank?
+
+      uri = URI.parse(raw)
+      return "/" if uri.host.present? && ![app_origin_host, client_origin_host].include?(uri.host)
+      return "/" unless uri.path.present? && uri.path.start_with?("/")
+
+      uri.path
+    rescue URI::InvalidURIError
+      "/"
+    end
+
+    def app_origin_host
+      URI.parse(Shakha.config.app_origin).host
+    end
+
+    def client_origin_host
+      URI.parse(Shakha.config.service_base_url).host
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def user_facing_error(exception)
+      case exception
+      when PKCEError
+        "Authentication failed. Please try again."
+      when GoogleOAuthError
+        "Unable to sign in with Google. Please try again later."
+      else
+        "An unexpected error occurred. Please try again."
+      end
+    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
+      if Shakha.config.embedded?
+        Shakha::Client.find_or_create_by!(origin: origin_uri) do |client|
+          client.name = URI.parse(origin).host
+        end
+      else
+        Shakha::Client.find_by!(origin: origin_uri)
       end
+    rescue ActiveRecord::RecordNotFound
+      raise ConfigurationError, "Unknown client origin: #{origin_uri}. Register this origin in shakha_clients first."
     end
 
     def build_google_auth_url(pkce)
@@ -114,12 +159,13 @@ module Shakha
 
       payload = decode_id_token(id_token)
       google_sub = payload["sub"]
-      pairwise_sub = Shakha.derive_pairwise_sub(google_sub)
 
       client = find_or_create_client
+      pairwise_sub = Shakha.derive_pairwise_sub(google_sub, client.client_id)
+
       user = Shakha::User.find_or_initialize_by(pairwise_sub: pairwise_sub, client: client)
 
-      if params[:request_pii] && payload["email"]
+      if payload["email"]
         user.assign_attributes(
           email: payload["email"],
           name: payload["name"],
@@ -142,7 +188,7 @@ module Shakha
         expires: Shakha.config.session_lifetime.from_now
       }
 
-      redirect_to return_to
+      redirect_to sanitize_return_to(return_to)
     end
 
     def exchange_code_for_id_token(code, verifier)

data/app/controllers/shakha/session_controller.rb

@@ -4,6 +4,25 @@ module Shakha
   class SessionController < ApplicationController
     skip_before_action :verify_authenticity_token, only: [:check]
 
+    def index
+      return render json: { error: "Authentication required" }, status: :unauthorized unless signed_in?
+
+      sessions = current_user.sessions.active.order(created_at: :desc)
+
+      render json: {
+        current_token: current_session.token,
+        sessions: sessions.map { |s|
+          {
+            id: s.id,
+            token: s.token,
+            created_at: s.created_at.iso8601,
+            expires_at: s.expires_at.iso8601,
+            current: s.token == current_session.token
+          }
+        }
+      }
+    end
+
     def show
       render json: {
         user_id: current_user&.pairwise_sub,
@@ -27,7 +46,28 @@ module Shakha
     def destroy
       current_session&.destroy
       cookies.delete(:shakha_session_token)
-      render json: { status: "signed_out" }
+
+      respond_to do |format|
+        format.html { redirect_to params[:return_to].presence || "/" }
+        format.json { render json: { status: "signed_out" } }
+      end
+    end
+
+    def revoke
+      return render json: { error: "Authentication required" }, status: :unauthorized unless signed_in?
+
+      session = current_user.sessions.find(params[:id])
+      session.destroy
+
+      cookies.delete(:shakha_session_token) if session.token == current_session&.token
+
+      ActiveSupport::Notifications.instrument("shakha.session_revoked", {
+        session_id: session.id,
+        user_id: current_user.id,
+        ip: request.remote_ip
+      })
+
+      render json: { status: "revoked" }
     end
   end
 end

data/lib/shakha/auditable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Shakha
+  module Auditable
+    extend ActiveSupport::Concern
+
+    included do
+      after_action :log_sign_in, only: [:callback]
+      after_action :log_sign_out, only: [:destroy]
+      after_action :log_token_exchange, only: [:token]
+    end
+
+    private
+
+    def log_sign_in
+      return unless response.successful? && @current_user
+
+      ActiveSupport::Notifications.instrument("shakha.sign_in", {
+        user_id: @current_user&.id,
+        pairwise_sub: @current_user&.pairwise_sub,
+        client_id: @current_client&.id,
+        ip: request.remote_ip,
+        user_agent: request.user_agent
+      })
+    end
+
+    def log_sign_out
+      return unless action_name == "destroy"
+
+      ActiveSupport::Notifications.instrument("shakha.sign_out", {
+        session_id: @current_session&.id,
+        user_id: @current_session&.user_id,
+        ip: request.remote_ip
+      })
+    end
+
+    def log_token_exchange
+      return unless action_name == "token"
+
+      ActiveSupport::Notifications.instrument("shakha.token_exchange", {
+        ip: request.remote_ip,
+        user_agent: request.user_agent,
+        success: response.successful?
+      })
+    end
+  end
+end

data/lib/shakha/config.rb

@@ -11,11 +11,13 @@ module Shakha
                   :session_lifetime,
                   :signing_key,
                   :verification_key,
-                  :key_id
+                  :key_id,
+                  :rate_limiting_enabled
 
     def initialize
       @session_lifetime = 30.days
       @issuer = "https://shakha.dev"
+      @rate_limiting_enabled = false
     end
 
     def embedded?

data/lib/shakha/config_validator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Shakha
+  module ConfigValidator
+    class << self
+      def validate!(config)
+        missing = []
+        missing << "SHAKHA_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?
+        missing << "SHAKHA_SERVICE_SECRET" unless config.service_secret.present?
+
+        unless missing.empty?
+          message = "Shakha: missing required configuration: #{missing.join(', ')}"
+          if Rails.env.production?
+            raise ConfigurationError, message
+          else
+            Rails.logger.warn(message)
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/shakha/engine.rb

@@ -6,6 +6,10 @@ module Shakha
 
     config.app_middleware.use Shakha::Middleware
 
+    config.after_initialize do
+      Shakha::ConfigValidator.validate!(Shakha.config)
+    end
+
     # Engine routes - these should be relative paths
     routes do
       root to: "auth#new"
@@ -16,8 +20,10 @@ module Shakha
       get "error" => "auth#error"
 
       get "session" => "session#show"
+      get "sessions" => "session#index"
       post "session/check" => "session#check"
       delete "session" => "session#destroy"
+      delete "sessions/:id" => "session#revoke"
 
       get ".well-known/jwks.json" => "jwks#show"
       get ".well-known/openid-configuration" => "openid#configuration"

data/lib/shakha/error_handler.rb

@@ -24,11 +24,12 @@ module Shakha
     end
 
     def bad_request(exception)
-      render json: { error: exception.message }, status: :bad_request
+      render json: { error: "Bad request" }, status: :bad_request
     end
 
     def bad_gateway(exception)
-      render json: { error: exception.message }, status: :bad_gateway
+      Rails.logger.error("[Shakha] Google OAuth error: #{exception.message}")
+      render json: { error: "Authentication service unavailable" }, status: :bad_gateway
     end
   end
 end

data/lib/shakha/rate_limiter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Shakha
+  module RateLimiter
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :check_rate_limit_authorize, only: [:authorize]
+      before_action :check_rate_limit_token, only: [:token]
+    end
+
+    private
+
+    def check_rate_limit_authorize
+      check_rate_limit("authorize", max: 20, period: 1.minute)
+    end
+
+    def check_rate_limit_token
+      check_rate_limit("token", 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.read(cache_key).to_i + 1
+
+      if count == 1
+        Rails.cache.write(cache_key, count, expires_in: period.seconds)
+      elsif count > max
+        render json: { error: "Too many requests. Try again later." }, status: :too_many_requests
+        return
+      else
+        Rails.cache.write(cache_key, count, expires_in: period.seconds)
+      end
+    end
+  end
+end

data/lib/shakha/version.rb

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

data/lib/shakha.rb

@@ -2,9 +2,12 @@
 
 require "shakha/version"
 require "shakha/config"
+require "shakha/config_validator"
 require "shakha/pairwise"
 require "shakha/jwt_handler"
 require "shakha/pkce"
+require "shakha/rate_limiter"
+require "shakha/auditable"
 require "shakha/error_handler"
 require "shakha/controller_helpers"
 require "shakha/middleware"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakha
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.4
 platform: ruby
 authors:
 - Asrat
@@ -30,6 +30,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -37,9 +40,36 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '10'
 description: |
-  Shakha handles Google OAuth + PKCE and gives your app a domain-scoped identity (pairwise_sub)
-  and a signed id_token. No client signup. No unnecessary scopes. Just identity.
+  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.
 email:
 - asrat@example.com
 executables: []
@@ -66,7 +96,9 @@ files:
 - lib/generators/shakha/templates/initializer.rb.erb
 - lib/generators/shakha/templates/migration.rb.erb
 - lib/shakha.rb
+- lib/shakha/auditable.rb
 - lib/shakha/config.rb
+- lib/shakha/config_validator.rb
 - lib/shakha/controller_helpers.rb
 - lib/shakha/engine.rb
 - lib/shakha/error_handler.rb
@@ -74,6 +106,7 @@ files:
 - lib/shakha/middleware.rb
 - lib/shakha/pairwise.rb
 - lib/shakha/pkce.rb
+- lib/shakha/rate_limiter.rb
 - lib/shakha/version.rb
 homepage: https://shakha.dev
 licenses:
@@ -96,5 +129,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Minimal auth broker for Google OAuth with PKCE and pairwise subjects
+summary: Headless Google OAuth broker with PKCE, pairwise subjects, and zero JavaScript
 test_files: []