Guards for Authorisation

// src/auth/roles.decorator.ts
import { Reflector } from '@nestjs/core';
import type { Role } from '../users/user.js';

// Creates a decorator that takes ONE argument of type Role[].
// Usage is @Roles(['admin']) - an array, not a list of arguments.
export const Roles = Reflector.createDecorator<Role[]>();

// The longhand it replaces. These two guards do the same thing:
//
//   @SetMetadata('roles', ['admin'])        // on the handler
//   this.reflector.getAllAndOverride<Role[]>('roles', [
//     context.getHandler(),
//     context.getClass(),
//   ]);                                      // in the guard
//
// The string key is untyped on both sides, so a typo in either place
// compiles and the guard just reads undefined. createDecorator() ties
// the key and the value type together, which is why it is preferred.

// src/orders/orders.controller.ts
import { Controller, Get, Param, Post, UseGuards } from '@nestjs/common';
import { RolesGuard } from '../auth/roles.guard.js';
import { Roles } from '../auth/roles.decorator.js';
import { OrdersService } from './orders.service.js';

@Controller('orders')
// Applies to every handler in this controller. @UseGuards() also accepts
// a comma-separated list, which then runs in the order written.
@UseGuards(RolesGuard)
@Roles(['customer', 'staff'])
export class OrdersController {
  constructor(private readonly orders: OrdersService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.orders.findOne(id);
  }

  // Overrides the controller-level @Roles() for this handler only,
  // because the guard uses getAllAndOverride().
  @Roles(['staff'])
  @Post(':id/refund')
  refund(@Param('id') id: string) {
    return this.orders.refund(id);
  }
}

// src/orders/orders.service.ts
import { ForbiddenException, Injectable, NotFoundException } from '@nestjs/common';
import type { User } from '../users/user.js';
import { OrdersRepository } from './orders.repository.js';

@Injectable()
export class OrdersService {
  constructor(private readonly repository: OrdersRepository) {}

  async findOne(user: User, id: string) {
    const order = await this.repository.findById(id);

    // 404 before the ownership check, so a caller cannot use the
    // 403/404 difference to learn which order ids exist.
    if (!order) {
      throw new NotFoundException();
    }

    // This is the check a route guard could not make: it needs the row.
    // The guard already established that the caller may use this route.
    const isOwner = order.userId === user.id;
    const isStaff = user.roles.includes('staff');
    if (!isOwner && !isStaff) {
      throw new ForbiddenException();
    }

    return order;
  }

  async findAll(user: User) {
    // Lists are filtered in the query, not checked record by record.
    // A per-row check after loading every order is both slow and easy
    // to forget on the next endpoint that lists orders.
    return user.roles.includes('staff')
      ? this.repository.findAll()
      : this.repository.findAllByUser(user.id);
  }
}

// src/orders/order.policy.ts
// npm i @nestjs/authorization
// EXPERIMENTAL: version 0.0.1, published days before this was written.
// The CanActivate guard above is the stable way to do this today.
import { Policy } from '@nestjs/authorization';
import type { User } from '../users/user.js';
import type { Order } from './order.js';

// A policy is an ordinary provider. Each method whose first parameter is
// the user is an "ability". Only a literal true allows; any other value,
// even a truthy one, denies.
@Policy()
export class OrderPolicy {
  // No record to pass, so a route guard can call this one with @Can() -
  // but only because the user parameter accepts null. @Can() rejects an
  // ability typed `user: User`, since it cannot know whether a route has
  // a signed-in user; such an ability is for services only.
  viewAll(user: User | null) {
    return !!user?.roles.includes('staff');
  }

  // Takes the order, so only a service that has loaded it can ask.
  view(user: User, order: Order) {
    return order.userId === user.id || user.roles.includes('staff');
  }

  refund(user: User, order: Order) {
    return user.roles.includes('staff') && order.status === 'paid';
  }
}

// src/orders/orders.service.ts
import { Injectable } from '@nestjs/common';
import { AuthorizationService } from '@nestjs/authorization';
import { OrderPolicy } from './order.policy.js';
import type { User } from '../users/user.js';
import { OrdersRepository } from './orders.repository.js';

@Injectable()
export class OrdersService {
  constructor(
    private readonly authorization: AuthorizationService,
    private readonly repository: OrdersRepository,
  ) {}

  async findAll(user: User) {
    // can() resolves to true or false and decides the query.
    return (await this.authorization.can(OrderPolicy, 'viewAll', user))
      ? this.repository.findAll()
      : this.repository.findAllByUser(user.id);
  }

  async refund(user: User, id: string) {
    const order = await this.repository.findByIdOrFail(id);
    // authorize() throws when the ability denies. AuthorizationModule
    // turns that into a 401 or a 403 once it leaves the handler.
    await this.authorization.authorize(OrderPolicy, 'refund', user, order);
    return this.repository.markRefunded(order);
  }
}