shakha 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dab553b64eb62de5d3a4225c5a4aa4fb470f8c6cf4aeea518f549dd664b7e67a
+  data.tar.gz: 0206f67ee329e747bad7da7cd3082c6be17811e19ef97ec67843d61bf50922de
+SHA512:
+  metadata.gz: 1704c398b0c6cdfa415a08f0662574eab25acb72b28ac9d8e8b83658750793111aeb9f24248ba22641ebc566500d6fbef2e63b250a895f43d6c7eb451c877d07
+  data.tar.gz: 9eab6f79cb46672c4df6dfc26507e91518616ac67ae7119bd07bfe7a177e7488f97918c09280eafcf8192953014d264bbc5beacc9c6bd5ced23fbb2e885f1e26

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT
+
+Copyright (c) 2026 Shakha Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+# Shakha
+
+Minimal auth broker for Google OAuth with PKCE and pairwise subjects.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "shakha"
+```
+
+Run the installer:
+
+```bash
+rails generate shakha:install
+```
+
+Set environment variables:
+
+```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"
+```
+
+## Configuration
+
+See `config/initializers/shakha.rb` for all options.
+
+## Usage
+
+### Sign In
+
+Redirect users to sign in:
+
+```erb
+<%= link_to "Sign in with Google", shakha.new_auth_path %>
+```
+
+### Current User
+
+In controllers:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Shakha::ControllerHelpers
+end
+```
+
+```ruby
+current_user        # Shakha::User or nil
+current_session    # Shakha::Session or nil
+signed_in?         # boolean
+authenticate!      # redirect to login if not signed in
+```
+
+### Protect Routes
+
+```ruby
+class PostsController < ApplicationController
+  before_action :authenticate!
+end
+```
+
+### JWT Verification (API Mode)
+
+```ruby
+payload = Shakha.verify_token(id_token)
+user_id = payload[:sub]
+```
+
+## Architecture
+
+- **PKCE** — S256 code challenges on every flow
+- **Pairwise subjects** — domain-scoped user identifiers
+- **ES256 JWTs** — signed with JWKS endpoint
+- **Database sessions** — DHH-style, no Redis
+- **Turbo native** — zero JS needed
+
+## License
+
+MIT

data/app/assets/stylesheets/shakha.css

@@ -0,0 +1,193 @@
+@layer shakha.base {
+  :root {
+    --shakha-bg: oklch(98% 0.002 250);
+    --shakha-surface: oklch(100% 0 0);
+    --shakha-border: oklch(87% 0.01 250);
+    --shakha-text: oklch(20% 0.03 250);
+    --shakha-text-muted: oklch(50% 0.02 250);
+    --shakha-primary: oklch(55% 0.2 250);
+    --shakha-primary-hover: oklch(50% 0.22 250);
+    --shakha-error: oklch(60% 0.2 25);
+    --shakha-radius: 8px;
+    --shakha-shadow: 0 1px 3px oklch(0% 0 0 / 0.05), 0 1px 2px oklch(0% 0 0 / 0.1);
+  }
+
+  * {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+  }
+
+  body {
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    background: var(--shakha-bg);
+    color: var(--shakha-text);
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  a {
+    color: var(--shakha-primary);
+    text-decoration: none;
+  }
+
+  a:hover {
+    text-decoration: underline;
+  }
+}
+
+@layer shakha.layout {
+  .shakha-container {
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 1.5rem;
+  }
+
+  .shakha-card {
+    width: 100%;
+    max-width: 400px;
+    background: var(--shakha-surface);
+    border: 1px solid var(--shakha-border);
+    border-radius: calc(var(--shakha-radius) + 4px);
+    box-shadow: var(--shakha-shadow);
+    overflow: hidden;
+  }
+
+  .shakha-card-center {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    min-height: 200px;
+    padding: 2rem;
+  }
+
+  .shakha-card-error {
+    text-align: center;
+    padding: 2rem;
+  }
+
+  .shakha-header {
+    padding: 1.5rem 1.5rem 0;
+    text-align: center;
+  }
+
+  .shakha-header h1 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    color: var(--shakha-text);
+  }
+
+  .shakha-body {
+    padding: 1.5rem;
+  }
+}
+
+@layer shakha.components {
+  .shakha-button {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.75rem;
+    width: 100%;
+    padding: 0.75rem 1rem;
+    border-radius: var(--shakha-radius);
+    font-size: 0.9375rem;
+    font-weight: 500;
+    text-decoration: none;
+    cursor: pointer;
+    transition: background 0.15s ease, border-color 0.15s ease;
+  }
+
+  .shakha-button-google {
+    background: var(--shakha-surface);
+    border: 1px solid var(--shakha-border);
+    color: var(--shakha-text);
+  }
+
+  .shakha-button-google:hover {
+    background: var(--shakha-bg);
+    text-decoration: none;
+  }
+
+  .shakha-button-primary {
+    background: var(--shakha-primary);
+    border: 1px solid var(--shakha-primary);
+    color: white;
+  }
+
+  .shakha-button-primary:hover {
+    background: var(--shakha-primary-hover);
+    text-decoration: none;
+  }
+
+  .shakha-google-icon {
+    width: 18px;
+    height: 18px;
+    flex-shrink: 0;
+  }
+
+  .shakha-privacy {
+    margin-top: 1rem;
+    font-size: 0.75rem;
+    color: var(--shakha-text-muted);
+    text-align: center;
+  }
+
+  .shakha-privacy a {
+    color: var(--shakha-text-muted);
+    text-decoration: underline;
+  }
+}
+
+@layer shakha.states {
+  .shakha-loading {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 1rem;
+  }
+
+  .shakha-loading p {
+    color: var(--shakha-text-muted);
+    font-size: 0.875rem;
+  }
+
+  .shakha-spinner {
+    width: 32px;
+    height: 32px;
+    border: 3px solid var(--shakha-border);
+    border-top-color: var(--shakha-primary);
+    border-radius: 50%;
+    animation: shakha-spin 0.8s linear infinite;
+  }
+
+  @keyframes shakha-spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  .shakha-error-icon {
+    margin-bottom: 1rem;
+  }
+
+  .shakha-error-icon svg {
+    width: 48px;
+    height: 48px;
+    color: var(--shakha-error);
+  }
+
+  .shakha-card-error h1 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin-bottom: 0.5rem;
+  }
+
+  .shakha-error-message {
+    color: var(--shakha-text-muted);
+    margin-bottom: 1.5rem;
+  }
+}

