rodauth-model 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ea8768862eb1ba1bf2bdf1bb93872c0167230bf8c139ca49db5b17927288797
+  data.tar.gz: fe85b970b503ecd33a9c074d1b8763616e65fac5e88fd0fbbd49d2b986ae29ea
+SHA512:
+  metadata.gz: 4b3f777be5c15eadacb69e074a4bf7b9aacad161e3b6c98f4c2f7ac0a3712af07259e82e62b339e18539522d98694d5d38d95318a11b10cac43c3cf042e87f0e
+  data.tar.gz: 7788e39bd9de5138773a90c5cac2babdef39da6b9a2a557a37af902c4b1bc851ec26e7e09dd6c6a62d799c3b39198750c39a24560025c2acb7e9fb0223bb4379

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-01-04
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Janko Marohnić
+
+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,202 @@
+# rodauth-model
+
+Extension for [Rodauth] providing a mixin for the account model that defines password attribute and associations based on enabled authentication features. At the moment only Active Record is supported.
+
+## Installation
+
+```sh
+$ bundle add rodauth-model
+```
+
+## Usage
+
+Assuming with have a `RodauthApp` Roda subclass with Rodauth configured, we can build the mixin from a Rodauth class, and include it into the account model:
+
+```rb
+require "rodauth/model" # require before enabling any authentication features
+
+class RodauthApp < Roda
+  plugin :rodauth do
+    # ...
+  end
+end
+```
+```rb
+class Account < ActiveRecord::Base
+  include Rodauth::Model(RodauthApp.rodauth)
+end
+```
+
+If you have multiple Rodauth configurations, pass the one for which you want associations to be defined.
+
+```rb
+class Account < ActiveRecord::Base
+  include Rodauth::Model(RodauthApp.rodauth(:admin))
+end
+```
+
+### Password attribute
+
+Regardless of whether you're storing the password hash in a column in the accounts table, or in a separate table, the `#password` attribute can be used to set or clear the password hash.
+
+```rb
+account = Account.create!(email: "user@example.com", password: "secret")
+
+# when password hash is stored in a column on the accounts table
+account.password_hash #=> "$2a$12$k/Ub1I2iomi84RacqY89Hu4.M0vK7klRnRtzorDyvOkVI.hKhkNw."
+
+# when password hash is stored in a separate table
+account.password_hash #=> #<Account::PasswordHash...> (record from `account_password_hashes` table)
+account.password_hash.password_hash #=> "$2a$12$k/Ub1..." (inaccessible when using database authentication functions)
+
+account.password = nil # clears password hash
+account.password_hash #=> nil
+```
+
+Note that the password attribute doesn't come with validations, making it unsuitable for forms. It was primarily intended to allow easily creating accounts in development console and in tests.
+
+### Associations
+
+The mixin defines associations for Rodauth tables associated to the accounts table:
+
+```rb
+account.remember_key #=> #<Account::RememberKey> (record from `account_remember_keys` table)
+account.active_session_keys #=> [#<Account::ActiveSessionKey>,...] (records from `account_active_session_keys` table)
+```
+
+You can also reference the associated models directly:
+
+```rb
+# model referencing the `account_authentication_audit_logs` table
+Account::AuthenticationAuditLog.where(message: "login").group(:account_id)
+```
+
+The associated models define the inverse `belongs_to :account` association:
+
+```rb
+Account::ActiveSessionKey.includes(:account).map(&:account)
+```
+
+### Association options
+
+By default, all associations except for audit logs have `dependent: :delete` set, to allow for easy deletion of account records in the console. You can use `:association_options` to modify global or per-association options:
+
+```rb
+# don't auto-delete associations when account model is deleted
+Rodauth::Model(RodauthApp.rodauth, association_options: { dependent: nil })
+
+# require authentication audit logs to be eager loaded before retrieval
+Rodauth::Model(RodauthApp.rodauth, association_options: -> (name) {
+  { strict_loading: true } if name == :authentication_audit_logs
+})
+```
+
+## Association reference
+
+Below is a list of all associations defined depending on the features loaded:
+
+| Feature                 | Association                  | Type       | Model                    | Table (default)                     |
+| :------                 | :----------                  | :---       | :----                    | :----                               |
+| account_expiration      | `:activity_time`             | `has_one`  | `ActivityTime`           | `account_activity_times`            |
+| active_sessions         | `:active_session_keys`       | `has_many` | `ActiveSessionKey`       | `account_active_session_keys`       |
+| audit_logging           | `:authentication_audit_logs` | `has_many` | `AuthenticationAuditLog` | `account_authentication_audit_logs` |
+| disallow_password_reuse | `:previous_password_hashes`  | `has_many` | `PreviousPasswordHash`   | `account_previous_password_hashes`  |
+| email_auth              | `:email_auth_key`            | `has_one`  | `EmailAuthKey`           | `account_email_auth_keys`           |
+| jwt_refresh             | `:jwt_refresh_keys`          | `has_many` | `JwtRefreshKey`          | `account_jwt_refresh_keys`          |
+| lockout                 | `:lockout`                   | `has_one`  | `Lockout`                | `account_lockouts`                  |
+| lockout                 | `:login_failure`             | `has_one`  | `LoginFailure`           | `account_login_failures`            |
+| otp                     | `:otp_key`                   | `has_one`  | `OtpKey`                 | `account_otp_keys`                  |
+| password_expiration     | `:password_change_time`      | `has_one`  | `PasswordChangeTime`     | `account_password_change_times`     |
+| recovery_codes          | `:recovery_codes`            | `has_many` | `RecoveryCode`           | `account_recovery_codes`            |
+| remember                | `:remember_key`              | `has_one`  | `RememberKey`            | `account_remember_keys`             |
+| reset_password          | `:password_reset_key`        | `has_one`  | `PasswordResetKey`       | `account_password_reset_keys`       |
+| single_session          | `:session_key`               | `has_one`  | `SessionKey`             | `account_session_keys`              |
+| sms_codes               | `:sms_code`                  | `has_one`  | `SmsCode`                | `account_sms_codes`                 |
+| verify_account          | `:verification_key`          | `has_one`  | `VerificationKey`        | `account_verification_keys`         |
+| verify_login_change     | `:login_change_key`          | `has_one`  | `LoginChangeKey`         | `account_login_change_keys`         |
+| webauthn                | `:webauthn_keys`             | `has_many` | `WebauthnKey`            | `account_webauthn_keys`             |
+| webauthn                | `:webauthn_user_id`          | `has_one`  | `WebauthnUserId`         | `account_webauthn_user_ids`         |
+
+Note that some Rodauth tables use composite primary keys, which Active Record doesn't support out of the box. For associations to work properly, you might need to add the [composite_primary_keys] gem to your Gemfile.
+
+## Extending associations
+
+It's possible to register custom associations for an external feature, which the model mixin would pick up and automatically define the association on the model if the feature is enabled.
+
+```rb
+# lib/rodauth/features/foo.rb
+module Rodauth
+  Feature.define(:foo, :Foo) do
+    auth_value_method :foo_table, :account_foos
+    auth_value_method :foo_id_column, :id
+    # ...
+  end
+
+  if defined?(Model)
+    Model.register_association(:foo) do
+      { name: :foo, type: :one, table: foo_table, key: foo_id_column }
+    end
+  end
+end
+```
+
+The `Rodauth::Model.register_association` method receives the feature name and a block, which is evaluted in the context of a Rodauth instance and should return the association definition with the following items:
+
+* `:name` – association name
+* `:type` – relationship type (`:one` for one-to-one, `:many` for one-to-many)
+* `:table` – associated table name
+* `:key` – foreign key on the associated table
+
+It's possible to register multiple associations for the same Rodauth feature.
+
+## Examples
+
+### Checking whether account has multifactor authentication enabled
+
+```rb
+class Account < ActiveRecord::Base
+  include Rodauth::Model(RodauthApp.rodauth)
+
+  def mfa_enabled?
+    otp_key || (sms_code && sms_code.num_failures.nil?) || recovery_codes.any?
+  end
+end
+```
+
+### Retrieving all accounts with multifactor authentication enabled
+
+```rb
+class Account < ActiveRecord::Base
+  include Rodauth::Model(RodauthApp.rodauth)
+
+  scope :otp_setup, -> { where(otp_key: OtpKey.all) }
+  scope :sms_codes_setup, -> { where(sms_code: SmsCode.where(num_failures: nil)) }
+  scope :recovery_codes_setup, -> { where(recovery_codes: RecoveryCode.all) }
+  scope :mfa_enabled, -> { merge(otp_setup.or(sms_codes_setup).or(recovery_codes_setup)) }
+end
+```
+
+## Future plans
+
+### Sequel support
+
+Currently on Active Record models are supported, but I would like support Sequel models in the near future as well.
+
+### Joined associations
+
+It's possible to have multiple Rodauth configurations that operate on the same tables, but it's currently possible to define associations just for a single configuration. I would like to support grabbing associations from multiple associations.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/janko/rodauth-model. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/janko/rodauth-model/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Rodauth::Model project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/janko/rodauth-model/blob/main/CODE_OF_CONDUCT.md).
+
+[Rodauth]: https://rodauth.jeremyevans.net
+[composite_primary_keys]: https://github.com/composite-primary-keys/composite_primary_keys

