NestJS Integration

const SHOP_POLICY = policy<ShopSubject, ShopObjects, ShopVerbs>({
  version: SHOP_MATRIX_VERSION,
  schema: SHOP_SCHEMA,
})
  .for('game', (p) =>
    p
      .allow('read', p.always)
      .visibility('public')
      // The operator grant and the manager grant are separate rules, so a
      // reader strikes one out without touching the other.
      .allow(
        'declare',
        p.contains('subject.roles', 'operator'),
        p.eq('object.shop', 'subject.shop'),
      )
      .allow(
        'declare',
        p.contains('subject.roles', 'manager'),
        p.eq('object.shop', 'subject.shop'),
      )
      .fields({
        fields: ['availability'],
        availability: { targets: [...AVAILABILITIES] },
      })
      .visibility('public')
      .allow(
        'reprice',
        p.contains('subject.roles', 'manager'),
        p.eq('object.shop', 'subject.shop'),
      )
      .fields({
        fields: ['availability', 'price'],
        availability: { targets: [...AVAILABILITIES] },
      })
      .visibility('public'),
  )
  .for('order', (p) =>
    p
      .allow('create', p.contains('subject.roles', 'customer'))
      .visibility('public'),
  )
  .for('telemetry', (p) =>
    p
      .allow('read', p.contains('subject.roles', 'manager'))
      .visibility('public'),
  )
  // No marking, so `serialize(access, 'reduced')` drops it: the browsers never
  // ask about stock, and a contract carrying a rule nobody evaluates is a
  // larger surface for nothing.
  .for('inventory', (p) => p.allow('read', p.always));

export function buildShopAccess(): Access<ShopSubject, ShopObjects> {
  return hydratePolicy<ShopSubject, ShopObjects>(SHOP_MATRIX);
}

@Module({})
export class AclModule {
  /**
   * Builds the matrix once and returns the module, registered `global: true`.
   *
   * Global for the reason `CorrelationModule.forRoot()` states about its own
   * registration: `AclGuard`, `GamesService`, `InventoryClient` and
   * `SubjectMiddleware` all resolve `ACL_ACCESS` or `SubjectService` from the
   * root injector, and without it every one of those modules would import this
   * one.
   *
   * `AclGuard` is bound under `APP_GUARD`, so it runs on every route in the
   * application and the `@Requires` metadata decides which routes it actually
   * gates. A route carrying no metadata is waved through by the guard itself.
   *
   * Call it once. A second `forRoot()` registers a second `ACL_ACCESS`
   * provider under the same token and the last import wins.
   */
  static forRoot(): DynamicModule {
    const accessProvider: Provider = {
      provide: ACL_ACCESS,
      // hydratePolicy runs here and nowhere else, so the process holds one
      // frozen document and a construction failure stops the boot.
      useValue: buildShopAccess(),
    };
 
    return {
      global: true,
      module: AclModule,
      controllers: [PolicyController],
      providers: [
        accessProvider,
        SubjectService,
        { provide: APP_GUARD, useClass: AclGuard },
      ],
      exports: [accessProvider, SubjectService],
    };
  }
}

export const ACL_ACCESS = '@evanion/shop-api:ACL_ACCESS';

@Injectable()
export class SubjectService {
  private readonly storage = new AsyncLocalStorage<ShopSubject>();
 
  /**
   * Runs `callback` with `subject` as the actor. Everything it awaits,
   * schedules or calls reads that subject, and overlapping requests stay
   * isolated.
   *
   * `SubjectMiddleware` does this per request. Call it directly for work no
   * request drives, such as a queue consumer or a seeding script.
   */
  run<T>(subject: ShopSubject, callback: () => T): T {
    return this.storage.run(subject, callback);
  }
 
  /**
   * The subject of the surrounding context, or `undefined` outside one.
   *
   * It invents no subject. A caller that needs one refuses when this answers
   * `undefined`, because a decision made against a subject nobody stated is a
   * decision made against nothing.
   */
  current(): ShopSubject | undefined {
    return this.storage.getStore();
  }
}

