@aurostack/stacks 0.1.0

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

@@ -0,0 +1,388 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { z } from 'zod';
+
+/**
+ * The single door onto the environment.
+ *
+ * App code must never read `process.env` directly — go through the injected
+ * `CustomConfigService` instead. Everything is validated once, at boot, against
+ * the Zod `schema`, so a missing variable fails the process immediately rather
+ * than surfacing as `undefined` deep inside a request.
+ *
+ * Adding a variable means three edits in this file: the interface, the Zod
+ * schema, and `getVariables` — plus a line in `.env.example`.
+ */
+namespace Config {
+	export interface App {
+		name: string;
+		twofaAppName: string;
+		env: string;
+		host: string;
+		appHost: string;
+		frontendHost: string;
+		miscCorsOrigins?: string;
+		port: number;
+		key: string;
+	}
+
+	export interface Logger {
+		level: string;
+	}
+
+	// @feature:start observability
+	/** Limits past which /health reports the process as down. */
+	export interface Health {
+		heapMaxMb: number;
+		rssMaxMb: number;
+		/** Fraction of `diskPath`'s volume that may be used, 0–1. */
+		diskThreshold: number;
+		diskPath: string;
+	}
+	// @feature:end
+
+	export interface Database {
+		url: string;
+	}
+
+	// @feature:start cache
+	export interface Redis {
+		host: string;
+		port: number;
+		username?: string;
+		password?: string;
+	}
+	// @feature:end
+
+	// @feature:start openapi, queue, observability
+	export interface BasicAuth {
+		user: string;
+		password: string;
+	}
+	// @feature:end
+
+	export interface BetterAuth {
+		secret: string;
+		url: string;
+		cookieDomain: string;
+		cookiePrefix: string;
+	}
+
+	// @feature:start feature-flags
+	export interface Growthbook {
+		apiHost: string;
+		clientKey: string;
+	}
+	// @feature:end
+
+	export interface Superuser {
+		email: string;
+		username: string;
+		password: string;
+	}
+
+	// @feature:start mail
+	export interface SMTP {
+		host: string;
+		port: number;
+		user: string;
+		password: string;
+		from: string;
+		supportEmail: string;
+		secure: boolean;
+	}
+	// @feature:end
+
+	// @feature:start media
+	export interface S3 {
+		accessKeyId: string;
+		secretAccessKey: string;
+		endpoint: string;
+		bucket: string;
+		region: string;
+	}
+	// @feature:end
+
+	// @feature:start rate-limit
+	export interface RateLimit {
+		enabled: boolean;
+		ttl: number;
+		limit: number;
+		authWindow: number;
+		authMax: number;
+		ipHeaders: string[];
+	}
+	// @feature:end
+
+	export interface OAuthGoogle {
+		clientId: string;
+		clientSecret: string;
+	}
+
+	export interface OAuth {
+		google: OAuthGoogle;
+	}
+
+	export interface Env {
+		app: App;
+		logger: Logger;
+		health: Health; // @feature observability
+		database: Database;
+		redis: Redis; // @feature cache
+		basicAuth: BasicAuth; // @feature openapi, queue, observability
+		betterAuth: BetterAuth;
+		growthbook: Growthbook; // @feature feature-flags
+		superuser: Superuser;
+		smtp: SMTP; // @feature mail
+		s3: S3; // @feature media
+		rateLimit: RateLimit; // @feature rate-limit
+		oauth: OAuth;
+	}
+
+	const { env } = process;
+
+	// Env primitives: a required string must be non-empty, and a number arrives
+	// as text that must parse (a blank is an error, not 0).
+	const str = () => z.string().min(1);
+	const num = (schema: z.ZodNumber = z.number()) =>
+		z.string().trim().min(1).transform(Number).pipe(schema);
+
+	export const schema = z.object({
+		APP_ENV: z
+			.enum(['development', 'production', 'test'])
+			.default('development'),
+		APP_HOST: str(),
+		APP_NAME: str(),
+		SERVER_HOST: str(),
+		FRONTEND_HOST: str(),
+		MISC_CORS_ORIGINS: z.string().default(''),
+		PORT: num().default(5000),
+		DATABASE_URL: str(),
+		BETTER_AUTH_SECRET: str(),
+		BETTER_AUTH_URL: str(),
+		BETTER_AUTH_COOKIE_DOMAIN: str(),
+		BETTER_AUTH_COOKIE_PREFIX: str(),
+		SUPERUSER_EMAIL: str(),
+		SUPERUSER_PASSWORD: str(),
+		OAUTH_GOOGLE_CLIENT_ID: z.string().optional(),
+		OAUTH_GOOGLE_CLIENT_SECRET: z.string().optional(),
+		LOG_LEVEL: str().default('info'),
+		// @feature:start observability
+		HEALTH_HEAP_MAX_MB: num(z.number().positive()).default(300),
+		HEALTH_RSS_MAX_MB: num(z.number().positive()).default(300),
+		HEALTH_DISK_THRESHOLD: num(z.number().min(0).max(1)).default(0.8),
+		HEALTH_DISK_PATH: str().default('/'),
+		// @feature:end
+		// @feature:start openapi, queue, observability
+		BASIC_AUTH_USER: str(),
+		BASIC_AUTH_PASS: str(),
+		// @feature:end
+		// @feature:start cache
+		REDIS_HOST: str().default('localhost'),
+		REDIS_PORT: num().default(6379),
+		REDIS_USER: z.string().optional(),
+		REDIS_PASSWORD: z.string().optional(),
+		// @feature:end
+		// @feature:start mail
+		SMTP_HOST: str(),
+		SMTP_PORT: z.enum(['465', '587']),
+		SMTP_SECURE: z.enum(['true', 'false']),
+		SMTP_USER: str(),
+		SMTP_PASSWORD: str(),
+		SMTP_FROM: str(),
+		SMTP_SUPPORT_EMAIL: str(),
+		// @feature:end
+		// @feature:start media
+		S3_REGION: str().default('us-east-1'),
+		S3_ENDPOINT: z.string().optional(),
+		S3_BUCKET_NAME: str(),
+		S3_ACCESS_KEY_ID: z.string().optional(),
+		S3_SECRET_ACCESS_KEY: z.string().optional(),
+		// @feature:end
+		// @feature:start rate-limit
+		RATE_LIMIT_ENABLED: z.enum(['true', 'false']).default('true'),
+		RATE_LIMIT_TTL: num().default(60_000),
+		RATE_LIMIT_MAX: num().default(120),
+		RATE_LIMIT_AUTH_WINDOW: num().default(10),
+		RATE_LIMIT_AUTH_MAX: num().default(100),
+		RATE_LIMIT_IP_HEADERS: str().default('x-forwarded-for'),
+		// @feature:end
+		// @feature:start feature-flags
+		GROWTHBOOK_API_HOST: str(),
+		GROWTHBOOK_CLIENT_KEY: str()
+		// @feature:end
+	});
+
+	export const getVariables = (): Config.Env => ({
+		app: {
+			name: env.APP_NAME || '',
+			twofaAppName: env.TWOFA_APP_NAME || env.APP_NAME || '',
+			env: env.APP_ENV || '',
+			host: env.SERVER_HOST || '',
+			appHost: env.APP_HOST || '',
+			frontendHost: env.FRONTEND_HOST || '',
+			miscCorsOrigins: env.MISC_CORS_ORIGINS,
+			port: Number(env.PORT) || 5000,
+			key: env.APP_KEY || ''
+		},
+		logger: {
+			level: env.LOG_LEVEL || 'info'
+		},
+		// @feature:start observability
+		health: {
+			heapMaxMb: Number(env.HEALTH_HEAP_MAX_MB) || 300,
+			rssMaxMb: Number(env.HEALTH_RSS_MAX_MB) || 300,
+			diskThreshold: env.HEALTH_DISK_THRESHOLD
+				? Number(env.HEALTH_DISK_THRESHOLD)
+				: 0.8,
+			diskPath: env.HEALTH_DISK_PATH || '/'
+		},
+		// @feature:end
+		database: {
+			url: env.DATABASE_URL || ''
+		},
+		// @feature:start cache
+		redis: {
+			host: env.REDIS_HOST || 'localhost',
+			port: Number(env.REDIS_PORT) || 6379,
+			username: env.REDIS_USER || '',
+			password: env.REDIS_PASSWORD || ''
+		},
+		// @feature:end
+		// @feature:start openapi, queue, observability
+		basicAuth: {
+			user: env.BASIC_AUTH_USER || 'user',
+			password: env.BASIC_AUTH_PASS || 'password'
+		},
+		// @feature:end
+		betterAuth: {
+			secret: env.BETTER_AUTH_SECRET || '',
+			url: env.BETTER_AUTH_URL || env.SERVER_HOST || '',
+			cookieDomain: env.BETTER_AUTH_COOKIE_DOMAIN || '',
+			cookiePrefix: env.BETTER_AUTH_COOKIE_PREFIX || ''
+		},
+		// @feature:start feature-flags
+		growthbook: {
+			apiHost: env.GROWTHBOOK_API_HOST || '',
+			clientKey: env.GROWTHBOOK_CLIENT_KEY || ''
+		},
+		// @feature:end
+		superuser: {
+			email: env.SUPERUSER_EMAIL || '',
+			username: env.SUPERUSER_USERNAME || '',
+			password: env.SUPERUSER_PASSWORD || ''
+		},
+		// @feature:start mail
+		smtp: {
+			host: env.SMTP_HOST || '',
+			port: Number(env.SMTP_PORT) || 465,
+			user: env.SMTP_USER || '',
+			password: env.SMTP_PASSWORD || '',
+			from: env.SMTP_FROM || '',
+			secure: env.SMTP_SECURE === 'true',
+			supportEmail: env.SMTP_SUPPORT_EMAIL || ''
+		},
+		// @feature:end
+		// @feature:start media
+		s3: {
+			accessKeyId: env.S3_ACCESS_KEY_ID || '',
+			secretAccessKey: env.S3_SECRET_ACCESS_KEY || '',
+			endpoint: env.S3_ENDPOINT || '',
+			bucket: env.S3_BUCKET_NAME || '',
+			region: env.S3_REGION || 'us-east-1'
+		},
+		// @feature:end
+		// @feature:start rate-limit
+		rateLimit: {
+			enabled: env.RATE_LIMIT_ENABLED !== 'false',
+			ttl: Number(env.RATE_LIMIT_TTL) || 60_000,
+			limit: Number(env.RATE_LIMIT_MAX) || 120,
+			authWindow: Number(env.RATE_LIMIT_AUTH_WINDOW) || 10,
+			authMax: Number(env.RATE_LIMIT_AUTH_MAX) || 100,
+			ipHeaders: (env.RATE_LIMIT_IP_HEADERS || 'x-forwarded-for')
+				.split(',')
+				.map((header) => header.trim().toLowerCase())
+				.filter(Boolean)
+		},
+		// @feature:end
+		oauth: {
+			google: {
+				clientId: env.OAUTH_GOOGLE_CLIENT_ID || '',
+				clientSecret: env.OAUTH_GOOGLE_CLIENT_SECRET || ''
+			}
+		}
+	});
+}
+
+@Injectable()
+export class CustomConfigService {
+	constructor(private readonly config: ConfigService<Config.Env, true>) {}
+
+	get app() {
+		return this.config.get('app', { infer: true });
+	}
+
+	get logger() {
+		return this.config.get('logger', { infer: true });
+	}
+
+	// @feature:start observability
+	get health() {
+		return this.config.get('health', { infer: true });
+	}
+	// @feature:end
+
+	get database() {
+		return this.config.get('database', { infer: true });
+	}
+
+	// @feature:start cache
+	get redis() {
+		return this.config.get('redis', { infer: true });
+	}
+	// @feature:end
+
+	// @feature:start openapi, queue, observability
+	get basicAuth() {
+		return this.config.get('basicAuth', { infer: true });
+	}
+	// @feature:end
+
+	get betterAuth() {
+		return this.config.get('betterAuth', { infer: true });
+	}
+
+	// @feature:start feature-flags
+	get growthbook() {
+		return this.config.get('growthbook', { infer: true });
+	}
+	// @feature:end
+
+	get superuser() {
+		return this.config.get('superuser', { infer: true });
+	}
+
+	// @feature:start mail
+	get smtp() {
+		return this.config.get('smtp', { infer: true });
+	}
+	// @feature:end
+
+	// @feature:start media
+	get s3() {
+		return this.config.get('s3', { infer: true });
+	}
+	// @feature:end
+
+	// @feature:start rate-limit
+	get rateLimit() {
+		return this.config.get('rateLimit', { infer: true });
+	}
+	// @feature:end
+
+	get oauth() {
+		return this.config.get('oauth', { infer: true });
+	}
+}
+
+export default Config;

