access_grant 1.0.0

data/lib/generators/access_grant/setup/templates/access_grant.rb.tt

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Boot wiring for AccessGrant. Every config.* option is listed below with
+# defaults and examples — see docs/architecture.md Configuration reference.
+
+AccessGrant.configure do |config|
+  # --- tenant_class (String or nil; default: nil = single-tenant) ---
+  # Host model that owns roles. When set, roles get a tenant FK and
+  # permitted? requires tenant:.
+<% if multi_tenant? -%>
+  config.tenant_class = "<%= tenant_class %>"
+  # Single-tenant: omit or set nil
+  # config.tenant_class = nil
+<% else -%>
+  # config.tenant_class = "Organization"
+  config.tenant_class = nil
+<% end -%>
+
+  # --- user_class (String; default: "User") ---
+  # Host model that receives roles and permitted?.
+  config.user_class = "<%= user_class %>"
+  # config.user_class = "Account"
+
+  # --- owner_role (Symbol: :protected | :bypass | :both | :none; default: :protected) ---
+  # How privileged the Owner role is.
+  config.owner_role = :<%= owner_role %>
+  # config.owner_role = :none   # no special Owner; grant_owner! raises
+
+  # --- owner_role_name (String; default: "Owner") ---
+  # Reserved role name for the privileged floor (case-insensitive).
+  config.owner_role_name = "Owner"
+  # config.owner_role_name = "Super Admin"
+
+  # --- tables (Hash; default: short names) ---
+  # Physical table names chosen by setup --tables=auto|simple|prefixed.
+  # If install migration still uses short names but these are prefixed,
+  # edit the install migration before db:migrate.
+  config.tables = {
+    roles: "<%= tables[:roles] %>",
+    permissions: "<%= tables[:permissions] %>",
+    role_permissions: "<%= tables[:role_permissions] %>",
+    user_roles: "<%= tables[:user_roles] %>"
+  }
+  # After collision / --tables=prefixed:
+  # config.tables = {
+  #   roles: "access_grant_roles",
+  #   permissions: "access_grant_permissions",
+  #   role_permissions: "access_grant_role_permissions",
+  #   user_roles: "access_grant_user_roles"
+  # }
+
+  # --- default_permission_actions (Array<String>) ---
+  # Actions emitted for each `resource :name` in the catalog DSL.
+  config.default_permission_actions = %w[index show create update destroy]
+  # config.default_permission_actions = %w[index show create update destroy search attach detach]
+
+  # --- current_user_method (Symbol; default: :current_user) ---
+  # Controller method used by access_grant_authorize! for the acting user.
+  config.current_user_method = :current_user
+  # config.current_user_method = :current_account
+
+  # --- current_tenant_method (Symbol; default: :current_tenant) ---
+  # Controller method for the tenant (multi-tenant). Host must define it.
+  # Unused when tenant_class is nil.
+  config.current_tenant_method = :current_tenant
+  # config.current_tenant_method = :current_organization
+
+  # --- on_tenant_created (Proc or nil; default: nil) ---
+  # Usually set in config/access_grant/roles.rb — seed default roles, not Owner.
+  # config.on_tenant_created = ->(tenant) { ... }
+
+  # --- recover_access (Proc or nil; default: built-in Recovery.grant_role!) ---
+  # Ops lockout recovery for rake access_grant:grant_role.
+  # config.recover_access = ->(role_name:, user_id:, tenant_id: nil) {
+  #   AccessGrant::Recovery.grant_role!(role_name:, user_id:, tenant_id:)
+  # }
+end
+
+# Load catalog + roles after boot config.
+Rails.root.glob("config/access_grant/**/*.rb").sort.each { |f| require f }

data/lib/generators/access_grant/setup/templates/create_access_grant_user_roles.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= @user_roles_table %>, id: false do |t|
+      t.bigint :user_id, null: false
+      t.bigint :role_id, null: false
+    end
+    # permitted? starts from user; unique prevents duplicate assignments
+    add_index :<%= @user_roles_table %>, %i[user_id role_id], unique: true
+    # last-Owner assignment_count / reverse: users for a role
+    add_index :<%= @user_roles_table %>, :role_id
+  end
+end

data/lib/generators/access_grant/setup/templates/permissions.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Permission catalog — code is the source of truth for keys.
+# Sync into the DB: bundle exec rake access_grant:sync_permissions
+
+AccessGrant.permissions do
+  resource :invoices do
+    action :couple, description: "Can couple invoices together"
+  end
+end

