Should authorization live in the database or the application layer?

Both, but they are not equal. Row-level security in Postgres is the real wall, because it runs where the user cannot reach it and it holds even if a route check is forgotten. The can() guard on your oRPC procedures and the hidden buttons in your UI are defense in depth and user experience, not the security boundary. Write the RLS policy first and treat the application checks as convenience on top of it. If only one layer exists, it has to be RLS.

What is the difference between a role and a permission in this model?

A permission is a single named capability, like post.delete or role.manage. A role is a bundle of permissions, like admin or viewer. Users are assigned roles, roles carry permissions, and your code only ever checks permissions, never roles. That indirection is the whole point. When you check can(context, 'post.delete') instead of checking role === 'admin', you can later create a new role, or move a permission from one role to another, without touching a single line of application code.

How do I add a new permission to an existing feature?

Insert one row into the permissions table with a new key, grant it to the roles that should have it in role_permissions, add a per-action RLS policy on the affected table that calls has_permission('your.new.key'), and attach requirePermission('your.new.key') to the matching oRPC procedure. There is no application schema migration and no redeploy needed to hand the permission out afterward. Assigning it to a role is a row change the role editor UI makes at runtime.

Roles and Permissions

Add one feature to your SaaS and you inherit four questions: who can see it, who can edit it, who can delete it, and where you enforce all three. A reusable authorization layer answers them once. This guide builds role based access control in Next.js 16 that every future feature plugs into for free: a roles and permissions schema in Postgres, a can() guard on your oRPC procedures, per-action Supabase RLS policies, and a role editor UI so you can hand out access without a deploy.

The goal is that "add the feature, then bolt on auth later" stops being a step. By the end, a new table ships with its policies, a new procedure ships behind a guard, and a new button only renders for people who can actually use it.

The Four Layers, and Which One Is Real

Authorization in a Next.js app lives in four places, and it helps to be honest about what each one is for.

The database layer (Supabase RLS) is the only one an attacker cannot route around. It runs inside Postgres, on every query, keyed to the verified user ID. The oRPC guard is the second layer: it rejects a forbidden call before your handler runs, with a clean error the client can display. The UI layer hides buttons a user cannot use, which is a courtesy, not a lock. The proxy layer redirects unauthenticated visitors at the edge before anything renders.

Only the first is a security boundary. The other three exist so the app feels right and fails early. Build them in reverse: write the RLS policy first, then the guard, then the UI. If you only ever get one done, RLS is the one that matters. This is the same principle behind adding authentication with Supabase, extended from "is this row yours" to "are you allowed this action".

The Permission Model

Roles belong in the database, and so do permissions. The mistake most tutorials make is hardcoding a single role column and then checking role === "admin" in fifty places. The day you need a "billing manager" who can refund but not delete users, you are editing fifty files.

Instead, model it as two things with a join between them. A permission is one named capability. A role is a bundle of permissions. Users hold roles, roles carry permissions, and your code only ever asks about permissions. This runs as a migration.

-- A role a user can hold: owner, admin, member, viewer, whatever you need
create table public.roles (
  id uuid primary key default gen_random_uuid(),
  key text unique not null,
  name text not null,
  description text
);

-- One named capability, keyed by a stable string like 'post.delete'
create table public.permissions (
  id uuid primary key default gen_random_uuid(),
  key text unique not null,
  description text
);

-- Which permissions each role grants (many-to-many)
create table public.role_permissions (
  role_id uuid references public.roles(id) on delete cascade,
  permission_id uuid references public.permissions(id) on delete cascade,
  primary key (role_id, permission_id)
);

-- Which roles each user holds (many-to-many, so a user can be admin AND editor)
create table public.user_roles (
  user_id uuid references auth.users(id) on delete cascade,
  role_id uuid references public.roles(id) on delete cascade,
  primary key (user_id, role_id)
);

The key columns are what your code references. A permission key like post.delete never changes even as you rename its display label. The user_roles table is many-to-many on purpose: a user can be both a member and a billing role, and their effective permissions are the union.

Seed the Default Roles

