@aurostack/stacks 0.1.0

package/templates/nest-api/files/src/lib/access.ts

@@ -0,0 +1,114 @@
+import { createAccessControl } from 'better-auth/plugins/access';
+
+/**
+ * Permission statements — the vocabulary every authorization check draws from.
+ *
+ * Add a resource here and it is immediately available to
+ * `@UserHasPermission({ permission: { <resource>: ['<action>'] } })` on HTTP
+ * routes, to `@WsPermissions(...)` on websocket handlers, and to
+ * {@link hasPermission} for offline checks. Grant it to a role below, or it is
+ * held by nobody but `superuser`.
+ */
+const statements = {
+	user: [
+		'create',
+		'list',
+		'set-role',
+		'ban',
+		'impersonate',
+		'delete',
+		'set-password',
+		'get',
+		'update'
+	],
+	session: ['list', 'revoke', 'delete']
+} as const;
+
+export type PermissionResource = keyof typeof statements;
+export type PermissionAction<Resource extends PermissionResource> =
+	(typeof statements)[Resource][number];
+export type Permission = Partial<{
+	[Resource in PermissionResource]: PermissionAction<Resource>[];
+}>;
+
+export const ac = createAccessControl(statements);
+
+// Regular user — may manage their own sessions and nothing else. Ownership of a
+// resource is checked in the service, not granted here, so a user acting on
+// their own content needs no statement at all.
+export const userAc = ac.newRole({
+	session: ['list', 'revoke']
+});
+
+// Admin — user administration, but not role assignment or deletion.
+export const adminAc = ac.newRole({
+	user: ['create', 'list', 'get', 'update', 'set-password', 'ban'],
+	session: ['list', 'revoke']
+});
+
+// Superuser — everything in `statements`.
+export const superuserAc = ac.newRole(statements);
+
+/**
+ * The canonical role map. Consumed by the runtime auth instance (`app.module.ts`),
+ * the standalone tooling instance (`lib/auth.ts`) and {@link hasPermission}, so a
+ * new role only has to be added here.
+ */
+export const roles = {
+	user: userAc,
+	admin: adminAc,
+	superuser: superuserAc
+};
+
+export type RoleName = keyof typeof roles;
+
+/**
+ * The roles above each have a differently-typed `authorize` (their statements
+ * differ), so indexing the map yields a union that TypeScript will not let us
+ * call. Structurally they are all the same function.
+ */
+interface AuthorizableRole {
+	authorize: (permission: Permission) => { success: boolean };
+}
+
+const roleRegistry = roles as Record<string, AuthorizableRole | undefined>;
+
+/** How a role arrives: a comma-separated string, an array, or absent. */
+export type RoleInput = string | string[] | null | undefined;
+
+/**
+ * Better-auth lets a user hold several roles, and hands them over as either a
+ * **comma-separated string** or an **array** (`UserSession['user'].role` is
+ * typed `string | string[]`). Anything inspecting a role has to normalise both,
+ * so that lives here. A missing role reads as the default role, not "no roles".
+ */
+export const rolesOf = (role: RoleInput): string[] =>
+	(Array.isArray(role) ? role : (role || 'user').split(','))
+		.map((name) => name.trim())
+		.filter(Boolean);
+
+/**
+ * Whether a (possibly multi-) role includes a specific one.
+ *
+ * Use this instead of `role === 'superuser'`: the equality silently fails for a
+ * user holding `"admin,superuser"`, and doesn't compile against the array form.
+ */
+export const hasRole = (role: RoleInput, name: string): boolean =>
+	rolesOf(role).includes(name);
+
+/**
+ * Check a role against a permission, without a database round-trip.
+ *
+ * Use where better-auth's `@UserHasPermission` decorator cannot reach — notably
+ * websocket message handlers, which never pass through the HTTP `AuthGuard`.
+ *
+ * A multi-role user is granted the union of their roles; a user with no role
+ * gets the plugin's `defaultRole`.
+ */
+export const hasPermission = (
+	role: RoleInput,
+	permission: Permission
+): boolean =>
+	rolesOf(role)
+		// An unrecognized role grants nothing rather than everything.
+		.some((name) => roleRegistry[name]?.authorize(permission).success ?? false);

