better-ts-stack 2.1.1 → 2.2.0

package/templates/modules/auth/express/config.json

@@ -1,20 +1,21 @@
 {
   "id": "auth",
-  "name": "JWT Auth",
-  "description": "JWT authentication with bcrypt password hashing",
+  "name": "Better Auth",
+  "description": "Better Auth for Express: email and password, email verification, password reset, GitHub and Google sign-in, and bearer tokens",
   "type": "feature",
   "dependencies": {
-    "bcrypt": "^6.0.0",
-    "jsonwebtoken": "^9.0.3",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {
-    "@types/bcrypt": "^6.0.0",
-    "@types/jsonwebtoken": "^9.0.10"
+    "better-auth": "^1.7.18"
   },
+  "devDependencies": {},
   "scripts": {},
   "envVars": {
-    "JWT_SECRET": "please-change-me",
-    "JWT_EXPIRES_IN": "1h"
+    "BETTER_AUTH_SECRET": "please-change-me-to-a-random-string",
+    "BETTER_AUTH_URL": "http://localhost:3000",
+    "GITHUB_CLIENT_ID": "",
+    "GITHUB_CLIENT_SECRET": "",
+    "GOOGLE_CLIENT_ID": "",
+    "GOOGLE_CLIENT_SECRET": "",
+    "RESEND_API_KEY": "",
+    "EMAIL_FROM": "onboarding@resend.dev"
   }
 }

package/templates/modules/auth/express/src/lib/auth.ts.hbs

@@ -0,0 +1,143 @@
+import { betterAuth } from "better-auth";
+{{#if (eq database 'none')}}
+import { memoryAdapter } from "better-auth/adapters/memory";
+{{/if}}
+{{#if (eq database 'prisma')}}
+import { prismaAdapter } from "better-auth/adapters/prisma";
+{{/if}}
+{{#if (eq database 'drizzle')}}
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+{{/if}}
+{{#if (eq database 'mongoose')}}
+import { mongodbAdapter } from "better-auth/adapters/mongodb";
+import { MongoClient } from "mongodb";
+{{/if}}
+import { bearer } from "better-auth/plugins";
+
+import { env } from "../env";
+{{#if (eq database 'drizzle')}}
+import { db } from "./db";
+{{/if}}
+import { sendEmail } from "./email";
+{{#if (eq database 'prisma')}}
+import { prisma } from "./prisma";
+{{/if}}
+
+{{#if (eq database 'none')}}
+// In-memory store for trying the API out: users and sessions are lost on
+// restart, so add a database before going to production
+const memoryDb = { user: [], session: [], account: [], verification: [] };
+
+{{/if}}
+{{#if (eq database 'mongoose')}}
+// Better Auth talks to MongoDB through the driver, next to Mongoose
+export const mongoClient = new MongoClient(env.MONGODB_URI);
+
+{{/if}}
+// Reports a failed email instead of failing the request: the sign-up or reset
+// already happened, and the user can ask for the email again
+function deliver(email: Parameters<typeof sendEmail>[0]): void {
+  sendEmail(email).catch((error: unknown) => {
+    console.error(`Could not send "${email.subject}" to ${email.to}:`, error);
+  });
+}
+
+// Points a verification link at the API itself when the client gave no page
+// to return to, so opening it answers with JSON instead of a redirect to "/"
+function withoutDefaultCallback(url: string): string {
+  const link = new URL(url);
+  if (link.searchParams.get("callbackURL") === "/") {
+    link.searchParams.delete("callbackURL");
+  }
+  return link.toString();
+}
+
+export const auth = betterAuth({
+  {{#if (eq database 'none')}}
+  database: memoryAdapter(memoryDb),
+  {{/if}}
+  {{#if (eq database 'prisma')}}
+  database: prismaAdapter(prisma, { provider: "postgresql" }),
+  {{/if}}
+  {{#if (eq database 'drizzle')}}
+  database: drizzleAdapter(db, { provider: "pg" }),
+  {{/if}}
+  {{#if (eq database 'mongoose')}}
+  // Without the client, writes run without transactions, which a standalone
+  // MongoDB server (no replica set) does not support
+  database: mongodbAdapter(mongoClient.db()),
+  {{/if}}
+  secret: env.BETTER_AUTH_SECRET,
+  baseURL: env.BETTER_AUTH_URL,
+  // Browser apps on these origins may call the auth routes with cookies
+  trustedOrigins: typeof env.CORS_ORIGIN === "string" ? [] : env.CORS_ORIGIN,
+  emailAndPassword: {
+    enabled: true,
+    // Set to true to block sign-in until the email address is verified
+    requireEmailVerification: false,
+    // A reset signs the user out everywhere
+    revokeSessionsOnPasswordReset: true,
+    sendResetPassword: ({ user, url, token }) => {
+      deliver({
+        to: user.email,
+        subject: "Reset your password",
+        text: `Open this link to choose a new password:\n${url}\n\nOr send this token to POST /api/auth/reset-password: ${token}`,
+      });
+      return Promise.resolve();
+    },
+  },
+  emailVerification: {
+    sendOnSignUp: true,
+    autoSignInAfterVerification: true,
+    sendVerificationEmail: ({ user, url }) => {
+      deliver({
+        to: user.email,
+        subject: "Verify your email address",
+        text: `Open this link to verify your email address:\n${withoutDefaultCallback(url)}`,
+      });
+      return Promise.resolve();
+    },
+  },
+  // Each provider is turned on once its client ID and secret are set
+  socialProviders: {
+    ...(env.GITHUB_CLIENT_ID && env.GITHUB_CLIENT_SECRET
+      ? {
+          github: {
+            clientId: env.GITHUB_CLIENT_ID,
+            clientSecret: env.GITHUB_CLIENT_SECRET,
+          },
+        }
+      : {}),
+    ...(env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET
+      ? {
+          google: {
+            clientId: env.GOOGLE_CLIENT_ID,
+            clientSecret: env.GOOGLE_CLIENT_SECRET,
+          },
+        }
+      : {}),
+  },
+  // Clients without cookies send "Authorization: Bearer <token>"; the token
+  // comes back in the set-auth-token header of sign-in and sign-up
+  plugins: [bearer()],
+  {{#if useRateLimit}}
+  // Sign-up, sign-in, and password reset: 10 attempts per client IP in 15
+  // minutes, against password guessing
+  rateLimit: {
+    enabled: true,
+    window: 15 * 60,
+    max: 100,
+    customRules: {
+      "/sign-in/*": { window: 15 * 60, max: 10 },
+      "/sign-up/*": { window: 15 * 60, max: 10 },
+      "/request-password-reset": { window: 15 * 60, max: 10 },
+    },
+  },
+  {{/if}}
+  advanced: {
+    // Set by the server from req.ip on every request (see index.ts)
+    ipAddress: { ipAddressHeaders: ["x-client-ip"] },
+  },
+});
+
+export type Session = typeof auth.$Infer.Session;

package/templates/modules/auth/express/src/lib/email.ts

@@ -0,0 +1,37 @@
+import { env } from "../env";
+
+interface Email {
+  to: string;
+  subject: string;
+  text: string;
+}
+
+if (!env.RESEND_API_KEY && process.env.NODE_ENV === "production") {
+  console.warn(
+    "RESEND_API_KEY is not set: emails are printed to the log instead of sent"
+  );
+}
+
+// Sends through Resend when RESEND_API_KEY is set. Without it the email is
+// printed, so verification and reset links can be copied from the terminal
+export async function sendEmail({ to, subject, text }: Email): Promise<void> {
+  if (!env.RESEND_API_KEY) {
+    console.log(`\n--- Email to ${to}: ${subject}\n${text}\n---\n`);
+    return;
+  }
+
+  const response = await fetch("https://api.resend.com/emails", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${env.RESEND_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ from: env.EMAIL_FROM, to, subject, text }),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Resend rejected the email (${response.status}): ${await response.text()}`
+    );
+  }
+}

package/templates/modules/auth/express/src/middleware/requireAuth.ts

@@ -0,0 +1,29 @@
+import { fromNodeHeaders } from "better-auth/node";
+import type { NextFunction, Request, Response } from "express";
+
+import { auth, type Session } from "../lib/auth";
+
+// Accepts a session cookie or an "Authorization: Bearer <token>" header and
+// stores the session in res.locals.session; answers 401 without one
+export function requireAuth(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void {
+  auth.api
+    .getSession({ headers: fromNodeHeaders(req.headers) })
+    .then((session) => {
+      if (!session) {
+        res.status(401).json({ error: "Unauthorized" });
+        return;
+      }
+      res.locals.session = session;
+      next();
+    })
+    .catch(next);
+}
+
+// The session requireAuth stored, for handlers that run after it
+export function getSession(res: Response): Session {
+  return res.locals.session as Session;
+}

package/templates/modules/auth/express/src/routes/me.ts

@@ -0,0 +1,13 @@
+import { Request, Response, Router } from "express";
+
+import { getSession, requireAuth } from "../middleware/requireAuth";
+
+const router: Router = Router();
+
+// Example of a protected route: returns the signed-in user
+router.get("/", requireAuth, (_req: Request, res: Response) => {
+  const { user, session } = getSession(res);
+  res.status(200).json({ user, session: { expiresAt: session.expiresAt } });
+});
+
+export default router;

package/templates/modules/auth/nestjs/config.json

@@ -1,20 +1,22 @@
 {
   "id": "auth",
-  "name": "JWT Auth",
-  "description": "JWT authentication for NestJS with bcrypt password hashing",
+  "name": "Better Auth",
+  "description": "Better Auth for NestJS: email and password, email verification, password reset, GitHub and Google sign-in, and bearer tokens",
   "type": "feature",
   "dependencies": {
-    "bcrypt": "^6.0.0",
-    "jsonwebtoken": "^9.0.3",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {
-    "@types/bcrypt": "^6.0.0",
-    "@types/jsonwebtoken": "^9.0.10"
+    "@thallesp/nestjs-better-auth": "^2.8.0",
+    "better-auth": "^1.7.18"
   },
+  "devDependencies": {},
   "scripts": {},
   "envVars": {
-    "JWT_SECRET": "please-change-me",
-    "JWT_EXPIRES_IN": "1h"
+    "BETTER_AUTH_SECRET": "please-change-me-to-a-random-string",
+    "BETTER_AUTH_URL": "http://localhost:3000",
+    "GITHUB_CLIENT_ID": "",
+    "GITHUB_CLIENT_SECRET": "",
+    "GOOGLE_CLIENT_ID": "",
+    "GOOGLE_CLIENT_SECRET": "",
+    "RESEND_API_KEY": "",
+    "EMAIL_FROM": "onboarding@resend.dev"
   }
 }

package/templates/modules/auth/nestjs/src/auth/auth.module.ts.hbs

@@ -1,22 +1,72 @@
-import { Module } from "@nestjs/common";
 {{#if (eq database 'mongoose')}}
-import { MongooseModule } from "@nestjs/mongoose";
+import {
+  Injectable,
+  Module,
+  type OnApplicationShutdown,
+} from "@nestjs/common";
+{{/if}}
+import { AuthModule as BetterAuthModule } from "@thallesp/nestjs-better-auth";
+import type { Request, Response } from "express";
+{{#if (eq database 'mongoose')}}
+import { MongoClient } from "mongodb";
 {{/if}}
 
+{{#if (eq database 'drizzle')}}
+import { type Database, DRIZZLE } from "../database/database.module.js";
+{{/if}}
 {{#if (eq database 'mongoose')}}
-import { User, UserSchema } from "../users/user.schema.js";
+import { env } from "../env.js";
 {{/if}}
-import { AuthController } from "./auth.controller.js";
-import { AuthService } from "./auth.service.js";
-import { UsersService } from "./users.service.js";
+{{#if (eq database 'prisma')}}
+import { PrismaService } from "../prisma/prisma.service.js";
+{{/if}}
+import { createAuth } from "./auth.js";
+
+{{#if (eq database 'mongoose')}}
+// Better Auth talks to MongoDB through the driver, next to Mongoose
+const mongoClient = new MongoClient(env.MONGODB_URI);
 
-@Module({
+@Injectable()
+class MongoClientShutdown implements OnApplicationShutdown {
+  onApplicationShutdown(): Promise<void> {
+    return mongoClient.close();
+  }
+}
+
+@Module({ providers: [MongoClientShutdown] })
+class MongoClientModule {}
+
+{{/if}}
+// Mounts Better Auth on /api/auth and protects every other route: add
+// @AllowAnonymous() to a controller or route that should stay public
+export const AuthModule = BetterAuthModule.forRootAsync({
+  {{#if (eq database 'prisma')}}
+  inject: [PrismaService],
+  useFactory: (prisma: PrismaService) => ({
+    auth: createAuth(prisma),
+  {{/if}}
+  {{#if (eq database 'drizzle')}}
+  inject: [DRIZZLE],
+  useFactory: (db: Database) => ({
+    auth: createAuth(db),
+  {{/if}}
   {{#if (eq database 'mongoose')}}
-  imports: [
-    MongooseModule.forFeature([{ name: User.name, schema: UserSchema }]),
-  ],
+  imports: [MongoClientModule],
+  useFactory: () => ({
+    auth: createAuth(mongoClient.db()),
+  {{/if}}
+  {{#if (eq database 'none')}}
+  useFactory: () => ({
+    auth: createAuth(),
   {{/if}}
-  controllers: [AuthController],
-  providers: [AuthService, UsersService],
-})
-export class AuthModule {}
+    // CORS stays with app.enableCors() in main.ts, which reads CORS_ORIGIN
+    disableTrustedOriginsCors: true,
+    // Better Auth reads the client IP for its rate limits from this header. It
+    // is set from req.ip on every request, so a client cannot pick its own
+    // value. Behind a reverse proxy, enable "trust proxy" for the real client IP
+    middleware: (req: Request, _res: Response, next: () => void) => {
+      req.headers["x-client-ip"] = req.ip;
+      next();
+    },
+  }),
+});

package/templates/modules/auth/nestjs/src/auth/auth.ts.hbs

@@ -0,0 +1,152 @@
+import { betterAuth } from "better-auth";
+{{#if (eq database 'none')}}
+import { memoryAdapter } from "better-auth/adapters/memory";
+{{/if}}
+{{#if (eq database 'prisma')}}
+import { prismaAdapter } from "better-auth/adapters/prisma";
+{{/if}}
+{{#if (eq database 'drizzle')}}
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+{{/if}}
+{{#if (eq database 'mongoose')}}
+import { mongodbAdapter } from "better-auth/adapters/mongodb";
+{{/if}}
+import { bearer } from "better-auth/plugins";
+{{#if (eq database 'mongoose')}}
+import type { Db } from "mongodb";
+{{/if}}
+
+{{#if (eq database 'drizzle')}}
+import type { Database } from "../database/database.module.js";
+{{/if}}
+import { env } from "../env.js";
+{{#if (eq database 'prisma')}}
+import type { PrismaService } from "../prisma/prisma.service.js";
+{{/if}}
+import { sendEmail } from "./email.js";
+
+{{#if (eq database 'none')}}
+// In-memory store for trying the API out: users and sessions are lost on
+// restart, so add a database before going to production
+const memoryDb = { user: [], session: [], account: [], verification: [] };
+
+{{/if}}
+// Reports a failed email instead of failing the request: the sign-up or reset
+// already happened, and the user can ask for the email again
+function deliver(email: Parameters<typeof sendEmail>[0]): void {
+  sendEmail(email).catch((error: unknown) => {
+    console.error(`Could not send "${email.subject}" to ${email.to}:`, error);
+  });
+}
+
+// Points a verification link at the API itself when the client gave no page
+// to return to, so opening it answers with JSON instead of a redirect to "/"
+function withoutDefaultCallback(url: string): string {
+  const link = new URL(url);
+  if (link.searchParams.get("callbackURL") === "/") {
+    link.searchParams.delete("callbackURL");
+  }
+  return link.toString();
+}
+
+// Builds the Better Auth server; auth.module.ts calls it with the database
+{{#if (eq database 'none')}}
+export function createAuth() {
+{{/if}}
+{{#if (eq database 'prisma')}}
+export function createAuth(prisma: PrismaService) {
+{{/if}}
+{{#if (eq database 'drizzle')}}
+export function createAuth(db: Database) {
+{{/if}}
+{{#if (eq database 'mongoose')}}
+export function createAuth(db: Db) {
+{{/if}}
+  return betterAuth({
+    {{#if (eq database 'none')}}
+    database: memoryAdapter(memoryDb),
+    {{/if}}
+    {{#if (eq database 'prisma')}}
+    database: prismaAdapter(prisma, { provider: "postgresql" }),
+    {{/if}}
+    {{#if (eq database 'drizzle')}}
+    database: drizzleAdapter(db, { provider: "pg" }),
+    {{/if}}
+    {{#if (eq database 'mongoose')}}
+    // Without the client, writes run without transactions, which a standalone
+    // MongoDB server (no replica set) does not support
+    database: mongodbAdapter(db),
+    {{/if}}
+    secret: env.BETTER_AUTH_SECRET,
+    baseURL: env.BETTER_AUTH_URL,
+    // Browser apps on these origins may call the auth routes with cookies
+    trustedOrigins: typeof env.CORS_ORIGIN === "string" ? [] : env.CORS_ORIGIN,
+    emailAndPassword: {
+      enabled: true,
+      // Set to true to block sign-in until the email address is verified
+      requireEmailVerification: false,
+      // A reset signs the user out everywhere
+      revokeSessionsOnPasswordReset: true,
+      sendResetPassword: ({ user, url, token }) => {
+        deliver({
+          to: user.email,
+          subject: "Reset your password",
+          text: `Open this link to choose a new password:\n${url}\n\nOr send this token to POST /api/auth/reset-password: ${token}`,
+        });
+        return Promise.resolve();
+      },
+    },
+    emailVerification: {
+      sendOnSignUp: true,
+      autoSignInAfterVerification: true,
+      sendVerificationEmail: ({ user, url }) => {
+        deliver({
+          to: user.email,
+          subject: "Verify your email address",
+          text: `Open this link to verify your email address:\n${withoutDefaultCallback(url)}`,
+        });
+        return Promise.resolve();
+      },
+    },
+    // Each provider is turned on once its client ID and secret are set
+    socialProviders: {
+      ...(env.GITHUB_CLIENT_ID && env.GITHUB_CLIENT_SECRET
+        ? {
+            github: {
+              clientId: env.GITHUB_CLIENT_ID,
+              clientSecret: env.GITHUB_CLIENT_SECRET,
+            },
+          }
+        : {}),
+      ...(env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET
+        ? {
+            google: {
+              clientId: env.GOOGLE_CLIENT_ID,
+              clientSecret: env.GOOGLE_CLIENT_SECRET,
+            },
+          }
+        : {}),
+    },
+    // Clients without cookies send "Authorization: Bearer <token>"; the token
+    // comes back in the set-auth-token header of sign-in and sign-up
+    plugins: [bearer()],
+    {{#if useRateLimit}}
+    // Sign-up, sign-in, and password reset: 10 attempts per client IP in 15
+    // minutes, against password guessing
+    rateLimit: {
+      enabled: true,
+      window: 15 * 60,
+      max: 100,
+      customRules: {
+        "/sign-in/*": { window: 15 * 60, max: 10 },
+        "/sign-up/*": { window: 15 * 60, max: 10 },
+        "/request-password-reset": { window: 15 * 60, max: 10 },
+      },
+    },
+    {{/if}}
+    advanced: {
+      // Set from req.ip on every request (see auth.module.ts)
+      ipAddress: { ipAddressHeaders: ["x-client-ip"] },
+    },
+  });
+}

package/templates/modules/auth/nestjs/src/auth/email.ts

@@ -0,0 +1,37 @@
+import { env } from "../env.js";
+
+interface Email {
+  to: string;
+  subject: string;
+  text: string;
+}
+
+if (!env.RESEND_API_KEY && process.env.NODE_ENV === "production") {
+  console.warn(
+    "RESEND_API_KEY is not set: emails are printed to the log instead of sent"
+  );
+}
+
+// Sends through Resend when RESEND_API_KEY is set. Without it the email is
+// printed, so verification and reset links can be copied from the terminal
+export async function sendEmail({ to, subject, text }: Email): Promise<void> {
+  if (!env.RESEND_API_KEY) {
+    console.log(`\n--- Email to ${to}: ${subject}\n${text}\n---\n`);
+    return;
+  }
+
+  const response = await fetch("https://api.resend.com/emails", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${env.RESEND_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ from: env.EMAIL_FROM, to, subject, text }),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Resend rejected the email (${response.status}): ${await response.text()}`
+    );
+  }
+}

package/templates/modules/auth/nestjs/src/me/me.controller.ts

@@ -0,0 +1,15 @@
+import { Controller, Get } from "@nestjs/common";
+import { Session, type UserSession } from "@thallesp/nestjs-better-auth";
+
+// Example of a protected route: the global auth guard answers 401 without a
+// session cookie or an "Authorization: Bearer <token>" header
+@Controller("api/me")
+export class MeController {
+  @Get()
+  me(@Session() { user, session }: UserSession): {
+    user: UserSession["user"];
+    session: { expiresAt: Date };
+  } {
+    return { user, session: { expiresAt: session.expiresAt } };
+  }
+}

package/templates/modules/auth/nextjs/app/api/auth/[...all]/route.ts

@@ -1,4 +1,4 @@
-import { auth } from "@/lib/auth";
-import { toNextJsHandler } from "better-auth/next-js";
-
-export const { GET, POST } = toNextJsHandler(auth);
+import { auth } from "@/lib/auth";
+import { toNextJsHandler } from "better-auth/next-js";
+
+export const { GET, POST } = toNextJsHandler(auth);