@hed-hog/core 0.0.390 → 0.0.393

package/src/user-device/user-device.controller.ts

@@ -0,0 +1,77 @@
+import { Role, User } from '@hed-hog/api';
+import { Pagination, PaginationDTO } from '@hed-hog/api-pagination';
+import {
+  Controller,
+  Delete,
+  Get,
+  Headers,
+  Param,
+  ParseIntPipe,
+} from '@nestjs/common';
+import { UserDeviceService } from './user-device.service';
+
+@Role()
+@Controller('user-device')
+export class UserDeviceController {
+  constructor(private readonly userDeviceService: UserDeviceService) {}
+
+  /**
+   * Dispositivos do proprio usuario autenticado.
+   *
+   * Os headers da requisicao entram para que o service saiba qual das linhas e
+   * o aparelho que esta perguntando (`current`) — sem eles a tela nao consegue
+   * distinguir "este dispositivo" dos outros, e o unico jeito de fazer isso no
+   * cliente seria expor a device_key.
+   */
+  @Get()
+  async list(
+    @Pagination() paginationParams: PaginationDTO,
+    @User() { id },
+    @Headers('user-agent') userAgent: string,
+    @Headers('x-browser-id') browserId: string,
+  ) {
+    return this.userDeviceService.list(paginationParams, id, {
+      userAgent: userAgent || null,
+      browserId: browserId || null,
+    });
+  }
+
+  /**
+   * Esquece um dispositivo do proprio usuario.
+   *
+   * O id do usuario vem do token, nunca da URL: e o que impede alguem de apagar
+   * o dispositivo de outra pessoa chutando o id.
+   */
+  @Delete(':deviceId')
+  async forget(
+    @User() { id },
+    @Param('deviceId', ParseIntPipe) deviceId: number,
+  ) {
+    return this.userDeviceService.forget(id, deviceId);
+  }
+
+  /**
+   * Dispositivos de outro usuario, para o sheet do admin. Restrita ao papel
+   * admin pela tabela `route` (ver hedhog/data/route.yaml) — o RoleGuard e quem
+   * barra; a rota em si nao checa papel.
+   */
+  @Get('user/:userId')
+  async listForUser(
+    @Pagination() paginationParams: PaginationDTO,
+    @Param('userId', ParseIntPipe) userId: number,
+  ) {
+    return this.userDeviceService.list(paginationParams, userId);
+  }
+
+  /**
+   * Esquece um dispositivo de outro usuario. Mesma restricao de papel da
+   * listagem acima.
+   */
+  @Delete('user/:userId/:deviceId')
+  async forgetForUser(
+    @Param('userId', ParseIntPipe) userId: number,
+    @Param('deviceId', ParseIntPipe) deviceId: number,
+  ) {
+    return this.userDeviceService.forget(userId, deviceId);
+  }
+}

package/src/user-device/user-device.module.ts

@@ -0,0 +1,13 @@
+import { PaginationModule } from '@hed-hog/api-pagination';
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { forwardRef, Module } from '@nestjs/common';
+import { UserDeviceController } from './user-device.controller';
+import { UserDeviceService } from './user-device.service';
+
+@Module({
+  imports: [forwardRef(() => PrismaModule), forwardRef(() => PaginationModule)],
+  controllers: [UserDeviceController],
+  providers: [UserDeviceService],
+  exports: [UserDeviceService],
+})
+export class UserDeviceModule {}

