shakha 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f67f490e63b0d03cfa0d2abd6b31e68ced7a20e17093b6ccc77f15209b4a2cd
-  data.tar.gz: 75edc086b7684691be80bc23ed40950d839a1c26b4070edcbe14447153d61995
+  metadata.gz: d366a8476de38c1c5ba4a9a1b5cc286b96ef0f99c20e08101c94a4048621a63c
+  data.tar.gz: 7a79e8f4493e93a4b1d6e2d9711ad0bbbd9eede57fede0de68ce667d184d82a9
 SHA512:
-  metadata.gz: 3797ed65b6d60130ac0afbe7dcb11790cacb4ab46feff2d74125575377a8b633aa290b5db2edf1d61b8fa87f3c66ce3980389424cca5d4d8394b729d67012a20
-  data.tar.gz: 9cc96c35365fdee1025a878d7abf344f0755e37cd14f94995566723a27f7a978e86532f4065a34ca9eec0b472c1cfd879509ee4f22c6c9faf6948fc5f17e326c
+  metadata.gz: 1da077fb10311c211402e86cc09525bc1ac6aabf0d78000952d493314f4b5f47e54d77b7ee00615483f5aefb6c29e1f0732997fa363fcfe84b4856466b0f4234
+  data.tar.gz: 17825d89cd29b0a4e63ed1b4a504e4a4c2c5fa91696d77dfccbbedbde1e0ff80ba2ee739f9916f43671a9b71f5345244c73956bfa464087a97eec58a07626ed8

data/CHANGELOG.md

@@ -7,6 +7,29 @@ versions may include breaking changes; these are called out below.
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-10-03
+
+Developer experience and adoption.
+
+### Added
+- `ActiveSupport::Notifications` events: `shakha.sign_in`, `shakha.auth_failure`,
+  and `shakha.sign_out`, documented in `docs/instrumentation.md`.
+- `Shakha::Providers.register(name, klass)` for third-party providers, plus a
+  provider-writing guide (`docs/providers.md`) with a worked GitLab example.
+- `GET /sessions` lists the current user's active sessions (flagging the
+  requesting one) and `DELETE /sessions/:id` revokes one of them.
+  `Shakha::Session.for(user)` returns a user's active sessions newest first.
+- Installer `--providers=google,github` option; the initializer only includes
+  the chosen providers.
+- `examples/rails-api-react`: a runnable Rails API + Vite/React demo, booted in CI.
+
+### Changed
+- Re-running `rails generate shakha:install` no longer creates a second
+  migration, overwrites an existing initializer, or re-adds the cookie
+  middleware.
+- Configuration validation now requires credentials only for enabled built-in
+  providers. A GitHub-only app no longer needs `GOOGLE_CLIENT_ID`.
+
 ## [0.8.0] — 2026-07-27
 
 First public release of the reworked gem.
@@ -94,7 +117,8 @@ installs of the intermediate 0.6.0 to migrate.
 - Initial prototype: Google OAuth broker with PKCE, database sessions, and a
   sign-in page.
 
-[Unreleased]: https://github.com/Asrat77/shakha/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/Asrat77/shakha/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/Asrat77/shakha/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/Asrat77/shakha/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/Asrat77/shakha/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/Asrat77/shakha/compare/v0.5.0...v0.6.0

data/README.md

@@ -53,7 +53,10 @@ bin/rails db:migrate
 
 The generator writes a migration and `config/initializers/shakha.rb`, includes
 `Shakha::ControllerHelpers` in your `ApplicationController`, and — for API-only
-apps — adds the cookie middleware Shakha needs.
+apps — adds the cookie middleware Shakha needs. It configures Google and GitHub
+by default; pass `--providers=google` (or `github`) to set up just one. Re-running
+the generator is safe: it won't add a second migration or overwrite your
+initializer.
 
 ### Configuration
 
