seams 0.1.0 → 0.2.0

data/lib/generators/seams/admin/templates/README.md.tt

@@ -77,8 +77,10 @@ Seams::Admin.configure { |c| c.tenancy_scope = :platform }
 Seams::Admin.configure { |c| c.tenancy_scope = :tenant }
 ```
 
-- **Gate:** `Accounts::Membership#role == "admin"` (read off
-  `Accounts::Current.membership`).
+- **Gate:** `Seams::Permissions.can?(role:, ability:)` — each tenant
+  policy resolves its resource's ability code against the membership
+  role read off `Accounts::Current.membership` (no `role == "admin"`
+  literal). Platform `staff?` and the `system` role still bypass.
 - **Visibility:** only the current Account's data — every Pundit
   `Scope` filters by `account_id`.
 - **Use case:** a tenant-facing admin surface where each customer's
@@ -87,6 +89,34 @@ Seams::Admin.configure { |c| c.tenancy_scope = :tenant }
 - **Requires:** the `accounts` engine. Without it the admin engine
   fails fast at boot with a clear error message.
 
+Tenant mode needs two more settings in the same initializer. With only
+`tenancy_scope = :tenant`, a tenant admin who is not platform staff gets
+a 403 from the gate, and no membership is resolved for admin requests:
+
+1. **Authenticator.** The default gate is `current_identity&.staff?`,
+   which only lets platform staff in. Let signed-in identities through
+   and leave per-record decisions to the tenant policies.
+2. **Membership resolver.** The admin controllers do not inherit your
+   `ApplicationController`, so whatever sets `Accounts::Current.membership`
+   there does not run for admin requests. Resolve it here.
+
+```ruby
+# config/initializers/seams_admin.rb
+Seams::Admin.configure do |c|
+  c.tenancy_scope = :tenant
+  c.authenticator = ->(ctrl) { ctrl.current_identity.present? }
+  # Example: the identity's first active membership. Pick the account the
+  # way your app does (subdomain, session, a switcher).
+  c.current_membership_resolver = lambda do |ctrl|
+    identity = ctrl.current_identity
+    identity && Accounts::Membership.find_by(identity_id: identity.id, active: true)
+  end
+end
+```
+
+With both set, a member-role identity still gets 403 from the policies,
+and an admin sees only its own account's rows.
+
 Switching modes is a config flip — no schema change, no regenerate.
 The `policy_namespace` lookup on `Seams::Admin::ApplicationController`
 reads `Seams::Admin.config.tenancy_scope` on every request.
@@ -170,7 +200,7 @@ bin/rails generate administrate:dashboard MyHost::Project
 # Move app/dashboards/my_host/project_dashboard.rb to
 # engines/admin/app/dashboards/admin/project_dashboard.rb
 # Move the controller similarly under app/controllers/admin/.
