@aurostack/stacks 0.1.0

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

@@ -0,0 +1,70 @@
+import { Factory } from 'fishery';
+import { faker as F } from '@faker-js/faker';
+import { UserSession } from '@thallesp/nestjs-better-auth';
+import { User } from '@db/client';
+import { ok } from 'common/entity';
+import { FileEntity } from 'media/entity'; // @feature media
+
+export class Entity {
+	static get ok() {
+		return ok();
+	}
+
+	static get user() {
+		return Factory.define<User>(() => ({
+			id: F.string.uuid(),
+			name: F.person.fullName(),
+			email: F.internet.email(),
+			image: F.image.avatar(),
+			emailVerified: F.datatype.boolean(),
+			banned: F.datatype.boolean(),
+			banReason: F.lorem.sentence(),
+			role: 'user',
+			banExpires: null,
+			onboardingCompletedAt: null,
+			createdAt: new Date(),
+			updatedAt: new Date()
+		}));
+	}
+
+	static get requestUser() {
+		return Factory.define<UserSession['user']>(() => ({
+			id: F.string.uuid(),
+			name: F.person.fullName(),
+			email: F.internet.email(),
+			image: F.image.avatar(),
+			emailVerified: F.datatype.boolean(),
+			banned: F.datatype.boolean(),
+			banReason: F.lorem.sentence(),
+			role: 'user',
+			banExpires: null,
+			createdAt: new Date(),
+			updatedAt: new Date()
+		}));
+	}
+
+	static get userSession() {
+		return Factory.define<UserSession>(() => {
+			const user = Entity.requestUser.build();
+			return {
+				user,
+				session: {
+					id: F.string.uuid(),
+					userId: user.id,
+					expiresAt: new Date(Date.now() + 1000 * 60 * 60), // 1 hour from now
+					token: F.string.alphanumeric(16),
+					createdAt: new Date(),
+					updatedAt: new Date()
+				}
+			};
+		});
+	}
+
+	// @feature:start media
+	static get file() {
+		return Factory.define<FileEntity>(() => ({
+			path: F.image.avatar()
+		}));
+	}
+	// @feature:end
+}

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

@@ -0,0 +1,75 @@
+import { createId as CUID } from '@paralleldrive/cuid2';
+import { faker as F } from '@faker-js/faker';
+import crypto from 'crypto';
+import { generate } from 'randomstring';
+
+interface EmailOptions {
+	firstName?: string | undefined;
+	lastName?: string | undefined;
+	provider?: string | undefined;
+	allowSpecialCharacters?: boolean | undefined;
+}
+
+interface UsernameOptions {
+	firstName?: string | undefined;
+	lastName?: string | undefined;
+}
+
+interface PasswordOptions {
+	length?: number | undefined;
+	memorable?: boolean | undefined;
+	pattern?: RegExp | undefined;
+	prefix?: string | undefined;
+}
+
+const DEFAULT_ROLES = ['superuser', 'admin', 'user'];
+const SAMPLE_ROLES = [
+	...DEFAULT_ROLES,
+	'user_manager',
+	'moderator',
+	'analytics_user',
+	'guest',
+	'content_editor'
+];
+
+export class Gen {
+	static numeric(length: number) {
+		return generate({ charset: 'numeric', length });
+	}
+
+	static alphabet(size = 64) {
+		return crypto.randomBytes(size).toString('hex');
+	}
+
+	static uuid() {
+		return F.string.uuid();
+	}
+
+	static cuid() {
+		return CUID();
+	}
+
+	static fullName(sex?: 'female' | 'male') {
+		return `${F.person.firstName(sex)} ${F.person.lastName(sex)}`;
+	}
+
+	static email(options?: EmailOptions) {
+		return F.internet.email(options);
+	}
+
+	static username(options?: UsernameOptions) {
+		return F.internet.userName(options);
+	}
+
+	static password(options?: PasswordOptions) {
+		return F.internet.password(options);
+	}
+
+	static defaultRole() {
+		return F.helpers.arrayElement(DEFAULT_ROLES);
+	}
+
+	static role() {
+		return F.helpers.arrayElement(SAMPLE_ROLES);
+	}
+}

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

