access_grant 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 286d6345a4ae68c6b87490f90d069e25cd7ea54c74543814ddee2d408083e451
+  data.tar.gz: f00a934a2747d2a5182abca43d85cda476854e4bd68086b86076ad60ad9a0f68
+SHA512:
+  metadata.gz: 28ebe5a51b2ac76094c5fd207d9f720f8763f3bed803752b9a09ed9da0fa4527375c52c27eed75ad63fd877ca03f0d11e0e003b9d772118e3c3628cb009e58e0
+  data.tar.gz: 5e5c81eb84665e3b9da6dde01ebbcb83f9ed6ca24a78b4ec55410f22330c54feda960245d9ada5c6cdaea195c1d9d91ebdd969db7f354824380f0aecbb1a6910

data/.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,98 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "bin/**/*"
+    - "pkg/**/*"
+    - "tmp/**/*"
+    - "vendor/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+Metrics/MethodLength:
+  Max: 20
+  CountAsOne: ["array", "hash", "heredoc"]
+  Exclude:
+    - "lib/generators/**/*"
+
+Metrics/AbcSize:
+  Max: 25
+  Exclude:
+    - "lib/generators/**/*"
+
+Metrics/ClassLength:
+  Max: 200
+  Exclude:
+    - "lib/generators/**/*"
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Layout/LineLength:
+  Max: 120
+
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: Gemfile
+
+# Integration / generator specs intentionally use string describes and richer examples.
+RSpec/ExampleLength:
+  Max: 50
+
+RSpec/MultipleExpectations:
+  Max: 25
+
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/integration/**/*"
+    - "spec/generators/**/*"
+    - "spec/support/**/*"
+    - "spec/access_grant/user_spec.rb"
+    - "spec/access_grant/controller_methods_spec.rb"
+    - "spec/access_grant/railtie_spec.rb"
+    - "spec/access_grant/apply_configuration_spec.rb"
+    - "spec/access_grant/owner_spec.rb"
+
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - "spec/access_grant/models/**/*"
+
+RSpec/InstanceVariable:
+  Exclude:
+    - "spec/generators/**/*"
+    - "spec/access_grant/controller_methods_spec.rb"
+    - "spec/access_grant/owner_spec.rb"
+
+RSpec/ContextWording:
+  Prefixes:
+    - when
+    - with
+    - without
+    - and
+    - for
+    - if
+
+RSpec/VerifiedDoubles:
+  Exclude:
+    - "spec/access_grant/controller_methods_spec.rb"
+
+RSpec/MessageSpies:
+  EnforcedStyle: receive
+
+RSpec/StubbedMock:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.2.6

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-08
+
+### Added
+
+- **Configuration** — table names, tenant/user classes, owner role mode, controller
+  hooks (`current_user_method`, `current_tenant_method`), and recovery callback.
+- **Permission catalog DSL** — code-defined `AccessGrant.permissions` catalog with
+  `resource` / `action` blocks; synced to DB via `rake access_grant:sync_permissions`.
+- **Sync** — idempotent upsert of catalog permissions into the database (never deletes).
+- **`permitted?(key, tenant:)`** — runtime authorization check on user models.
+- **Owner role** — protected/bypass/both modes, last-owner guard, `grant_owner!` /
+  `revoke_owner!`.
+- **Recovery rake** — `access_grant:grant_role` for ops lockout recovery.
+- **Controller authorization** — `access_grant_authorize!` before-action hook
+  (raises `AccessGrant::NotAuthorizedError`).
+- **Generators** — `access_grant:install` (core tables) and `access_grant:setup`
+  (initializer, catalog, user_roles migration, model patches).
+- **Railtie** — loads rake tasks and `ActiveSupport.on_load` hooks for
+  `ActionController` and `ActiveRecord`.
+- Project scaffolding: gemspec, RSpec/RuboCop harness, CI, and design docs
+  (docs/proposal.md, docs/architecture.md).
+
+## [0.1.0] - 2026-09-05
+
+- Initial gem skeleton (pre-release, unpublished).