package/src/user-device/user-device.service.spec.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+import { buildDeviceKey } from '../utils/device-key';
+import { UserDeviceService } from './user-device.service';
+
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/151.0.0.0 Safari/537.36';
+
+const makeService = () => {
+  const prisma = {
+    user_device: {
+      findFirst: jest.fn(),
+      findUnique: jest.fn(),
+      upsert: jest.fn(),
+      deleteMany: jest.fn(),
+    },
+  };
+  const pagination = { paginatePrismaModel: jest.fn() };
+  return {
+    service: new UserDeviceService(prisma as any, pagination as any),
+    prisma,
+    pagination,
+  };
+};
+
+describe('UserDeviceService.isNewDevice', () => {
+  it('nao considera novo o primeiro login da conta', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.findFirst.mockResolvedValue(null);
+    prisma.user_device.findUnique.mockResolvedValue(null);
+
+    expect(await service.isNewDevice(1, UA, 'b1')).toBe(false);
+  });
+
+  it('considera novo quando ha dispositivos, mas nenhum e este', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.findFirst.mockResolvedValue({ id: 7 });
+    prisma.user_device.findUnique.mockResolvedValue(null);
+
+    expect(await service.isNewDevice(1, UA, 'b1')).toBe(true);
+  });
+
+  it('nao considera novo um dispositivo ja registrado', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.findFirst.mockResolvedValue({ id: 7 });
+    prisma.user_device.findUnique.mockResolvedValue({ id: 9 });
+
+    expect(await service.isNewDevice(1, UA, 'b1')).toBe(false);
+  });
+
+  it('procura pela device_key derivada do browser_id', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.findFirst.mockResolvedValue(null);
+    prisma.user_device.findUnique.mockResolvedValue(null);
+
+    await service.isNewDevice(42, UA, 'browser-1');
+
+    expect(prisma.user_device.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: {
+          user_id_device_key: { user_id: 42, device_key: buildDeviceKey(UA, 'browser-1') },
+        },
+      }),
+    );
+  });
+
+  it('nao reanuncia o dispositivo quando o navegador se atualiza', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.findFirst.mockResolvedValue({ id: 7 });
+    // Registrado com o Chrome 150; volta com o 151, mesmo browser_id.
+    prisma.user_device.findUnique.mockImplementation(async ({ where }: any) =>
+      where.user_id_device_key.device_key === buildDeviceKey('Chrome/150', 'b1')
+        ? { id: 9 }
+        : null,
+    );
+
+    expect(await service.isNewDevice(1, 'Chrome/151', 'b1')).toBe(false);
+  });
+});
+
+describe('UserDeviceService.remember', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('grava a device_key, o UA interpretado e o ultimo IP', async () => {
+    const { service, prisma } = makeService();
+
+    await service.remember(42, { userAgent: UA, browserId: 'b1', ipAddress: '8.8.8.8' });
+
+    const arg = prisma.user_device.upsert.mock.calls[0][0] as any;
+    expect(arg.where).toEqual({
+      user_id_device_key: { user_id: 42, device_key: buildDeviceKey(UA, 'b1') },
+    });
+    expect(arg.create).toMatchObject({
+      user_id: 42,
+      browser_id: 'b1',
+      browser_name: 'Chrome',
+      os_name: 'Windows',
+      last_ip: '8.8.8.8',
+    });
+    expect(arg.update.last_seen_at).toEqual(expect.any(Date));
+    // O create nao pode reescrever o created_at de um dispositivo ja conhecido.
+    expect(arg.update).not.toHaveProperty('created_at');
+  });
+
+  it('normaliza vazios para null em vez de gravar string vazia', async () => {
+    const { service, prisma } = makeService();
+
+    await service.remember(42, { userAgent: '', browserId: '  ', ipAddress: undefined });
+
+    const arg = prisma.user_device.upsert.mock.calls[0][0] as any;
+    expect(arg.create).toMatchObject({
+      browser_id: null,
+      user_agent: null,
+      browser_name: null,
+      os_name: null,
+      last_ip: null,
+    });
+  });
+
+  it('engole a falha: nao registrar dispositivo nao pode impedir o login', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.upsert.mockRejectedValue(new Error('deadlock'));
+
+    await expect(
+      service.remember(42, { userAgent: UA, browserId: 'b1', ipAddress: '8.8.8.8' }),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe('UserDeviceService.list', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  const row = (id: number, device_key: string) => ({
+    id,
+    device_key,
+    browser_name: 'Chrome',
+    os_name: 'Windows',
+    user_agent: UA,
+    last_ip: '8.8.8.8',
+    last_seen_at: new Date(),
+    created_at: new Date(),
+  });
+
+  it('pagina escopado ao usuário e do mais recente para o mais antigo', async () => {
+    const { service, pagination, prisma } = makeService();
+    pagination.paginatePrismaModel.mockResolvedValue({ data: [], total: 0 });
+
+    await service.list({ page: 1, pageSize: 10 } as any, 42);
+
+    const [model, args] = pagination.paginatePrismaModel.mock.calls[0] as any[];
+    expect(model).toBe(prisma.user_device);
+    expect(args.where).toEqual({ user_id: 42 });
+    // Sem isto a primeira página traz os dispositivos mais antigos.
+    expect(args.orderBy).toEqual({ last_seen_at: 'desc' });
+  });
+
+  it('não expõe a device_key, que identifica o dispositivo nas requisições', async () => {
+    const { service, pagination } = makeService();
+    // Ela é lida do banco para calcular o `current`, mas não pode sair daqui.
+    pagination.paginatePrismaModel.mockResolvedValue({
+      data: [row(1, buildDeviceKey(UA, 'b1'))],
+      total: 1,
+    });
+
+    const { data } = await service.list({ page: 1, pageSize: 10 } as any, 42, {
+      userAgent: UA,
+      browserId: 'b1',
+    });
+
+    expect(data[0]).not.toHaveProperty('device_key');
+  });
+
+  it('marca como atual só o dispositivo que fez a chamada', async () => {
+    const { service, pagination } = makeService();
+    pagination.paginatePrismaModel.mockResolvedValue({
+      data: [row(1, buildDeviceKey(UA, 'b1')), row(2, buildDeviceKey(UA, 'b2'))],
+      total: 2,
+    });
+
+    const { data } = await service.list({ page: 1, pageSize: 10 } as any, 42, {
+      userAgent: UA,
+      browserId: 'b2',
+    });
+
+    expect(data.map((d: any) => [d.id, d.current])).toEqual([
+      [1, false],
+      [2, true],
+    ]);
+  });
+
+  it('sem fingerprint nenhum dispositivo é o atual', async () => {
+    const { service, pagination } = makeService();
+    pagination.paginatePrismaModel.mockResolvedValue({
+      data: [row(1, buildDeviceKey(UA, 'b1'))],
+      total: 1,
+    });
+
+    // O caso do admin olhando a lista de outra pessoa: sem os headers da
+    // requisição, `buildDeviceKey(null, null)` casaria com as linhas gravadas
+    // sem UA nem browser_id se o flag não fosse desligado de propósito.
+    const { data } = await service.list({ page: 1, pageSize: 10 } as any, 42);
+
+    expect(data[0].current).toBe(false);
+  });
+});
+
+describe('UserDeviceService.forget', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('exige que o dispositivo seja do usuário informado', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.deleteMany.mockResolvedValue({ count: 1 });
+
+    await service.forget(42, 7);
+
+    // O user_id no where é o que impede apagar o dispositivo de outra pessoa
+    // só por adivinhar o id.
+    expect(prisma.user_device.deleteMany).toHaveBeenCalledWith({
+      where: { id: 7, user_id: 42 },
+    });
+  });
+
+  it('devolve deleted=false quando o dispositivo é de outro usuário', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.deleteMany.mockResolvedValue({ count: 0 });
+
+    await expect(service.forget(42, 7)).resolves.toEqual({ deleted: false });
+  });
+
+  it('devolve deleted=true quando removeu', async () => {
+    const { service, prisma } = makeService();
+    prisma.user_device.deleteMany.mockResolvedValue({ count: 1 });
+
+    await expect(service.forget(42, 7)).resolves.toEqual({ deleted: true });
+  });
+});

