custos 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 24708985bf3ae2ecd4778c38c0793b847aa099fe64bbbbdce10ded72300311d8
+  data.tar.gz: fe8af54c9038f8642f3f5de46bfb23818551f981bfecb9f936cb22e2bb205db7
+SHA512:
+  metadata.gz: 53f840b0476ababd9dcd88303b1b1eb310d31bcae0a77ca2ce192a6470ff9f0e555d41cf45266994572b14a55cbbbb9c8ff0db1176d0464136d33152b85ec00b
+  data.tar.gz: b3fc5c6c76b7f6a4c4364abf12a7d7a23bfbb6b93c57d2449f74419f83f4c7a3f011c69629b7f3d7e46f7c4b6920faaf4682344a2d9f48d0bc556790fa45fd17

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-03-16
+
+### Added
+
+- Core authentication framework with `Custos::Authenticatable` concern
+- Plugin system with per-model configuration DSL
+- Session management with HMAC-SHA256 token digests and scope filtering
+- Controller helpers: `custos_authenticate!`, `custos_current`, `custos_session`
+- Token extraction from signed cookies and Authorization header
+- Callback system with configurable error strategy (`:log` / `:raise`)
+- Install and model generators
+
+#### Plugins
+
+- **Password** — Argon2id hashing, configurable complexity rules, timing-safe dummy verify
+- **Magic Link** — Passwordless email authentication with cooldown and expiry
+- **API Tokens** — Bearer token authentication with optional expiration
+- **MFA** — TOTP, backup codes (48-bit entropy), SMS verification
+- **Lockout** — Atomic SQL-based account lockout after failed attempts
+- **Email Confirmation** — Token-based email verification with configurable expiry
+- **Remember Me** — Persistent session tokens with rotation on use
+
+#### Security
+
+- HMAC-SHA256 token digests (plain-text tokens never persisted)
+- AES-256-GCM encryption for MFA secrets via `Custos::MfaEncryptor`
+- Timing-safe comparisons for all token verification
+- Atomic lockout updates (single SQL statement, no race conditions)
+- MFA rate limiting via Lockout plugin integration
+- Cleanup rake task for expired sessions and tokens

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ingvar
+
+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,117 @@
+# Custos
+
+[![Gem Version](https://img.shields.io/gem/v/custos)](https://rubygems.org/gems/custos)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0-red)](https://rubyonrails.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)
+
+Plugin-based authentication for Ruby on Rails. Modern, modular authentication that supports password, magic link, API tokens, MFA, and more — all as composable plugins.
+
+**No magic controllers.** Custos provides services and helpers, not generated controllers and routes. You stay in control. Email delivery, SMS, and other side effects are handled through callbacks — use Action Mailer, Postmark, or anything else.
+
+## Quick Start
+
+Add to your Gemfile:
+
+```ruby
+gem "custos"
+```
+
+Run the install generator:
+
+```bash
+bundle install
+rails generate custos:install
+rails db:migrate
+```
+
+Generate model authentication (pick the plugins you need):
+
+```bash
+rails generate custos:model User password magic_link lockout email_confirmation
+rails db:migrate
+```
+
+Configure your model:
+
+```ruby
+class User < ApplicationRecord
+  include Custos::Authenticatable
+
+  custos do
+    plugin :password, min_length: 10, require_digit: true
+    plugin :magic_link
+    plugin :lockout, max_attempts: 5
+    plugin :email_confirmation
+
+    on(:magic_link_created) do |record, token|
+      AuthMailer.magic_link(record, token).deliver_later
+    end
+
+    on(:email_confirmation_requested) do |record, token|
+      AuthMailer.confirm_email(record, token).deliver_later
+    end
+  end
+end
+```
+
+Authenticate in controllers:
+
+```ruby
+class DashboardController < ApplicationController
+  before_action :custos_authenticate!
+
+  def show
+    @user = custos_current
+  end
+end
+```
+
+## Plugins
+
+| Plugin | Description |
+|--------|-------------|
+| Password | Email + password authentication with Argon2 hashing |
+| Magic Link | Passwordless authentication via email links |
+| API Tokens | Bearer token authentication for APIs |
+| MFA | TOTP, backup codes, and SMS verification |
+| Lockout | Account lockout after failed attempts |
+| Email Confirmation | Email verification on sign-up |
+| Remember Me | Long-lived sessions via persistent tokens |
+
+Each plugin is standalone. Use password authentication for users and API tokens for service accounts — on the same app, with per-model configuration.
+
+## Security
+
+- **Argon2id** password hashing (resistant to GPU/ASIC attacks)
+- **HMAC-SHA256** token digests — plain-text tokens are never persisted
+- **AES-256-GCM** encrypted MFA secrets
+- **Timing-safe** comparisons for all token verification
+- **Atomic lockout** — race-condition-free via single SQL UPDATE
+- **256-bit entropy** session tokens
+
+## Configuration
+
+```ruby
+# config/initializers/custos.rb
+Custos.configure do |config|
+  config.session_expiry = 24 * 60 * 60     # 24 hours
+  config.token_length = 32                  # bytes
+  config.token_secret = Rails.application.secret_key_base
+  config.mfa_encryption_key = ENV["CUSTOS_MFA_KEY"]  # optional, enables MFA secret encryption
+  config.callback_error_strategy = :log     # :log or :raise
+end
+```
+
+## Documentation
+
+Full documentation is available at **[github.com/supostat/Custos](https://github.com/supostat/Custos)**.
+
+## Requirements
+
+- Ruby 3.2+
+- Rails 7.0+
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/custos/authenticatable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Custos
+  module Authenticatable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :custos_sessions,
+               class_name: 'Custos::Session',
+               as: :authenticatable,
+               dependent: :destroy
+    end
+
+    class_methods do
+      def custos(&block)
+        @custos_config = Custos::ModelConfig.new(self)
+        @custos_config.instance_eval(&block)
+        @custos_config
+      end
+
+      def custos_config
+        return @custos_config if instance_variable_defined?(:@custos_config)
+
+        superclass.custos_config if superclass.respond_to?(:custos_config)
+      end
+    end
+  end
+end

data/lib/custos/callback_registry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Custos
+  class CallbackRegistry
+    def self.fire(model_class, event_name, *args)
+      config = model_class.custos_config
+      return unless config
+
+      config.callbacks[event_name].each do |callback|
+        callback.call(*args)
+      rescue StandardError => e
+        handle_callback_error(event_name, e)
+      end
+    end
+
+    def self.fire_hooks(model_class, event_name, *args)
+      config = model_class.custos_config
+      return unless config
+
+      config.hooks[event_name].each { |hook| hook.call(*args) }
+    end
+
+    def self.handle_callback_error(event_name, error)
+      strategy = Custos.configuration.callback_error_strategy
+
+      raise error if strategy == :raise
+
+      if defined?(Rails.logger)
+        Rails.logger.error "[Custos] Callback error on #{event_name}: #{error.message}"
+      else
+        warn "[Custos] Callback error on #{event_name}: #{error.message}"
+      end
+    end
+
+    private_class_method :handle_callback_error
+  end
+end

data/lib/custos/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Custos
+  class Configuration
+    attr_accessor :session_expiry,
+                  :session_renewal_interval,
+                  :token_length,
+                  :scope_map,
+                  :token_secret,
+                  :mfa_encryption_key,
+                  :callback_error_strategy
+
+    def initialize
+      @session_expiry = 24 * 60 * 60 # 24 hours in seconds
+      @session_renewal_interval = 60 * 60       # 1 hour in seconds
+      @token_length = 32                        # bytes
+      @scope_map = {}                           # e.g. { user: "User", api_client: "ApiClient" }
+      @token_secret = nil                       # HMAC secret; falls back to Rails.application.secret_key_base
+      @mfa_encryption_key = nil                 # AES-256-GCM key for MFA secrets; nil = plaintext
+      @callback_error_strategy = :log           # :log or :raise
+    end
+
+    VALID_CLASS_NAME = /\A[A-Z][A-Za-z0-9]*(::[A-Z][A-Za-z0-9]*)*\z/
+
+    def model_class_for_scope(scope)
+      class_name = @scope_map[scope.to_sym]
+      return nil unless class_name
+      return nil unless class_name.match?(VALID_CLASS_NAME)
+
+      class_name.constantize
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/custos/controller_helpers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Custos
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    def custos_authenticate!(scope: :user)
+      return if custos_authenticated?(scope: scope)
+
+      raise Custos::NotAuthenticatedError, 'Authentication required'
+    end
+
+    def custos_authenticated?(scope: :user)
+      custos_current(scope: scope).present?
+    end
+
+    def custos_current(scope: :user)
+      ivar = "@custos_current_#{scope}"
+      return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+      session = resolve_custos_session(scope)
+      instance_variable_set(ivar, session&.authenticatable)
+    end
+
+    def custos_session
+      token = extract_custos_token
+      @custos_session ||= Custos::SessionManager.find_by_token(token) if token
+    end
+
+    private
+
+    def resolve_custos_session(scope)
+      token = extract_custos_token
+      return nil unless token
+
+      model_class = Custos.configuration.model_class_for_scope(scope)
+      Custos::SessionManager.find_by_token(token, authenticatable_type: model_class&.name)
+    end
+
+    def extract_custos_token
+      cookies.signed[:custos_session_token] ||
+        request.headers['Authorization']&.delete_prefix('Bearer ')
+    end
+  end
+end

data/lib/custos/mfa_encryptor.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module Custos
+  class MfaEncryptor
+    ENCRYPTED_PREFIX = 'enc:'
+    CIPHER = 'aes-256-gcm'
+    IV_LENGTH = 12
+    TAG_LENGTH = 16
+
+    class << self
+      def encrypt(plaintext)
+        key = encryption_key
+        return plaintext unless key
+
+        cipher = OpenSSL::Cipher.new(CIPHER)
+        cipher.encrypt
+        iv = cipher.random_iv
+        cipher.key = derive_key(key)
+        cipher.auth_data = ''
+
+        encrypted = cipher.update(plaintext) + cipher.final
+        tag = cipher.auth_tag
+
+        "#{ENCRYPTED_PREFIX}#{Base64.strict_encode64(iv + tag + encrypted)}"
+      end
+
+      def decrypt(ciphertext)
+        key = encryption_key
+        return ciphertext unless key
+        return ciphertext unless ciphertext&.start_with?(ENCRYPTED_PREFIX)
+
+        raw = Base64.strict_decode64(ciphertext.delete_prefix(ENCRYPTED_PREFIX))
+        iv = raw.byteslice(0, IV_LENGTH)
+        tag = raw.byteslice(IV_LENGTH, TAG_LENGTH)
+        encrypted = raw.byteslice((IV_LENGTH + TAG_LENGTH)..)
+
+        cipher = OpenSSL::Cipher.new(CIPHER)
+        cipher.decrypt
+        cipher.key = derive_key(key)
+        cipher.iv = iv
+        cipher.auth_tag = tag
+        cipher.auth_data = ''
+
+        cipher.update(encrypted) + cipher.final
+      rescue ArgumentError, OpenSSL::Cipher::CipherError => e
+        raise Custos::DecryptionError, "MFA decryption failed: #{e.class}"
+      end
+
+      private
+
+      def encryption_key
+        Custos.configuration.mfa_encryption_key
+      end
+
+      def derive_key(key)
+        OpenSSL::Digest::SHA256.digest(key)
+      end
+    end
+  end
+end

data/lib/custos/model_config.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Custos
+  class ModelConfig
+    attr_reader :model_class, :loaded_plugins, :callbacks, :hooks
+
+    def initialize(model_class)
+      @model_class = model_class
+      @loaded_plugins = {}
+      @callbacks = Hash.new { |hash, key| hash[key] = [] }
+      @hooks = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def plugin(name, **options)
+      mod = Custos::Plugin.resolve(name)
+      mod.apply(@model_class, **options)
+      @loaded_plugins[name.to_sym] = options
+    end
+
+    def on(event_name, &block)
+      @callbacks[event_name.to_sym] << block
+    end
+
+    def hook(event_name, &block)
+      @hooks[event_name.to_sym] << block
+    end
+
+    def plugin_enabled?(name)
+      @loaded_plugins.key?(name.to_sym)
+    end
+
+    def plugin_options(name)
+      @loaded_plugins.fetch(name.to_sym) { raise Custos::UnknownPluginError, "Plugin #{name} is not loaded" }
+    end
+  end
+end

data/lib/custos/models/api_token.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Custos
+  class ApiToken < ActiveRecord::Base
+    self.table_name = 'custos_api_tokens'
+
+    belongs_to :authenticatable, polymorphic: true
+
+    scope :active, -> { where(revoked_at: nil).where('expires_at IS NULL OR expires_at > ?', Time.current) }
+
+    def revoke!
+      update!(revoked_at: Time.current)
+    end
+
+    def revoked?
+      revoked_at.present?
+    end
+
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+  end
+end

data/lib/custos/models/magic_link_token.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Custos
+  class MagicLinkToken < ActiveRecord::Base
+    self.table_name = 'custos_magic_links'
+
+    belongs_to :authenticatable, polymorphic: true
+
+    scope :unused, -> { where(used_at: nil) }
+    scope :not_expired, -> { where('expires_at > ?', Time.current) }
+    scope :valid_tokens, -> { unused.not_expired }
+  end
+end

data/lib/custos/models/mfa_credential.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Custos
+  class MfaCredential < ActiveRecord::Base
+    self.table_name = 'custos_mfa_credentials'
+
+    belongs_to :authenticatable, polymorphic: true
+
+    scope :enabled, -> { where.not(enabled_at: nil) }
+    scope :by_method, ->(method_name) { where(method: method_name) }
+
+    def secret_data
+      Custos::MfaEncryptor.decrypt(super)
+    rescue Custos::DecryptionError
+      nil
+    end
+
+    def secret_data=(value)
+      super(Custos::MfaEncryptor.encrypt(value))
+    end
+  end
+end

data/lib/custos/models/remember_token.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Custos
+  class RememberToken < ActiveRecord::Base
+    self.table_name = 'custos_remember_tokens'
+
+    belongs_to :authenticatable, polymorphic: true
+
+    scope :not_expired, -> { where('expires_at > ?', Time.current) }
+  end
+end

data/lib/custos/plugin.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Custos
+  module Plugin
+    @registry = {}
+    @mutex = Mutex.new
+
+    class << self
+      def register(name, mod)
+        @mutex.synchronize { @registry[name.to_sym] = mod }
+      end
+
+      def resolve(name)
+        @mutex.synchronize do
+          @registry.fetch(name.to_sym) do
+            raise Custos::UnknownPluginError, "Unknown plugin: #{name}"
+          end
+        end
+      end
+
+      def registered?(name)
+        @mutex.synchronize { @registry.key?(name.to_sym) }
+      end
+
+      def registered_names
+        @mutex.synchronize { @registry.keys }
+      end
+    end
+  end
+end

data/lib/custos/plugins/api_tokens.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Custos
+  module Plugins
+    module ApiTokens
+      def self.apply(model_class, **_options)
+        model_class.has_many :custos_api_tokens,
+                             class_name: 'Custos::ApiToken',
+                             as: :authenticatable,
+                             dependent: :destroy
+
+        model_class.include(InstanceMethods)
+        model_class.extend(ClassMethods)
+      end
+
+      module InstanceMethods
+        def generate_api_token(expires_in: nil)
+          token = Custos::TokenGenerator.generate
+
+          default_expiry = self.class.custos_config.plugin_options(:api_tokens).fetch(:default_expiry, nil)
+          expiry = expires_in || default_expiry
+
+          custos_api_tokens.create!(
+            token_digest: Custos::TokenGenerator.digest(token),
+            expires_at: expiry ? Time.current + expiry : nil
+          )
+          token
+        end
+      end
+
+      module ClassMethods
+        def authenticate_api_token(token)
+          digest = Custos::TokenGenerator.digest(token)
+          api_token = Custos::ApiToken.active.find_by(
+            token_digest: digest,
+            authenticatable_type: name
+          )
+          return nil unless api_token
+
+          api_token.update_column(:last_used_at, Time.current)
+          api_token.authenticatable
+        end
+      end
+    end
+  end
+end
+
+Custos::Plugin.register(:api_tokens, Custos::Plugins::ApiTokens)

data/lib/custos/plugins/email_confirmation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Custos
+  module Plugins
+    module EmailConfirmation
+      DEFAULT_CONFIRMATION_EXPIRY = 24 * 60 * 60 # 24 hours in seconds
+
+      def self.apply(model_class, **_options)
+        model_class.include(InstanceMethods)
+      end
+
+      module InstanceMethods
+        def send_email_confirmation
+          token = Custos::TokenGenerator.generate
+          update!(
+            email_confirmation_token_digest: Custos::TokenGenerator.digest(token),
+            email_confirmation_sent_at: Time.current
+          )
+
+          Custos::CallbackRegistry.fire(self.class, :email_confirmation_requested, self, token)
+          token
+        end
+
+        def confirm_email!(token)
+          digest = Custos::TokenGenerator.digest(token)
+          stored = email_confirmation_token_digest || ''
+
+          token_matches = Custos::TokenGenerator.secure_compare(stored, digest)
+          return false unless token_matches
+          return false if confirmation_token_expired?
+
+          update!(
+            email_confirmed_at: Time.current,
+            email_confirmation_token_digest: nil
+          )
+
+          Custos::CallbackRegistry.fire(self.class, :email_confirmed, self)
+          true
+        end
+
+        def email_confirmed?
+          email_confirmed_at.present?
+        end
+
+        private
+
+        def confirmation_token_expired?
+          return true if email_confirmation_sent_at.nil?
+
+          options = self.class.custos_config.plugin_options(:email_confirmation)
+          expiry = options.fetch(:confirmation_expiry, DEFAULT_CONFIRMATION_EXPIRY)
+          email_confirmation_sent_at < expiry.seconds.ago
+        end
+      end
+    end
+  end
+end
+
+Custos::Plugin.register(:email_confirmation, Custos::Plugins::EmailConfirmation)