package/templates/nest-api/files/src/lib/auth.ts

@@ -0,0 +1,76 @@
+import 'dotenv/config';
+import { betterAuth } from 'better-auth';
+import { prismaAdapter } from 'better-auth/adapters/prisma';
+import { admin, openAPI } from 'better-auth/plugins';
+import { PrismaPg } from '@prisma/adapter-pg';
+import { PrismaClient } from '../../prisma/generated/client';
+import { ac, roles } from './access';
+import { AUTH_RATE_LIMIT_RULES } from './rate-limit'; // @feature rate-limit
+import { OriginBuilder } from '../common/misc';
+
+const { env } = process;
+
+const db = new PrismaClient({
+	adapter: new PrismaPg({
+		connectionString: env.DATABASE_URL
+	})
+});
+
+export const auth = betterAuth({
+	appName: env.APP_NAME,
+	secret: env.BETTER_AUTH_SECRET,
+	baseURL: env.BETTER_AUTH_URL,
+	basePath: '/auth',
+	database: prismaAdapter(db, {
+		provider: 'postgresql'
+	}),
+	emailAndPassword: {
+		enabled: true,
+		requireEmailVerification: true // @feature mail
+	},
+	advanced: {
+		// Must match the runtime instance: the realtime gateway validates socket
+		// sessions through this one, so a different cookie name would reject them.
+		cookiePrefix: env.BETTER_AUTH_COOKIE_PREFIX,
+		crossSubDomainCookies: {
+			enabled: true,
+			domain: env.BETTER_AUTH_COOKIE_DOMAIN
+		},
+		database: {
+			joins: true
+		}
+	},
+	socialProviders: {
+		google: {
+			clientId: env.OAUTH_GOOGLE_CLIENT_ID || '',
+			clientSecret: env.OAUTH_GOOGLE_CLIENT_SECRET || '',
+			scope: ['email', 'profile'],
+			redirectURI: `${env.BETTER_AUTH_URL}/auth/callback/google`,
+			accessType: 'offline',
+			prompt: 'select_account consent'
+		}
+	},
+	// @feature:start rate-limit
+	// Mirrors the runtime config in `app.module.ts` so the two instances agree on
+	// the rules. This instance is tooling-only (CLI, schema generation) and never
+	// serves traffic, so it keeps better-auth's default in-memory storage — the
+	// Redis-backed `customStorage` lives with the Nest DI container.
+	rateLimit: {
+		customRules: AUTH_RATE_LIMIT_RULES
+	},
+	// @feature:end
+	plugins: [
+		admin({
+			defaultRole: 'user',
+			ac,
+			roles
+		}),
+		openAPI() // @feature openapi
+	],
+	trustedOrigins: [
+		env.FRONTEND_HOST!,
+		...OriginBuilder.build(env.MISC_CORS_ORIGINS)
+	]
+});
+
+export type BetterAuth = typeof auth;

package/templates/nest-api/files/src/lib/rate-limit.ts

@@ -0,0 +1,20 @@
+/** `window` is in seconds; `max` is requests allowed per window. */
+export interface AuthRateLimitRule {
+	window: number;
+	max: number;
+}
+
+/**
+ * Stricter windows for the better-auth endpoints that actually get attacked.
+ * Paths are matched after normalization against `basePath` (`/auth`), so they
+ * are written without it.
+ *
+ * Shared by the runtime instance (`app.module.ts`) and the standalone tooling
+ * instance (`lib/auth.ts`) so the two cannot drift.
+ */
+export const AUTH_RATE_LIMIT_RULES: Record<string, AuthRateLimitRule> = {
+	'/sign-in/email': { window: 60, max: 5 },
+	'/sign-up/email': { window: 3600, max: 5 },
+	'/forget-password': { window: 3600, max: 3 },
+	'/reset-password': { window: 3600, max: 5 }
+};

