create-nexst-monorepo 0.1.0

package/template/apps/api/src/app-info/app-info.resolver.spec.ts

@@ -0,0 +1,14 @@
+import type { ConfigService } from "@nestjs/config";
+import { vi } from "vitest";
+import { AppInfoResolver } from "#src/app-info/app-info.resolver.js";
+import type { AppConfig } from "#src/config/app.config.js";
+
+describe("appInfoResolver", () => {
+  it("returns the configured title and version", () => {
+    const cfg = {
+      get: vi.fn(() => ({ description: "d", title: "Test API", version: "1.2.3" })),
+    } as unknown as ConfigService<AppConfig, true>;
+
+    expect(new AppInfoResolver(cfg).appInfo()).toEqual({ title: "Test API", version: "1.2.3" });
+  });
+});

package/template/apps/api/src/app-info/app-info.resolver.ts

@@ -0,0 +1,21 @@
+import { ConfigService } from "@nestjs/config";
+import { Query, Resolver } from "@nestjs/graphql";
+import { AppInfoDto } from "#src/app-info/app-info.dto.js";
+import { AllowAnonymous } from "#src/auth/decorator/allow-anonymous.decorator.js"; // @if auth
+import type { AppConfig } from "#src/config/app.config.js";
+
+/**
+ * Public metadata about the running API. Also guarantees the GraphQL schema
+ * always has a root `Query`, which Apollo requires.
+ */
+@Resolver(() => AppInfoDto)
+export class AppInfoResolver {
+  constructor(private readonly cfg: ConfigService<AppConfig, true>) {}
+
+  @AllowAnonymous() // @if auth
+  @Query(() => AppInfoDto)
+  appInfo(): AppInfoDto {
+    const { title, version } = this.cfg.get("app", { infer: true });
+    return { title, version };
+  }
+}

package/template/apps/api/src/app.module.spec.ts

@@ -0,0 +1,93 @@
+import type { NestFastifyApplication } from "@nestjs/platform-fastify";
+import { FastifyAdapter } from "@nestjs/platform-fastify";
+import type { TestingModule } from "@nestjs/testing";
+import { Test } from "@nestjs/testing";
+import { Logger } from "nestjs-pino";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { AppModule } from "#src/app.module.js";
+import { registerGraphqlEnums } from "#src/bootstrap/register-graphql-enums.js"; // @if auth
+import { addSecurity } from "#src/bootstrap/security.js";
+import { addSwagger } from "#src/bootstrap/swagger.js";
+import { PrismaService } from "#src/prisma/prisma.service.js";
+
+// @if auth || worker
+const { fn: mockFn } = vi.hoisted(() => ({ fn: vi.fn }));
+// @endif
+
+// @if auth
+vi.mock("#src/auth/auth.js", () => ({
+  createAuth: mockFn(() => ({ api: { getSession: mockFn() }, options: {} })),
+}));
+// @endif
+// @if worker
+
+vi.mock("ioredis", () => {
+  const Redis = mockFn(function () {
+    return {
+      disconnect: mockFn().mockResolvedValue("OK"),
+      off: mockFn(),
+      on: mockFn(),
+      ping: mockFn().mockResolvedValue("PONG"),
+      quit: mockFn().mockResolvedValue("OK"),
+    };
+  });
+  return { default: Redis, Redis };
+});
+
+vi.mock("bullmq", () => {
+  function connectionLike() {
+    return {
+      add: mockFn(),
+      close: mockFn().mockResolvedValue(undefined),
+      off: mockFn(),
+      on: mockFn(),
+      waitUntilReady: mockFn().mockResolvedValue(undefined),
+    };
+  }
+  return {
+    FlowProducer: mockFn(connectionLike),
+    Job: class Job {},
+    Queue: mockFn(connectionLike),
+    QueueEvents: mockFn(connectionLike),
+    Worker: mockFn(connectionLike),
+  };
+});
+// @endif
+
+describe("appModule (wiring)", () => {
+  let moduleRef: TestingModule;
+  let app: NestFastifyApplication;
+
+  beforeAll(async () => {
+    const prismaMock = {
+      $connect: vi.fn(),
+      $disconnect: vi.fn(),
+      $on: vi.fn(),
+      onModuleDestroy: vi.fn(),
+      onModuleInit: vi.fn(),
+    };
+
+    moduleRef = await Test.createTestingModule({ imports: [AppModule] })
+      .overrideProvider(PrismaService)
+      .useValue(prismaMock)
+      .compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+
+    await addSecurity(app);
+    registerGraphqlEnums(); // @if auth
+    app.useLogger(app.get(Logger));
+    addSwagger(app);
+
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app?.close();
+    await moduleRef?.close();
+  });
+
+  it("compiles", () => {
+    expect(app).toBeDefined();
+  });
+});

