account_authz 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1e9672c8fabc32992a01109eb826f621b631115b131911a9004d0468c1ed969
+  data.tar.gz: b1d4e2cc0be088d2cc0bcfbd2dcdb6b71feadce5bff36113aa3732142620ed9f
+SHA512:
+  metadata.gz: 2706e214202cdc4e4a2fedcfad8a55b18cdb54b4f3e3fa3c583da7b7550337bdfe2a8d8a62b0e5323ed94e84c77c01e12b0bbbbfa3a07f19e6bfb55baf2b1b75
+  data.tar.gz: c5769acd763ab5ab17be67746eb184b61f239360ab717c109384b8bd49151c442aa61f2e0b521076b8161188ed732ca87cd439569cb0970d34c78df1f76dabe9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 tylercschneider
+
+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,45 @@
+# AccountAuthz
+
+Capability-based authorization for multi-tenant apps. **Capabilities are code;
+roles are data.**
+
+- The app declares a fixed **catalog** of capabilities (permission + metric keys)
+  in code — what the software *can* do.
+- Accounts manage **roles** (data) that bundle those capabilities.
+- AccountAuthz resolves what a member may do (`can?`) and which metrics they may see
+  (`approved_metrics`) from the roles they hold, and plugs into **Pundit** for
+  enforcement.
+
+AccountAuthz owns **no role storage** — hosts bring their own (rolify, Jumpstart
+`AccountUser` roles, …) via an injectable resolver. It stays a thin, reusable
+layer over Pundit + your existing roles.
+
+## Why not just Pundit?
+
+Pundit enforces a decision but has no capability *catalog*, no role *records*,
+and no "which metrics may this member see" *list*. AccountAuthz adds exactly those —
+the parts you'd otherwise hand-roll in every app — and nothing else.
+
+## Usage (sketch)
+
+```ruby
+AccountAuthz.catalog do
+  permission :view_fulfillment
+  metric :revenue
+  metric :deals
+end
+
+# roles -> capabilities comes from the host (data); AccountAuthz resolves:
+AccountAuthz.can?(grants, :view_fulfillment)   # => true/false
+AccountAuthz.approved_metrics(grants)          # => [:revenue, :deals]
+```
+
+## Installation
+
+```ruby
+gem "account_authz"
+```
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+task test: "app:test"
+task default: :test
+
+require "the_local/rake"

data/app/controllers/account_authz/application_controller.rb

@@ -0,0 +1,19 @@
+module AccountAuthz
+  class ApplicationController < ::ApplicationController
+    include AccountAuthz::Authorization
+
+    helper KeystoneUiHelper, AccountAuthz::Engine.routes.url_helpers, AccountAuthz::AppRoutesHelper
+
+    before_action { AccountAuthz::AppRoutesHelper.define_app_route_helpers }
+
+    def self.requires_capability(&capability)
+      before_action { head :forbidden unless can?(capability.call) }
+    end
+
+    private
+
+    def refuse(reason, back_to:)
+      redirect_to back_to, alert: t("account_authz.refusals.#{reason}")
+    end
+  end
+end

data/app/controllers/account_authz/invitations_controller.rb

@@ -0,0 +1,30 @@
+module AccountAuthz
+  class InvitationsController < ApplicationController
+    requires_capability { AccountAuthz.members_capability }
+
+    def new
+    end
+
+    def create
+      run Invite, name: params.require(:invitation)[:name], email: params.require(:invitation)[:email]
+    end
+
+    def resend
+      run ResendInvitation, invitation_id: params[:id]
+    end
+
+    def destroy
+      run CancelInvitation, invitation_id: params[:id]
+    end
+
+    private
+
+    def run(action, **values)
+      result = action.new(person: current_member, account: Current.account_id, values: values).call
+
+      return redirect_to(members_path, alert: result.message) unless result.ok?
+
+      redirect_to members_path
+    end
+  end
+end

data/app/controllers/account_authz/member_roles_controller.rb

@@ -0,0 +1,27 @@
+module AccountAuthz
+  class MemberRolesController < ApplicationController
+    requires_capability { AccountAuthz.members_capability }
+
+    def create
+      run GiveRole
+    end
+
+    def destroy
+      run TakeRole
+    end
+
+    private
+
+    def run(action)
+      result = action.new(person: current_member, account: Current.account_id, values: submitted_values).call
+
+      return redirect_to(members_path, alert: result.message) unless result.ok?
+
+      redirect_to members_path
+    end
+
+    def submitted_values
+      { member_id: params[:member_id], role_id: params[:role_id] || params[:id] }
+    end
+  end
+end

