Fastify

PurposeCopy Anchor Link

Fastify's plugin system, request decorators and typed route generics map cleanly onto the server kernel. permdock/fastify registers a plugin that resolves the subject in an onRequest hook and decorates request.permdock; protect is a preHandler that loads data, decides and replies with Problem Details on denial. Fastify already fails closed after reply.send() in a hook, so denial never falls through to the handler.

APICopy Anchor Link

import Fastify from "fastify";
import { createPermDock } from "permdock/fastify";
import { policy } from "./policy";
import { permissions } from "./permissions";

export const { permdock, protect } = createPermDock(policy, {
  subject: (request) => request.user ?? null,
});

const app = Fastify();
await app.register(permdock); // request.permdock is the request-scoped PermDock

app.delete<{ Params: { id: string } }>(
  "/posts/:id",
  {
    preHandler: protect(permissions.post.delete, (request) =>
      loadPost(request.params.id),
    ),
    schema: { security: openapi.security(permissions.post.delete).security }, // @fastify/swagger
  },
  async (request, reply) => {
    await deletePost(request.permdockData);
    return reply.code(204).send();
  },
);

EncapsulationCopy Anchor Link

Fastify plugins are encapsulated by default. permdock is wrapped with fastify-plugin so the decorator and error handler are visible to the registering scope and its children; registering it once on the root instance covers every route. Apps that want different policies per prefix register the plugin from a second createPermDock result inside a child scope, and request.permdock is typed per scope through Fastify's declaration merging on the plugin's generic rather than a global FastifyRequest augmentation.

await app.register(
  async (admin) => {
    await admin.register(adminPermdock); // a second factory with a stricter policy
    admin.get(
      "/audit",
      { preHandler: adminProtect(permissions.audit.read) },
      listAudit,
    );
  },
  { prefix: "/admin" },
);

Request lifecycleCopy Anchor Link

permdock/fastify follows the shared adapter contract through the server kernel. What differs on Fastify:

• The plugin's onRequest hook resolves the subject once; protect runs as a preHandler and stores the loaded row on request.permdockData, so the handler does not run the loader twice.
• The plugin registers the error handler itself and chains to the one that was in place before, so thrown PermDock errors become Problem Details and an app's own setErrorHandler keeps handling everything else.
• Fastify's own JSON Schema validation runs first; PermDock validates only the resource shape the policy uses.
• The decision endpoint builds its Web Request from the body Fastify already parsed. Multipart bodies stay with @fastify/multipart: request.file() works in a handler behind protect.
• Using protect on a route in a scope where the plugin is not registered throws at startup.
• Decision events carry request.method and request.routeOptions.url.

Denials are the kernel's Problem Details responses.

WhyCopy Anchor Link

protect takes the route, schema and type provider as generics instead of fixing them to Fastify's defaults, so the handler it returns fits any typed preHandler slot. TypeScript infers route generics (app.get<{ Params }>) into loadData from that slot. A body derived from a type provider's schema does not flow into an inline preHandler: protect(...): the route shorthand infers its own schema generic from the same options object and accepts one handler or an array, and TypeScript does not carry the provider back through both into a nested generic call. The handler still sees the typed body. Rather than a Fastify-specific wrapper, protect<RouteGenericInterface, FastifySchema, ZodTypeProvider>(...) names the provider explicitly, and a loader that only needs request.params.id needs nothing at all. Both patterns are type-tested.

Example appCopy Anchor Link

apps/examples/fastify: posts API with the plugin, protect on CRUD routes, @fastify/swagger emitting securitySchemes and per-route security, the decision endpoint, and app.inject() tests asserting exact denial bodies.

tests/integration/src/http/fastify.test.ts runs the testHttpAdapter scenarios with @fastify/multipart and a prefixed admin plugin.

Related standardsCopy Anchor Link

• Problem Details, OpenAPI 3.2.