data/lib/rodauth/model/active_record.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "rodauth/model/associations"
+
+module Rodauth
+  class Model
+    module ActiveRecord
+      ASSOCIATION_TYPES = { one: :has_one, many: :has_many }
+
+      private
+
+      def define_methods(model)
+        rodauth = @auth_class.allocate.freeze
+
+        attr_reader :password
+
+        define_method(:password=) do |password|
+          @password = password
+          password_hash = rodauth.send(:password_hash, password) if password
+          set_password_hash(password_hash)
+        end
+
+        define_method(:set_password_hash) do |password_hash|
+          if rodauth.account_password_hash_column
+            public_send(:"#{rodauth.account_password_hash_column}=", password_hash)
+          else
+            if password_hash
+              record = self.password_hash || build_password_hash
+              record.public_send(:"#{rodauth.password_hash_column}=", password_hash)
+            else
+              self.password_hash&.mark_for_destruction
+            end
+          end
+        end
+      end
+
+      def define_associations(model)
+        define_password_hash_association(model) unless rodauth.account_password_hash_column
+
+        feature_associations.each do |association|
+          association[:type] = ASSOCIATION_TYPES.fetch(association[:type])
+          association[:foreign_key] = association.delete(:key)
+
+          define_association(model, **association)
+        end
+      end
+
+      def define_password_hash_association(model)
+        password_hash_id_column = rodauth.password_hash_id_column
+        scope = -> { select(password_hash_id_column) } if rodauth.send(:use_database_authentication_functions?)
+
+        define_association model,
+          type: :has_one,
+          name: :password_hash,
+          table: rodauth.password_hash_table,
+          foreign_key: password_hash_id_column,
+          scope: scope,
+          autosave: true
+      end
+
+      def define_association(model, type:, name:, table:, foreign_key:, scope: nil, **options)
+        associated_model = Class.new(model.superclass)
+        associated_model.table_name = table
+        associated_model.belongs_to :account,
+          class_name: model.name,
+          foreign_key: foreign_key,
+          inverse_of: name
+
+        model.const_set(name.to_s.singularize.camelize, associated_model)
+
+        unless name == :authentication_audit_logs
+          dependent = type == :has_many ? :delete_all : :delete
+        end
+
+        model.public_send type, name, scope,
+          class_name: associated_model.name,
+          foreign_key: foreign_key,
+          dependent: dependent,
+          inverse_of: :account,
+          **options,
+          **association_options(name)
+      end
+
+      def association_options(name)
+        options = @association_options
+        options = options.call(name) if options.respond_to?(:call)
+        options || {}
+      end
+    end
+  end
+end

