Labxus Auth Multitenant con RLS, Next.js, NestJS, PostgreSQL, Drizzle, Zod y TypeScript

1. Stack obligatorio

Gestor de paquetes

Usar obligatoriamente:

pnpm
No usar npm.
No usar yarn.
No usar bun.
Todos los comandos deben estar escritos con pnpm.
El monorepo debe usar pnpm-workspace.yaml.

Lenguaje

Usar obligatoriamente:

TypeScript en todo el proyecto
TypeScript en frontend.
TypeScript en backend.
TypeScript en package compartido.
TypeScript en scripts de seed.
TypeScript en configuración cuando sea posible.
No usar JavaScript plano salvo archivos estrictamente necesarios generados por herramientas.

2. Versiones obligatorias

Usar estas versiones o rangos específicos:

Frontend

Next.js v16.2.x
React compatible con Next.js v16.2.x
TypeScript en última versión estable compatible
Tailwind CSS v4.1
Shadcn UI compatible con Tailwind v4
React Hook Form
Zod
TanStack Query, si aplica

Backend

NestJS v11.1.19
TypeScript
PostgreSQL
Drizzle ORM siguiendo la guía oficial para PostgreSQL con pnpm
Bcrypt
JWT
Helmet
CORS
Rate limiting

ORM

Usar:

Drizzle ORM
drizzle-kit
PostgreSQL con pg / node-postgres
Configuración basada en la guía oficial: https://orm.drizzle.team/docs/get-started/postgresql-new

Instalación esperada con pnpm:

pnpm add drizzle-orm pg
pnpm add -D drizzle-kit @types/pg

3. Stack técnico final

Frontend

Next.js v16.2.x con App Router
TypeScript
Tailwind CSS v4.1
Shadcn UI
React Hook Form
Zod
TanStack Query, si aplica
Fetch wrapper propio o Axios
Variables CSS con HSL
Modo claro y modo oscuro
Arquitectura limpia, escalable y fácil de mantener

Backend

NestJS v11.1.19
TypeScript
PostgreSQL
Drizzle ORM
Zod para validaciones compartidas
JWT Access Token
Refresh Token
Bcrypt para contraseñas
Helmet
CORS configurado correctamente
Rate limiting
Arquitectura modular

Base de datos

PostgreSQL
Drizzle ORM
Multitenant usando company_id
PostgreSQL Row Level Security, RLS
Migraciones con Drizzle
Seeds iniciales

Arquitectura

Monolito modular
Monorepo con pnpm
NO microservicios
NO Firebase
NO MongoDB
NO Prisma
NO Supabase Auth
NO Clerk
NO Auth0
NO NextAuth
Package compartido para Zod, types, constantes, roles y permisos

4. Arquitectura general esperada

Crear una arquitectura tipo monorepo:

labxus-platform/
├── apps/
│   ├── web/                 # Frontend Next.js v16.2.x
│   └── api/                 # Backend NestJS v11.1.19
│
├── packages/
│   ├── shared/              # Zod schemas, types, roles, permisos
│   ├── ui/                  # Opcional: componentes compartidos
│   └── config/              # Configuración compartida
│
├── package.json
├── pnpm-workspace.yaml
├── turbo.json
├── README.md
└── .gitignore

Usar preferiblemente:

pnpm
Turborepo, si aplica
TypeScript en todo el proyecto

5. package.json raíz esperado

Crear un package.json raíz parecido a este:

{
  "name": "labxus-platform",
  "version": "0.1.0",
  "private": true,
  "packageManager": "pnpm@latest",
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "lint": "turbo lint",
    "typecheck": "turbo typecheck",
    "format": "prettier --write .",
    "db:generate": "pnpm --filter @labxus/api db:generate",
    "db:migrate": "pnpm --filter @labxus/api db:migrate",
    "db:studio": "pnpm --filter @labxus/api db:studio",
    "db:seed": "pnpm --filter @labxus/api db:seed"
  },
  "devDependencies": {
    "turbo": "latest",
    "typescript": "latest",
    "prettier": "latest"
  }
}

6. pnpm-workspace.yaml esperado

Crear:

packages:
  - "apps/*"
  - "packages/*"

7. Modelo de negocio y reglas principales

La plataforma será SaaS multitenant.

Reglas obligatorias:

Yo, como dueño de Labxus, soy el único que puede crear empresas nuevas.
Para crear empresas nuevas debo iniciar sesión como SUPER_ADMIN.
Las empresas NO pueden registrarse públicamente.
No debe existir formulario público para registrar empresas.
Cada empresa puede crear usuarios internos solo dentro de su propia empresa.
Cada empresa puede crear roles internos solo dentro de su propia empresa.
Cada empresa puede asignar permisos permitidos a sus propios roles.
Los usuarios de una empresa no pueden ver, crear, editar ni eliminar datos de otra empresa.
Cada usuario pertenece a una empresa mediante company_id, excepto el SUPER_ADMIN, que puede tener company_id nulo.
El SUPER_ADMIN de Labxus puede ver y administrar todas las empresas.
El COMPANY_ADMIN solo puede administrar usuarios, roles y permisos de su propia empresa.
Los usuarios normales no pueden administrar usuarios ni roles, a menos que tengan permisos específicos.
El backend nunca debe confiar en el company_id enviado desde el frontend para usuarios normales.
El company_id debe obtenerse desde el token del usuario autenticado.
PostgreSQL debe reforzar el aislamiento con Row Level Security.

8. Módulos iniciales a construir

Crear los siguientes módulos:

auth
companies
users
roles
permissions
database
common

Estructura esperada en backend:

