@aurostack/stacks 0.1.0

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

@@ -0,0 +1,106 @@
+import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { PrismaPg } from '@prisma/adapter-pg';
+import { PaginationOptions } from 'common/types';
+import { Prisma, PrismaClient } from '@db/client';
+import { getPaginationInfo } from '../utils';
+import type { PaginationMeta } from '../entity';
+import { CustomConfigService } from './config.service';
+
+type TableNames = Array<{ tablename: string }>;
+
+const setupExtensions = (db: PrismaClient) =>
+	db.$extends({
+		model: {
+			$allModels: {
+				async exists<
+					Type,
+					Arguments,
+					Result extends Prisma.Result<Type, Arguments, 'count'>
+				>(this: Type, where: Prisma.Args<Type, 'count'>['where']) {
+					const ctx = Prisma.getExtensionContext(this) as any;
+					const counts: Result = await ctx.count({ where });
+					return Boolean(counts);
+				},
+				async paginate<
+					Type,
+					Args extends Omit<
+						Prisma.Args<Type, 'findMany'>,
+						'skip' | 'take' | 'cursor'
+					>,
+					Result extends Prisma.Result<Type, Args, 'findMany'>
+				>(this: Type, args: Args & PaginationOptions) {
+					const { limit, page, where, ...rest } = args;
+					const {
+						skip,
+						take,
+						page: currentPage
+					} = getPaginationInfo({
+						limit,
+						page
+					});
+					const ctx = Prisma.getExtensionContext(this) as any;
+					const [list, total]: [Result, number] = await Promise.all([
+						ctx.findMany({ ...rest, skip, take, where }),
+						ctx.count({ where })
+					]);
+					const meta: PaginationMeta = {
+						total,
+						currentPage,
+						pageSize: list.length,
+						lastPage: Math.ceil(total / take) || 1
+					};
+					const result: [Result, PaginationMeta] = [list, meta];
+					return result;
+				}
+			}
+		}
+	});
+
+@Injectable()
+export class PrismaService
+	extends PrismaClient
+	implements OnModuleInit, OnModuleDestroy
+{
+	constructor(private readonly c: CustomConfigService) {
+		const adapter = new PrismaPg({
+			connectionString: c.database.url
+		});
+		super({
+			adapter,
+			transactionOptions: {
+				isolationLevel: Prisma.TransactionIsolationLevel.Serializable,
+				maxWait: 6000,
+				timeout: 150000
+			}
+		});
+	}
+
+	get x() {
+		return setupExtensions(this);
+	}
+
+	async onModuleInit() {
+		await this.$connect();
+	}
+
+	async onModuleDestroy() {
+		await this.$disconnect();
+	}
+
+	async truncate() {
+		const tableNames = await this
+			.$queryRaw<TableNames>`SELECT tablename from pg_tables where schemaname='public'`;
+
+		const tables = tableNames
+			.map(({ tablename }) => tablename)
+			.filter((name) => name !== '_prisma_migrations')
+			.map((name) => `"public"."${name}"`)
+			.join(', ');
+
+		try {
+			await this.$executeRawUnsafe(`TRUNCATE TABLE ${tables} CASCADE;`);
+		} catch (error) {
+			console.log({ error });
+		}
+	}
+}

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