data/lib/rodauth/model/associations.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Rodauth
+  Model.register_association(:remember) do
+    { name: :remember_key, type: :one, table: remember_table, key: remember_id_column }
+  end
+  Model.register_association(:verify_account) do
+    { name: :verification_key, type: :one, table: verify_account_table, key: verify_account_id_column }
+  end
+  Model.register_association(:reset_password) do
+    { name: :password_reset_key, type: :one, table: reset_password_table, key: reset_password_id_column }
+  end
+  Model.register_association(:verify_login_change) do
+    { name: :login_change_key, type: :one, table: verify_login_change_table, key: verify_login_change_id_column }
+  end
+  Model.register_association(:lockout) do
+    { name: :lockout, type: :one, table: account_lockouts_table, key: account_lockouts_id_column }
+  end
+  Model.register_association(:lockout) do
+    { name: :login_failure, type: :one, table: account_login_failures_table, key: account_login_failures_id_column }
+  end
+  Model.register_association(:email_auth) do
+    { name: :email_auth_key, type: :one, table: email_auth_table, key: email_auth_id_column }
+  end
+  Model.register_association(:account_expiration) do
+    { name: :activity_time, type: :one, table: account_activity_table, key: account_activity_id_column }
+  end
+  Model.register_association(:active_sessions) do
+    { name: :active_session_keys, type: :many, table: active_sessions_table, key: active_sessions_account_id_column }
+  end
+  Model.register_association(:audit_logging) do
+    { name: :authentication_audit_logs, type: :many, table: audit_logging_table, key: audit_logging_account_id_column }
+  end
+  Model.register_association(:disallow_password_reuse) do
+    { name: :previous_password_hashes, type: :many, table: previous_password_hash_table, key: previous_password_account_id_column }
+  end
+  Model.register_association(:jwt_refresh) do
+    { name: :jwt_refresh_keys, type: :many, table: jwt_refresh_token_table, key: jwt_refresh_token_account_id_column }
+  end
+  Model.register_association(:password_expiration) do
+    { name: :password_change_time, type: :one, table: password_expiration_table, key: password_expiration_id_column }
+  end
+  Model.register_association(:single_session) do
+    { name: :session_key, type: :one, table: single_session_table, key: single_session_id_column }
+  end
+  Model.register_association(:otp) do
+    { name: :otp_key, type: :one, table: otp_keys_table, key: otp_keys_id_column }
+  end
+  Model.register_association(:sms_codes) do
+    { name: :sms_code, type: :one, table: sms_codes_table, key: sms_id_column }
+  end
+  Model.register_association(:recovery_codes) do
+    { name: :recovery_codes, type: :many, table: recovery_codes_table, key: recovery_codes_id_column }
+  end
+  Model.register_association(:webauthn) do
+    { name: :webauthn_user_id, type: :one, table: webauthn_user_ids_table, key: webauthn_user_ids_account_id_column }
+  end
+  Model.register_association(:webauthn) do
+    { name: :webauthn_keys, type: :many, table: webauthn_keys_table, key: webauthn_keys_account_id_column }
+  end
+end