data/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing
+
+## Getting started
+
+```
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+```
+
+`bin/console` starts an IRB session with the gem loaded, for quick manual
+experiments.
+
+## Branching
+
+`main` is always releasable. Work happens on short-lived branches named by
+type:
+
+- `feature/<slug>` — new functionality
+- `fix/<slug>` — bug fixes
+- `docs/<slug>` — documentation-only changes
+- `chore/<slug>` — tooling, dependencies, CI, maintenance
+
+## Commit messages
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Common types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`.
+
+Examples:
+
+```
+feat: add permitted? memoization per instance
+fix: prevent duplicate role names within a tenant
+docs: document the migration sequencing guardrail
+```
+
+A breaking change is marked either with `!` after the type/scope
+(`feat!: rename acts_as_permissible to acts_as_grantable`) or a
+`BREAKING CHANGE:` footer explaining the impact.
+
+## Pull requests
+
+Every PR should:
+
+- Pass `bundle exec rspec` and `bundle exec rubocop` (enforced by CI).
+- Update `CHANGELOG.md` under `[Unreleased]` for any user-facing change.
+- Update `README.md` / `docs/` if behavior or the public API changed.
+
+The PR template checklist covers this — fill it in rather than deleting it.
+
+## Versioning & releases
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+### Cut a release
+
+1. Open a PR on `main` that:
+   - Bumps `AccessGrant::VERSION` in `lib/access_grant/version.rb`
+   - Moves `[Unreleased]` entries in `CHANGELOG.md` under
+     `## [X.Y.Z] - YYYY-MM-DD` and leaves a fresh empty `[Unreleased]`
+   - Uses commit message `chore: release vX.Y.Z`
+2. Merge the PR and wait for CI on `main` to pass.
+3. In GitHub Actions, run the **Release** workflow on `main` with input
+   `version` set to `X.Y.Z` (must match `AccessGrant::VERSION`).
+4. The workflow:
+   - Fails fast if the version or CHANGELOG heading does not match
+   - Publishes the gem to RubyGems.org via Trusted Publishing (OIDC)
+   - Creates git tag `vX.Y.Z` and a GitHub Release from the CHANGELOG section
+
+Do **not** run `bundle exec rake release` locally for production publishes;
+Actions owns tagging and `gem push`.
+
+### One-time RubyGems setup
+
+1. Create a RubyGems.org account and enable MFA.
+2. Configure a [Trusted Publisher](https://guides.rubygems.org/trusted-publishing/)
+   for gem `access_grant`:
+   - Repository owner: `SahSantoshh`
+   - Repository name: `access_grant`
+   - Workflow filename: `release.yml`
+   - Environment: leave blank (must match the workflow — no `environment:` key)
+3. For the first publish, use RubyGems’ pending trusted-publisher flow if the
+   gem name is not on the index yet.
+
+## Code style
+
+RuboCop must pass with no offenses (`bundle exec rubocop`). Match the
+conventions already established in the codebase rather than introducing new
+ones ad hoc; propose `.rubocop.yml` changes separately if a rule genuinely
+doesn't fit.

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"
+gem "rubocop", "~> 1.75"
+gem "rubocop-rspec", "~> 3.0"
+gem "sqlite3", ">= 1.4"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santosh Sah
+
+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,123 @@
+# AccessGrant
+
+[![Gem Version](https://badge.fury.io/rb/access_grant.svg)](https://rubygems.org/gems/access_grant)
+[![CI](https://github.com/SahSantoshh/access_grant/actions/workflows/ci.yml/badge.svg)](https://github.com/SahSantoshh/access_grant/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+Dynamic, database-backed, per-tenant role and permission management for
+Rails — the "roles and permissions live in the database, admins edit them at
+runtime" pattern, without a canonical Rails equivalent until now.
+
+> **Status:** v1.0 published on [RubyGems](https://rubygems.org/gems/access_grant).
+> Design: [`docs/architecture.md`](docs/architecture.md),
+> [`docs/proposal.md`](docs/proposal.md).
+
+## The problem
+
+Every mainstream Rails authorization gem hardcodes "who can do what" in Ruby
+code — a policy class, an `Ability` class. Changing a permission means a
+developer opening a pull request and deploying. AccessGrant instead keeps
+the permission *catalog* in code (so a new capability always requires a code
+change to exist) but keeps the *role → permission mapping* in the database,
+fully editable by tenant admins at runtime.
+
+## How it compares
+
+| Gem | Roles as data | Permission catalog | Runtime-editable | Per-tenant scoping |
+|---|---|---|---|---|
+| Pundit | No | No | No | App-defined |
+| CanCanCan | No | No | No | App-defined |
+| Action Policy | No | No | No | App-defined |
+| Rolify | Yes | **No** — no permission concept at all | N/A | Partial |
+| **AccessGrant** | Yes | **Yes** | **Yes** | **Yes** |
+
+Built **from scratch** (not on Pundit or Rolify). See [`docs/proposal.md`](docs/proposal.md).
+
+## Installation
+
+```ruby
+# Gemfile
+gem "access_grant"
+```
+
+```
+bundle install
+rails g access_grant:install
+rails g access_grant:setup \
+  --multi-tenant \
+  --tenant=Organization \
+  --user=User \
+  --owner-role=protected \
+  --tables=auto
+rails db:migrate
+bundle exec rake access_grant:sync_permissions
+```
+
+`setup` patches models with `access_grant :tenant` / `access_grant :user`
+and writes `config/initializers/access_grant.rb` plus
+`config/access_grant/{permissions,roles}.rb`.
+
+**On every deploy:** run `bundle exec rake access_grant:sync_permissions`
+after migrate. Catalog sync is **not** a migration.
+
+## Usage
+
+```ruby
+class Organization < ApplicationRecord
+  access_grant :tenant
+end
+
+class User < ApplicationRecord
+  access_grant :user
+end
+
+# config/access_grant/permissions.rb
+AccessGrant.permissions do
+  resource :invoices do
+    action :couple, description: "Can couple invoices together"
+  end
+end
+
+org.grant_owner!(current_user)
+current_user.permitted?("invoices.index", tenant: org) # => true / false
+```
+
+```ruby
+# ApplicationController
+access_grant_authorize!  # uses current_user + current_tenant
+# host defines: def current_tenant; …; end
+
+# Skip public auth endpoints (Devise sessions/registrations/passwords, etc.)
+skip_access_grant_authorize! if: :devise_controller?
+
+# Raises AccessGrant::NotAuthorizedError — rescue in the host, e.g.:
+# rescue_from AccessGrant::NotAuthorizedError, with: -> { head :forbidden }
+```
+
+Keys are strictly `resource.action`. Permission descriptions come from the
+catalog (dev/sync only); role descriptions are admin-editable.
+
+See [`docs/architecture.md`](docs/architecture.md) for models, Owner,
+[configuration reference](docs/architecture.md#configuration-reference)
+(every `config.*` option with examples), overrides, and the full decision
+table. Acceptance scenarios:
+[`docs/superpowers/specs/2026-09-07-usage-scenarios.md`](docs/superpowers/specs/2026-09-07-usage-scenarios.md).
+
+## Development
+
+```
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+```
+
+Public APIs use **YARD** comments (`@param`, `@return`, `@raise`, `@example`) —
+the usual Ruby documentation style (YARD extends RDoc). IDEs show them on
+hover; optionally generate HTML with `yard doc` if the `yard` gem is installed.
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for branching, commit, and release
+conventions.
+
+## License
+
+MIT — see [`LICENSE.txt`](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]