@@ -0,0 +1,112 @@
+import { Injectable } from '@nestjs/common';
+import { ThrottlerStorage } from '@nestjs/throttler';
+import { ThrottlerStorageRecord } from '@nestjs/throttler/dist/throttler-storage-record.interface';
+import type IoRedis from 'ioredis';
+import { CacheService } from './cache.service';
+
+const HITS_PREFIX = 'throttle';
+
+/**
+ * Increment the hit counter and decide whether the tracker is blocked, in a
+ * single round-trip. Splitting this into INCR + PTTL + SET would let two
+ * concurrent requests both observe a below-limit count.
+ *
+ * KEYS: hits, block. ARGV: ttl(ms), limit, blockDuration(ms).
+ * Returns: { totalHits, hitsPttl(ms), isBlocked(0|1), blockPttl(ms) }.
+ */
+const INCREMENT_SCRIPT = `
+local hitsKey = KEYS[1]
+local blockKey = KEYS[2]
+local ttl = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+local blockDuration = tonumber(ARGV[3])
+
+-- Already serving a block: report it without consuming another hit.
+local blockPttl = redis.call('PTTL', blockKey)
+if blockPttl > 0 then
+	local hits = tonumber(redis.call('GET', hitsKey)) or (limit + 1)
+	local hitsPttl = redis.call('PTTL', hitsKey)
+	if hitsPttl < 0 then hitsPttl = 0 end
+	return { hits, hitsPttl, 1, blockPttl }
+end
+
+local hits = redis.call('INCR', hitsKey)
+if hits == 1 then
+	redis.call('PEXPIRE', hitsKey, ttl)
+end
+
+local hitsPttl = redis.call('PTTL', hitsKey)
+if hitsPttl < 0 then
+	-- Key exists without a TTL (or raced with expiry); re-arm the window.
+	redis.call('PEXPIRE', hitsKey, ttl)
+	hitsPttl = ttl
+end
+
+if hits > limit then
+	redis.call('SET', blockKey, '1', 'PX', blockDuration)
+	return { hits, hitsPttl, 1, blockDuration }
+end
+
+return { hits, hitsPttl, 0, 0 }
+`;
+
+type IncrementResult = [number, number, number, number];
+
+type ThrottlerRedis = IoRedis & {
+	throttlerIncrement(
+		hitsKey: string,
+		blockKey: string,
+		ttl: number,
+		limit: number,
+		blockDuration: number
+	): Promise<IncrementResult>;
+};
+
+/**
+ * Redis-backed {@link ThrottlerStorage}, sharing the ioredis connection already
+ * opened by {@link CacheService}. In-memory storage would give each process its
+ * own buckets, which is wrong as soon as more than one instance runs.
+ *
+ * `ttl` and `blockDuration` arrive in milliseconds; `timeToExpire` and
+ * `timeToBlockExpire` are returned in seconds, matching `ThrottlerStorageService`.
+ */
+@Injectable()
+export class RedisThrottlerStorage implements ThrottlerStorage {
+	private readonly redis: ThrottlerRedis;
+
+	constructor(private readonly cache: CacheService) {
+		this.redis = this.cache.db as ThrottlerRedis;
+		this.redis.defineCommand('throttlerIncrement', {
+			numberOfKeys: 2,
+			lua: INCREMENT_SCRIPT
+		});
+	}
+
+	async increment(
+		key: string,
+		ttl: number,
+		limit: number,
+		blockDuration: number,
+		throttlerName: string
+	): Promise<ThrottlerStorageRecord> {
+		const hitsKey = `${HITS_PREFIX}:${throttlerName}:${key}`;
+		const [totalHits, hitsPttl, isBlocked, blockPttl] =
+			await this.redis.throttlerIncrement(
+				hitsKey,
+				`${hitsKey}:block`,
+				ttl,
+				limit,
+				blockDuration
+			);
+
+		return {
+			totalHits,
+			timeToExpire: toSeconds(hitsPttl),
+			isBlocked: isBlocked === 1,
+			timeToBlockExpire: toSeconds(blockPttl)
+		};
+	}
+}
+
+const toSeconds = (milliseconds: number) =>
+	Math.ceil(Math.max(milliseconds, 0) / 1000);

package/templates/nest-api/files/src/common/types/email.ts

@@ -0,0 +1,55 @@
+export enum MailJob {
+	Activation = 'activation',
+	ActivationTwofa = 'activation-twofa',
+	ForgotPassword = 'forgot-password',
+	PasswordChanged = 'password-changed',
+	ResetPassword = 'reset-password',
+	SetPassword = 'set-password',
+	Welcome = 'welcome'
+}
+
+export interface EmailGlobalProps {
+	host: string;
+	appName: string;
+	footerText: string;
+}
+
+export interface EmailBaseProps extends EmailGlobalProps {
+	subject: string;
+	preview?: string;
+}
+
+export type EmailProps<T extends { to: string }> = Omit<T, 'to'> &
+	EmailBaseProps;
+
+export interface ActivationData {
+	to: string;
+	firstName: string;
+	token: string;
+	url: string;
+}
+
+export interface ActivationTwoFaData {
+	to: string;
+	firstName: string;
+	qrcode: string;
+}
+
+export interface ForgotPasswordData {
+	to: string;
+	token: string;
+	url: string;
+}
+
+export interface SetPasswordData {
+	to: string;
+	firstName: string;
+	token: string;
+}
+
+export interface WelcomeData {
+	to: string;
+	firstName: string;
+	clientLoginPage: string;
+	supportEmail: string;
+}

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

