@aurostack/stacks 0.1.0

package/templates/nest-api/files/src/common/processors/mail/process.ts

@@ -0,0 +1,225 @@
+import { Job } from 'bullmq';
+import { ISendMailOptions } from '@nestjs-modules/mailer';
+import { render } from '@react-email/render';
+import Activation from '@emails/activation';
+import ActivationTwofa from '@emails/activation-twofa';
+import Welcome from '@emails/welcome';
+import ForgotPassword from '@emails/forgot-password';
+import PasswordChanged from '@emails/password-changed';
+import ResetPassword from '@emails/reset-password';
+import SetPassword from '@emails/set-password';
+import {
+	MailJob,
+	EmailGlobalProps,
+	ActivationData,
+	ActivationTwoFaData,
+	WelcomeData,
+	SetPasswordData,
+	ForgotPasswordData
+} from 'common/types';
+
+type Options = Omit<ISendMailOptions, 'from'>;
+
+abstract class ProcessAbstract<T> {
+	abstract subject: string;
+	abstract preview?: string;
+
+	constructor(
+		protected readonly job: Job<T, any, string>,
+		protected readonly globals: EmailGlobalProps
+	) {}
+
+	abstract process(): Options;
+}
+
+class ActivationProcess extends ProcessAbstract<ActivationData> {
+	subject = 'Account Activation';
+	preview = 'Activate your account!';
+
+	process(): Options {
+		const {
+			subject,
+			preview,
+			job: {
+				data: { to, firstName, token, url }
+			}
+		} = this;
+		const html = render(
+			Activation({ ...this.globals, subject, preview, firstName, token, url })
+		);
+		return { to, subject, html };
+	}
+}
+
+class ActivationTwofaProcess extends ProcessAbstract<ActivationTwoFaData> {
+	subject = 'Enable Two Factor Authentication';
+	preview = 'Scan the code!';
+
+	process(): Options {
+		const {
+			subject,
+			preview,
+			job: {
+				data: { to, firstName, qrcode }
+			}
+		} = this;
+		const html = render(
+			ActivationTwofa({ ...this.globals, subject, preview, firstName })
+		);
+		return {
+			to,
+			subject,
+			html,
+			attachments: [
+				{
+					filename: 'qrcode.png',
+					path: qrcode,
+					cid: 'qrcode'
+				}
+			]
+		};
+	}
+}
+
+class ForgotPasswordProcess extends ProcessAbstract<ForgotPasswordData> {
+	subject = 'Password Reset Request';
+	preview = 'Reset your password!';
+
+	process(): Options {
+		const {
+			subject,
+			preview,
+			job: {
+				data: { to, token, url }
+			}
+		} = this;
+		const html = render(
+			ForgotPassword({
+				...this.globals,
+				subject,
+				preview,
+				token,
+				url
+			})
+		);
+		return { to, subject, html };
+	}
+}
+
+class WelcomeProcess extends ProcessAbstract<WelcomeData> {
+	subject = `Welcome aboard 🎉`;
+	preview = 'Your account has been activated!';
+
+	process(): Options {
+		const {
+			subject,
+			preview,
+			job: {
+				data: { to, firstName, clientLoginPage, supportEmail }
+			}
+		} = this;
+		const html = render(
+			Welcome({
+				...this.globals,
+				firstName,
+				subject,
+				preview,
+				clientLoginPage,
+				supportEmail
+			})
+		);
+		return { to, subject, html };
+	}
+}
+
+class SetPasswordProcess extends ProcessAbstract<SetPasswordData> {
+	subject = 'Account Created';
+	preview = 'Set your account password!';
+
+	process(): Options {
+		const {
+			subject,
+			preview,
+			job: {
+				data: { to, firstName, token }
+			}
+		} = this;
+		const html = render(
+			SetPassword({
+				...this.globals,
+				firstName,
+				subject,
+				preview,
+				token
+			})
+		);
+		return { to, subject, html };
+	}
+}
+
+class ResetPasswordProcess extends ProcessAbstract<string> {
+	subject = 'Password Reset';
+	preview = 'New password created!';
+
+	process(): Options {
+		const {
+			subject,
+			preview,
+			job: { data: to }
+		} = this;
+		const html = render(
+			ResetPassword({
+				...this.globals,
+				subject,
+				preview
+			})
+		);
+		return { to, subject, html };
+	}
+}
+
+class PasswordChangedProcess extends ProcessAbstract<string> {
+	subject = 'Password Changed';
+	preview = 'New password created!';
+
+	process(): Options {
+		const {
+			subject,
+			preview,
+			job: { data: to }
+		} = this;
+		const html = render(
+			PasswordChanged({
+				...this.globals,
+				subject,
+				preview
+			})
+		);
+		return { to, subject, html };
+	}
+}
+
+export class ProcessFactory {
+	private static jobs = {
+		[MailJob.Activation]: ActivationProcess,
+		[MailJob.ActivationTwofa]: ActivationTwofaProcess,
+		[MailJob.Welcome]: WelcomeProcess,
+		[MailJob.ForgotPassword]: ForgotPasswordProcess,
+		[MailJob.ResetPassword]: ResetPasswordProcess,
+		[MailJob.PasswordChanged]: PasswordChangedProcess,
+		[MailJob.SetPassword]: SetPasswordProcess
+	};
+
+	private static getProcess(name: MailJob) {
+		const entry = Object.entries(ProcessFactory.jobs).find(
+			(item) => item[0] === name
+		);
+		return entry ? entry[1] : null;
+	}
+
+	static init(job: Job<any, any, string>, globals: EmailGlobalProps) {
+		const Process = ProcessFactory.getProcess(job.name as MailJob);
+		if (!Process) return null;
+		return new Process(job, globals);
+	}
+}

