clowk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 56e3503c335ec716e89e49428b66a0c4157be9cb6ff19c46095117062f4c7848
+  data.tar.gz: 1db10f568e025bc52ea97e255f9e4cdc8064507ace6adf83e74d78d20d5b5d9e
+SHA512:
+  metadata.gz: 3ed1c6bb69c0644f5476374f8004ce865c1661aeec3729b42a59442ee453e6e431c23583d603ccf49b9e045ae2c0d7e9733f2482a040ef3418c069e6f88ef531
+  data.tar.gz: 393ed6db1f3777cc402731fe16e0874d64c842ab3b5118aa49c9a79e5b208f38a660b4bbcca45ee349eccf1f1be030ac35ff6e235310edbc9e14d57cd730a24b

data/README.md

@@ -0,0 +1,365 @@
+# Clowk Ruby SDK
+
+Clowk is the Ruby gem for integrating Clowk authentication into Rails applications.
+
+It focuses on a small client-side surface:
+
+- redirect users to Clowk
+- verify the JWT returned by Clowk
+- expose Rails-friendly auth helpers
+- provide a minimal HTTP client for the Clowk API
+
+## Product domains
+
+Clowk uses different domains for different concerns:
+
+- `clowk.in`: public product site
+- `app.clowk.in`: dashboard used to manage apps and instances
+- `*.clowk.dev`: per-instance auth domain used by your end users
+
+For a Rails app using this gem, the important part is the instance auth domain. Your app redirects users there, Clowk authenticates them, then redirects back with a signed JWT.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'clowk'
+```
+
+## Quick start
+
+```ruby
+# config/initializers/clowk.rb
+Clowk.configure do |config|
+  config.publishable_key = ENV['CLOWK_PUBLISHABLE_KEY']
+  config.secret_key = ENV['CLOWK_SECRET_KEY']
+end
+```
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount Clowk::Engine => '/clowk'
+end
+```
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Clowk::Authenticable
+end
+```
+
+```ruby
+class DashboardController < ApplicationController
+  before_action :authenticate_clowk!
+
+  def index
+    @user = current_clowk
+  end
+end
+```
+
+## Authentication flow
+
+1. Your app redirects the user to `*.clowk.dev`.
+2. Clowk authenticates the user.
+3. Clowk redirects back to your callback URL with `token` and `state`.
+4. The gem validates `state`, verifies the JWT, stores the authenticated session, and redirects back to a safe internal path.
+
+The callback flow includes:
+
+- session-backed `state` validation
+- JWT verification with your instance `secret_key`
+- internal-only redirect sanitization
+- session reset before persisting the authenticated user
+- `httponly` cookie persistence with `SameSite=Lax`
+
+## Configuration
+
+```ruby
+Clowk.configure do |config|
+  config.secret_key = ENV['CLOWK_SECRET_KEY']
+  config.publishable_key = ENV['CLOWK_PUBLISHABLE_KEY']
+  config.subdomain_url = 'https://acme.clowk.dev'
+  config.prefix_by = :clowk
+
+  config.after_sign_in_path = '/'
+  config.after_sign_out_path = '/'
+
+  config.api_base_url = 'https://api.clowk.dev/client/v1'
+  config.callback_path = '/clowk/oauth/callback'
+  config.mount_path = '/clowk'
+
+  config.http_open_timeout = 5
+  config.http_read_timeout = 10
+  config.http_write_timeout = 10
+  config.http_retry_attempts = 2
+  config.http_retry_interval = 0.05
+  config.http_logger = Rails.logger
+end
+```
+
+Important settings:
+
+| Setting | Purpose |
+| --- | --- |
+| `secret_key` | Required. Used to verify JWT signatures. |
+| `publishable_key` | Preferred for auth URL resolution. The gem resolves the latest instance URL from it before sign in/sign up. |
+| `subdomain_url` | Fallback auth domain when you do not want publishable-key-based resolution. |
+| `prefix_by` | Prefix used to generate helper names. Default: `:clowk`. |
+| `mount_path` | Local mount prefix used by helper path generation. Default: `/clowk`. |
+| `callback_path` | Callback route Clowk redirects back to. Default: `/clowk/oauth/callback`. |
+| `http_logger` | Optional logger used by `Clowk::Http`. |
+
+Auth URL resolution priority:
+
+1. `publishable_key`
+2. `subdomain_url`
+
+When `publishable_key` is present, the gem resolves the current auth base URL first and caches it briefly in memory. The lookup endpoint returns the full instance JSON payload, and the gem derives the final auth URL from that data (including `subdomain`). This keeps dashboard subdomain changes visible without redeploying the client app. If you do not want that lookup, configure only `subdomain_url`.
+
+Internally, that lookup is done through `Clowk::SDK::Client`, via `client.subdomains.find_by_pk('pk_...')`.
+
+If you mount the engine under a different prefix, keep `mount_path` and `callback_path` aligned with that choice.
+
+Example:
+
+```ruby
+Clowk.configure do |config|
+  config.mount_path = '/auth'
+  config.callback_path = '/auth/oauth/callback'
+end
+
+Rails.application.routes.draw do
+  mount Clowk::Engine => '/auth'
+end
+```
+
+## Generated helpers
+
+With the default `prefix_by = :clowk`, the concern exposes:
+
+- `current_clowk`
+- `authenticate_clowk!`
+- `clowk_signed_in?`
+
+You can change the prefix to avoid collisions with another auth system.
+
+```ruby
+Clowk.configure do |config|
+  config.prefix_by = :member
+end
+```
+
+That generates:
+
+- `current_member`
+- `authenticate_member!`
+- `member_signed_in?`
+
+## Current subject
+
+`current_clowk` returns a `Clowk::Current` object.
+
+```ruby
+current_clowk.id
+current_clowk.email
+current_clowk.name
+current_clowk.avatar_url
+current_clowk.provider
+current_clowk.instance_id
+current_clowk.app_id
+```
+
+You can also access raw claims:
+
+```ruby
+current_clowk[:sub]
+current_clowk.to_h
+```
+
+## Route protection
+
+```ruby
+class AdminController < ApplicationController
+  before_action :authenticate_clowk!
+end
+```
+
+Use `authenticate_clowk!` for protected pages. Use `current_clowk` when the route can be public but should still know who is authenticated.
+
+## View and URL helpers
+
+Local mounted routes:
+
+```erb
+<%= link_to 'Sign in', clowk_sign_in_path(return_to: dashboard_path) %>
+<%= link_to 'Sign up', clowk_sign_up_path(return_to: dashboard_path) %>
+<%= link_to 'Sign out', clowk_sign_out_path %>
+```
+
+Direct remote URLs:
+
+```erb
+<%= link_to 'Direct sign in', clowk_sign_in_url(redirect_to: dashboard_url) %>
+<%= link_to 'Direct sign up', clowk_sign_up_url(redirect_to: dashboard_url) %>
+```
+
+When `publishable_key` is configured, these helpers resolve the latest instance URL before building the final `sign-in` or `sign-up` destination. When it is absent, they use `subdomain_url` directly.
+
+Mounted routes exposed by the engine:
+
+- `/clowk/sign_in`
+- `/clowk/sign_up`
+- `/clowk/sign_out`
+- `/clowk/oauth/callback`
+
+When you mount the engine elsewhere, the same route set is exposed under your chosen prefix.
+
+## Token sources
+
+The concern can read the token from:
+
+- `params[:token]`
+- cookies
+- `Authorization: Bearer <token>`
+
+That keeps the integration usable for callback routes, regular controllers, and API-style endpoints.
+
+## SDK Client
+
+The gem includes a resource-oriented SDK for the Clowk API.
+
+```ruby
+client = Clowk::SDK::Client.new
+```
+
+The client uses your global configuration by default. You can also pass options explicitly:
+
+```ruby
+client = Clowk::SDK::Client.new(
+  secret_key: 'sk_live_xxx',
+  publishable_key: 'pk_live_xxx'
+)
+```
+
+### Resources
+
+Each resource is accessible as a method on the client:
+
+```ruby
+client.users
+client.sessions
+client.subdomains
+```
+
+These return `Clowk::SDK::Resource` subclasses with a standard CRUD interface:
+
+```ruby
+client.users.list
+client.users.find('user_123')
+client.users.show('user_123')
+client.users.destroy('user_123')
+```
+
+### Token verification
+
+```ruby
+response = client.tokens.verify(token: params[:token])
+
+response.status       # => 200
+response.success?     # => true
+response.body_parsed  # => { 'valid' => true }
+```
+
+### Subdomain resolution
+
+```ruby
+response = client.subdomains.find_by_pk('pk_live_xxx')
+```
+
+### Search operators
+
+The `search` method uses a Zendesk-style query syntax. You can use keyword arguments or a raw string for advanced operators.
+
+**Keywords:**
+
+```ruby
+client.users.search(email: "user@example.com")
+# GET /users/search?query=email%3Auser%40example.com
+
+client.users.search(status: "active", role: "admin")
+# GET /users/search?query=status%3Aactive+role%3Aadmin
+```
+
+**Raw string** for custom operators like `>`, `<`, `>=`:
+
+```ruby
+client.users.search("email:user@example.com active:true created_at>2026-01-01")
+# GET /users/search?query=email%3Auser%40example.com+active%3Atrue+created_at%3E2026-01-01
+```
+
+The raw string is sent as-is, giving full control over the query syntax. The API backend parses and applies the operators.
+
+### Raw HTTP methods
+
+The client also exposes raw HTTP methods for custom requests:
+
+```ruby
+client.get('custom/endpoint')
+client.post('custom/endpoint', { key: 'value' })
+client.put('custom/endpoint', { key: 'value' })
+client.patch('custom/endpoint', { key: 'value' })
+client.delete('custom/endpoint')
+client.head('custom/endpoint')
+client.options('custom/endpoint')
+```
+
+## `Clowk::Http::Response`
+
+HTTP responses are returned as `Clowk::Http::Response` objects.
+
+```ruby
+response = client.get('users/user_123')
+
+response.status       # => 200
+response.success?     # => true
+response.body         # => '{"id":"user_123"}'
+response.body_parsed  # => { 'id' => 'user_123' }
+response.headers      # => { 'content-type' => ['application/json'] }
+```
+
+For compatibility, the response also supports:
+
+```ruby
+response[:status]
+response[:success?]
+response.to_h
+```
+
+## HTTP middleware
+
+`Clowk::Http` uses a small internal middleware stack built on `Net::HTTP`.
+
+Included behavior:
+
+- request and response logging
+- open, read, and write timeouts
+- retry on retryable network errors
+- automatic JSON request encoding
+- automatic `body_parsed` JSON decoding when possible
+
+## Scope
+
+This gem is intentionally narrow. It does not try to replace your entire app session architecture or act as an auth server.
+
+Its job is to make the Rails side of Clowk integration predictable:
+
+- start authentication
+- validate callbacks safely
+- expose a clean authenticated subject
+- make future Clowk API access straightforward
+
+## License
+
+MIT. See `LICENSE`.

data/clowk.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/clowk/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'clowk'
+  spec.version = Clowk::VERSION
+  spec.authors = ['Clowk']
+  spec.email = ['support@clowk.in']
+
+  spec.summary = 'Rails SDK for Clowk authentication'
+  spec.description = 'Clowk Authentication, JWT verification, and future API access'
+  spec.homepage = 'https://clowk.in'
+  spec.license = 'AGPL-3.0'
+  spec.required_ruby_version = '>= 3.3'
+  spec.metadata = {
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir['README.md', 'clowk.gemspec', 'config/routes.rb', 'lib/**/*.rb']
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 7.0'
+  spec.add_dependency 'jwt', '>= 2.7', '< 3.0'
+  spec.add_dependency 'railties', '>= 7.0'
+
+  spec.add_development_dependency 'rspec', '>= 3.13', '< 4.0'
+end

data/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Clowk::Engine.routes.draw do
+  get '/sign_in', to: 'sessions#new', as: :sign_in
+  get '/sign_up', to: 'sessions#sign_up', as: :sign_up
+  match '/sign_out', to: 'sessions#destroy', via: %i(get delete), as: :sign_out
+  get '/oauth/callback', to: 'callbacks#show', as: :auth_callback
+end

data/lib/clowk/authenticable.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Clowk
+  module Authenticable
+    extend ActiveSupport::Concern
+
+    def self.install_dynamic_methods(base)
+      scope = Clowk.config.prefix_by.to_s
+      current_method = :"current_#{scope}"
+      authenticate_method = :"authenticate_#{scope}!"
+      signed_in_method = :"#{scope}_signed_in?"
+
+      base.class_eval do
+        define_method(current_method) do
+          clowk_current_resource
+        end
+
+        define_method(authenticate_method) do
+          clowk_authenticate!
+        end
+
+        define_method(signed_in_method) do
+          clowk_current_resource.present?
+        end
+
+        helper_method current_method, authenticate_method, signed_in_method, :current_token if respond_to?(:helper_method)
+      end
+    end
+
+    included do
+      Clowk::Authenticable.install_dynamic_methods(self)
+    end
+
+    def clowk_current_resource
+      @clowk_current_resource ||= begin
+        payload = stored_user_payload || verified_request_payload
+        payload ? Current.new(payload) : nil
+      end
+    end
+
+    def current_token
+      stored_session&.dig('token') || extracted_token
+    end
+
+    def clowk_signed_in?
+      clowk_current_resource.present?
+    end
+
+    def clowk_authenticate!
+      return clowk_current_resource if clowk_signed_in?
+
+      if request.format.json?
+        render json: { error: 'Unauthorized' }, status: :unauthorized
+      else
+        redirect_to clowk_sign_in_path(return_to: request.fullpath)
+      end
+    end
+
+    def clowk_sign_out!
+      session.delete(Clowk.config.session_key)
+      cookies.delete(Clowk.config.cookie_key)
+
+      @clowk_current_resource = nil
+    end
+
+    private
+
+    def verified_request_payload
+      return unless extracted_token
+
+      payload = Clowk::JwtVerifier.new.verify(extracted_token)
+      persist_clowk_session(extracted_token, payload)
+
+      payload
+    rescue Clowk::InvalidTokenError
+      nil
+    end
+
+    def extracted_token
+      @extracted_token ||= Clowk::Middleware::TokenExtractor.new(request).call
+    end
+
+    def stored_session
+      raw_session = session[Clowk.config.session_key]
+      return unless raw_session.respond_to?(:to_h)
+
+      raw_session.to_h
+    end
+
+    def stored_user_payload
+      payload = stored_session&.dig('user') || stored_session&.dig(:user)
+      payload&.deep_symbolize_keys
+    end
+
+    def persist_clowk_session(token, payload)
+      session[Clowk.config.session_key] = {
+        token: token,
+        user: payload,
+        signed_in_at: Time.now.to_i
+      }
+
+      cookies[Clowk.config.cookie_key] = {
+        value: token,
+        httponly: true,
+        same_site: :lax,
+        secure: request.ssl?
+      }
+    end
+  end
+end

data/lib/clowk/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Clowk
+  class Configuration
+    attr_accessor :api_base_url
+    attr_accessor :app_base_url
+    attr_accessor :after_sign_in_path
+    attr_accessor :after_sign_out_path
+    attr_accessor :callback_path
+    attr_accessor :cookie_key
+    attr_accessor :http_logger
+    attr_accessor :http_open_timeout
+    attr_accessor :http_read_timeout
+    attr_accessor :http_retry_attempts
+    attr_accessor :http_retry_interval
+    attr_accessor :http_write_timeout
+    attr_accessor :issuer
+    attr_accessor :mount_path
+    attr_accessor :publishable_key
+    attr_accessor :prefix_by
+    attr_accessor :secret_key
+    attr_accessor :session_key
+    attr_accessor :subdomain_url
+    attr_accessor :token_param
+
+    def initialize
+      @api_base_url = 'https://api.clowk.dev/client/v1'
+      @app_base_url = 'https://app.clowk.in'
+      @after_sign_in_path = '/'
+      @after_sign_out_path = '/'
+      @mount_path = '/clowk'
+      @callback_path = '/clowk/oauth/callback'
+      @cookie_key = 'clowk_token'
+      @http_logger = nil
+      @http_open_timeout = 5
+      @http_read_timeout = 10
+      @http_retry_attempts = 2
+      @http_retry_interval = 0.05
+      @http_write_timeout = 10
+      @issuer = 'clowk'
+      @session_key = :clowk
+      @prefix_by = :clowk
+      @token_param = :token
+    end
+  end
+end

data/lib/clowk/controllers/base_controller.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'uri'
+
+module Clowk
+  class BaseController < ActionController::Base
+    include Clowk::Authenticable
+    include Clowk::Helpers::UrlHelpers
+
+    protect_from_forgery with: :exception
+
+    private
+
+    def redirect_back_or(default, return_to: params[:return_to])
+      redirect_target = safe_redirect_path(return_to) || safe_redirect_path(default) || '/'
+
+      redirect_to redirect_target
+    end
+
+    def start_clowk_auth_flow!(return_to: nil)
+      sanitized_return_to = safe_redirect_path(return_to) || safe_redirect_path(Clowk.config.after_sign_in_path) || '/'
+      state = SecureRandom.hex(32)
+
+      session[:clowk_auth_flow] = {
+        'state' => state,
+        'return_to' => sanitized_return_to
+      }
+
+      state
+    end
+
+    def consume_clowk_auth_flow!
+      flow = session.delete(:clowk_auth_flow)
+      return {} unless flow.respond_to?(:to_h)
+
+      flow.to_h
+    end
+
+    def validate_clowk_state!(expected_state, actual_state)
+      raise Clowk::InvalidStateError, 'missing state' if actual_state.blank?
+      raise Clowk::InvalidStateError, 'missing state' if expected_state.blank?
+      raise Clowk::InvalidStateError, 'invalid state' unless state_matches?(expected_state, actual_state)
+    end
+
+    def state_matches?(expected_state, actual_state)
+      return false if expected_state.bytesize != actual_state.bytesize
+
+      ActiveSupport::SecurityUtils.secure_compare(expected_state, actual_state)
+    end
+
+    def safe_redirect_path(candidate)
+      value = candidate.to_s
+      return if value.empty?
+
+      return value if value.start_with?('/') && !value.start_with?('//')
+
+      uri = URI.parse(value)
+      return unless uri.host == request.host && uri.scheme == request.scheme
+
+      uri.request_uri
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def reset_clowk_session!
+      reset_session
+    end
+  end
+end

data/lib/clowk/controllers/callbacks_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Clowk
+  class CallbacksController < BaseController
+    def show
+      flow = consume_clowk_auth_flow!
+      validate_clowk_state!(flow['state'], params[:state])
+
+      token = params[Clowk.config.token_param]
+      raise Clowk::InvalidTokenError, 'missing token' if token.blank?
+
+      payload = Clowk::JwtVerifier.new.verify(token)
+      return_to = flow['return_to']
+
+      reset_clowk_session!
+      persist_clowk_session(token, payload)
+
+      redirect_back_or(Clowk.config.after_sign_in_path, return_to:)
+    rescue Clowk::InvalidTokenError, Clowk::InvalidStateError => e
+      flash[:alert] = "Clowk authentication failed: #{e.message}"
+
+      redirect_back_or(Clowk.config.after_sign_out_path, return_to: nil)
+    end
+  end
+end

data/lib/clowk/controllers/sessions_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Clowk
+  class SessionsController < BaseController
+    def new
+      state = start_clowk_auth_flow!(return_to: params[:return_to])
+
+      redirect_to clowk_sign_in_url(state:), allow_other_host: true
+    end
+
+    def sign_up
+      state = start_clowk_auth_flow!(return_to: params[:return_to])
+
+      redirect_to clowk_sign_up_url(state:), allow_other_host: true
+    end
+
+    def destroy
+      clowk_sign_out!
+
+      redirect_back_or(Clowk.config.after_sign_out_path)
+    end
+  end
+end