package/template/apps/api/src/app.module.ts

@@ -0,0 +1,77 @@
+import type { ApolloDriverConfig } from "@nestjs/apollo";
+import { Module } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config"; // @if auth
+// import { ConfigModule } from "@nestjs/config"; // @if !auth
+import { APP_FILTER, APP_GUARD } from "@nestjs/core"; // @if auth
+// import { APP_FILTER } from "@nestjs/core"; // @if !auth
+import { GraphQLModule } from "@nestjs/graphql";
+import { ThrottlerModule } from "@nestjs/throttler";
+import { AuthModule } from "@thallesp/nestjs-better-auth"; // @if auth
+import { AppInfoModule } from "#src/app-info/app-info.module.js";
+import { AuthGuard } from "#src/auth/auth.guard.js"; // @if auth
+import { createAuth } from "#src/auth/auth.js"; // @if auth
+import { loadConfig } from "#src/config/app.config.js";
+import type { AppConfig } from "#src/config/app.config.js"; // @if auth
+import { graphqlConfig } from "#src/config/graphql.config.js";
+import { HealthModule } from "#src/health/health.module.js";
+import { LoggingModule } from "#src/logging/logging.module.js";
+import { MailModule } from "#src/mail/mail.module.js"; // @if auth
+import { MailService } from "#src/mail/mail.service.js"; // @if auth
+import { PrismaModule } from "#src/prisma/prisma.module.js";
+import { PrismaService } from "#src/prisma/prisma.service.js"; // @if auth
+import { QueueModule } from "#src/queue/queue.module.js"; // @if worker
+import { R2Module } from "#src/r2/r2.module.js"; // @if r2
+import { UserModule } from "#src/user/user.module.js"; // @if auth
+import { CatchEverythingFilter } from "#src/utils/catch-everything-exception.filter.js";
+import { PrismaExceptionFilter } from "#src/utils/prisma-exception.filter.js";
+import { PrismaGraphQLExceptionFilter } from "#src/utils/prisma-graphql-exception.filter.js";
+
+/**
+ * Root NestJS module
+ */
+@Module({
+  imports: [
+    GraphQLModule.forRoot<ApolloDriverConfig>(graphqlConfig),
+    LoggingModule,
+    ConfigModule.forRoot({ isGlobal: true, load: [loadConfig] }),
+    ThrottlerModule.forRoot([
+      {
+        limit: 100,
+        skipIf: () => process.env.NODE_ENV !== "production",
+        ttl: 10_000,
+      },
+    ]),
+    PrismaModule,
+    HealthModule,
+    AppInfoModule,
+    // @if auth
+    MailModule,
+    AuthModule.forRootAsync({
+      disableGlobalAuthGuard: true,
+      imports: [ConfigModule, PrismaModule, MailModule],
+      inject: [PrismaService, ConfigService, MailService],
+      useFactory: (
+        prisma: PrismaService,
+        cfg: ConfigService<AppConfig, true>,
+        mail: MailService,
+      ) => ({
+        auth: createAuth(prisma, cfg.get("security", { infer: true }).allowedOrigins, mail),
+      }),
+    }),
+    UserModule,
+    // @endif
+    // @if r2
+    R2Module,
+    // @endif
+    // @if worker
+    QueueModule,
+    // @endif
+  ],
+  providers: [
+    { provide: APP_GUARD, useClass: AuthGuard }, // @if auth
+    { provide: APP_FILTER, useClass: PrismaExceptionFilter },
+    { provide: APP_FILTER, useClass: PrismaGraphQLExceptionFilter },
+    { provide: APP_FILTER, useClass: CatchEverythingFilter },
+  ],
+})
+export class AppModule {}

