Identity & Access

Who are you, and what are you allowed to do here?

The Job​

When a platform serves multiple organisations, help every user land in the right org with the right permissions — so no one is locked out, no one sees data they shouldn't, and the builder never needs to touch the database to onboard a customer.

Pitch-Prompt Deck​

Five cards. Five headlines. Five pictures. The meme layer — 80 cents in the dollar.

Priority Score​

PRIORITY = Pain x Demand x Edge x Trend x Conversion

The Incident​

2026-02-24: Owner locked out of production dashboard. App completely inaccessible — infinite redirect loop between /dashboard and /sign-in?error=admin_access_required every ~400ms.

Root cause (from Vercel production logs, request ID dx89j-1771901662057-8dbab5d4899c):

1. Authentication succeeds — Clerk validates session, ClerkAuthAdapter resolves userId → systemUserId → organisationId. All correct.
2. User-Role query fails with PostgreSQL 22P02 (invalid text representation) — the role lookup passes the Clerk userId string (user_36MjIJRckjpXRqdOHaZcgMpFjzE) to a column expecting UUID. The systemUserId (f388dbc7-cb98-41ee-9708-d6f5d2c54fe0) is the correct UUID to use.
3. Feature access denied — because the query errored (not because the role doesn't exist). The system logs feature_access_denied for dashboard read.
4. Infinite redirect loop — dashboard denies access → redirects to /sign-in?error=admin_access_required → Clerk sees user IS authenticated → afterSignInUrl: "/dashboard" → redirect back → loop.

The bug is in the User-Role query, not the role data. Even if roles were seeded correctly, the query would still fail because it's casting a string to UUID. Fix the query first, then seed the roles.

Evidence: 789 warnings + 789 errors in the Vercel logs within 30 minutes from the redirect loop alone.

What this reveals: Authentication and authorization are different systems with different failure modes. Authentication failing = "I can't get in." Authorization failing = "I got in but I can't do anything." The second is worse — it looks like a bug, erodes trust, and blocks revenue.

Current State Audit​

What's built vs what's wired.

Summary: Authentication is solid. Multi-tenancy schema is solid. Authorization is a landmine — schema exists, guards deployed, but no data and no admin bootstrapping. Billing, settings, and analytics are unbuilt.

Multi-Tenant Checklist Audit​

Every item from the Multi-Tenant SaaS Checklist, scored against the current codebase. This is the specification — every item must pass before multi-tenancy is commissioned.

1. Foundational Model​

2. Data Isolation​

3. User-Org Association​

4. Organisation ID Propagation​

5. Authentication and Sessions​

6. RBAC​

7. Billing and Subscriptions​

8. Settings​

9. Onboarding​

10. Analytics​

11. Security and Isolation​

12. Future-Proofing​

Audit Summary​

22% passing. Schema depth is real — most "Fail" items have tables built but no wiring, no data, no enforcement. The gap is operational, not architectural.

Demand-Side Jobs​

Job 1: I Built This — Let Me In​

Situation: Platform owner deploys the app. First user. No admin role exists yet. The guard that should protect the app from strangers is blocking the builder.

Features that serve this job:

• Bootstrap admin: first user in an org OR ADMIN_EMAILS env var gets Admin role auto-assigned
• Admin bootstrap runs on first login, not manual DB insert
• ADMIN_EMAILS env var documented and configured in Vercel production
• If isOrgAdmin() fails, show clear error message (not just a redirect param)
• Admin status visible in user profile/settings

Job 2: Control Who Sees What​

Situation: The platform grows. Sales team member joins. They should see their deals, not admin settings. A client gets a portal login. They should see their RFP status, not the pipeline.

Features that serve this job:

• Three roles defined: Admin, Member, Viewer
• Role assignment on invite/onboarding
• PolicyEngine switched from defaultAllow: true to defaultAllow: false
• Per-resource permission checks on server actions
• Role-based UI: admin routes, member routes, viewer routes
• Audit trail for access decisions (governance_access_audit table already exists)

Job 3: Separate My Clients' Worlds​

Situation: Platform serves multiple organisations. Each org's data must be isolated. An RFP from Company A must never appear in Company B's dashboard.

Features that serve this job:

• ApplicationContext.organizationId always present (enforced by ClerkAuthAdapter)
• All repository queries filter by org ID (audit existing queries)
• Database-level RLS policies as defense-in-depth (Supabase/Postgres)
• Org switching for users who belong to multiple orgs
• Org creation flow (name, settings, invite first members)

Job 4: Invite Someone Without a Support Ticket​

Situation: Admin wants to add a team member. They shouldn't need to ask a developer to insert a database row.

Features that serve this job:

• Invite-by-email from admin settings
• Invite creates pending membership (accepted on sign-up)
• Role assigned at invite time
• Invite revocable before acceptance
• Member removable after acceptance
• Clerk organization sync (Clerk orgs ↔ internal orgs)

Job 5: Know What's Happening in My Org​

Situation: Admin needs visibility into who did what, when, in their org. Billing needs to count seats. Settings need to stay within org boundaries.

Features that serve this job:

• Billing on org, not user — stripeCustomerId wired to org_organisation
• Seat counting from memberships
• Org-level settings page
• Per-org user preferences on agent_profile
• Analytics events include organisationId
• Org-scoped activity feed or audit log UI

Architecture: The Desired Flow​

Authentication Flow (WHO are you?)​

Browser → Clerk Middleware → Session Valid?
  ├── NO  → /sign-in (public route)
  └── YES → ClerkAuthAdapter.validateContext()
              ├── Clerk userId present?
              │     ├── NO  → INVALID_SESSION error
              │     └── YES → Lookup in org_system_user
              │                 ├── FOUND → Return ApplicationContext
              │                 └── NOT FOUND → Auto-provision
              │                                  ├── Create org_system_user
              │                                  ├── Create "Personal Workspace" org
              │                                  ├── Assign Admin role (bootstrap)
              │                                  └── Return ApplicationContext
              └── Error → LOOKUP_FAILED / PROVISION_FAILED

This flow exists and works. The gap: auto-provision creates the user and org but does NOT assign the Admin role.

Authorization Flow (WHAT can you do?)​

Server Action called
  → buildService() → authAdapter.validateContext()
    → Returns ApplicationContext { userId, systemUserId, organizationId }
      → governance.policyEngine.canI(context, action, resourceType)
        ├── defaultAllow: true  → ALLOW (current state — bypass)
        └── defaultAllow: false → Check governance_role_permissions
              ├── Permission found → ALLOW
              └── Permission not found → DENY → 403

Admin route guard (current):

/admin/layout.tsx
  → isOrgAdmin()
    → Check 1: Is email in ADMIN_EMAILS env var? → YES = admin
    → Check 2: Does user have "Admin" role in governance_user_roles? → YES = admin
    → Neither? → redirect('/dashboard?error=admin_access_required')

Multi-Tenancy Model​

Clerk User (external)
  └── org_system_user (internal, branded SystemUserId)
        └── org_organisation (tenant boundary)
              ├── All business data scoped here
              ├── governance_user_roles (what can this user do in this org?)
              └── governance_permissions (what actions exist?)

One user can belong to multiple orgs (composite unique: external_auth_id + organisation_id)

Data Flow: Org ID Propagation​

Request arrives
  → Clerk Middleware (validates session cookie)
    → ClerkAuthAdapter.validateContext()
      → Resolves: externalAuthId → systemUserId → organisationId
        → Returns ApplicationContext { systemUserId, organisationId, ... }
          → buildService(context)
            → Every repository method receives organisationId
              → Every SQL query includes WHERE organisation_id = $1
                → Response scoped to tenant

The enforcement gap: Nothing prevents a repository method from omitting the WHERE clause. The fix is either:

• Code-level: base repository class that requires organisationId (Tier 2)
• Database-level: Postgres RLS policies as defense-in-depth (Tier 3)

Implementation Tiers​

Tier 0: Unblock Owner (Immediate)​

Fix the infinite redirect loop. Two bugs, both must be fixed.

Success criteria: Owner logs in → lands on dashboard → no redirect loop → can access /admin. Verified by nav (dream team) via browser commissioning.

Tier 1: Bootstrap Admin on First Login​

Make Tier 0 unnecessary for future deploys.

Success criteria: Fresh deploy → first sign-up → automatic admin → full access.

Tier 2: Role-Based Access Control​

Switch from defaultAllow: true to enforced permissions.

Success criteria: defaultAllow: false in production. No permission = no access. Audit log captures every deny.

Tier 3: Multi-Org & Invites​

Full multi-tenancy operations.

Success criteria: Admin invites user by email → user signs up → lands in correct org with correct role → admin can manage members from UI.

Tier 4: Billing, Settings, Analytics​

Operational infrastructure for paying customers.

Success criteria: Admin can see billing, manage settings, view org-scoped analytics. Stripe invoices go to the org, not the user.

Tier 5: Hardening​

Defense-in-depth and future-proofing.

Success criteria: No cross-tenant leakage under any role. Security tests automated. Enforcement approach documented.

Role Definitions​

Permission Model​

Permissions follow the pattern already in governance_permissions schema:

{resource_type}:{action}

Commissioning​

Browser-based validation against this PRD. The builder never validates their own work.

Risk + Kill Signal​

Kill signal: None — this is mandatory infrastructure. Every SaaS product requires multi-tenancy. The question is not "should we build this" but "in what order." Kill signals apply to the ventures that depend on this, not to this capability itself.

Business Validation​

Success Criteria​

Context​

• Multi-Tenant SaaS Checklist — the engineering standard this PRD must satisfy (54 items, 12 passing)
• Browser Commissioning Protocol — how dream team validates fixes
• Sales CRM & RFP — the product blocked by this regression
• Hexagonal Architecture — the pattern that makes isolation enforceable
• Identity and Security — auth provider decisions
• Clerk Documentation — authentication provider
• Jobs to Be Done — demand-side thinking
• Commissioning Dashboard — maturity tracking