yes-auth 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b8e3b75db27fa4e2079f268a02bbb3a3d3321a65dc25d7d167888cf8d7f222e
+  data.tar.gz: 3def0c48b89e0a3b42032d215d574c6cfb388a8ca40b08d3d07045665520e907
+SHA512:
+  metadata.gz: 60b40d20b625ca87978ed8238d7bb4f5d571217afeca6eb809cfaaff960d9278ff05c88d888740ae7dca9f059d90a07f8e2e552eb5f09ff762ee13df91a3e828
+  data.tar.gz: 6f7bccb82e4c9b9f4074e76e9595454e1153a3cbb6147fc1dbe86aaf29c4e525aaf84580749dba78a08c6ac259ac44fe78ae1dae1072431f7d5e3d8a2a9db7d0

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [1.0.0] - 2026-03-25
+
+### Added
+
+- Initial release
+- Authorization principal models (User, Role, ReadResourceAccess, WriteResourceAccess)
+- Cerbos principal data builders for read and write resource access

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 ncri
+
+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,137 @@
+# Yes Auth
+
+Authorization principals and Cerbos integration for the [Yes](https://github.com/yousty/yes) event sourcing framework.
+
+## Overview
+
+`yes-auth` provides ActiveRecord-backed authorization principal models and Cerbos principal data builders. It is designed to work with `yes-core` to provide role-based access control with fine-grained read and write resource access permissions.
+
+### Principal Models
+
+- **User** - represents an authorization principal with roles and resource accesses
+- **Role** - named roles that can be assigned to users and resource accesses
+- **ReadResourceAccess** - links a principal to a role-based read permission scoped by service, scope, and resource type
+- **WriteResourceAccess** - links a principal to a role-based write permission scoped by context and resource type
+
+### Cerbos Integration
+
+- **WriteResourceAccess::PrincipalData** - builds Cerbos principal data from write resource accesses
+- **ReadResourceAccess::PrincipalData** - builds Cerbos principal data from read resource accesses
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'yes-auth'
+```
+
+Or if using a monorepo with path references:
+
+```ruby
+gem 'yes-auth', path: 'yes-auth'
+```
+
+### Auto-Configuration
+
+When loaded in a Rails application, yes-auth automatically configures the Cerbos principal data builders in yes-core:
+
+- `config.cerbos_principal_data_builder` → `Yes::Auth::Cerbos::WriteResourceAccess::PrincipalData`
+- `config.cerbos_read_principal_data_builder` → `Yes::Auth::Cerbos::ReadResourceAccess::PrincipalData`
+
+This means you don't need to manually configure these in your initializer — just adding `yes-auth` to your Gemfile is enough.
+
+To override the default builders, set them explicitly in your initializer (after yes-auth's railtie runs):
+
+```ruby
+Yes::Core.configure do |config|
+  config.cerbos_principal_data_builder = MyCustomPrincipalDataBuilder.method(:call)
+end
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CERBOS_URL` | `cerbos-cluster-ip-service:3593` | Cerbos server address (set via yes-core config) |
+
+## Usage
+
+### Principal Models
+
+```ruby
+# Find a user by identity
+user = Yes::Auth::Principals::User.find_by(identity_id: 'user-uuid')
+
+# Check roles
+user.read_resource_access_authorization_roles
+user.write_resource_access_authorization_roles
+user.super_admin?
+
+# Access resource permissions
+user.read_resource_accesses
+user.write_resource_accesses
+```
+
+### Cerbos Principal Data
+
+Build principal data for Cerbos authorization checks:
+
+```ruby
+# For write operations
+write_data = Yes::Auth::Cerbos::WriteResourceAccess::PrincipalData.call(
+  identity_id: 'user-uuid'
+)
+# => { id: 'identity-id', roles: ['manager'], attributes: { write_resource_access: { ... } } }
+
+# For read operations
+read_data = Yes::Auth::Cerbos::ReadResourceAccess::PrincipalData.call(
+  identity_id: 'user-uuid'
+)
+# => { id: 'identity-id', roles: ['viewer'], attributes: { read_resource_access: { ... } } }
+```
+
+### Configuration
+
+Plug into `yes-core`'s Cerbos authorization by configuring the principal data builder:
+
+```ruby
+# config/initializers/yes.rb
+Yes::Core.configure do |config|
+  config.cerbos_principal_data_builder = Yes::Auth::Cerbos::WriteResourceAccess::PrincipalData
+end
+```
+
+For read APIs that need read-scoped authorization:
+
+```ruby
+Yes::Core.configure do |config|
+  config.cerbos_principal_data_builder = Yes::Auth::Cerbos::ReadResourceAccess::PrincipalData
+end
+```
+
+## Database Schema
+
+The gem expects the following tables to exist:
+
+- `auth_principals_users` - stores user principals
+- `auth_principals_roles` - stores named roles
+- `auth_principals_read_resource_accesses` - stores read resource access records
+- `auth_principals_write_resource_accesses` - stores write resource access records
+- A join table for the users-roles HABTM association
+
+## Development
+
+```bash
+cd yes-auth
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+See the [contributing guide](../CONTRIBUTING.md) for instructions on how to contribute to the Yes framework.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/yes/auth/cerbos/read_resource_access/principal_attributes.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module Cerbos
+      module ReadResourceAccess
+        # Builds principal attributes for Cerbos authorization based on read resource accesses.
+        #
+        # @example Building attributes
+        #   Yes::Auth::Cerbos::ReadResourceAccess::PrincipalAttributes.call(
+        #     principal: user,
+        #     read_resource_accesses: accesses
+        #   )
+        class PrincipalAttributes
+          class << self
+            # @param principal [Yes::Auth::Principals::User, nil] the principal user
+            # @param read_resource_accesses [Array, ActiveRecord::Relation] read resource accesses
+            # @return [HashWithIndifferentAccess] Cerbos principal attributes
+            def call(principal: nil, read_resource_accesses: [])
+              return {} unless principal
+
+              {
+                **(principal.auth_attributes || {}),
+                read_resource_access: read_attributes(read_resource_accesses)
+              }.with_indifferent_access
+            end
+
+            private
+
+            # @param accesses [Array, ActiveRecord::Relation] read resource accesses
+            # @return [Hash] nested hash of read resource access attributes
+            def read_attributes(accesses)
+              attributes = Hash.new { |h, k| h[k] = Hash.new(&h.default_proc) }
+
+              accesses.each do |access|
+                next unless access.authorization_complete?
+
+                attributes[access.service][access.scope][access.resource_type][access.role&.resource_authorization_name][access.resource_id] =
+                  access.auth_attributes || {}
+              end
+
+              attributes
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/cerbos/read_resource_access/principal_data.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module Cerbos
+      module ReadResourceAccess
+        # Builds principal data for Cerbos authorization based on read resource accesses.
+        #
+        # @example Building principal data
+        #   Yes::Auth::Cerbos::ReadResourceAccess::PrincipalData.call(identity_id: 'user-uuid')
+        #   # => { id: 'identity-id', roles: ['role1'], attributes: { ... } }
+        class PrincipalData
+          class << self
+            # @param auth_data [Hash] authentication data containing :identity_id
+            # @return [Hash] Cerbos-compatible principal data, or empty hash if principal not found
+            def call(auth_data)
+              return {} unless (principal = load_principal(auth_data[:identity_id]))
+
+              read_resource_accesses = load_read_resource_accesses(principal.id)
+
+              {
+                id: principal.identity_id,
+                roles: roles(principal),
+                attributes: attributes(principal, read_resource_accesses)
+              }.with_indifferent_access
+            end
+
+            private
+
+            # @param principal_id [String] the principal's database ID
+            # @return [ActiveRecord::Relation] read resource accesses with joined roles
+            def load_read_resource_accesses(principal_id)
+              Principals::ReadResourceAccess.eager_load(:role).where(principal_id:)
+            end
+
+            # @param identity_id [String] the identity ID to look up
+            # @return [Yes::Auth::Principals::User, nil] the found principal or nil
+            def load_principal(identity_id)
+              Principals::User.includes(:roles).find_by(identity_id:)
+            end
+
+            # @param principal [Yes::Auth::Principals::User] the principal user
+            # @return [Array<String>] authorization roles or fallback roles
+            def roles(principal)
+              principal.read_resource_access_authorization_roles.presence || Principals::User::NO_AUTHORIZATION_ROLES_YET
+            end
+
+            # @param principal [Yes::Auth::Principals::User] the principal user
+            # @param read_resource_accesses [ActiveRecord::Relation] the read resource accesses
+            # @return [Hash] Cerbos principal attributes
+            def attributes(principal, read_resource_accesses)
+              PrincipalAttributes.call(principal:, read_resource_accesses:)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/cerbos/write_resource_access/principal_attributes.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module Cerbos
+      module WriteResourceAccess
+        # Builds principal attributes for Cerbos authorization based on write resource accesses.
+        #
+        # @example Building attributes
+        #   Yes::Auth::Cerbos::WriteResourceAccess::PrincipalAttributes.call(
+        #     principal: user,
+        #     write_resource_accesses: accesses
+        #   )
+        class PrincipalAttributes
+          class << self
+            # @param principal [Yes::Auth::Principals::User, nil] the principal user
+            # @param write_resource_accesses [Array, ActiveRecord::Relation] write resource accesses
+            # @return [HashWithIndifferentAccess] Cerbos principal attributes
+            def call(principal: nil, write_resource_accesses: [])
+              return {} unless principal
+
+              {
+                **(principal.auth_attributes || {}),
+                write_resource_access: write_attributes(write_resource_accesses)
+              }.with_indifferent_access
+            end
+
+            private
+
+            # @param accesses [Array, ActiveRecord::Relation] write resource accesses
+            # @return [Hash] nested hash of write resource access attributes
+            def write_attributes(accesses)
+              attributes = Hash.new { |h, k| h[k] = Hash.new(&h.default_proc) }
+
+              accesses.each do |access|
+                next unless access.authorization_complete?
+
+                attributes[access.context][access.resource_type][access.role&.resource_authorization_name][access.resource_id] =
+                  access.auth_attributes || {}
+              end
+
+              attributes
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/cerbos/write_resource_access/principal_data.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module Cerbos
+      module WriteResourceAccess
+        # Builds principal data for Cerbos authorization based on write resource accesses.
+        #
+        # @example Building principal data
+        #   Yes::Auth::Cerbos::WriteResourceAccess::PrincipalData.call(identity_id: 'user-uuid')
+        #   # => { id: 'identity-id', roles: ['role1'], attributes: { ... } }
+        class PrincipalData
+          class << self
+            # @param auth_data [Hash] authentication data containing :identity_id
+            # @return [Hash] Cerbos-compatible principal data, or empty hash if principal not found
+            def call(auth_data)
+              return {} unless (principal = load_principal(auth_data[:identity_id]))
+
+              write_resource_accesses = load_write_resource_accesses(principal.id)
+
+              {
+                id: principal.identity_id,
+                roles: roles(principal),
+                attributes: attributes(principal, write_resource_accesses)
+              }.with_indifferent_access
+            end
+
+            private
+
+            # @param principal_id [String] the principal's database ID
+            # @return [ActiveRecord::Relation] write resource accesses with joined roles
+            def load_write_resource_accesses(principal_id)
+              Principals::WriteResourceAccess.eager_load(:role).where(principal_id:)
+            end
+
+            # @param identity_id [String] the identity ID to look up
+            # @return [Yes::Auth::Principals::User, nil] the found principal or nil
+            def load_principal(identity_id)
+              Principals::User.includes(:roles).find_by(identity_id:)
+            end
+
+            # @param principal [Yes::Auth::Principals::User] the principal user
+            # @return [Array<String>] authorization roles or fallback roles
+            def roles(principal)
+              principal.write_resource_access_authorization_roles.presence || Principals::User::NO_AUTHORIZATION_ROLES_YET
+            end
+
+            # @param principal [Yes::Auth::Principals::User] the principal user
+            # @param write_resource_accesses [ActiveRecord::Relation] the write resource accesses
+            # @return [Hash] Cerbos principal attributes
+            def attributes(principal, write_resource_accesses)
+              PrincipalAttributes.call(principal:, write_resource_accesses:)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/principals/read_resource_access.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module Principals
+      # Represents a read resource access record linking a principal to a role-based read permission.
+      #
+      # @example Checking if an access is complete
+      #   access = Yes::Auth::Principals::ReadResourceAccess.find(id)
+      #   access.authorization_complete?
+      class ReadResourceAccess < ActiveRecord::Base
+        self.table_name = 'auth_principals_read_resource_accesses'
+
+        belongs_to :role, class_name: 'Yes::Auth::Principals::Role', optional: true
+
+        # @return [Boolean] whether all required fields are present for authorization
+        def authorization_complete?
+          service.present? && scope.present? && resource_type.present? && role.present? && resource_id.present?
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/principals/role.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module Principals
+      # Represents an authorization role that can be assigned to users and resource accesses.
+      #
+      # @example Finding the super admin role
+      #   Yes::Auth::Principals::Role.super_admin_role
+      class Role < ActiveRecord::Base
+        self.table_name = 'auth_principals_roles'
+
+        SUPER_ADMIN_ROLE_NAME = 'admin'
+
+        has_and_belongs_to_many :users, class_name: 'Yes::Auth::Principals::User',
+                                        foreign_key: :auth_principals_role_id,
+                                        association_foreign_key: :auth_principals_user_id
+
+        has_many :read_resource_accesses, class_name: 'Yes::Auth::Principals::ReadResourceAccess'
+        has_many :write_resource_accesses, class_name: 'Yes::Auth::Principals::WriteResourceAccess'
+
+        scope :complete, -> { where.not(name: nil) }
+
+        # @return [String, nil] the role name with colons replaced by underscores
+        def resource_authorization_name
+          name&.tr(':', '_')
+        end
+
+        # @return [Yes::Auth::Principals::Role, nil] the super admin role
+        def self.super_admin_role
+          find_by(name: SUPER_ADMIN_ROLE_NAME)
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/principals/user.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module Principals
+      # Represents an authorization principal user with roles and resource accesses.
+      #
+      # @example Finding a user and checking roles
+      #   user = Yes::Auth::Principals::User.find_by(identity_id: 'some-uuid')
+      #   user.read_resource_access_authorization_roles
+      class User < ActiveRecord::Base
+        self.table_name = 'auth_principals_users'
+
+        NO_AUTHORIZATION_ROLES_YET = ['no-roles-yet'].freeze
+
+        has_and_belongs_to_many :roles, class_name: 'Yes::Auth::Principals::Role',
+                                        foreign_key: :auth_principals_user_id,
+                                        association_foreign_key: :auth_principals_role_id
+
+        has_many :write_resource_accesses, class_name: 'Yes::Auth::Principals::WriteResourceAccess',
+                                           foreign_key: :principal_id
+
+        has_many :read_resource_accesses, class_name: 'Yes::Auth::Principals::ReadResourceAccess',
+                                          foreign_key: :principal_id
+
+        # @return [Array<String>] role names for read resource access authorization
+        # NOTE: Runs 2 queries (resource access roles + direct roles). The direct roles
+        # query is shared with write_resource_access_authorization_roles but cannot be
+        # easily combined since they query different join tables. Use .includes(:roles)
+        # when loading the User to avoid N+1 on the direct roles association.
+        def read_resource_access_authorization_roles
+          read_role_names = Set.new(
+            Role.joins(:read_resource_accesses).where(read_resource_accesses: { principal_id: id }).complete.pluck(:name)
+          )
+
+          (read_role_names + complete_role_names).to_a
+        end
+
+        # @return [Array<String>] role names for write resource access authorization
+        # NOTE: Runs 2 queries (resource access roles + direct roles). The direct roles
+        # query is shared with read_resource_access_authorization_roles but cannot be
+        # easily combined since they query different join tables. Use .includes(:roles)
+        # when loading the User to avoid N+1 on the direct roles association.
+        def write_resource_access_authorization_roles
+          write_role_names = Set.new(
+            Role.joins(:write_resource_accesses).where(write_resource_accesses: { principal_id: id }).complete.pluck(:name)
+          )
+
+          (write_role_names + complete_role_names).to_a
+        end
+
+        # @return [Boolean] whether the user has the super admin role
+        def super_admin?
+          super_admin_role_id = Role.super_admin_role&.id
+          return false unless super_admin_role_id
+
+          roles.ids.include?(super_admin_role_id)
+        end
+
+        private
+
+        # @return [Array<String>] cached complete role names for the user
+        def complete_role_names
+          @complete_role_names ||= roles.complete.pluck(:name)
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/principals/write_resource_access.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module Principals
+      # Represents a write resource access record linking a principal to a role-based write permission.
+      #
+      # @example Checking if an access is complete
+      #   access = Yes::Auth::Principals::WriteResourceAccess.find(id)
+      #   access.authorization_complete?
+      class WriteResourceAccess < ActiveRecord::Base
+        self.table_name = 'auth_principals_write_resource_accesses'
+
+        belongs_to :role, class_name: 'Yes::Auth::Principals::Role', optional: true
+
+        # @return [Boolean] whether all required fields are present for authorization
+        def authorization_complete?
+          context.present? && resource_type.present? && role.present? && resource_id.present?
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    # Auto-configures yes-core's Cerbos principal data builders when yes-auth is loaded.
+    class Railtie < Rails::Railtie
+      initializer 'yes_auth.configure_cerbos' do
+        Yes::Core.configure do |config|
+          config.cerbos_principal_data_builder =
+            Yes::Auth::Cerbos::WriteResourceAccess::PrincipalData.method(:call)
+          config.cerbos_read_principal_data_builder =
+            Yes::Auth::Cerbos::ReadResourceAccess::PrincipalData.method(:call)
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/read_models/principals/read_resource_access/builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module ReadModels
+      module Principals
+        module ReadResourceAccess
+          # @see Yes::Core::ReadModel::Builder
+          class Builder < Yes::Core::ReadModel::Builder
+            private
+
+            def default_read_model_class
+              Yes::Auth::Principals::ReadResourceAccess
+            end
+
+            def aggregate_id_key
+              'read_resource_access_id'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/read_models/principals/read_resource_access/on_read_resource_access_principal_assigned.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module ReadModels
+      module Principals
+        module ReadResourceAccess
+          # @see Yes::Core::ReadModel::EventHandler
+          class OnReadResourceAccessPrincipalAssigned < Yes::Core::ReadModel::EventHandler
+            # @param event [Yes::Core::Event]
+            # @return [void]
+            def call(event)
+              read_model.update_columns(principal_id: event.data['principal_id'])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/read_models/principals/read_resource_access/on_read_resource_access_removed.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module ReadModels
+      module Principals
+        module ReadResourceAccess
+          # @see Yes::Core::ReadModel::EventHandler
+          class OnReadResourceAccessRemoved < Yes::Core::ReadModel::EventHandler
+            # @param event [Yes::Core::Event]
+            # @return [void]
+            def call(_event)
+              read_model.delete
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/read_models/principals/read_resource_access/on_read_resource_access_resource_assigned.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module ReadModels
+      module Principals
+        module ReadResourceAccess
+          # @see Yes::Core::ReadModel::EventHandler
+          class OnReadResourceAccessResourceAssigned < Yes::Core::ReadModel::EventHandler
+            # @param event [Yes::Core::Event]
+            # @return [void]
+            def call(event)
+              read_model.update_columns(resource_id: event.data['resource_id'])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/auth/read_models/principals/read_resource_access/on_read_resource_access_resource_type_changed.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yes
+  module Auth
+    module ReadModels
+      module Principals
+        module ReadResourceAccess
+          # @see Yes::Core::ReadModel::EventHandler
+          class OnReadResourceAccessResourceTypeChanged < Yes::Core::ReadModel::EventHandler
+            # @param event [Yes::Core::Event]
+            # @return [void]
+            def call(event)
+              read_model.update_columns(resource_type: event.data['resource_type'])
+            end
+          end
+        end
+      end
+    end
+  end
+end