docs: define enterprise account and org management model

Author: brianfunk

README.md

@@ -19,6 +19,7 @@ OpenComments is currently transitioning from a hackathon prototype to a producti
 - Delivery tracking: [`docs/plan/README.md`](docs/plan/README.md)
 - Milestones: [`docs/plan`](docs/plan)
 - Current focus: schema reconciliation, RBAC/multi-tenancy hardening, agency workflow completion, quality gates
+- RBAC and account model: [`docs/RBAC_ACCOUNT_ORG_MANAGEMENT.md`](docs/RBAC_ACCOUNT_ORG_MANAGEMENT.md)
 
 ## 🏛️ Project Purpose
 
@@ -125,6 +126,7 @@ Before deploying, ensure quality gates pass:
 - **[DATAMODEL.md](docs/DATAMODEL.md)** - Database schema and relationships
 - **[API_V1.md](docs/API_V1.md)** - Public and agency API contract (v1)
 - **[DATA_DICTIONARY.md](docs/DATA_DICTIONARY.md)** - Canonical domain field definitions
+- **[RBAC_ACCOUNT_ORG_MANAGEMENT.md](docs/RBAC_ACCOUNT_ORG_MANAGEMENT.md)** - Enterprise role, account, and organization management model
 - **[AGENCY_ONBOARDING.md](docs/AGENCY_ONBOARDING.md)** - First-time agency setup guide
 - **[AGENCY_ADMIN_GUIDE.md](docs/AGENCY_ADMIN_GUIDE.md)** - Guide for government staff
 - **[PUBLIC_USER_GUIDE.md](docs/PUBLIC_USER_GUIDE.md)** - Guide for citizens

docs/ARCHITECTURE.md

@@ -9,6 +9,12 @@ OpenComments is a shared multi-tenant public comment platform:
 - Supabase Edge Functions for async jobs and notifications
 - Netlify static hosting
 
+Core security and governance model:
+
+- Shared multi-tenant data model with agency-scoped RLS policies.
+- Enterprise RBAC for agency and platform administrators.
+- Account/profile self-service with guarded fields and role-safe organization management workflows.
+
 ## Primary Personas
 
 - Public commenters

docs/DATAMODEL.md

@@ -8,6 +8,9 @@ OpenComments uses PostgreSQL with Supabase's Row Level Security (RLS) to ensure
 
 ## 📋 Core Entities
 
+> Canonical role and account governance behavior is defined in `docs/RBAC_ACCOUNT_ORG_MANAGEMENT.md`.  
+> This document focuses on relational structures and RLS patterns.
+
 ### User Management
 
 **profiles**
@@ -584,4 +587,4 @@ FOR EACH ROW EXECUTE FUNCTION update_docket_search_vector();
 
 ---
 
-**See also**: [ARCHITECTURE.md](ARCHITECTURE.md), [DEVELOPER.md](DEVELOPER.md)
+**See also**: [ARCHITECTURE.md](ARCHITECTURE.md), [DEVELOPER.md](DEVELOPER.md)

docs/RBAC_ACCOUNT_ORG_MANAGEMENT.md

@@ -0,0 +1,68 @@
+# RBAC, Account, and Organization Management
+
+This document defines the production RBAC and account-management model for OpenComments.
+
+## Agency Role Definitions
+
+| Role | Responsibility | Can manage users? | Can manage dockets? | Can moderate comments? | Can edit agency settings? |
+| --- | --- | --- | --- | --- | --- |
+| `owner` | Organization governance and final authority | Yes (all roles) | Yes | Yes | Yes |
+| `admin` | Operational administration | Yes (`manager`, `reviewer`, `viewer`) | Yes | Yes | Yes |
+| `manager` | Program operations for public-comment periods | No | Yes | Yes | No |
+| `reviewer` | Moderation workflow execution | No | No | Yes | No |
+| `viewer` | Read/export only | No | No | No | No |
+
+## Platform Roles
+
+| Role | Responsibility |
+| --- | --- |
+| `super_owner` | Full platform administration and super-user management |
+| `super_user` | Agency provisioning and invitation operations |
+
+## Enterprise Guardrails
+
+Database-enforced guardrails are implemented in `supabase/migrations/20260211000600_rbac_account_management_hardening.sql`:
+
+- Managers are excluded from agency-admin controls (`is_agency_admin` is owner/admin only).
+- Admins cannot assign or modify `owner`/`admin` members.
+- Users cannot deactivate their own agency membership.
+- APIs prevent removal/deactivation of the last active owner.
+- Role self-downgrades require ownership transfer flow.
+- Self profile updates cannot modify protected fields (`role`, `email`, `agency_name`) unless platform-admin.
+
+## Primary Workflows
+
+### 1. Member self-service
+
+- Route: `/agency/users`
+- All agency members can:
+  - View their role and effective permissions.
+  - Update profile display name.
+  - Request elevated access through support workflow.
+
+### 2. Agency admin management
+
+- Owners/Admins can:
+  - Invite users.
+  - Change eligible roles within governance limits.
+  - Activate/deactivate memberships within governance limits.
+  - Review pending invitations and resend/revoke invites.
+
+### 3. Ownership governance
+
+- Owners can transfer ownership to another active member.
+- Transfer demotes existing owners to `admin` and promotes selected member to `owner`.
+
+## UI Surfaces
+
+- Agency navigation now exposes a unified `Users & Access` entry for all agency roles.
+- User dropdown includes `My Profile & Access` quick access.
+- Platform admin invitation flow uses live agency data instead of mock organization lists.
+
+## Verification
+
+Automated checks include:
+
+- `src/types/roles.test.ts` for role hierarchy/assignment contracts.
+- `tests/rbac-policy-contracts.test.js` for migration-level RBAC guardrail contracts.
+- `tests/tenant-isolation-policies.test.js` for tenant isolation policy assumptions.

