@aurostack/stacks 0.1.0

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

@@ -0,0 +1,268 @@
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { HttpModule } from '@nestjs/axios'; // @feature http-client
+import { ScheduleModule } from '@nestjs/schedule'; // @feature scheduler
+import { MailerModule } from '@nestjs-modules/mailer'; // @feature mail
+import { BullModule } from '@nestjs/bullmq'; // @feature queue
+import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler'; // @feature rate-limit
+import { AuthModule, AuthGuard } from '@thallesp/nestjs-better-auth';
+import { betterAuth } from 'better-auth';
+import { prismaAdapter } from 'better-auth/adapters/prisma';
+import { admin, openAPI } from 'better-auth/plugins';
+import { BullBoardModule } from '@bull-board/nestjs'; // @feature queue
+import { GraphQLModule } from '@nestjs/graphql'; // @feature graphql
+import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo'; // @feature graphql
+import { ExpressAdapter } from '@bull-board/express'; // @feature queue
+import { CustomConfigService, PrismaService } from 'common/services';
+import { MailService } from 'common/services'; // @feature mail
+// @feature:start rate-limit
+import {
+	CacheService,
+	RedisThrottlerStorage,
+	createAuthRateLimitStorage
+} from 'common/services';
+// @feature:end
+import { getClientIp } from 'common/utils'; // @feature rate-limit
+import { CommonModule } from 'common/common.module';
+import { UsersModule } from 'users/users.module'; // @feature users
+import { MediaModule } from 'media/media.module'; // @feature media
+import { RealtimeModule } from 'realtime/realtime.module'; // @feature realtime
+import { NotificationsModule } from 'notifications/notifications.module'; // @feature notifications
+import { AppController } from 'app.controller';
+import { AppResolver } from 'app.resolver'; // @feature graphql
+import { ac, roles } from 'lib/access';
+import { AUTH_RATE_LIMIT_RULES } from 'lib/rate-limit'; // @feature rate-limit
+import { OriginBuilder } from 'common/misc';
+
+@Module({
+	imports: [
+		CommonModule,
+		AuthModule.forRootAsync({
+			inject: [
+				PrismaService,
+				CustomConfigService,
+				MailService, // @feature mail
+				CacheService // @feature rate-limit
+			],
+			useFactory: (
+				db: PrismaService,
+				config: CustomConfigService,
+				mail: MailService, // @feature mail
+				cache: CacheService // @feature rate-limit
+			) => ({
+				auth: betterAuth({
+					appName: config.app.name,
+					secret: config.betterAuth.secret,
+					baseURL: config.betterAuth.url,
+					basePath: '/auth',
+					database: prismaAdapter(db, {
+						provider: 'postgresql'
+					}),
+					// @feature:start rate-limit
+					// better-auth's limiter only guards `/auth/*` — every other route
+					// is covered by ThrottlerGuard below.
+					rateLimit: {
+						// better-auth defaults to production-only; follow RATE_LIMIT_ENABLED
+						// instead, so dev is limited too and tests can opt out (and back in).
+						enabled: config.rateLimit.enabled,
+						window: config.rateLimit.authWindow,
+						max: config.rateLimit.authMax,
+						customRules: AUTH_RATE_LIMIT_RULES,
+						customStorage: createAuthRateLimitStorage(cache)
+					},
+					// @feature:end
+					advanced: {
+						// @feature:start rate-limit
+						ipAddress: {
+							// Without this, `getIp` behind a proxy resolves every request
+							// to the proxy's address — and if it resolves nothing at all,
+							// better-auth skips rate limiting entirely with a warning.
+							ipAddressHeaders: config.rateLimit.ipHeaders
+						},
+						// @feature:end
+						// Share the session cookie across subdomains so one login covers
+						// every frontend. Domain comes from BETTER_AUTH_COOKIE_DOMAIN
+						// (`.lvh.me` in dev, your apex in production).
+						cookiePrefix: config.betterAuth.cookiePrefix,
+						crossSubDomainCookies: {
+							enabled: true,
+							domain: config.betterAuth.cookieDomain
+						},
+						database: {
+							joins: true
+						}
+					},
+					user: {
+						additionalFields: {
+							// Example of an extra session-borne field. `input: false` is
+							// load-bearing on anything the client must not be able to set
+							// for itself — without it, a signup payload could grant it.
+							onboardingCompletedAt: {
+								type: 'date',
+								required: false,
+								input: false
+							}
+						}
+					},
+					socialProviders: {
+						google: {
+							clientId: config.oauth.google.clientId,
+							clientSecret: config.oauth.google.clientSecret,
+							scope: ['email', 'profile'],
+							redirectURI: `${config.betterAuth.url}/auth/callback/google`,
+							accessType: 'offline',
+							prompt: 'select_account consent'
+						}
+					},
+					emailAndPassword: {
+						enabled: true,
+						// @feature:start mail
+						requireEmailVerification: true,
+						sendResetPassword: async ({ user, url, token }) => {
+							mail.forgotPassword({
+								to: user.email,
+								token,
+								url
+							});
+						},
+						onPasswordReset: async ({ user }) => {
+							mail.resetPassword(user.email);
+						}
+						// @feature:end
+					},
+					// @feature:start mail
+					emailVerification: {
+						sendOnSignUp: true,
+						sendVerificationEmail: async ({ user, url, token }) => {
+							mail.activation({
+								to: user.email,
+								token,
+								firstName: user.name.split(' ')[0],
+								url
+							});
+						},
+						afterEmailVerification: async ({ email, name }) => {
+							mail.welcome({
+								to: email,
+								firstName: name,
+								supportEmail: config.smtp.supportEmail,
+								clientLoginPage: config.app.frontendHost
+							});
+						}
+					},
+					// @feature:end
+					plugins: [
+						admin({
+							defaultRole: 'user',
+							ac,
+							roles
+						}),
+						openAPI() // @feature openapi
+					],
+					trustedOrigins: [
+						config.app.frontendHost,
+						...OriginBuilder.build(config.app.miscCorsOrigins)
+					]
+				}),
+				middleware: (req, _, next) => {
+					req.url = req.originalUrl;
+					req.baseUrl = '';
+					next();
+				}
+			})
+		}),
+		// @feature:start mail
+		MailerModule.forRootAsync({
+			imports: [],
+			inject: [CustomConfigService],
+			useFactory: async (config: CustomConfigService) => ({
+				defaults: {
+					from: config.smtp.from
+				},
+				transport: {
+					host: config.smtp.host,
+					port: config.smtp.port,
+					secure: config.smtp.secure,
+					auth: {
+						user: config.smtp.user,
+						pass: config.smtp.password
+					}
+				}
+			})
+		}),
+		// @feature:end
+		HttpModule.registerAsync({ useFactory: () => ({ timeout: 5000 }) }), // @feature http-client
+		// @feature:start queue
+		BullModule.forRootAsync({
+			inject: [CustomConfigService],
+			useFactory: async (config: CustomConfigService) => ({
+				connection: {
+					host: config.redis.host,
+					port: config.redis.port,
+					username: config.redis.username,
+					password: config.redis.password
+				},
+				defaultJobOptions: {
+					removeOnComplete: true
+				}
+			})
+		}),
+		BullBoardModule.forRoot({
+			route: '/dashboard',
+			adapter: ExpressAdapter
+		}),
+		// @feature:end
+		// @feature:start rate-limit
+		ThrottlerModule.forRootAsync({
+			inject: [CustomConfigService, RedisThrottlerStorage],
+			useFactory: (
+				config: CustomConfigService,
+				storage: RedisThrottlerStorage
+			) => ({
+				throttlers: [
+					{
+						name: 'default',
+						ttl: config.rateLimit.ttl,
+						limit: config.rateLimit.limit
+					}
+				],
+				storage,
+				getTracker: (req) => getClientIp(req, config.rateLimit.ipHeaders),
+				skipIf: () => !config.rateLimit.enabled
+			})
+		}),
+		// @feature:end
+		// @feature:start graphql
+		// Code-first GraphQL alongside the REST controllers. The schema file is
+		// generated from resolvers at boot; add resolvers to any feature module
+		// and they are picked up automatically.
+		GraphQLModule.forRoot<ApolloDriverConfig>({
+			driver: ApolloDriver,
+			autoSchemaFile: true,
+			graphiql: false
+		}),
+		// @feature:end
+		ScheduleModule.forRoot(), // @feature scheduler
+		UsersModule, // @feature users
+		MediaModule, // @feature media
+		RealtimeModule, // @feature realtime
+		NotificationsModule // @feature notifications
+	],
+	controllers: [AppController],
+	providers: [
+		AppResolver, // @feature graphql
+		// Order matters: Nest runs global guards in registration order, so floods
+		// are rejected before AuthGuard does a session lookup and hits the DB.
+		// @feature:start rate-limit
+		{
+			provide: APP_GUARD,
+			useClass: ThrottlerGuard
+		},
+		// @feature:end
+		{
+			provide: APP_GUARD,
+			useClass: AuthGuard
+		}
+	]
+})
+export class AppModule {}