apps/api/src/
├── app.module.ts
├── main.ts
├── config/
│   ├── env.schema.ts
│   └── config.module.ts
│
├── database/
│   ├── db.ts
│   ├── database.module.ts
│   ├── drizzle.config.ts
│   ├── schema/
│   │   ├── companies.schema.ts
│   │   ├── users.schema.ts
│   │   ├── roles.schema.ts
│   │   ├── permissions.schema.ts
│   │   ├── role-permissions.schema.ts
│   │   ├── refresh-tokens.schema.ts
│   │   ├── password-reset-tokens.schema.ts
│   │   ├── modules.schema.ts
│   │   ├── company-modules.schema.ts
│   │   └── audit-logs.schema.ts
│   ├── migrations/
│   └── seed.ts
│
├── common/
│   ├── decorators/
│   │   ├── current-user.decorator.ts
│   │   ├── require-roles.decorator.ts
│   │   └── require-permissions.decorator.ts
│   │
│   ├── guards/
│   │   ├── jwt-auth.guard.ts
│   │   ├── roles.guard.ts
│   │   ├── permissions.guard.ts
│   │   └── tenant.guard.ts
│   │
│   ├── filters/
│   ├── interceptors/
│   ├── pipes/
│   ├── utils/
│   └── types/
│
├── auth/
│   ├── auth.module.ts
│   ├── auth.controller.ts
│   ├── auth.service.ts
│   ├── auth.repository.ts
│   ├── strategies/
│   └── dto/
│
├── companies/
│   ├── companies.module.ts
│   ├── companies.controller.ts
│   ├── companies.service.ts
│   ├── companies.repository.ts
│   └── dto/
│
├── users/
│   ├── users.module.ts
│   ├── users.controller.ts
│   ├── users.service.ts
│   ├── users.repository.ts
│   └── dto/
│
├── roles/
│   ├── roles.module.ts
│   ├── roles.controller.ts
│   ├── roles.service.ts
│   ├── roles.repository.ts
│   └── dto/
│
└── permissions/
    ├── permissions.module.ts
    ├── permissions.controller.ts
    ├── permissions.service.ts
    ├── permissions.repository.ts
    └── dto/

9. Package compartido

Crear un package compartido:

packages/shared/
├── src/
│   ├── schemas/
│   │   ├── auth.schema.ts
│   │   ├── company.schema.ts
│   │   ├── user.schema.ts
│   │   ├── role.schema.ts
│   │   ├── permission.schema.ts
│   │   └── common.schema.ts
│   │
│   ├── types/
│   │   ├── auth.types.ts
│   │   ├── company.types.ts
│   │   ├── user.types.ts
│   │   ├── role.types.ts
│   │   ├── permission.types.ts
│   │   └── common.types.ts
│   │
│   ├── constants/
│   │   ├── roles.ts
│   │   ├── permissions.ts
│   │   ├── modules.ts
│   │   └── statuses.ts
│   │
│   └── index.ts
│
├── package.json
└── tsconfig.json

Este package debe usarse tanto en:

Frontend Next.js
Backend NestJS

Reglas:

Las validaciones deben estar en Zod.
Los types deben inferirse desde Zod usando z.infer.
No duplicar validaciones entre frontend y backend.
No duplicar constantes de roles y permisos.
El frontend debe importar los schemas para validar formularios.
El backend debe importar los schemas para validar request body.

10. Zod schemas compartidos

Crear schemas para:

Auth

loginSchema
forgotPasswordSchema
resetPasswordSchema
refreshTokenSchema

Companies

createCompanySchema
updateCompanySchema
companyStatusSchema

Users

createUserSchema
updateUserSchema
userStatusSchema
changePasswordSchema

Roles

createRoleSchema
updateRoleSchema
assignPermissionsToRoleSchema

Permissions

permissionSchema
permissionCodeSchema

Reglas de password

La contraseña debe cumplir:

Mínimo 8 caracteres
Al menos una mayúscula
Al menos una minúscula
Al menos un número
Al menos un símbolo

11. Roles base

Crear constantes compartidas para roles:

SUPER_ADMIN
COMPANY_ADMIN
MANAGER
EMPLOYEE
READ_ONLY

Reglas:

SUPER_ADMIN pertenece a Labxus.
SUPER_ADMIN puede crear empresas.
SUPER_ADMIN puede ver todas las empresas.
SUPER_ADMIN puede administrar módulos globales.
SUPER_ADMIN puede crear usuarios administradores de empresa.
COMPANY_ADMIN administra solo su empresa.
COMPANY_ADMIN no puede crear otros SUPER_ADMIN.
COMPANY_ADMIN no puede modificar empresas globalmente.
MANAGER puede tener permisos administrativos limitados.
EMPLOYEE puede operar módulos permitidos.
READ_ONLY solo puede consultar información.

12. Permisos base

Crear constantes compartidas para permisos:

companies.create
companies.read
companies.update
companies.delete

users.create
users.read
users.update
users.delete

roles.create
roles.read
roles.update
roles.delete

permissions.read
permissions.assign

dashboard.read

settings.read
settings.update

Preparar también permisos futuros para módulos:

inventory.create
inventory.read
inventory.update
inventory.delete

warehouses.create
warehouses.read
warehouses.update
warehouses.delete

orders.create
orders.read
orders.update
orders.delete

customers.create
customers.read
customers.update
customers.delete

invoicing.create
invoicing.read
invoicing.update
invoicing.delete

employees.create
employees.read
employees.update
employees.delete

payroll.create
payroll.read
payroll.update
payroll.delete

13. Base de datos con Drizzle ORM

