Server kernel

PurposeCopy Anchor Link

permdock/server implements the shared behaviour of every server adapter once, in terms of the Fetch API (Request, Response, Headers). Frameworks that already speak Fetch (Hono, Elysia, SvelteKit, Next.js Route Handlers, Bun, Deno, Cloudflare Workers) can use it directly. Frameworks with their own request types (Express, Fastify, Nest, Node http) wrap it with a few lines of typed glue. The kernel owns four things: subject resolution, request-scoped instance creation, protect semantics, and the denial-to-response mapping. Adapters add only naming, storage of the instance on the framework context, and OpenAPI hooks.

permix adapters each copy request isolation onto the framework context; PermDock does it once in the kernel (landscape).

APICopy Anchor Link

import {
  createPermDock,
  discoverViaSignatureAgent,
  verifyWebBotAuth,
} from "permdock/server";
import { policy } from "./policy";

export const { permdock, protect, connection, problem, openapi } =
  createPermDock(policy, {
    subject: async (request) => userFromSession(request.headers.get("cookie")),
    actor: async (request) => agentFrom(request), // optional; Web Bot Auth fills this automatically when enabled
    webBotAuth: (request) =>
      verifyWebBotAuth(request, {
        // optional RFC 9421 verification
        keys: discoverViaSignatureAgent({ allow: ["agents.example.com"] }),
        required: false,
      }),
    tenant: (request) => orgFromPath(request), // optional; resolved again on every protect
    limits: memoryLimitStore(), // optional LimitStore for quota grants
  });

// Plain Fetch handler
export default async function handler(request: Request): Promise<Response> {
  const guard = await protect(permissions.post.delete, (request) =>
    loadPost(idFrom(request)),
  )(request);
  if (!guard.ok) return guard.response; // 403 application/problem+json
  const { permdock: instance, data: post } = guard;
  await deletePost(post);
  return new Response(null, { status: 204 });
}

OptionsCopy Anchor Link

Typed genericsCopy Anchor Link

createPermDock in the kernel is generic over the policy (for permission and subject types) and over an optional Ctx type that framework adapters bind to their context. Adapter factories forward those generics so c.get('permdock') in Hono, req.permdock in Express and ctx.permdock in tRPC are typed PermDock for that policy without casts. permix's setupMiddleware returned an untyped MiddlewareHandler, which its users hit in issue 27; here the middleware type is derived, not any.

Build an adapterCopy Anchor Link

createServerKernel(policy, options) is the kernel every in-tree HTTP and RPC adapter builds on; an out-of-tree adapter uses it the same way. It returns a ServerKernel: the members of createPermDock, each taking an optional TenantScope ({ tenant }) as its last argument. The adapter resolves its own tenant option against its framework context with tenantScope(option, context) and passes the result, so the kernel never reads the framework context. ServerKernelOptions adds one option to ServerPermDockOptions and narrows another:

import { createServerKernel, tenantScope } from "permdock/server";

const kernel = createServerKernel(policy, {
  subject: (request) => userFrom(request),
  adapter: "my-framework",
});

app.use(async (ctx) => {
  const scope = await tenantScope(options.tenant, ctx);
  const guard = await kernel.protect(permissions.post.read)(ctx.request, scope);
  if (!guard.ok) return guard.response;
});

testHttpAdapter in permdock/testing runs the shared adapter contract against the result.

protect semanticsCopy Anchor Link