package/template/apps/api/src/auth/auth.guard.spec.ts

@@ -0,0 +1,90 @@
+import type { ExecutionContext } from "@nestjs/common";
+import type { Reflector } from "@nestjs/core";
+import type { AuthService } from "@thallesp/nestjs-better-auth";
+import { vi } from "vitest";
+import type { Mock } from "vitest";
+import { AuthGuard } from "#src/auth/auth.guard.js";
+import type { AuthInstance } from "#src/auth/auth.js";
+import { ALLOW_ANONYMOUS_KEY } from "#src/auth/decorator/allow-anonymous.decorator.js";
+import { IS_EMAIL_VERIFIED_KEY } from "#src/auth/decorator/is-email-verified.decorator.js";
+import { ROLES_KEY } from "#src/auth/decorator/roles.decorator.js";
+import { makeSession } from "#src/auth/testing/make-session.js";
+import { ErrorCode } from "#src/errors/error-code.enum.js";
+import { UserRole } from "#src/generated/prisma/client.js";
+
+type AnyRequest = Record<string, unknown>;
+
+const makeContext = (request: AnyRequest): ExecutionContext =>
+  ({
+    getClass: () => ({}),
+    getHandler: () => ({}),
+    getType: () => "http",
+    switchToHttp: () => ({ getRequest: () => request }),
+  }) as unknown as ExecutionContext;
+
+describe("authGuard", () => {
+  let guard: AuthGuard;
+  let reflector: { getAllAndOverride: Mock };
+
+  const build = (session: unknown) => {
+    const getSession = vi.fn().mockResolvedValue(session);
+    const authService = { api: { getSession } } as unknown as AuthService<AuthInstance>;
+    guard = new AuthGuard(reflector as unknown as Reflector, authService);
+  };
+
+  /** Marks metadata keys as present (as if the route carried their decorators). */
+  const withMetadata = (metadata: Record<string, unknown>) =>
+    reflector.getAllAndOverride.mockImplementation((key: string) => metadata[key]);
+
+  beforeEach(() => {
+    reflector = { getAllAndOverride: vi.fn().mockReturnValue(undefined) };
+    build(makeSession());
+  });
+
+  it("rejects anonymous access to a protected route", async () => {
+    build(null);
+
+    await expect(guard.canActivate(makeContext({ headers: {} }))).rejects.toMatchObject({
+      code: ErrorCode.UNAUTHORIZED,
+    });
+  });
+
+  it("allows @AllowAnonymous routes without a session", async () => {
+    withMetadata({ [ALLOW_ANONYMOUS_KEY]: true });
+    build(null);
+
+    await expect(guard.canActivate(makeContext({ headers: {} }))).resolves.toBe(true);
+  });
+
+  it("attaches the resolved session to the request", async () => {
+    const request: AnyRequest = { headers: {} };
+
+    await guard.canActivate(makeContext(request));
+
+    expect(request.user).toMatchObject({ id: "user-1" });
+  });
+
+  it("rejects an unverified email on @IsEmailVerified routes", async () => {
+    withMetadata({ [IS_EMAIL_VERIFIED_KEY]: true });
+    build(makeSession("user-1", { emailVerified: false }));
+
+    await expect(guard.canActivate(makeContext({ headers: {} }))).rejects.toMatchObject({
+      code: ErrorCode.EMAIL_NOT_VERIFIED,
+    });
+  });
+
+  it("rejects a user without any of the @Roles", async () => {
+    withMetadata({ [ROLES_KEY]: [UserRole.ADMIN] });
+
+    await expect(guard.canActivate(makeContext({ headers: {} }))).rejects.toMatchObject({
+      code: ErrorCode.INSUFFICIENT_ROLE,
+    });
+  });
+
+  it("allows a user holding one of the @Roles", async () => {
+    withMetadata({ [ROLES_KEY]: [UserRole.ADMIN] });
+    build(makeSession("user-1", { role: [UserRole.USER, UserRole.ADMIN] }));
+
+    await expect(guard.canActivate(makeContext({ headers: {} }))).resolves.toBe(true);
+  });
+});