@@ -0,0 +1,21 @@
+import { ExecutionContext } from '@nestjs/common';
+import { createMock, DeepMocked } from '@golevelup/ts-vitest';
+
+namespace Util {
+	export type Context = DeepMocked<ExecutionContext>;
+
+	export class ExceptionNotThrownError extends Error {
+		constructor() {
+			super('Exception not thrown');
+			this.name = 'ExceptionNotThrownError';
+		}
+	}
+
+	export class Mock {
+		static executionContext() {
+			return createMock<ExecutionContext>();
+		}
+	}
+}
+
+export { Util };

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

@@ -0,0 +1,176 @@
+import { AppFactory } from '@test/factory/app';
+import { TEST_ADMIN, TEST_USER } from '@test/factory/constants';
+import { NotificationsService } from 'notifications/services/notifications.service';
+
+describe('Notifications', () => {
+	let app: AppFactory;
+	let userCookie: string;
+	let adminCookie: string;
+	let userId: string;
+
+	// Seed through the service's write side — the same call other modules make —
+	// so these specs exercise the endpoints without depending on any producer.
+	const dispatch = (recipientId = userId, data: object = { message: 'Hi' }) =>
+		app.instance
+			.get(NotificationsService)
+			.dispatch(recipientId, 'system', data);
+
+	const listNotifications = (cookie: string, query = '') =>
+		app.request.get(`/v1/notifications${query}`).set('Cookie', cookie);
+
+	const unreadCount = (cookie: string) =>
+		app.request.get('/v1/notifications/unread-count').set('Cookie', cookie);
+
+	beforeAll(async () => {
+		app = await AppFactory.init();
+	});
+
+	afterAll(async () => {
+		await app.close();
+	});
+
+	beforeEach(async () => {
+		await app.refresh();
+		userCookie = (await app.signIn(TEST_USER.email, TEST_USER.password))
+			.cookie!;
+		adminCookie = (await app.signIn(TEST_ADMIN.email, TEST_ADMIN.password))
+			.cookie!;
+		const session = await app.request
+			.get('/auth/get-session')
+			.set('Cookie', userCookie);
+		userId = session.body.user.id;
+	});
+
+	describe('OpenAPI', () => {
+		it('lists the notification routes in /openapi-json', async () => {
+			const response = await app.request.get('/openapi-json');
+			expect(response.status).toBe(200);
+			const paths = Object.keys(response.body.paths ?? {});
+			expect(paths).toEqual(
+				expect.arrayContaining([
+					'/v1/notifications',
+					'/v1/notifications/unread-count',
+					'/v1/notifications/{id}/read',
+					'/v1/notifications/read-all'
+				])
+			);
+		});
+	});
+
+	describe('OpenAPI components', () => {
+		it('documents the notification type from the Prisma enum', async () => {
+			const doc = (await app.request.get('/openapi-json')).body;
+			const { type } = doc.components.schemas.NotificationEntity.properties;
+			expect([...type.enum].sort()).toEqual(
+				['comment', 'mention', 'reply', 'system'].sort()
+			);
+		});
+	});
+
+	describe('GET /v1/notifications', () => {
+		it('rejects unauthenticated requests with 401', async () => {
+			const response = await listNotifications('');
+			expect(response.status).toBe(401);
+		});
+
+		it('starts empty for a fresh user', async () => {
+			const response = await listNotifications(userCookie);
+			expect(response.status).toBe(200);
+			expect(response.body.list).toEqual([]);
+			expect(response.body.total).toBe(0);
+		});
+	});
+
+	describe('dispatch', () => {
+		it('lists a dispatched notification for its recipient', async () => {
+			await dispatch(userId, { message: 'Welcome aboard' });
+
+			const response = await listNotifications(userCookie);
+			expect(response.status).toBe(200);
+			expect(response.body.total).toBe(1);
+			expect(response.body.list[0]).toMatchObject({
+				userId,
+				type: 'system',
+				readAt: null,
+				data: { message: 'Welcome aboard' }
+			});
+		});
+
+		it("does not show one user's notifications to another", async () => {
+			await dispatch();
+
+			const response = await listNotifications(adminCookie);
+			expect(response.body.total).toBe(0);
+		});
+
+		it('filters to unread with ?unread=true', async () => {
+			const first = await dispatch();
+			await dispatch();
+			await app.request
+				.patch(`/v1/notifications/${first!.id}/read`)
+				.set('Cookie', userCookie);
+
+			const response = await listNotifications(userCookie, '?unread=true');
+			expect(response.body.total).toBe(1);
+		});
+	});
+
+	describe('GET /v1/notifications/unread-count', () => {
+		it('counts only unread notifications', async () => {
+			const first = await dispatch();
+			await dispatch();
+			await dispatch();
+			await app.request
+				.patch(`/v1/notifications/${first!.id}/read`)
+				.set('Cookie', userCookie);
+
+			const response = await unreadCount(userCookie);
+			expect(response.status).toBe(200);
+			expect(response.body.count).toBe(2);
+		});
+	});
+
+	describe('PATCH /v1/notifications/:id/read', () => {
+		it('marks a single notification read and drops the unread count', async () => {
+			const { id } = (await dispatch())!;
+
+			const read = await app.request
+				.patch(`/v1/notifications/${id}/read`)
+				.set('Cookie', userCookie);
+			expect(read.status).toBe(200);
+			expect(read.body.readAt).toEqual(expect.any(String));
+
+			const count = await unreadCount(userCookie);
+			expect(count.body.count).toBe(0);
+		});
+
+		it("404s when marking another user's notification", async () => {
+			const { id } = (await dispatch())!;
+
+			// Admin has no such notification — it belongs to TEST_USER.
+			const response = await app.request
+				.patch(`/v1/notifications/${id}/read`)
+				.set('Cookie', adminCookie);
+			expect(response.status).toBe(404);
+		});
+	});
+
+	describe('POST /v1/notifications/read-all', () => {
+		it('marks every notification read', async () => {
+			await dispatch();
+			await dispatch();
+
+			const response = await app.request
+				.post('/v1/notifications/read-all')
+				.set('Cookie', userCookie);
+			expect(response.status).toBe(200);
+			expect(response.body).toMatchObject({ status: 200, message: 'ok' });
+
+			const count = await unreadCount(userCookie);
+			expect(count.body.count).toBe(0);
+
+			const unread = await listNotifications(userCookie, '?unread=true');
+			expect(unread.body.total).toBe(0);
+		});
+	});
+});

