NestJS

Requires: @nestjs/common 12, @nestjs/core 12 and @nestjs/platform-express 12

PurposeCopy Anchor Link

Nest structures authorization as guards and decorators, so permdock/nest maps the server kernel onto that shape: a module that registers the factory, a guard registered as APP_GUARD that builds the request-scoped instance and evaluates route metadata, a Protect decorator that attaches the permission (and optional loader) to a handler, and a parameter decorator to inject the instance. The kernel only needs the underlying Node request converted once. Outside HTTP (GraphQL, WebSocket gateways, microservices) a route with Protect metadata is denied unless the request option maps the ExecutionContext to a request; a route without metadata passes through.

APICopy Anchor Link

// permdock.module.ts
import { Module } from "@nestjs/common";
import { createPermDock } from "permdock/nest";
import { policy } from "./policy";

export const { PermDockModule, Protect, InjectPermDock } = createPermDock(
  policy,
  {
    subject: (request) => request.user ?? null,
  },
);

@Module({
  imports: [PermDockModule.forRoot({ guard: "global" })],
})
export class AppModule {}

// posts.controller.ts
@Controller("posts")
export class PostsController {
  constructor(private readonly posts: PostsService) {}

  @Delete(":id")
  @Protect(permissions.post.delete, (request) => loadPost(request.params.id))
  async remove(@InjectPermDock() permdock: PermDock, @Param("id") id: string) {
    await this.posts.remove(id);
  }

  @Get()
  async list(@InjectPermDock() permdock: PermDock) {
    return permdock.filter(permissions.post.read, await this.posts.all());
  }
}

GatewaysCopy Anchor Link

connection(client, req, options?) opens a kernel Connection for a gateway client (typed NestSocket: a Socket.IO socket or a raw ws socket), memoised per client. When it aborts, the client receives permdock:error with the Problem Details and is disconnected, or a raw socket is closed with 1008. PermDockGuard on a @SubscribeMessage handler with Protect metadata checks each message against the client's connection the way HTTP protect does: the OAuth scope check, the loader (a null result is a 404 problem), the decision and the approval resume from the PermDock-Approval header on the mapped request. A denial is the usual Problem Details and the connection stays open; a message after revocation throws PermDockRevokedError. Pass revocations to PermDockModule.

@WebSocketGateway()
export class ProjectsGateway
  implements OnGatewayConnection, OnGatewayDisconnect
{
  async handleConnection(client: Socket) {
    await permdock.connection(client, client.request, {
      permission: permissions.project.read,
    });
  }
  async handleDisconnect(client: Socket) {
    (await permdock.connection(client, client.request)).close();
  }
}

Request lifecycleCopy Anchor Link

permdock/nest follows the shared adapter contract through the server kernel. What differs on Nest:

1. PermDockGuard runs for every HTTP route; it converts the platform request, calls subject(request) once, builds the instance for the tenant the tenant option reads from the routed request, and caches it on the request object. Both @nestjs/platform-express and @nestjs/platform-fastify are supported: the guard reads the parsed body or the raw stream of either, and the filter and decision controller write through a ServerResponse or a FastifyReply. Another platform fails loudly with a TypeError naming both.
2. If the handler or class carries Protect metadata, the guard runs the loader, validates untrusted input after Nest's own ValidationPipe has run, and decides. Denials throw before the handler executes. A Protect decorator referencing a permission from a different definition than the module's policy is a type error.
3. Handlers receive the instance through @InjectPermDock() and may call assert, filter or where.
4. PermDockExceptionFilter renders by transport: HTTP gets the kernel's Problem Details; a ws client with emit receives an exception event carrying status: 'error', the title and the Problem Details body; other transports get the exception rethrown to their own filters.

Example appCopy Anchor Link

apps/examples/nest: a posts module on the Express platform with the guard registered by PermDockModule.forRoot({ guard: 'global' }), Protect applied with decorateMethod on PATCH /posts/:id and POST /posts/:id/publish, and the decision endpoint controller.

tests/integration/src/http/nest.test.ts runs the testHttpAdapter scenarios on both platforms: FileInterceptor uploads on Express, @fastify/multipart on Fastify, an admin module under RouterModule and the decision controller at a tenant path.

Related standardsCopy Anchor Link

• Problem Details, OpenAPI 3.2.