package/template/apps/api/src/auth/auth.guard.ts

@@ -0,0 +1,97 @@
+import { HttpStatus, Injectable } from "@nestjs/common";
+import type { CanActivate, ExecutionContext } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { GqlExecutionContext } from "@nestjs/graphql";
+import { AuthService } from "@thallesp/nestjs-better-auth";
+import { fromNodeHeaders } from "better-auth/node";
+import type { AuthInstance } from "#src/auth/auth.js";
+import { ALLOW_ANONYMOUS_KEY } from "#src/auth/decorator/allow-anonymous.decorator.js";
+import { IS_EMAIL_VERIFIED_KEY } from "#src/auth/decorator/is-email-verified.decorator.js";
+import { ROLES_KEY } from "#src/auth/decorator/roles.decorator.js";
+import type { RequestWithSession, UserSession } from "#src/auth/types/auth.types.js";
+import { AppException } from "#src/errors/app.exception.js";
+import { ErrorCode } from "#src/errors/error-code.enum.js";
+import type { UserRole } from "#src/generated/prisma/client.js";
+
+/**
+ * Single global authentication + authorization guard.
+ *
+ * Better Auth's own global guard is disabled (`disableGlobalAuthGuard: true`),
+ * so this one guard both authenticates and authorizes — which guarantees
+ * authentication runs *before* the app-specific checks, instead of relying on
+ * the order two separate global guards happen to execute in.
+ *
+ * Flow:
+ *
+ * 1. Resolve the session and attach it — with the app's `customSession` fields —
+ *    to `request.session`/`request.user`.
+ * 2. `@AllowAnonymous()` routes stay reachable without a session (e.g. `/health`).
+ *    Every other route requires a session (401 otherwise).
+ * 3. Enforce email verification on `@IsEmailVerified()` routes.
+ * 4. Enforce role membership on `@Roles(...)` routes.
+ */
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly authService: AuthService<AuthInstance>,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = this.extractRequest(context);
+
+    const session = (await this.authService.api.getSession({
+      headers: fromNodeHeaders(request.headers),
+    })) as null | UserSession;
+    request.session = session;
+    request.user = session?.user ?? null;
+
+    if (this.requires(context, ALLOW_ANONYMOUS_KEY)) {
+      return true;
+    }
+
+    if (!session) {
+      throw new AppException(ErrorCode.UNAUTHORIZED, HttpStatus.UNAUTHORIZED);
+    }
+
+    if (this.requires(context, IS_EMAIL_VERIFIED_KEY) && !session.user.emailVerified) {
+      throw new AppException(ErrorCode.EMAIL_NOT_VERIFIED, HttpStatus.FORBIDDEN);
+    }
+
+    const requiredRoles = this.reflector.getAllAndOverride<undefined | UserRole[]>(ROLES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (requiredRoles?.length && !requiredRoles.some((role) => session.user.role.includes(role))) {
+      throw new AppException(ErrorCode.INSUFFICIENT_ROLE, HttpStatus.FORBIDDEN);
+    }
+
+    return true;
+  }
+
+  /**
+   * Extracts the request object from an HTTP or GraphQL execution context.
+   */
+  private extractRequest(context: ExecutionContext): RequestWithSession {
+    if (context.getType<"graphql" | "http">() === "graphql") {
+      return GqlExecutionContext.create(context).getContext<{
+        req: RequestWithSession;
+      }>().req;
+    }
+
+    const request = context.switchToHttp().getRequest<RequestWithSession | undefined>();
+    if (!request) {
+      throw new AppException(ErrorCode.REQUEST_CONTEXT_MISSING, HttpStatus.UNAUTHORIZED);
+    }
+    return request;
+  }
+
+  private requires(context: ExecutionContext, key: string): boolean {
+    return (
+      this.reflector.getAllAndOverride<boolean | undefined>(key, [
+        context.getHandler(),
+        context.getClass(),
+      ]) ?? false
+    );
+  }
+}

