@aurostack/stacks 0.1.0

package/templates/nest-api/files/src/users/__tests__/users.service.spec.ts

@@ -0,0 +1,398 @@
+import { TestBed, type Mocked } from '@suites/unit';
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+import { Gen } from '@test/factory/gen';
+import { Entity } from '@test/factory/entity';
+import { Dto } from '@test/factory/dto';
+import { PrismaService } from 'common/services';
+import { UsersService } from '../services';
+import { PaginatedUserEntity, UserEntity } from '../entity';
+import { OKEntity } from 'common/entity';
+
+describe('UsersService', () => {
+	let service: UsersService;
+	let db: Mocked<PrismaService>;
+
+	beforeAll(async () => {
+		const { unit, unitRef } = await TestBed.solitary(UsersService).compile();
+		service = unit;
+		db = unitRef.get(PrismaService);
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+
+	describe('paginate', () => {
+		beforeEach(() => {
+			vi.clearAllMocks();
+			// Every role the specs filter by is one some user holds.
+			db.x.user.exists.mockResolvedValue(true);
+		});
+
+		const currentUser = Entity.requestUser.build({ role: 'admin' });
+		const getCallArgs = (): any => db.x.user.paginate.mock.calls[0][0];
+
+		it('should return a PaginatedUserEntity', async () => {
+			const users = Entity.user.buildList(3);
+			db.x.user.paginate.mockResolvedValue([
+				users,
+				{ total: 3, currentPage: 1, pageSize: 3, lastPage: 1 }
+			]);
+
+			const result = await service.paginate(currentUser, {});
+			expect(PaginatedUserEntity.safeParse(result).success).toBe(true);
+			expect(result.list).toHaveLength(3);
+			expect(result.total).toBe(3);
+		});
+
+		it('rejects a role no user holds, with a validation error', async () => {
+			db.x.user.exists.mockResolvedValue(false);
+
+			await expect(
+				service.paginate(currentUser, Dto.userFilters.build({ role: 'ghost' }))
+			).rejects.toThrow(
+				new BadRequestException("Validation: role 'ghost' does not exist")
+			);
+			expect(db.x.user.exists).toHaveBeenCalledWith({
+				role: { equals: 'ghost', mode: 'insensitive' }
+			});
+			expect(db.x.user.paginate).not.toHaveBeenCalled();
+		});
+
+		it('skips the role lookup when no role is given', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(currentUser, {});
+			expect(db.x.user.exists).not.toHaveBeenCalled();
+		});
+
+		it('should exclude the current user from results', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(currentUser, {});
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.id).toEqual({ not: currentUser.id });
+		});
+
+		// The listing is now an allowlist of visible roles rather than a single
+		// "not superuser" exclusion, so `moderator` is filterable and superusers
+		// are visible to their own tier.
+		it('restricts a non-superuser viewer to the non-superuser roles', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(currentUser, {});
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.role).toEqual({
+				in: ['user', 'moderator', 'admin']
+			});
+		});
+
+		it('lets a superuser see superusers too', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				Entity.requestUser.build({ role: 'superuser' }),
+				{}
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.role).toEqual({
+				in: ['user', 'moderator', 'admin', 'superuser']
+			});
+		});
+
+		it('should add search filter for name and email when search is provided', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ search: 'john' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.OR).toEqual([
+				{ email: { contains: 'john', mode: 'insensitive' } },
+				{ name: { contains: 'john', mode: 'insensitive' } }
+			]);
+		});
+
+		it('should trim the search string', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ search: '  john  ' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.OR).toEqual([
+				{ email: { contains: 'john', mode: 'insensitive' } },
+				{ name: { contains: 'john', mode: 'insensitive' } }
+			]);
+		});
+
+		it('should skip search filter when search is empty string', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ search: '' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.OR).toBeUndefined();
+		});
+
+		it('should skip search filter when search is only whitespace', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ search: '       ' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.OR).toBeUndefined();
+		});
+
+		it('should filter by role when role is "admin"', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ role: 'admin' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.role).toBe('admin');
+		});
+
+		it('should filter by role when role is "user"', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ role: 'user' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.role).toBe('user');
+		});
+
+		// The security-relevant path: an admin asking for superusers must not get
+		// them, and must not get an unfiltered listing either.
+		it('falls back to the visible roles when an admin filters by superuser', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ role: 'superuser' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.role).toEqual({
+				in: ['user', 'moderator', 'admin']
+			});
+		});
+
+		it('honours a superuser filtering by superuser', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				Entity.requestUser.build({ role: 'superuser' }),
+				Dto.userFilters.build({ role: 'superuser' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.role).toBe('superuser');
+		});
+
+		// Previously the role filter only accepted 'admin' | 'user', so asking for
+		// moderators silently returned everyone. That was a bug, not a policy.
+		it('should filter by role when role is "moderator"', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 1, pageSize: 0, lastPage: 1 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ role: 'moderator' })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.where.role).toBe('moderator');
+		});
+
+		it('should pass page and limit to paginate', async () => {
+			db.x.user.paginate.mockResolvedValue([
+				[],
+				{ total: 0, currentPage: 3, pageSize: 0, lastPage: 5 }
+			]);
+
+			await service.paginate(
+				currentUser,
+				Dto.userFilters.build({ page: 3, limit: 5 })
+			);
+
+			const callArgs = getCallArgs();
+			expect(callArgs.page).toBe(3);
+			expect(callArgs.limit).toBe(5);
+		});
+	});
+
+	describe('getUserById', () => {
+		// Takes the whole session user, not just an id: visibility depends on the
+		// viewer's role and has to agree with `paginate`.
+		const admin = Entity.requestUser.build({ role: 'admin' });
+		const superuser = Entity.requestUser.build({ role: 'superuser' });
+
+		it('should throw NotFoundException when looking up own ID', async () => {
+			await expect(service.getUserById(admin, admin.id)).rejects.toThrow(
+				NotFoundException
+			);
+		});
+
+		it('should throw NotFoundException when user does not exist', async () => {
+			const targetId = Gen.uuid();
+			db.user.findFirst.mockResolvedValue(null);
+
+			await expect(service.getUserById(admin, targetId)).rejects.toThrow(
+				NotFoundException
+			);
+		});
+
+		it('hides a superuser from an admin', async () => {
+			const targetId = Gen.uuid();
+			db.user.findFirst.mockResolvedValue(
+				Entity.user.build({ id: targetId, role: 'superuser' })
+			);
+
+			await expect(service.getUserById(admin, targetId)).rejects.toThrow(
+				NotFoundException
+			);
+		});
+
+		// The inconsistency this signature change fixed: `paginate` lists
+		// superusers to a superuser, so opening one must not 404.
+		it('shows a superuser to another superuser', async () => {
+			const targetId = Gen.uuid();
+			db.user.findFirst.mockResolvedValue(
+				Entity.user.build({ id: targetId, role: 'superuser' })
+			);
+
+			const result = await service.getUserById(superuser, targetId);
+			expect(UserEntity.safeParse(result).success).toBe(true);
+			expect(result.role).toBe('superuser');
+		});
+
+		it('reads a multi-role viewer, not just an exact match', async () => {
+			const targetId = Gen.uuid();
+			db.user.findFirst.mockResolvedValue(
+				Entity.user.build({ id: targetId, role: 'superuser' })
+			);
+
+			const result = await service.getUserById(
+				Entity.requestUser.build({ role: 'admin,superuser' }),
+				targetId
+			);
+			expect(UserEntity.safeParse(result).success).toBe(true);
+		});
+
+		it('should return UserEntity for a valid user', async () => {
+			const targetId = Gen.uuid();
+			db.user.findFirst.mockResolvedValue(
+				Entity.user.build({ id: targetId, role: 'user' })
+			);
+
+			const result = await service.getUserById(admin, targetId);
+			expect(UserEntity.safeParse(result).success).toBe(true);
+			expect(result.id).toBe(targetId);
+		});
+
+		it('should return UserEntity for an admin user', async () => {
+			const targetId = Gen.uuid();
+			db.user.findFirst.mockResolvedValue(
+				Entity.user.build({ id: targetId, role: 'admin' })
+			);
+
+			const result = await service.getUserById(admin, targetId);
+			expect(UserEntity.safeParse(result).success).toBe(true);
+			expect(result.role).toBe('admin');
+		});
+
+		it('should query by id', async () => {
+			const targetId = Gen.uuid();
+			db.user.findFirst.mockResolvedValue(
+				Entity.user.build({ id: targetId, role: 'user' })
+			);
+
+			await service.getUserById(admin, targetId);
+
+			expect(db.user.findFirst).toHaveBeenCalledWith({
+				where: { id: targetId }
+			});
+		});
+	});
+
+	describe('remove', () => {
+		it('should delete the user by id', async () => {
+			const userId = Gen.uuid();
+			db.user.delete.mockResolvedValue(Entity.user.build({ id: userId }));
+
+			await service.remove(userId);
+
+			expect(db.user.delete).toHaveBeenCalledWith({
+				where: { id: userId }
+			});
+		});
+
+		it('should return an OKEntity', async () => {
+			const userId = Gen.uuid();
+			db.user.delete.mockResolvedValue(Entity.user.build({ id: userId }));
+
+			const result = await service.remove(userId);
+			expect(OKEntity.safeParse(result).success).toBe(true);
+			expect(result.status).toBe(200);
+			expect(result.message).toBe('ok');
+		});
+	});
+});