Give yourself four sensible roles and a starting set of permissions. The keys are the contract your code depends on, so pick them deliberately and treat them as stable.

insert into public.roles (key, name, description) values
  ('owner',  'Owner',  'Full access, including managing roles'),
  ('admin',  'Admin',  'Manage content and members'),
  ('member', 'Member', 'Create and edit content'),
  ('viewer', 'Viewer', 'Read-only access');

insert into public.permissions (key, description) values
  ('post.read',   'View posts'),
  ('post.create', 'Create posts'),
  ('post.update', 'Edit posts'),
  ('post.delete', 'Delete posts'),
  ('role.manage', 'Create roles and assign permissions');

Now wire the roles to permissions. The owner gets everything. The admin gets everything except the one permission that lets someone rewrite the permission system itself, which is the kind of least-privilege line worth drawing early.

-- Owner gets every permission
insert into public.role_permissions (role_id, permission_id)
select r.id, p.id
from public.roles r cross join public.permissions p
where r.key = 'owner';

-- Admin gets everything except managing roles
insert into public.role_permissions (role_id, permission_id)
select r.id, p.id
from public.roles r cross join public.permissions p
where r.key = 'admin' and p.key <> 'role.manage';

-- Member: read, create, update (no delete)
insert into public.role_permissions (role_id, permission_id)
select r.id, p.id
from public.roles r join public.permissions p
  on p.key in ('post.read', 'post.create', 'post.update')
where r.key = 'member';

-- Viewer: read only
insert into public.role_permissions (role_id, permission_id)
select r.id, p.id
from public.roles r join public.permissions p on p.key = 'post.read'
where r.key = 'viewer';

There is a bootstrapping catch worth naming: the role editor below needs the role.manage permission to open, so the very first owner has to be assigned by hand. Run one insert into public.user_roles in the Supabase SQL editor for your own user ID and the owner role, and every assignment after that happens in the UI.

has_permission() and Per-Action RLS

Two Postgres functions do the heavy lifting. Both are SECURITY DEFINER so they run with the definer's rights and bypass RLS during their own lookups, which matters for two reasons: it avoids infinite recursion when a policy on a permission table needs to read the permission tables, and it means the join tables never need their own broad read policies.

The first function answers "does the signed-in user have this permission" and gets called from inside RLS policies.

create function public.has_permission(perm text)
returns boolean
language sql
security definer
stable
set search_path = ''
as $$
  select exists (
    select 1
    from public.user_roles ur
    join public.role_permissions rp on rp.role_id = ur.role_id
    join public.permissions p on p.id = rp.permission_id
    where ur.user_id = (select auth.uid())
      and p.key = perm
  );
$$;

The second returns the full set of permission keys for the current user, which the Next.js request context reads once per request to build the can() guard. A matching my_roles() does the same for role keys, so a user can see the roles they hold.

create function public.my_permissions()
returns setof text
language sql
security definer
stable
set search_path = ''
as $$
  select p.key
  from public.user_roles ur
  join public.role_permissions rp on rp.role_id = ur.role_id
  join public.permissions p on p.id = rp.permission_id
  where ur.user_id = (select auth.uid());
$$;

create function public.my_roles()
returns setof text
language sql
security definer
stable
set search_path = ''
as $$
  select r.key
  from public.user_roles ur
  join public.roles r on r.id = ur.role_id
  where ur.user_id = (select auth.uid());
$$;

Now the policies. This is where "per-action" earns its name: instead of one blanket policy per table, you write one policy per SQL action, each gated on the specific permission that action requires. Reading a post checks post.read, deleting one checks post.delete.

alter table public.posts enable row level security;

create policy "read posts with permission"
on public.posts for select
to authenticated
using ( public.has_permission('post.read') );

create policy "create posts with permission"
on public.posts for insert
to authenticated
with check ( public.has_permission('post.create') );

create policy "update posts with permission"
on public.posts for update
to authenticated
using ( public.has_permission('post.update') )
with check ( public.has_permission('post.update') );

create policy "delete posts with permission"
on public.posts for delete
to authenticated
using ( public.has_permission('post.delete') );