package/template/apps/api/src/auth/auth.ts

@@ -0,0 +1,129 @@
+import { randomUUID } from "node:crypto";
+import { passkey } from "@better-auth/passkey";
+import { prismaAdapter } from "better-auth/adapters/prisma";
+import { betterAuth } from "better-auth/minimal";
+import { customSession, oneTap } from "better-auth/plugins";
+import type { Prisma, PrismaClient } from "#src/generated/prisma/client.js";
+import type { MailService } from "#src/mail/mail.service.js";
+import type { PrismaService } from "#src/prisma/prisma.service.js";
+
+/**
+ * App fields merged onto the session user via the {@link customSession}
+ * plugin. Better Auth only returns its own core columns, so the app fields are
+ * selected explicitly here. Mirrors `SessionProfile` in `types/auth.types.ts`;
+ * keep them in sync.
+ */
+const USER_SESSION_SELECT = {
+  role: true,
+} satisfies Prisma.UserSelect;
+
+/**
+ * Google sign-in (button, One Tap, account linking) is on only when both
+ * credentials are set, so local dev and E2E runs work without a Google client.
+ */
+const googleProvider = () => {
+  const clientId = process.env.GOOGLE_CLIENT_ID?.trim();
+  const clientSecret = process.env.GOOGLE_CLIENT_SECRET?.trim();
+  return clientId && clientSecret ? { google: { clientId, clientSecret } } : undefined;
+};
+
+/**
+ * Shared better-auth configuration.
+ *
+ * Better Auth owns the Prisma `User`, `Session`, `Account` and `Verification`
+ * models. The prisma adapter resolves a model via `prisma[modelName]`, so the
+ * names must match the camelCase Prisma client accessors.
+ *
+ * @param prisma - Any PrismaClient-compatible instance (the NestJS PrismaService
+ *   at runtime, or a bare client for the better-auth CLI).
+ * @param allowedOrigins - Origins from the shared security/CORS configuration.
+ */
+export const buildBaseAuthOptions = (prisma: PrismaClient, allowedOrigins: string[]) => {
+  const cookieDomain = process.env.COOKIE_DOMAIN?.trim();
+  const baseURL = process.env.BETTER_AUTH_URL ?? "http://localhost:3001";
+  // Passkeys are bound to the registrable domain the web app runs on (the API sits on
+  // a subdomain), so the relying party is the cookie domain, not the API host.
+  const passkeyRpId = cookieDomain ? cookieDomain.replace(/^\./, "") : new URL(baseURL).hostname;
+  const google = googleProvider();
+
+  return {
+    account: {
+      // A Google sign-in with the email of an existing account links to it instead of failing.
+      accountLinking: { enabled: true, trustedProviders: ["google"] },
+    },
+    advanced: {
+      database: { generateId: () => randomUUID() },
+      ipAddress: { ipAddressHeaders: ["cf-connecting-ip", "x-forwarded-for"] },
+      ...(cookieDomain ? { crossSubDomainCookies: { domain: cookieDomain, enabled: true } } : {}),
+    },
+    baseURL,
+    database: prismaAdapter(prisma, { provider: "postgresql" }),
+    // E2E runs (NODE_ENV=test) skip the verification mail round-trip.
+    ...(process.env.NODE_ENV === "test"
+      ? {
+          databaseHooks: {
+            user: {
+              create: {
+                before: () => Promise.resolve({ data: { emailVerified: true } }),
+              },
+            },
+          },
+        }
+      : {}),
+    emailAndPassword: {
+      enabled: true,
+    },
+    emailVerification: {
+      autoSignInAfterVerification: true,
+    },
+    plugins: [
+      passkey({ origin: allowedOrigins, rpID: passkeyRpId, rpName: "Nexst" }),
+      oneTap(),
+      customSession(async ({ session, user }) => {
+        const profile = await prisma.user.findUnique({
+          select: USER_SESSION_SELECT,
+          where: { id: user.id },
+        });
+        return { session, user: { ...user, ...profile } };
+      }),
+    ],
+    secret: process.env.BETTER_AUTH_SECRET,
+    ...(google ? { socialProviders: google } : {}),
+    trustedOrigins: allowedOrigins,
+  } satisfies Parameters<typeof betterAuth>[0];
+};
+
+/**
+ * Builds the better-auth instance from the app's PrismaService.
+ *
+ * PrismaService extends PrismaClient, so it can be passed straight to the prisma
+ * adapter. This reuses the same connection pool, ConfigService-derived URL, and
+ * logging as the rest of the app instead of opening a second client.
+ *
+ * @param mail - The injected MailService used to deliver auth emails.
+ */
+export const createAuth = (prisma: PrismaService, allowedOrigins: string[], mail: MailService) => {
+  const options = buildBaseAuthOptions(prisma, allowedOrigins);
+
+  return betterAuth({
+    ...options,
+    emailAndPassword: {
+      ...options.emailAndPassword,
+      sendResetPassword: async ({ url, user }) => {
+        await mail.sendPasswordResetEmail(user.email, url);
+      },
+    },
+    emailVerification: {
+      ...options.emailVerification,
+      sendOnSignUp: true,
+      sendVerificationEmail: async ({ url, user }) => {
+        await mail.sendVerificationEmail(user.email, url);
+      },
+    },
+  });
+};
+
+/**
+ * Type of the configured better-auth instance, for injection sites.
+ */
+export type AuthInstance = ReturnType<typeof createAuth>;

