feat(auth): role-based permissions + user management (plan phase 1)

Adds the RBAC foundation the CRUD phases build on, and the first write
module (users). The platform was read-only: every controller was guarded
only by AuthenticatedGuard and UserRole was ADMIN|STAFF. The old PHP app
stored level+role but enforced neither, so this is a fresh design.

Permission model (server-authoritative):
- UserRole expanded to an ordered rank ADMIN > MANAGER > STAFF > VIEWER.
  VIEWER is the read-only role; STAFF+ can write.
- auth/abilities.ts: ROLE_RANK + ABILITY_MIN matrix + can()/abilitiesFor().
- @RequireAbility decorator + AbilityGuard enforce it on write routes;
  reads stay on AuthenticatedGuard so any logged-in user can read.
- /auth/login and /auth/me now return the resolved abilities map, so the
  web gates its UI off one payload instead of duplicating the rules.

User management (ADMIN-only, ability "user:manage"):
- UsersService gains list/create/update/resetPassword (argon2), never
  returns passwordHash; blocks self-deactivation and self-demotion;
  maps duplicate email to 409.
- UsersController: GET/POST /users, PATCH /users/:id,
  POST /users/:id/reset-password.
- Every mutation logged via new AuditService over the existing
  ActivityLog model (global CommonModule).

Web:
- AuthContext + useAuth/useCan; AppShell provides the user and gates the
  new "Usuarios" nav entry on user:manage; shows the user's role.
- /usuarios admin page: list + create/edit form + password reset +
  active toggle, Spanish-first, reusing existing card/table/field styles.

Schema pushed to dev (enum only, non-destructive). Verified end-to-end
against dev: admin CRUD works, VIEWER writes 403 while reads 200,
self-lockout guards and duplicate-email 409 all hold.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/api/src/app.module.ts

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common";
 import { ConfigModule } from "@nestjs/config";
 import { PrismaModule } from "./prisma/prisma.module";
+import { CommonModule } from "./common/common.module";
 import { UsersModule } from "./users/users.module";
 import { AuthModule } from "./auth/auth.module";
 import { CustomersModule } from "./customers/customers.module";
@@ -14,6 +15,7 @@ import { AppController } from "./app.controller";
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
     PrismaModule,
+    CommonModule,
     UsersModule,
     AuthModule,
     CustomersModule,

apps/api/src/auth/abilities.ts

@@ -0,0 +1,67 @@
+// Server-authoritative permission matrix. Roles form an ordered rank
+// (ADMIN > MANAGER > STAFF > VIEWER — this is the "level" concept); every
+// write action carries a minimum rank. VIEWER holds rank 0 and is the
+// read-only role. Reads are not listed here — they stay on AuthenticatedGuard
+// alone, so any logged-in user (including VIEWER) can read.
+//
+// This is the single source of truth: the API enforces it via AbilityGuard and
+// ships the resolved per-user map to the web through /auth/me, so the UI never
+// keeps its own copy of the rules.
+
+export type Role = "ADMIN" | "MANAGER" | "STAFF" | "VIEWER";
+
+export const ROLE_RANK: Record<Role, number> = {
+  VIEWER: 0,
+  STAFF: 1,
+  MANAGER: 2,
+  ADMIN: 3,
+};
+
+export type Ability =
+  | "customer:create"
+  | "customer:update"
+  | "customer:delete"
+  | "policy:create"
+  | "policy:update"
+  | "policy:delete"
+  | "property:create"
+  | "property:update"
+  | "property:delete"
+  | "ledger:create"
+  | "ledger:void"
+  | "bank:create"
+  | "bank:void"
+  | "lookup:manage"
+  | "user:manage";
+
+/** Minimum role required for each ability. */
+export const ABILITY_MIN: Record<Ability, Role> = {
+  "customer:create": "STAFF",
+  "customer:update": "STAFF",
+  "customer:delete": "ADMIN",
+  "policy:create": "STAFF",
+  "policy:update": "STAFF",
+  "policy:delete": "MANAGER",
+  "property:create": "STAFF",
+  "property:update": "STAFF",
+  "property:delete": "MANAGER",
+  "ledger:create": "STAFF",
+  "ledger:void": "MANAGER",
+  "bank:create": "STAFF",
+  "bank:void": "MANAGER",
+  "lookup:manage": "MANAGER",
+  "user:manage": "ADMIN",
+};
+
+export const ALL_ABILITIES = Object.keys(ABILITY_MIN) as Ability[];
+
+export function can(role: Role, ability: Ability): boolean {
+  return ROLE_RANK[role] >= ROLE_RANK[ABILITY_MIN[ability]];
+}
+
+/** Resolved {ability: boolean} map for a role — sent to the web via /auth/me. */
+export function abilitiesFor(role: Role): Record<Ability, boolean> {
+  return Object.fromEntries(
+    ALL_ABILITIES.map((a) => [a, can(role, a)]),
+  ) as Record<Ability, boolean>;
+}