package/templates/nest-api/files/src/common/schemas/fields.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { Prisma } from '@db/client';
+
+/**
+ * Reusable Zod fields. Request schemas validate and coerce what arrives;
+ * response schemas are codecs that turn what a service returns (Date, Decimal)
+ * into what goes over the wire, and OpenAPI documents the wire side.
+ */
+
+/** `Date` → ISO 8601 date-time string. */
+export const dateTime = () =>
+	z.codec(z.date(), z.iso.datetime(), {
+		decode: (date) => date.toISOString(),
+		encode: (iso) => new Date(iso)
+	});
+
+/** `Date` → `YYYY-MM-DD`. */
+export const dateOnly = () =>
+	z.codec(z.date(), z.iso.date(), {
+		decode: (date) => date.toISOString().slice(0, 10),
+		encode: (iso) => new Date(iso)
+	});
+
+/** `Prisma.Decimal` (or a numeric string) → number, rounded to 4 places. */
+export const decimal = () =>
+	z.codec(z.union([z.instanceof(Prisma.Decimal), z.string()]), z.number(), {
+		decode: (value) => new Prisma.Decimal(value).toDecimalPlaces(4).toNumber(),
+		encode: (value) => new Prisma.Decimal(value)
+	});
+
+/** An email address, stored and compared in lower case. */
+export const email = () => z.email().toLowerCase();
+
+/**
+ * Free-text search: at least three characters, with a blank value (a cleared
+ * search box sends `?search=`) treated as absent rather than rejected.
+ */
+export const search = () =>
+	z
+		.union([z.string().trim().min(3), z.literal('')])
+		.transform((value) => value || undefined)
+		.optional();
+
+/**
+ * A comma-separated sort spec over `keys`, each optionally prefixed with `-`
+ * for descending, e.g. `name,-createdAt`.
+ */
+export const sortKeys = (keys: readonly string[]) =>
+	z
+		.string()
+		.refine(
+			(value) =>
+				value.split(',').every((key) => keys.includes(key.replace(/^-/, ''))),
+			{ message: `Sort key must be one of the following: ${keys.join(', ')}` }
+		)
+		.meta({ example: keys.join(',') })
+		.optional();
+
+/** A file part in a multipart/form-data body (documentation only). */
+export const binary = () => z.string().meta({ format: 'binary' });
+
+/**
+ * Require two fields of an object schema to be equal, e.g. a password and its
+ * confirmation. The issue is reported on `confirm`.
+ */
+export const mustMatch =
+	<T extends Record<string, unknown>>(field: keyof T, confirm: keyof T) =>
+	(value: T, ctx: z.RefinementCtx) => {
+		if (value[field] !== value[confirm]) {
+			ctx.addIssue({
+				code: 'custom',
+				path: [confirm as string],
+				message: `${String(confirm)} must match ${String(field)}`
+			});
+		}
+	};

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

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