data/app/controllers/shakha/application_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Shakha
+  class ApplicationController < ActionController::Base
+    include ErrorHandler
+    include ControllerHelpers
+
+    protect_from_forgery with: :exception
+
+    layout -> { false if request.format == :json }
+
+    rescue_from ActiveSupport::ActionController::InvalidAuthenticityToken, with: :invalid_csrf_token
+
+    private
+
+    def invalid_csrf_token(exception)
+      render json: { error: "Invalid CSRF token" }, status: :unprocessable_entity
+    end
+  end
+end

data/app/controllers/shakha/auth_controller.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Shakha
+  class AuthController < ApplicationController
+    include PKCEMixin
+
+    skip_before_action :verify_authenticity_token, only: [:callback, :token]
+
+    def new
+      @client = find_or_create_client
+      @return_to = params[:return_to] || "/"
+    end
+
+    def authorize
+      pkce = create_pkce_bundle
+      @client = find_or_create_client
+
+      google_auth_url = build_google_auth_url(pkce)
+
+      redirect_to google_auth_url
+    end
+
+    def callback
+      verifier = verify_pkce!(params[:code])
+
+      exchange_code_for_tokens(params[:code], verifier)
+    rescue PKCEError, GoogleOAuthError => e
+      redirect_to shakha.error_path(message: e.message)
+    end
+
+    def token
+      code = params[:code]
+      verifier = params[:code_verifier]
+
+      raise PKCEError, "Missing code" unless code
+      raise PKCEError, "Missing code_verifier" unless verifier
+
+      id_token = exchange_code_for_id_token(code, verifier)
+
+      render json: {
+        id_token: id_token,
+        pairwise_sub: id_token_payload(id_token)[:sub],
+        expires_in: 24.hours.to_i
+      }
+    rescue PKCEError, JWTError, GoogleOAuthError => e
+      render json: { error: e.message }, status: :unauthorized
+    end
+
+    def error
+      @message = params[:message] || "Authentication failed"
+    end
+
+    private
+
+    def find_or_create_client
+      origin = URI.parse(request.origin).origin
+
+      Shakha::Client.find_or_create_by!(origin: origin) do |client|
+        client.name = URI.parse(request.origin).host
+      end
+    end
+
+    def build_google_auth_url(pkce)
+      client_id = Shakha.config.google_client_id || ENV["GOOGLE_CLIENT_ID"]
+      redirect_uri = "#{Shakha.config.service_base_url}/auth/shakha/callback"
+
+      scopes = ["openid", "email", "profile"].join(" ")
+      scopes += " https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile" if params[:request_pii]
+
+      params = {
+        client_id: client_id,
+        redirect_uri: redirect_uri,
+        response_type: "code",
+        scope: scopes,
+        code_challenge: pkce[:challenge],
+        code_challenge_method: "S256",
+        state: pkce[:state],
+        access_type: "offline",
+        prompt: "consent"
+      }
+
+      URI.parse("https://accounts.google.com/o/oauth2/v2/auth").tap do |uri|
+        uri.query = URI.encode_www_form(params)
+      end.to_s
+    end
+
+    def exchange_code_for_tokens(code, verifier)
+      client_id = Shakha.config.google_client_id || ENV["GOOGLE_CLIENT_ID"]
+      client_secret = Shakha.config.google_client_secret || ENV["GOOGLE_CLIENT_SECRET"]
+      redirect_uri = "#{Shakha.config.service_base_url}/auth/shakha/callback"
+
+      response = http_post(
+        "https://oauth2.googleapis.com/token",
+        {
+          code: code,
+          client_id: client_id,
+          client_secret: client_secret,
+          redirect_uri: redirect_uri,
+          grant_type: "authorization_code",
+          code_verifier: verifier
+        }
+      )
+
+      tokens = JSON.parse(response.body)
+      id_token = tokens["id_token"]
+      access_token = tokens["access_token"]
+
+      raise GoogleOAuthError, "No id_token received" unless id_token
+
+      payload = decode_id_token(id_token)
+      google_sub = payload["sub"]
+      pairwise_sub = Shakha.derive_pairwise_sub(google_sub)
+
+      client = find_or_create_client
+      user = Shakha::User.find_or_initialize_by(pairwise_sub: pairwise_sub)
+
+      if params[:request_pii] && payload["email"]
+        user.assign_attributes(
+          email: payload["email"],
+          name: payload["name"],
+          picture: payload["picture"]
+        )
+      end
+      user.save!
+
+      session_record = Shakha::Session.create!(
+        user: user,
+        client: client,
+        jti: SecureRandom.uuid
+      )
+
+      cookies.encrypted[:shakha_session_token] = {
+        value: session_record.token,
+        httponly: true,
+        secure: Rails.env.production?,
+        same_site: :lax,
+        expires: Shakha.config.session_lifetime.from_now
+      }
+
+      return_to = pkce_state&.dig(:return_to) || "/"
+
+      redirect_to return_to
+    end
+
+    def exchange_code_for_id_token(code, verifier)
+      client_id = Shakha.config.google_client_id || ENV["GOOGLE_CLIENT_ID"]
+      client_secret = Shakha.config.google_client_secret || ENV["GOOGLE_CLIENT_SECRET"]
+      redirect_uri = "#{Shakha.config.service_base_url}/auth/shakha/callback"
+
+      response = http_post(
+        "https://oauth2.googleapis.com/token",
+        {
+          code: code,
+          client_id: client_id,
+          client_secret: client_secret,
+          redirect_uri: redirect_uri,
+          grant_type: "authorization_code",
+          code_verifier: verifier
+        }
+      )
+
+      tokens = JSON.parse(response.body)
+      tokens["id_token"] || raise(GoogleOAuthError, "No id_token in response")
+    end
+
+    def id_token_payload(id_token)
+      JWT.decode(id_token, nil, false)[0]
+    end
+
+    def decode_id_token(id_token)
+      JWT.decode(id_token, nil, false)[0]
+    end
+
+    def http_post(url, body)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Content-Type"] = "application/x-www-form-urlencoded"
+      request.body = URI.encode_www_form(body)
+
+      http.request(request)
+    end
+  end
+end