@@ -0,0 +1,3 @@
+export * from './prisma';
+export * from './misc';
+export * from './email'; // @feature mail

package/templates/nest-api/files/src/common/types/misc.ts

@@ -0,0 +1,20 @@
+export interface PaginationOptions {
+	page?: number;
+	limit?: number;
+}
+
+export interface PaginationInfo {
+	skip: number;
+	take: number;
+	page: number;
+}
+
+export interface SortNesting {
+	key: string;
+	values: string[];
+}
+
+export interface SortObjectArg {
+	sort?: string;
+	nesting?: SortNesting[];
+}

package/templates/nest-api/files/src/common/types/prisma.ts

@@ -0,0 +1,18 @@
+import { PrismaClient } from '@db/client';
+
+export type PrismaModelName = keyof Omit<
+	PrismaClient,
+	| '$on'
+	| '$connect'
+	| '$disconnect'
+	| '$extends'
+	| '$use'
+	| '$queryRaw'
+	| '$executeRaw'
+	| '$executeRawUnsafe'
+	| '$queryRawUnsafe'
+	| '$transaction'
+	| symbol
+>;
+
+export type PrismaModel<Name extends PrismaModelName> = PrismaClient[Name];

package/templates/nest-api/files/src/common/utils/enum.ts

@@ -0,0 +1,39 @@
+import { Gender as G } from '@db/enums';
+namespace Enum {
+	/**
+	 * S3 key prefixes. Add a folder here rather than passing a raw string, and
+	 * list it in `PrivateUploadFolders` if its objects must not be publicly
+	 * readable — that set is what decides the object ACL on upload, so an
+	 * omission silently makes private files world-readable.
+	 */
+	export enum UploadFolder {
+		AVATARS = 'avatars',
+		UPLOAD = 'upload',
+		PRIVATE = 'private'
+	}
+
+	export const PrivateUploadFolders: ReadonlySet<UploadFolder> = new Set([
+		UploadFolder.PRIVATE
+	]);
+
+	export const isPrivateUploadFolder = (folder: UploadFolder) =>
+		PrivateUploadFolders.has(folder);
+
+	export enum Gender {
+		MALE = 'male',
+		FEMALE = 'female'
+	}
+	export type UserGender = G | Gender;
+	export const Genders = Object.values(Gender);
+	export const gendersErrorMessage = () => {
+		const GENDER: Record<Gender, string> = {
+			[Gender.MALE]: 'male',
+			[Gender.FEMALE]: 'female'
+		};
+
+		const genders = Genders.map((g) => `${g} (${GENDER[g]})`).join(', ');
+		return `genderId must be one of [${genders}]`;
+	};
+}
+
+export default Enum;

package/templates/nest-api/files/src/common/utils/helpers.ts