package/templates/nest-api/files/src/common/services/feature-flag.service.ts

@@ -0,0 +1,117 @@
+import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { Interval } from '@nestjs/schedule';
+import {
+	GrowthBookClient,
+	UserScopedGrowthBook,
+	type Attributes,
+	type FeatureResult
+} from '@growthbook/growthbook';
+import { CustomConfigService } from './config.service';
+import { LoggerService } from './logger.service';
+
+const POLL_INTERVAL_MS = 60_000;
+
+/**
+ * Declare each flag here so `isOn`/`getValue` are typed against real keys
+ * instead of arbitrary strings — a renamed flag then fails to compile rather
+ * than silently evaluating to its default forever.
+ */
+export interface AppFeatures extends Record<string, unknown> {
+	example: boolean;
+}
+
+@Injectable()
+export class FeatureFlagService implements OnModuleInit, OnModuleDestroy {
+	private readonly client: GrowthBookClient<AppFeatures>;
+
+	constructor(
+		private readonly config: CustomConfigService,
+		private readonly logger: LoggerService
+	) {
+		const { apiHost, clientKey } = this.config.growthbook;
+		this.client = new GrowthBookClient<AppFeatures>({
+			apiHost,
+			clientKey,
+			enabled: true
+		});
+	}
+
+	async onModuleInit() {
+		try {
+			const { success, error } = await this.client.init({ timeout: 2000 });
+			if (success) {
+				this.logger.info('GrowthBook initialized');
+			} else {
+				this.logger.warn(
+					{ err: error },
+					'GrowthBook init did not load features — using defaults'
+				);
+			}
+		} catch (err) {
+			this.logger.error(
+				{ err },
+				'GrowthBook init failed — feature flags will use defaults'
+			);
+		}
+	}
+
+	onModuleDestroy() {
+		this.client.destroy();
+	}
+
+	/**
+	 * Poll GrowthBook for updated feature definitions.
+	 * Used instead of SSE streaming
+	 */
+	@Interval('growthbook-refresh', POLL_INTERVAL_MS)
+	async poll() {
+		try {
+			await this.client.refreshFeatures({ skipCache: true });
+		} catch (err) {
+			this.logger.warn(
+				{ err },
+				'GrowthBook poll refresh failed — keeping last known flags'
+			);
+		}
+	}
+
+	/**
+	 * Bind a set of user attributes (e.g. from the session) to a scoped
+	 * instance. Prefer this when evaluating several flags for the same user.
+	 */
+	forUser(attributes: Attributes): UserScopedGrowthBook<AppFeatures> {
+		return this.client.createScopedInstance({ attributes });
+	}
+
+	async refresh() {
+		await this.client.refreshFeatures();
+	}
+
+	isOn<K extends string & keyof AppFeatures = string>(
+		key: K,
+		attributes: Attributes = {}
+	): boolean {
+		return this.client.isOn(key, { attributes });
+	}
+
+	isOff<K extends string & keyof AppFeatures = string>(
+		key: K,
+		attributes: Attributes = {}
+	): boolean {
+		return this.client.isOff(key, { attributes });
+	}
+
+	getValue<
+		V extends AppFeatures[K],
+		K extends string & keyof AppFeatures = string
+	>(key: K, defaultValue: V, attributes: Attributes = {}) {
+		return this.client.getFeatureValue(key, defaultValue, { attributes });
+	}
+
+	evalFeature<
+		V extends AppFeatures[K],
+		K extends string & keyof AppFeatures = string
+	>(key: K, attributes: Attributes = {}): FeatureResult<V | null> {
+		return this.client.evalFeature(key, { attributes });
+	}
+}

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

