@yohangel / auth-nest

1.0.0 ▾

1.0.0

MIT

GitHub

Better Auth for NestJS: global auth guard with @AllowAnonymous, @OptionalAuth and @Session

Code3 filesContext~369 tokensscan passed

~369 tokens→ src/lib/auth-nest/AGENTS.md→ .cursor/rules/genpm-yohangel-auth-nest.mdc

This is exactly what your AI reads when it works in src/lib/auth-nest. Nothing else is added to its context.

@yohangel/auth-nest — rules for AI agents

Purpose

Connects @yohangel/auth to NestJS (Express platform) through @thallesp/nestjs-better-auth: Better Auth routes on /api/auth/* and a GLOBAL guard — every route requires a session unless marked otherwise.

Module map

index.ts — authModule(opts), and the decorators AllowAnonymous, OptionalAuth, Session, type UserSession, AuthGuard.

Integration (do this after installing)

main.ts: const app = await NestFactory.create(AppModule, { bodyParser: false }); (required).
app.module.ts: imports: [authModule({ sendEmail })].
Public routes: @AllowAnonymous() on the handler or controller. Optional session: @OptionalAuth().
Read the user: me(@Session() session: UserSession) { return session.user; }.
Fastify is not supported by this package; use the Express platform.

Conventions

Default-deny: new controllers are private automatically; mark public ones explicitly and review every @AllowAnonymous().
System roles need Better Auth's admin() plugin (createAuth({ plugins: [admin()] })) and @Roles(['admin']) from @thallesp/nestjs-better-auth; organization roles use @OrgRoles — never mix them.

Don't

Don't re-enable Nest's body parser globally (bodyParser: true): it breaks Better Auth.
Don't disable the global guard to "make it work"; add @AllowAnonymous() where intended.
Don't return the session token or session object to clients.

# @yohangel/auth-nest — rules for AI agents

## Purpose
Connects `@yohangel/auth` to NestJS (Express platform) through `@thallesp/nestjs-better-auth`: Better Auth routes on `/api/auth/*` and a GLOBAL guard — every route requires a session unless marked otherwise.

## Module map
- `index.ts` — `authModule(opts)`, and the decorators `AllowAnonymous`, `OptionalAuth`, `Session`, type `UserSession`, `AuthGuard`.

## Integration (do this after installing)
1. `main.ts`: `const app = await NestFactory.create(AppModule, { bodyParser: false });` (required).
2. `app.module.ts`: `imports: [authModule({ sendEmail })]`.
3. Public routes: `@AllowAnonymous()` on the handler or controller. Optional session: `@OptionalAuth()`.
4. Read the user: `me(@Session() session: UserSession) { return session.user; }`.
5. Fastify is not supported by this package; use the Express platform.

## Conventions
- Default-deny: new controllers are private automatically; mark public ones explicitly and review every `@AllowAnonymous()`.
- System roles need Better Auth's `admin()` plugin (`createAuth({ plugins: [admin()] })`) and `@Roles(['admin'])` from `@thallesp/nestjs-better-auth`; organization roles use `@OrgRoles` — never mix them.

## Don't
- Don't re-enable Nest's body parser globally (`bodyParser: true`): it breaks Better Auth.
- Don't disable the global guard to "make it work"; add `@AllowAnonymous()` where intended.
- Don't return the session token or `session` object to clients.

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/auth-nest/index.tsread-only · 7145b9d

// @yohangel/auth-nest — Better Auth en NestJS (plataforma Express) vía @thallesp/nestjs-better-auth.
// Registra un AuthGuard GLOBAL: toda ruta exige sesión salvo @AllowAnonymous() u @OptionalAuth().
// main.ts: `NestFactory.create(AppModule, { bodyParser: false })` (Better Auth lee el cuerpo; el módulo vuelve a
// activar json/urlencoded para el resto de rutas).
import { AuthModule } from '@thallesp/nestjs-better-auth';
import { type CreateAuthOptions, createAuth } from '../auth/index.js';

/** `imports: [authModule()]` en tu AppModule. */
export function authModule(opts: CreateAuthOptions = {}) {
  return AuthModule.forRoot({ auth: createAuth(opts) });
}

export {
  AllowAnonymous,
  AuthGuard,
  OptionalAuth,
  Session,
  type UserSession,
} from '@thallesp/nestjs-better-auth';