Fastify Auth Prisma Plugin

Common errors

• Property 'connectedUser' does not exist on type 'FastifyRequest<RouteGenericInterface, RawServerDefault, RawRequestDefaultExpression, RouteShorthandOptions<RawServerDefault>, ContextConfigDefault>'

  cause Missing TypeScript declaration merging for the `FastifyRequest` interface.
  fix Add `declare module 'fastify' { interface FastifyRequest { connectedUser?: User; } }` to your project's global declaration file or a relevant TypeScript file.

• TypeError: Cannot read properties of undefined (reading 'register')

  cause Attempting to register the plugin before the Fastify instance is fully initialized or when `server` is not a valid Fastify instance.
  fix Ensure `fastify()` is called correctly and `server.register` is invoked within an `async` function with `await` if using top-level await or inside a setup function.

• FastifyError: FST_ERR_MISSING_SECRET: Missing secret

  cause The `secret` option was not provided or was an empty string during plugin registration.
  fix Provide a non-empty string for the `secret` option when registering `fastifyAuthPrismaPlugin`, ideally from `process.env`.

Warnings

• breaking The `declare module 'fastify'` block for `connectedUser` is essential. Failing to include it will result in TypeScript errors when attempting to access `request.connectedUser` within route handlers.
  Fix: Ensure you add the `declare module 'fastify'` snippet as shown in the quickstart or documentation to extend the `FastifyRequest` interface with `connectedUser`.
• gotcha The `secret` option for `fastifyAuthPrismaPlugin` is critical for JWT security. Using a hardcoded or easily guessable secret in production can lead to severe security vulnerabilities. It is strongly recommended to use a robust, externally managed secret.
  Fix: Always store `process.env.JWT_ACCESS_SECRET` in production environments. Consider using environment variable managers or secret management services for deployment.
• gotcha Proper Prisma schema setup is crucial for this plugin. The `Token` and `User` models, along with their relations, must match the structure expected by the plugin for correct authentication flow.
  Fix: Refer to the `prisma.schema` example provided in the documentation to ensure your Prisma models for `User` and `Token` include the necessary fields like `id`, `refreshToken`, `accessToken`, and the relation `owner`/`ownerId`.
• gotcha The `unify-fastify` plugin is registered in the example setup. If your application does not use or register `unify-fastify`, you might encounter unexpected behavior or errors if `fastify-auth-prisma` has a hard dependency or expects its functionalities.
  Fix: Either register `unify-fastify` if it's a required dependency, or check if `fastify-auth-prisma` can function correctly without it based on its internal implementation details or future documentation updates.

Install

• npm install fastify-auth-prisma npm
• yarn add fastify-auth-prisma yarn
• pnpm add fastify-auth-prisma pnpm

Imports

• fastifyAuthPrismaPlugin
  wrong:

  const fastifyAuthPrismaPlugin = require('fastify-auth-prisma').fastifyAuthPrismaPlugin;

  correct:

  import { fastifyAuthPrismaPlugin } from 'fastify-auth-prisma';

  The library primarily uses named exports and is designed for ESM contexts within Fastify. CommonJS require() usage needs to specifically target the named export or use a transpiler.
• createUserToken

  import { createUserToken } from 'fastify-auth-prisma';

  This function is provided as a utility to generate user tokens outside of the main plugin registration.
• User

  import { User } from '@prisma/client';

  While not directly from `fastify-auth-prisma`, the `User` type is crucial for extending FastifyRequest and is sourced from `@prisma/client`, which is a core dependency.

Quickstart

This quickstart demonstrates how to set up `fastify-auth-prisma` with a basic Fastify server, including Prisma client integration, custom user validation, and defining public/protected routes. It shows how `connectedUser` is made available on the request object for authenticated users.

import fastify from 'fastify';
import { PrismaClient, User } from '@prisma/client';
import unifyFastifyPlugin from 'unify-fastify';
import { fastifyAuthPrismaPlugin } from 'fastify-auth-prisma';

const prisma = new PrismaClient();
const server = fastify({
  logger: true
});

declare module 'fastify' {
  interface FastifyRequest {
    connectedUser?: User;
  }
}

async function startServer() {
  await server.register(unifyFastifyPlugin);

  await server.register(fastifyAuthPrismaPlugin, {
    config: [{ url: '/public/*', method: 'GET' }],
    prisma,
    secret: process.env.JWT_ACCESS_SECRET ?? 'supersecretjwtkey',
    userValidation: async (user: User) => {
      if (!user.id) {
        throw new Error('User not found or invalid.');
      }
      // Add custom validation logic here, e.g., check if user is banned
    }
  });

  server.get('/public/hello', async (request, reply) => {
    return { message: 'Hello, public world!' };
  });

  server.get('/protected/hello', async (request, reply) => {
    if (!request.connectedUser) {
      reply.code(401).send({ message: 'Unauthorized' });
      return;
    }
    return { message: `Hello, ${request.connectedUser.id}! You are connected.` };
  });

  try {
    await server.listen({ port: 3000 });
    server.log.info(`Server listening on http://localhost:3000`);
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
}

startServer();