shakha 0.3.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f2fb69e4f483c981312b4211c9205e9ae5d0d100a0d3d8f0d61f693478c8369
-  data.tar.gz: 6dfb50d826c90ea54ed5453d7eebad7a94bf93cea02a1bb407fbd69a61da421e
+  metadata.gz: 8f67f490e63b0d03cfa0d2abd6b31e68ced7a20e17093b6ccc77f15209b4a2cd
+  data.tar.gz: 75edc086b7684691be80bc23ed40950d839a1c26b4070edcbe14447153d61995
 SHA512:
-  metadata.gz: 1bac5c8e1d92fb2997713d5ad19d7b16327fc21ec7e7520adf09d736bbe2c15c1cb72ef7c859798cba62a8a012819a1fb4863bd6c49830cd10d98f3082d4afc9
-  data.tar.gz: 8e9ae9652bb51b48bc30623305113e75c2a1c56676ec17a4e9503f4dc9694f55cf87d1d58fa9a2aaee956e47fa8ee1ecdc35024f3500c616e228942f42efbfac
+  metadata.gz: 3797ed65b6d60130ac0afbe7dcb11790cacb4ab46feff2d74125575377a8b633aa290b5db2edf1d61b8fa87f3c66ce3980389424cca5d4d8394b729d67012a20
+  data.tar.gz: 9cc96c35365fdee1025a878d7abf344f0755e37cd14f94995566723a27f7a978e86532f4065a34ca9eec0b472c1cfd879509ee4f22c6c9faf6948fc5f17e326c