data/app/controllers/shakha/jwks_controller.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Shakha
+  class JwksController < ApplicationController
+    def show
+      render json: Shakha::JwtHandler.jwks,
+             content_type: "application/json"
+    end
+  end
+end

data/app/controllers/shakha/openid_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Shakha
+  class OpenidController < ApplicationController
+    def configuration
+      render json: {
+        issuer: Shakha.config.issuer,
+        authorization_endpoint: "#{Shakha.config.service_base_url}/auth/shakha/authorize",
+        token_endpoint: "#{Shakha.config.service_base_url}/auth/shakha/token",
+        userinfo_endpoint: "#{Shakha.config.service_base_url}/auth/shakha/session",
+        jwks_uri: "#{Shakha.config.service_base_url}/.well-known/jwks.json",
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code"],
+        code_challenge_methods_supported: ["S256"],
+        subject_types_supported: ["pairwise"],
+        id_token_signing_alg_values_supported: ["ES256"],
+        scopes_supported: ["openid", "email", "profile"]
+      }, content_type: "application/json"
+    end
+  end
+end

data/app/controllers/shakha/session_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Shakha
+  class SessionController < ApplicationController
+    skip_before_action :verify_authenticity_token, only: [:check]
+
+    def show
+      render json: {
+        user_id: current_user&.pairwise_sub,
+        email: current_user&.email,
+        name: current_user&.name,
+        expires_at: current_session&.expires_at&.iso8601
+      }
+    end
+
+    def check
+      if signed_in?
+        render json: { status: "active" }
+      else
+        render json: {
+          status: "login_required",
+          reason: "no_session"
+        }, status: :unauthorized
+      end
+    end
+
+    def destroy
+      current_session&.destroy
+      cookies.delete(:shakha_session_token)
+      render json: { status: "signed_out" }
+    end
+  end
+end