data/app/controllers/account_authz/members_controller.rb

@@ -0,0 +1,38 @@
+module AccountAuthz
+  class MembersController < ApplicationController
+    requires_capability { AccountAuthz.members_capability }
+
+    def index
+      @members = AccountAuthz.members_source.members(Current.account_id)
+      @held_roles = held_roles
+      @invitations = AccountAuthz.members_source.invitations(Current.account_id)
+    end
+
+    def show
+      @member = AccountAuthz.members_source.members(Current.account_id).find(params[:id])
+      @held = Assignment.where(member: @member, role: Role.in_account(Current.account_id)).includes(:role).map(&:role)
+      @reach = reach
+      @last_manager = LastManager.new(account_id: Current.account_id)
+      @roles = Role.in_account(Current.account_id).select { |role| reach.includes_role?(role) }
+    end
+
+    def destroy
+      result = RemoveMember.new(person: current_member, account: Current.account_id, values: { member_id: params[:id] }).call
+
+      return redirect_to(members_path, alert: result.message) unless result.ok?
+
+      redirect_to members_path
+    end
+
+    private
+
+    def held_roles
+      Assignment.where(member: @members.to_a, role: Role.in_account(Current.account_id)).includes(:role)
+        .group_by(&:member_id).transform_values { |assignments| assignments.map(&:role) }
+    end
+
+    def reach
+      @reach ||= Reach.new(current_member, account_id: Current.account_id)
+    end
+  end
+end

data/app/controllers/account_authz/roles_controller.rb

@@ -0,0 +1,56 @@
+module AccountAuthz
+  class RolesController < ApplicationController
+    requires_capability { AccountAuthz.roles_capability }
+
+    def index
+      @roles = Role.in_account(Current.account_id)
+    end
+
+    def new
+      @role = Role.new(account_id: Current.account_id)
+    end
+
+    def create
+      if params[:template].present?
+        return refuse(:capabilities_out_of_reach, back_to: roles_path) unless reach.includes_capabilities?(AccountAuthz.templates.find(params[:template].to_sym).capabilities)
+
+        Role.from_template(account_id: Current.account_id, template: params[:template].to_sym)
+      else
+        return refuse(:rank_out_of_reach, back_to: new_role_path) if role_params.key?(:rank) && !reach.includes_rank?(role_params[:rank])
+        return refuse(:capabilities_out_of_reach, back_to: new_role_path) unless reach.includes_capabilities?(role_params[:capabilities])
+
+        Role.create!(account_id: Current.account_id, **role_params)
+      end
+
+      redirect_to roles_path
+    end
+
+    def edit
+      @role = Role.in_account(Current.account_id).find(params[:id])
+    end
+
+    def update
+      role = Role.in_account(Current.account_id).find(params[:id])
+      return refuse(:role_edit_out_of_reach, back_to: roles_path) unless reach.includes_role?(role)
+      return refuse(:rank_out_of_reach, back_to: edit_role_path(role)) if role_params.key?(:rank) && !reach.includes_rank?(role_params[:rank])
+      return refuse(:capabilities_out_of_reach, back_to: edit_role_path(role)) unless reach.includes_capabilities?(Array(role_params[:capabilities]) - role.capabilities)
+      return refuse(:last_manager, back_to: edit_role_path(role)) if role_params.key?(:capabilities) && LastManager.new(account_id: Current.account_id).lost_by_changing?(role, role_params[:capabilities])
+
+      role.update!(**role_params)
+
+      redirect_to roles_path
+    end
+
+    private
+
+    def reach
+      @reach ||= Reach.new(current_member, account_id: Current.account_id)
+    end
+
+    def role_params
+      permitted = params.require(:role).permit(:name, :rank, capabilities: []).to_h.symbolize_keys
+      permitted[:capabilities] = permitted[:capabilities].compact_blank if permitted.key?(:capabilities)
+      permitted
+    end
+  end
+end

data/app/controllers/concerns/account_authz/authorization.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "pundit"
+
+module AccountAuthz
+  module Authorization
+    extend ActiveSupport::Concern
+
+    included do
+      include Pundit::Authorization
+      helper_method :can?
+    end
+
+    def can?(capability)
+      Current.account_id.present? && current_member&.can?(capability, account_id: Current.account_id) || false
+    end
+  end
+end

data/app/helpers/account_authz/app_routes_helper.rb

