Next.js

PurposeCopy Anchor Link

permdock/next is the full-stack adapter for Next.js 16.3 and later (the next peer range is >=16.3); its client half, permdock/next/client, holds PermissionBoundary. One createPermDock call in a server-only file returns the async server API (getPermDock, getPermission, requireAccess), a Server Component provider that serialises the snapshot for permdock/react, and a Route Handler for the batched decision endpoint. The design goals come from Next.js 16.3 Instant Navigations: permission-gated UI must land in the prefetched App Shell, never block a navigation, and refresh when roles change. The end-to-end pattern for a multi-org app is the Next.js Cache Components guide.

APICopy Anchor Link

// src/permdock/server.ts (server-only)
import "server-only";
import { cookies } from "next/headers";
import { createPermDock } from "permdock/next";
import { policy } from "@/policy";

export const {
  getPermDock,
  getPermission,
  requireAccess,
  PermDockProvider,
  permdockHandler,
} = createPermDock(policy, {
  subject: async () => getUser(await cookies()),
  tenant: async () => (await cookies()).get("org")?.value, // active tenant; accepted only when a membership matches
  onDenied: () => redirect("/forbidden"), // runs on assert and requireAccess refusals
});

The active tenant usually comes from the URL (app/[org]/...); a Server Component or Route Handler passes it explicitly with getPermDock({ tenant: params.org }), and the resolver above is the fallback for requests without a segment. Either way the value is a request, not a fact: core keeps it only when principal.memberships holds that tenant, otherwise tenant-scoped checks are denied with no-membership (tenancy).

// app/[org]/layout.tsx: never awaits; hooks under it answer pending until the snapshot streams in
import { PermDockProvider } from "@/permdock/server";
export default function Layout({ children }) {
  return (
    <PermDockProvider include={[permissions.post, permissions.billing]}>
      {children}
    </PermDockProvider>
  );
}

// app/posts/[id]/page.tsx (RSC), a Server Action or a Route Handler
import { getPermDock, getPermission } from "@/permdock/server";
const permdock = await getPermDock();
permdock.assert(permissions.post.update, post);
const { allowed } = await getPermission(permissions.post.update, post);
await requireAccess({
  permission: permissions.post.update,
  data: post,
  tenant: org,
}); // forbidden() / unauthorized() on a denial

// app/api/permdock/route.ts: decision endpoint for closure grants
import { permdockHandler } from "@/permdock/server";
export const { POST } = permdockHandler();

// Client components import from permdock/react, never from permdock/next
import { usePermission, useTenant, useFilter, Protected } from "permdock/react";

PermissionBoundaryCopy Anchor Link

requireAccess replaces a whole segment with forbidden.tsx. When only part of a page is gated, and the rest should keep rendering, let the check throw and catch it with PermissionBoundary from permdock/next/client, a 'use client' entry built on catchError from next/error:

// app/[org]/quotes/[id]/page.tsx (Server Component)
import { PermissionBoundary } from "permdock/next/client";

<PermissionBoundary
  denied={<p>Only staff can delete quotes.</p>}
  approval={<ApprovalNotice />}
>
  <Suspense fallback={null}>
    {/* awaits getPermDock(), then permdock.assert(permissions.quote.delete, quote) */}
    <DeleteZone params={params} />
  </Suspense>
</PermissionBoundary>;

// approval-notice.tsx
("use client");
import { usePermissionBoundary } from "permdock/next/client";

export function ApprovalNotice() {
  const state = usePermissionBoundary(); // { outcome, permission, token?, retry }
  if (state?.outcome !== "approval-required") return null;
  return (
    <button onClick={() => state.retry()}>I have approval, try again</button>
  );
}

• It recognises PermDockDeniedError and PermDockApprovalRequiredError by their digest (errors), which is the only part of a Server Component error that reaches the client in production. Every other error, and forbidden(), notFound() and redirect(), passes to the next boundary up.
• denied renders for a denial; approval for an approval request, defaulting to denied. Each is a React node, which a Server Component can pass, or, from a Client Component, a function of the usePermissionBoundary() state: approval={(state) => <RequestAccess token={state.token} />}.
• usePermissionBoundary() inside a fallback returns the permission key, the approval token for a request-access flow, and retry(), which re-fetches and re-renders the boundary's children, for example after the approval is granted or a role changes.
• Put a Suspense inside the boundary: during server rendering an error goes to the nearest Suspense, and the boundary catches it when the client renders.
• The boundary never decides; the check that threw did. Keep the enforcement in the Server Action as well.

Active tenant from a root segmentCopy Anchor Link

When the organization is the root segment (app/[org]/layout.tsx is the root layout), the getter next/root-params generates for it is already a tenant resolver, so deep components need neither props nor getPermDock({ tenant }):