docs/plan/M02-auth-rbac-and-multi-tenancy.md

@@ -7,6 +7,8 @@ Implement real agency membership and permission checks with tenant isolation.
 - Replace mocked permission and agency context hooks with DB-backed lookups.
 - Enforce role-aware behavior in app logic.
 - Add/validate RLS for agency-isolated resources.
+- Harden account and role-management guardrails in RPCs.
+- Provide self-service profile management for all agency members.
 
 ## Out of scope
 
@@ -19,11 +21,15 @@ Implement real agency membership and permission checks with tenant isolation.
 - [x] Update permissions hook to use real memberships.
 - [x] Ensure platform roles are loaded from `platform_roles`.
 - [x] Add tests for tenant isolation assumptions.
+- [x] Add explicit role-assignment/status-change guardrails (owner/admin boundaries, last-owner protections, self-change protections).
+- [x] Add account profile self-service update flow backed by `profiles` with secure field protection.
 
 ## Acceptance criteria
 
 - [x] Agency routes use actual membership data.
 - [x] Permission gating no longer depends on mock role mapping.
+- [x] Manager role cannot administratively manage users/settings outside docket/moderation scope.
+- [x] Role/status change APIs prevent unsafe operations (self-deactivation, removing last owner, unauthorized role elevation).
 
 ## Risks/blockers
 
@@ -40,3 +46,5 @@ Implement real agency membership and permission checks with tenant isolation.
 - 2026-02-11: Updated permission hook to derive role/capabilities from real membership records with legacy fallback behavior only when needed.
 - 2026-02-11: Updated auth context bootstrapping to load `platform_roles` during session initialization.
 - 2026-02-11: Added `tests/tenant-isolation-policies.test.js` to verify RLS enablement and tenant predicates exist across agency-scoped tables.
+- 2026-02-11: Added migration `20260211000600_rbac_account_management_hardening.sql` to tighten `is_agency_admin` semantics (owner/admin only), enforce enterprise role/status guardrails in membership RPCs, and protect restricted profile fields from self-escalation.
+- 2026-02-11: Expanded agency user experience with self-service profile management and role-permission catalog while retaining admin workflows for invite/role/status/ownership management.

docs/plan/M03-agency-operations.md

@@ -7,6 +7,7 @@ Replace mock agency workflows with real data operations.
 - Docket list/detail/create flows.
 - User management routing and role workflows.
 - Moderation queue functionality.
+- Organization ownership transfer and account access UX.
 
 ## Out of scope
 
@@ -18,11 +19,14 @@ Replace mock agency workflows with real data operations.
 - [x] Remove high-visibility "coming soon" placeholders in core agency routes.
 - [x] Connect docket pages to real Supabase tables/RPCs.
 - [x] Ensure moderation queue reads/writes real moderation data.
+- [x] Provide non-admin self-service account/profile experience in agency portal.
+- [x] Provide owner ownership-transfer workflow in agency portal.
 
 ## Acceptance criteria
 
 - [x] Agency can create and manage dockets without mock data.
 - [x] Agency moderation actions persist and are auditable.
+- [x] Agency staff can manage profile/access clearly from one consistent Users & Access screen.
 
 ## Risks/blockers
 
@@ -44,3 +48,4 @@ Replace mock agency workflows with real data operations.
 - 2026-02-11: Replaced mock agency dashboard data in `src/pages/agency/AgencyDashboard.tsx` with real agency analytics, moderation queue, and docket summary queries.
 - 2026-02-11: Replaced mock docket detail workflow in `src/pages/agency/DocketDetail.tsx` with real Supabase reads/writes, moderation actions, supporting-document retrieval, and audit/moderation activity history.
 - 2026-02-11: Implemented real docket edit-mode behavior in `src/pages/agency/DocketWizard.tsx`, including preload/update of existing docket settings and additive supporting document uploads.
+- 2026-02-11: Upgraded `src/pages/agency/UserManagement.tsx` into a unified Users & Access experience with profile self-service, explicit permission catalog, role catalog, admin team management filters, and owner ownership transfer.

docs/plan/M07-ux-accessibility-and-design-system.md

@@ -40,3 +40,4 @@ Consolidate UX architecture and enforce accessible, coherent UI patterns.
 - 2026-02-11: Expanded `docs/ACCESSIBILITY_TRACKER.md` with a concrete WCAG 2.1 AA verification checklist for primary public and agency workflows.
 - 2026-02-11: Removed unused legacy pages (`src/pages/AgencyDashboard.tsx`, `src/pages/AgencyLogin.tsx`) that contained stale placeholder/duplicate agency UI, leaving canonical `/pages/agency/*` surfaces as the single implementation path.
 - 2026-02-11: Added Playwright + Axe automated accessibility baseline (`tests/playwright/accessibility.pw.ts`) and verified no `critical` violations on primary entry routes; recorded in `docs/ACCESSIBILITY_TRACKER.md`.
+- 2026-02-11: Refined `Users & Access` IA so all agency roles have a single profile/access surface, with admins getting advanced management controls and role catalog context in the same page.