package/templates/nest-api/files/src/users/controllers/current-user.controller.ts

@@ -0,0 +1,82 @@
+import {
+	BadRequestException, // @feature media
+	Controller,
+	Get,
+	HttpCode,
+	Post,
+	UploadedFile, // @feature media
+	UseInterceptors // @feature media
+} from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+import { ApiBadRequestResponse, ApiBody } from '@nestjs/swagger'; // @feature media
+import { FileInterceptor } from '@nestjs/platform-express'; // @feature media
+import { Session, UserSession } from '@thallesp/nestjs-better-auth';
+import { Op, Returns } from 'common/decorators';
+import { MultipartFormData } from 'common/decorators'; // @feature media
+import { FileEntity } from 'media/entity'; // @feature media
+import { CurrentUserService } from '../services';
+import { CurrentUserEntity, toCurrentUser } from '../entity';
+import { AVATAR_UPLOAD_SCHEMA } from '../dto'; // @feature media
+
+@ApiTags('Current User')
+@Controller({ path: 'user', version: '1' })
+export class CurrentUserController {
+	constructor(private service: CurrentUserService) {}
+
+	@Get()
+	@Op('user', '/v1/user', 'Get current user')
+	@Returns(CurrentUserEntity, { description: 'The current user' })
+	getCurrentUser(@Session() { user }: UserSession) {
+		return toCurrentUser(user);
+	}
+
+	@Post('onboarding')
+	@Op(
+		'completeOnboarding',
+		'/v1/user/onboarding',
+		"Mark the current user's onboarding as complete"
+	)
+	@HttpCode(200)
+	@Returns(CurrentUserEntity, { description: 'The updated user' })
+	completeOnboarding(@Session() { user }: UserSession) {
+		return this.service.completeOnboarding(user);
+	}
+
+	// @feature:start media
+	@Post('avatar')
+	@Op(
+		'avatar',
+		'/v1/user/avatar',
+		'Upload a new avatar image for the current user'
+	)
+	@MultipartFormData()
+	@ApiBody({ schema: AVATAR_UPLOAD_SCHEMA })
+	@UseInterceptors(
+		FileInterceptor('file', {
+			limits: { fileSize: 1 * 1024 * 1024 }, // 1MB limit
+			fileFilter: (req, file, cb) => {
+				if (!file.mimetype.match(/\/(jpg|jpeg|png|gif)$/)) {
+					return cb(
+						new BadRequestException(
+							'Only image files (jpg, jpeg, png, gif) are allowed for avatars'
+						),
+						false
+					);
+				}
+				cb(null, true);
+			}
+		})
+	)
+	@HttpCode(200)
+	@Returns(FileEntity, { description: 'The uploaded avatar file entity' })
+	@ApiBadRequestResponse({
+		description: 'Invalid file upload (e.g., wrong format, file too large)'
+	})
+	updateAvatar(
+		@Session() { user }: UserSession,
+		@UploadedFile() file: Express.Multer.File
+	) {
+		return this.service.updateAvatar(user, file);
+	}
+	// @feature:end
+}