package/src/user-device/user-device.service.ts

@@ -0,0 +1,168 @@
+import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
+import { PrismaService } from '@hed-hog/api-prisma';
+import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import { buildDeviceKey } from '../utils/device-key';
+import { parseUserAgent } from '../utils/user-agent';
+
+export interface DeviceFingerprint {
+  userAgent?: string | null;
+  browserId?: string | null;
+  ipAddress?: string | null;
+}
+
+/**
+ * Dispositivos ja vistos por usuario.
+ *
+ * Substitui a heuristica anterior, que procurava no historico de `user_session`
+ * para decidir se um login vinha de um dispositivo novo. Aquilo dependia de
+ * dados que a rotina de limpeza apaga: `clearExpiredSessions` remove sessoes
+ * expiradas com mais de `session-retention-days`, entao um dispositivo parado
+ * alguns meses saia do historico e era anunciado como novo de novo.
+ */
+@Injectable()
+export class UserDeviceService {
+  private readonly logger = new Logger(UserDeviceService.name);
+
+  constructor(
+    private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => PaginationService))
+    private readonly paginationService: PaginationService,
+  ) {}
+
+  /**
+   * `true` quando o usuario ja tem dispositivos registrados e nenhum deles e
+   * este.
+   *
+   * O primeiro login da conta nunca conta como dispositivo novo: nao ha com o
+   * que comparar, e quem acabou de se cadastrar ja recebeu as boas-vindas.
+   *
+   * Tem que rodar ANTES de `remember`, que passa a conhecer o dispositivo atual.
+   */
+  async isNewDevice(
+    userId: number,
+    userAgent?: string | null,
+    browserId?: string | null,
+  ): Promise<boolean> {
+    const device_key = buildDeviceKey(userAgent, browserId);
+
+    const [anyDevice, knownDevice] = await Promise.all([
+      this.prisma.user_device.findFirst({
+        where: { user_id: userId },
+        select: { id: true },
+      }),
+      this.prisma.user_device.findUnique({
+        where: { user_id_device_key: { user_id: userId, device_key } },
+        select: { id: true },
+      }),
+    ]);
+
+    return Boolean(anyDevice) && !knownDevice;
+  }
+
+  /**
+   * Registra o dispositivo ou atualiza o ultimo uso.
+   *
+   * Nunca lanca: isto roda dentro do fluxo de login, e falhar em anotar um
+   * dispositivo nao pode impedir alguem de entrar. O custo de engolir o erro e
+   * um alerta repetido no proximo login, nao um login perdido.
+   */
+  async remember(
+    userId: number,
+    { userAgent, browserId, ipAddress }: DeviceFingerprint,
+  ): Promise<void> {
+    const device_key = buildDeviceKey(userAgent, browserId);
+    const ua = parseUserAgent(userAgent);
+
+    const seen = {
+      browser_id: (browserId ?? '').trim() || null,
+      user_agent: (userAgent ?? '').trim() || null,
+      browser_name: ua?.browser_name ?? null,
+      os_name: ua?.os_name ?? null,
+      last_ip: (ipAddress ?? '').trim() || null,
+      last_seen_at: new Date(),
+    };
+
+    try {
+      await this.prisma.user_device.upsert({
+        where: { user_id_device_key: { user_id: userId, device_key } },
+        create: { user_id: userId, device_key, ...seen },
+        update: seen,
+      });
+    } catch (error) {
+      this.logger.error(
+        `Falha ao registrar dispositivo userId=${userId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  /**
+   * Dispositivos de um usuario, do mais recente para o mais antigo.
+   *
+   * Paginado como a lista de sessoes: uma conta antiga acumula dezenas de
+   * dispositivos, e devolver tudo de uma vez entrega uma parede de linhas.
+   *
+   * A `device_key` e lida para marcar qual linha e o aparelho que fez esta
+   * chamada (`current`), mas nunca sai daqui: e derivada do browser_id, entao
+   * devolve-la seria entregar de graca o valor que identifica o dispositivo nas
+   * requisicoes. Sem `fingerprint` — o caso do admin olhando a lista de outra
+   * pessoa — nenhuma linha e a atual.
+   */
+  async list(
+    paginationParams: PaginationDTO,
+    userId: number,
+    fingerprint?: DeviceFingerprint,
+  ) {
+    const currentKey = fingerprint
+      ? buildDeviceKey(fingerprint.userAgent, fingerprint.browserId)
+      : null;
+
+    const paginate = await this.paginationService.paginatePrismaModel(
+      this.prisma.user_device,
+      {
+        ...paginationParams,
+        where: { user_id: userId },
+        select: {
+          id: true,
+          device_key: true,
+          browser_name: true,
+          os_name: true,
+          user_agent: true,
+          last_ip: true,
+          last_seen_at: true,
+          created_at: true,
+        },
+        // Explicito: sem isto a paginacao ordena crescente e a primeira pagina
+        // mostra os dispositivos mais antigos.
+        orderBy: { last_seen_at: 'desc' },
+      },
+    );
+
+    return {
+      ...paginate,
+      data: (paginate.data ?? []).map(
+        ({ device_key, ...device }: { device_key: string }) => ({
+          ...device,
+          current: Boolean(currentKey) && device_key === currentKey,
+        }),
+      ),
+    };
+  }
+
+  /**
+   * Esquece um dispositivo. O proximo login vindo dele volta a disparar o
+   * alerta de dispositivo desconhecido — que e a reacao certa para "esse ai nao
+   * fui eu".
+   *
+   * O `user_id` entra no where junto com o id: sem ele, qualquer usuario
+   * autenticado apagaria o dispositivo de qualquer outro so por adivinhar o id.
+   */
+  async forget(userId: number, deviceId: number): Promise<{ deleted: boolean }> {
+    const { count } = await this.prisma.user_device.deleteMany({
+      where: { id: deviceId, user_id: userId },
+    });
+
+    return { deleted: count > 0 };
+  }
+}

package/src/utils/device-key.spec.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from '@jest/globals';
+import { createHash } from 'crypto';
+import { buildDeviceKey } from './device-key';
+
+const sha256 = (s: string) => createHash('sha256').update(s, 'utf8').digest('hex');
+
+const UA_A = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/151.0.0.0';
+const UA_B = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Safari/605.1.15';
+
+describe('buildDeviceKey', () => {
+  it('e estavel para a mesma entrada', () => {
+    expect(buildDeviceKey(UA_A, 'abc')).toBe(buildDeviceKey(UA_A, 'abc'));
+  });
+
+  it('devolve sempre 64 hex', () => {
+    for (const key of [
+      buildDeviceKey(UA_A, 'abc'),
+      buildDeviceKey(UA_A, null),
+      buildDeviceKey(null, null),
+    ]) {
+      expect(key).toMatch(/^[0-9a-f]{64}$/);
+    }
+  });
+
+  it('da precedencia ao browser_id e ignora o user agent', () => {
+    // Mesmo dispositivo que atualizou o navegador continua sendo o mesmo.
+    expect(buildDeviceKey(UA_A, 'abc')).toBe(buildDeviceKey(UA_B, 'abc'));
+  });
+
+  it('separa browser_ids diferentes', () => {
+    expect(buildDeviceKey(UA_A, 'abc')).not.toBe(buildDeviceKey(UA_A, 'xyz'));
+  });
+
+  it('cai no user agent quando nao ha browser_id', () => {
+    expect(buildDeviceKey(UA_A, null)).not.toBe(buildDeviceKey(UA_B, null));
+    expect(buildDeviceKey(UA_A, null)).toBe(buildDeviceKey(UA_A, undefined));
+    expect(buildDeviceKey(UA_A, '   ')).toBe(buildDeviceKey(UA_A, null));
+  });
+
+  it('nao confunde um user agent com um browser_id de mesmo texto', () => {
+    // E para isso que servem os prefixos b:/u:.
+    expect(buildDeviceKey('token-123', null)).not.toBe(buildDeviceKey(null, 'token-123'));
+  });
+
+  it('normaliza espacos nas bordas', () => {
+    expect(buildDeviceKey(UA_A, ' abc ')).toBe(buildDeviceKey(UA_A, 'abc'));
+    expect(buildDeviceKey(`  ${UA_A}  `, null)).toBe(buildDeviceKey(UA_A, null));
+  });
+
+  it('bate com a expressao que a migration usa no backfill', () => {
+    // A migration 20260808140000_core_user_device monta a mesma string antes do
+    // sha256. Divergir aqui faz todo dispositivo conhecido virar novo.
+    expect(buildDeviceKey(UA_A, 'abc')).toBe(sha256('b:abc'));
+    expect(buildDeviceKey(UA_A, null)).toBe(sha256(`u:${UA_A}`));
+    expect(buildDeviceKey(null, null)).toBe(sha256('u:'));
+  });
+});

package/src/utils/device-key.ts

@@ -0,0 +1,32 @@
+import { createHash } from 'crypto';
+
+/**
+ * Identidade estavel de um dispositivo para um usuario.
+ *
+ * O `browser_id` (UUID em localStorage, header X-Browser-ID) e o sinal forte e
+ * tem precedencia. Sem ele — app desktop, integracoes, clientes que nao mandam
+ * o header — cai no User-Agent, que erra para menos (nao distingue dois
+ * dispositivos com o mesmo UA) e nunca para mais.
+ *
+ * O resultado e um sha256 hex de largura fixa, e nao o valor cru, para caber
+ * num indice unico junto com o user_id sem depender do tamanho do UA. O
+ * `browser_id` e o `user_agent` continuam gravados em colunas proprias de
+ * `user_device`, entao nada de diagnostico se perde no hash.
+ *
+ * O prefixo `b:`/`u:` impede que um User-Agent que por acaso seja igual a um
+ * browser_id colida com ele.
+ *
+ * IMPORTANTE: a migration 20260808140000_core_user_device reproduz esta mesma
+ * expressao em SQL para popular a tabela a partir do historico de sessoes. Ao
+ * mudar a normalizacao aqui, as chaves ja gravadas deixam de casar e todo
+ * dispositivo conhecido vira "novo" — o que dispara um alerta para cada usuario.
+ */
+export function buildDeviceKey(
+  userAgent?: string | null,
+  browserId?: string | null,
+): string {
+  const browser = (browserId ?? '').trim();
+  const source = browser ? `b:${browser}` : `u:${(userAgent ?? '').trim()}`;
+
+  return createHash('sha256').update(source, 'utf8').digest('hex');
+}