@@ -0,0 +1,139 @@
+import {
+	PaginationInfo,
+	PaginationOptions,
+	SortNesting,
+	SortObjectArg
+} from 'common/types';
+
+/**
+ *	Check if an enum includes specified value
+ * @param type - Type of the enum to check
+ * @param value - Value to check
+ */
+export const isInEnum = <T extends ArrayLike<unknown>, U extends keyof T>(
+	type: T,
+	value: U
+) => Object.values(type).includes(value);
+
+export const getPaginationInfo = (
+	options: PaginationOptions
+): PaginationInfo => {
+	const page = options.page && options.page > 0 ? options.page : 1;
+	const take = options.limit && options.limit > 0 ? options.limit : 10;
+	return {
+		skip: (page - 1) * take,
+		take,
+		page
+	};
+};
+
+/**
+ * Parse a value as boolean
+ * @param value - value to check
+ * @param defaultValue - default value to return for an invalid `value`
+ */
+export const parseBoolean = (
+	value: string | number | null | undefined,
+	defaultValue = false
+): boolean => {
+	if (value === '' || value === null || value === undefined) {
+		return defaultValue;
+	}
+
+	if (typeof value === 'string') {
+		if (value.trim() === '') {
+			return defaultValue;
+		}
+
+		const toCheck = value.trim().toLowerCase();
+		if (toCheck === '1' || toCheck === 'true' || toCheck === 'yes') {
+			return true;
+		}
+	}
+
+	if (typeof value === 'number') {
+		if (value >= 1) {
+			return true;
+		}
+	}
+
+	return false;
+};
+
+/**
+ * It takes an array of any type and returns a random item from that array
+ * @param arr - The array to get a random item from.
+ */
+export const getRandomArrayItem = <T>(arr: T[]) =>
+	arr[Math.floor(Math.random() * arr.length)];
+
+/**
+ * "Convert a string to lowercase, optionally capitalizing the first letter."
+ *
+ * @param str - The string to be converted to lowercase.
+ * @param capitalizeFirstLetter - If true, the first letter of the string will
+ * be capitalized.
+ */
+export const lowercase = (str: string, capitalizeFirstLetter = false) => {
+	const result = str.trim().toLocaleLowerCase();
+
+	return capitalizeFirstLetter
+		? result.replace(/^[a-z]/, (letter) => letter.toUpperCase())
+		: result;
+};
+
+export const isValidUUID = (value: string) => {
+	const uuidPattern =
+		/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/;
+
+	return uuidPattern.test(value);
+};
+
+/**
+ * Create sort objects from a string
+ * @param sort - the string to convert to a sort object
+ * @returns the sort object
+ */
+export function createSortObject<T = any>(
+	options: SortObjectArg | undefined
+): T[];
+export function createSortObject<T = any>(sort?: string): T[];
+export function createSortObject<T = any>(
+	param: SortObjectArg | string | undefined
+): T[] {
+	const list: T[] = [];
+
+	let sort: string | undefined;
+	let nesting: SortNesting[] | undefined;
+
+	if (!param) return list;
+
+	if (typeof param === 'string') {
+		sort = param;
+	} else {
+		sort = param.sort;
+		nesting = param.nesting;
+	}
+
+	if (!sort) return list;
+
+	const keys = sort.split(',');
+	keys.forEach((key) => {
+		const name = key.replace(/^-/, '');
+		const value = key.startsWith('-') ? 'desc' : 'asc';
+		const obj: T = { [name]: value } as T;
+
+		if (!nesting || !nesting.length) {
+			list.push(obj);
+		} else {
+			const nest = nesting.find((n) => n.values.includes(name));
+			if (!nest) {
+				list.push(obj);
+			} else {
+				list.push({ [nest.key]: obj } as T);
+			}
+		}
+	});
+
+	return list;
+}

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

@@ -0,0 +1,5 @@
+export { default as Enum } from './enum';
+export * from './helpers';
+export * from './redis.keys'; // @feature cache
+export * from './ip'; // @feature rate-limit
+export * from './records';

package/templates/nest-api/files/src/common/utils/ip.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve the client IP from proxy headers, falling back to the socket address.
+ *
+ * Behind a reverse proxy every request carries the proxy's socket address, so
+ * rate-limit buckets keyed on it would be shared by all clients. `x-forwarded-for`
+ * is a comma-separated chain (`client, proxy1, proxy2`) — the client is first.
+ */
+export const getClientIp = (
+	req: Record<string, any>,
+	headerNames: string[]
+): string => {
+	const headers = (req.headers ?? {}) as Record<string, string | string[]>;
+
+	for (const name of headerNames) {
+		const raw = headers[name];
+		const value = Array.isArray(raw) ? raw[0] : raw;
+		const first = value?.split(',')[0]?.trim();
+		if (first) return first;
+	}
+
+	return req.ip ?? req.socket?.remoteAddress ?? 'unknown';
+};

package/templates/nest-api/files/src/common/utils/records.ts