package/templates/nest-api/files/src/main.ts

@@ -0,0 +1,28 @@
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from 'app.module';
+import * as setup from './app.setup';
+
+(async () => {
+	// `bodyParser: false` is intentional — better-auth needs raw bodies on its
+	// own routes. JSON parsing is re-applied everywhere else by
+	// `enableJsonBodyParser` below. Do not re-enable it globally.
+	const app = await NestFactory.create(AppModule, {
+		bodyParser: false,
+		bufferLogs: true
+	});
+	setup.usePinoLogger(app);
+	setup.enableBasicAuth(app); // @feature openapi, queue, observability
+	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);
+	// Must run before `start()` — the websocket adapter has to be attached
+	// before the HTTP server begins listening.
+	await setup.enableRealtime(app); // @feature realtime
+	await setup.start(app);
+})();

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

@@ -0,0 +1,60 @@
+import { TestBed, type Mocked } from '@suites/unit';
+import type { Mock } from 'vitest';
+import { getQueueToken } from '@nestjs/bullmq';
+import type { Queue } from 'bullmq';
+import { Enum } from 'common/utils';
+import { MediaService } from 'media/services';
+import { S3Service } from 'media/services';
+
+describe('MediaService', () => {
+	let service: MediaService;
+	// Only `add` is exercised; Mocked<Queue> is too deep a type for tsc.
+	let queue: { add: Mock<Queue['add']> };
+	let s3: Mocked<S3Service>;
+
+	beforeAll(async () => {
+		const { unit, unitRef } = await TestBed.solitary(MediaService).compile();
+		service = unit;
+		queue = unitRef.get(getQueueToken('media'));
+		s3 = unitRef.get(S3Service);
+	});
+
+	beforeEach(() => {
+		queue.add.mockReset();
+		s3.uploadFile.mockReset();
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+
+	describe('uploadAvatar', () => {
+		it('should delegate to S3Service.uploadFile with AVATARS folder', async () => {
+			const file = {
+				originalname: 'avatar.png',
+				buffer: Buffer.from('avatar'),
+				mimetype: 'image/png'
+			} as any;
+			const url = 'http://example.com/avatars/avatar.png';
+			s3.uploadFile.mockResolvedValue(url);
+
+			const result = await service.uploadAvatar(file);
+
+			expect(s3.uploadFile).toHaveBeenCalledWith(
+				file,
+				Enum.UploadFolder.AVATARS
+			);
+			expect(result).toBe(url);
+		});
+	});
+
+	describe('deleteFile', () => {
+		it('should enqueue delete-file job on media queue', async () => {
+			const url = 'http://example.com/avatars/avatar.png';
+
+			await service.deleteFile(url);
+
+			expect(queue.add).toHaveBeenCalledWith('delete-file', url);
+		});
+	});
+});

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

@@ -0,0 +1,159 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { vi } from 'vitest';
+import {
+	S3Client,
+	PutObjectCommand,
+	DeleteObjectCommand
+} from '@aws-sdk/client-s3';
+import { BadRequestException } from '@nestjs/common';
+import { Enum } from 'common/utils';
+import {
+	CustomConfigService,
+	GeneratorService,
+	LoggerService
+} from 'common/services';
+import { S3Service } from 'media/services';
+
+describe('S3Service', () => {
+	let service: S3Service;
+	let sendSpy: ReturnType<typeof vi.spyOn>;
+
+	const mockConfig: Partial<CustomConfigService> = {
+		s3: {
+			accessKeyId: 'ACCESS_KEY_ID',
+			secretAccessKey: 'SECRET_ACCESS_KEY',
+			endpoint: 'http://localhost:9000',
+			bucket: 'test-bucket',
+			region: 'us-east-1'
+		}
+	} as any;
+
+	const mockGen: Partial<GeneratorService> = {
+		cuid: () => 'test-uuid'
+	} as any;
+
+	/*
+	 * S3Service gained a LoggerService dependency; without a stub Nest fails to
+	 * construct it and vitest reports a failed *suite* with all 7 tests skipped —
+	 * green-looking output hiding zero coverage. Only `error` is called (the
+	 * upload catch), but the rest are stubbed so a new log line can't resurrect
+	 * that failure mode.
+	 */
+	const mockLogger = {
+		error: vi.fn(),
+		warn: vi.fn(),
+		info: vi.fn(),
+		debug: vi.fn()
+	} as unknown as LoggerService;
+
+	beforeAll(async () => {
+		const module: TestingModule = await Test.createTestingModule({
+			providers: [
+				S3Service,
+				{
+					provide: CustomConfigService,
+					useValue: mockConfig
+				},
+				{
+					provide: GeneratorService,
+					useValue: mockGen
+				},
+				{
+					provide: LoggerService,
+					useValue: mockLogger
+				}
+			]
+		}).compile();
+
+		service = module.get(S3Service);
+		sendSpy = vi
+			.spyOn(S3Client.prototype as any, 'send')
+			.mockResolvedValue({} as any);
+	});
+
+	beforeEach(() => {
+		sendSpy.mockClear();
+	});
+
+	afterAll(() => {
+		vi.restoreAllMocks();
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+
+	describe('getKey', () => {
+		it('should build key using folder, uuid and file extension', () => {
+			const file = { originalname: 'photo.jpg' } as any;
+			const key = service.getKey(Enum.UploadFolder.AVATARS, file);
+			expect(key).toBe('avatars/test-uuid.jpg');
+		});
+	});
+
+	describe('getUrl / getKeyFromUrl / isHostedUrl', () => {
+		it('should build and parse hosted URLs correctly', () => {
+			const key = 'avatars/test-uuid.jpg';
+			const url = service.getUrl(key);
+			expect(url).toBe(
+				'http://localhost:9000/test-bucket/avatars/test-uuid.jpg'
+			);
+			expect(service.getKeyFromUrl(url)).toBe(key);
+			expect(service.isHostedUrl(url)).toBe(true);
+			expect(
+				service.isHostedUrl('http://external.com/avatars/test-uuid.jpg')
+			).toBe(false);
+		});
+	});
+
+	describe('uploadFile', () => {
+		it('should upload file and return its URL', async () => {
+			const file = {
+				originalname: 'photo.jpg',
+				buffer: Buffer.from('data'),
+				mimetype: 'image/jpeg'
+			} as any;
+
+			const result = await service.uploadFile(file, Enum.UploadFolder.AVATARS);
+
+			expect(sendSpy).toHaveBeenCalledTimes(1);
+			const command = sendSpy.mock.calls[0][0];
+			expect(command).toBeInstanceOf(PutObjectCommand);
+			const expectedUrl =
+				'http://localhost:9000/test-bucket/avatars/test-uuid.jpg';
+			expect(result).toBe(expectedUrl);
+		});
+
+		it('should throw BadRequestException when upload fails', async () => {
+			sendSpy.mockRejectedValueOnce(new Error('upload failed'));
+
+			const file = {
+				originalname: 'photo.jpg',
+				buffer: Buffer.from('data'),
+				mimetype: 'image/jpeg'
+			} as any;
+
+			await expect(
+				service.uploadFile(file, Enum.UploadFolder.AVATARS)
+			).rejects.toThrow(BadRequestException);
+		});
+	});
+
+	describe('deleteFile', () => {
+		it('should delete file without error', async () => {
+			await service.deleteFile('avatars/test-uuid.jpg');
+
+			expect(sendSpy).toHaveBeenCalledTimes(1);
+			const command = sendSpy.mock.calls[0][0];
+			expect(command).toBeInstanceOf(DeleteObjectCommand);
+		});
+
+		it('should throw BadRequestException when delete fails', async () => {
+			sendSpy.mockRejectedValueOnce(new Error('delete failed'));
+
+			await expect(service.deleteFile('avatars/test-uuid.jpg')).rejects.toThrow(
+				BadRequestException
+			);
+		});
+	});
+});

package/templates/nest-api/files/src/media/entity/file.entity.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+import { faker as F } from '@faker-js/faker';
+
+export const FileEntity = z
+	.object({ path: z.string().meta({ example: F.image.avatar() }) })
+	.meta({ id: 'FileEntity' });
+export type FileEntity = z.input<typeof FileEntity>;

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

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

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

@@ -0,0 +1,20 @@
+import { Global, Module } from '@nestjs/common';
+import { MulterModule } from '@nestjs/platform-express';
+import { memoryStorage } from 'multer';
+import { QueueModule } from 'common/modules';
+import { S3Service, MediaService } from './services';
+import { MediaProcessor } from './processors';
+
+@Global()
+@Module({
+	imports: [
+		MulterModule.register({
+			storage: memoryStorage() // use memory storage for having the buffer
+		}),
+		QueueModule.register('media')
+	],
+	controllers: [],
+	providers: [S3Service, MediaService, MediaProcessor],
+	exports: [MediaService]
+})
+export class MediaModule {}

package/templates/nest-api/files/src/media/processors/index.ts

@@ -0,0 +1,44 @@
+import { Processor, WorkerHost, OnWorkerEvent } from '@nestjs/bullmq';
+import { Injectable } from '@nestjs/common';
+import { Job } from 'bullmq';
+import { LoggerService } from 'common/services';
+import { S3Service } from '../services';
+
+@Injectable()
+@Processor('media')
+export class MediaProcessor extends WorkerHost {
+	constructor(
+		private readonly s3: S3Service,
+		private readonly logger: LoggerService
+	) {
+		super();
+	}
+
+	async process(job: Job<string, any, any>): Promise<void> {
+		if (job.name === 'delete-file') {
+			if (!this.s3.isHostedUrl(job.data)) {
+				this.logger.warn(
+					{ jobId: job.id, jobName: job.name },
+					'Not a hosted URL; skipping delete.'
+				);
+				return;
+			}
+			const key = this.s3.getKeyFromUrl(job.data);
+			await this.s3.deleteFile(key);
+			await job.updateProgress(100);
+		}
+	}
+
+	@OnWorkerEvent('completed')
+	onCompleted(job: Job<string, any, any>) {
+		this.logger.info({ jobId: job.id, jobName: job.name }, 'File deleted.');
+	}
+
+	@OnWorkerEvent('failed')
+	onFailed(job: Job, err: Error) {
+		this.logger.error(
+			{ err, jobId: job.id, jobName: job.name },
+			'File delete failed.'
+		);
+	}
+}

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

@@ -0,0 +1,2 @@
+export * from './s3.service';
+export * from './media.service';

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

@@ -0,0 +1,29 @@
+import { Injectable } from '@nestjs/common';
+import { InjectQueue } from '@nestjs/bullmq';
+import { Queue } from 'bullmq';
+import { Enum } from 'common/utils';
+import { S3Service } from './s3.service';
+
+@Injectable()
+export class MediaService {
+	constructor(
+		@InjectQueue('media') private queue: Queue,
+		private s3: S3Service
+	) {}
+
+	async uploadAvatar(file: Express.Multer.File) {
+		return await this.s3.uploadFile(file, Enum.UploadFolder.AVATARS);
+	}
+
+	async uploadFile(file: Express.Multer.File, folder: Enum.UploadFolder) {
+		return await this.s3.uploadFile(file, folder);
+	}
+
+	async getFileBuffer(url: string): Promise<Buffer> {
+		return await this.s3.getFileBuffer(this.s3.getKeyFromUrl(url));
+	}
+
+	async deleteFile(data: string) {
+		this.queue.add('delete-file', data);
+	}
+}