package/templates/nest-api/files/src/users/controllers/index.ts

@@ -0,0 +1,2 @@
+export * from './current-user.controller';
+export * from './users.controller';

package/templates/nest-api/files/src/users/controllers/users.controller.ts

@@ -0,0 +1,40 @@
+import { Controller, Get, Param, Query } from '@nestjs/common';
+import {
+	ApiBadRequestResponse,
+	ApiNotFoundResponse,
+	ApiTags
+} from '@nestjs/swagger';
+import { Session, UserSession } from '@thallesp/nestjs-better-auth';
+import { IdParam, Op, Returns } from 'common/decorators';
+import { UserPermissions } from '../decorators';
+import { UsersService } from '../services';
+import { UserEntity, PaginatedUserEntity } from '../entity';
+import { UserFilters } from '../dto';
+
+@ApiTags('Users')
+@Controller({ path: 'users', version: '1' })
+export class UsersController {
+	constructor(private service: UsersService) {}
+
+	@Get()
+	@Op('users', '/v1/users', 'Get all users')
+	@Returns(PaginatedUserEntity)
+	@UserPermissions('list')
+	findAll(
+		@Query({ schema: UserFilters }) filters: UserFilters,
+		@Session() { user }: UserSession
+	) {
+		return this.service.paginate(user, filters);
+	}
+
+	@Get(':id')
+	@Op('users/:id', '/v1/users/:id', 'Get user by ID')
+	@IdParam()
+	@ApiBadRequestResponse()
+	@Returns(UserEntity)
+	@ApiNotFoundResponse({ description: 'User not found' })
+	@UserPermissions('get')
+	async findOne(@Param('id') id: string, @Session() { user }: UserSession) {
+		return this.service.getUserById(user, id);
+	}
+}

