@aurostack/stacks 0.1.0

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

@@ -0,0 +1,88 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { UserSession } from '@thallesp/nestjs-better-auth';
+import { Prisma } from '@db/client';
+import { PrismaService } from 'common/services';
+import { ensureExists } from 'common/utils';
+import { hasRole, type RoleInput } from 'lib/access';
+import { PaginatedUserEntity, UserEntity } from '../entity';
+import { UserFilters } from '../dto';
+import { ok } from 'common/entity';
+
+const SU = 'superuser';
+
+/**
+ * Roles a viewer may see. Superusers are visible only to their own tier —
+ * everyone below sees user / moderator / admin.
+ */
+const visibleRolesFor = (role: RoleInput): string[] =>
+	hasRole(role, SU)
+		? ['user', 'moderator', 'admin', SU]
+		: ['user', 'moderator', 'admin'];
+
+@Injectable()
+export class UsersService {
+	constructor(private db: PrismaService) {}
+
+	async paginate(
+		user: UserSession['user'],
+		filters: UserFilters
+	): Promise<PaginatedUserEntity> {
+		await ensureExists(this.db, 'user', 'role', filters.role);
+
+		const where: Prisma.UserWhereInput = {
+			id: { not: user.id }
+		};
+		if (filters.search && filters.search.trim() !== '') {
+			const search = filters.search.trim();
+			where.OR = [
+				{ email: { contains: search, mode: 'insensitive' } },
+				{ name: { contains: search, mode: 'insensitive' } }
+			];
+		}
+
+		// `hasRole`, not `user.role === SU`: better-auth stores role as a
+		// comma-separated string, so a user holding "admin,superuser" fails a
+		// straight equality. See `lib/access.ts`.
+		const visibleRoles = visibleRolesFor(user.role);
+
+		// An out-of-range role (a non-superuser asking for superusers) narrows to
+		// the whole visible set rather than leaking — never to an unfiltered list.
+		where.role =
+			filters.role && visibleRoles.includes(filters.role)
+				? filters.role
+				: { in: visibleRoles };
+
+		const [list, meta] = await this.db.x.user.paginate({
+			where,
+			page: filters.page,
+			limit: filters.limit
+		});
+
+		return { list, ...meta };
+	}
+
+	/**
+	 * Takes the whole session user, not just an id, because visibility depends on
+	 * the viewer's role — it has to agree with {@link paginate}. Before, a
+	 * superuser could see other superusers in the listing and then 404 opening
+	 * one, which is what the admin drawer does on row click.
+	 */
+	async getUserById(
+		viewer: UserSession['user'],
+		id: string
+	): Promise<UserEntity> {
+		if (viewer.id === id) throw new NotFoundException();
+		const user = await this.db.user.findFirst({ where: { id } });
+		if (!user) throw new NotFoundException();
+		// 404 rather than 403 — a hidden user shouldn't be confirmed to exist.
+		if (!visibleRolesFor(viewer.role).includes(user.role ?? 'user')) {
+			throw new NotFoundException();
+		}
+		return user;
+	}
+
+	async remove(id: string) {
+		await this.db.user.delete({ where: { id } });
+		return ok();
+	}
+}

package/templates/nest-api/files/src/users/users.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { CurrentUserController, UsersController } from './controllers';
+import { CurrentUserService, UsersService } from './services';
+
+@Module({
+	imports: [],
+	controllers: [CurrentUserController, UsersController],
+	providers: [CurrentUserService, UsersService]
+})
+export class UsersModule {}

package/templates/nest-api/files/test/app.spec.ts