apps/api/src/auth/ability.guard.ts

@@ -0,0 +1,36 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { Request } from "express";
+import { ABILITY_KEY } from "./require-ability.decorator";
+import { Ability, Role, can } from "./abilities";
+
+/**
+ * Enforces the ability matrix (abilities.ts) against req.user.role. A route
+ * with no @RequireAbility passes through untouched — this guard only gates the
+ * routes that declare one. It does NOT check authentication; always list it
+ * after AuthenticatedGuard so an unauthenticated request is rejected first.
+ */
+@Injectable()
+export class AbilityGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const ability = this.reflector.getAllAndOverride<Ability | undefined>(
+      ABILITY_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+    if (!ability) return true;
+
+    const req = context.switchToHttp().getRequest<Request>();
+    const user = req.user as { role?: Role } | undefined;
+    if (!user?.role || !can(user.role, ability)) {
+      throw new ForbiddenException("No tiene permisos para esta acción");
+    }
+    return true;
+  }
+}

apps/api/src/auth/auth.controller.ts

@@ -3,6 +3,14 @@ import { Request, Response } from "express";
 import { LocalAuthGuard } from "./local-auth.guard";
 import { AuthenticatedGuard } from "./authenticated.guard";
 import { LoginDto } from "./login.dto";
+import { abilitiesFor, Role } from "./abilities";
+
+/** Attach the resolved ability map so the web can gate its UI off one payload. */
+function withAbilities(user: unknown) {
+  const u = user as { role?: Role } | undefined;
+  if (!u?.role) return u;
+  return { ...u, abilities: abilitiesFor(u.role) };
+}
 
 @Controller("auth")
 export class AuthController {
@@ -13,13 +21,13 @@ export class AuthController {
   @Post("login")
   @HttpCode(200)
   login(@Req() req: Request, @Res({ passthrough: true }) _res: Response, _body?: LoginDto) {
-    return req.user;
+    return withAbilities(req.user);
   }
 
   @UseGuards(AuthenticatedGuard)
   @Get("me")
   me(@Req() req: Request) {
-    return req.user;
+    return withAbilities(req.user);
   }
 
   @Post("logout")

apps/api/src/auth/require-ability.decorator.ts

@@ -0,0 +1,12 @@
+import { SetMetadata } from "@nestjs/common";
+import type { Ability } from "./abilities";
+
+export const ABILITY_KEY = "required_ability";
+
+/**
+ * Tags a write route with the ability it requires. Pair with
+ * `@UseGuards(AuthenticatedGuard, AbilityGuard)` — AuthenticatedGuard proves
+ * the session, AbilityGuard checks this ability against the user's role.
+ */
+export const RequireAbility = (ability: Ability) =>
+  SetMetadata(ABILITY_KEY, ability);

apps/api/src/common/audit.service.ts

@@ -0,0 +1,34 @@
+import { Injectable } from "@nestjs/common";
+import { Prisma } from "@jorgecuadros/database";
+import { PrismaService } from "../prisma/prisma.service";
+
+/**
+ * Thin writer over the existing ActivityLog model. Every mutating route calls
+ * this so who-did-what is recorded — the structural replacement for the old
+ * PHP app's scattered Logger calls. Best-effort: a logging failure must never
+ * fail the underlying write, so callers `void audit.log(...)` without awaiting.
+ */
+@Injectable()
+export class AuditService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async log(
+    userId: string | null | undefined,
+    event: string,
+    message?: Record<string, unknown>,
+    level = "info",
+  ): Promise<void> {
+    try {
+      await this.prisma.activityLog.create({
+        data: {
+          userId: userId ?? undefined,
+          event,
+          level,
+          message: (message as Prisma.InputJsonValue) ?? undefined,
+        },
+      });
+    } catch {
+      /* never let audit logging break a real write */
+    }
+  }
+}

apps/api/src/common/common.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from "@nestjs/common";
+import { AuditService } from "./audit.service";
+
+@Global()
+@Module({
+  providers: [AuditService],
+  exports: [AuditService],
+})
+export class CommonModule {}

apps/api/src/users/create-user.dto.ts

@@ -0,0 +1,21 @@
+import { IsEmail, IsEnum, IsOptional, IsString, MinLength } from "class-validator";
+import { UserRole } from "@jorgecuadros/database";
+
+export class CreateUserDto {
+  @IsString()
+  @MinLength(1)
+  name!: string;
+
+  @IsEmail()
+  email!: string;
+
+  @IsString()
+  @MinLength(8)
+  password!: string;
+
+  @IsEnum(UserRole)
+  role!: UserRole;
+
+  @IsOptional()
+  active?: boolean;
+}

apps/api/src/users/reset-password.dto.ts

@@ -0,0 +1,7 @@
+import { IsString, MinLength } from "class-validator";
+
+export class ResetPasswordDto {
+  @IsString()
+  @MinLength(8)
+  password!: string;
+}

apps/api/src/users/update-user.dto.ts

@@ -0,0 +1,22 @@
+import { IsBoolean, IsEmail, IsEnum, IsOptional, IsString, MinLength } from "class-validator";
+import { UserRole } from "@jorgecuadros/database";
+
+/** Password changes go through the dedicated reset-password route, not here. */
+export class UpdateUserDto {
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  name?: string;
+
+  @IsOptional()
+  @IsEmail()
+  email?: string;
+
+  @IsOptional()
+  @IsEnum(UserRole)
+  role?: UserRole;
+
+  @IsOptional()
+  @IsBoolean()
+  active?: boolean;
+}

apps/api/src/users/users.controller.ts

@@ -0,0 +1,72 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  Patch,
+  Post,
+  Req,
+  UseGuards,
+} from "@nestjs/common";
+import { Request } from "express";
+import { AuthenticatedGuard } from "../auth/authenticated.guard";
+import { AbilityGuard } from "../auth/ability.guard";
+import { RequireAbility } from "../auth/require-ability.decorator";
+import { AuditService } from "../common/audit.service";
+import { UsersService } from "./users.service";
+import { CreateUserDto } from "./create-user.dto";
+import { UpdateUserDto } from "./update-user.dto";
+import { ResetPasswordDto } from "./reset-password.dto";
+
+/** Every route here is ADMIN-only (ability "user:manage"). */
+@UseGuards(AuthenticatedGuard, AbilityGuard)
+@RequireAbility("user:manage")
+@Controller("users")
+export class UsersController {
+  constructor(
+    private readonly users: UsersService,
+    private readonly audit: AuditService,
+  ) {}
+
+  private actingId(req: Request): string {
+    return (req.user as { id: string }).id;
+  }
+
+  @Get()
+  list() {
+    return this.users.list();
+  }
+
+  @Post()
+  async create(@Body() dto: CreateUserDto, @Req() req: Request) {
+    const user = await this.users.create(dto);
+    void this.audit.log(this.actingId(req), "user.create", {
+      userId: user.id,
+      email: user.email,
+      role: user.role,
+    });
+    return user;
+  }
+
+  @Patch(":id")
+  async update(
+    @Param("id") id: string,
+    @Body() dto: UpdateUserDto,
+    @Req() req: Request,
+  ) {
+    const user = await this.users.update(id, dto, this.actingId(req));
+    void this.audit.log(this.actingId(req), "user.update", { userId: id, changes: dto });
+    return user;
+  }
+
+  @Post(":id/reset-password")
+  async resetPassword(
+    @Param("id") id: string,
+    @Body() dto: ResetPasswordDto,
+    @Req() req: Request,
+  ) {
+    const user = await this.users.resetPassword(id, dto.password);
+    void this.audit.log(this.actingId(req), "user.reset_password", { userId: id });
+    return user;
+  }
+}

