Multi-Tenant Auth & RBAC Core

Every B2B SaaS eventually needs the same spine — orgs, roles, invites, sessions, and a guarantee that tenant A can never see tenant B's data — and it's the code teams reliably get wrong the first time, usually by finding out in a security review or a customer's pentest. This pack builds it: DB-backed sessions, multi-org membership with owner/admin/member roles, a full invite lifecycle, and Postgres row-level security as the actual enforcement wall, not just an app-layer check that hopes nobody forgets a `WHERE` clause. The receipt proves it: a 39-check, ~105-assertion verify suite — including cross-tenant probes run directly against the database as the app's own restricted role — has to pass before this pack ships.

Example use cases

• **A solo founder** turning a single-user side project into a real team plan — adding "invite your team," role-gated admin controls, and per-org data before their first paid pilot.
• **An agency** shipping the same B2B admin panel to multiple clients, each client isolated as its own org on shared infrastructure, without operating a separate database per customer.
• **A dev-tools startup** adding organization support ahead of a security review, where "prove tenant data can't leak" is a question an enterprise buyer's security team will actually ask.
• **A vertical SaaS team** (scheduling, ticketing, ops tooling) forking the pack's `notes` exemplar resource into their real per-tenant table — the org-scoped CRUD, permission checks, and RLS policies are already worked out; they copy the pattern instead of re-deriving it.

Why this pack

Everyone building multi-tenant SaaS chooses between four paths. Here's the honest comparison:

**On the bare-agent column, specifically** — these are the classes of bug this pack pre-solves, not hypothetical:

• Connecting the app as the Postgres **owner role** on a managed host. Neon and Railway both hand you an owner connection string by default, and row-level security does not bind the table owner — so RLS is silently off, and everything still looks like it works in testing.
• **`USING`-only write policies.** A policy that correctly blocks cross-tenant reads but has no `WITH CHECK` still lets a request insert rows into another tenant's org.
• **Pooler-unsafe session context.** Setting tenant identity with a session-scoped `SET` instead of a transaction-local `set_config(..., true)` leaks one request's org context into the next request that reuses the same pooled connection — invisible until concurrent traffic on a transaction-mode pooler exposes it.

**On the auth-SaaS column** — Clerk, Auth0, and similar are genuinely good at what they do: login screens, session UX, SSO, MFA. That's a different problem from this pack. An auth SaaS tells you *who* someone is; it says nothing about whether your database will hand tenant A's rows to tenant B once they're logged in. This pack is the tenancy-enforcement layer and pairs fine with an auth SaaS in front of it if you want one — it isn't a replacement for one, and this pack ships its own DB-backed sessions instead because owning exact invalidation semantics (revoke-on-password-change, no-stale-role-claims) is the actual product here.

**On hand-rolling** — what you're buying isn't the idea, it's the ~300-line frozen migration (schema, RLS policies, `SECURITY DEFINER` helpers, grants) and the 39-check verify suite that had to pass against it. That's the part that takes an experienced engineer real time to get exactly right and is easy to get subtly wrong in ways that don't show up until a specific bad request arrives.

We won't claim this pack makes your app unhackable — no pack can promise that. What the receipt backs is narrower and true: the specific cross-tenant leak classes above are closed by construction and asserted by an automated suite that connects to the database directly, not just through the app.

Scale envelope

Derived from the shipped architecture, not aspiration — and labeled as an engineering estimate, since it isn't load-tested at this pack's price point:

• **Per-query cost of enforcement:** every tenant-scoped policy resolves through a `SECURITY DEFINER` helper (`is_org_member`) doing a single primary-key-indexed lookup on `org_members(org_id, user_id)` — not a join, not a scan. `org_id` is denormalized onto every tenant table specifically so policies never need one. In practical terms, RLS enforcement adds the cost of one indexed lookup per query, not a cost that grows with your data.
• **Why the pooling design matters at scale:** identity is set with `set_config('app.user_id', ..., true)` inside an explicit transaction — `is_local=true` means it dies at COMMIT/ROLLBACK. That's what makes this safe under **transaction-mode connection pooling** (PgBouncer, Neon's pooler), which is the standard way to serve far more concurrent app requests than Postgres's raw connection limit allows. A session-scoped `SET` — the naive version — would leak context between requests sharing a pooled connection and simply doesn't work under transaction pooling. This design does.
• **Estimate:** a single small managed Postgres instance (roughly the smallest paid tier on Railway or Neon — shared vCPU, a few hundred MB–1GB RAM, fronted by a transaction-mode pooler) should comfortably serve low thousands of orgs and tens of thousands of users at this schema's normal CRUD load. This is an estimate based on the indexing and policy shape, not a benchmark result.
• **Where the first ceiling actually is:** not RLS policy cost — it's the same two things that limit any single-instance Postgres app: raw connection count (before you're pooling) and general write throughput/vacuum overhead as `org_members` and your tenant tables grow. Nothing about the RLS/GUC design imposes a lower ceiling than plain Postgres would have anyway.
• **Upgrade path:** the standard Postgres playbook, unchanged by this pattern — bump instance size, add a read replica for read-heavy endpoints (member lists, notes lists), and only at genuinely large single-tenant volume consider partitioning a table like `notes` by `org_id`. Because `org_id` is already denormalized onto every tenant table, this schema is also a reasonable starting point for sharded/distributed Postgres (e.g. Citus-style) if you ever outgrow a single instance — that's a distant follow-on, not something this pack implements.

**What it costs to skip the pack (modelled, not measured):** building this spine yourself the way most people actually work — one agent on a top-tier model, no cheap-tier routing, no parallel subagents, no prompt-caching discipline — models out at roughly **$60–245 in API tokens, likely around $120**. That's this pack's own measured build volume repriced at Opus-class rates, multiplied by an exploration factor for the ~20 tenancy decisions in `ARCHITECTURE.md`; the pack-guided build itself measured ≈$6 of tokens per verification run (August 2026 rates), because tasks route down to cheaper tiers. Honest reading: at the likely figure that is **less** than the $149 price — the token math alone does not pay for this pack, and we won't pretend otherwise. What it pays for is the 39-check isolation suite, and the fact that the leak classes above are the ones you'd otherwise find in someone else's pentest report.

Verified against

• claude-opus-5
• claude-sonnet-5
• claude-haiku-4-5

Supported stacks

• nextjs-postgres

  next	16.2.12
  react	19.2.8
  react-dom	19.2.8
  pg	8.22.0
  zod	4.4.3
  @node-rs/argon2	2.0.2
  typescript	5.9.3
  @types/node	24.13.3
  @types/pg	8.20.3
  @types/react	19.2.18
  @types/react-dom	19.2.4
  tailwindcss	4.3.3
  @tailwindcss/postcss	4.3.3
  class-variance-authority	0.7.1
  clsx	2.1.1
  tailwind-merge	3.6.0
  @radix-ui/react-slot	1.3.3
  tw-animate-css	1.4.0
  postgres	18.4
  node	24.18.1

Estimated buyer token cost

550,000 tokens for one build pass (estimate, not a guarantee).