package/templates/nest-api/files/src/common/services/auth-rate-limit.storage.ts

@@ -0,0 +1,79 @@
+import type IoRedis from 'ioredis';
+import { CacheService } from './cache.service';
+
+const PREFIX = 'auth:rl';
+
+/**
+ * Count one request against a fixed window and decide whether it is allowed,
+ * in a single round-trip. A separate GET + SET would let concurrent requests
+ * all read a below-limit count before any increment lands.
+ *
+ * Denied requests are not counted, so the window is not extended while a
+ * client keeps retrying.
+ *
+ * KEYS: counter. ARGV: window(ms), max.
+ * Returns: { allowed(0|1), pttl(ms) } — pttl is only meaningful when denied.
+ */
+const CONSUME_SCRIPT = `
+local key = KEYS[1]
+local window = tonumber(ARGV[1])
+local max = tonumber(ARGV[2])
+
+local count = tonumber(redis.call('GET', key)) or 0
+if count >= max then
+	local pttl = redis.call('PTTL', key)
+	if pttl < 0 then
+		-- Key exists without a TTL; re-arm it so the client is not locked out.
+		redis.call('PEXPIRE', key, window)
+		pttl = window
+	end
+	return { 0, pttl }
+end
+
+if redis.call('INCR', key) == 1 then
+	redis.call('PEXPIRE', key, window)
+end
+
+return { 1, 0 }
+`;
+
+type AuthRateLimitRedis = IoRedis & {
+	authRateLimitConsume(
+		key: string,
+		window: number,
+		max: number
+	): Promise<[number, number]>;
+};
+
+/**
+ * Redis-backed storage for better-auth's `/auth/*` rate limiter.
+ *
+ * Passed as `rateLimit.customStorage` rather than `secondaryStorage`: the latter
+ * is also consumed by better-auth's internal adapter for **session** persistence,
+ * so setting it would silently relocate sessions out of Postgres. `customStorage`
+ * is rate-limit-scoped and takes precedence over `rateLimit.storage`.
+ *
+ * better-auth passes each rule's `window` in seconds and expects `retryAfter`
+ * back in seconds.
+ */
+export const createAuthRateLimitStorage = (cache: CacheService) => {
+	const redis = cache.db as AuthRateLimitRedis;
+	redis.defineCommand('authRateLimitConsume', {
+		numberOfKeys: 1,
+		lua: CONSUME_SCRIPT
+	});
+
+	return {
+		consume: async (key: string, rule: { window: number; max: number }) => {
+			const [allowed, pttl] = await redis.authRateLimitConsume(
+				`${PREFIX}:${key}`,
+				rule.window * 1000,
+				rule.max
+			);
+
+			return allowed === 1
+				? { allowed: true, retryAfter: null }
+				: { allowed: false, retryAfter: Math.ceil(pttl / 1000) };
+		}
+	};
+};

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

@@ -0,0 +1,16 @@
+import { Injectable } from '@nestjs/common';
+import { AuthService } from '@thallesp/nestjs-better-auth';
+import { BetterAuth } from 'lib/auth';
+
+@Injectable()
+export class CustomAuthService {
+	constructor(private readonly auth: AuthService<BetterAuth>) {}
+
+	get api() {
+		return this.auth.api;
+	}
+
+	get instance() {
+		return this.auth;
+	}
+}

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