package/templates/nest-api/files/src/app.resolver.ts

@@ -0,0 +1,32 @@
+import { Field, ObjectType, Query, Resolver } from '@nestjs/graphql';
+import { AllowAnonymous } from '@thallesp/nestjs-better-auth';
+import { SWAGGER_OPTIONS } from 'common/constants';
+
+@ObjectType()
+class ApiInfo {
+	@Field()
+	title: string;
+
+	@Field(() => String, { nullable: true })
+	description?: string;
+
+	constructor(title: string, description?: string) {
+		this.title = title;
+		this.description = description;
+	}
+}
+
+/**
+ * Root query type. Code-first schema generation fails without at least one
+ * `@Query`, so this keeps the endpoint bootable until feature modules add
+ * their own resolvers.
+ */
+@Resolver()
+export class AppResolver {
+	@Query(() => ApiInfo, { description: 'Basic information about the API' })
+	@AllowAnonymous()
+	info(): ApiInfo {
+		const { info } = SWAGGER_OPTIONS;
+		return new ApiInfo(info.title, info.description);
+	}
+}

package/templates/nest-api/files/src/app.setup.ts

@@ -0,0 +1,178 @@
+import {
+	BadRequestException,
+	INestApplication,
+	StandardSchemaSerializerInterceptor,
+	StandardSchemaValidationPipe,
+	VersioningType,
+	Logger
+} from '@nestjs/common';
+import { SwaggerModule } from '@nestjs/swagger'; // @feature openapi
+import { HttpAdapterHost, Reflector } from '@nestjs/core';
+import helmet from 'helmet';
+import express from 'express';
+import expressBasicAuth from 'express-basic-auth'; // @feature openapi, queue, observability
+import { apiReference } from '@scalar/nestjs-api-reference'; // @feature openapi
+import { AuthService } from '@thallesp/nestjs-better-auth'; // @feature openapi
+import { Logger as PinoLogger } from 'nestjs-pino';
+import { join } from 'path';
+import {
+	PrismaClientKnownRequestExceptionFilter,
+	PrismaClientValidationExceptionFilter
+} from 'common/exceptions';
+import { CustomConfigService } from 'common/services';
+import { CORS_OPTIONS } from 'common/constants';
+import { SWAGGER_OPTIONS } from 'common/constants'; // @feature openapi
+import { RedisIoAdapter } from 'realtime/adapters/redis-io.adapter'; // @feature realtime
+
+export const enableVersioning = (app: INestApplication) => {
+	app.enableVersioning({
+		type: VersioningType.URI
+	});
+};
+
+export const usePinoLogger = (app: INestApplication) => {
+	const logger = app.get(PinoLogger);
+	app.useLogger(logger);
+};
+
+export const setStatic = (app: INestApplication) => {
+	app.use(express.static(join(__dirname, '..', '..', 'public')));
+};
+
+// Scoped JSON body parsing — excludes /auth so better-auth retains raw bodies.
+export const enableJsonBodyParser = (app: INestApplication) => {
+	const json = express.json();
+	const urlencoded = express.urlencoded({ extended: true });
+	app.use((req, res, next) => {
+		if (req.path.startsWith('/auth')) return next();
+		return json(req, res, next);
+	});
+	app.use((req, res, next) => {
+		if (req.path.startsWith('/auth')) return next();
+		return urlencoded(req, res, next);
+	});
+};
+
+/**
+ * Validate every `@Body/@Query/@Param({ schema })` against its Zod schema; the
+ * handler receives the schema's output (coerced, defaulted, transformed).
+ * Failures keep the API's error contract: one 400 whose message is
+ * `Validation: <field>: <first problem>`.
+ */
+export const useGlobalPipes = (app: INestApplication) => {
+	app.useGlobalPipes(
+		new StandardSchemaValidationPipe({
+			exceptionFactory: (issues) => {
+				const [first] = issues;
+				if (!first) return new BadRequestException('Validation failed');
+
+				const path = (first.path ?? [])
+					.map((segment) =>
+						typeof segment === 'object' ? segment.key : segment
+					)
+					.join('.');
+				return new BadRequestException(
+					`Validation: ${path ? `${path}: ` : ''}${first.message}`
+				);
+			}
+		})
+	);
+};
+
+// Serialize responses through the schema a handler declares with @Returns().
+export const useGlobalInterceptors = (app: INestApplication) => {
+	app.useGlobalInterceptors(
+		new StandardSchemaSerializerInterceptor(app.get(Reflector))
+	);
+};
+
+// apply PrismaClientExceptionFilter to entire application,
+// requires HttpAdapterHost because it extends BaseExceptionFilter
+export const useGlobalFilters = (app: INestApplication) => {
+	const { httpAdapter } = app.get(HttpAdapterHost);
+	app.useGlobalFilters(
+		new PrismaClientKnownRequestExceptionFilter(httpAdapter),
+		new PrismaClientValidationExceptionFilter(httpAdapter)
+	);
+};
+
+export const enableCors = (app: INestApplication) => {
+	app.enableCors(CORS_OPTIONS);
+};
+
+// @feature:start realtime
+/**
+ * Attach the Redis-backed Socket.io adapter so realtime events fan out across
+ * replicas. Must run before `start()` (i.e. before the HTTP server listens).
+ */
+export const enableRealtime = async (app: INestApplication) => {
+	const config = app.get(CustomConfigService);
+	const adapter = new RedisIoAdapter(app);
+	await adapter.connectToRedis(config);
+	app.useWebSocketAdapter(adapter);
+};
+// @feature:end
+
+export const enableHelmet = (app: INestApplication) => {
+	app.use(helmet());
+};
+
+// @feature:start openapi, queue, observability
+/**
+ * Lock the operator-facing surfaces behind basic auth. Every path added here is
+ * something that leaks internals if left open — the API reference, the queue
+ * dashboard, the metrics scrape endpoint — so a new one belongs in this list on
+ * the same commit that mounts it.
+ */
+export const enableBasicAuth = (app: INestApplication) => {
+	const config = app.get(CustomConfigService);
+	const { user, password } = config.basicAuth;
+
+	app.use(
+		[
+			'/docs', // @feature openapi
+			'/openapi-json', // @feature openapi
+			'/dashboard', // @feature queue
+			'/metrics' // @feature observability
+		],
+		expressBasicAuth({
+			users: { [user]: password },
+			challenge: true
+		})
+	);
+};
+// @feature:end
+
+// @feature:start openapi
+export const enableOpenAPI = async (app: INestApplication) => {
+	const config = app.get(CustomConfigService);
+	const auth = app.get(AuthService);
+	const document = SwaggerModule.createDocument(app, SWAGGER_OPTIONS);
+	SwaggerModule.setup('/openapi', app, document, {
+		customSiteTitle: config.app.name
+	});
+
+	const authSchema = await auth.api.generateOpenAPISchema();
+
+	app.use(
+		'/docs',
+		apiReference({
+			theme: 'purple',
+			sources: [
+				{ slug: 'auth', title: 'Authentication', content: authSchema },
+				{ slug: 'main', title: 'Main API', url: '/openapi-json', default: true }
+			]
+		})
+	);
+};
+// @feature:end
+
+export const start = async (app: INestApplication) => {
+	const logger = new Logger('Bootstrap');
+	const config = app.get(CustomConfigService);
+	const { port, appHost, host } = config.app;
+	await app.listen(port, appHost, () => {
+		logger.debug(`\n\n-------------------------------------------------------\n\nApplication listening on:\n- http://${appHost}:${port}\n- ${host}\n\nAPI Documentation available at:\n- http://${appHost}:${port}/docs\n- ${host}/docs\n\n-------------------------------------------------------
+	`);
+	});
+};

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

@@ -0,0 +1,31 @@
+import { TestBed, type Mocked } from '@suites/unit';
+import { AuthService } from '@thallesp/nestjs-better-auth';
+import { CustomAuthService } from 'common/services/auth.service';
+import type { BetterAuth } from 'lib/auth';
+
+describe('CustomAuthService', () => {
+	let service: CustomAuthService;
+	let auth: Mocked<AuthService<BetterAuth>>;
+
+	beforeAll(async () => {
+		const { unit, unitRef } =
+			await TestBed.solitary(CustomAuthService).compile();
+		service = unit;
+		auth = unitRef.get(AuthService<BetterAuth> as any);
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+
+	it('should expose auth api getter', () => {
+		const api = {} as any;
+		auth.api = api;
+
+		expect(service.api).toBe(api);
+	});
+
+	it('should expose auth instance getter', () => {
+		expect(service.instance).toBe(auth);
+	});
+});