package/templates/nest-api/files/test/rate-limit.spec.ts

@@ -0,0 +1,180 @@
+import { AppFactory } from '@test/factory/app';
+import { TEST_USER } from '@test/factory/constants';
+import { createAuthRateLimitStorage } from 'common/services';
+import { AUTH_RATE_LIMIT_RULES } from 'lib/rate-limit';
+
+// `GET /ping` on AppController carries @Throttle({ limit: 30, ttl: 60_000 }).
+const PING = '/ping';
+const PING_LIMIT = 30;
+
+describe('Rate limiting', () => {
+	let app: AppFactory;
+
+	// .env.test turns throttling off so buckets cannot leak between specs; this
+	// spec is the one that needs it on, so it flips the flag before the app boots
+	// and restores it afterwards (spec files run one at a time).
+	const previous = process.env.RATE_LIMIT_ENABLED;
+
+	beforeAll(async () => {
+		process.env.RATE_LIMIT_ENABLED = 'true';
+		app = await AppFactory.init();
+		await app.refresh();
+	});
+
+	afterAll(async () => {
+		await app.close();
+		process.env.RATE_LIMIT_ENABLED = previous;
+	});
+
+	// Buckets live in Redis and outlive a single test.
+	beforeEach(async () => {
+		await app.cache.truncate();
+	});
+
+	describe(`GET ${PING}`, () => {
+		it('allows requests up to the route limit', async () => {
+			for (let i = 0; i < PING_LIMIT; i++) {
+				const response = await app.request.get(PING);
+				expect(response.status).toBe(200);
+			}
+		});
+
+		it('returns 429 once the limit is exceeded', async () => {
+			for (let i = 0; i < PING_LIMIT; i++) {
+				await app.request.get(PING);
+			}
+
+			const response = await app.request.get(PING);
+			expect(response.status).toBe(429);
+		});
+
+		it('sets Retry-After to the seconds remaining on the block', async () => {
+			for (let i = 0; i < PING_LIMIT; i++) {
+				await app.request.get(PING);
+			}
+
+			const response = await app.request.get(PING);
+			const retryAfter = Number(response.headers['retry-after']);
+			expect(retryAfter).toBeGreaterThan(0);
+			expect(retryAfter).toBeLessThanOrEqual(60);
+		});
+
+		it('exposes the remaining allowance while under the limit', async () => {
+			const response = await app.request.get(PING);
+			expect(response.status).toBe(200);
+			expect(Number(response.headers['x-ratelimit-limit'])).toBe(PING_LIMIT);
+			expect(Number(response.headers['x-ratelimit-remaining'])).toBe(
+				PING_LIMIT - 1
+			);
+		});
+
+		it('keeps counting per-route, so a different route is unaffected', async () => {
+			for (let i = 0; i < PING_LIMIT + 1; i++) {
+				await app.request.get(PING);
+			}
+			expect((await app.request.get(PING)).status).toBe(429);
+
+			// Anonymous, separate handler → separate bucket.
+			expect((await app.request.get('/')).status).not.toBe(429);
+		});
+	});
+
+	describe('storage', () => {
+		// Guards against silently falling back to throttler's in-memory storage,
+		// which would give each process its own buckets once we scale out.
+		it('keeps counters in Redis, not in process memory', async () => {
+			expect(await app.cache.db.keys('throttle:*')).toHaveLength(0);
+
+			await app.request.get(PING);
+
+			const keys = await app.cache.db.keys('throttle:default:*');
+			expect(keys).toHaveLength(1);
+			expect(await app.cache.db.get(keys[0])).toBe('1');
+		});
+
+		it('sets a TTL on the bucket so the window rolls over', async () => {
+			await app.request.get(PING);
+
+			const [key] = await app.cache.db.keys('throttle:default:*');
+			const ttl = await app.cache.db.pttl(key);
+			expect(ttl).toBeGreaterThan(0);
+			expect(ttl).toBeLessThanOrEqual(60_000);
+		});
+
+		it('writes a block key once the limit is exceeded', async () => {
+			for (let i = 0; i < PING_LIMIT + 1; i++) {
+				await app.request.get(PING);
+			}
+
+			expect(await app.cache.db.keys('throttle:default:*:block')).toHaveLength(
+				1
+			);
+		});
+	});
+
+	// better-auth's own limiter on /auth/*, backed by createAuthRateLimitStorage.
+	describe('auth endpoints', () => {
+		const SIGN_IN = '/auth/sign-in/email';
+		const SIGN_IN_LIMIT = AUTH_RATE_LIMIT_RULES['/sign-in/email'].max;
+
+		// better-auth keys buckets on the client IP and skips limiting entirely
+		// when it cannot resolve one, so every request names its client.
+		const signIn = (ip = '203.0.113.7') =>
+			app.request
+				.post(SIGN_IN)
+				.set('x-forwarded-for', ip)
+				.send({ email: TEST_USER.email, password: 'wrong-password' });
+
+		it('returns 429 once the sign-in limit is exceeded', async () => {
+			for (let i = 0; i < SIGN_IN_LIMIT; i++) {
+				expect((await signIn()).status).not.toBe(429);
+			}
+
+			const response = await signIn();
+			expect(response.status).toBe(429);
+			const retryAfter = Number(response.headers['x-retry-after']);
+			expect(retryAfter).toBeGreaterThan(0);
+			expect(retryAfter).toBeLessThanOrEqual(60);
+		});
+
+		it('keeps separate buckets per client IP', async () => {
+			for (let i = 0; i < SIGN_IN_LIMIT + 1; i++) await signIn();
+
+			expect((await signIn('198.51.100.9')).status).not.toBe(429);
+		});
+
+		it('keeps its counters in Redis with the rule window as TTL', async () => {
+			await signIn();
+
+			const keys = await app.cache.db.keys('auth:rl:*');
+			expect(keys).toHaveLength(1);
+			expect(await app.cache.db.get(keys[0])).toBe('1');
+			const ttl = await app.cache.db.pttl(keys[0]);
+			expect(ttl).toBeGreaterThan(0);
+			expect(ttl).toBeLessThanOrEqual(60_000);
+		});
+
+		it('admits exactly `max` concurrent requests', async () => {
+			// The storage checks and increments in one Redis call; a read-then-write
+			// would let every concurrent request see a below-limit count.
+			const storage = createAuthRateLimitStorage(app.cache);
+			const rule = { window: 60, max: 5 };
+
+			const results = await Promise.all(
+				Array.from({ length: 50 }, () => storage.consume('concurrency', rule))
+			);
+
+			expect(results.filter((r) => r.allowed)).toHaveLength(rule.max);
+		});
+	});
+
+	describe('exempt routes', () => {
+		it('does not throttle the index route', async () => {
+			// Well past any configured limit.
+			for (let i = 0; i < PING_LIMIT + 5; i++) {
+				const response = await app.request.get('/');
+				expect(response.status).not.toBe(429);
+			}
+		});
+	});
+});

package/templates/nest-api/files/test/setup.ts

@@ -0,0 +1 @@
+import '@suites/doubles.vitest';