@hed-hog/core 0.0.387 → 0.0.393

package/src/realtime/realtime.gateway.ts

@@ -0,0 +1,138 @@
+import { Logger } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import {
+  ConnectedSocket,
+  MessageBody,
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  OnGatewayInit,
+  SubscribeMessage,
+  WebSocketGateway,
+  WebSocketServer,
+} from '@nestjs/websockets';
+import type { Server, Socket } from 'socket.io';
+import { TokenService } from '../token/token.service';
+import { RealtimeService } from './realtime.service';
+
+/** Events other modules can listen to via `@OnEvent(...)`. */
+export const REALTIME_EVENTS = {
+  userConnected: 'realtime.user.connected',
+  userDisconnected: 'realtime.user.disconnected',
+} as const;
+
+function corsOrigin(): string[] | boolean {
+  const raw = String(process.env.CORS_ALLOWED_ORIGINS || '').trim();
+  if (!raw) return true; // permissive handshake — the JWT is the real gate
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Single Socket.IO gateway (`/realtime`) on the same HTTP server/port. It only
+ * handles transport + auth + room membership; the reusable emit API lives in
+ * {@link RealtimeService}. Auth reuses {@link TokenService.verify} (same JWT as
+ * the HTTP `AuthGuard`); connection lifecycle is broadcast via EventEmitter2 so
+ * features (e.g. presence) react without this layer knowing about them.
+ */
+@WebSocketGateway({
+  namespace: '/realtime',
+  cors: { origin: corsOrigin(), credentials: true },
+})
+export class RealtimeGateway
+  implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect
+{
+  private readonly logger = new Logger(RealtimeGateway.name);
+
+  @WebSocketServer()
+  server!: Server;
+
+  constructor(
+    private readonly realtime: RealtimeService,
+    private readonly token: TokenService,
+    private readonly events: EventEmitter2,
+  ) {}
+
+  afterInit(server: Server) {
+    this.realtime.setServer(server);
+    this.logger.log('Realtime gateway initialized on /realtime');
+  }
+
+  private extractToken(socket: Socket): string | undefined {
+    const authToken = (socket.handshake.auth as { token?: string } | undefined)?.token;
+    if (authToken) return authToken;
+    const header = socket.handshake.headers.authorization;
+    const [type, value] = String(header ?? '').split(' ');
+    return type === 'Bearer' ? value : undefined;
+  }
+
+  async handleConnection(socket: Socket) {
+    const token = this.extractToken(socket);
+    if (!token) {
+      socket.disconnect(true);
+      return;
+    }
+    try {
+      const payload = await this.token.verify('en', token);
+      const userId = Number(payload?.sub);
+      if (!Number.isInteger(userId) || userId <= 0) {
+        socket.disconnect(true);
+        return;
+      }
+      socket.data.userId = userId;
+      socket.join(`user:${userId}`);
+      const localCount = this.realtime.trackConnect(userId);
+      this.events.emit(REALTIME_EVENTS.userConnected, {
+        userId,
+        firstConnection: localCount === 1,
+      });
+    } catch {
+      socket.disconnect(true);
+    }
+  }
+
+  handleDisconnect(socket: Socket) {
+    const userId = socket.data?.userId as number | undefined;
+    if (!userId) return;
+    const remaining = this.realtime.trackDisconnect(userId);
+    this.events.emit(REALTIME_EVENTS.userDisconnected, {
+      userId,
+      remainingLocalSockets: remaining,
+    });
+  }
+
+  /** Joins the socket to the given channels (rooms `channel:{name}`). */
+  @SubscribeMessage('subscribe')
+  onSubscribe(
+    @ConnectedSocket() socket: Socket,
+    @MessageBody() body: { channels?: string[] },
+  ) {
+    const channels = Array.isArray(body?.channels) ? body.channels : [];
+    for (const ch of channels) {
+      if (this.isAllowed(socket, String(ch))) socket.join(`channel:${ch}`);
+    }
+    return { ok: true, subscribed: channels };
+  }
+
+  @SubscribeMessage('unsubscribe')
+  onUnsubscribe(
+    @ConnectedSocket() socket: Socket,
+    @MessageBody() body: { channels?: string[] },
+  ) {
+    const channels = Array.isArray(body?.channels) ? body.channels : [];
+    for (const ch of channels) socket.leave(`channel:${ch}`);
+    return { ok: true };
+  }
+
+  /**
+   * Channel-subscription authorization. `presence:{id}` is readable by any
+   * authenticated user (presence is coarse/non-sensitive). Modules adding
+   * sensitive channels should extend this with per-channel checks.
+   */
+  private isAllowed(_socket: Socket, channel: string): boolean {
+    if (channel.startsWith('presence:')) return true;
+    // Default-allow other channels for now; tighten per feature as needed.
+    return true;
+  }
+}

package/src/realtime/realtime.module.ts

@@ -0,0 +1,16 @@
+import { forwardRef, Module } from '@nestjs/common';
+import { TokenModule } from '../token/token.module';
+import { RealtimeGateway } from './realtime.gateway';
+import { RealtimeService } from './realtime.service';
+
+/**
+ * Generic real-time (WebSocket) layer for the whole app. Any module can inject
+ * {@link RealtimeService} to push events to users/channels, fanned out across
+ * instances via Redis. EventEmitter2 (global) delivers connection lifecycle.
+ */
+@Module({
+  imports: [forwardRef(() => TokenModule)],
+  providers: [RealtimeGateway, RealtimeService],
+  exports: [RealtimeService],
+})
+export class RealtimeModule {}

package/src/realtime/realtime.service.spec.ts

@@ -0,0 +1,50 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { RealtimeService } from './realtime.service';
+
+const makeServer = () => {
+  const emit = jest.fn();
+  const to = jest.fn(() => ({ emit }));
+  return { to, emit: emit as any, rootEmit: jest.fn(), server: { to, emit: jest.fn() } };
+};
+
+describe('RealtimeService', () => {
+  let service: RealtimeService;
+  let server: ReturnType<typeof makeServer>;
+
+  beforeEach(() => {
+    service = new RealtimeService();
+    server = makeServer();
+    service.setServer(server.server as any);
+  });
+
+  it('emits to the user room', () => {
+    service.emitToUser(7, 'presence:update', { online: true });
+    expect(server.to).toHaveBeenCalledWith('user:7');
+  });
+
+  it('emits to the channel room', () => {
+    service.emitToChannel('presence:7', 'presence:update', { online: true });
+    expect(server.to).toHaveBeenCalledWith('channel:presence:7');
+  });
+
+  it('broadcasts to everyone', () => {
+    service.broadcast('ping', {});
+    expect((server.server as any).emit).toHaveBeenCalledWith('ping', {});
+  });
+
+  it('does not throw when no server is bound yet', () => {
+    const bare = new RealtimeService();
+    expect(() => bare.emitToUser(1, 'x', {})).not.toThrow();
+  });
+
+  it('tracks local connections per user', () => {
+    expect(service.trackConnect(1)).toBe(1);
+    expect(service.trackConnect(1)).toBe(2);
+    expect(service.isLocallyConnected(1)).toBe(true);
+    expect(service.getLocallyConnectedUserIds()).toEqual([1]);
+    expect(service.trackDisconnect(1)).toBe(1);
+    expect(service.trackDisconnect(1)).toBe(0);
+    expect(service.isLocallyConnected(1)).toBe(false);
+    expect(service.getLocallyConnectedUserIds()).toEqual([]);
+  });
+});

package/src/realtime/realtime.service.ts

@@ -0,0 +1,187 @@
+import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { createClient, type RedisClientType } from 'redis';
+import type { Server } from 'socket.io';
+
+type EmitTarget =
+  | { type: 'user'; target: string }
+  | { type: 'channel'; target: string }
+  | { type: 'broadcast' };
+
+interface RealtimeMessage {
+  target: EmitTarget;
+  event: string;
+  payload: unknown;
+  originInstanceId: string;
+}
+
+/**
+ * Generic real-time messaging layer usable by ANY module. Wraps the Socket.IO
+ * server (bound by {@link RealtimeGateway}) and fans emits out across API
+ * instances via Redis pub/sub — mirroring the settings-sync pattern — so a
+ * message emitted on one pod reaches clients connected to another. Without
+ * `REDIS_URL` it degrades to single-instance (local emit still works).
+ *
+ * Rooms: `user:{id}` (auto-joined on connect) and `channel:{name}` (joined via
+ * the gateway's `subscribe` message). Other modules just inject this service and
+ * call {@link emitToUser} / {@link emitToChannel} / {@link broadcast}.
+ */
+@Injectable()
+export class RealtimeService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(RealtimeService.name);
+  private readonly instanceId = randomUUID();
+  private readonly redisUrl = String(process.env.REDIS_URL || '').trim();
+  private readonly channel = 'core:realtime:emit';
+
+  private server: Server | null = null;
+  private redisPublisher: RedisClientType | null = null;
+  private redisSubscriber: RedisClientType | null = null;
+
+  /** Local (this-instance) socket count per user id, for presence/liveness. */
+  private readonly localConnections = new Map<number, number>();
+
+  async onModuleInit() {
+    await this.initRedis();
+  }
+
+  async onModuleDestroy() {
+    await Promise.allSettled([
+      this.safeClose(this.redisSubscriber),
+      this.safeClose(this.redisPublisher),
+    ]);
+  }
+
+  /** Called by the gateway once Socket.IO is initialized. */
+  setServer(server: Server) {
+    this.server = server;
+  }
+
+  private userRoom(userId: string | number) {
+    return `user:${userId}`;
+  }
+  private channelRoom(name: string) {
+    return `channel:${name}`;
+  }
+
+  /** Emits an event to every socket of a given user (all their tabs/devices). */
+  emitToUser(userId: string | number, event: string, payload: unknown) {
+    this.dispatch({ target: { type: 'user', target: String(userId) }, event, payload });
+  }
+
+  /** Emits an event to everyone subscribed to a named channel. */
+  emitToChannel(channel: string, event: string, payload: unknown) {
+    this.dispatch({ target: { type: 'channel', target: channel }, event, payload });
+  }
+
+  /** Emits an event to every connected client. */
+  broadcast(event: string, payload: unknown) {
+    this.dispatch({ target: { type: 'broadcast' }, event, payload });
+  }
+
+  private dispatch(msg: Omit<RealtimeMessage, 'originInstanceId'>) {
+    this.emitLocal(msg);
+    this.publish(msg);
+  }
+
+  private emitLocal(msg: Omit<RealtimeMessage, 'originInstanceId'>) {
+    if (!this.server) return;
+    const { target, event, payload } = msg;
+    if (target.type === 'user') {
+      this.server.to(this.userRoom(target.target)).emit(event, payload);
+    } else if (target.type === 'channel') {
+      this.server.to(this.channelRoom(target.target)).emit(event, payload);
+    } else {
+      this.server.emit(event, payload);
+    }
+  }
+
+  private publish(msg: Omit<RealtimeMessage, 'originInstanceId'>) {
+    if (!this.redisPublisher) return;
+    const full: RealtimeMessage = { ...msg, originInstanceId: this.instanceId };
+    this.redisPublisher
+      .publish(this.channel, JSON.stringify(full))
+      .catch((error) =>
+        this.logger.warn(
+          `Realtime publish failed: ${error instanceof Error ? error.message : 'unknown'}`,
+        ),
+      );
+  }
+
+  private handleRedisMessage(raw: string) {
+    let msg: RealtimeMessage;
+    try {
+      msg = JSON.parse(raw) as RealtimeMessage;
+    } catch {
+      return;
+    }
+    // Skip our own messages — they were already emitted locally.
+    if (!msg || msg.originInstanceId === this.instanceId) return;
+    this.emitLocal(msg);
+  }
+
+  // ── Connection tracking (called by the gateway) ────────────────────────────
+
+  /** Records a new local socket for a user; returns the new local count. */
+  trackConnect(userId: number): number {
+    const next = (this.localConnections.get(userId) ?? 0) + 1;
+    this.localConnections.set(userId, next);
+    return next;
+  }
+
+  /** Drops a local socket for a user; returns the remaining local count. */
+  trackDisconnect(userId: number): number {
+    const next = Math.max(0, (this.localConnections.get(userId) ?? 0) - 1);
+    if (next === 0) this.localConnections.delete(userId);
+    else this.localConnections.set(userId, next);
+    return next;
+  }
+
+  /** Whether the user has at least one socket on THIS instance. */
+  isLocallyConnected(userId: number): boolean {
+    return (this.localConnections.get(userId) ?? 0) > 0;
+  }
+
+  /** All user ids with at least one socket on this instance. */
+  getLocallyConnectedUserIds(): number[] {
+    return [...this.localConnections.keys()];
+  }
+
+  // ── Redis wiring (mirrors setting.service) ─────────────────────────────────
+
+  private async initRedis() {
+    if (!this.redisUrl) {
+      this.logger.log('Realtime Redis fan-out disabled (REDIS_URL not set); single-instance only.');
+      return;
+    }
+    try {
+      const opts = {
+        url: this.redisUrl,
+        socket: { reconnectStrategy: (retries: number) => Math.min(retries * 250, 5000) },
+      };
+      this.redisPublisher = createClient(opts);
+      this.redisSubscriber = createClient(opts);
+      this.redisPublisher.on('error', (e) => this.logger.warn(`Realtime Redis publisher error: ${e?.message ?? e}`));
+      this.redisSubscriber.on('error', (e) => this.logger.warn(`Realtime Redis subscriber error: ${e?.message ?? e}`));
+      await this.redisPublisher.connect();
+      await this.redisSubscriber.connect();
+      await this.redisSubscriber.subscribe(this.channel, (msg) => this.handleRedisMessage(msg));
+      this.logger.log(`Realtime Redis fan-out enabled on channel ${this.channel}`);
+    } catch (error) {
+      this.logger.warn(
+        `Failed to init realtime Redis fan-out: ${error instanceof Error ? error.message : 'unknown'}`,
+      );
+      await Promise.allSettled([this.safeClose(this.redisSubscriber), this.safeClose(this.redisPublisher)]);
+      this.redisPublisher = null;
+      this.redisSubscriber = null;
+    }
+  }
+
+  private async safeClose(client: RedisClientType | null) {
+    if (!client) return;
+    try {
+      if (client.isOpen) await client.quit();
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/src/redis/redis-pubsub.ts

@@ -0,0 +1,190 @@
+import * as Sentry from '@sentry/nestjs';
+import { Logger } from '@nestjs/common';
+import { createClient, type RedisClientType } from 'redis';
+
+export type RedisPubSub = {
+  /** `false` means no Redis: publishing is a no-op and this process runs single-instance. */
+  readonly enabled: boolean;
+  publish(payload: unknown): Promise<void>;
+  close(): Promise<void>;
+};
+
+export type CreateRedisPubSubOptions = {
+  channel: string;
+  logger: Logger;
+  /** Used in log lines, e.g. `ai instruction` -> "Redis ai instruction sync enabled...". */
+  label: string;
+  onMessage: (raw: string) => void | Promise<void>;
+  /** Defaults to `REDIS_URL`, read at call time so tests can set it before init. */
+  url?: string;
+  errorLogCooldownMs?: number;
+};
+
+const DEFAULT_ERROR_LOG_COOLDOWN_MS = 30000;
+
+/**
+ * A connection failure must never take the client's data path down with it, so
+ * every error path here degrades to `INERT` and lets the caller keep serving
+ * from its local cache.
+ */
+const INERT: RedisPubSub = {
+  enabled: false,
+  async publish() {
+    // no-op
+  },
+  async close() {
+    // no-op
+  },
+};
+
+/**
+ * `createClient` rejects with an `AggregateError` whose own `message` is empty,
+ * so logging it directly yields "Redis error: " with nothing after it.
+ */
+function extractRedisErrorMessage(error: unknown): string {
+  if (error instanceof AggregateError && error.errors?.length) {
+    return error.errors
+      .map((e) => (e instanceof Error ? e.message || e.toString() : String(e)))
+      .join('; ');
+  }
+  if (error instanceof Error) {
+    return error.message || error.toString();
+  }
+  return String(error);
+}
+
+async function safeClose(client: RedisClientType | null) {
+  if (!client || !client.isOpen) {
+    return;
+  }
+
+  try {
+    await client.quit();
+  } catch {
+    try {
+      client.disconnect();
+    } catch {
+      // ignore shutdown errors
+    }
+  }
+}
+
+/**
+ * Publisher/subscriber pair on a single channel, mirroring the settings-sync
+ * pattern. Never throws: without a URL — or if the connection fails — it returns
+ * an inert handle and logs once.
+ *
+ * A dedicated subscriber connection is required: node-redis v4 puts a client in
+ * subscriber mode, where it can no longer issue regular commands.
+ */
+export async function createRedisPubSub(
+  options: CreateRedisPubSubOptions,
+): Promise<RedisPubSub> {
+  const { channel, logger, label, onMessage } = options;
+  const url = String(options.url ?? process.env.REDIS_URL ?? '').trim();
+
+  if (!url) {
+    logger.log(`Redis ${label} sync disabled because REDIS_URL is not configured.`);
+    return INERT;
+  }
+
+  const cooldownMs = Math.max(
+    1000,
+    Number(options.errorLogCooldownMs || DEFAULT_ERROR_LOG_COOLDOWN_MS),
+  );
+  // A Redis outage fires `error` on every reconnect attempt; unthrottled that
+  // buries every other log line in the pod.
+  const lastErrorLogAt: Record<'subscriber' | 'publisher', number> = {
+    subscriber: 0,
+    publisher: 0,
+  };
+
+  const logClientError = (kind: 'subscriber' | 'publisher', error: unknown) => {
+    const now = Date.now();
+    if (now - lastErrorLogAt[kind] < cooldownMs) {
+      return;
+    }
+    lastErrorLogAt[kind] = now;
+    logger.warn(`Redis ${label} ${kind} error: ${extractRedisErrorMessage(error)}`);
+  };
+
+  let subscriber: RedisClientType | null = null;
+  let publisher: RedisClientType | null = null;
+
+  try {
+    const clientOptions = {
+      url,
+      socket: {
+        reconnectStrategy: (retries: number) => Math.min(retries * 250, 5000),
+      },
+    };
+
+    subscriber = createClient(clientOptions) as RedisClientType;
+    publisher = createClient(clientOptions) as RedisClientType;
+
+    // Registered before `connect` so a failure during the handshake is handled
+    // rather than thrown as an unhandled 'error' event.
+    subscriber.on('error', (error) => logClientError('subscriber', error));
+    publisher.on('error', (error) => logClientError('publisher', error));
+
+    await subscriber.connect();
+    await publisher.connect();
+    await subscriber.subscribe(channel, async (message) => {
+      try {
+        await onMessage(message);
+      } catch (error) {
+        // A instrumentação automática do Sentry para node-redis cobre publish()
+        // mas NÃO subscribe()/entrega de mensagem (limitação da instrumentação
+        // vendorizada, não deste projeto) — sem esta captura explícita, uma
+        // falha aqui era só um logger.warn, invisível fora do log do pod.
+        Sentry.withScope((scope) => {
+          scope.setTags({ 'redis.channel': channel, 'redis.label': label });
+          Sentry.captureException(error, {
+            mechanism: { handled: true, type: 'hedhog.redis_pubsub' },
+          });
+        });
+        logger.warn(
+          `Failed to handle Redis ${label} message: ${extractRedisErrorMessage(error)}`,
+        );
+      }
+    });
+
+    logger.log(`Redis ${label} sync enabled on channel ${channel}`);
+  } catch (error) {
+    logger.warn(
+      `Failed to initialize Redis ${label} sync: ${extractRedisErrorMessage(error)}`,
+    );
+
+    await Promise.allSettled([safeClose(subscriber), safeClose(publisher)]);
+
+    return INERT;
+  }
+
+  const activePublisher = publisher;
+  const activeSubscriber = subscriber;
+  let closed = false;
+
+  return {
+    enabled: true,
+    async publish(payload: unknown) {
+      if (closed || !activePublisher.isOpen) {
+        return;
+      }
+
+      try {
+        await activePublisher.publish(channel, JSON.stringify(payload));
+      } catch (error) {
+        logger.warn(
+          `Failed to publish Redis ${label} message: ${extractRedisErrorMessage(error)}`,
+        );
+      }
+    },
+    async close() {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      await Promise.allSettled([safeClose(activeSubscriber), safeClose(activePublisher)]);
+    },
+  };
+}

package/src/role/guards/role.guard.spec.ts

@@ -154,4 +154,79 @@ describe('RoleGuard', () => {
       true,
     );
   });
+
+  describe('simulação de acesso — denylist de rotas', () => {
+    const impersonatedRequest = {
+      headers: { authorization: 'Bearer tok' },
+      auth: { sub: 42, sessionId: 555, act: 7, imp: true },
+    };
+
+    it('bloqueia GET /auth/desktop-token, que é @NoRole()', async () => {
+      // Sem esta guarda o operador cunharia para o ALVO uma sessão completa,
+      // renovável e de 30 dias — furando o teto da simulação.
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { withNoRole: true });
+      setPath(deps.reflector, 'auth', 'desktop-token', RequestMethod.GET);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it('bloqueia POST /auth/logout, que é @Public()', async () => {
+      // O cookie `rt` da mesma origem é o do OPERADOR: sair por aqui revogaria
+      // a sessão real dele.
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { public: true });
+      setPath(deps.reflector, 'auth', 'logout', RequestMethod.POST);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it('bloqueia a família /auth/pairing por prefixo', async () => {
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { public: true });
+      setPath(deps.reflector, 'auth', 'pairing/redeem', RequestMethod.POST);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it('bloqueia simulação aninhada em POST /impersonation/start', async () => {
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { withRole: true });
+      setPath(deps.reflector, 'impersonation', 'start', RequestMethod.POST);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it('libera POST /impersonation/stop — sem ela não há como sair', async () => {
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { withNoRole: true });
+      setPath(deps.reflector, 'impersonation', 'stop', RequestMethod.POST);
+
+      await expect(
+        guard.canActivate(makeContext(impersonatedRequest) as any),
+      ).resolves.toBe(true);
+    });
+
+    it('não interfere fora de uma simulação', async () => {
+      const { guard, deps } = makeService();
+      setMeta(deps.reflector, { withNoRole: true });
+      setPath(deps.reflector, 'auth', 'desktop-token', RequestMethod.GET);
+      const request = {
+        headers: { authorization: 'Bearer tok' },
+        auth: { sub: 3, sessionId: 1 },
+      };
+
+      await expect(guard.canActivate(makeContext(request) as any)).resolves.toBe(
+        true,
+      );
+    });
+  });
 });