Note insert uses with check (it validates the new row) while select and delete use using (they filter existing rows), and update needs both. Getting that split right is exactly the kind of thing to hand Claude Code with the rule written down: "every table gets four policies, one per action, each calling has_permission with the matching key."

Finally, lock down the RBAC tables themselves. The catalog of role and permission names is not secret, so any signed-in user can read it, but only a role.manage holder can touch the assignments.

alter table public.roles enable row level security;
alter table public.permissions enable row level security;
alter table public.role_permissions enable row level security;
alter table public.user_roles enable row level security;

create policy "read roles catalog" on public.roles
  for select using (true);

create policy "read permissions catalog" on public.permissions
  for select using (true);

create policy "manage role permissions" on public.role_permissions
  for all to authenticated
  using ( public.has_permission('role.manage') )
  with check ( public.has_permission('role.manage') );

create policy "read own roles" on public.user_roles
  for select to authenticated
  using ( user_id = (select auth.uid()) or public.has_permission('role.manage') );

create policy "assign roles" on public.user_roles
  for all to authenticated
  using ( public.has_permission('role.manage') )
  with check ( public.has_permission('role.manage') );

Loading Permissions Into Request Context

The database is now airtight on its own. The application layer is about making the app pleasant and failing fast, and it starts with loading the user's permissions once per request. This context helper runs on the server, reads the verified user, and calls the two functions from above.

// server/orpc/context.ts
import { createClient } from "@/lib/supabase/server";

export interface Context {
  userId: string;
  roles: string[];
  permissions: Set<string>;
}

export async function createContext(): Promise<Context> {
  const supabase = await createClient();
  const {
    data: { user },
  } = await supabase.auth.getUser();

  if (!user) {
    return { userId: "", roles: [], permissions: new Set() };
  }

  const [{ data: perms }, { data: roles }] = await Promise.all([
    supabase.rpc("my_permissions"),
    supabase.rpc("my_roles"),
  ]);

  return {
    userId: user.id,
    roles: roles ?? [],
    permissions: new Set<string>(perms ?? []),
  };
}

That uses a my_roles() companion to my_permissions(), identical in shape but selecting r.key from roles instead of permission keys, useful when you want to show a user their own roles. Storing permissions as a Set<string> makes the lookup in the next step an O(1) has() call.

One caution on Next.js 16 caching: never put a "use cache" directive on createContext() or anything derived from it. It reads auth.uid(), so a cached copy would serve one user's permission set to the next visitor, which is a cross-tenant leak. The static permission catalog is fair game to cache since it is the same for everyone, but the per-user set never is.

The can() Guard on oRPC Procedures

Here is the piece the whole layer is named for. can() is a pure function over the context, and requirePermission() wraps it in oRPC middleware that throws before any handler runs. Writing the check once, in one file, is what keeps it from drifting across the codebase.

// server/orpc/base.ts
import { os, ORPCError } from "@orpc/server";
import type { Context } from "./context";

export const base = os.$context<Context>();

// The single source of truth for "is this allowed"
export function can(context: Context, permission: string): boolean {
  return context.permissions.has(permission);
}

// oRPC middleware factory: attach it to any procedure to gate it
export const requirePermission = (permission: string) =>
  base.middleware(async ({ context, next }) => {
    if (!can(context, permission)) {
      throw new ORPCError("FORBIDDEN", {
        message: `Missing permission: ${permission}`,
      });
    }
    return next();
  });

Attaching it is one line per procedure. Because the middleware runs before the handler, a forbidden call never reaches your business logic, and the FORBIDDEN error carries a message the client can surface.

// server/orpc/posts.ts
import { z } from "zod";
import { base, requirePermission } from "./base";
import { createClient } from "@/lib/supabase/server";

export const deletePost = base
  .use(requirePermission("post.delete"))
  .input(z.object({ id: z.string().uuid() }))
  .handler(async ({ input }) => {
    const supabase = await createClient();
    const { error } = await supabase.from("posts").delete().eq("id", input.id);
    if (error) throw error;
    return { ok: true };
  });