@@ -0,0 +1,102 @@
+import { AppFactory } from '@test/factory/app';
+import { SWAGGER_OPTIONS } from 'common/constants';
+
+describe('App', () => {
+	let app: AppFactory;
+
+	beforeAll(async () => {
+		app = await AppFactory.init();
+	});
+
+	afterAll(async () => {
+		await app.close();
+	});
+
+	describe('GET: /', () => {
+		let status: number;
+		let body: any;
+		let headers: Record<string, string>;
+
+		beforeAll(async () => {
+			const response = await app.request.get('/');
+			status = response.status;
+			body = response.body;
+			headers = response.headers as Record<string, string>;
+		});
+
+		it('should have 200 status', () => {
+			expect(status).toBe(200);
+		});
+
+		it('should return object with app title and description', () => {
+			const {
+				info: { title, description }
+			} = SWAGGER_OPTIONS;
+			expect(body).toStrictEqual({ title, description });
+		});
+
+		it('should apply basic security headers via helmet', () => {
+			// A small subset of headers that helmet sets by default
+			expect(headers['x-dns-prefetch-control']).toBeDefined();
+			expect(headers['x-content-type-options']).toBe('nosniff');
+			expect(headers['x-frame-options']).toBeDefined();
+		});
+	});
+
+	describe('GET: /non-existent', () => {
+		it('should return 404 for unknown route', async () => {
+			const response = await app.request.get('/non-existent');
+			expect(response.status).toBe(404);
+			expect(response.body).toMatchObject({
+				statusCode: 404
+			});
+			expect(typeof response.body.message).toBe('string');
+		});
+	});
+
+	describe('GET: /openapi-json', () => {
+		it('should expose OpenAPI document', async () => {
+			const response = await app.request.get('/openapi-json');
+			expect(response.status).toBe(200);
+			expect(response.headers['content-type']).toContain('application/json');
+			const body = response.body as any;
+			expect(body).toHaveProperty('openapi');
+			const {
+				info: { title }
+			} = SWAGGER_OPTIONS;
+			expect(body.info.title).toBe(title);
+		});
+	});
+
+	describe('GET: /docs', () => {
+		it('should serve API documentation UI', async () => {
+			const response = await app.request.get('/docs');
+			expect(response.status).toBe(200);
+			expect(response.headers['content-type']).toContain('text/html');
+		});
+	});
+
+	// @feature:start graphql
+	describe('POST: /graphql', () => {
+		it('should answer the root info query', async () => {
+			const response = await app.request
+				.post('/graphql')
+				.send({ query: '{ info { title description } }' });
+			expect(response.status).toBe(200);
+			const { info } = SWAGGER_OPTIONS;
+			expect(response.body.data.info).toEqual({
+				title: info.title,
+				description: info.description
+			});
+		});
+	});
+	// @feature:end
+
+	describe('OPTIONS: / (CORS preflight)', () => {
+		it('should respond with CORS headers for allowed origin', async () => {
+			const response = await app.request.get('/');
+			expect(response.headers['vary']).toContain('Origin');
+			expect(response.headers['access-control-allow-credentials']).toBe('true');
+		});
+	});
+});

package/templates/nest-api/files/test/auth.spec.ts

@@ -0,0 +1,108 @@
+import { Response } from 'supertest';
+import { AppFactory } from '@test/factory/app';
+import { SUPER_USER } from '@test/factory/constants';
+
+describe('Auth', () => {
+	let app: AppFactory;
+
+	beforeAll(async () => {
+		app = await AppFactory.init();
+		await app.refresh();
+	});
+
+	afterAll(async () => {
+		await app.close();
+	});
+
+	describe('Sign in with email [ /auth/sign-in/email ]', () => {
+		describe('with valid credentials', () => {
+			let response: Response;
+			let cookie: string | undefined;
+
+			beforeAll(async () => {
+				const result = await app.signIn(SUPER_USER.email, SUPER_USER.password);
+				response = result.response;
+				cookie = result.cookie;
+			});
+
+			it('should succeed with logged in user', () => {
+				expect(response.status).toBe(200);
+				expect(response.body).toHaveProperty('user');
+				expect(response.body.user).toHaveProperty('email', SUPER_USER.email);
+			});
+
+			it('should establish a session (cookie)', () => {
+				expect(cookie).toBeDefined();
+			});
+
+			describe('Protected route: /auth/get-session', () => {
+				let res: Response;
+
+				beforeAll(async () => {
+					res = await app.request
+						.get('/auth/get-session')
+						.set('Cookie', cookie!);
+				});
+
+				it('should allow access with valid session cookie', () => {
+					expect(res.status).toBe(200);
+				});
+
+				it('should return the session information', async () => {
+					expect(res.body).toHaveProperty('session');
+					expect(res.body.session).toMatchObject({
+						id: expect.any(String),
+						expiresAt: expect.any(String),
+						token: expect.any(String),
+						createdAt: expect.any(String),
+						updatedAt: expect.any(String),
+						ipAddress: expect.any(String),
+						userAgent: expect.any(String),
+						userId: expect.any(String),
+						impersonatedBy: null
+					});
+				});
+
+				it('should return the user information', async () => {
+					expect(res.body).toHaveProperty('user');
+					expect(res.body.user).toHaveProperty('name', SUPER_USER.name);
+					expect(res.body.user).toHaveProperty('email', SUPER_USER.email);
+				});
+			});
+		});
+
+		describe('otherwise', () => {
+			let response: Response;
+			let cookie: string | undefined;
+
+			beforeAll(async () => {
+				const result = await app.signIn('wrong@example.com', 'invalid');
+				response = result.response;
+				cookie = result.cookie;
+			});
+
+			it('should return error for wrong credentials', async () => {
+				expect([400, 401]).toContain(response.status);
+			});
+
+			it('should NOT set a session cookie', () => {
+				expect(cookie).toBeUndefined();
+			});
+
+			describe('Protected route: /auth/get-session', () => {
+				let res: Response;
+
+				beforeAll(async () => {
+					res = await app.request
+						.get('/auth/get-session')
+						.set('Cookie', cookie || '');
+				});
+
+				it('should NOT allow access', () => {
+					expect(res.status).toBe(200);
+					expect(res.body).toBeNull();
+				});
+			});
+		});
+	});
+});