import { org } from "next/root-params";

export const { getPermDock, getPermission, requireAccess } = createPermDock(
  policy,
  {
    subject: async () => getUser(await cookies()),
    tenant: org,
  },
);

Root parameters are readable only in Server Components: in a Server Action or Route Handler the getter throws, the resolver yields no tenant, and tenant-scoped checks deny. Pass { tenant } explicitly there. With Cache Components, the root layout also needs generateStaticParams returning at least one value.

Segment configs and linksCopy Anchor Link

A capability token in the URL (?token=) is URL data: a <Link prefetch={true}> resolves it in the prefetch, so every such link costs a server render, and a shared 'use cache' scope must never read it, because its output would be served to everyone. Verify the token inside 'use cache: private' or at request time, and link to token pages with the default prefetch.

Why an explicit factory file and not a Next pluginCopy Anchor Link

The next.config.ts plugin (createPermDockPlugin) exists only as a build hook for permdock collect; it never wires runtime API. Runtime wiring lives in src/permdock/server.ts because:

• The file is the single import boundary between server and client. It can carry import 'server-only', so a client component importing getPermDock fails at build time (permix issue 49 leaked Prisma and Better Auth into the browser bundle through a middleware callback).
• Types flow from the returned object, not from module augmentation. Two policies, or a test double, can coexist.
• Same shape in Vite, Expo and Hono: one file, one createPermDock. See Next.js plugin.

Request lifecycleCopy Anchor Link

1. A request or RSC render starts. The first call to getPermDock, getPermission or PermDockProvider runs the subject resolver inside React.cache; the result is memoised for the rest of the render. Server Actions and Route Handlers get their own instance per invocation.
2. Snapshot. For permission UI that should be prefetched, the app owns the cache directive. PermDock never adds 'use cache' and never reads headers() or cookies() itself; getSnapshot runs the factory's subject resolver and sets the lifetime and tag inside the app's private cache:

// src/permdock/snapshot.ts
import { getSnapshot } from "./server";

export async function loadSnapshot(org: string) {
  "use cache: private";
  // cacheLife(cacheLifeFor(snapshot)): 30 s minimum for per-link prefetch, 300 s for the App Shell
  // cacheTag(snapshotTag(sub), ...tags): permdock:<sub>, or permdock:anon
  return getSnapshot({ tenant: org, include: [permissions.post] });
}

// app/[org]/layout.tsx: synchronous, so the layout itself is static
import { PermDockProvider } from "permdock/react";
export default function Layout({ children, params }) {
  return (
    <PermDockProvider
      snapshotPromise={params.then(({ org }) => loadSnapshot(org))}
    >
      {children}
    </PermDockProvider>
  );
}

Without the factory, call snapshotFor(policy, user, { tenant }) and set cacheLife(cacheLifeFor(snapshot)) and cacheTag(snapshotTag(user?.id)) yourself, as getSnapshot does. The tenant is part of the cache key because it is an argument, so /acme and /globex shells carry different snapshots; a subject that does not belong to the segment's tenant gets an empty tenant scope, never another tenant's grants.

'use cache: private' caches per browser session, so session-derived output is allowed into the prefetched App Shell. Anything that reads cookies() without it must render behind a Suspense boundary or the navigation blocks. 3. Guards resolve from the shell. Client Protected and usePermission answer from the prefetched snapshot, so a link to an admin page paints on click. Data-dependent checks (getPermission(permissions.post.update, post) where post comes from the database) sit under Suspense and stream. 4. Mutations. A Server Action calls permdock.assert(...) or await requireAccess(...), performs the write, then updateTag(snapshotTag(user)) (the tag your loader set) if the write changed roles, memberships or custom roles, which invalidates the private cache and the client refetches. A Route Handler, such as a billing webhook, an entitlement webhook or a revocation-counter bump, uses revalidateTag(tag, { expire: 0 }) instead, because updateTag works only in Server Actions. Not revalidateTag(tag, 'max'): stale-while-revalidate would keep serving the revoked grant for one more visit. refresh() is for a Server Action that changed nothing cached but must repaint the acting browser. A role-assignment action additionally checks permissions.member.assignRole and that the new role is in permdock.assignableRoles() before writing (tenancy). 5. Closure grants. usePermission posts batched evaluations to app/api/permdock/route.ts; permdockHandler resolves the same subject, validates the posted data at the boundary and answers. 6. Segments that must not be prefetched with permission UI export instant = false (see segment configs).

OpenAPICopy Anchor Link

Next.js has no built-in spec generator, so permdock/next has no in-process OpenAPI hook. The recipe is a producer plus PermDock's Overlay:

1. next-openapi-gen scans app/api/**/route.ts, generates an operationId per handler, and scaffolds Scalar as the docs UI.
2. permdock openapi emit --format overlay writes permdock.overlay.json with securitySchemes, per-operation security and x-permdock-* for every handler that calls getPermDock().assert(...) or is wrapped by permdockHandler (CLI: openapi).
3. next-openapi-gen's overlay.apply merges the Overlay before writing the spec, so Scalar, any Arazzo files it compiles, and SDK generators such as @hey-api/openapi-ts see the applied description.

// openapi-gen.config.ts
export default defineConfig({
  openapi: "3.2.0",
  overlay: { apply: ["./permdock.overlay.json"] },
});

permdock openapi emit --doc public/openapi.json --format overlay --out permdock.overlay.json --check   # CI
pnpm exec openapi-gen generate

next-openapi-gen accepts Overlay 1.0 to 1.2, so this recipe is where --overlay 1.2 (the pinned Overlay 1.2 draft with reusable actions, OpenAPI Overlay) can be used first; the default 1.1 output works identically.

Rules: operationId is the join key, and --check fails on a handler without one. Do not use next-openapi-gen's @auth JSDoc tag or authPresets on handlers PermDock covers; two sources of security on one operation is the failure mode the recipe exists to avoid. PermDock owns security; the producer owns paths and schemas. The Overlay is the documented default here because the description is generated on every build (Overlay).

MCP routeCopy Anchor Link

A Next.js app exposes an MCP server as a route handler through mcp-handler; permdock/mcp guards it with the same policy and the same subject resolver the rest of the app uses (MCP adapter, Hosting). This is the route the PermDock Cloud template on the Vercel Marketplace exposes (Cloud adapter).

// app/api/mcp/route.ts
import { createMcpHandler, withMcpAuth } from "mcp-handler";
import { createPermDock } from "permdock/mcp";
import { createJwtSubjectResolver } from "permdock/jwt";
import { policy, permissions } from "@/permissions";
import { store } from "@/permdock"; // the same ApprovalStore the server components use

const verify = createJwtSubjectResolver({
  issuer: process.env.AUTH_ISSUER!,
  audience: process.env.MCP_RESOURCE!,
});
const { protectServer } = createPermDock(policy, {
  subject: (authInfo) => authInfo.extra?.subject ?? null,
  store,
});

const handler = createMcpHandler((server) => {
  const guarded = protectServer(server);
  guarded.registerTool(
    "delete_post",
    { permission: permissions.post.delete, inputSchema, data: loadPost },
    deletePost,
  );
});

const authed = withMcpAuth(
  handler,
  async (_req, token) => {
    const subject = await verify(token);
    if (!subject.principal) return undefined;
    return {
      token,
      clientId: subject.claims.client_id,
      scopes: subject.claims.scope?.split(" ") ?? [],
      expiresAt: subject.expiresAt,
      extra: { subject },
    };
  },
  { required: true },
);

export { authed as GET, authed as POST };

Three rules. The subject comes from the verified bearer token, never from the app session: an MCP client is not a browser and carries no cookie. store must be durable on Vercel because each invocation is stateless (memoryApprovalStore() would drop a pending approval; permdock doctor warns). And the route is unrelated to permdockHandler(), which serves the client decision endpoint for the React side; the two can share one policy file and nothing else. mcp-handler also mounts on Nuxt, SvelteKit and Hono with the same file, so the recipe is not Next-specific.

What it validates and how denials surfaceCopy Anchor Link

The shared adapter contract applies; the Next.js specifics:

• include must reference groups or resources from the policy's definition; unknown references are a type error.
• permdock/next is server-only: createPermDock throws when it runs where document exists. Keep it in a server-only file; the definition module stays client-safe.
• assert runs the layered handlers: the per-call handler, instance on('denied') hooks, then onDenied from the factory. PermDock picks no default page behaviour: the app's onDenied calls redirect() or notFound(), and without one assert throws PermDockDeniedError. PermDockApprovalRequiredError carries the replay-safe token so an approval page can call the action again.
• getPermission never throws a PermDock error; a failure to build the instance returns a no-grant denial. Next.js interrupts from subject or tenant (redirect(), notFound(), request-time bailouts) pass through, as from getPermDock. requireAccess throws only the Next.js interrupts and the two assert errors above.
• Route Handlers using permdockHandler answer with Problem Details; client components behave as in React.
• The subject always comes from the factory's subject resolver; getPermDock and requireAccess accept only a tenant. A Route Handler authenticated by a bearer token instead of cookies uses permdock/server with a token resolver. The active tenant stays explicit (getPermDock({ tenant }), the tenant prop, or the tenant resolver); PermDock never reads a [org] segment on its own. Only the App Router is supported.