-# Add `resources :projects, controller: "admin/projects"` to
+# Add `resources :projects, controller: "/admin/projects"` to
 # engines/admin/config/routes.rb (or splice via the
 # admin.routes.after_resources insertion point in a follow-up generator).
 ```

data/lib/generators/seams/admin/templates/app/controllers/admin/application_controller.rb.tt

@@ -41,7 +41,67 @@ module Seams
     # policy; a request that fails a policy never reaches the action;
     # the audit row only writes after a successful action.
     class ApplicationController < ::Administrate::ApplicationController
+      # Administrate's base controller does not inherit the host's
+      # ApplicationController, so it never picks up the auth engine's
+      # session lookup. Include it here, before the gate, so
+      # `current_identity` resolves and `Auth::Current.identity` is set
+      # for pundit_user and the audit actor.
+      include ::Auth::Authentication if defined?(::Auth::Authentication)
       include ::Seams::Admin::Authenticator
+
+      # The dashboard controllers are top-level `Admin::*`, outside the
+      # isolated Seams::Admin namespace, so Rails wires them to the host
+      # app's routes. Administrate's views call url_for against the
+      # current controller's routes, so give each subclass the engine's
+      # route set instead (the later include wins).
+      def self.inherited(subclass)
+        super
+        subclass.include(::Seams::Admin.railtie_routes_url_helpers)
+      end
+
+      # [route_key, action] pairs for this engine's dashboard routes.
+      def self.admin_routes
+        ::Seams::Admin::Engine.routes.routes.filter_map do |route|
+          controller = route.defaults[:controller]
+          next unless controller&.start_with?("admin/")
+
+          [controller.delete_prefix("admin/"), route.defaults[:action]]
+        end.to_set
+      end
+
+      # "Auth::Identity" => "identities", derived from each dashboard's
+      # declared model so follow-up dashboards are picked up too.
+      def self.admin_route_keys_by_model
+        admin_routes.map(&:first).uniq.each_with_object({}) do |key, map|
+          dashboard = "Admin::#{key.classify}Dashboard".safe_constantize
+          map[dashboard.model.name] = key if dashboard.respond_to?(:model)
+        end
+      end
+
+      # Accounts::Membership and Teams::Membership both have the route
+      # key `memberships` (isolated-engine model naming), so
+      # Administrate's polymorphic `[:admin, membership]` calls
+      # admin_membership(s)_path, which does not exist. These helpers
+      # route by the record's class, or by the current controller for a
+      # new record's form URL.
+      MEMBERSHIP_ROUTE_KEYS = {
+        "Accounts::Membership" => "accounts_membership",
+        "Teams::Membership"    => "teams_membership"
+      }.freeze
+
+      {
+        "admin_memberships"     => "admin_%ss",
+        "admin_membership"      => "admin_%s",
+        "new_admin_membership"  => "new_admin_%s",
+        "edit_admin_membership" => "edit_admin_%s"
+      }.each do |name, target|
+        %w[path url].each do |suffix|
+          define_method(:"#{name}_#{suffix}") do |*args, **opts|
+            public_send(:"#{format(target, membership_route_key(args.first))}_#{suffix}", *args, **opts)
+          end
+          helper_method :"#{name}_#{suffix}"
+        end
+      end
       # Administrate's canonical Pundit integration. Internally:
       #   - includes Pundit::Authorization
       #   - overrides `authorized_action?` to call
@@ -78,10 +138,12 @@ module Seams
       # `authorize` / `policy_scope`. Administrate's `Punditize`
       # already calls them on every standard action, so any future
       # custom action added to a subclass that forgets the call gets
-      # caught loudly in development. `:only` excludes `:index`
-      # (covered by `verify_policy_scoped` instead) and the rescue
-      # responders themselves (which never authorise — they 403).
-      after_action :verify_authorized,    except: %i[index respond_with_admin_unauthorised]
+      # caught loudly in development. `:except` skips `:index`, which
+      # is covered by `verify_policy_scoped` instead. The 403 rescue
+      # responder needs no exclusion: after_actions do not run when
+      # rescue_from handles the exception, and naming a non-action
+      # here raises ActionNotFound on Rails 7.1+.
+      after_action :verify_authorized,    except: :index
       after_action :verify_policy_scoped, only:   %i[index]
 
       # Helper exposed to dashboards so they can read the active
@@ -89,6 +151,7 @@ module Seams
       # policy scopes; dashboards may also branch on it for
       # account_id columns.
       helper_method :seams_admin_tenancy_scope
+      helper_method :seams_admin_navigation
 
       def seams_admin_tenancy_scope
         ::Seams::Admin.config.tenancy_scope
@@ -125,6 +188,13 @@ module Seams
       # at runtime per-request (rare; typically configured once at boot)
       # override this method on a subclass and consult their own request
       # state.
+      # Administrate's `create` never sets `@requested_resource`, and
+      # calling `requested_resource` there looks up `params[:id]` (nil).
+      # Keep the saved record for record_admin_audit.
+      def create
+        super { |resource| @created_resource = resource }
+      end
+
       def policy_namespace
         case ::Seams::Admin.config.tenancy_scope
         when :tenant   then [::Admin::Tenant]
@@ -134,6 +204,82 @@ module Seams
 
       private
 
+      # Pundit's array lookup cannot reach these policies on its own: it
+      # turns a Module namespace element into `Module`, and it keeps the
+      # record's namespace (`Admin::Platform::Auth::IdentityPolicy`).
+      # Each dashboard controller maps 1:1 to a policy instead
+      # (Admin::AccountsMembershipsController ->
+      # Admin::Platform::AccountsMembershipPolicy), so resolve the class
+      # explicitly and hand it to Pundit's own `policy_class:` options.
+      # That keeps verify_authorized / verify_policy_scoped working.
+      # Administrate's flash messages name the resource through a
+      # resolver that guesses the model from the controller path
+      # ("admin/plans" -> Plan). Use the dashboard's real model instead.
+      def translate_with_resource(key)
+        t("administrate.controller.#{key}", resource: resource_class.model_name.human)
+      end
+
+      def membership_route_key(record)
+        MEMBERSHIP_ROUTE_KEYS[record.class.name] || controller_name.singularize
+      end
+
+      def admin_policy_class
+        "#{policy_namespace.first}::#{controller_name.classify}Policy".constantize
+      end
+
+      def scoped_resource
+        policy_scope(resource_class.default_scoped, policy_scope_class: admin_policy_class::Scope)
+      end
+
+      def authorize_resource(resource)
+        authorize(resource, policy_class: admin_policy_class)
+      end
+
+      # Views ask about other resources too (navigation, association
+      # lists), so pick the policy for the resource being linked, not
+      # this controller's. Unknown resources are denied.
+      def authorized_action?(resource, action)
+        key    = admin_route_key_for(resource) || controller_name
+        policy = "#{policy_namespace.first}::#{key.classify}Policy".safe_constantize
+        return false if policy.nil?
+
+        policy.new(pundit_user, resource).public_send(:"#{action}?")
+      end
+
+      # Administrate decides which links to render with existing_action?,
+      # built from Rails.application.routes. A mounted engine's routes are
+      # not in that set, so every show/edit/new/destroy link and the
+      # navigation vanished. Read this engine's routes instead.
+      def existing_action?(resource, action_name)
+        key = admin_route_key_for(resource)
+        key.present? && self.class.admin_routes.include?([key, action_name.to_s])
+      end
+
+      # Route key ("accounts_memberships") for a record, a model class,
+      # or a name Administrate passes ("admin/accounts_membership",
+      # :identities).
+      def admin_route_key_for(resource)
+        case resource
+        when ::ActiveRecord::Base then self.class.admin_route_keys_by_model[resource.class.name]
+        when Class                then self.class.admin_route_keys_by_model[resource.name]
+        else resource.to_s.delete_prefix("admin/").pluralize.presence
+        end
+      end
+
+      # Sidebar entries for the navigation partial: every dashboard with
+      # an index route that the current user may list.
+      def seams_admin_navigation
+        self.class.admin_routes.select { |_key, action| action == "index" }.map(&:first).uniq.filter_map do |key|
+          dashboard = "Admin::#{key.classify}Dashboard".safe_constantize
+          next unless dashboard.respond_to?(:model) && authorized_action?(dashboard.model, :index)
+
+          { key: key,
+            label: dashboard.model.model_name.human(count: 2),
+            path: url_for(controller: "/admin/#{key}", action: :index),
+            active: key == controller_name }
+        end
+      end
+
       # Resolve the current Accounts::Membership for tenant-mode
       # policy decisions. Delegates to
       # `Seams::Admin.config.current_membership_resolver` (a callable
@@ -170,10 +316,10 @@ module Seams
       #     row from this controller would double-log. We detect the
       #     `audit_logs` association the concern installs and skip.
       #
-      # `requested_resource` is Administrate's resolved record. On
-      # `create` it's the just-saved record; on `update` it's the
-      # just-updated record; on `destroy` it's the record that was just
-      # destroyed (frozen but still readable for `id` / `class.name`).
+      # The audited record: on `create` the record our `create` override
+      # captured (Administrate never sets requested_resource there); on
+      # `update` the just-updated record; on `destroy` the record that was
+      # just destroyed (frozen but still readable for `id` / `class.name`).
       def record_admin_audit
         return unless defined?(::Core::AuditLog)
         return unless response.successful? || response.redirect?
@@ -215,6 +361,8 @@ module Seams
       # subclass that overrode `requested_resource` to raise) we don't
       # want the audit hook to take down the whole response.
       def requested_resource_for_audit
+        return @created_resource if action_name == "create"
+
         respond_to?(:requested_resource, true) ? requested_resource : nil
       rescue StandardError
         nil

data/lib/generators/seams/admin/templates/app/dashboards/admin/account_dashboard.rb.tt

@@ -11,6 +11,12 @@ require "administrate/base_dashboard"
 # secondary identifier and renders fine as Field::Number.
 module Admin
   class AccountDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (AccountDashboard -> Admin::Account), which does not exist.
+    def self.model
+      ::Accounts::Account
+    end
+
     ATTRIBUTE_TYPES = {
       # UUID PK — Field::String, not Field::Number.
       id:                  Field::String,
@@ -18,7 +24,9 @@ module Admin
       external_account_id: Field::Number,
       cancelled_at:        Field::DateTime,
       incinerated_at:      Field::DateTime,
-      memberships:         Field::HasMany,
+      memberships:         Admin::Fields::HasMany.with_options(
+        class_name: "Accounts::Membership", dashboard: "Admin::AccountsMembershipDashboard"
+      ),
       created_at:          Field::DateTime,
       updated_at:          Field::DateTime
     }.freeze

data/lib/generators/seams/admin/templates/app/dashboards/admin/accounts_membership_dashboard.rb.tt

@@ -17,10 +17,18 @@ require "administrate/base_dashboard"
 # the admin surface treats identity_id as a typed integer reference.
 module Admin
   class AccountsMembershipDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (AccountsMembershipDashboard -> Admin::AccountsMembership), which does not exist.
+    def self.model
+      ::Accounts::Membership
+    end
+
     ATTRIBUTE_TYPES = {
       # UUID PK — Field::String, not Field::Number.
       id:          Field::String,
-      account:     Field::BelongsTo.with_options(class_name: "Accounts::Account"),
+      account:     Admin::Fields::BelongsTo.with_options(
+        class_name: "Accounts::Account", dashboard: "Admin::AccountDashboard"
+      ),
       identity_id: Field::Number,
       name:        Field::String,
       role:        Field::Select.with_options(collection: %w[owner admin member system]),

data/lib/generators/seams/admin/templates/app/dashboards/admin/identity_dashboard.rb.tt

@@ -13,6 +13,12 @@ require "administrate/base_dashboard"
 # auth engine's reset flow, not through the admin surface.
 module Admin
   class IdentityDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (IdentityDashboard -> Admin::Identity), which does not exist.
+    def self.model
+      ::Auth::Identity
+    end
+
     # ATTRIBUTE_TYPES describes how Administrate renders each column.
     # Administrate auto-discovers attributes from the model; declaring
     # them explicitly here makes the rendering deterministic and lets

data/lib/generators/seams/admin/templates/app/dashboards/admin/invitation_dashboard.rb.tt

@@ -8,9 +8,15 @@ require "administrate/base_dashboard"
 # read the full token (they re-issue if lost).
 module Admin
   class InvitationDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (InvitationDashboard -> Admin::Invitation), which does not exist.
+    def self.model
+      ::Teams::Invitation
+    end
+
     ATTRIBUTE_TYPES = {
       id:          Field::Number,
-      team:        Field::BelongsTo.with_options(class_name: "Teams::Team"),
+      team:        Admin::Fields::BelongsTo.with_options(class_name: "Teams::Team", dashboard: "Admin::TeamDashboard"),
       email:       Field::String.with_options(searchable: true),
       # Truncated to 16 chars so the table view doesn't get blown up
       # by the 43-char base64 token. Full value still available on the

data/lib/generators/seams/admin/templates/app/dashboards/admin/invoice_dashboard.rb.tt

@@ -12,6 +12,12 @@ require "administrate/base_dashboard"
 # column on the same row.
 module Admin
   class InvoiceDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (InvoiceDashboard -> Admin::Invoice), which does not exist.
+    def self.model
+      ::Billing::Invoice
+    end
+
     ATTRIBUTE_TYPES = {
       id:               Field::Number,
       # UUID — Field::String, not Field::Number.

data/lib/generators/seams/admin/templates/app/dashboards/admin/lifetime_pass_dashboard.rb.tt

@@ -8,6 +8,12 @@ require "administrate/base_dashboard"
 # track the human (Auth::Identity bigint) who pressed the button.
 module Admin
   class LifetimePassDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (LifetimePassDashboard -> Admin::LifetimePass), which does not exist.
+    def self.model
+      ::Billing::LifetimePass
+    end
+
     ATTRIBUTE_TYPES = {
       id:                       Field::Number,
       # UUID — Field::String, not Field::Number.

data/lib/generators/seams/admin/templates/app/dashboards/admin/notification_dashboard.rb.tt

@@ -12,6 +12,12 @@ require "administrate/base_dashboard"
 # collection view and only shown on the show page.
 module Admin
   class NotificationDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (NotificationDashboard -> Admin::Notification), which does not exist.
+    def self.model
+      ::Notifications::Notification
+    end
+
     ATTRIBUTE_TYPES = {
       id:               Field::Number,
       type:             Field::String,

data/lib/generators/seams/admin/templates/app/dashboards/admin/notification_preference_dashboard.rb.tt

@@ -8,6 +8,12 @@ require "administrate/base_dashboard"
 # false` is an explicit opt-out.
 module Admin
   class NotificationPreferenceDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (NotificationPreferenceDashboard -> Admin::NotificationPreference), which does not exist.
