@aurostack/stacks 0.1.0

package/templates/nest-api/files/src/realtime/constants/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Socket.io path — kept distinct from the REST surface so a reverse proxy can
+ * route WebSocket upgrades independently. The frontend must connect with the
+ * same `path`.
+ */
+export const SOCKET_PATH = '/realtime';
+
+/**
+ * Server → client event names. Keeping them centralized means the gateway, the
+ * publisher service and the frontend share a single source of truth instead of
+ * trading raw strings.
+ */
+export const ServerEvent = {
+	/** Presence roster changed (a user came online / went offline). */
+	PRESENCE_UPDATE: 'presence:update',
+	/** Someone started/stopped typing in a room. */
+	TYPING: 'activity:typing',
+	/** Someone is viewing a resource. */
+	VIEWING: 'activity:viewing',
+	/** A user-directed notification. */
+	NOTIFICATION: 'notification',
+	/** Something in a channel changed; payload is app-defined. */
+	CHANNEL_UPDATE: 'channel:update'
+} as const;
+
+/**
+ * Client → server event names.
+ */
+export const ClientEvent = {
+	JOIN_ROOM: 'room:join',
+	LEAVE_ROOM: 'room:leave',
+	TYPING: 'activity:typing',
+	VIEWING: 'activity:viewing'
+} as const;
+
+/** Every socket of a single user joins this room, so we can target the user. */
+export const userRoom = (userId: string) => `user:${userId}`;
+
+/** Firehose room — clients here see every broadcast on the default channel. */
+export const FEED_ROOM = 'feed';
+
+/** Room scoped to one resource; comments, typing and viewing land here. */
+export const channelRoom = (channelId: string) => `channel:${channelId}`;
+
+/** cuid-shaped ids, as generated by Prisma's `@default(cuid())`. */
+const CHANNEL_ROOM_PATTERN = /^channel:[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * Rooms a client may join via the generic `room:join` message.
+ *
+ * This is an allowlist on purpose. Rooms are plain strings, so an open
+ * `socket.join(body.room)` would let any authenticated user join `user:<id>`
+ * and receive another user's private notifications (see
+ * `RealtimeService.notifyUser`). That is reachable only through this door, so
+ * widen the allowlist deliberately — never by passing the client's string
+ * straight to `socket.join`.
+ */
+export const isJoinableRoom = (room: string): boolean =>
+	room === FEED_ROOM || CHANNEL_ROOM_PATTERN.test(room);
+
+/** Redis key holding the set of currently-connected user ids (presence). */
+export const PRESENCE_KEY = 'realtime:presence:online';
+/**
+ * Per-user connection counter. A user may have several tabs/devices; they only
+ * count as "offline" once every socket has disconnected.
+ */
+export const presenceCountKey = (userId: string) =>
+	`realtime:presence:count:${userId}`;

package/templates/nest-api/files/src/realtime/decorators/index.ts

@@ -0,0 +1 @@
+export * from './ws-permissions.decorator';

package/templates/nest-api/files/src/realtime/decorators/ws-permissions.decorator.ts

@@ -0,0 +1,14 @@
+import { SetMetadata } from '@nestjs/common';
+import { Permission } from 'lib/access';
+
+export const WS_PERMISSIONS_KEY = 'ws:permissions';
+
+/**
+ * Require a permission on a `@SubscribeMessage` handler, mirroring what
+ * `@UserHasPermission` does for HTTP routes. Enforced by `WsPermissionsGuard`.
+ *
+ * Websocket handlers never pass through the global HTTP `AuthGuard`, so without
+ * this they are gated on identity alone.
+ */
+export const WsPermissions = (permission: Permission) =>
+	SetMetadata(WS_PERMISSIONS_KEY, permission);

package/templates/nest-api/files/src/realtime/gateways/events.gateway.ts