@@ -0,0 +1,118 @@
+import { Injectable, OnModuleDestroy } from '@nestjs/common';
+import IoRedis from 'ioredis';
+import { CustomConfigService } from './config.service';
+import { User } from '@db/client';
+// import { RoleFull } from 'common/types';
+import { Key } from '../utils';
+
+@Injectable()
+export class CacheService implements OnModuleDestroy {
+	readonly db: IoRedis;
+	readonly DEFAULT_EXPIRY = 86400; // 24 hours
+
+	constructor(private cfg: CustomConfigService) {
+		this.db = new IoRedis({ ...cfg.redis });
+	}
+
+	async disconnect() {
+		await this.db.disconnect();
+	}
+
+	async onModuleDestroy() {
+		await this.db.disconnect();
+	}
+
+	async truncate() {
+		await this.db.flushall();
+	}
+
+	/** Delete a plain string key (no-op if it does not exist). */
+	async delete(key: string) {
+		await this.db.del(key);
+	}
+
+	async store<T = string>(key: string, data: T, exp = this.DEFAULT_EXPIRY) {
+		if (typeof data === 'string') {
+			await this.db.setex(key, exp, data);
+			return;
+		}
+
+		const stringified = JSON.stringify(data);
+		await this.db.setex(key, exp, stringified);
+	}
+
+	async hashStore<T extends { id: string | number }>(
+		key: Key.TypeKey,
+		item: T
+	) {
+		await this.db.hset(
+			Key.Type[key],
+			Key.id(key, item.id),
+			JSON.stringify(item)
+		);
+	}
+
+	/**
+	 * Atomic counter with a fixed window — returns the count after incrementing.
+	 * The TTL is set only on first hit, so the window is fixed (not sliding).
+	 */
+	async incr(key: string, windowSeconds: number): Promise<number> {
+		const count = await this.db.incr(key);
+		if (count === 1) await this.db.expire(key, windowSeconds);
+		return count;
+	}
+
+	async fetch<T = string>(key: string): Promise<T | null> {
+		const cached = await this.db.get(key);
+		if (!cached) return null;
+
+		try {
+			return JSON.parse(cached) as T;
+		} catch {
+			return cached as T;
+		}
+	}
+
+	async hashFetch<Key extends Key.TypeKey, ID extends string | number>(
+		key: Key,
+		id: ID
+	): Promise<Key.EntityMap<Key> | null> {
+		const result = await this.db.hget(Key.Type[key], Key.id(key, id));
+		return result ? (JSON.parse(result) as Key.EntityMap<Key>) : null;
+	}
+
+	async hashFetchAll<Key extends Key.TypeKey>(
+		key: Key
+	): Promise<Key.EntityMap<Key>[]> {
+		const result = await this.db.hvals(Key.Type[key]);
+		return result.map((item) => JSON.parse(item) as Key.EntityMap<Key>);
+	}
+
+	async hashDelete<Key extends Key.TypeKey, ID extends string | number>(
+		key: Key,
+		id: ID
+	): Promise<void> {
+		await this.db.hdel(Key.Type[key], Key.id(key, id));
+	}
+
+	async deleteKey(key: Key.TypeKey) {
+		await this.db.del(Key.Type[key]);
+	}
+
+	/**
+	 * Bulk-load a set of entities into their hash in one round trip. Model new
+	 * bulk loaders on this — a per-item `hset` in a loop costs one round trip
+	 * each, which is what the pipeline avoids.
+	 */
+	async storeUsers(list: User[]) {
+		const pipeline = this.db.pipeline();
+		for (const item of list) {
+			pipeline.hset(
+				Key.Type.Users,
+				Key.id('Users', item.id),
+				JSON.stringify(item)
+			);
+		}
+		await pipeline.exec();
+	}
+}