package/template/apps/api/src/auth/decorator/allow-anonymous.decorator.ts

@@ -0,0 +1,17 @@
+import { SetMetadata } from "@nestjs/common";
+
+/**
+ * Metadata key that marks a route as public. Same `"PUBLIC"` string the library's
+ * `@AllowAnonymous()` uses; kept as a named constant here because the library
+ * does not export it and {@link AuthGuard} needs to read it.
+ */
+export const ALLOW_ANONYMOUS_KEY = "PUBLIC";
+
+/**
+ * Allows unauthenticated (anonymous) access to a route or controller.
+ *
+ * Local wrapper over the library's `@AllowAnonymous()` that sets
+ * {@link ALLOW_ANONYMOUS_KEY}. The library's own global guard is disabled
+ * (`disableGlobalAuthGuard: true`), so {@link AuthGuard} enforces this.
+ */
+export const AllowAnonymous = () => SetMetadata(ALLOW_ANONYMOUS_KEY, true);

package/template/apps/api/src/auth/decorator/is-email-verified.decorator.spec.ts

@@ -0,0 +1,41 @@
+import { Reflector } from "@nestjs/core";
+import {
+  IS_EMAIL_VERIFIED_KEY,
+  IsEmailVerified,
+} from "#src/auth/decorator/is-email-verified.decorator.js";
+
+describe("isEmailVerified", () => {
+  it("should set metadata to true", () => {
+    const decorator = IsEmailVerified();
+
+    class TestClass {
+      @decorator
+      testMethod() {
+        return "test";
+      }
+    }
+
+    const reflector = new Reflector();
+    const metadata = reflector.get(IS_EMAIL_VERIFIED_KEY, TestClass.prototype.testMethod);
+
+    expect(metadata).toBe(true);
+  });
+
+  it("should be usable as a method decorator", () => {
+    class TestController {
+      @IsEmailVerified()
+      testMethod() {
+        return "test";
+      }
+    }
+
+    const reflector = new Reflector();
+    const metadata = reflector.get(IS_EMAIL_VERIFIED_KEY, TestController.prototype.testMethod);
+
+    expect(metadata).toBe(true);
+  });
+
+  it("should have the correct metadata key", () => {
+    expect(IS_EMAIL_VERIFIED_KEY).toBe("auth:is-email-verified");
+  });
+});