Notice this procedure is now guarded twice on purpose. The requirePermission("post.delete") middleware rejects the call cleanly, and even if a bug slipped past it, the delete posts with permission RLS policy would still refuse the query in Postgres. The guard exists for a better error and an earlier exit, not because the database needs help.

Hiding UI the User Cannot Use

The same can() function drives the UI, so there is no second definition of "allowed" to keep in sync. In a Server Component, build the context and check the permission before rendering the button. Next.js 16 hands you params as a promise, so it needs await.

// app/posts/[id]/page.tsx
import { createContext } from "@/server/orpc/context";
import { can } from "@/server/orpc/base";
import { DeletePostButton } from "@/components/delete-post-button";

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function PostPage({ params }: PageProps) {
  const { id } = await params;
  const context = await createContext();

  return (
    <main className="max-w-2xl mx-auto py-10">
      {/* ...post content... */}
      {can(context, "post.delete") && <DeletePostButton id={id} />}
    </main>
  );
}

If a user without post.delete inspects the page, the button is simply not there. If they forge the request anyway, the oRPC guard and the RLS policy both reject it. Three layers, one definition of the rule.

The Role Editor UI

The payoff of modeling roles in the database is that you can edit them at runtime. A non-engineer opens a page, ticks a box, and a role gains a permission with no deploy. The editor is a set of oRPC procedures behind role.manage, plus a small client component for the toggles.

Start with the procedures. Group them under a shared guard so the permission check is declared once.

// server/orpc/roles.ts
import { z } from "zod";
import { base, requirePermission } from "./base";
import { createClient } from "@/lib/supabase/server";

const manageRoles = base.use(requirePermission("role.manage"));

export const listRoles = manageRoles.handler(async () => {
  const supabase = await createClient();
  const { data, error } = await supabase
    .from("roles")
    .select("id, key, name")
    .order("name");
  if (error) throw error;
  return data ?? [];
});

export const listPermissions = manageRoles.handler(async () => {
  const supabase = await createClient();
  const { data, error } = await supabase
    .from("permissions")
    .select("id, key, description")
    .order("key");
  if (error) throw error;
  return data ?? [];
});

export const getRolePermissions = manageRoles
  .input(z.object({ roleId: z.string().uuid() }))
  .handler(async ({ input }) => {
    const supabase = await createClient();
    const { data, error } = await supabase
      .from("role_permissions")
      .select("permission_id")
      .eq("role_id", input.roleId);
    if (error) throw error;
    return (data ?? []).map((r) => r.permission_id);
  });

export const setRolePermission = manageRoles
  .input(
    z.object({
      roleId: z.string().uuid(),
      permissionId: z.string().uuid(),
      enabled: z.boolean(),
    })
  )
  .handler(async ({ input }) => {
    const supabase = await createClient();
    if (input.enabled) {
      const { error } = await supabase
        .from("role_permissions")
        .upsert({ role_id: input.roleId, permission_id: input.permissionId });
      if (error) throw error;
    } else {
      const { error } = await supabase
        .from("role_permissions")
        .delete()
        .eq("role_id", input.roleId)
        .eq("permission_id", input.permissionId);
      if (error) throw error;
    }
    return { ok: true };
  });

The page reads the current role from the URL, fetches everything through the router client on the server, and renders a checkbox per permission. Keeping the selected role in a search param means a specific role's editor is a shareable link that survives a refresh. In Next.js 16, searchParams arrives as a promise you await.

// app/(admin)/admin/roles/page.tsx
import { createRouterClient } from "@orpc/server";
import { notFound } from "next/navigation";
import { router } from "@/server/orpc/router";
import { createContext } from "@/server/orpc/context";
import { can } from "@/server/orpc/base";
import { RolePermissionToggle } from "@/components/admin/role-permission-toggle";

interface PageProps {
  searchParams: Promise<{ role?: string }>;
}