@@ -0,0 +1,187 @@
+import { UseGuards } from '@nestjs/common';
+import {
+	ConnectedSocket,
+	MessageBody,
+	OnGatewayConnection,
+	OnGatewayDisconnect,
+	OnGatewayInit,
+	SubscribeMessage,
+	WebSocketGateway,
+	WebSocketServer,
+	WsException
+} from '@nestjs/websockets';
+import { Server, Socket } from 'socket.io';
+import { CustomAuthService, LoggerService } from 'common/services';
+import { PresenceService } from '../services/presence.service';
+import { RealtimeService } from '../services/realtime.service';
+import { WsAuthGuard, WsPermissionsGuard } from '../guards';
+import { getSessionUserFromSocket } from '../misc/session-from-socket';
+import {
+	ClientEvent,
+	ServerEvent,
+	isJoinableRoom,
+	userRoom
+} from '../constants';
+
+/**
+ * Central Socket.io gateway.
+ *
+ * Responsibilities (PRD §2.2 / §3.1):
+ *  - Authenticate every socket against the better-auth session on connect.
+ *  - Maintain online-user presence across replicas (via {@link PresenceService}).
+ *  - Let clients subscribe to live market rooms for price tickers.
+ *  - Relay lightweight activity signals (typing / viewing) within a room.
+ *
+ * The `cors` / `path` for the server are configured on the Redis adapter
+ * (`RedisIoAdapter`), so the decorator stays option-free.
+ */
+@WebSocketGateway()
+// Applied at class level so a newly added handler is guarded by default rather
+// than by remembering to decorate it. `handleConnection` is not a message
+// handler and is unaffected — it does its own session check.
+/**
+ * Guards are applied at the **class** level, so every `@SubscribeMessage`
+ * handler is covered by default — Nest concatenates class- then method-level
+ * guard metadata. `WsAuthGuard` establishes identity; `WsPermissionsGuard`
+ * enforces `@WsPermissions({ <resource>: ['<action>'] })` from
+ * `realtime/decorators`, which is the only authorization path websockets get
+ * (they never traverse the HTTP `AuthGuard`).
+ */
+@UseGuards(WsAuthGuard, WsPermissionsGuard)
+export class EventsGateway
+	implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect
+{
+	@WebSocketServer() private server!: Server;
+
+	constructor(
+		private readonly auth: CustomAuthService,
+		private readonly presence: PresenceService,
+		private readonly realtime: RealtimeService,
+		private readonly logger: LoggerService
+	) {}
+
+	afterInit(server: Server) {
+		// Hand the live server to the publisher so other modules can emit.
+		this.realtime.bindServer(server);
+		this.logger.debug('Realtime gateway initialized.');
+	}
+
+	async handleConnection(socket: Socket) {
+		const user = await getSessionUserFromSocket(socket, this.auth);
+		if (!user) {
+			// No valid session — refuse the connection.
+			socket.emit('error', { message: 'Unauthorized' });
+			socket.disconnect(true);
+			return;
+		}
+
+		socket.data.user = user;
+		// Every socket of a user joins their personal room for direct messaging.
+		await socket.join(userRoom(user.id));
+
+		const cameOnline = await this.presence.connect(user.id);
+		if (cameOnline) {
+			this.server.emit(ServerEvent.PRESENCE_UPDATE, {
+				userId: user.id,
+				status: 'online'
+			});
+		}
+
+		this.logger.debug(
+			{ userId: user.id, socketId: socket.id },
+			'Socket connected.'
+		);
+	}
+
+	async handleDisconnect(socket: Socket) {
+		const user = socket.data.user;
+		if (!user) return;
+
+		const wentOffline = await this.presence.disconnect(user.id);
+		if (wentOffline) {
+			this.server.emit(ServerEvent.PRESENCE_UPDATE, {
+				userId: user.id,
+				status: 'offline'
+			});
+		}
+
+		this.logger.debug(
+			{ userId: user.id, socketId: socket.id },
+			'Socket disconnected.'
+		);
+	}
+
+	// --- Presence ----------------------------------------------------------
+
+	@SubscribeMessage('presence:list')
+	async listOnline() {
+		const userIds = await this.presence.online();
+		return { event: ServerEvent.PRESENCE_UPDATE, data: { online: userIds } };
+	}
+
+	// --- Rooms --------------------------------------------------------------
+
+	@SubscribeMessage(ClientEvent.JOIN_ROOM)
+	async joinRoom(
+		@ConnectedSocket() socket: Socket,
+		@MessageBody() body: { room: string }
+	) {
+		// Only rooms on the allowlist are joinable this way. `user:<id>` is not —
+		// it would hand the caller another user's private notifications.
+		if (!isJoinableRoom(body.room)) {
+			throw new WsException('Forbidden');
+		}
+		await socket.join(body.room);
+		return { ok: true, room: body.room };
+	}
+
+	@SubscribeMessage(ClientEvent.LEAVE_ROOM)
+	async leaveRoom(
+		@ConnectedSocket() socket: Socket,
+		@MessageBody() body: { room: string }
+	) {
+		await socket.leave(body.room);
+		return { ok: true };
+	}
+
+	// --- Activity signals (who is typing / viewing) ------------------------
+
+	@SubscribeMessage(ClientEvent.TYPING)
+	typing(
+		@ConnectedSocket() socket: Socket,
+		@MessageBody() body: { room: string; isTyping: boolean }
+	) {
+		this.assertInRoom(socket, body.room);
+		// Relay to everyone else in the room — never echo back to the sender.
+		socket.to(body.room).emit(ServerEvent.TYPING, {
+			room: body.room,
+			userId: socket.data.user!.id,
+			name: socket.data.user!.name,
+			isTyping: body.isTyping
+		});
+	}
+
+	@SubscribeMessage(ClientEvent.VIEWING)
+	viewing(
+		@ConnectedSocket() socket: Socket,
+		@MessageBody() body: { room: string; viewing: boolean }
+	) {
+		this.assertInRoom(socket, body.room);
+		socket.to(body.room).emit(ServerEvent.VIEWING, {
+			room: body.room,
+			userId: socket.data.user!.id,
+			viewing: body.viewing
+		});
+	}
+
+	/**
+	 * A client may only signal into a room it actually occupies. Otherwise it
+	 * could emit forged typing/viewing events into any room by name, including
+	 * another user's `user:<id>` room.
+	 */
+	private assertInRoom(socket: Socket, room: string) {
+		if (!socket.rooms.has(room)) {
+			throw new WsException('Not in room');
+		}
+	}
+}