@Injectable()
export class SubjectMiddleware implements NestMiddleware {
  constructor(private readonly subjects: SubjectService) {}
 
  use(
    req: IncomingMessage,
    _res: ServerResponse,
    next: (error?: unknown) => void,
  ): void {
    const header = singleValue(req.headers[SHOP_SUBJECT_HEADER.toLowerCase()]);
    this.subjects.run(subjectFrom(header), next);
  }
}

export const Requires = (key: RequiredPermission['key'], action: string) =>
  SetMetadata<string, RequiredPermission>(REQUIRES_PERMISSION, { key, action });

@Injectable()
export class AclGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,
    private readonly subjects: SubjectService,
    @Inject(ACL_ACCESS)
    private readonly access: Access<ShopSubject, ShopObjects>,
  ) {}
 
  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<
      RequiredPermission | undefined
    >(REQUIRES_PERMISSION, [context.getHandler(), context.getClass()]);
 
    if (!required) return true;
 
    const subject = this.subjects.current();
    // SubjectMiddleware runs on every route and falls back to the anonymous
    // subject, so this is reached only where the middleware did not run, which
    // is a request nothing resolved an actor for.
    if (!subject) throw new UnauthorizedException();
 
    const decision = this.access.can(subject, required.key, required.action);
    if (decision.allowed) return true;
 
    // A permission whose rules read `object.*` is decided by the service on the
    // row it loads, whatever `can` answered here without one.
    if (this.access.readsObject(required.key, required.action)) return true;
 
    throw new ForbiddenException(decision.reason);
  }
}

declare(urn: string, proposed: GameDeclaration): Game {
  const game = this.findByUrn(urn);
  const subject = this.subjects.current();
  if (!subject) throw new UnauthorizedException();
 
  const action = 'price' in proposed ? 'reprice' : 'declare';
  const decision = this.access.canFields(
    subject,
    'game',
    action,
    game,
    'write',
    proposed,
  );
  if (!decision.action.allowed) {
    throw new ForbiddenException(decision.action.reason);
  }
 
  // pickAllowedFields keeps the keys the decision marked `allowed` and
  // nothing else, so a denied key and an unevaluable key are both withheld.
  const writable = pickAllowedFields(decision, proposed);
  if (Object.keys(writable).length === 0) {
    throw new BadRequestException('No field of this declaration is writable');
  }
 
  this.declared.set(urn, { ...this.declared.get(urn), ...writable });
  return this.findByUrn(urn);
}

it('lets an operator change a title their own shop lists', () => {
  const service = serviceFor(STOCKHOLM_OPERATOR);
 
  const game = service.declare(STOCKHOLM_TITLE, {
    availability: 'preorder',
  });
 
  expect(game.availability).toBe('preorder');
  expect(service.findByUrn(STOCKHOLM_TITLE).availability).toBe('preorder');
});
 
it('refuses the same operator on a title another shop lists', () => {
  const service = serviceFor(STOCKHOLM_OPERATOR);
 
  expect(() =>
    service.declare(GOTHENBURG_TITLE, { availability: 'preorder' }),
  ).toThrow(ForbiddenException);
});

@Controller('policy')
export class PolicyController {
  constructor(
    @Inject(ACL_ACCESS)
    private readonly access: Access<ShopSubject, ShopObjects>,
  ) {}
 
  @Get()
  read(): PolicyDocument {
    const matrix = serialize(this.access, 'reduced');
    return { version: matrix.version, matrix };
  }
}

const controllerFor = async (subject: ShopSubject) => {
  const module = await Test.createTestingModule({
    controllers: [GamesController],
    providers: [
      GamesService,
      FeaturesService,
      { provide: ACL_ACCESS, useValue: buildShopAccess() },
      { provide: SHOP_FEATURES, useValue: buildShopFeatures() },
      { provide: SubjectService, useValue: { current: () => subject } },
    ],
  }).compile();
  return module.get(GamesController);
};