package/templates/nest-api/files/src/users/decorators/index.ts

@@ -0,0 +1 @@
+export * from './permissions.decorator';

package/templates/nest-api/files/src/users/decorators/permissions.decorator.ts

@@ -0,0 +1,24 @@
+import { applyDecorators } from '@nestjs/common';
+import { UserHasPermission } from '@thallesp/nestjs-better-auth';
+import type { PermissionAction, Permission } from 'lib/access';
+
+/**
+ * Thin, typed wrappers over better-auth's `UserHasPermission`. Add one per
+ * resource you declare in `lib/access.ts` — the `PermissionAction<'x'>` type
+ * argument is what makes a typo'd action a compile error instead of a check
+ * that silently never passes.
+ */
+export function UserPermissions(...actions: PermissionAction<'user'>[]) {
+	return applyDecorators(UserHasPermission({ permission: { user: actions } }));
+}
+
+export function SessionPermissions(...actions: PermissionAction<'session'>[]) {
+	return applyDecorators(
+		UserHasPermission({ permission: { session: actions } })
+	);
+}
+
+/** Escape hatch for a multi-resource check. */
+export function Permissions(permissions: Permission) {
+	return applyDecorators(UserHasPermission({ permissions }));
+}

package/templates/nest-api/files/src/users/dto/avatar.dto.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { SchemaObject } from '@nestjs/swagger';
+import { binary } from 'common/schemas';
+
+/**
+ * The avatar upload body. Documentation only: the file itself arrives through
+ * FileInterceptor, which the validation pipe does not see.
+ */
+export const AvatarUpload = z.object({ file: binary() });
+
+export const AVATAR_UPLOAD_SCHEMA = z.toJSONSchema(AvatarUpload, {
+	target: 'openapi-3.0'
+}) as SchemaObject;

package/templates/nest-api/files/src/users/dto/filters.dto.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { CommonFilters } from 'common/dto';
+
+export const UserFilters = CommonFilters.extend({
+	// Whether any user holds this role is checked in UsersService, against the DB.
+	role: z.string().optional()
+});
+export type UserFilters = z.output<typeof UserFilters>;

package/templates/nest-api/files/src/users/dto/index.ts

@@ -0,0 +1,2 @@
+export * from './avatar.dto'; // @feature media
+export * from './filters.dto';