export default async function RolesPage({ searchParams }: PageProps) {
  const context = await createContext();
  if (!can(context, "role.manage")) notFound();

  const client = createRouterClient(router, { context });
  const { role } = await searchParams;

  const [roles, permissions] = await Promise.all([
    client.listRoles(),
    client.listPermissions(),
  ]);

  const selected = role ?? roles[0]?.id;
  const enabled = selected
    ? await client.getRolePermissions({ roleId: selected })
    : [];
  const enabledSet = new Set(enabled);

  return (
    <main className="max-w-3xl mx-auto py-10 space-y-6">
      <h1 className="text-2xl font-bold">Roles</h1>

      <nav className="flex gap-2">
        {roles.map((r) => (
          <a
            key={r.id}
            href={`/admin/roles?role=${r.id}`}
            className={r.id === selected ? "font-bold underline" : "text-gray-500"}
          >
            {r.name}
          </a>
        ))}
      </nav>

      <ul className="divide-y">
        {permissions.map((p) => (
          <li key={p.id} className="flex items-center gap-3 py-2">
            <RolePermissionToggle
              roleId={selected!}
              permissionId={p.id}
              checked={enabledSet.has(p.id)}
            />
            <span className="font-mono text-sm">{p.key}</span>
            <span className="text-gray-500 text-sm">{p.description}</span>
          </li>
        ))}
      </ul>
    </main>
  );
}

The toggle is a Client Component that calls a Server Action, which forwards to the guarded procedure. Wrapping the call in a transition keeps the checkbox responsive while the write lands.

// components/admin/role-permission-toggle.tsx
"use client";

import { useTransition } from "react";
import { setRolePermissionAction } from "@/app/(admin)/admin/roles/actions";

export function RolePermissionToggle({
  roleId,
  permissionId,
  checked,
}: {
  roleId: string;
  permissionId: string;
  checked: boolean;
}) {
  const [pending, startTransition] = useTransition();

  return (
    <input
      type="checkbox"
      defaultChecked={checked}
      disabled={pending}
      onChange={(e) =>
        startTransition(() =>
          setRolePermissionAction(roleId, permissionId, e.target.checked)
        )
      }
    />
  );
}

The Server Action is a thin wrapper: build the context, call the procedure through the router client, then revalidate so the page reflects the change. The role.manage check still runs inside the procedure, so the action does not re-implement it.

// app/(admin)/admin/roles/actions.ts
"use server";

import { revalidatePath } from "next/cache";
import { createRouterClient } from "@orpc/server";
import { router } from "@/server/orpc/router";
import { createContext } from "@/server/orpc/context";

export async function setRolePermissionAction(
  roleId: string,
  permissionId: string,
  enabled: boolean
) {
  const client = createRouterClient(router, { context: await createContext() });
  await client.setRolePermission({ roleId, permissionId, enabled });
  revalidatePath("/admin/roles");
}

Gate the /admin/roles route at the edge too, so unauthenticated visitors never reach the render. That redirect belongs in proxy.ts (renamed from middleware.ts in Next.js 16), and it works exactly like the admin gate in the admin dashboard guide. The proxy proves someone is signed in, the can() check proves they may manage roles, and the RLS policies prove it one more time at the query.

Quality Gates Before You Ship

Authorization code is the code you least want a silent type error in. Run both gates after every change to this layer.

npx tsc --noEmit
npm run build

The type check catches a renamed permission key that a handler still references. The build catches a Server Action wired to a procedure whose input shape drifted. Then run the real test, which no compiler covers: sign in as a viewer, confirm the delete button is gone, forge the delete request anyway, and confirm both the oRPC guard and the RLS policy refuse it. A green build is necessary, not sufficient.

Wire It Once, Ship It Every Time

The reason to build this as a layer instead of per feature is that Claude Code writes each of these pieces correctly, then re-derives them from scratch on the next project unless the pattern is saved somewhere. The $29 Code Kit is that somewhere: a one-time harness on top of Claude Code that plans the feature, builds it, evaluates the output, tests it against a real browser, and runs the quality gates (zero type errors, zero lint errors, a clean build) before anything is considered done, with the RBAC schema, the can() guard, and per-action RLS already in place from the first migration. It is a one-time purchase, not a subscription, and Claude Code itself still needs its own paid Anthropic plan underneath it. What you get is a new feature that arrives access-controlled instead of one you promise to secure later.

Posted by @speedy_devv

Roles and Permissions

On this page