data/lib/generators/access_grant/setup/templates/roles.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Default roles seeded when a tenant is created (multi-tenant).
+# Edit this file freely — it is your app's starting point, not Owner assignment.
+# Owner stays host-owned: org.grant_owner!(user).
+#
+# Prerequisite: run `bundle exec rake access_grant:sync_permissions` so the
+# permission catalog exists in the DB before roles reference keys.
+
+AccessGrant.configure do |config|
+  config.on_tenant_created = ->(tenant) do
+    # Per-resource Viewer + Manager roles from synced Permission.category
+    # (e.g. resource :invoices → "Invoices Viewer", "Invoices Manager").
+    # Create-only: existing role names for this tenant are left alone.
+    AccessGrant::Role.ensure_resource_defaults_for!(tenant)
+
+    # Or define explicit names/keys yourself:
+    # AccessGrant::Role.ensure_defaults_for!(
+    #   tenant,
+    #   "Admin" => %w[invoices.index invoices.show invoices.update],
+    #   "Member" => %w[invoices.index invoices.show]
+    # )
+  end
+end
+
+# Single-tenant: there is no tenant create callback. From db/seeds.rb (after sync):
+#   AccessGrant::Role.ensure_resource_defaults_for!(nil)

data/lib/tasks/access_grant_tasks.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+namespace :access_grant do
+  # Sync {AccessGrant.catalog} into the permissions table. Never deletes keys.
+  # For :protected/:both, reattaches all keys to Owner roles.
+  # Run on every deploy after migrate.
+  desc "Upsert catalog permissions into the database (never deletes)"
+  task sync_permissions: :environment do
+    AccessGrant::Sync.call
+  end
+
+  # Ops recovery: ROLE=Owner USER_ID=1 TENANT_ID=42 rake access_grant:grant_role
+  # Uses config.recover_access when set, else AccessGrant::Recovery.grant_role!.
+  desc "Grant a named role to a user (ops lockout recovery). Env: ROLE, USER_ID, optional TENANT_ID"
+  task grant_role: :environment do
+    role_name = ENV.fetch("ROLE") { raise "ROLE is required" }
+    user_id = Integer(ENV.fetch("USER_ID") { raise "USER_ID is required" })
+    tenant_id = ENV["TENANT_ID"]&.then { |id| Integer(id) }
+
+    callable = AccessGrant.config.recover_access
+    if callable
+      callable.call(role_name: role_name, user_id: user_id, tenant_id: tenant_id)
+    else
+      AccessGrant::Recovery.grant_role!(role_name: role_name, user_id: user_id, tenant_id: tenant_id)
+    end
+  end
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: access_grant
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- SahSantoshh
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: |
+  AccessGrant gives Rails apps a role-based access control system where permissions
+  live in the database and can be reassigned to roles by tenant admins at runtime,
+  with no deploy required. Unlike Pundit/CanCanCan/Action Policy (which hardcode
+  permission logic in Ruby policy/ability classes) or Rolify (which manages role
+  assignment but has no concept of permissions), AccessGrant ships a code-defined
+  permission catalog synced into the database, dynamic per-tenant roles, and a
+  permitted?(key) check.
+email:
+- sahsantoshh@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".codegraph/.gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/architecture.md
+- docs/proposal.md
+- docs/superpowers/plans/2026-09-08-access-grant-v1.md
+- docs/superpowers/plans/2026-09-08-gem-release.md
+- docs/superpowers/specs/2026-09-05-owner-role-design.md
+- docs/superpowers/specs/2026-09-07-proposal-review.md
+- docs/superpowers/specs/2026-09-07-usage-scenarios.md
+- docs/superpowers/specs/2026-09-08-gem-release-design.md
+- lib/access_grant.rb
+- lib/access_grant/catalog.rb
+- lib/access_grant/catalog/dsl.rb
+- lib/access_grant/configuration.rb
+- lib/access_grant/controller_methods.rb
+- lib/access_grant/models/permission.rb
+- lib/access_grant/models/role.rb
+- lib/access_grant/models/role_permission.rb
+- lib/access_grant/owner.rb
+- lib/access_grant/permission_key.rb
+- lib/access_grant/railtie.rb
+- lib/access_grant/recovery.rb
+- lib/access_grant/sync.rb
+- lib/access_grant/tenant.rb
+- lib/access_grant/user.rb
+- lib/access_grant/version.rb
+- lib/generators/access_grant/install/install_generator.rb
+- lib/generators/access_grant/install/templates/create_access_grant_tables.rb.tt
+- lib/generators/access_grant/setup/setup_generator.rb
+- lib/generators/access_grant/setup/templates/access_grant.rb.tt
+- lib/generators/access_grant/setup/templates/create_access_grant_user_roles.rb.tt
+- lib/generators/access_grant/setup/templates/permissions.rb.tt
+- lib/generators/access_grant/setup/templates/roles.rb.tt
+- lib/tasks/access_grant_tasks.rake
+homepage: https://github.com/SahSantoshh/access_grant
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/SahSantoshh/access_grant
+  source_code_uri: https://github.com/SahSantoshh/access_grant
+  changelog_uri: https://github.com/SahSantoshh/access_grant/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Dynamic, database-backed, per-tenant role and permission management for Rails.
+test_files: []