Crear schemas de Drizzle para las siguientes tablas:

companies
users
roles
permissions
role_permissions
refresh_tokens
password_reset_tokens
audit_logs
modules
company_modules

Usar Drizzle ORM con PostgreSQL y pg.

Instalación esperada en apps/api:

pnpm add drizzle-orm pg
pnpm add -D drizzle-kit @types/pg

Ejemplo esperado de conexión:

import "dotenv/config";
import { drizzle } from "drizzle-orm/node-postgres";

export const db = drizzle(process.env.DATABASE_URL!);

Ejemplo esperado de drizzle.config.ts:

import "dotenv/config";
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/database/schema/index.ts",
  out: "./src/database/migrations",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

Scripts esperados en apps/api/package.json:

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio",
    "db:seed": "tsx src/database/seed.ts"
  }
}

14. Tabla companies

Campos:

id uuid primary key
name varchar not null
legal_name varchar
nit varchar unique
email varchar
phone varchar
address text
status varchar not null default 'active'
created_at timestamp
updated_at timestamp

Estados:

active
inactive
suspended

Reglas:

Solo SUPER_ADMIN puede crear empresas.
Solo SUPER_ADMIN puede listar todas las empresas.
COMPANY_ADMIN puede ver información básica de su propia empresa.
Al crear una empresa, opcionalmente se debe crear el primer usuario administrador de esa empresa.

15. Tabla users

Campos:

id uuid primary key
company_id uuid nullable references companies(id)
name varchar not null
email varchar not null unique
password_hash text not null
status varchar not null default 'active'
is_super_admin boolean default false
created_at timestamp
updated_at timestamp

Estados:

active
inactive
pending
blocked

Reglas:

SUPER_ADMIN puede ver usuarios de todas las empresas.
COMPANY_ADMIN solo puede ver usuarios de su empresa.
COMPANY_ADMIN solo puede crear usuarios dentro de su empresa.
Usuarios normales no pueden crear usuarios salvo que tengan permiso.
Al crear usuarios desde empresa, el company_id debe salir del token.
Nunca confiar en company_id enviado desde frontend.
Solo SUPER_ADMIN puede asignar manualmente company_id.
El email debe ser único.
Nunca devolver password_hash.

16. Tabla roles

Campos:

id uuid primary key
company_id uuid nullable references companies(id)
name varchar not null
code varchar not null
description text
is_system_role boolean default false
created_at timestamp
updated_at timestamp

Reglas:

Los roles con company_id nulo pueden ser roles globales del sistema.
Los roles con company_id pertenecen a una empresa.
SUPER_ADMIN puede crear roles globales.
COMPANY_ADMIN puede crear roles solo para su empresa.
Una empresa no puede modificar roles de otra empresa.
No se deben eliminar roles del sistema si is_system_role = true.

17. Tabla permissions

Campos:

id uuid primary key
name varchar not null
code varchar not null unique
description text
module varchar not null
created_at timestamp
updated_at timestamp

Reglas:

Los permisos son globales.
Solo SUPER_ADMIN puede crear, editar o eliminar permisos.
Los usuarios autenticados pueden leer permisos según necesidad.
El frontend usará estos permisos para mostrar u ocultar opciones.
El backend usará estos permisos para proteger endpoints.

18. Tabla role_permissions

Campos:

id uuid primary key
role_id uuid references roles(id)
permission_id uuid references permissions(id)
created_at timestamp

Reglas:

Relaciona roles con permisos.
SUPER_ADMIN puede asignar permisos a cualquier rol.
COMPANY_ADMIN puede asignar permisos solo a roles de su empresa.
COMPANY_ADMIN no puede asignar permisos reservados de SUPER_ADMIN.
No se deben duplicar permisos en el mismo rol.

19. Tabla refresh_tokens

Campos:

id uuid primary key
user_id uuid references users(id)
token_hash text not null
expires_at timestamp not null
revoked_at timestamp nullable
created_at timestamp

Reglas:

Guardar refresh tokens hasheados.
Nunca guardar refresh token plano.
Revocar refresh tokens al cambiar contraseña.
Revocar refresh token en logout.
Validar expiración.
Validar si fue revocado.

20. Tabla password_reset_tokens

Campos:

id uuid primary key
user_id uuid references users(id)
token_hash text not null
expires_at timestamp not null
used_at timestamp nullable
created_at timestamp

Reglas:

Guardar token hasheado.
Nunca guardar token plano.
El token debe expirar.
El token solo puede usarse una vez.
Al restablecer contraseña, marcar token como usado.
Al restablecer contraseña, revocar refresh tokens anteriores.

21. Tabla audit_logs

Campos:

id uuid primary key
company_id uuid nullable references companies(id)
user_id uuid nullable references users(id)
action varchar not null
entity varchar not null
entity_id uuid nullable
metadata jsonb
ip_address varchar
user_agent text
created_at timestamp

Reglas:

Registrar acciones importantes.
Registrar creación de empresas.
Registrar creación de usuarios.
Registrar cambios de roles.
Registrar asignación de permisos.
Registrar login exitoso.
Registrar intentos de acceso no autorizado si aplica.

22. Tabla modules

Campos:

id uuid primary key
name varchar not null
code varchar not null unique
description text
is_active boolean default true
created_at timestamp
updated_at timestamp

Ejemplos:

inventory
orders
invoicing
employees
payroll
reports

Reglas:

Tabla global.
Solo SUPER_ADMIN puede administrar módulos.
Empresas no pueden crear módulos globales.

23. Tabla company_modules

Campos:

id uuid primary key
company_id uuid references companies(id)
module_id uuid references modules(id)
is_active boolean default true
created_at timestamp
updated_at timestamp

Reglas:

Define qué módulos tiene activos cada empresa.
SUPER_ADMIN puede activar o desactivar módulos para empresas.
COMPANY_ADMIN solo puede leer módulos activos de su empresa.
COMPANY_ADMIN no puede activar módulos manualmente si eso depende comercialmente de Labxus.

24. PostgreSQL Row Level Security, RLS

Implementar Row Level Security, RLS, en PostgreSQL para reforzar el aislamiento multitenant por company_id.

Objetivo

Cada empresa solo puede leer, crear, actualizar o eliminar registros que pertenezcan a su propia company_id.
SUPER_ADMIN puede consultar y administrar datos de todas las empresas.
La seguridad no debe depender únicamente del backend.
PostgreSQL debe proteger los datos usando políticas RLS.
Aunque un desarrollador olvide filtrar por company_id en una consulta, la base de datos debe impedir fugas de información entre empresas.

Reglas obligatorias

Activar RLS en todas las tablas multitenant.
Toda tabla de negocio debe tener company_id.
Crear políticas RLS para SELECT, INSERT, UPDATE y DELETE.
El company_id usado por RLS debe salir del contexto de la sesión de base de datos.
El backend NestJS debe establecer el company_id del usuario autenticado antes de ejecutar consultas.
El backend también debe establecer si el usuario es SUPER_ADMIN.
Los usuarios normales no pueden cambiar manualmente el company_id.
SUPER_ADMIN puede acceder a todos los registros.
COMPANY_ADMIN y usuarios normales solo pueden acceder a registros de su propia empresa.
Las tablas globales, como permissions o modules, pueden tener reglas especiales.
La tabla companies debe tener reglas especiales.
No basta con filtrar por company_id desde el backend. PostgreSQL debe aplicar RLS obligatoriamente en las tablas multitenant.

25. Variables de contexto para RLS

Implementar variables personalizadas de PostgreSQL:

app.current_company_id
app.current_user_id
app.is_super_admin

Ejemplo:

SELECT set_config('app.current_company_id', 'uuid-de-la-empresa', true);
SELECT set_config('app.current_user_id', 'uuid-del-usuario', true);
SELECT set_config('app.is_super_admin', 'false', true);

Para SUPER_ADMIN:

SELECT set_config('app.current_company_id', '', true);
SELECT set_config('app.current_user_id', 'uuid-del-super-admin', true);
SELECT set_config('app.is_super_admin', 'true', true);

26. Integración de RLS con NestJS y Drizzle

Crear un helper, servicio o middleware para establecer el contexto RLS por request.

Ejemplo conceptual:

await db.execute(sql`
  SELECT set_config('app.current_company_id', ${currentUser.companyId ?? ""}, true)
`);

await db.execute(sql`
  SELECT set_config('app.current_user_id', ${currentUser.id}, true)
`);

await db.execute(sql`
  SELECT set_config('app.is_super_admin', ${currentUser.isSuperAdmin ? "true" : "false"}, true)
`);

Reglas:

Configurar el contexto RLS antes de ejecutar queries protegidas.
Preferir ejecutar consultas dentro de una transacción.
Dentro de la transacción, primero se configura el contexto y luego se ejecutan las consultas.
Evitar usar conexión compartida sin configurar tenant.
Considerar problemas de connection pooling.
Garantizar que el contexto se establezca por request o por transacción.
No permitir que una request herede el contexto de otra.

27. Ejemplo de política RLS para una tabla multitenant

Ejemplo para products:

ALTER TABLE products ENABLE ROW LEVEL SECURITY;
ALTER TABLE products FORCE ROW LEVEL SECURITY;

CREATE POLICY products_select_policy
ON products
FOR SELECT
USING (
  current_setting('app.is_super_admin', true) = 'true'
  OR company_id::text = current_setting('app.current_company_id', true)
);

CREATE POLICY products_insert_policy
ON products
FOR INSERT
WITH CHECK (
  current_setting('app.is_super_admin', true) = 'true'
  OR company_id::text = current_setting('app.current_company_id', true)
);

CREATE POLICY products_update_policy
ON products
FOR UPDATE
USING (
  current_setting('app.is_super_admin', true) = 'true'
  OR company_id::text = current_setting('app.current_company_id', true)
)
WITH CHECK (
  current_setting('app.is_super_admin', true) = 'true'
  OR company_id::text = current_setting('app.current_company_id', true)
);

CREATE POLICY products_delete_policy
ON products
FOR DELETE
USING (
  current_setting('app.is_super_admin', true) = 'true'
  OR company_id::text = current_setting('app.current_company_id', true)
);

28. Tablas que deben tener RLS

Aplicar RLS a tablas como:

companies
users
roles
role_permissions
company_modules
audit_logs

Y futuras tablas de negocio:

customers
products
warehouses
product_stocks
orders
order_items
employees
payroll
invoices

29. Reglas especiales de RLS por tabla

companies

Reglas:

SUPER_ADMIN puede ver todas las empresas.
SUPER_ADMIN puede crear, editar y eliminar empresas.
COMPANY_ADMIN solo puede ver su propia empresa.
Usuarios normales pueden ver información básica de su propia empresa.
Ninguna empresa puede ver datos de otra empresa.

users

Reglas:

SUPER_ADMIN puede ver todos los usuarios.
COMPANY_ADMIN puede ver usuarios de su empresa.
Usuarios normales pueden ver su propio perfil.
COMPANY_ADMIN puede crear usuarios solo dentro de su empresa.
No se permite crear SUPER_ADMIN desde una empresa.