@@ -0,0 +1,54 @@
+import { Injectable } from '@nestjs/common';
+import { v4 as ID } from 'uuid';
+import { createId as CUID } from '@paralleldrive/cuid2';
+import moment from 'moment';
+import crypto from 'crypto';
+import { generate } from 'randomstring';
+
+@Injectable()
+export class GeneratorService {
+	avatar(name: string) {
+		const seed = name.toLowerCase().replace(' ', '+');
+		const options = `seed=${seed}%size=500`;
+		return `https://api.dicebear.com/7.x/initials/png?${options}`;
+	}
+
+	numeric(length: number) {
+		return generate({ charset: 'numeric', length });
+	}
+
+	alphabet = (size = 64) => {
+		return crypto.randomBytes(size).toString('hex');
+	};
+
+	uuid() {
+		return ID();
+	}
+
+	cuid() {
+		return CUID();
+	}
+
+	now() {
+		return moment.utc();
+	}
+
+	currentDate() {
+		return new Date().toISOString().slice(0, 10);
+	}
+
+	currentHour() {
+		return new Date().toISOString().slice(0, 13);
+	}
+
+	addPrefix(prefix: string, text: string, delimiter = ':') {
+		return prefix + delimiter + text;
+	}
+
+	expiry(
+		amount: moment.DurationInputArg1,
+		unit: moment.unitOfTime.DurationConstructor
+	) {
+		return this.now().add(amount, unit);
+	}
+}

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