package/templates/nest-api/files/test/current-user.spec.ts

@@ -0,0 +1,154 @@
+import { Response } from 'supertest';
+import { AppFactory } from '@test/factory/app';
+import { SUPER_USER, TEST_ADMIN, TEST_USER } from '@test/factory/constants';
+
+describe('Current User', () => {
+	let app: AppFactory;
+	let superuserCookie: string;
+	let adminCookie: string;
+	let userCookie: string;
+
+	beforeAll(async () => {
+		app = await AppFactory.init();
+		await app.refresh();
+
+		const superuserResult = await app.signIn(
+			SUPER_USER.email,
+			SUPER_USER.password
+		);
+		superuserCookie = superuserResult.cookie!;
+
+		const adminResult = await app.signIn(TEST_ADMIN.email, TEST_ADMIN.password);
+		adminCookie = adminResult.cookie!;
+
+		const userResult = await app.signIn(TEST_USER.email, TEST_USER.password);
+		userCookie = userResult.cookie!;
+	});
+
+	afterAll(async () => {
+		await app.close();
+	});
+
+	describe('v1', () => {
+		describe('GET: /v1/user', () => {
+			describe('as superuser', () => {
+				let response: Response;
+
+				beforeAll(async () => {
+					response = await app.request
+						.get('/v1/user')
+						.set('Cookie', superuserCookie);
+				});
+
+				it('should return 200', () => {
+					expect(response.status).toBe(200);
+				});
+
+				it('should return current user data', () => {
+					expect(response.body).toHaveProperty('id');
+					expect(response.body).toHaveProperty('name');
+					expect(response.body).toHaveProperty('email', SUPER_USER.email);
+					expect(response.body).toHaveProperty('emailVerified');
+					expect(response.body).toHaveProperty('createdAt');
+					expect(response.body).toHaveProperty('updatedAt');
+				});
+
+				it('should include role', () => {
+					expect(response.body).toHaveProperty('role');
+					expect(response.body.role).toBe('superuser');
+				});
+			});
+
+			describe('as admin', () => {
+				let response: Response;
+
+				beforeAll(async () => {
+					response = await app.request
+						.get('/v1/user')
+						.set('Cookie', adminCookie);
+				});
+
+				it('should return 200', () => {
+					expect(response.status).toBe(200);
+				});
+
+				it('should return admin user data', () => {
+					expect(response.body.email).toBe(TEST_ADMIN.email);
+					expect(response.body.name).toBe(TEST_ADMIN.name);
+				});
+
+				it('should have admin role', () => {
+					expect(response.body.role).toBe('admin');
+				});
+			});
+
+			describe('as regular user', () => {
+				let response: Response;
+
+				beforeAll(async () => {
+					response = await app.request
+						.get('/v1/user')
+						.set('Cookie', userCookie);
+				});
+
+				it('should return 200', () => {
+					expect(response.status).toBe(200);
+				});
+
+				it('should return regular user data', () => {
+					expect(response.body.email).toBe(TEST_USER.email);
+					expect(response.body.name).toBe(TEST_USER.name);
+				});
+
+				it('should have user role', () => {
+					expect(response.body.role).toBe('user');
+				});
+			});
+
+			describe('without authentication', () => {
+				let response: Response;
+
+				beforeAll(async () => {
+					response = await app.request.get('/v1/user');
+				});
+
+				it('should return 401', () => {
+					expect(response.status).toBe(401);
+				});
+			});
+
+			describe('response shape', () => {
+				let response: Response;
+
+				beforeAll(async () => {
+					response = await app.request
+						.get('/v1/user')
+						.set('Cookie', userCookie);
+				});
+
+				it('should not expose banned fields', () => {
+					expect(response.body).not.toHaveProperty('banned');
+					expect(response.body).not.toHaveProperty('banReason');
+					expect(response.body).not.toHaveProperty('banExpires');
+				});
+
+				it('should have image field (nullable)', () => {
+					expect(response.body).toHaveProperty('image');
+				});
+
+				it('should have emailVerified as boolean', () => {
+					expect(typeof response.body.emailVerified).toBe('boolean');
+				});
+			});
+		});
+
+		describe('GET: /user (without version)', () => {
+			it('should return 404 when version prefix is missing', async () => {
+				const response = await app.request
+					.get('/user')
+					.set('Cookie', userCookie);
+				expect(response.status).toBe(404);
+			});
+		});
+	});
+});