@@ -0,0 +1,12 @@
+module AccountAuthz
+  module AppRoutesHelper
+    def self.define_app_route_helpers
+      @app_route_helpers_defined ||= begin
+        (Rails.application.routes.named_routes.helper_names - AccountAuthz::Engine.routes.named_routes.helper_names).each do |name|
+          define_method(name) { |*args, **options| main_app.public_send(name, *args, **options) }
+        end
+        true
+      end
+    end
+  end
+end

data/app/helpers/account_authz/application_helper.rb

@@ -0,0 +1,4 @@
+module AccountAuthz
+  module ApplicationHelper
+  end
+end

data/app/models/account_authz/account_id.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  module AccountId
+    def self.from(account)
+      account.respond_to?(:id) ? account.id : account
+    end
+  end
+end

data/app/models/account_authz/acting_member.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  module ActingMember
+    def self.for(person:, account:, source: AccountAuthz.members_source)
+      return person unless source.respond_to?(:member_for)
+
+      source.member_for(account_id: AccountId.from(account), person: person) || person
+    end
+  end
+end

data/app/models/account_authz/application_record.rb

@@ -0,0 +1,5 @@
+module AccountAuthz
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/account_authz/assignment.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class Assignment < ApplicationRecord
+    belongs_to :member, polymorphic: true
+    belongs_to :role, class_name: "AccountAuthz::Role"
+  end
+end

data/app/models/account_authz/cancel_invitation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class CancelInvitation
+    def initialize(person:, account:, values:)
+      @person = person
+      @account = AccountId.from(account)
+      @values = values
+    end
+
+    def call
+      AccountAuthz.members_source.cancel_invitation(invitation)
+
+      Result.ok
+    end
+
+    private
+
+    def invitation
+      AccountAuthz.members_source.invitations(@account).find(@values[:invitation_id])
+    end
+  end
+end

data/app/models/account_authz/current.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :account_id
+  end
+end

data/app/models/account_authz/give_role.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class GiveRole
+    def initialize(person:, account:, values:)
+      @person = person
+      @account = AccountId.from(account)
+      @values = values
+    end
+
+    def call
+      return Result.refused(:member_out_of_reach) unless reach.includes_member?(member)
+      return Result.refused(:role_out_of_reach) unless reach.includes_role?(role)
+
+      member.assign_role(role)
+
+      Result.ok
+    end
+
+    private
+
+    def reach
+      @reach ||= Reach.new(ActingMember.for(person: @person, account: @account), account_id: @account)
+    end
+
+    def member
+      @member ||= AccountAuthz.members_source.members(@account).find(@values[:member_id])
+    end
+
+    def role
+      @role ||= Role.in_account(@account).find(@values[:role_id])
+    end
+  end
+end

data/app/models/account_authz/invite.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class Invite
+    def initialize(person:, account:, values:)
+      @person = person
+      @account = AccountId.from(account)
+      @values = values
+    end
+
+    def call
+      AccountAuthz.members_source.invite(account_id: @account, invited_by: @person, name: @values[:name], email: @values[:email])
+
+      Result.ok
+    end
+  end
+end

data/app/models/account_authz/last_manager.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class LastManager
+    def initialize(account_id:)
+      @account_id = account_id
+    end
+
+    def lost_by_taking?(member, role)
+      managing_assignments.none? { |assignment| !holds?(assignment, member, role) }
+    end
+
+    def lost_by_removing?(member)
+      managing_assignments.none? { |assignment| !held_by?(assignment, member) }
+    end
+
+    def lost_by_changing?(role, capabilities)
+      managing_role_ids.include?(role.id) && !grants_members_capability?(capabilities) && managing_assignments.none? { |assignment| assignment.role_id != role.id }
+    end
+
+    private
+
+    def managing_assignments
+      @managing_assignments ||= Assignment.where(role_id: managing_role_ids).to_a
+    end
+
+    def holds?(assignment, member, role)
+      held_by?(assignment, member) && assignment.role_id == role.id
+    end
+
+    def held_by?(assignment, member)
+      assignment.member_id == member.id && assignment.member_type == member.class.polymorphic_name
+    end
+
+    def managing_role_ids
+      @managing_role_ids ||= Role.in_account(@account_id).select { |role| grants_members_capability?(role.capabilities) }.map(&:id)
+    end
+
+    def grants_members_capability?(capabilities)
+      AccountAuthz.can?(Array(capabilities).map(&:to_sym), AccountAuthz.members_capability)
+    end
+  end
+end

