@gadmin2n/schematics 0.0.139 → 0.0.140

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/subjectProvider/providers/user.provider.ts

@@ -0,0 +1,168 @@
+import { Injectable } from '@nestjs/common';
+import { User } from '@prisma/client';
+import { UserService } from '../../user/user.service';
+import {
+  SubjectProviderCapabilityError,
+  SubjectProviderUnavailableError,
+} from '../subject-provider.errors';
+import {
+  ActorContext,
+  ProviderValidationIssue,
+  ResolveContext,
+  ResolvedPrincipal,
+  SubjectPreview,
+  SubjectProvider,
+  SubjectProviderDescriptor,
+  SubjectResource,
+} from '../subject-provider.types';
+
+@Injectable()
+export class UserProvider implements SubjectProvider {
+  readonly key = 'USER';
+  constructor(private readonly users: UserService) {}
+
+  descriptor(_actor: ActorContext): SubjectProviderDescriptor {
+    return {
+      key: this.key,
+      label: 'Users',
+      referenceFormat: 'STRING',
+      principalType: 'USER',
+      capabilities: {
+        search: true,
+        preview: true,
+        inlineCreate: false,
+        edit: false,
+        emitsChanges: false,
+      },
+    };
+  }
+
+  async search(
+    query: string,
+    _actor: ActorContext,
+  ): Promise<SubjectResource[]> {
+    const q = query.trim();
+    try {
+      const { entities } = await this.users.findMany({
+        where: {
+          isActive: true,
+          ...(q && {
+            OR: [
+              { userid: { contains: q, mode: 'insensitive' } },
+              { username: { contains: q, mode: 'insensitive' } },
+            ],
+          }),
+        },
+        orderBy: { userid: 'asc' },
+        take: 50,
+      });
+      return entities.map((user) => this.resource(user));
+    } catch {
+      throw new SubjectProviderUnavailableError(this.key);
+    }
+  }
+
+  async create(
+    _input: Record<string, unknown>,
+    _actor: ActorContext,
+  ): Promise<SubjectResource> {
+    throw new SubjectProviderCapabilityError(
+      'SUBJECT_PROVIDER_CREATE_NOT_SUPPORTED',
+      this.key,
+    );
+  }
+
+  async validate(refs: string[]) {
+    const { unique, duplicates } = this.normalize(refs);
+    const users = await this.find(unique);
+    const byRef = new Map(users.map((user) => [user.userid, user]));
+    const issues: ProviderValidationIssue[] = duplicates.map((ref) => ({
+      ref,
+      code: 'DUPLICATE_REF',
+      message: `Duplicate user reference: ${ref}`,
+    }));
+    for (const ref of unique) {
+      const user = byRef.get(ref);
+      if (!user)
+        issues.push({
+          ref,
+          code: 'NOT_FOUND',
+          message: `User not found: ${ref}`,
+        });
+      else if (!user.isActive)
+        issues.push({
+          ref,
+          code: 'INACTIVE',
+          message: `User is inactive: ${ref}`,
+        });
+    }
+    return { valid: issues.length === 0, ...(issues.length ? { issues } : {}) };
+  }
+
+  async preview(refs: string[]): Promise<SubjectPreview> {
+    const { unique } = this.normalize(refs);
+    const users = await this.find(unique);
+    const byRef = new Map(users.map((user) => [user.userid, user]));
+    return {
+      items: unique.flatMap((ref) => {
+        const user = byRef.get(ref);
+        return user
+          ? [
+              {
+                ...this.resource(user),
+                principals: [this.principal(user, ref)],
+              },
+            ]
+          : [];
+      }),
+    };
+  }
+
+  async resolve(
+    refs: string[],
+    _context: ResolveContext,
+  ): Promise<ResolvedPrincipal[]> {
+    const users = await this.find(this.normalize(refs).unique);
+    return users
+      .filter((user) => user.isActive)
+      .map((user) => this.principal(user, user.userid))
+      .sort((a, b) => a.principalRef.localeCompare(b.principalRef));
+  }
+
+  private async find(refs: string[]): Promise<User[]> {
+    if (!refs.length) return [];
+    try {
+      return (await this.users.findMany({ where: { userid: { in: refs } } }))
+        .entities;
+    } catch {
+      throw new SubjectProviderUnavailableError(this.key);
+    }
+  }
+
+  private resource(user: User): SubjectResource {
+    return {
+      ref: user.userid,
+      label: user.username ?? user.userid,
+      ...(user.description ? { description: user.description } : {}),
+      active: user.isActive,
+    };
+  }
+
+  private principal(user: User, sourceRef: string): ResolvedPrincipal {
+    return {
+      principalType: 'USER',
+      principalRef: user.userid,
+      displayName: user.username ?? user.userid,
+      sourceRefs: [sourceRef],
+    };
+  }
+
+  private normalize(refs: string[]) {
+    const seen = new Set<string>(),
+      duplicateSet = new Set<string>();
+    const unique: string[] = [];
+    for (const ref of refs)
+      seen.has(ref) ? duplicateSet.add(ref) : (seen.add(ref), unique.push(ref));
+    return { unique, duplicates: [...duplicateSet] };
+  }
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/subjectProvider/subject-provider.controller.spec.ts

@@ -0,0 +1,157 @@
+/// <reference types="jest" />
+import { ACGuard } from '@gadmin2n/nest-common';
+import { GUARDS_METADATA } from '@nestjs/common/constants';
+import { SubjectProviderController } from './subject-provider.controller';
+import {
+  SubjectProviderError,
+  SubjectProviderUnavailableError,
+} from './subject-provider.errors';
+import { SubjectProviderRegistry } from './subject-provider.registry';
+import { ActorContext, SubjectProvider } from './subject-provider.types';
+
+const actorRequest = {
+  user: {
+    userid: 'user-1',
+    username: 'alice',
+    roles: ['SPOOFED_FROM_AUTH_PAYLOAD'],
+    configPerms: { roles: ['EDITOR'] },
+    permissions: {
+      'read:subjectProviderSearch:any': { granted: true },
+      denied: { granted: false },
+    },
+    credentials: 'must-not-leak',
+  },
+} as any;
+
+function makeProvider(): jest.Mocked<SubjectProvider> {
+  return {
+    key: 'USER',
+    descriptor: jest.fn().mockReturnValue({
+      key: 'USER',
+      label: 'Users',
+      referenceFormat: 'STRING',
+      principalType: 'USER',
+      capabilities: {
+        search: true,
+        preview: true,
+        inlineCreate: true,
+        edit: false,
+        emitsChanges: false,
+      },
+    }),
+    search: jest.fn().mockResolvedValue([{ ref: 'alice', label: 'Alice' }]),
+    create: jest.fn().mockResolvedValue({ ref: 'bob', label: 'Bob' }),
+    validate: jest.fn().mockResolvedValue({ valid: true }),
+    preview: jest.fn().mockResolvedValue({ items: [] }),
+    resolve: jest.fn().mockResolvedValue([]),
+  };
+}
+
+describe('SubjectProviderController', () => {
+  let registry: SubjectProviderRegistry;
+  let provider: jest.Mocked<SubjectProvider>;
+  let controller: SubjectProviderController;
+
+  beforeEach(() => {
+    registry = new SubjectProviderRegistry();
+    provider = makeProvider();
+    registry.register(provider);
+    controller = new SubjectProviderController(registry);
+  });
+
+  it('requires authentication and the endpoint-specific server permissions', () => {
+    // AuthGuard and RolesGuard are global in main.ts; this local guard enforces
+    // each @UseRoles declaration without resetting the enriched request user.
+    expect(
+      Reflect.getMetadata(GUARDS_METADATA, SubjectProviderController),
+    ).toEqual([ACGuard]);
+
+    const rolesFor = (method: keyof SubjectProviderController) =>
+      Reflect.getMetadata('roles', SubjectProviderController.prototype[method]);
+    expect(rolesFor('list')).toEqual([
+      { resource: 'subjectProviderSearch', action: 'read', possession: 'any' },
+    ]);
+    expect(rolesFor('search')).toEqual(rolesFor('list'));
+    expect(rolesFor('create')).toEqual([
+      {
+        resource: 'subjectProviderCreate',
+        action: 'create',
+        possession: 'any',
+      },
+    ]);
+    expect(rolesFor('preview')).toEqual([
+      { resource: 'subjectProviderPreview', action: 'read', possession: 'any' },
+    ]);
+    expect(rolesFor('validate')).toEqual(rolesFor('preview'));
+  });
+
+  it('lists descriptors and delegates search with a minimal actor copy', async () => {
+    await expect(controller.list(actorRequest)).resolves.toHaveLength(1);
+    await expect(
+      controller.search('USER', { q: 'ali' }, actorRequest),
+    ).resolves.toEqual([{ ref: 'alice', label: 'Alice' }]);
+
+    const actor = provider.search.mock.calls[0][1] as ActorContext;
+    expect(actor).toEqual({
+      userId: 'user-1',
+      username: 'alice',
+      roles: ['EDITOR'],
+      permissions: ['read:subjectProviderSearch:any'],
+    });
+    expect(actor).not.toBe(actorRequest.user);
+  });
+
+  it('rejects unsupported inline creation before calling the provider', async () => {
+    provider.descriptor.mockReturnValue({
+      ...provider.descriptor(actorRequest.user),
+      capabilities: {
+        ...provider.descriptor(actorRequest.user).capabilities,
+        inlineCreate: false,
+      },
+    });
+
+    await expect(
+      controller.create('USER', {}, actorRequest),
+    ).rejects.toMatchObject({
+      code: 'SUBJECT_PROVIDER_CREATE_NOT_SUPPORTED',
+      response: { code: 'SUBJECT_PROVIDER_CREATE_NOT_SUPPORTED' },
+    });
+    expect(provider.create).not.toHaveBeenCalled();
+  });
+
+  it('delegates preview and validation without changing stable refs', async () => {
+    const refs = ['group:ops', 'user:alice'];
+    await controller.preview('USER', { refs }, actorRequest);
+    await controller.validate('USER', { refs }, actorRequest);
+
+    expect(provider.preview).toHaveBeenCalledWith(refs, expect.any(Object));
+    expect(provider.validate).toHaveBeenCalledWith(refs, expect.any(Object));
+  });
+
+  it('preserves provider errors and sanitizes unexpected failures', async () => {
+    const native = new SubjectProviderError(
+      'SUBJECT_PROVIDER_UNAVAILABLE',
+      'safe provider message',
+    );
+    provider.search.mockRejectedValueOnce(native);
+    await expect(
+      controller.search('USER', { q: 'x' }, actorRequest),
+    ).rejects.toBe(native);
+    expect(native.getResponse()).toEqual({
+      code: 'SUBJECT_PROVIDER_UNAVAILABLE',
+      message: 'safe provider message',
+    });
+
+    provider.search.mockRejectedValueOnce(
+      new Error('password=super-secret database.example.internal'),
+    );
+    await expect(
+      controller.search('USER', { q: 'x' }, actorRequest),
+    ).rejects.toEqual(
+      expect.objectContaining<Partial<SubjectProviderUnavailableError>>({
+        code: 'SUBJECT_PROVIDER_UNAVAILABLE',
+        message: 'Subject provider is unavailable: USER',
+      }),
+    );
+  });
+});

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/subjectProvider/subject-provider.controller.ts

@@ -0,0 +1,176 @@
+import { ACGuard } from '@gadmin2n/nest-common';
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Get,
+  Param,
+  Post,
+  Query,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+import { UseRoles } from 'nest-access-control';
+import {
+  actorContextFromRequest,
+  AuthenticatedActorRequest,
+} from './actor-context.util';
+import {
+  SubjectRefsDto,
+  SubjectResourceSearchQueryDto,
+} from './subject-provider.dto';
+import {
+  SubjectProviderCapabilityError,
+  SubjectProviderError,
+  SubjectProviderUnavailableError,
+} from './subject-provider.errors';
+import { SubjectProviderRegistry } from './subject-provider.registry';
+import { SubjectProvider } from './subject-provider.types';
+
+@ApiTags('subject-providers')
+// Authentication + role hydration are global (main.ts). Re-running AuthGuard
+// here would replace the hydrated user before ACGuard evaluates @UseRoles.
+@UseGuards(ACGuard)
+@Controller('subject-providers')
+export class SubjectProviderController {
+  constructor(private readonly registry: SubjectProviderRegistry) {}
+
+  @Get()
+  @UseRoles({
+    resource: 'subjectProviderSearch',
+    action: 'read',
+    possession: 'any',
+  })
+  async list(@Req() request: AuthenticatedActorRequest) {
+    const actor = this.actorFrom(request);
+    try {
+      return this.registry.listDescriptors(actor);
+    } catch (error) {
+      this.rethrowProviderError(error, 'registry');
+    }
+  }
+
+  @Get(':key/resources')
+  @UseRoles({
+    resource: 'subjectProviderSearch',
+    action: 'read',
+    possession: 'any',
+  })
+  search(
+    @Param('key') key: string,
+    @Query() query: SubjectResourceSearchQueryDto,
+    @Req() request: AuthenticatedActorRequest,
+  ) {
+    const actor = this.actorFrom(request);
+    return this.callProvider(key, async (provider) => {
+      const descriptor = provider.descriptor(actor);
+      if (!descriptor.capabilities.search) {
+        throw new SubjectProviderCapabilityError(
+          'SUBJECT_PROVIDER_SEARCH_NOT_SUPPORTED',
+          key,
+        );
+      }
+      return provider.search(query.q ?? '', actor);
+    });
+  }
+
+  @Post(':key/resources')
+  @UseRoles({
+    resource: 'subjectProviderCreate',
+    action: 'create',
+    possession: 'any',
+  })
+  create(
+    @Param('key') key: string,
+    @Body() input: Record<string, unknown>,
+    @Req() request: AuthenticatedActorRequest,
+  ) {
+    this.assertObjectInput(input);
+    const actor = this.actorFrom(request);
+    return this.callProvider(key, async (provider) => {
+      const descriptor = provider.descriptor(actor);
+      if (!descriptor.capabilities.inlineCreate) {
+        throw new SubjectProviderCapabilityError(
+          'SUBJECT_PROVIDER_CREATE_NOT_SUPPORTED',
+          key,
+        );
+      }
+      return provider.create(input, actor);
+    });
+  }
+
+  @Post(':key/validate')
+  @UseRoles({
+    resource: 'subjectProviderPreview',
+    action: 'read',
+    possession: 'any',
+  })
+  validate(
+    @Param('key') key: string,
+    @Body() body: SubjectRefsDto,
+    @Req() request: AuthenticatedActorRequest,
+  ) {
+    const actor = this.actorFrom(request);
+    return this.callProvider(key, (provider) =>
+      provider.validate(body.refs, actor),
+    );
+  }
+
+  @Post(':key/preview')
+  @UseRoles({
+    resource: 'subjectProviderPreview',
+    action: 'read',
+    possession: 'any',
+  })
+  preview(
+    @Param('key') key: string,
+    @Body() body: SubjectRefsDto,
+    @Req() request: AuthenticatedActorRequest,
+  ) {
+    const actor = this.actorFrom(request);
+    return this.callProvider(key, async (provider) => {
+      const descriptor = provider.descriptor(actor);
+      if (!descriptor.capabilities.preview) {
+        throw new SubjectProviderCapabilityError(
+          'SUBJECT_PROVIDER_PREVIEW_NOT_SUPPORTED',
+          key,
+        );
+      }
+      return provider.preview(body.refs, actor);
+    });
+  }
+
+  private async callProvider<T>(
+    key: string,
+    operation: (provider: SubjectProvider) => Promise<T> | T,
+  ): Promise<T> {
+    try {
+      return await operation(this.registry.get(key));
+    } catch (error) {
+      this.rethrowProviderError(error, key);
+    }
+  }
+
+  private rethrowProviderError(error: unknown, key: string): never {
+    if (
+      error instanceof SubjectProviderError ||
+      error instanceof SubjectProviderCapabilityError
+    ) {
+      throw error;
+    }
+    throw new SubjectProviderUnavailableError(key);
+  }
+
+  private actorFrom(request: AuthenticatedActorRequest) {
+    return actorContextFromRequest(request);
+  }
+
+  private assertObjectInput(
+    input: unknown,
+  ): asserts input is Record<string, unknown> {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+      throw new BadRequestException('create input must be an object');
+    }
+  }
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/subjectProvider/subject-provider.dto.ts

@@ -0,0 +1,21 @@
+import {
+  ArrayNotEmpty,
+  IsArray,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+
+export class SubjectResourceSearchQueryDto {
+  @IsOptional()
+  @IsString()
+  q?: string;
+}
+
+export class SubjectRefsDto {
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsString({ each: true })
+  @IsNotEmpty({ each: true })
+  refs: string[];
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/subjectProvider/subject-provider.errors.ts

@@ -0,0 +1,78 @@
+export type SubjectProviderErrorCode =
+  | 'SUBJECT_PROVIDER_NOT_FOUND'
+  | 'SUBJECT_PROVIDER_DUPLICATE'
+  | 'SUBJECT_PROVIDER_UNAVAILABLE';
+
+export type SubjectProviderCapabilityErrorCode =
+  | 'SUBJECT_PROVIDER_SEARCH_NOT_SUPPORTED'
+  | 'SUBJECT_PROVIDER_CREATE_NOT_SUPPORTED'
+  | 'SUBJECT_PROVIDER_PREVIEW_NOT_SUPPORTED';
+
+export class SubjectProviderError extends Error {
+  constructor(public readonly code: SubjectProviderErrorCode, message: string) {
+    super(message);
+    this.name = 'SubjectProviderError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  getStatus(): number {
+    if (this.code === 'SUBJECT_PROVIDER_NOT_FOUND') return 404;
+    if (this.code === 'SUBJECT_PROVIDER_DUPLICATE') return 409;
+    return 503;
+  }
+
+  getResponse(): { code: SubjectProviderErrorCode; message: string } {
+    return { code: this.code, message: this.message };
+  }
+}
+
+export class SubjectProviderNotFoundError extends SubjectProviderError {
+  constructor(key: string) {
+    super('SUBJECT_PROVIDER_NOT_FOUND', `Subject provider not found: ${key}`);
+    this.name = 'SubjectProviderNotFoundError';
+  }
+}
+
+export class SubjectProviderDuplicateError extends SubjectProviderError {
+  constructor(key: string) {
+    super('SUBJECT_PROVIDER_DUPLICATE', `duplicate provider key: ${key}`);
+    this.name = 'SubjectProviderDuplicateError';
+  }
+}
+
+export class SubjectProviderUnavailableError extends SubjectProviderError {
+  constructor(key: string, message?: string) {
+    super(
+      'SUBJECT_PROVIDER_UNAVAILABLE',
+      message ?? `Subject provider is unavailable: ${key}`,
+    );
+    this.name = 'SubjectProviderUnavailableError';
+  }
+}
+
+/** HTTP-facing capability failure; provider-native errors remain untouched. */
+export class SubjectProviderCapabilityError extends Error {
+  readonly response: {
+    code: SubjectProviderCapabilityErrorCode;
+    message: string;
+  };
+
+  constructor(
+    public readonly code: SubjectProviderCapabilityErrorCode,
+    providerKey: string,
+  ) {
+    const message = `Subject provider capability is not supported: ${providerKey}`;
+    super(message);
+    this.name = 'SubjectProviderCapabilityError';
+    this.response = { code, message };
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  getStatus(): number {
+    return 400;
+  }
+
+  getResponse(): { code: SubjectProviderCapabilityErrorCode; message: string } {
+    return this.response;
+  }
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/subjectProvider/subject-provider.registry.spec.ts

@@ -0,0 +1,100 @@
+import { SubjectProviderRegistry } from './subject-provider.registry';
+import { ActorContext, SubjectProvider } from './subject-provider.types';
+
+const actor: ActorContext = { userId: 'alice' };
+
+function fakeProvider(
+  key: string,
+  label = key,
+  inlineCreate = false,
+): SubjectProvider {
+  return {
+    key,
+    descriptor: (currentActor) => ({
+      key,
+      label,
+      referenceFormat: 'STRING',
+      principalType: 'USER',
+      capabilities: {
+        search: true,
+        preview: true,
+        inlineCreate:
+          inlineCreate && currentActor.permissions?.includes('create') === true,
+        edit: false,
+        emitsChanges: false,
+      },
+      createSchema: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+      },
+    }),
+    search: async () => [],
+    create: async () => ({ ref: 'ref', label: 'Resource' }),
+    validate: async () => ({ valid: true }),
+    preview: async () => ({ items: [] }),
+    resolve: async () => [],
+  };
+}
+
+describe('SubjectProviderRegistry', () => {
+  it('registers and gets providers by any stable key', () => {
+    const registry = new SubjectProviderRegistry();
+    const provider = fakeProvider('DEPARTMENT');
+
+    registry.register(provider);
+
+    expect(registry.get('DEPARTMENT')).toBe(provider);
+  });
+
+  it('rejects duplicate and empty provider keys', () => {
+    const registry = new SubjectProviderRegistry();
+    registry.register(fakeProvider('USER'));
+
+    expect(() => registry.register(fakeProvider('USER'))).toThrow(
+      expect.objectContaining({ code: 'SUBJECT_PROVIDER_DUPLICATE' }),
+    );
+    expect(() => registry.register(fakeProvider('   '))).toThrow();
+  });
+
+  it('returns a coded error for a missing provider', () => {
+    const registry = new SubjectProviderRegistry();
+
+    expect(() => registry.get('MISSING')).toThrow(
+      expect.objectContaining({ code: 'SUBJECT_PROVIDER_NOT_FOUND' }),
+    );
+  });
+
+  it('builds actor-specific, sorted descriptors without exposing provider state', () => {
+    const registry = new SubjectProviderRegistry();
+    const sourceDescriptor = fakeProvider('ROLE', 'Zulu').descriptor(actor);
+    const roleProvider = fakeProvider('ROLE', 'unused');
+    roleProvider.descriptor = (currentActor) => ({
+      ...sourceDescriptor,
+      capabilities: {
+        ...sourceDescriptor.capabilities,
+        inlineCreate: currentActor.permissions?.includes('create') === true,
+      },
+    });
+    registry.register(roleProvider);
+    registry.register(fakeProvider('USER_GROUP', 'Alpha', true));
+
+    const descriptors = registry.listDescriptors({
+      userId: 'admin',
+      permissions: ['create'],
+    });
+
+    expect(descriptors.map(({ key }) => key)).toEqual(['USER_GROUP', 'ROLE']);
+    expect(descriptors[1].capabilities.inlineCreate).toBe(true);
+    expect(Object.isFrozen(descriptors)).toBe(true);
+    expect(Object.isFrozen(descriptors[0].capabilities)).toBe(true);
+    expect(() => {
+      (descriptors[1].capabilities as { inlineCreate: boolean }).inlineCreate =
+        false;
+    }).toThrow();
+    expect(sourceDescriptor.capabilities.inlineCreate).toBe(false);
+    expect(
+      registry.listDescriptors({ userId: 'viewer' })[1].capabilities
+        .inlineCreate,
+    ).toBe(false);
+  });
+});