package/templates/nest-api/files/src/realtime/guards/index.ts

@@ -0,0 +1,2 @@
+export * from './ws-auth.guard';
+export * from './ws-permissions.guard';

package/templates/nest-api/files/src/realtime/guards/ws-auth.guard.ts

@@ -0,0 +1,20 @@
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { WsException } from '@nestjs/websockets';
+import { Socket } from 'socket.io';
+
+/**
+ * Guards `@SubscribeMessage` handlers: the socket must already carry an
+ * authenticated user (attached at connection time in `EventsGateway`). This is
+ * defense-in-depth — unauthenticated sockets are disconnected on connect, but
+ * message handlers should never trust that implicitly.
+ */
+@Injectable()
+export class WsAuthGuard implements CanActivate {
+	canActivate(context: ExecutionContext): boolean {
+		const socket = context.switchToWs().getClient<Socket>();
+		if (!socket.data.user) {
+			throw new WsException('Unauthorized');
+		}
+		return true;
+	}
+}

package/templates/nest-api/files/src/realtime/guards/ws-permissions.guard.ts

@@ -0,0 +1,35 @@
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { WsException } from '@nestjs/websockets';
+import { Socket } from 'socket.io';
+import { Permission, hasPermission } from 'lib/access';
+import { WS_PERMISSIONS_KEY } from '../decorators/ws-permissions.decorator';
+
+/**
+ * Enforces `@WsPermissions(...)` on socket message handlers.
+ *
+ * Runs after `WsAuthGuard`, which establishes *who* the socket is; this decides
+ * *what* they may do. A handler with no `@WsPermissions` metadata is allowed —
+ * identity alone is the requirement there.
+ */
+@Injectable()
+export class WsPermissionsGuard implements CanActivate {
+	constructor(private readonly reflector: Reflector) {}
+
+	canActivate(context: ExecutionContext): boolean {
+		const required = this.reflector.getAllAndOverride<Permission | undefined>(
+			WS_PERMISSIONS_KEY,
+			[context.getHandler(), context.getClass()]
+		);
+		if (!required) return true;
+
+		const socket = context.switchToWs().getClient<Socket>();
+		const user = socket.data.user;
+		if (!user) throw new WsException('Unauthorized');
+
+		if (!hasPermission(user.role, required)) {
+			throw new WsException('Forbidden');
+		}
+		return true;
+	}
+}

package/templates/nest-api/files/src/realtime/misc/session-from-socket.ts

