shakha 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82e8c2eda1b9b817ce681d22f4e5a331d15e0c59588c972067d1fa432db03b62
-  data.tar.gz: 979e1a3513ac57e1b1d6a81fffd954c1fb911fbb8d0cca729b65ce161bbe9f44
+  metadata.gz: 7ff145da09437c51afcef947199c0225b2fb557a6e0559e1792e07d7af646250
+  data.tar.gz: d95b3e5a110d49b7defde447935240d27e0faf2a76e3874b4b05dba7f174336e
 SHA512:
-  metadata.gz: 80529b985eb5d490eada76a0829a9aa3311ec30af375c83b4f33ef0cb5e2399e4b1f75242bb8d5ee843e8b49d583da36ac84f53d0953b33d96868bf80dd9bb33
-  data.tar.gz: 15777157e9a5fb3746019943f760b57ef92a9b10680056d0178f65d42392ed0391da8f1c3bf72c90e5c32d2c6110dac3420a8e1062cc0cf3d999b50309888c3d
+  metadata.gz: f61b03a6afdb461afde6274f2892b54f1f7979369023a1421b5037f99b333351c5c7bca5194c7f76db22d9f516594c4c737d96f501f82b8663c2ad5fafa472d1
+  data.tar.gz: 344441bf4fcfc2dc8061bb25fab5dfbe64485919405658cbbd16c376ffcdddc685682e0256d7e2fe2401c29e22a8122a157439e111748ccb8d6e0b8c266dc9a4

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/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,8 @@ 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)}"
+      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 +56,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 +155,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 +184,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

@@ -27,7 +27,11 @@ 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
   end
 end

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"

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/version.rb

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

data/lib/shakha.rb

@@ -2,6 +2,7 @@
 
 require "shakha/version"
 require "shakha/config"
+require "shakha/config_validator"
 require "shakha/pairwise"
 require "shakha/jwt_handler"
 require "shakha/pkce"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakha
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 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: []
@@ -67,6 +97,7 @@ files:
 - lib/generators/shakha/templates/migration.rb.erb
 - lib/shakha.rb
 - lib/shakha/config.rb
+- lib/shakha/config_validator.rb
 - lib/shakha/controller_helpers.rb
 - lib/shakha/engine.rb
 - lib/shakha/error_handler.rb
@@ -96,5 +127,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: []