@@ -103,6 +106,9 @@ useEffect(() => {
 }, []);
 ```
 
+For a complete runnable version (Rails API + Vite/React), see
+[examples/rails-api-react](examples/rails-api-react).
+
 ## Rails monolith usage
 
 Shakha ships a minimal sign-in page and sets an encrypted session cookie, so a
@@ -145,6 +151,8 @@ All paths are relative to the mount point (`/auth/shakha` above).
 | GET | `/session` | cookie or bearer | Current user: `{ user: {...}, session: {...} }` |
 | GET | `/session/check` | cookie or bearer | Lightweight `{ status: "active" }` / `401 { status: "expired" }` |
 | DELETE | `/sign_out` | cookie or bearer | Destroy the session |
+| GET | `/sessions` | cookie or bearer | Your active sessions, newest first: `{ sessions: [{ id, ip_address, user_agent, created_at, current }] }` |
+| DELETE | `/sessions/:id` | cookie or bearer | Revoke one of your sessions (`404` if it isn't yours) |
 
 ## Configuration reference
 
@@ -170,6 +178,13 @@ strings in the database — deleting the row revokes access immediately. See
 [SECURITY.md](SECURITY.md) for the full threat model and how to report a
 vulnerability.
 
+## Instrumentation
+
+Shakha emits `shakha.sign_in`, `shakha.auth_failure`, and `shakha.sign_out`
+through `ActiveSupport::Notifications`, so you can build an audit log without
+patching the engine. See [docs/instrumentation.md](docs/instrumentation.md) for
+payloads and examples.
+
 ## How it compares
 
 - **OmniAuth** — a Rack middleware for the OAuth handshake; you still build
@@ -184,9 +199,10 @@ vulnerability.
 
 A provider implements five methods (`provider_name`, `scopes`, `authorize_url`,
 `exchange_code`, `identity_from_response`) returning an identity hash of
-`{ provider:, uid:, email:, name:, picture: }`. See
-[`Shakha::Providers::Base`](lib/shakha/providers/base.rb) and the Google/GitHub
-implementations alongside it.
+`{ provider:, uid:, email:, name:, picture: }`, and is registered with
+`Shakha::Providers.register(:gitlab, "GitLabProvider")`. See
+[docs/providers.md](docs/providers.md) for the full contract, a worked GitLab
+example, and a testing pattern.
 
 ## Development
 

data/app/controllers/shakha/auth_controller.rb

@@ -43,6 +43,10 @@ module Shakha
       user = find_or_create_user(provider.provider_name, identity)
       session_record = create_session(user)
       set_session_cookie(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
@@ -50,7 +54,10 @@ module Shakha
     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)
 
       if request.format.json?
@@ -127,6 +134,10 @@ module Shakha
     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?

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

@@ -10,6 +10,10 @@ module Shakha
 
     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?

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

@@ -8,14 +8,31 @@ module Shakha
       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
-        template "shakha.rb.erb", "config/initializers/shakha.rb"
+        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
@@ -30,6 +47,7 @@ module Shakha
 
       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
@@ -43,26 +61,23 @@ module Shakha
         say "  #{'─' * 50}", :green
         say ""
         say "  1. Set environment variables:", :yellow
-        say "     GOOGLE_CLIENT_ID", :cyan
-        say "     GOOGLE_CLIENT_SECRET", :cyan
+        providers.each do |provider|
+          say "     #{provider.upcase}_CLIENT_ID / #{provider.upcase}_CLIENT_SECRET", :cyan
+        end
         say ""
-        say "  2. (Optional) GitHub:", :yellow
-        say "     GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET", :cyan
+        say "  2. For SPA: set ALLOWED_REDIRECT_ORIGINS", :yellow
         say ""
-        say "  3. For SPA: set ALLOWED_REDIRECT_ORIGINS", :yellow
-        say ""
-        say "  4. Run migrations:", :yellow
+        say "  3. 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 "  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/google"
+        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"
@@ -71,6 +86,10 @@ module Shakha
 
       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

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

@@ -19,17 +19,20 @@ Shakha.setup do |config|
   # (simpler, but the token is exposed in history/logs/Referer).
   # config.redirect_token_delivery = :token
 
-  # Google OAuth (required)
+<% if providers.include?("google") -%>
+  # Google OAuth
   config.google_client_id     = ENV["GOOGLE_CLIENT_ID"]
   config.google_client_secret = ENV["GOOGLE_CLIENT_SECRET"]
 
-  # GitHub OAuth (optional — remove from providers if unused)
+<% 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 = [:google]                # Google only
-  config.providers = [:google, :github]          # Both
+  config.providers = [ <%= providers.map { |p| ":#{p}" }.join(", ") %> ]
 
   # Session lifetime (default: 30 days)
   # config.session_lifetime = 30.days

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

@@ -15,6 +15,8 @@ module Shakha
       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"
 

data/lib/shakha/providers.rb

@@ -11,9 +11,29 @@ module Shakha
       github: "Shakha::Providers::GitHub"
     }.freeze
 
-    def self.resolve(name)
-      class_name = PROVIDER_MAP[name.to_sym] || raise(ConfigurationError, "Unknown provider: #{name}")
-      class_name.constantize.new
+    @registry = PROVIDER_MAP.dup
+
+    class << self
+      # Registers a provider under +name+. +klass+ is a Providers::Base
+      # subclass or its name as a String (a String survives code reloading in
+      # development). Registering an existing name replaces it.
+      def register(name, klass)
+        @registry[name.to_sym] = klass
+      end
+
+      def registered
+        @registry.keys
+      end
+
+      def resolve(name)
+        klass = @registry[name.to_sym] || raise(ConfigurationError, "Unknown provider: #{name}")
+        klass = klass.constantize if klass.is_a?(String)
+        klass.new
+      end
+
+      def reset!
+        @registry = PROVIDER_MAP.dup
+      end
     end
   end
 end

data/lib/shakha/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakha
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Asrat
@@ -90,6 +90,7 @@ files:
 - app/controllers/shakha/application_controller.rb
 - app/controllers/shakha/auth_controller.rb
 - app/controllers/shakha/session_controller.rb
+- app/controllers/shakha/sessions_controller.rb
 - app/models/shakha/session.rb
 - app/models/shakha/user.rb
 - app/views/shakha/auth/callback.html.erb