@@ -0,0 +1,54 @@
+import { Socket } from 'socket.io';
+import { CustomAuthService } from 'common/services';
+
+/** The authenticated identity we stash on `socket.data` after the handshake. */
+export interface SocketUser {
+	id: string;
+	name: string;
+	email: string;
+	role?: string | null;
+}
+
+declare module 'socket.io' {
+	interface SocketData {
+		user?: SocketUser;
+	}
+}
+
+/**
+ * Resolve a better-auth session from a socket handshake.
+ *
+ * The browser sends the same session cookie it uses for REST, so we forward the
+ * handshake headers to better-auth's `getSession`. Returns `null` when there is
+ * no valid session — callers decide whether to disconnect.
+ */
+export const getSessionUserFromSocket = async (
+	socket: Socket,
+	auth: CustomAuthService
+): Promise<SocketUser | null> => {
+	// socket.io exposes handshake headers as a plain object; better-auth wants a
+	// Fetch `Headers`. The cookie is the only header it needs.
+	const headers = new Headers();
+	const cookie = socket.handshake.headers.cookie;
+	if (cookie) headers.set('cookie', cookie);
+
+	// Also accept a bearer token (handy for native/PWA clients that can't rely on
+	// cookies), mirroring better-auth's bearer support.
+	const auth_header =
+		socket.handshake.auth?.token ?? socket.handshake.headers.authorization;
+	if (auth_header) {
+		headers.set(
+			'authorization',
+			auth_header.startsWith('Bearer ') ? auth_header : `Bearer ${auth_header}`
+		);
+	}
+
+	try {
+		const session = await auth.api.getSession({ headers });
+		if (!session?.user) return null;
+		const { id, name, email, role } = session.user;
+		return { id, name, email, role };
+	} catch {
+		return null;
+	}
+};

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

@@ -0,0 +1,26 @@
+import { Global, Module } from '@nestjs/common';
+import { EventsGateway } from './gateways/events.gateway';
+import { PresenceService } from './services/presence.service';
+import { RealtimeService } from './services/realtime.service';
+import { WsAuthGuard, WsPermissionsGuard } from './guards';
+
+/**
+ * Realtime (Socket.io) layer. Marked `@Global` so cross-cutting publishers —
+ * queue processors, schedulers and REST services — can
+ * inject {@link RealtimeService} without importing this module everywhere.
+ *
+ * The Redis adapter for horizontal scaling is wired separately in `main.ts`
+ * (`RedisIoAdapter`) because it must be attached to the app before `listen()`.
+ */
+@Global()
+@Module({
+	providers: [
+		EventsGateway,
+		PresenceService,
+		RealtimeService,
+		WsAuthGuard,
+		WsPermissionsGuard
+	],
+	exports: [RealtimeService, PresenceService]
+})
+export class RealtimeModule {}

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