@@ -0,0 +1,10 @@
+export * from './config.service';
+export * from './generator.service';
+export * from './prisma.service';
+export * from './auth.service';
+export * from './logger.service';
+export * from './cache.service'; // @feature cache
+export * from './mail.service'; // @feature mail
+export * from './throttler-storage.service'; // @feature rate-limit
+export * from './auth-rate-limit.storage'; // @feature rate-limit
+export * from './feature-flag.service'; // @feature feature-flags

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

@@ -0,0 +1,14 @@
+import { Injectable, Inject, Scope } from '@nestjs/common';
+import { INQUIRER } from '@nestjs/core';
+import { PinoLogger, Params, PARAMS_PROVIDER_TOKEN } from 'nestjs-pino';
+
+@Injectable({ scope: Scope.TRANSIENT })
+export class LoggerService extends PinoLogger {
+	constructor(
+		@Inject(PARAMS_PROVIDER_TOKEN) params: Params,
+		@Inject(INQUIRER) parent: object
+	) {
+		super(params);
+		this.setContext(parent?.constructor?.name ?? 'App');
+	}
+}

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

@@ -0,0 +1,44 @@
+import { Injectable } from '@nestjs/common';
+import { InjectQueue } from '@nestjs/bullmq';
+import { Queue } from 'bullmq';
+import {
+	MailJob,
+	ActivationData,
+	ActivationTwoFaData,
+	WelcomeData,
+	ForgotPasswordData,
+	SetPasswordData
+} from 'common/types';
+
+@Injectable()
+export class MailService {
+	constructor(@InjectQueue('mail') private mail: Queue) {}
+
+	activation = (data: ActivationData) => {
+		this.mail.add(MailJob.Activation, data);
+	};
+
+	activationTwofa = (data: ActivationTwoFaData) => {
+		this.mail.add(MailJob.ActivationTwofa, data);
+	};
+
+	welcome = (data: WelcomeData) => {
+		this.mail.add(MailJob.Welcome, data);
+	};
+
+	forgotPassword = (data: ForgotPasswordData) => {
+		this.mail.add(MailJob.ForgotPassword, data);
+	};
+
+	resetPassword = (data: string) => {
+		this.mail.add(MailJob.ResetPassword, data);
+	};
+
+	passwordChanged = (data: string) => {
+		this.mail.add(MailJob.PasswordChanged, data);
+	};
+
+	setPassword = (data: SetPasswordData) => {
+		this.mail.add(MailJob.SetPassword, data);
+	};
+}