account_authz 0.1.0

data/the_local/agents/account_authz-install.md

@@ -0,0 +1,80 @@
+---
+name: account_authz-install
+description: Use to hook account_authz into a project — adding the gem, installing its migrations, choosing the account membership model and including AccountAuthz::Member in it, including AccountAuthz::Authorization in controllers, setting AccountAuthz::Current.account_id per request, and mounting AccountAuthz::Engine for the members and role pages.
+tools: Bash, Read, Edit
+scope: authorization — capability catalog, roles, and Pundit enforcement in multi-tenant Rails apps
+---
+
+You follow the steps below exactly, in order, and invent none. Where a step says to ask the developer, ask and wait for the answer.
+
+## What account_authz is
+A Rails engine for capability-based authorization in multi-tenant apps, hooked in when a host needs account-scoped roles enforced through Pundit.
+
+## Interface
+- `gem "account_authz"` — adds the engine to the host's Gemfile, and brings in `rails`, `pundit` and `keystone_ui` as dependencies.
+- `bin/rails account_authz:install:migrations` — copies the engine's three migrations into the host's `db/migrate/`.
+- `AccountAuthz::Member` — a model concern included in the host model that holds roles, normally the record for a person inside one account, giving it role assignments.
+- `AccountAuthz::Authorization` — a controller concern that includes `Pundit::Authorization` and adds a `can?(capability)` helper to controllers and views.
+- `AccountAuthz::Current.account_id` — the per-request account that the `can?` helper scopes its answer to.
+- `mount AccountAuthz::Engine` — a line in the host's `config/routes.rb` that serves two sets of pages for the current account. The members page lists each member with their name, email and roles, gives or takes away roles ranked below the viewer's own, invites a person by name and email, lists the invitations still waiting with a button to send each again and one to cancel it, and removes a member from the account. The role pages list the account's roles, create a role, add a role from a default template, and change a role's name, rank or capabilities, limited to roles ranked below the viewer unless the viewer holds the top rank, ranks up to the viewer's own and capabilities the viewer holds. The members page links to the roles page for a viewer who holds the roles capability, and the roles page links back to the members page. All of them are built from keystone_ui components and shown inside the host's own layout.
+
+## How to use it
+1. Confirm the host runs Ruby 3.2 or later and Rails 7.1 or later.
+2. Ask the developer which source to install account_authz from.
+   - RubyGems: `gem "account_authz"`
+   - Git: `gem "account_authz", github: "DYB-Development/account_authz", branch: "main"`
+
+   Add the chosen line to `Gemfile`, then run `bundle install`. This updates `Gemfile.lock`.
+3. Run `bin/rails account_authz:install:migrations`. It copies three files into `db/migrate/`, named `<timestamp>_create_account_authz_roles.account_authz.rb`, `<timestamp>_create_account_authz_assignments.account_authz.rb` and `<timestamp>_add_rank_to_account_authz_roles.account_authz.rb`.
+   - `account_authz_roles` has `account_id` (bigint, required, indexed), `name` (string, required), `capabilities` (json, default empty array), and `rank` (integer, required, default 0).
+   - `account_authz_assignments` has a polymorphic `member` reference, a `role` reference, and a unique index on member and role together.
+   - Neither table has a foreign key to an accounts table, so the host needs no account model for the migrations to run.
+   - AccountAuthz stores no invitations of its own, so no table is copied for them.
+4. Open the three copied files. They declare `ActiveRecord::Migration[8.1]`. If the host runs a Rails version older than 8.1, change `[8.1]` in all three files to the host's Rails version, such as `[7.2]`.
+5. Run `bin/rails db:migrate`. This updates `db/schema.rb` or `db/structure.sql`.
+6. Choose the model that holds roles. A role belongs to one account, so the model to include `AccountAuthz::Member` in is the record for a person inside one account, such as `Membership`, not the person record, such as `User`.
+   - Look in `app/models/` for a model that joins a person to an account. If there is one, confirm with the developer that it is the record to use.
+   - If there is none, tell the developer that roles can be held by the person record instead, and ask whether to use it or to add a membership model first. With the person record, a check made from a controller, a view or a policy counts only the current account's roles, and a check made anywhere else must name the account or it counts the person's roles in every account.
+   - Add `include AccountAuthz::Member` to the chosen model's file in `app/models/`. Any Active Record model works, because the assignment is polymorphic. Destroying a member record destroys its role assignments, so with a membership model, a person's roles in an account go when their membership in it goes.
+7. Add `include AccountAuthz::Authorization` to `app/controllers/application_controller.rb`. If the controller already includes `Pundit::Authorization`, leave that line in place.
+8. `AccountAuthz::Authorization` calls `current_member` on the controller, and its `can?` helper returns `false` when that returns `nil`. Check whether `ApplicationController` already defines `current_member`. If it does not, ask the developer how the member record for the signed-in request is found, and define `current_member` in `ApplicationController` to return that record. With a membership model, that is the signed-in person's membership in the current account from step 10, so `current_member` must look it up after the current account is set.
+9. Pundit passes `pundit_user` to every policy, and `pundit_user` returns `current_user` unless the host overrides it. If the model from step 6 is not the model `current_user` returns, define `pundit_user` in `ApplicationController` to return `current_member`.
+10. Ask the developer how the current account is found for a request, such as from the subdomain, the signed-in user, or a URL parameter. Add a `before_action` to `ApplicationController` that sets `AccountAuthz::Current.account_id` to that account's integer id. Rails resets it at the end of every request.
+11. Ask the developer whether they want account_authz's pages. The one mount serves both the members page and the role pages, so the host gets both or neither. If they do not want them, skip this step and steps 12 and 13. If they do, ask which path to serve them under, offering `/account_authz`, and add `mount AccountAuthz::Engine => "/account_authz"` with that path to `config/routes.rb`. The members page is then at that path followed by `/members`, and the roles page at that path followed by `/roles`.
+    - The engine's controllers inherit the host's `ApplicationController`, so the sign-in, `current_member`, current account and CSRF protection from the host apply to every page and every form on them.
+    - The pages render inside the layout the host's `ApplicationController` uses, such as `app/views/layouts/application.html.erb`. Route helpers in that layout, such as `root_path`, reach the host's own routes on the pages without a `main_app.` prefix, so the layout needs no change for them.
+    - The pages are built from keystone_ui components and ship no stylesheet of their own, so that layout must load keystone_ui's styles. Check whether the host already loads them. If it does not and the host has a keystone_ui install local, hand that step to it. Otherwise ask the developer how the host loads keystone_ui's styles before continuing.
+    - A change a manager may not make sends them back to a page with a flash alert saying why, and the engine's pages do not show flash messages themselves. Check whether that layout renders `flash[:alert]`. If it does not, tell the developer that refused changes will return to the page with no message, and ask where in the layout to render the alert.
+    - The members page shows a `Roles` link only to a viewer who holds the roles capability in the current account, and the roles page shows a `Members` link to every viewer. A member who holds the roles capability but not the members capability gets a 403 response on the members page, so that member reaches the roles page only through a link straight to it. Ask the developer whether the host's navigation should link to the members page, the roles page, or both, and where to put each link.
+    - A request with no current account gets a 403 response on every page and every form.
+12. Check the members page against these facts, and tell the developer about any that the host does not meet.
+    - A member who does not hold the members capability in the current account gets a 403 response, whether they load the page, give or take a role, invite a person, send an invitation again, cancel one, or remove a member. The capability is `manage_members` unless the develop local changes it.
+    - Every member record the page lists must respond to `name` and `email` and include `AccountAuthz::Member`. If the model from step 6 lacks `name` or `email`, as a membership model often does, ask the developer how it should answer them, such as from the person record it belongs to, before continuing.
+    - Every waiting invitation the page lists must respond to `name` and `email`, and must be findable by its id among the current account's invitations. It needs no account_authz concern and no account_authz table.
+    - The engine sends no email and stores no invitation. Inviting a person, sending an invitation again, and cancelling one each call the host's own code, and accepting an invitation is the host's own flow.
+    - The invite form has a required `Name` field, a required `Email` field and an `Invite` button, and the engine does not validate either value, so the host's invite decides what to do with one it rejects.
+    - Giving or taking a role, removing a member, sending an invitation again and cancelling one find the record only among the current account's members, roles or invitations, so a record from another account raises a not-found error, which Rails answers with a 404 response outside development.
+    - A refused give, take or removal changes nothing and returns to the members page with a flash alert naming the reason, drawn from these four: `You can only give or take roles ranked below your own.`, `You can only change members ranked below you.`, `Someone else needs to be able to manage members first.` and `This member can't be removed from the account.`
+    - Sending an invitation again and cancelling one are not limited by rank, so every viewer who holds the members capability may do both to every waiting invitation.
+    - The account always keeps at least one member who holds the members capability, so a `Take <role>` or `Remove` button is left out when that member is the only way anyone in the current account holds it.
+    - Every role starts at rank 0, so until ranks are set, every viewer who holds a role reaches every member and every role. Tell the developer this, and that a role's rank is set on the role form.
+    - Removing a member takes away every role they hold in the current account and then calls the host's remove, both in one database transaction.
+    - The page does not know which records to list, which invitations are waiting, how to invite a person, how to send an invitation again, how to cancel one, which members cannot be removed, or how to remove one until the develop local configures that. Until then, a request from a member who holds the members capability raises an error on the page, on every button and on the invite form.
+13. Check the role pages against these facts, and tell the developer about any that the host does not meet.
+    - A member who does not hold the roles capability in the current account gets a 403 response on every role page and form. The capability is `manage_roles` unless the develop local changes it.
+    - The roles page lists each role in the current account by name with its number of capabilities, and each name links to that role's edit form. A `New role` link opens the form for a new role.
+    - The new and edit forms take a name, a rank as a number field with a minimum of 0, and a checkbox for each capability in the catalog, and saving returns to the roles page. Until the develop local declares the catalog, the forms show no checkboxes.
+    - The roles page shows an `Add <template>` button for each default template, which creates that role in the current account at rank 0. The section is left out until the develop local declares a default template.
+    - A refused create or save changes nothing and returns to the form or the roles page with a flash alert naming the reason, drawn from these four: `You can only change roles ranked below your own.`, `You can only set a rank up to your own.`, `You can only give a role capabilities you have yourself.` and `Someone else needs to be able to manage members first.`
+    - Editing a role finds it only among the current account's roles, so a role from another account raises a not-found error, which Rails answers with a 404 response outside development.
+    - Saving a role with a blank name raises a validation error, which Rails answers with a 422 response outside development.
+
+## Conventions
+- After step 5, confirm the schema file contains both `account_authz_roles` and `account_authz_assignments`, and that `account_authz_roles` has a `rank` column.
+- After step 10, confirm the host boots with `bin/rails runner 'puts AccountAuthz::Current.account_id.inspect'`, which prints `nil` outside a request.
+- After step 11, confirm `bin/rails routes` lists the mount and, under the routes for `AccountAuthz::Engine`, a `GET` route for `members`, a `DELETE` route for `members/:id`, a `POST` route for `members/:member_id/roles`, a `DELETE` route for `members/:member_id/roles/:id`, a `POST` route for `invitations`, a `POST` route for `invitations/:id/resend`, a `DELETE` route for `invitations/:id`, `GET` routes for `roles`, `roles/new` and `roles/:id/edit`, a `POST` route for `roles`, and `PATCH` and `PUT` routes for `roles/:id`.
+- After step 12, once the develop local has configured the members page, load it as a member who holds the members capability and confirm it shows the invite form and any waiting invitations inside the host's layout with keystone_ui's styles applied.
+- After step 13, load the roles page as a member who holds the roles capability and confirm it shows inside the host's layout with keystone_ui's styles applied.
+- After updating the account_authz gem, run `bin/rails account_authz:install:migrations` again, then `bin/rails db:migrate`. The task copies only migrations the host does not already have. A host that installed account_authz before ranks existed gets the rank migration this way, and every existing role gets rank 0.
+- Declaring capabilities, declaring templates, seeding roles for a new account, giving the first member the members or roles capability, writing policies, checking reach in host code, checking in host code whether a change would leave the account with no member who holds the members capability, configuring which members and which waiting invitations the members page lists, how it invites a person, sends an invitation again and cancels one, which members cannot be removed and how it removes one, configuring which capabilities open the pages, and rewording the refusal messages are out of scope for this local. Hand that work to the account_authz-develop local.
+- The members page and the role pages are the only screens account_authz adds. Deleting a role is not offered on them, and a screen for it belongs to the host. Sending an invitation and accepting one also belong to the host.