@@ -0,0 +1,56 @@
+import { Injectable } from '@nestjs/common';
+import { CacheService } from 'common/services';
+import { PRESENCE_KEY, presenceCountKey } from '../constants';
+
+/**
+ * Tracks which users are online across all backend replicas.
+ *
+ * A user can hold several sockets at once (multiple tabs / devices), so we keep
+ * a per-user connection counter in Redis and only flip presence when it crosses
+ * the 0↔1 boundary. State lives in Redis (not memory) so it is correct behind
+ * the horizontally-scaled Socket.io adapter.
+ */
+@Injectable()
+export class PresenceService {
+	constructor(private readonly cache: CacheService) {}
+
+	private get redis() {
+		return this.cache.db;
+	}
+
+	/**
+	 * Record a new socket for a user. Returns `true` if this was their first
+	 * connection (i.e. they just came online), so the caller can broadcast it.
+	 */
+	async connect(userId: string): Promise<boolean> {
+		const count = await this.redis.incr(presenceCountKey(userId));
+		if (count === 1) {
+			await this.redis.sadd(PRESENCE_KEY, userId);
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Record a socket closing for a user. Returns `true` if that was their last
+	 * connection (i.e. they just went offline).
+	 */
+	async disconnect(userId: string): Promise<boolean> {
+		const count = await this.redis.decr(presenceCountKey(userId));
+		if (count <= 0) {
+			await this.redis.del(presenceCountKey(userId));
+			await this.redis.srem(PRESENCE_KEY, userId);
+			return true;
+		}
+		return false;
+	}
+
+	/** Ids of every currently-online user. */
+	async online(): Promise<string[]> {
+		return this.redis.smembers(PRESENCE_KEY);
+	}
+
+	async isOnline(userId: string): Promise<boolean> {
+		return (await this.redis.sismember(PRESENCE_KEY, userId)) === 1;
+	}
+}

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

@@ -0,0 +1,72 @@
+import { Injectable } from '@nestjs/common';
+import { Server } from 'socket.io';
+import { LoggerService } from 'common/services';
+import { FEED_ROOM, ServerEvent, channelRoom, userRoom } from '../constants';
+
+/**
+ * The publish side of the realtime layer.
+ *
+ * Any module (queue processors, schedulers, REST services) can inject this to
+ * push events to connected clients without depending on the gateway — which
+ * would create a cycle and couple business logic to the transport. The gateway
+ * hands us the live Socket.io `Server` in its `afterInit`; before that (or in
+ * tests with no WS server) every emit is a safe no-op.
+ */
+@Injectable()
+export class RealtimeService {
+	private server?: Server;
+
+	constructor(private readonly logger: LoggerService) {}
+
+	/** Called once by the gateway when the Socket.io server is ready. */
+	bindServer(server: Server) {
+		this.server = server;
+	}
+
+	get isReady(): boolean {
+		return !!this.server;
+	}
+
+	/** Deliver a notification to every socket belonging to one user. */
+	notifyUser(userId: string, notification: unknown) {
+		this.emitToRoom(userRoom(userId), ServerEvent.NOTIFICATION, notification);
+	}
+
+	/** Announce something to everyone watching the global feed. */
+	emitToFeed(event: string, payload: unknown) {
+		this.emitToRoom(FEED_ROOM, event, payload);
+	}
+
+	/** Push an update to everyone in one channel's room. */
+	emitToChannel(channelId: string, payload: unknown) {
+		this.emitToRoom(
+			channelRoom(channelId),
+			ServerEvent.CHANNEL_UPDATE,
+			payload
+		);
+	}
+
+	/** Low-level: emit to a specific room. */
+	emitToRoom(room: string, event: string, payload: unknown) {
+		if (!this.server) {
+			this.logger.debug(
+				{ room, event },
+				'Realtime server not ready; dropping emit.'
+			);
+			return;
+		}
+		this.server.to(room).emit(event, payload);
+	}
+
+	/** Low-level: emit to every connected client. */
+	broadcast(event: string, payload: unknown) {
+		if (!this.server) {
+			this.logger.debug(
+				{ event },
+				'Realtime server not ready; dropping broadcast.'
+			);
+			return;
+		}
+		this.server.emit(event, payload);
+	}
+}

package/templates/nest-api/files/src/users/__tests__/current-user.controller.spec.ts

@@ -0,0 +1,77 @@
+import { TestBed, type Mocked } from '@suites/unit';
+import { Entity } from '@test/factory/entity';
+import { CurrentUserController } from '../controllers';
+import { CurrentUserService } from '../services';
+import { CurrentUserEntity, toCurrentUser } from '../entity';
+
+describe('CurrentUserController', () => {
+	let controller: CurrentUserController;
+	let service: Mocked<CurrentUserService>;
+
+	beforeAll(async () => {
+		const { unit, unitRef } = await TestBed.solitary(
+			CurrentUserController
+		).compile();
+		controller = unit;
+		service = unitRef.get(CurrentUserService);
+	});
+
+	it('should be defined', () => {
+		expect(controller).toBeDefined();
+	});
+
+	describe('completeOnboarding', () => {
+		it('delegates to CurrentUserService with the session user', async () => {
+			const session = Entity.userSession.build();
+			const updated = toCurrentUser(session.user);
+			service.completeOnboarding.mockResolvedValue(updated);
+
+			const result = await controller.completeOnboarding(session);
+
+			expect(service.completeOnboarding).toHaveBeenCalledWith(session.user);
+			expect(result).toBe(updated);
+		});
+	});
+
+	describe('getCurrentUser', () => {
+		it('should return a CurrentUserEntity from session user', () => {
+			const session = Entity.userSession.build();
+			const result = controller.getCurrentUser(session);
+
+			expect(CurrentUserEntity.safeParse(result).success).toBe(true);
+			expect(result.id).toBe(session.user.id);
+			expect(result.name).toBe(session.user.name);
+			expect(result.email).toBe(session.user.email);
+		});
+	});
+
+	// @feature:start media
+	describe('updateAvatar', () => {
+		const file = {
+			originalname: 'photo.jpg',
+			buffer: Buffer.from('photo-data'),
+			mimetype: 'image/jpeg'
+		} as Express.Multer.File;
+
+		it('should delegate to CurrentUserService.updateAvatar', async () => {
+			const session = Entity.userSession.build();
+			const fileEntity = Entity.file.build();
+			service.updateAvatar.mockResolvedValue(fileEntity);
+
+			const result = await controller.updateAvatar(session, file);
+
+			expect(service.updateAvatar).toHaveBeenCalledWith(session.user, file);
+			expect(result).toBe(fileEntity);
+		});
+
+		it('should pass the session user and uploaded file to the service', async () => {
+			const session = Entity.userSession.build();
+			const fileEntity = Entity.file.build();
+			service.updateAvatar.mockResolvedValue(fileEntity);
+			await controller.updateAvatar(session, file);
+
+			expect(service.updateAvatar).toHaveBeenCalledWith(session.user, file);
+		});
+	});
+	// @feature:end
+});