package/templates/nest-api/files/test/factory/app.ts

@@ -0,0 +1,172 @@
+import { INestApplication } from '@nestjs/common';
+import { Test, TestingModule } from '@nestjs/testing';
+import supertest from 'supertest';
+import { vi } from 'vitest';
+import { AppModule } from 'app.module';
+import { CustomConfigService, PrismaService } from 'common/services';
+import { CacheService } from 'common/services'; // @feature cache
+import { MailService } from 'common/services'; // @feature mail
+import { FeatureFlagService } from 'common/services'; // @feature feature-flags
+import { MediaService } from 'media/services'; // @feature media
+import Seeder from '@seeders/util';
+import * as setup from 'app.setup';
+
+type Cookie = string[] | undefined;
+
+// @feature:start feature-flags
+/** Per-spec overrides for the integrations AppFactory replaces. */
+type AppFactoryOverrides = {
+	flags?: Partial<FeatureFlagService>;
+};
+// @feature:end
+
+/**
+ * Boots the *real* Nest application against the real test Postgres and Redis —
+ * only the outbound integrations are replaced. Mirrors `app.setup.ts`, so a
+ * global pipe or filter added there has to be added here too or e2e will pass
+ * on behaviour production does not have.
+ *
+ * Always `await app.close()` in `afterAll`: it triggers `refresh()`, and a spec
+ * that skips it leaves rows behind for the next one.
+ */
+export class AppFactory {
+	private constructor(private readonly app: INestApplication) {}
+
+	get instance() {
+		return this.app;
+	}
+
+	get server() {
+		return this.app.getHttpServer();
+	}
+
+	get request() {
+		return supertest(this.server);
+	}
+
+	get db() {
+		return this.app.get(PrismaService);
+	}
+
+	// @feature:start cache
+	get cache() {
+		return this.app.get(CacheService);
+	}
+	// @feature:end
+
+	get config() {
+		return this.app.get(CustomConfigService);
+	}
+
+	async refresh() {
+		await this.db.truncate();
+		await this.cache.truncate(); // @feature cache
+		await this.seed();
+	}
+
+	async seed() {
+		await Seeder.setup(this.db).seed(this.config.superuser, true);
+	}
+
+	async signIn(email: string, password: string) {
+		const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+		const response = await this.request.post('/auth/sign-in/email').send({
+			email,
+			password
+		});
+		errorSpy.mockRestore();
+
+		const setCookie = response.headers['set-cookie'] as unknown as Cookie;
+		const cookie = setCookie?.[0];
+		return { cookie, response };
+	}
+
+	async close() {
+		await this.refresh();
+		await this.app.close();
+	}
+
+	static async init(
+		overrides: AppFactoryOverrides = {} // @feature feature-flags
+	) {
+		// @feature:start mail
+		// No-op MailService so nothing is enqueued to the BullMQ `mail` queue.
+		// cache.truncate() (Redis flushall) runs between specs and would wipe
+		// in-flight job keys, making the worker throw "Missing key for job N".
+		// (Listed explicitly — a Proxy that answers every prop, incl. `then`,
+		// makes this look thenable and Nest DI hangs awaiting it.)
+		const mailMock: Record<keyof MailService, ReturnType<typeof vi.fn>> = {
+			activation: vi.fn(),
+			activationTwofa: vi.fn(),
+			welcome: vi.fn(),
+			forgotPassword: vi.fn(),
+			resetPassword: vi.fn(),
+			passwordChanged: vi.fn(),
+			setPassword: vi.fn()
+		};
+		// @feature:end
+
+		// @feature:start feature-flags
+		// Treat every feature flag as ON in tests by default, so flag-gated
+		// routes behave deterministically without reaching the real GrowthBook
+		// API at boot. Specs can override per-flag behaviour via `overrides.flags`.
+		const flagsMock: Partial<FeatureFlagService> = {
+			isOn: () => true,
+			isOff: () => false,
+			getValue: (_key, defaultValue) => defaultValue as never,
+			refresh: vi.fn(),
+			...overrides.flags
+		};
+		// @feature:end
+
+		// @feature:start media
+		// In-memory MediaService so uploads never touch real S3. Buffers are kept
+		// keyed by their fake URL so an async worker can re-read what was uploaded.
+		const mediaFiles = new Map<string, Buffer>();
+		const mediaMock: Partial<Record<keyof MediaService, unknown>> = {
+			uploadAvatar: vi.fn(async () => 'https://test.local/avatars/mock.png'),
+			uploadFile: vi.fn(async (file: Express.Multer.File) => {
+				const url = `https://test.local/uploads/${Math.random()
+					.toString(36)
+					.slice(2)}`;
+				mediaFiles.set(url, file.buffer);
+				return url;
+			}),
+			getFileBuffer: vi.fn(
+				async (url: string) => mediaFiles.get(url) ?? Buffer.alloc(0)
+			),
+			deleteFile: vi.fn(async () => {})
+		};
+		// @feature:end
+
+		const module: TestingModule = await Test.createTestingModule({
+			imports: [AppModule]
+		})
+			.overrideProvider(MailService) // @feature mail
+			.useValue(mailMock) // @feature mail
+			.overrideProvider(MediaService) // @feature media
+			.useValue(mediaMock) // @feature media
+			.overrideProvider(FeatureFlagService) // @feature feature-flags
+			.useValue(flagsMock) // @feature feature-flags
+			.compile();
+
+		const app = module.createNestApplication({
+			bodyParser: false,
+			bufferLogs: true
+		});
+
+		setup.usePinoLogger(app);
+		setup.enableVersioning(app);
+		setup.setStatic(app);
+		setup.enableJsonBodyParser(app);
+		setup.useGlobalPipes(app);
+		setup.useGlobalInterceptors(app);
+		setup.useGlobalFilters(app);
+		await setup.enableOpenAPI(app); // @feature openapi
+		setup.enableCors(app);
+		setup.enableHelmet(app);
+
+		await app.init();
+		return new AppFactory(app);
+	}
+}

