shakha 0.3.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f2fb69e4f483c981312b4211c9205e9ae5d0d100a0d3d8f0d61f693478c8369
-  data.tar.gz: 6dfb50d826c90ea54ed5453d7eebad7a94bf93cea02a1bb407fbd69a61da421e
+  metadata.gz: d366a8476de38c1c5ba4a9a1b5cc286b96ef0f99c20e08101c94a4048621a63c
+  data.tar.gz: 7a79e8f4493e93a4b1d6e2d9711ad0bbbd9eede57fede0de68ce667d184d82a9
 SHA512:
-  metadata.gz: 1bac5c8e1d92fb2997713d5ad19d7b16327fc21ec7e7520adf09d736bbe2c15c1cb72ef7c859798cba62a8a012819a1fb4863bd6c49830cd10d98f3082d4afc9
-  data.tar.gz: 8e9ae9652bb51b48bc30623305113e75c2a1c56676ec17a4e9503f4dc9694f55cf87d1d58fa9a2aaee956e47fa8ee1ecdc35024f3500c616e228942f42efbfac
+  metadata.gz: 1da077fb10311c211402e86cc09525bc1ac6aabf0d78000952d493314f4b5f47e54d77b7ee00615483f5aefb6c29e1f0732997fa363fcfe84b4856466b0f4234
+  data.tar.gz: 17825d89cd29b0a4e63ed1b4a504e4a4c2c5fa91696d77dfccbbedbde1e0ff80ba2ee739f9916f43671a9b71f5345244c73956bfa464087a97eec58a07626ed8

data/CHANGELOG.md

@@ -0,0 +1,128 @@
+# 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.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.
+
+### 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.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
+[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,123 @@
 # 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
+```
+
+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. 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
+
+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));
+}, []);
 ```
 
-Google Cloud Console redirect URI: `https://yourapp.com/auth/shakha/callback`
+For a complete runnable version (Rails API + Vite/React), see
+[examples/rails-api-react](examples/rails-api-react).
 
-## 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 +125,96 @@ 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
+
+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 |
+| 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
+
+Set in `config/initializers/shakha.rb` via `Shakha.setup { |config| ... }`.
+
+| 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) |
+
+## Security
+
+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.
+
+## 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
+  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: }`, 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
 
-```ruby
-payload = Shakha.verify_token(id_token)
-user_id = payload[:pairwise_sub]
+```bash
+bundle install
+bundle exec rake test
+bundle exec rubocop
 ```
 
-## Architecture
-
-- **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
-
-## 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.
+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