data/app/models/shakha/client.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Shakha
+  class Client < ::ApplicationRecord
+    self.table_name = "shakha_clients"
+
+    has_many :sessions, class_name: "Shakha::Session", dependent: :restrict_with_error
+    has_many :users, class_name: "Shakha::User", dependent: :nullify
+
+    validates :origin, presence: true, uniqueness: true
+
+    def client_id
+      "origin:#{origin}"
+    end
+
+    def self.find_by_origin!(origin)
+      find_by!(origin: URI.parse(origin).origin)
+    end
+  end
+end

data/app/models/shakha/session.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Shakha
+  class Session < ::ApplicationRecord
+    self.table_name = "shakha_sessions"
+
+    belongs_to :user, class_name: "Shakha::User", optional: true
+    belongs_to :client, class_name: "Shakha::Client"
+
+    before_create :generate_token
+    before_create :generate_jti
+
+    scope :active, -> { where("created_at > ?", Shakha.config.session_lifetime.ago) }
+
+    def expired?
+      created_at < Shakha.config.session_lifetime.ago
+    end
+
+    def expires_at
+      created_at + Shakha.config.session_lifetime
+    end
+
+    private
+
+    def generate_token
+      self.token ||= SecureRandom.urlsafe_base64(32)
+    end
+
+    def generate_jti
+      self.jti ||= SecureRandom.uuid
+    end
+  end
+end

data/app/models/shakha/user.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Shakha
+  class User < ::ApplicationRecord
+    self.table_name = "shakha_users"
+
+    has_many :sessions, class_name: "Shakha::Session", dependent: :destroy
+
+    validates :pairwise_sub, presence: true, uniqueness: true
+    validates :email, uniqueness: true, allow_blank: true
+
+    def can_access?(resource)
+      true
+    end
+  end
+end

data/app/views/shakha/auth/callback.html.erb

@@ -0,0 +1,12 @@
+<% content_for :title, "Signing In..." %>
+
+<div class="shakha-container">
+  <div class="shakha-card shakha-card-center">
+    <div class="shakha-loading">
+      <div class="shakha-spinner"></div>
+      <p>Signing you in...</p>
+    </div>
+  </div>
+</div>
+
+<meta http-equiv="refresh" content="2;url=<%= @return_to || "/" %>">

data/app/views/shakha/auth/new.html.erb

@@ -0,0 +1,29 @@
+<% content_for :title, "Sign In" %>
+
+<div class="shakha-container">
+  <div class="shakha-card">
+    <div class="shakha-header">
+      <h1>Sign in to <%= @client&.name || "your app" %></h1>
+    </div>
+
+    <div class="shakha-body">
+      <%= link_to shakha.authorize_path(request_pii: 1),
+                  class: "shakha-button shakha-button-google",
+                  data: { turbo: false } do %>
+        <svg class="shakha-google-icon" viewBox="0 0 18 18" aria-hidden="true">
+          <path fill="#4285F4" d="M17.64 9.2c0-.637-.057-1.251-.164-1.84H9v3.481h4.844c-.209 1.125-.843 2.078-1.796 2.717v2.258h2.908c1.702-1.567 2.684-3.875 2.684-6.615z"/>
+          <path fill="#34A853" d="M9 18c2.43 0 4.467-.806 5.956-2.184l-2.908-2.258c-.806.54-1.837.86-3.048.86-2.344 0-4.328-1.584-5.036-3.711H.957v2.332A8.997 8.997 0 0 0 9 18z"/>
+          <path fill="#FBBC05" d="M3.964 10.71A5.41 5.41 0 0 1 3.682 9c0-.593.102-1.17.282-1.71V4.958H.957A8.996 8.996 0 0 0 0 9c0 1.452.348 2.827.957 4.042l3.007-2.332z"/>
+          <path fill="#EA4335" d="M9 3.58c1.321 0 2.508.454 3.44 1.345l2.582-2.58C13.463.891 11.426 0 9 0A8.997 8.997 0 0 0 .957 4.958L3.964 7.29C4.672 5.163 6.656 3.58 9 3.58z"/>
+        </svg>
+        Continue with Google
+      <% end %>
+
+      <p class="shakha-privacy">
+        By signing in, you agree to our
+        <%= link_to "Terms of Service", "#" %> and
+        <%= link_to "Privacy Policy", "#" %>.
+      </p>
+    </div>
+  </div>
+</div>