• Collection action (permissions.post.create): no loadData; decide runs on the subject alone.
• Instance action with loadData: the loader runs before the handler; a null or undefined result is a 404 .../not-found problem, and so is a denial on a resource with disclosure: 'hide' (permissions); the loaded value is validated against the resource schema unless protect is called with { trusted: true }. The decision endpoint always treats resource.properties as untrusted and validates them.
• Denial status: 401 for an anonymous caller or a step-up (with acr_values and max_age), 429 with Retry-After and the RateLimit fields when every denial is limit, 503 for limit-unavailable, 403 otherwise (Problem Details).
• approval-required: protect fails closed with a 403 whose type ends in /approval-required and whose body carries token. The handler never runs.
• OAuth scopes per route: protect(permission, loadData, { oauthScopes: ['api:read'] }), or the scopes the matching operation declares under operations, narrow which coarse scopes reach the route. When the subject carries a token delegation (an OAuth client's scope), a token that holds none of them is refused before the loader runs with a 403 and WWW-Authenticate: Bearer error="insufficient_scope", scope="api:read", naming the first; a subject without a delegation, such as a first-party session, is not gated. They only narrow, as in permdock/mcp: the decision still needs the delegation to cover the permission, so the policy's oauthScopes lists the permission under each coarse scope that may reach it. A later delegation denial names the route's first scope in its challenge too. An empty list throws.
• A route without a permission, such as a chat endpoint or setting the caller's active organization: protect(null, loadData?, { oauthScopes: ['api:chat'] }), or protect(null) with operations declaring { oauthScopes } for the operation. The guard checks no permission and has no decision: an anonymous caller gets a 401, a delegated token that holds none of the scopes the same 403 insufficient_scope challenge, and a first-party session passes. protect(null) with no scopes in its options and no operations throws when it is built, and a request no operation declares scopes for throws when it runs. The Hono, Express, Fastify, Elysia, Node, Nest (Protect(null, …)), tRPC and oRPC adapters take null the same way, and the Supabase middleware takes withPermDock({ oauthScopes }) without protect.
• A loader that throws fails closed: the error is reported through on('error') and the route answers 403 with reason validation and the detail <key> failed closed: the row could not be loaded, as permdock/mcp does. The handler never runs.
• Per-route decide options: protect(permission, loadData, { trusted, oauthScopes, field, explain }). field checks one schema field of the row, as decide(…, { field }) does, and explain adds the trace to the decision the guard returns.
• A failed guard is { ok: false, response, decision }, with decision absent when the route checks no permission or the loader found no row, so an adapter that builds its own answer can read the outcome.
• Every outcome is emitted through on('decision') like any other decision. The decision event carries the permission, resource, subject, tenant and outcome, not the HTTP method or path; an otel span or a wrap adds request context where it is needed.

Verified materialCopy Anchor Link

The subject resolver is the kernel's trust boundary. createPermDock(policy, { subject: async (request) => ... }) receives the raw Request, and whatever the resolver returns is taken as verified: the kernel does not re-verify sessions or tokens, so the resolver must only return material something has already checked (Authentication and PermDock).

Three consequences:

• A resolver that decodes a JWT without verifying it, or reads a X-User-Id header, has turned unverified input into a principal, and nothing downstream can detect it. Use a subjectFrom* function or the framework's session API as the last step of the resolver.
• MCP servers do not go through this resolver: permdock/mcp receives authInfo from the SDK's bearer middleware and hands the principal mapping the same verified object (MCP adapter). The shape of the trust boundary is the same; only the carrier differs.
• API keys resolve through subjectFromApiKey(options), exported here next to its helpers (apiKeyVerifier, memoryCredentials, generateApiKey, hashApiKey, parseApiKey). It is itself a SubjectResolver, so a resolver that reads a pdk_ bearer calls it and returns the subject; a service key's membership comes from the credential, so skip the memberships source for it (API keys).
• binding is pass-through. The kernel records the cnf object (jkt or x5t#S256) but does not check proof-of-possession; that is done by the resolver (verifyDpopProof in permdock/jwt) or by the TLS terminator for mTLS. An adapter that can forward the client certificate thumbprint passes it to the resolver as the second argument.

Snapshot loadersCopy Anchor Link

getSnapshot(request) returns the snapshot a client provider (permdock/react, permdock/vue, permdock/svelte, permdock/solid) takes. Send it with snapshotHeaders(snapshot) when the framework lets a loader set headers. The private Cache-Control keeps a shared cache from storing it, and its max-age never reaches past expiresAt. Call invalidate() or refresh() on the client after a role change.

React Router 7 and 8, in app/root.tsx (apps/examples/react-router):

import { snapshotHeaders } from "permdock/server";
import { PermDockProvider } from "permdock/react";
import { data, Outlet, useLoaderData } from "react-router";
import { getSnapshot } from "~/permdock.server";

export async function loader({ request }: Route.LoaderArgs) {
  const snapshot = await getSnapshot(request);
  return data({ snapshot }, { headers: snapshotHeaders(snapshot) });
}

export function headers({ loaderHeaders }: Route.HeadersArgs) {
  return loaderHeaders;
}

export default function App() {
  const { snapshot } = useLoaderData<typeof loader>();
  return (
    <PermDockProvider snapshot={snapshot} endpoint="/api/permdock">
      <Outlet />
    </PermDockProvider>
  );
}

TanStack Start, with a server function the root route's loader calls:

import { createServerFn } from "@tanstack/react-start";
import { getRequest, setResponseHeaders } from "@tanstack/react-start/server";
import { snapshotHeaders } from "permdock/server";
import { getSnapshot } from "./permdock.server";

export const loadSnapshot = createServerFn().handler(async () => {
  const snapshot = await getSnapshot(getRequest());
  setResponseHeaders(new Headers(snapshotHeaders(snapshot)));
  return snapshot;
});

SvelteKit, in src/routes/+layout.server.ts; the layout passes data.snapshot to setPermDock:

import { snapshotHeaders } from "permdock/server";
import { getSnapshot } from "$lib/server/permdock";

export async function load({ request, params, setHeaders }) {
  const snapshot = await getSnapshot(request, { tenant: params.org });
  const { "Cache-Control": cacheControl, Vary: vary } =
    snapshotHeaders(snapshot);
  setHeaders({ "Cache-Control": cacheControl, Vary: vary });
  return { snapshot };
}

Nuxt, with a server route that useFetch reads before app.use(permdockPlugin, { snapshot }):

// server/api/permdock/snapshot.get.ts
import { snapshotHeaders } from "permdock/server";
import { getSnapshot } from "~~/server/permdock";

export default defineEventHandler(async (event) => {
  const snapshot = await getSnapshot(toWebRequest(event));
  setResponseHeaders(event, snapshotHeaders(snapshot));
  return snapshot;
});

ConnectionsCopy Anchor Link

A WebSocket, an SSE stream or a subscription lives longer than one decision. connection(request, options?) resolves the subject from the request that opened it and returns a frozen Connection:

const guard = await protect(permissions.project.read, loadProject)(request);
if (!guard.ok) return guard.response;
const conn = await connection(request, {
  permission: permissions.project.read,
  data: guard.data,
});

for await (const event of projectEvents(conn.signal)) {
  for (const row of conn.filter(permissions.project.read, [event])) send(row);
}
// conn.signal.reason is a PermDockRevokedError: send its toProblemDetails(), then close
conn.close();

ConnectionOptions are permission and data (a value or a loader) for the permission that opened the connection, re-checked after every revalidation, and revalidate (milliseconds, off by default) for a periodic revalidation. The connection aborts with expired at the subject's expiresAt, and revalidates at the earliest membership expiry and on a changed event from revocations: subject(request) runs again on the original request, and a different or missing principal aborts with subject-changed. A session-revoked event aborts without revalidating.

Open a connection only after protect succeeded, so the refusal at open is the usual 401, 403 or 404 response. Framework adapters wrap the transport: Hono (socket, sse), tRPC and oRPC (async iterables returned behind protect), Elysia (connection(ws)) and Nest (connection(client, req)).

Request lifecycleCopy Anchor Link

The kernel implements the shared adapter contract for every HTTP adapter. What it adds:

• permdock(request) always takes a Fetch Request. Adapters with their own request type convert it first (toRequest in permdock/node) and pass their framework context only to the tenant resolver, so memoisation has one key everywhere.
• When webBotAuth is set and the request carries Signature and Signature-Agent, the kernel verifies the RFC 9421 signature against the agent's directory (the created / expires window, covered components and key lookup) and fills actor with the verified key id.
• Bearer tokens are not validated here; the subject resolver or a provider does that, and the kernel only reads the scopes and authorization_details the resolver returns.
• PermDockDeniedError thrown by assert inside a handler is caught by the adapter's error hook and routed through problemFromError.

How denials surfaceCopy Anchor Link

denied and approval-required become 403 application/problem+json bodies built by problem (Problem Details, errors); boundary validation failures are 400 with issues. Anonymous subjects hitting a permission that any role could grant receive 401 with WWW-Authenticate when the adapter knows the scheme, otherwise 403. The approval-required body with its token is the whole signal over plain HTTP: the kernel adds no Retry-After (a human reviewer has no predictable latency) and no Location (the approval UI belongs to the application or the approvals inbox).

Example appCopy Anchor Link

apps/examples/react-router calls getSnapshot and snapshotHeaders from its root loader and serves the decision endpoint from a resource route. The rest of the kernel is exercised by every HTTP example (apps/examples/hono first) and by the Bun, Deno and workerd apps in tests/runtimes. Kernel unit tests live next to the entry and cover anonymous subjects, loadData returning null, boundary validation failures (PermDockValidationError to 400), and approval-required responses. tests/integration/src/http/kernel.test.ts runs the testHttpAdapter scenarios against the kernel behind a plain Fetch handler on @hono/node-server.

Related standardsCopy Anchor Link

• Problem Details (RFC 9457).
• OpenAPI: the security and securitySchemes shapes the hook contract emits.
• Web Bot Auth (RFC 9421 HTTP Message Signatures).
• OAuth agent delegation: where delegation values come from.