data/app/models/account_authz/reach.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class Reach
+    def initialize(manager, account_id:)
+      @manager = manager
+      @account_id = account_id
+    end
+
+    def includes_member?(member)
+      includes_roles?(member.account_authz_roles.in_account(@account_id))
+    end
+
+    def includes_roles?(roles)
+      top_rank? || (roles.map(&:rank).max || -Float::INFINITY) < own_rank
+    end
+
+    def includes_role?(role)
+      top_rank? || role.rank < own_rank
+    end
+
+    def includes_capabilities?(capabilities)
+      (Array(capabilities).map(&:to_sym) - @manager.capabilities(account_id: @account_id)).empty?
+    end
+
+    def includes_rank?(rank)
+      rank.to_i <= own_rank
+    end
+
+    private
+
+    def top_rank?
+      return @top_rank unless @top_rank.nil?
+
+      @top_rank = own_rank.finite? && own_rank >= Role.in_account(@account_id).maximum(:rank)
+    end
+
+    def own_rank
+      @own_rank ||= highest_rank(@manager)
+    end
+
+    def highest_rank(member)
+      member.account_authz_roles.in_account(@account_id).maximum(:rank) || -Float::INFINITY
+    end
+  end
+end

data/app/models/account_authz/remove_member.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class RemoveMember
+    def initialize(person:, account:, values:)
+      @person = person
+      @account = AccountId.from(account)
+      @values = values
+    end
+
+    def call
+      return Result.refused(:member_out_of_reach) unless reach.includes_member?(member)
+      return Result.refused(:not_removable) unless AccountAuthz.members_source.removable?(member)
+      return Result.refused(:last_manager) if LastManager.new(account_id: @account).lost_by_removing?(member)
+
+      ApplicationRecord.transaction do
+        member.account_authz_roles.in_account(@account).each { |role| member.revoke_role(role) }
+        AccountAuthz.members_source.remove(member)
+      end
+
+      Result.ok
+    end
+
+    private
+
+    def reach
+      @reach ||= Reach.new(ActingMember.for(person: @person, account: @account), account_id: @account)
+    end
+
+    def member
+      @member ||= AccountAuthz.members_source.members(@account).find(@values[:member_id])
+    end
+  end
+end

data/app/models/account_authz/resend_invitation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class ResendInvitation
+    def initialize(person:, account:, values:)
+      @person = person
+      @account = AccountId.from(account)
+      @values = values
+    end
+
+    def call
+      AccountAuthz.members_source.resend_invitation(invitation)
+
+      Result.ok
+    end
+
+    private
+
+    def invitation
+      AccountAuthz.members_source.invitations(@account).find(@values[:invitation_id])
+    end
+  end
+end

data/app/models/account_authz/result.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class Result
+    attr_reader :message
+
+    def self.ok
+      new(ok: true)
+    end
+
+    def self.refused(reason)
+      new(ok: false, message: I18n.t("account_authz.refusals.#{reason}"))
+    end
+
+    def initialize(ok:, message: nil)
+      @ok = ok
+      @message = message
+    end
+
+    def ok?
+      @ok
+    end
+  end
+end

data/app/models/account_authz/role.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class Role < ApplicationRecord
+    validates :name, presence: true
+    validate :capabilities_within_catalog
+
+    scope :in_account, ->(account_id) { where(account_id: account_id) }
+
+    def self.from_template(account_id:, template:)
+      definition = AccountAuthz.templates.find(template)
+      create!(account_id: account_id, name: definition.role_name, capabilities: definition.capabilities)
+    end
+
+    private
+
+    def capabilities_within_catalog
+      known = AccountAuthz.capabilities.map(&:to_s)
+      (Array(capabilities).map(&:to_s) - known).each do |unknown|
+        errors.add(:capabilities, "includes unknown capability: #{unknown}")
+      end
+    end
+  end
+end

data/app/models/account_authz/take_role.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class TakeRole
+    def initialize(person:, account:, values:)
+      @person = person
+      @account = AccountId.from(account)
+      @values = values
+    end
+
+    def call
+      return Result.refused(:member_out_of_reach) unless reach.includes_member?(member)
+      return Result.refused(:role_out_of_reach) unless reach.includes_role?(role)
+      return Result.refused(:last_manager) if LastManager.new(account_id: @account).lost_by_taking?(member, role)
+
+      member.revoke_role(role)
+
+      Result.ok
+    end
+
+    private
+
+    def reach
+      @reach ||= Reach.new(ActingMember.for(person: @person, account: @account), account_id: @account)
+    end
+
+    def member
+      @member ||= AccountAuthz.members_source.members(@account).find(@values[:member_id])
+    end
+
+    def role
+      @role ||= Role.in_account(@account).find(@values[:role_id])
+    end
+  end
+end