package/template/apps/api/src/auth/decorator/is-email-verified.decorator.ts

@@ -0,0 +1,20 @@
+import { SetMetadata } from "@nestjs/common";
+
+export const IS_EMAIL_VERIFIED_KEY = "auth:is-email-verified";
+
+/**
+ * Decorator to require email verification for route access.
+ *
+ * When applied, the AuthGuard checks `session.user.emailVerified` from
+ * Better Auth and rejects the request if the email is not verified.
+ *
+ * @example
+ * ```typescript
+ * @IsEmailVerified()
+ * @Mutation(() => Boolean)
+ * publish(@Session() session: UserSession) {
+ *   ...
+ * }
+ * ```
+ */
+export const IsEmailVerified = () => SetMetadata(IS_EMAIL_VERIFIED_KEY, true);

package/template/apps/api/src/auth/decorator/roles.decorator.ts

@@ -0,0 +1,27 @@
+import { SetMetadata } from "@nestjs/common";
+import type { UserRole } from "#src/generated/prisma/client.js";
+
+/**
+ * Metadata key read by Better Auth's global AuthGuard to enforce role access.
+ * Mirrors the `@Roles()` decorator from `@thallesp/nestjs-better-auth`.
+ */
+export const ROLES_KEY = "ROLES";
+
+/**
+ * Restricts a route to users holding at least one of the given {@link UserRole}s.
+ * Roles are additive: a user matches if any of their roles is listed.
+ *
+ * A local wrapper over the library's `@Roles()`: it takes a variadic list of the
+ * Prisma {@link UserRole} enum (rather than a `string[]`) and sets the same
+ * `ROLES` metadata key. The library's own global guard is disabled
+ * (`disableGlobalAuthGuard: true`), so the check is enforced by our
+ * {@link AuthGuard}, which reads this key.
+ *
+ * @example
+ * ```typescript
+ * @Roles(UserRole.ADMIN)
+ * @Mutation(() => Boolean)
+ * purgeCache() { ... }
+ * ```
+ */
+export const Roles = (...roles: UserRole[]) => SetMetadata(ROLES_KEY, roles);

package/template/apps/api/src/auth/testing/make-session.ts

@@ -0,0 +1,31 @@
+import type { SessionUser, UserSession } from "#src/auth/types/auth.types.js";
+import { UserRole } from "#src/generated/prisma/client.js";
+
+/**
+ * Builds a fully populated {@link UserSession} for use in unit tests, mirroring
+ * what Better Auth's `customSession` plugin attaches to `request.session`.
+ *
+ * @param id - The authenticated user id.
+ * @param user - Overrides for the session user.
+ */
+export const makeSession = (id = "user-1", user: Partial<SessionUser> = {}): UserSession => ({
+  session: {
+    createdAt: new Date(0),
+    expiresAt: new Date(0),
+    id: "session-1",
+    token: "token-1",
+    updatedAt: new Date(0),
+    userId: id,
+  },
+  user: {
+    createdAt: new Date(0),
+    email: "test@example.com",
+    emailVerified: true,
+    id,
+    image: null,
+    name: "Test User",
+    role: [UserRole.USER],
+    updatedAt: new Date(0),
+    ...user,
+  },
+});