roles

Reglas:

SUPER_ADMIN puede ver roles globales y roles de todas las empresas.
COMPANY_ADMIN puede ver roles globales permitidos y roles de su empresa.
COMPANY_ADMIN solo puede crear roles para su empresa.
Una empresa no puede editar roles de otra empresa.

permissions

Reglas:

Puede ser una tabla global.
Usuarios autenticados pueden leer permisos.
Solo SUPER_ADMIN puede crear, editar o eliminar permisos.

modules

Reglas:

Puede ser una tabla global.
Usuarios autenticados pueden leer módulos visibles.
Solo SUPER_ADMIN puede crear, editar o eliminar módulos.

company_modules

Reglas:

SUPER_ADMIN puede administrar todos.
COMPANY_ADMIN puede leer solo módulos activos de su empresa.
COMPANY_ADMIN no puede activar o desactivar módulos.

refresh_tokens

Reglas:

Un usuario solo puede acceder a sus propios refresh tokens.
Los tokens deben guardarse hasheados.
No exponer tokens desde endpoints públicos.

password_reset_tokens

Reglas:

Acceso solo desde servicios internos de autenticación.
Los tokens deben guardarse hasheados.
No exponer tokens desde endpoints públicos.

30. Migraciones RLS

Crear migraciones de Drizzle o SQL para:

ALTER TABLE ... ENABLE ROW LEVEL SECURITY
ALTER TABLE ... FORCE ROW LEVEL SECURITY
CREATE POLICY ...
DROP POLICY ...

Las migraciones deben incluir:

Activación de RLS.
Creación de políticas por tabla.
Reversión segura.
Comentarios explicando cada política.

31. Pruebas de RLS

Crear pruebas o ejemplos para verificar:

Empresa A no puede leer usuarios de Empresa B.
Empresa A no puede modificar usuarios de Empresa B.
Empresa A no puede eliminar roles de Empresa B.
Empresa A no puede leer módulos privados de otra empresa.
SUPER_ADMIN sí puede leer todas las empresas.
Si no se establece app.current_company_id, las queries multitenant deben fallar o no retornar datos.
Si app.is_super_admin es false, no debe poder ver datos globales restringidos.

32. Módulo Auth

Crear estas rutas backend:

POST /auth/login
POST /auth/logout
POST /auth/refresh
POST /auth/forgot-password
POST /auth/reset-password
GET /auth/me

Reglas:

Login con email y password.
Validar usuario existente.
Validar estado activo.
Comparar password con bcrypt.
Generar access token.
Generar refresh token.
Guardar hash del refresh token.
Devolver datos seguros del usuario.
No devolver password_hash.

El access token debe incluir:

user_id
company_id
role
permissions
is_super_admin

Logout

Reglas:

Revocar refresh token actual.
Permitir cerrar sesión de forma segura.

Refresh token

Reglas:

Validar refresh token.
Comparar contra hash guardado.
Verificar expiración.
Verificar que no esté revocado.
Generar nuevo access token.
Opcionalmente rotar refresh token.

Auth me

Reglas:

Devolver usuario autenticado.
Devolver empresa.
Devolver rol.
Devolver permisos.
Devolver módulos activos de la empresa si aplica.

33. Recuperación de contraseña

Crear flujo:

Usuario solicita recuperación
↓
Escribe email
↓
Si existe, crear token seguro
↓
Guardar hash del token
↓
Enviar email con enlace
↓
Usuario entra a /reset-password?token=...
↓
Escribe nueva contraseña
↓
Backend valida token
↓
Backend cambia contraseña
↓
Backend marca token como usado
↓
Backend revoca refresh tokens anteriores

Reglas:

No revelar si el correo existe o no.
Siempre responder con mensaje genérico.
Token debe tener expiración.
Token solo puede usarse una vez.
Token debe guardarse hasheado.
Al cambiar contraseña, revocar refresh tokens anteriores.
Aplicar rate limiting en forgot-password.

Mensaje recomendado:

Si el correo existe en nuestra plataforma, enviaremos instrucciones para recuperar la contraseña.

34. Módulo Companies

Crear rutas:

POST /companies
GET /companies
GET /companies/:id
PATCH /companies/:id
DELETE /companies/:id

Reglas:

Solo SUPER_ADMIN puede crear empresas.
Solo SUPER_ADMIN puede listar todas las empresas.
Solo SUPER_ADMIN puede editar o eliminar empresas.
COMPANY_ADMIN puede leer únicamente su propia empresa.
Al crear una empresa, permitir crear primer usuario administrador.
Ese primer usuario debe tener rol COMPANY_ADMIN.
La empresa debe iniciar en estado active, salvo que se indique otra cosa.
Registrar en audit log la creación de empresa.

35. Módulo Users

Crear rutas:

POST /users
GET /users
GET /users/:id
PATCH /users/:id
DELETE /users/:id

Reglas:

SUPER_ADMIN puede ver usuarios de todas las empresas.
COMPANY_ADMIN solo puede ver usuarios de su propia empresa.
COMPANY_ADMIN puede crear usuarios solo para su propia empresa.
Usuario normal no puede crear usuarios salvo que tenga users.create.
Al crear usuario desde empresa, company_id sale del token.
No confiar en company_id enviado desde frontend.
Solo SUPER_ADMIN puede asignar manualmente company_id.
No permitir que COMPANY_ADMIN cree SUPER_ADMIN.
No permitir que usuarios normales modifiquen roles o permisos.
Registrar creación, edición y eliminación en audit log.

36. Módulo Roles

Crear rutas:

POST /roles
GET /roles
GET /roles/:id
PATCH /roles/:id
DELETE /roles/:id

Reglas:

SUPER_ADMIN puede crear roles globales.
COMPANY_ADMIN puede crear roles solo para su empresa.
Los roles pueden ser globales o por empresa.
Un usuario puede tener un rol principal.
Los roles deben tener permisos asociados.
No permitir que una empresa modifique roles de otra empresa.
No permitir eliminar roles del sistema.
Registrar cambios en audit log.

37. Módulo Permissions

Crear rutas:

GET /permissions
POST /roles/:id/permissions
DELETE /roles/:id/permissions/:permissionId

Reglas:

Los permisos definen qué acciones puede hacer un usuario.
Los permisos deben usarse en backend y frontend.
Backend debe proteger rutas con permisos.
Frontend debe ocultar o mostrar opciones del menú según permisos.
Solo SUPER_ADMIN puede crear permisos si se implementa creación.
COMPANY_ADMIN puede asignar permisos permitidos a roles de su empresa.
No permitir asignar permisos reservados de SUPER_ADMIN.

38. Guards, decorators y helpers

Crear:

@CurrentUser()
@RequireRoles()
@RequirePermissions()
JwtAuthGuard
RolesGuard
PermissionsGuard
TenantGuard

CurrentUser

Debe permitir obtener:

id
companyId
email
role
permissions
isSuperAdmin

JwtAuthGuard

Debe:

Validar access token.
Rechazar tokens inválidos.
Agregar usuario al request.

RolesGuard

Debe:

Validar roles requeridos.
Permitir acceso automático a SUPER_ADMIN cuando aplique.

PermissionsGuard

Debe:

Validar permisos requeridos.
Revisar permisos desde token o base de datos.
Permitir acceso si usuario tiene permiso requerido.
Bloquear si no tiene permiso.

TenantGuard

Debe:

Asegurar que usuarios normales operen dentro de su empresa.
Evitar que un usuario manipule company_id.
Permitir a SUPER_ADMIN operar globalmente.

39. Seguridad obligatoria

Implementar:

Hash de contraseñas con bcrypt.
Hash de refresh tokens.
Hash de password reset tokens.
Rate limiting en login.
Rate limiting en forgot-password.
Helmet en NestJS.
CORS configurado correctamente.
Validación de variables de entorno.
No devolver password_hash.
No exponer tokens sensibles.
No permitir escalamiento de privilegios.
No permitir que COMPANY_ADMIN cree SUPER_ADMIN.
No permitir que usuarios normales modifiquen sus permisos.
No permitir que una empresa vea datos de otra.
Sanitizar errores.
Manejo correcto de errores.
Audit logs para acciones críticas.

40. Variables de entorno backend

Crear archivo .env.example para backend:

NODE_ENV=development
PORT=4000

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/labxus

JWT_ACCESS_SECRET=change-me-access-secret
JWT_REFRESH_SECRET=change-me-refresh-secret
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

PASSWORD_RESET_EXPIRES_IN=30m

FRONTEND_URL=http://localhost:3000

SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASS=
SMTP_FROM=

BCRYPT_SALT_ROUNDS=10

41. Variables de entorno frontend

Crear archivo .env.example para frontend:

NEXT_PUBLIC_API_URL=http://localhost:4000

42. Frontend Next.js

Crear estas rutas públicas:

/login
/forgot-password
/reset-password

Crear estas rutas privadas:

/dashboard
/dashboard/companies
/dashboard/companies/new
/dashboard/users
/dashboard/users/new
/dashboard/roles
/dashboard/roles/new
/dashboard/settings

Reglas frontend:

Si el usuario no está autenticado, redirigir a /login.
Si el usuario autenticado intenta entrar a una ruta sin permiso, mostrar pantalla de acceso denegado.
El menú lateral debe mostrar opciones según permisos.
SUPER_ADMIN ve empresas.
COMPANY_ADMIN no ve el módulo global de empresas.
COMPANY_ADMIN ve usuarios y roles solo de su empresa.
Los formularios deben usar React Hook Form + Zod.
La UI debe hacerse con Shadcn UI.
El diseño debe usar Tailwind CSS v4.1 con variables HSL.
Crear layout de dashboard moderno tipo SaaS.
Crear modo oscuro.
Crear manejo de loading states.
Crear manejo de errores.
Crear componentes reutilizables.

43. Componentes frontend

Crear:

LoginForm
ForgotPasswordForm
ResetPasswordForm
CreateCompanyForm
CreateUserForm
CreateRoleForm
Sidebar
DashboardLayout
ProtectedRoute
PermissionGate
UserMenu
DataTable
EmptyState
LoadingState
AccessDenied
ThemeToggle

44. PermissionGate

Crear componente para mostrar contenido según permisos.

Ejemplo esperado:

<PermissionGate permission="users.create">
  <Button>Crear usuario</Button>
</PermissionGate>

Reglas:

Si el usuario tiene permiso, muestra children.
Si no tiene permiso, no muestra nada.
Puede recibir fallback opcional.

El menú debe renderizarse según permisos.

Ejemplo:

Dashboard
Empresas
Usuarios
Roles
Configuración

Reglas:

SUPER_ADMIN ve Empresas.
COMPANY_ADMIN no ve Empresas globales.
Usuarios sin users.read no ven Usuarios.
Usuarios sin roles.read no ven Roles.
Las rutas deben estar protegidas también en backend, no solo ocultas en frontend.

46. Diseño visual con HSL

Configurar Tailwind CSS v4.1 y CSS variables con HSL.

Usar marca visual de Labxus:

Morado tecnológico
Azul eléctrico
Fondo claro profesional
Modo oscuro elegante
Estilo SaaS moderno
Bordes suaves
Cards limpias
Buen contraste
Diseño moderno tipo startup

Ejemplo base:

:root {
  --background: 240 20% 99%;
  --foreground: 240 10% 8%;

  --card: 0 0% 100%;
  --card-foreground: 240 10% 8%;

  --primary: 258 90% 58%;
  --primary-foreground: 0 0% 100%;

  --secondary: 221 83% 53%;
  --secondary-foreground: 0 0% 100%;

  --muted: 240 10% 96%;
  --muted-foreground: 240 5% 45%;

  --border: 240 8% 90%;
  --input: 240 8% 90%;
  --ring: 258 90% 58%;

  --destructive: 0 84% 60%;
  --destructive-foreground: 0 0% 100%;

  --radius: 0.75rem;
}

.dark {
  --background: 240 10% 4%;
  --foreground: 0 0% 98%;

  --card: 240 10% 7%;
  --card-foreground: 0 0% 98%;

  --primary: 258 90% 65%;
  --primary-foreground: 0 0% 100%;

  --secondary: 221 83% 60%;
  --secondary-foreground: 0 0% 100%;

  --muted: 240 8% 14%;
  --muted-foreground: 240 5% 65%;

  --border: 240 8% 18%;
  --input: 240 8% 18%;
  --ring: 258 90% 65%;

  --destructive: 0 72% 51%;
  --destructive-foreground: 0 0% 100%;
}

47. Backend endpoints esperados

Auth

POST /auth/login
POST /auth/logout
POST /auth/refresh
POST /auth/forgot-password
POST /auth/reset-password
GET /auth/me

Companies

POST /companies
GET /companies
GET /companies/:id
PATCH /companies/:id
DELETE /companies/:id

Users

POST /users
GET /users
GET /users/:id
PATCH /users/:id
DELETE /users/:id

Roles

POST /roles
GET /roles
GET /roles/:id
PATCH /roles/:id
DELETE /roles/:id

Permissions

GET /permissions
POST /roles/:id/permissions
DELETE /roles/:id/permissions/:permissionId

48. Seeds iniciales

Crear seed inicial para:

Usuario SUPER_ADMIN

Debe crear un usuario super administrador.

Ejemplo:

name: David Labxus Admin
email: admin@labxus.com
password: cambiar123*
is_super_admin: true
company_id: null
status: active

La contraseña debe hashearse con bcrypt.

Roles base

Crear:

SUPER_ADMIN
COMPANY_ADMIN
MANAGER
EMPLOYEE
READ_ONLY

Permisos base

Crear todos los permisos definidos anteriormente.

Módulos base

Crear:

inventory
orders
invoicing
employees
payroll
reports

49. Testing esperado

Crear pruebas o ejemplos para validar:

Auth

Login correcto.
Login con contraseña incorrecta.
Login con usuario bloqueado.
Refresh token válido.
Refresh token revocado.
Forgot password no revela si email existe.
Reset password cambia contraseña.
Reset password revoca refresh tokens.

Empresas

SUPER_ADMIN crea empresa.
COMPANY_ADMIN no puede crear empresa.
Usuario normal no puede crear empresa.

Usuarios

COMPANY_ADMIN crea usuario en su empresa.
COMPANY_ADMIN no puede crear usuario en otra empresa.
Usuario normal no puede crear usuarios sin permiso.
COMPANY_ADMIN no puede crear SUPER_ADMIN.

Roles y permisos

COMPANY_ADMIN crea rol en su empresa.
COMPANY_ADMIN no modifica rol de otra empresa.
No se puede eliminar rol del sistema.
Se asignan permisos correctamente.

RLS

Empresa A no ve datos de Empresa B.
Empresa A no actualiza datos de Empresa B.
Empresa A no elimina datos de Empresa B.
SUPER_ADMIN sí puede ver todo.
Sin contexto RLS, las queries protegidas no retornan datos.

50. Documentación esperada

Entregar documentación con:

Cómo instalar pnpm.
Cómo instalar dependencias con pnpm.
Cómo configurar .env.
Cómo ejecutar PostgreSQL local.
Cómo correr migraciones con pnpm.
Cómo correr seeds con pnpm.
Cómo iniciar backend con pnpm.
Cómo iniciar frontend con pnpm.
Cómo probar login.
Cómo crear primera empresa.
Cómo crear usuarios.
Cómo probar permisos.
Cómo probar RLS.
Cómo agregar nuevos módulos en el futuro.

51. Comandos esperados

Usar comandos con pnpm.

Ejemplos:

pnpm install
pnpm dev
pnpm build
pnpm lint
pnpm typecheck
pnpm --filter @labxus/api db:generate
pnpm --filter @labxus/api db:migrate
pnpm --filter @labxus/api db:seed
pnpm --filter @labxus/api start:dev
pnpm --filter @labxus/web dev

52. Fases de implementación

No generes todo de golpe de forma desordenada.

Primero entrega el diseño técnico completo:

Arquitectura general.
Estructura de carpetas.
Modelo de base de datos.
Relaciones entre tablas.
Flujo de autenticación.
Flujo multitenant.
Estrategia RLS.
Roles y permisos.
Flujo frontend.
Fases de implementación.

Después empieza la implementación por fases.

Fase 1

Crear estructura base del monorepo:

apps/web
apps/api
packages/shared

Configurar:

pnpm workspace
TypeScript en todo el proyecto
package shared
NestJS v11.1.19
Next.js v16.2.x
Tailwind CSS v4.1
Shadcn UI
Variables HSL
ESLint/Prettier si aplica