data/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Until 1.0.0, minor
+versions may include breaking changes; these are called out below.
+
+## [Unreleased]
+
+## [0.8.0] — 2026-07-27
+
+First public release of the reworked gem.
+
+### Added
+- Rewritten README, `CHANGELOG.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`,
+  issue/PR templates, and Dependabot.
+
+### Changed
+- Gemspec: accurate summary/description, GitHub homepage, `source_code_uri` /
+  `changelog_uri` / `bug_tracker_uri`, `rubygems_mfa_required`, and an explicit
+  packaged-file manifest.
+- Removed superseded planning directories from the repo (kept in git history).
+
+## [0.7.0] — 2026-07-26
+
+Security hardening. Several changes are breaking; there are no production
+installs of the intermediate 0.6.0 to migrate.
+
+### Security
+- Verify the Google ID token: the OIDC `nonce` is now threaded through the
+  authorize step and checked on callback, and the `iss`, `aud`, and `exp` claims
+  are validated. The `aud` check rejects tokens minted for other clients.
+- Deliver the session token via a single-use, 60-second exchange code by default
+  instead of placing it in the redirect URL, where it could leak into history,
+  `Referer` headers, and logs.
+- Validate `return_to` against the app origin and `allowed_redirect_origins`
+  before it is stored, closing an open-redirect path in the OAuth flow.
+- Run `bundler-audit` in CI; raise the `jwt` floor to `>= 2.10.3` and patch
+  `rails-html-sanitizer`, `json`, and `concurrent-ruby`.
+- Add `SECURITY.md` with a private disclosure process and threat model.
+
+### Changed
+- **Breaking:** the OAuth callback now redirects with `?code=` (a one-time
+  exchange code). Set `config.redirect_token_delivery = :token` to restore the
+  previous `?token=` behavior for one release.
+- **Breaking:** removed the `shakha_clients` table and the `Shakha::Client`
+  model. Users and sessions no longer belong to a client. The sign-in page shows
+  `config.app_name` (default `"Shakha"`).
+- Returning users' `email`/`name`/`picture` are refreshed on each sign-in.
+- The OAuth `redirect_uri` is derived from the engine's actual mount point, so
+  Shakha works when mounted anywhere.
+- An unknown or disabled provider returns `404` instead of raising a `500`.
+
+### Added
+- `config.redirect_token_delivery`, `config.app_name`.
+- `POST /auth/shakha/session/exchange` — swap a one-time code for the token.
+- The install generator injects `ActionDispatch::Cookies` into API-only hosts.
+
+## [0.6.0] — 2026-07-26
+
+### Added
+- A real test suite: an in-process dummy Rails app harness with full coverage of
+  the OAuth flow, session/bearer auth, providers, PKCE, models, and the
+  generator. Previously the suite could not load.
+- GitHub Actions CI across Ruby 3.1–3.4 × Rails 7.1/8.0/8.1, plus RuboCop
+  (`rubocop-rails-omakase`).
+
+### Fixed
+- PKCE code verifier no longer carries base64 padding (`SecureRandom.urlsafe_base64`
+  takes `padding` positionally, so `padding: false` had passed a truthy hash).
+- The OAuth callback no longer trips Rails' open-redirect protection.
+- The install generator injects into `ApplicationController` using the
+  generator's `destination_root` rather than a CWD-relative path.
+
+### Changed
+- **Breaking (API-mode hosts):** the engine no longer force-inserts cookie and
+  session middleware into the host app. Re-run `rails generate shakha:install`,
+  or add `ActionDispatch::Cookies` to your middleware stack.
+
+## [0.5.0] — 2026-05-20
+- End-to-end verification of the SPA flow in a Rails 8.1 API app; runtime fixes
+  found during that testing; API-mode cookie/session compatibility.
+
+## [0.3.0] — 2026-05-19
+- Multi-provider system (Google and GitHub) wired into the engine; simplified
+  provider-scoped URLs; `rails generate shakha:install` generator.
+
+## [0.2.0] — 2026-05-19
+- Rework toward an SPA-first broker: fixed six fatal bugs and several security
+  issues; rewrote the auth flow and controllers; simplified models and config;
+  removed the JWT/JWKS/OIDC and pairwise-subject service infrastructure.
+
+## [0.1.0] — 2026-05
+- 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
+[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
+[0.5.0]: https://github.com/Asrat77/shakha/compare/v0.3.0...v0.5.0
+[0.3.0]: https://github.com/Asrat77/shakha/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/Asrat77/shakha/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Asrat77/shakha/releases/tag/v0.1.0

data/README.md

@@ -1,93 +1,117 @@
 # Shakha
 
-Headless Google OAuth broker for Rails — PKCE, pairwise subjects, zero JavaScript.
+**SPA-first OAuth for Rails. One redirect. One token. Done.**
 
-Same Google account, different IDs per application. Built DHH-style: database sessions, Turbo native, single "Continue with Google" button.
+[![CI](https://github.com/Asrat77/shakha/actions/workflows/ci.yml/badge.svg)](https://github.com/Asrat77/shakha/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/shakha.svg)](https://rubygems.org/gems/shakha)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
-## Installation
+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`,
+and (for Google) `nonce` — against Google or GitHub, stores a revocable
+database-backed session, and hands your frontend a session token it uses as a
+cookie or `Authorization: Bearer` header.
 
-```ruby
-gem "shakha"
-```
+No JWTs to issue or rotate. No Redis. No frontend SDK.
 
-Run the migration:
+## The flow
 
-```bash
-bin/rails generate migration CreateShakhaTables
 ```
+1. Frontend:  window.location = "https://api.example.com/auth/shakha/google?return_to=https://app.example.com/login"
+2. Shakha:    redirects to accounts.google.com (PKCE, state, nonce — handled)
+3. Google:    redirects back to /auth/shakha/google/callback?code=...
+4. Shakha:    exchanges the code, verifies the ID token, creates the User + Session
+5. Shakha:    redirects to https://app.example.com/login?code=<one-time-code>
+6. Frontend:  POST /auth/shakha/session/exchange { code }  ->  { token, expires_at }
+7. Frontend:  send "Authorization: Bearer <token>" on every API call
+```
+
+The one-time code in step 5 keeps the session token out of the redirect URL (and
+therefore out of browser history, `Referer` headers, and logs). It is single-use
+and expires in 60 seconds.
+
+## Installation
+
+Add the gem:
 
 ```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 :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.references :client, null: false, foreign_key: { to_table: :shakha_clients }
-      t.string :token, null: false
-      t.string :ip_address
-      t.string :user_agent
-      t.timestamps
-      t.index :token, unique: true
-      t.index :created_at
-    end
-  end
-end
+gem "shakha"
 ```
 
-## Configuration
-
-Create `config/initializers/shakha.rb`:
+Mount the engine in `config/routes.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
+mount Shakha::Engine => "/auth/shakha"
 ```
 
-Environment variables:
+Run the installer and migrate:
 
 ```bash
-export SHAKHA_APP_ORIGIN="https://yourapp.com"
-export SHAKHA_SERVICE_SECRET="your-secret-key"
-export GOOGLE_CLIENT_ID="your-google-client-id"
-export GOOGLE_CLIENT_SECRET="your-google-client-secret"
+bin/rails generate shakha:install
+bin/rails db:migrate
 ```
 
-Google Cloud Console redirect URI: `https://yourapp.com/auth/shakha/callback`
+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.
+
+### Configuration
+
+Set these environment variables (the generated initializer reads them):
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `APP_ORIGIN` | yes | Your Rails app's origin, e.g. `https://api.example.com` |
+| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | for Google | Google OAuth credentials |
+| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | for GitHub | GitHub OAuth credentials |
+| `ALLOWED_REDIRECT_ORIGINS` | for a cross-origin SPA | Comma-separated frontend origins allowed as `return_to`, e.g. `https://app.example.com` |
+
+Provider console redirect URIs (derived from `APP_ORIGIN` and the mount point):
+
+- Google: `https://api.example.com/auth/shakha/google/callback`
+- GitHub: `https://api.example.com/auth/shakha/github/callback`
+
+## Frontend (React) example
+
+```jsx
+// Start sign-in
+const signIn = () => {
+  const returnTo = "https://app.example.com/login";
+  window.location =
+    `https://api.example.com/auth/shakha/google?return_to=${encodeURIComponent(returnTo)}`;
+};
+
+// On the return page (/login), swap the one-time code for a token
+useEffect(() => {
+  const code = new URLSearchParams(window.location.search).get("code");
+  if (!code) return;
+
+  fetch("https://api.example.com/auth/shakha/session/exchange", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code }),
+  })
+    .then((r) => r.json())
+    .then(({ token }) => {
+      localStorage.setItem("token", token);
+      return fetch("https://api.example.com/auth/shakha/session", {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+    })
+    .then((r) => r.json())
+    .then(({ user }) => setUser(user));
+}, []);
+```
 
-## Usage
+## Rails monolith usage
 
-### Sign In
+Shakha ships a minimal sign-in page and sets an encrypted session cookie, so a
+classic server-rendered app needs no JavaScript.
 
 ```erb
-<%= link_to "Sign in with Google", shakha.new_auth_path %>
+<%= link_to "Sign in", "/auth/shakha/google" %>
 ```
 
-### Protect Routes
-
 ```ruby
 class ApplicationController < ActionController::Base
   include Shakha::ControllerHelpers
@@ -95,48 +119,86 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-### Current User
-
 ```ruby
-current_user        # Shakha::User or nil
-current_session     # Shakha::Session or nil
-signed_in?          # boolean
-authenticate!       # redirects to login if not signed in
+current_user      # Shakha::User or nil
+current_session   # Shakha::Session or nil
+signed_in?        # boolean
+authenticate!     # 401 JSON for API requests, redirect to sign-in for HTML
 ```
 
-### Sign Out
+Sign out:
 
 ```erb
-<%= link_to "Sign out", shakha.session_path, data: { turbo_method: :delete } %>
+<%= button_to "Sign out", "/auth/shakha/sign_out", method: :delete %>
 ```
 
-### JWT Verification (API Mode)
+## Endpoints
 
-```ruby
-payload = Shakha.verify_token(id_token)
-user_id = payload[:pairwise_sub]
-```
+All paths are relative to the mount point (`/auth/shakha` above).
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| GET | `/` | — | Built-in sign-in page (monolith) |
+| GET | `/:provider` | — | Start OAuth (`google`, `github`) |
+| GET | `/:provider/callback` | — | OAuth callback (provider redirects here) |
+| POST | `/session/exchange` | one-time code | Swap the code for `{ token, expires_at }` |
+| 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 |
+
+## Configuration reference
 
-## Architecture
+Set in `config/initializers/shakha.rb` via `Shakha.setup { |config| ... }`.
 
-- **PKCE** — S256 code challenges on every flow
-- **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 JavaScript needed
-- **Embedded or standalone** — runs as Rails engine or headless service
+| Option | Default | Description |
+|---|---|---|
+| `app_origin` | — | Your Rails app's origin; used to build the OAuth `redirect_uri` |
+| `app_name` | `"Shakha"` | Name shown on the built-in sign-in page |
+| `google_client_id` / `google_client_secret` | — | Google OAuth credentials |
+| `github_client_id` / `github_client_secret` | — | GitHub OAuth credentials |
+| `providers` | `[:google]` | Enabled providers |
+| `allowed_redirect_origins` | `nil` | Extra origins permitted as `return_to` targets |
+| `redirect_token_delivery` | `:exchange_code` | `:exchange_code` (one-time code) or `:token` (token in the URL) |
+| `session_lifetime` | `30.days` | How long a session stays valid |
+| `rate_limiting_enabled` | `false` | Rate-limit `authorize` (20/min) and `callback` (10/min) |
 
-## Modes
+## Security
 
-### Embedded (default)
+Shakha uses PKCE (S256), a timing-safe `state` check, and Google `nonce` +
+ID-token claim (`iss`/`aud`/`exp`) verification. Session tokens are random
+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.
 
-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.
+## How it compares
 
-### Service (multi-tenant)
+- **OmniAuth** — a Rack middleware for the OAuth handshake; you still build
+  sessions, endpoints, and the SPA token hand-off yourself. Shakha ships the
+  whole path.
+- **Devise** — excellent for password auth in a monolith; OAuth and API/SPA
+  token flows are add-ons. Shakha is OAuth-only and API-first.
+- **Rodauth** — broader and more configurable, with its own conventions. Shakha
+  does one thing: an OAuth session broker for the API + SPA era.
+
+## Writing your own provider
+
+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.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
 
-Set `SHAKHA_SERVICE_URL` and register each app's origin in `shakha_clients`. Each app gets different pairwise subjects for the same Google user.
+Test against another Rails version with `BUNDLE_GEMFILE=gemfiles/rails_71.gemfile`.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-MIT
+MIT — see [LICENSE.txt](LICENSE.txt).

data/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+## Supported versions
+
+Shakha is pre-1.0. Security fixes are released only for the latest minor
+version. Please stay current until 1.0 establishes a support window.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for security problems.**
+
+Report privately through GitHub Security Advisories — the "Report a
+vulnerability" button on the repository's Security tab. Include a description,
+affected versions, and a reproduction if you have one. We aim to acknowledge
+within 7 days and to coordinate disclosure once a fix is available.
+
+## Threat model
+
+Shakha is an OAuth session broker. It is responsible for the integrity of the
+OAuth redirect flow and for session lifecycle; it deliberately delegates the
+rest to the host application.
+
+### What Shakha protects
+
+- **Authorization-code interception** — PKCE (S256) on every flow.
+- **CSRF on the OAuth round-trip** — a random `state`, stored in an encrypted,
+  http-only cookie and compared timing-safely on callback.
+- **ID token replay / substitution (Google)** — the OIDC `nonce` is verified
+  against the value minted at authorize time, and the `iss`, `aud`, and `exp`
+  claims are validated. The `aud` check rejects tokens minted for other clients.
+- **Open redirects** — `return_to` is validated against the app origin and an
+  explicit `allowed_redirect_origins` allowlist before it is stored, so the
+  post-login redirect can only reach approved origins.
+- **Token exposure in URLs** — by default the callback redirects with a
+  single-use, 60-second exchange code rather than the session token itself; the
+  frontend swaps it for the token over a POST.
+- **Session revocation** — sessions are random tokens stored in the database;
+  deleting the row revokes access immediately. No JWTs are issued, so there is
+  no standalone-token revocation gap.
+- **Brute force on the auth endpoints** — optional rate limiting on `authorize`
+  and `callback`.
+
+### What the host application owns
+
+- **TLS** — Shakha assumes it runs behind HTTPS in production; the Google ID
+  token's signature is trusted on the basis of the TLS connection to Google's
+  token endpoint rather than re-verified.
+- **CORS** — the host configures which origins may call its API.
+- **Frontend XSS** — any script that runs in the frontend can read a bearer
+  token the SPA stores; Shakha cannot defend a compromised frontend.
+- **Secret management** — `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_SECRET`, and
+  the Rails `secret_key_base` (which encrypts Shakha's cookies) are the host's
+  responsibility.
+- **Rate-limit backing store** — atomic rate limiting requires a shared,
+  atomic cache (Redis/Memcached) in multi-process deployments; the default
+  in-memory store does not coordinate across processes.

data/app/controllers/shakha/application_controller.rb

@@ -4,9 +4,8 @@ module Shakha
   class ApplicationController < ActionController::Base
     include ErrorHandler
     include ControllerHelpers
-    include RateLimiter
 
-    protect_from_forgery with: :exception
+    protect_from_forgery with: :exception, unless: -> { request.format.json? }
 
     layout -> { false if request.format == :json }
 
@@ -18,4 +17,4 @@ module Shakha
       render json: { error: "Invalid CSRF token" }, status: :unprocessable_entity
     end
   end
-end
+end

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,14 +36,14 @@ 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)
+      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)
@@ -53,9 +53,10 @@ module Shakha
       current_session&.destroy
       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 +67,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,8 +114,14 @@ 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
@@ -116,7 +132,8 @@ module Shakha
       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 +162,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