apps/api/src/users/users.module.ts

@@ -1,8 +1,10 @@
 import { Module } from "@nestjs/common";
 import { UsersService } from "./users.service";
+import { UsersController } from "./users.controller";
 
 @Module({
   providers: [UsersService],
+  controllers: [UsersController],
   exports: [UsersService],
 })
 export class UsersModule {}

apps/api/src/users/users.service.ts

@@ -1,11 +1,35 @@
-import { Injectable } from "@nestjs/common";
-import { PrismaService } from "../prisma/prisma.service";
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
+import * as argon2 from "argon2";
+import { Prisma } from "@jorgecuadros/database";
 import type { User } from "@jorgecuadros/database";
+import { PrismaService } from "../prisma/prisma.service";
+import { CreateUserDto } from "./create-user.dto";
+import { UpdateUserDto } from "./update-user.dto";
+
+/** Shape returned to the UI — never carries passwordHash. */
+const safeSelect = {
+  id: true,
+  name: true,
+  email: true,
+  role: true,
+  active: true,
+  createdAt: true,
+  updatedAt: true,
+} satisfies Prisma.UserSelect;
+
+export type SafeUserRow = Prisma.UserGetPayload<{ select: typeof safeSelect }>;
 
 @Injectable()
 export class UsersService {
   constructor(private readonly prisma: PrismaService) {}
 
+  // --- used by auth (need the hash / full row) -----------------------------
+
   findByEmail(email: string): Promise<User | null> {
     return this.prisma.user.findUnique({ where: { email } });
   }
@@ -13,4 +37,89 @@ export class UsersService {
   findById(id: string): Promise<User | null> {
     return this.prisma.user.findUnique({ where: { id } });
   }
+
+  // --- admin CRUD (safe rows only) -----------------------------------------
+
+  list(): Promise<SafeUserRow[]> {
+    return this.prisma.user.findMany({
+      orderBy: [{ active: "desc" }, { name: "asc" }],
+      select: safeSelect,
+    });
+  }
+
+  async create(dto: CreateUserDto): Promise<SafeUserRow> {
+    const passwordHash = await argon2.hash(dto.password);
+    try {
+      return await this.prisma.user.create({
+        data: {
+          name: dto.name,
+          email: dto.email,
+          passwordHash,
+          role: dto.role,
+          active: dto.active ?? true,
+        },
+        select: safeSelect,
+      });
+    } catch (e) {
+      throw this.mapError(e);
+    }
+  }
+
+  /**
+   * `actingUserId` is the admin making the change — used to stop an admin from
+   * locking themselves out (deactivating or demoting their own account).
+   */
+  async update(
+    id: string,
+    dto: UpdateUserDto,
+    actingUserId: string,
+  ): Promise<SafeUserRow> {
+    await this.ensureExists(id);
+
+    if (id === actingUserId) {
+      if (dto.active === false) {
+        throw new BadRequestException("No puede desactivar su propia cuenta");
+      }
+      if (dto.role && dto.role !== "ADMIN") {
+        throw new BadRequestException("No puede quitarse su propio rol de administrador");
+      }
+    }
+
+    try {
+      return await this.prisma.user.update({
+        where: { id },
+        data: {
+          name: dto.name,
+          email: dto.email,
+          role: dto.role,
+          active: dto.active,
+        },
+        select: safeSelect,
+      });
+    } catch (e) {
+      throw this.mapError(e);
+    }
+  }
+
+  async resetPassword(id: string, password: string): Promise<SafeUserRow> {
+    await this.ensureExists(id);
+    const passwordHash = await argon2.hash(password);
+    return this.prisma.user.update({
+      where: { id },
+      data: { passwordHash },
+      select: safeSelect,
+    });
+  }
+
+  private async ensureExists(id: string): Promise<void> {
+    const found = await this.prisma.user.findUnique({ where: { id }, select: { id: true } });
+    if (!found) throw new NotFoundException(`Usuario ${id} no encontrado`);
+  }
+
+  private mapError(e: unknown): Error {
+    if (e instanceof Prisma.PrismaClientKnownRequestError && e.code === "P2002") {
+      return new ConflictException("Ya existe un usuario con ese correo");
+    }
+    return e as Error;
+  }
 }