data/lib/rodauth/model.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rodauth
+  def self.Model(*args, **options)
+    Rodauth::Model.new(*args, **options)
+  end
+
+  class Model < Module
+    Error = Class.new(StandardError)
+
+    autoload :ActiveRecord, "rodauth/model/active_record"
+
+    def self.associations
+      @associations ||= {}
+    end
+
+    def self.register_association(feature, &block)
+      associations[feature] ||= []
+      associations[feature] << block
+    end
+
+    def initialize(auth_class, association_options: {})
+      @auth_class = auth_class
+      @association_options = association_options
+    end
+
+    def included(model)
+      if defined?(::ActiveRecord::Base) && model < ::ActiveRecord::Base
+        extend Rodauth::Model::ActiveRecord
+      elsif defined?(::Sequel::Model) && model < ::Sequel::Model
+        raise Error, "Sequel models are not yet supported"
+      else
+        raise Error, "must be an Active Record model"
+      end
+
+      define_associations(model)
+      define_methods(model)
+    end
+
+    def inspect
+      "#<#{self.class}(#{@auth_class.inspect})>"
+    end
+
+    private
+
+    def feature_associations
+      self.class.associations
+        .values_at(*rodauth.features)
+        .compact
+        .flatten
+        .map { |block| rodauth.instance_exec(&block) }
+    end
+
+    def rodauth
+      @auth_class.allocate
+    end
+  end
+end
+
+require "rodauth/model/associations"

data/lib/rodauth-model.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "rodauth/model"

data/rodauth-model.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "rodauth-model"
+  spec.version       = "0.1.0"
+  spec.authors       = ["Janko Marohnić"]
+  spec.email         = ["janko@hey.com"]
+
+  spec.description   = "Provides model mixin for Active Record and Sequel that defines password attribute and associations based on Rodauth configuration."
+  spec.summary       = spec.description
+  spec.homepage      = "https://github.com/janko/rodauth-model"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.3"
+
+  spec.metadata["source_code_uri"] = "https://github.com/janko/rodauth-model"
+
+  spec.files         = Dir["README.md", "LICENSE.txt", "CHANGELOG.md", "lib/**/*", "*.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rodauth", "~> 2.0"
+
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "minitest-hooks"
+  spec.add_development_dependency "bcrypt"
+  spec.add_development_dependency "jwt"
+  spec.add_development_dependency "rotp"
+  spec.add_development_dependency "rqrcode"
+  spec.add_development_dependency "webauthn" unless RUBY_ENGINE == "jruby"
+end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: rodauth-model
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Janko Marohnić
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-05-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rodauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-hooks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bcrypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rotp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rqrcode
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webauthn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides model mixin for Active Record and Sequel that defines password
+  attribute and associations based on Rodauth configuration.
+email:
+- janko@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rodauth-model.rb
+- lib/rodauth/model.rb
+- lib/rodauth/model/active_record.rb
+- lib/rodauth/model/associations.rb
+- rodauth-model.gemspec
+homepage: https://github.com/janko/rodauth-model
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/janko/rodauth-model
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Provides model mixin for Active Record and Sequel that defines password attribute
+  and associations based on Rodauth configuration.
+test_files: []