+    def self.model
+      ::Notifications::NotificationPreference
+    end
+
     ATTRIBUTE_TYPES = {
       id:                Field::Number,
       identity_id:       Field::Number,

data/lib/generators/seams/admin/templates/app/dashboards/admin/plan_dashboard.rb.tt

@@ -12,6 +12,12 @@ require "administrate/base_dashboard"
 # `currency` from the same row and formats accordingly.
 module Admin
   class PlanDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (PlanDashboard -> Admin::Plan), which does not exist.
+    def self.model
+      ::Billing::Plan
+    end
+
     ATTRIBUTE_TYPES = {
       id:                  Field::Number,
       gateway_ref:         Field::String,

data/lib/generators/seams/admin/templates/app/dashboards/admin/subscription_dashboard.rb.tt

@@ -10,6 +10,12 @@ require "administrate/base_dashboard"
 # account_id as an opaque tenant reference rather than a belongs_to.
 module Admin
   class SubscriptionDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (SubscriptionDashboard -> Admin::Subscription), which does not exist.
+    def self.model
+      ::Billing::Subscription
+    end
+
     ATTRIBUTE_TYPES = {
       id:                 Field::Number,
       # UUID — Field::String, not Field::Number.

data/lib/generators/seams/admin/templates/app/dashboards/admin/team_dashboard.rb.tt

@@ -8,12 +8,22 @@ require "administrate/base_dashboard"
 # (Teams::Membership), not via Accounts::Membership.
 module Admin
   class TeamDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (TeamDashboard -> Admin::Team), which does not exist.
+    def self.model
+      ::Teams::Team
+    end
+
     ATTRIBUTE_TYPES = {
       id:          Field::Number,
       name:        Field::String,
       slug:        Field::String,
-      memberships: Field::HasMany.with_options(class_name: "Teams::Membership"),
-      invitations: Field::HasMany.with_options(class_name: "Teams::Invitation"),
+      memberships: Admin::Fields::HasMany.with_options(
+        class_name: "Teams::Membership", dashboard: "Admin::TeamsMembershipDashboard"
+      ),
+      invitations: Admin::Fields::HasMany.with_options(
+        class_name: "Teams::Invitation", dashboard: "Admin::InvitationDashboard"
+      ),
       created_at:  Field::DateTime,
       updated_at:  Field::DateTime
     }.freeze

data/lib/generators/seams/admin/templates/app/dashboards/admin/teams_membership_dashboard.rb.tt

@@ -14,9 +14,15 @@ require "administrate/base_dashboard"
 # treats it as a typed integer reference rather than a belongs_to.
 module Admin
   class TeamsMembershipDashboard < Administrate::BaseDashboard
+    # Administrate derives the model from the class name
+    # (TeamsMembershipDashboard -> Admin::TeamsMembership), which does not exist.
+    def self.model
+      ::Teams::Membership
+    end
+
     ATTRIBUTE_TYPES = {
       id:          Field::Number,
-      team:        Field::BelongsTo.with_options(class_name: "Teams::Team"),
+      team:        Admin::Fields::BelongsTo.with_options(class_name: "Teams::Team", dashboard: "Admin::TeamDashboard"),
       identity_id: Field::Number,
       role:        Field::Select.with_options(collection: %w[owner admin member]),
       created_at:  Field::DateTime,

data/lib/generators/seams/admin/templates/app/fields/admin/fields/belongs_to.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Admin
+  module Fields
+    # Administrate::Field::BelongsTo plus the `dashboard:` option (see
+    # Admin::Fields::DashboardOption). Renders with the stock
+    # fields/belongs_to partials.
+    class BelongsTo < ::Administrate::Field::BelongsTo
+      include DashboardOption
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/fields/admin/fields/dashboard_option.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Admin
+  module Fields
+    # Administrate finds an association's dashboard by appending
+    # "Dashboard" to the associated class name (Teams::Team ->
+    # Teams::TeamDashboard). This engine's dashboards live under Admin::,
+    # and defining constants inside another engine's namespace would
+    # break the engine boundary. The `dashboard:` option names the
+    # dashboard explicitly:
+    #
+    #   team: Admin::Fields::BelongsTo.with_options(
+    #     class_name: "Teams::Team", dashboard: "Admin::TeamDashboard"
+    #   )
+    module DashboardOption
+      def associated_dashboard
+        name = options[:dashboard]
+        name ? name.constantize.new : super
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/fields/admin/fields/has_many.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Admin
+  module Fields
+    # Administrate::Field::HasMany plus the `dashboard:` option (see
+    # Admin::Fields::DashboardOption). Renders with the stock
+    # fields/has_many partials.
+    class HasMany < ::Administrate::Field::HasMany
+      include DashboardOption
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/account_policy.rb.tt

@@ -21,6 +21,10 @@ module Admin
 
       private
 
+      def permission_ability
+        "account.manage.accounts"
+      end
+
       def record_in_tenant_scope?
         return true if user&.identity&.staff?
         return true if record.nil? || record.is_a?(Class)

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/accounts_membership_policy.rb.tt

@@ -19,6 +19,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "membership.manage.accounts"
+      end
     end
   end
 end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/application_policy.rb.tt

@@ -3,10 +3,24 @@
 module Admin
   module Tenant
     # Abstract base for every tenant-mode admin policy. Tenant mode
-    # gates on `Accounts::Membership.role` for the currently-resolved
-    # membership (`Seams::Admin::Context#membership`). Staff Identities
-    # always pass the gate too — a platform staff member can drop into
-    # any tenant's admin without rejoining as an account-admin.
+    # resolves access through `Seams::Permissions.can?` — the gem's
+    # single source of truth for authorisation — keyed by the
+    # currently-resolved membership's role
+    # (`Seams::Admin::Context#membership.role`) and the ability code
+    # the concrete policy owns (see `permission_ability`). There is
+    # deliberately no `role == "admin"` literal here: the
+    # owner/admin/member hierarchy and the grant map live in
+    # `Seams::Permissions::ROLE_HIERARCHY` and
+    # `Seams.configuration.permission_grants`, so the admin surface and
+    # the host controllers decide from the same map and never drift.
+    #
+    # Two bypass tiers remain explicit and intentional, mirroring
+    # `Accounts::Authorization#authorize_permission!`:
+    #   - Platform staff (`Auth::Identity#staff?`) always pass — a
+    #     platform staff member can drop into any tenant's admin without
+    #     rejoining as an account-admin.
+    #   - The `system` pseudo-role bypasses inside
+    #     `Seams::Permissions.can?` itself (trusted internal callers).
     #
     # The `Scope` inner class is overridden per-policy; this base
     # returns `scope.none` so a subclass that forgets to override gets
@@ -118,16 +132,43 @@ module Admin
 
       private
 
-      # Permitted when (a) the Identity is staff (platform admins drop
-      # into every tenant), or (b) the resolved Accounts::Membership
-      # carries an admin/owner role for the current Account.
+      # Permitted when (a) the Identity is platform staff (the bypass
+      # tier — platform admins drop into every tenant), or (b) the
+      # resolved Accounts::Membership's role holds this policy's ability
+      # in the gem's permission registry. Resolution is delegated to
+      # `Seams::Permissions.can?` so the owner/admin/member hierarchy
+      # and the host grant map are the only place access is decided.
       def permitted?
+        permitted_to?(permission_ability)
+      end
+
+      # Shared resolution path for every tenant policy: apply the staff
+      # bypass, then defer to `Seams::Permissions.can?` with the
+      # membership role and the given ability code. Concrete policies
+      # never re-implement the role logic — they only name their
+      # ability via `permission_ability`.
+      #
+      # Fail closed: a request with no resolved membership, or a policy
+      # that names no ability, is denied (only platform staff pass).
+      def permitted_to?(ability)
         return true if user&.identity&.staff?
+        return false if ability.nil?
+
+        role = user&.membership&.role
+        return false if role.nil?
 
-        membership = user&.membership
-        return false if membership.nil?
+        ::Seams::Permissions.can?(role: role.to_s, ability: ability)
+      end
 
-        %w[owner admin].include?(membership.role.to_s)
+      # The owning engine's ability code (resource.action.engine) this
+      # policy resolves through. Each concrete tenant policy overrides
+      # this to name its resource's `manage` ability — the code the
+      # owning engine registers at boot and that
+      # `Seams::Permissions::DEFAULT_GRANTS` grants to the admin tier.
+      # nil here fails closed (only platform staff pass), so a subclass
+      # that forgets to name its ability never silently grants access.
+      def permission_ability
+        nil
       end
 
       def account_id

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/identity_policy.rb.tt

@@ -48,6 +48,10 @@ module Admin
 
       private
 
+      def permission_ability
+        "identity.manage.auth"
+      end
+
       # Identity has no `account_id` column. Per-record tenant guard
       # checks instead that the Identity holds a membership in the
       # current Account.

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/invitation_policy.rb.tt

@@ -19,6 +19,12 @@ module Admin
           scope.where(account_id: account_id)
         end
       end
+
+      private
+
+      def permission_ability
+        "invitation.manage.teams"
+      end
     end
   end
 end