Fase 2

Crear base de datos:

Drizzle configurado con PostgreSQL
PostgreSQL conectado
Schemas principales
Migraciones iniciales
Seeds iniciales
Usuario SUPER_ADMIN
Roles base
Permisos base

Fase 3

Crear autenticación:

Login
Logout
Refresh token
Auth me
JWT strategy
Guards
Decorators
Hash de contraseñas
Hash de refresh token

Fase 4

Crear recuperación de contraseña:

Forgot password
Reset password
Password reset tokens
Envío de email o mock inicial
Revocación de refresh tokens

Fase 5

Crear empresas:

CRUD companies
Solo SUPER_ADMIN
Crear empresa con primer admin
Audit logs

Fase 6

Crear usuarios:

CRUD users
Reglas por empresa
Validaciones
Protección por permisos
No permitir escalamiento de privilegios

Fase 7

Crear roles y permisos:

CRUD roles
Listar permisos
Asignar permisos a roles
Proteger endpoints
Proteger frontend

Fase 8

Implementar RLS:

Activar RLS en tablas
Crear políticas
Crear helper de contexto RLS
Integrar con Drizzle
Probar aislamiento por empresa
Documentar connection pooling

Fase 9

Crear frontend:

Login
Forgot password
Reset password
Dashboard layout
Sidebar
Companies pages
Users pages
Roles pages
PermissionGate
Protected routes
Access denied

Fase 10

Testing y documentación:

Pruebas unitarias
Pruebas de integración
Pruebas RLS
README completo
Guía para agregar módulos futuros

53. Resultado esperado

Quiero que entregues:

Diseño técnico completo.
Estructura completa de carpetas.
Modelo de base de datos.
Relaciones entre tablas.
Schemas Drizzle.
Migraciones Drizzle.
Migraciones SQL para RLS.
Políticas RLS por tabla.
Seeds iniciales.
Schemas Zod compartidos.
Types compartidos.
Constantes compartidas de roles.
Constantes compartidas de permisos.
Código backend NestJS por módulos.
Código frontend Next.js por páginas y componentes.
Guards de autenticación.
Guards de roles.
Guards de permisos.
TenantGuard.
Decoradores personalizados.
Helper para configurar contexto RLS.
Formularios con Shadcn UI.
Validaciones con React Hook Form + Zod.
Ejemplos de peticiones API.
Documentación para ejecutar el proyecto.
Pruebas para seguridad multitenant.
Explicación sobre connection pooling con RLS.
Explicación de cómo agregar módulos futuros.

54. Restricciones importantes

No usar:

Microservicios
Firebase
MongoDB
Prisma
Supabase Auth
Clerk
NextAuth
Auth0
npm
yarn
bun
JavaScript plano para lógica principal

Sí usar:

pnpm
TypeScript en todo el proyecto
NestJS v11.1.19
Next.js v16.2.x
Tailwind CSS v4.1
NestJS Auth propio
PostgreSQL
Drizzle ORM
Zod
JWT
Refresh tokens
RLS
Tailwind
Shadcn UI
HSL

55. Regla final muy importante

No basta con ocultar botones en el frontend.

La seguridad debe existir en 3 niveles:

1. Frontend:
   Ocultar opciones según permisos.

2. Backend:
   Proteger rutas con guards de auth, roles, permisos y tenant.

3. Base de datos:
   Proteger filas con PostgreSQL Row Level Security.

El sistema debe estar preparado para crecer después con módulos como:

inventario
órdenes
facturación electrónica
empleados
nómina
reportes
clientes
bodegas
productos
kardex

Labxus Auth Multitenant con RLS, Next.js, NestJS, PostgreSQL, Drizzle, Zod y TypeScript

1. Stack obligatorio

Gestor de paquetes

Lenguaje

2. Versiones obligatorias

Frontend

Backend

ORM

3. Stack técnico final

Frontend

Backend

Base de datos

Arquitectura

4. Arquitectura general esperada

5. package.json raíz esperado

6. pnpm-workspace.yaml esperado

7. Modelo de negocio y reglas principales

8. Módulos iniciales a construir

9. Package compartido

10. Zod schemas compartidos

Auth

Companies

Users

Roles

Permissions

Reglas de password

11. Roles base

12. Permisos base

13. Base de datos con Drizzle ORM

14. Tabla companies

15. Tabla users

16. Tabla roles

17. Tabla permissions

18. Tabla role_permissions

19. Tabla refresh_tokens

20. Tabla password_reset_tokens

21. Tabla audit_logs

22. Tabla modules

23. Tabla company_modules

24. PostgreSQL Row Level Security, RLS

Objetivo

Reglas obligatorias

25. Variables de contexto para RLS

26. Integración de RLS con NestJS y Drizzle

27. Ejemplo de política RLS para una tabla multitenant

28. Tablas que deben tener RLS

29. Reglas especiales de RLS por tabla

companies

users

roles

permissions

modules

company_modules

refresh_tokens

password_reset_tokens

30. Migraciones RLS

31. Pruebas de RLS

32. Módulo Auth

Login

Logout

Refresh token

Auth me

33. Recuperación de contraseña

34. Módulo Companies

35. Módulo Users

36. Módulo Roles

37. Módulo Permissions

38. Guards, decorators y helpers

CurrentUser

JwtAuthGuard

RolesGuard

PermissionsGuard

TenantGuard

39. Seguridad obligatoria

40. Variables de entorno backend

41. Variables de entorno frontend

42. Frontend Next.js

43. Componentes frontend

44. PermissionGate

45. Sidebar dinámico