Next.js 16.3 functionsCopy Anchor Link

How permdock/next relates to each function in the Next.js functions reference. "Adapter" means permdock/next calls it; "app" means the app calls it next to PermDock.

Plain NodeCopy Anchor Link

permdock/next and permdock/next/client also load without a bundler: in Vitest, which runs dependencies as plain Node ES modules, and in Node scripts. next publishes no exports map, so the entries import next/cache.js, next/server.js and next/error.js with their file extension. next/navigation goes through the package import #next/navigation: under the react-server condition it stays the bare next/navigation, which Next.js maps to its server build, and elsewhere it resolves to next/navigation.js. Turbopack and webpack builds are unchanged.

Example appCopy Anchor Link

apps/examples/next is a field-service app on named scopes: organizations (acme, globex) with staff roles, and customers inside them whose portal contacts see only their own quotes. It turns on cacheComponents, partialPrefetching, experimental.authInterrupts and experimental.useOffline.

• src/permdock/server.ts calls createPermDock from permdock/next; src/lib/access.ts holds the app-owned caches: loadSnapshot (private, cacheLifeFor), visibleQuotes (private, permdock.filter), and quoteAccess (private, keyed on the quote id).
• The staff quote page wraps a request-time delete check in PermissionBoundary: a member sees an approval notice with a retry button, a contact sees the denied fallback, and the quote itself keeps rendering.
• /[org] pages and the portal export instant = true; /[org]/settings exports prefetch = 'force-disabled' and instant = false and calls requireAccess.
• Quote links use <Link prefetch={true}>; Server Actions call requireAccess and then updateTag.

To check a route by hand, open the Next.js DevTools in next dev, select Navigation Inspector, turn on Pause on navigations, then refresh (the static shell) or click a link (the prefetched UI) and confirm the gated nav and actions are already there. Prefetching happens only under next start, so confirm the result with pnpm --filter @permdock/example-next build and start.

apps/examples/next-better-supabase is the same shape on Supabase sessions from better-supabase: /[locale]/[orgSlug]/... routes, staff roles in memberships, portal contacts through contacts.user_id, and the PermDock access-token hook and RLS helpers generated from one set of sources. It runs in snapshot-only mode (endpoint={false}, no /api/permdock route), loads the snapshot and the RLS-filtered rows through bs.cached(), and tags both with snapshotTag(sub) (the recipe). pnpm --filter @permdock/example-next-better-supabase serve starts Postgres in testcontainers, so it needs Docker.

WhyCopy Anchor Link

• The app owns every cache directive. Whether a value may be shared ('use cache') or only per session ('use cache: private'), how long it lives and which tags bust it depend on where the app reads the session and what it mutates. A directive inside the package would hide those choices. So permdock/next returns plain values (cacheLifeFor, snapshotFor), and the example shows where 'use cache: private' goes.
• io(), never connection(). Both keep the clock read out of the static shell, but connection() waits for a real request and so blocks every prefetch of a gated page. io() suspends only the prerender and resolves at once inside a cache scope, which is where prefetchable permission UI lives.
• { expire: 0 }, not 'max', for revocations. 'max' is Next.js's recommended stale-while-revalidate default for content; for a permission it means one more visit with the revoked grant.
• No scopeFromRootParams() export. next/root-params generates one getter per root segment, named after the folder, so a library cannot import it. The getter is already a tenant resolver.
• PermissionBoundary reads a digest. A client boundary sees a Server Component error in production only through its digest, and Next.js keeps a digest the error already carries. So the denial and approval errors set a stable one in core, where every adapter throws them, and the boundary parses it instead of matching messages or class names. It is an error boundary, not a gate: a second way to hide UI on a client-side check would compete with <Protected>.
• endpoint: false, not a missing route. Without the option, a closure grant read by usePermission posts to /api/permdock, and an app that never added the route gets a 404 per check and a pending that resolves to a denial over the network. false makes the choice explicit, keeps the browser from making the request at all, and gives the denial its own reason so a test can assert it. permdock doctor PD044 warns when a hook reads such a grant and neither a route nor an endpoint exists.
• requireAccess takes an object. A collection permission has no row, and a positional requireAccess(p, undefined, { tenant }) placeholder is easy to misread; the object form states the tenant where it is used.

Related standardsCopy Anchor Link

• AuthZEN: decision endpoint shapes served by permdockHandler.
• Problem Details: Route Handler denials.
• Standard Schema: boundary validation.
• OpenAPI 3.2 and OpenAPI Overlay: the next-openapi-gen recipe above.
• Design rationale: Next.js 16.3 Instant Navigations, the collect extraction model, explicit factory over a plugin, composing with the OpenAPI toolchain and the ecosystem index.