package/templates/nest-api/files/test/factory/constants.ts

@@ -0,0 +1,22 @@
+import 'dotenv/config';
+
+export const SUPER_USER = {
+	name: 'Super User',
+	email: process.env.SUPERUSER_EMAIL || 'superuser@example.com',
+	password: process.env.SUPERUSER_PASSWORD || 'Secret@1',
+	role: 'superuser'
+};
+
+export const TEST_ADMIN = {
+	name: 'Test Admin',
+	email: 'test.admin@example.com',
+	password: 'secret',
+	role: 'admin'
+};
+
+export const TEST_USER = {
+	name: 'Test User',
+	email: 'test.user@example.com',
+	password: 'secret',
+	role: 'user'
+};

package/templates/nest-api/files/test/factory/dto.ts

@@ -0,0 +1,27 @@
+import { Factory } from 'fishery';
+import type { z } from 'zod';
+import { CommonFilters } from 'common/dto';
+import { UserFilters } from 'users/dto'; // @feature users
+
+export class Dto {
+	/**
+	 * Run a request schema over `plain` the way the validation pipe does, and
+	 * return the Zod result (`success`, then `data` or `error`).
+	 */
+	static parse<T extends z.ZodType>(schema: T, plain: unknown) {
+		return schema.safeParse(plain);
+	}
+
+	static get commonFilters() {
+		return Factory.define<CommonFilters>(() => ({}));
+	}
+
+	// @feature:start users
+	static get userFilters() {
+		return Factory.define<UserFilters>(() => ({
+			page: 1,
+			limit: 10
+		}));
+	}
+	// @feature:end
+}