data/the_local/interface.yml

@@ -0,0 +1,71 @@
+scope: authorization — capability catalog, roles, and Pundit enforcement in multi-tenant Rails apps
+
+install:
+  - gem "account_authz"
+  - bin/rails account_authz:install:migrations
+  - AccountAuthz::Member
+  - AccountAuthz::Authorization
+  - AccountAuthz::Current.account_id
+  - mount AccountAuthz::Engine
+
+develop:
+  - AccountAuthz.catalog
+  - AccountAuthz.catalog.permissions
+  - AccountAuthz.catalog.metrics
+  - AccountAuthz.capabilities
+  - AccountAuthz.reset!
+  - AccountAuthz.can?
+  - AccountAuthz.approved_metrics
+  - AccountAuthz::Role.in_account
+  - AccountAuthz::Role.create!
+  - AccountAuthz::Role.from_template
+  - AccountAuthz.templates
+  - AccountAuthz.templates.find
+  - AccountAuthz.templates.defaults
+  - AccountAuthz.seed_default_roles
+  - member.assign_role
+  - member.revoke_role
+  - member.account_authz_roles
+  - member.capabilities
+  - member.can?
+  - member.approved_metrics
+  - AccountAuthz::ApplicationPolicy
+  - AccountAuthz.members_source
+  - AccountAuthz.members_capability
+  - AccountAuthz.roles_capability
+  - AccountAuthz::Reach
+  - reach.includes_member?
+  - reach.includes_role?
+  - reach.includes_capabilities?
+  - reach.includes_rank?
+  - AccountAuthz::LastManager
+  - account_authz.refusals
+  - last_manager.lost_by_taking?
+  - last_manager.lost_by_removing?
+  - last_manager.lost_by_changing?
+
+sources:
+  - lib/account_authz.rb
+  - lib/account_authz/catalog.rb
+  - lib/account_authz/templates.rb
+  - lib/account_authz/engine.rb
+  - config/routes.rb
+  - app/controllers/account_authz/members_controller.rb
+  - app/controllers/account_authz/invitations_controller.rb
+  - test/dummy/app/models/member_directory.rb
+  - app/controllers/account_authz/member_roles_controller.rb
+  - app/views/account_authz/members/index.html.erb
+  - app/controllers/account_authz/roles_controller.rb
+  - app/models/account_authz/reach.rb
+  - app/models/account_authz/last_manager.rb
+  - config/locales/en.yml
+  - app/views/account_authz/roles/index.html.erb
+  - app/views/account_authz/roles/_form.html.erb
+  - app/controllers/account_authz/application_controller.rb
+  - app/helpers/account_authz/app_routes_helper.rb
+  - lib/account_authz/reference/guide.md
+  - app/models/account_authz/role.rb
+  - app/models/account_authz/current.rb
+  - app/models/concerns/account_authz/member.rb
+  - app/controllers/concerns/account_authz/authorization.rb
+  - app/policies/account_authz/application_policy.rb

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: account_authz
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tylercschneider
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: pundit
+  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: keystone_ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: AccountAuthz is the authorization layer for multi-tenant apps. The app
+  declares a fixed catalog of capabilities (permission + metric keys) in code; accounts
+  manage roles as data that bundle those capabilities; AccountAuthz resolves what
+  a member may do (can?) and which metrics they may see (approved_metrics) from their
+  roles, and plugs into Pundit for enforcement.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/account_authz/application_controller.rb
+- app/controllers/account_authz/invitations_controller.rb
+- app/controllers/account_authz/member_roles_controller.rb
+- app/controllers/account_authz/members_controller.rb
+- app/controllers/account_authz/roles_controller.rb
+- app/controllers/concerns/account_authz/authorization.rb
+- app/helpers/account_authz/app_routes_helper.rb
+- app/helpers/account_authz/application_helper.rb
+- app/models/account_authz/account_id.rb
+- app/models/account_authz/acting_member.rb
+- app/models/account_authz/application_record.rb
+- app/models/account_authz/assignment.rb
+- app/models/account_authz/cancel_invitation.rb
+- app/models/account_authz/current.rb
+- app/models/account_authz/give_role.rb
+- app/models/account_authz/invite.rb
+- app/models/account_authz/last_manager.rb
+- app/models/account_authz/reach.rb
+- app/models/account_authz/remove_member.rb
+- app/models/account_authz/resend_invitation.rb
+- app/models/account_authz/result.rb
+- app/models/account_authz/role.rb
+- app/models/account_authz/take_role.rb
+- app/models/concerns/account_authz/member.rb
+- app/policies/account_authz/application_policy.rb
+- app/views/account_authz/invitations/new.html.erb
+- app/views/account_authz/members/_team.html.erb
+- app/views/account_authz/members/index.html.erb
+- app/views/account_authz/members/show.html.erb
+- app/views/account_authz/roles/_form.html.erb
+- app/views/account_authz/roles/edit.html.erb
+- app/views/account_authz/roles/index.html.erb
+- app/views/account_authz/roles/new.html.erb
+- config/locales/en.yml
+- config/routes.rb
+- db/migrate/20260607000001_create_citizen_roles.rb
+- db/migrate/20260607000002_create_citizen_assignments.rb
+- db/migrate/20260916000001_add_rank_to_citizen_roles.rb
+- db/migrate/20260921220000_rename_citizen_tables_to_account_authz.rb
+- lib/account_authz.rb
+- lib/account_authz/catalog.rb
+- lib/account_authz/engine.rb
+- lib/account_authz/reference.rb
+- lib/account_authz/reference/guide.md
+- lib/account_authz/templates.rb
+- lib/account_authz/version.rb
+- lib/tasks/account_authz_tasks.rake
+- the_local/agents/account_authz-develop.md
+- the_local/agents/account_authz-info.md
+- the_local/agents/account_authz-install.md
+- the_local/interface.yml
+homepage: https://github.com/DYB-Development/account_authz
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/DYB-Development/account_authz
+  source_code_uri: https://github.com/DYB-Development/account_authz
+  changelog_uri: https://github.com/DYB-Development/account_authz/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DYB-Development/account_authz/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Capability-based authorization: roles grant capabilities, Pundit enforces'
+test_files: []