@@ -0,0 +1,66 @@
+import { BadRequestException } from '@nestjs/common';
+import type { PrismaService } from '../services';
+import type { PrismaModelName } from '../types';
+
+/**
+ * Database-backed checks for request values. A schema validates shape without
+ * a database handle, so these run in the service that uses the value. Matching
+ * is case-insensitive, and failures are 400s in the same `Validation: …` form
+ * the validation pipe produces.
+ */
+
+const matches = (
+	db: PrismaService,
+	model: PrismaModelName,
+	field: string,
+	value: string
+): Promise<boolean> =>
+	(db.x[model] as any).exists({
+		[field]: { equals: value, mode: 'insensitive' }
+	});
+
+/** Reject `value` unless some `model` row has it in `field`. Skips empties. */
+export async function ensureExists(
+	db: PrismaService,
+	model: PrismaModelName,
+	field: string,
+	value: string | null | undefined
+) {
+	if (!value) return;
+	if (!(await matches(db, model, field, value))) {
+		throw new BadRequestException(
+			`Validation: ${field} '${value}' does not exist`
+		);
+	}
+}
+
+/** Reject `values` unless every one exists in `model`.`field`. */
+export async function ensureEachExists(
+	db: PrismaService,
+	model: PrismaModelName,
+	field: string,
+	values: readonly string[] | null | undefined
+) {
+	for (const value of values ?? []) {
+		if (!(await matches(db, model, field, value))) {
+			throw new BadRequestException(
+				`Validation: ${field} element with id '${value}' does not exist`
+			);
+		}
+	}
+}
+
+/** Reject `value` if a `model` row already has it in `field`. */
+export async function ensureUnique(
+	db: PrismaService,
+	model: PrismaModelName,
+	field: string,
+	value: string | null | undefined
+) {
+	if (!value) return;
+	if (await matches(db, model, field, value)) {
+		throw new BadRequestException(
+			`Validation: ${field} '${value}' already exists`
+		);
+	}
+}

package/templates/nest-api/files/src/common/utils/redis.keys.ts

@@ -0,0 +1,31 @@
+import { User } from '@db/client';
+
+/**
+ * Namespaced Redis keys for hash-cached entities.
+ *
+ * Adding a cached entity means three matching edits: a `Type` member (the hash
+ * key), a `TypeEntityMap` entry (what a member deserializes to), and an `ID`
+ * builder (the field key). They are kept in one file precisely so a mismatch
+ * shows up here rather than as a runtime cache miss.
+ */
+export namespace Key {
+	type IdType = number | string;
+
+	export enum Type {
+		Users = 'users'
+	}
+
+	export type TypeKey = keyof typeof Type;
+
+	type TypeEntityMap = {
+		Users: User;
+	};
+	export type EntityMap<T extends TypeKey> = TypeEntityMap[T];
+
+	const ID: Record<Type, <T = IdType>(id: T) => string> = {
+		[Type.Users]: (id) => `uid:${id}`
+	};
+
+	export const id = <T = IdType>(typeKey: TypeKey, key: T) =>
+		ID[Type[typeKey]](key);
+}

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

@@ -0,0 +1,33 @@
+import { hasPermission } from 'lib/access';
+
+describe('hasPermission', () => {
+	it('grants a permission the role holds', () => {
+		expect(hasPermission('user', { session: ['list'] })).toBe(true);
+		expect(hasPermission('user', { session: ['list', 'revoke'] })).toBe(true);
+		expect(hasPermission('admin', { user: ['ban'] })).toBe(true);
+		expect(hasPermission('superuser', { user: ['delete'] })).toBe(true);
+	});
+
+	it('denies a permission the role lacks', () => {
+		expect(hasPermission('user', { user: ['list'] })).toBe(false);
+		expect(hasPermission('user', { user: ['delete'] })).toBe(false);
+		expect(hasPermission('admin', { user: ['delete'] })).toBe(false);
+	});
+
+	it("treats a missing role as the admin plugin's defaultRole", () => {
+		expect(hasPermission(null, { session: ['list'] })).toBe(true);
+		expect(hasPermission(undefined, { session: ['list'] })).toBe(true);
+		expect(hasPermission('', { session: ['list'] })).toBe(true);
+		// ...but the default role is still only a `user`.
+		expect(hasPermission(null, { user: ['delete'] })).toBe(false);
+	});
+
+	it('fails closed on an unrecognized role', () => {
+		expect(hasPermission('bogus', { session: ['list'] })).toBe(false);
+	});
+
+	it('unions comma-separated roles, ignoring unknown ones', () => {
+		expect(hasPermission('bogus,user', { session: ['list'] })).toBe(true);
+		expect(hasPermission('user, admin', { user: ['ban'] })).toBe(true);
+	});
+});