package/templates/nest-api/files/src/users/entity/index.ts

@@ -0,0 +1 @@
+export * from './user.entity';

package/templates/nest-api/files/src/users/entity/user.entity.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { UserSession } from '@thallesp/nestjs-better-auth';
+import { faker as F } from '@faker-js/faker';
+import { dateTime, email } from 'common/schemas';
+import { paginated } from 'common/entity';
+
+export const UserEntity = z
+	.object({
+		id: z.string(),
+		name: z.string().meta({ example: F.person.fullName() }),
+		email: email(),
+		emailVerified: z.boolean(),
+		image: z.string().nullable().meta({ example: F.image.avatar() }),
+		createdAt: dateTime(),
+		updatedAt: dateTime(),
+		role: z.string().nullable().meta({ example: 'user' }),
+		banned: z.boolean().nullable().meta({ example: false }),
+		banReason: z.string().nullable().meta({ example: 'Violation of terms' }),
+		banExpires: dateTime().nullable(),
+		onboardingCompletedAt: dateTime().nullable()
+	})
+	.meta({ id: 'UserEntity' });
+/** What a service hands back; the schema turns it into the response. */
+export type UserEntity = z.input<typeof UserEntity>;
+
+export const PaginatedUserEntity = paginated(UserEntity, 'PaginatedUserEntity');
+export type PaginatedUserEntity = z.input<typeof PaginatedUserEntity>;
+
+export const CurrentUserEntity = UserEntity.omit({
+	banned: true,
+	banReason: true,
+	banExpires: true
+}).meta({ id: 'CurrentUserEntity' });
+export type CurrentUserEntity = z.input<typeof CurrentUserEntity>;
+
+/** Shape a better-auth session user into a {@link CurrentUserEntity}. */
+export function toCurrentUser(user: UserSession['user']): CurrentUserEntity {
+	return {
+		id: user.id,
+		name: user.name,
+		email: user.email,
+		emailVerified: user.emailVerified,
+		image: user.image || null,
+		createdAt: user.createdAt,
+		updatedAt: user.updatedAt,
+		// better-auth may hand back several roles; the first is the primary one.
+		role: (Array.isArray(user.role) ? user.role[0] : user.role) || null,
+		// additionalField — not present on the inferred session-user type.
+		onboardingCompletedAt:
+			(user as { onboardingCompletedAt?: Date | null }).onboardingCompletedAt ??
+			null
+	};
+}

package/templates/nest-api/files/src/users/services/current-user.service.ts

@@ -0,0 +1,46 @@
+import { Injectable } from '@nestjs/common';
+import { UserSession } from '@thallesp/nestjs-better-auth';
+import { PrismaService } from 'common/services';
+import { MediaService } from 'media/services'; // @feature media
+import { FileEntity } from 'media/entity'; // @feature media
+import { CurrentUserEntity, toCurrentUser } from '../entity';
+
+@Injectable()
+export class CurrentUserService {
+	constructor(
+		private media: MediaService, // @feature media
+		private db: PrismaService
+	) {}
+
+	// @feature:start media
+	async updateAvatar(
+		user: UserSession['user'],
+		file: Express.Multer.File
+	): Promise<FileEntity> {
+		const image = await this.media.uploadAvatar(file);
+		if (user.image) {
+			this.media.deleteFile(user.image);
+		}
+		await this.db.user.update({
+			where: { id: user.id },
+			data: { image }
+		});
+		return { path: image };
+	}
+	// @feature:end
+
+	/**
+	 * Stamp the user's onboarding as complete (idempotent — re-stamps on repeat).
+	 * Called when the wizard finishes or is skipped so the first-run gate stops
+	 * redirecting them.
+	 */
+	async completeOnboarding(
+		user: UserSession['user']
+	): Promise<CurrentUserEntity> {
+		const updated = await this.db.user.update({
+			where: { id: user.id },
+			data: { onboardingCompletedAt: new Date() }
+		});
+		return toCurrentUser(updated as unknown as UserSession['user']);
+	}
+}

package/templates/nest-api/files/src/users/services/index.ts

@@ -0,0 +1,2 @@
+export * from './current-user.service';
+export * from './users.service';