@hed-hog/core 0.0.387 → 0.0.393

package/src/pairing/pairing.module.ts

@@ -0,0 +1,27 @@
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { Module, forwardRef } from '@nestjs/common';
+import { AuthModule } from '../auth/auth.module';
+import { SecurityModule } from '../security/security.module';
+import { TokenModule } from '../token/token.module';
+import { PairingController } from './pairing.controller';
+import { PairingService } from './pairing.service';
+
+/**
+ * Separado do AuthorizeModule: lá o HedHog é provedor OAuth para um cliente que
+ * conhece de antemão o servidor; aqui o ponto é justamente o aparelho que ainda
+ * não sabe com quem falar. O que os dois compartilham — token opaco com hash,
+ * TTL curto e consumo atômico — está copiado, não abstraído: uma base comum
+ * amarraria dois fluxos de auth que devem poder divergir.
+ */
+@Module({
+  imports: [
+    forwardRef(() => PrismaModule),
+    forwardRef(() => SecurityModule),
+    forwardRef(() => AuthModule),
+    forwardRef(() => TokenModule),
+  ],
+  controllers: [PairingController],
+  providers: [PairingService],
+  exports: [PairingService],
+})
+export class PairingModule {}

package/src/pairing/pairing.service.spec.ts

@@ -0,0 +1,462 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { BadRequestException } from '@nestjs/common';
+import { createHash, randomBytes } from 'crypto';
+
+// Mocka o MESMO módulo de onde o service importa (@hed-hog/api-prisma). Mockar
+// '@prisma/client' aqui deixaria o teste verde com um import que quebra em
+// runtime — a mesma armadilha documentada no spec do AuthorizeService.
+jest.mock('@hed-hog/api-prisma', () => ({
+  PrismaService: class {},
+  Prisma: {
+    sql: (strings: TemplateStringsArray, ...values: unknown[]) => ({
+      strings: [...strings],
+      values,
+    }),
+  },
+}));
+
+// eslint-disable-next-line import/first
+import { PairingService } from './pairing.service';
+
+const CLIENT_ID = 'hedhog-vaults';
+const USER_ID = 7;
+
+const sha256b64url = (value: string) =>
+  createHash('sha256').update(value).digest('base64url');
+
+const makeToken = () => randomBytes(32).toString('base64url');
+
+const future = () => new Date(Date.now() + 60_000);
+const past = () => new Date(Date.now() - 1);
+
+type Row = {
+  id: bigint;
+  direction: string;
+  user_id: number | null;
+  eph_public_key: string | null;
+  want_session: boolean;
+  payload_enc: string | null;
+  issued_ip: string | null;
+  issued_user_agent: string | null;
+  claimed_at: Date | null;
+  claim_ip: string | null;
+  claim_user_agent: string | null;
+  confirmed_at: Date | null;
+  cancelled_at: Date | null;
+  consumed_at: Date | null;
+  expires_at: Date;
+};
+
+const makeRow = (overrides: Partial<Row> = {}): Row => ({
+  id: 1n,
+  direction: 'browser-to-device',
+  user_id: USER_ID,
+  eph_public_key: null,
+  want_session: true,
+  payload_enc: null,
+  issued_ip: '10.0.0.1',
+  issued_user_agent: 'Chrome',
+  claimed_at: null,
+  claim_ip: null,
+  claim_user_agent: null,
+  confirmed_at: null,
+  cancelled_at: null,
+  consumed_at: null,
+  expires_at: future(),
+  ...overrides,
+});
+
+const makeDeps = () => {
+  const prisma = {
+    oauth_app_client: {
+      findUnique: jest.fn(async () => ({ client_id: CLIENT_ID, enabled: true })),
+    },
+    device_pairing_request: {
+      create: jest.fn(async () => ({ id: 1n })),
+      findFirst: jest.fn(async () => null),
+      updateMany: jest.fn(async () => ({ count: 1 })),
+      deleteMany: jest.fn(async () => ({ count: 0 })),
+    },
+    user_activity: { create: jest.fn(async () => ({})) },
+    $queryRaw: jest.fn(async () => [] as unknown[]),
+  };
+  // Cripto real: o hash é o contrato com o cliente, então não pode ser mockado.
+  const security = { hashSha256: (value: string) => sha256b64url(value) };
+  const auth = {
+    getAuthenticationPayload: jest.fn(async () => ({
+      accessToken: 'ACCESS',
+      refreshToken: 'REFRESH',
+      session: { id: 1, expires_at: future() },
+    })),
+  };
+  return { prisma, security, auth };
+};
+
+const makeService = (deps: ReturnType<typeof makeDeps>) =>
+  new PairingService(
+    deps.prisma as never,
+    deps.security as never,
+    deps.auth as never,
+  );
+
+/** Valores interpolados no `Prisma.sql` da última chamada. */
+const lastSqlValues = (deps: ReturnType<typeof makeDeps>): unknown[] => {
+  const calls = deps.prisma.$queryRaw.mock.calls;
+  return (calls[calls.length - 1]?.[0] as { values: unknown[] }).values;
+};
+
+let deps: ReturnType<typeof makeDeps>;
+let service: PairingService;
+
+beforeEach(() => {
+  deps = makeDeps();
+  service = makeService(deps);
+});
+
+describe('direção A: abertura', () => {
+  it('persiste apenas o hash — o token cru nunca chega ao banco', async () => {
+    const token = makeToken();
+
+    await service.start({
+      userId: USER_ID,
+      authTokenHash: sha256b64url(token),
+      clientId: CLIENT_ID,
+      ipAddress: '10.0.0.1',
+      userAgent: 'Chrome',
+    });
+
+    const args = deps.prisma.device_pairing_request.create.mock
+      .calls[0][0] as { data: Record<string, unknown> };
+    expect(args.data.auth_hash).toBe(sha256b64url(token));
+    expect(JSON.stringify(args.data)).not.toContain(token);
+    // Um pareamento recém-aberto não guarda material de chave nenhum.
+    expect(args.data.payload_enc).toBeUndefined();
+  });
+
+  it('recusa cliente desconhecido ou desabilitado', async () => {
+    deps.prisma.oauth_app_client.findUnique.mockResolvedValueOnce(null as never);
+
+    await expect(
+      service.start({
+        userId: USER_ID,
+        authTokenHash: 'h',
+        clientId: 'quem-sou-eu',
+        ipAddress: '',
+        userAgent: '',
+      }),
+    ).rejects.toThrow(BadRequestException);
+  });
+});
+
+describe('direção A: claim', () => {
+  it('reivindica uma vez e registra quem foi', async () => {
+    const token = makeToken();
+    deps.prisma.$queryRaw.mockResolvedValueOnce([
+      { id: 1n, user_id: USER_ID, expires_at: future() },
+    ] as never);
+
+    const result = await service.claim({
+      authToken: token,
+      clientId: CLIENT_ID,
+      ipAddress: '192.168.0.9',
+      userAgent: 'HedHogVaults/1.0',
+    });
+
+    expect(result.status).toBe('claimed');
+    const values = lastSqlValues(deps);
+    expect(values).toContain('192.168.0.9');
+    expect(values).toContain(sha256b64url(token));
+    expect(values).not.toContain(token);
+  });
+
+  it('o segundo leitor do mesmo QR perde a corrida', async () => {
+    // O UPDATE ... WHERE claimed_at IS NULL não devolve linha na segunda vez.
+    deps.prisma.$queryRaw.mockResolvedValueOnce([] as never);
+
+    await expect(
+      service.claim({
+        authToken: makeToken(),
+        clientId: CLIENT_ID,
+        ipAddress: '',
+        userAgent: '',
+      }),
+    ).rejects.toThrow(BadRequestException);
+  });
+});
+
+describe('direção A: confirm', () => {
+  it('grava o blob e marca confirmado', async () => {
+    deps.prisma.$queryRaw.mockResolvedValueOnce([{ id: 1n }] as never);
+
+    await service.confirm({ userId: USER_ID, id: '1', payloadEnc: 'BLOB' });
+
+    expect(lastSqlValues(deps)).toContain('BLOB');
+  });
+
+  it('a consulta é sempre filtrada pelo dono', async () => {
+    deps.prisma.$queryRaw.mockResolvedValueOnce([{ id: 1n }] as never);
+
+    await service.confirm({ userId: USER_ID, id: '1', payloadEnc: 'BLOB' });
+
+    expect(lastSqlValues(deps)).toContain(USER_ID);
+  });
+
+  it('recusa quando o registro não está no estado esperado', async () => {
+    // Cobre "de outro usuário", "antes do claim", "já confirmado" e "expirado":
+    // todos falham pelo mesmo WHERE, que não devolve linha.
+    deps.prisma.$queryRaw.mockResolvedValueOnce([] as never);
+
+    await expect(
+      service.confirm({ userId: 999, id: '1', payloadEnc: 'BLOB' }),
+    ).rejects.toThrow(BadRequestException);
+  });
+
+  it('recusa id que não é número', async () => {
+    await expect(
+      service.confirm({ userId: USER_ID, id: 'abc', payloadEnc: 'BLOB' }),
+    ).rejects.toThrow(BadRequestException);
+  });
+});
+
+describe('direção A: redeem', () => {
+  const params = {
+    authToken: 'TOKEN',
+    clientId: CLIENT_ID,
+    locale: 'en',
+    ipAddress: '192.168.0.9',
+    userAgent: 'HedHogVaults/1.0',
+  };
+
+  it('antes do confirm devolve pending e NÃO consome', async () => {
+    deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+      makeRow({ claimed_at: new Date() }) as never,
+    );
+
+    expect(await service.redeem(params)).toEqual({ status: 'pending' });
+    // O poll não pode queimar o registro: a aprovação ainda vai chegar.
+    expect(deps.prisma.$queryRaw).not.toHaveBeenCalled();
+  });
+
+  it('depois do confirm devolve tokens e o blob intacto', async () => {
+    deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+      makeRow({ claimed_at: new Date(), confirmed_at: new Date() }) as never,
+    );
+    deps.prisma.$queryRaw.mockResolvedValueOnce([
+      { user_id: USER_ID, payload_enc: 'BLOB-OPACO' },
+    ] as never);
+
+    const result = await service.redeem(params);
+
+    expect(result).toMatchObject({
+      status: 'confirmed',
+      accessToken: 'ACCESS',
+      refreshToken: 'REFRESH',
+      payload: 'BLOB-OPACO',
+    });
+    expect(deps.auth.getAuthenticationPayload).toHaveBeenCalledWith(
+      'en',
+      USER_ID,
+      '192.168.0.9',
+      'HedHogVaults/1.0',
+    );
+  });
+
+  it('o segundo redeem falha (consumo é único)', async () => {
+    deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+      makeRow({ confirmed_at: new Date() }) as never,
+    );
+    deps.prisma.$queryRaw.mockResolvedValueOnce([] as never);
+
+    await expect(service.redeem(params)).rejects.toThrow(BadRequestException);
+  });
+
+  it('recusa registro expirado, cancelado ou já consumido', async () => {
+    for (const row of [
+      makeRow({ expires_at: past() }),
+      makeRow({ cancelled_at: new Date() }),
+      makeRow({ consumed_at: new Date() }),
+    ]) {
+      deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+        row as never,
+      );
+      await expect(service.redeem(params)).rejects.toThrow(BadRequestException);
+    }
+  });
+
+  it('a mensagem de erro não distingue os casos', async () => {
+    const messages: string[] = [];
+    for (const row of [null, makeRow({ expires_at: past() })]) {
+      deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+        row as never,
+      );
+      await service.redeem(params).catch((e: Error) => messages.push(e.message));
+    }
+    expect(messages[0]).toBe(messages[1]);
+  });
+});
+
+describe('direção B', () => {
+  const EPH = 'BFakePublicKeyBase64==';
+
+  it('abre sem dono: o navegador que pede ainda não é ninguém', async () => {
+    await service.startReverse({
+      pollHash: 'HASH',
+      ephPublicKey: EPH,
+      wantSession: true,
+      clientId: CLIENT_ID,
+      ipAddress: '10.0.0.1',
+      userAgent: 'Chrome',
+    });
+
+    const args = deps.prisma.device_pairing_request.create.mock
+      .calls[0][0] as { data: Record<string, unknown> };
+    expect(args.data.user_id).toBeUndefined();
+    expect(args.data.eph_public_key).toBe(EPH);
+    expect(args.data.direction).toBe('device-to-browser');
+  });
+
+  it('a inspeção exige a pública efêmera do QR (barra enumeração de id)', async () => {
+    deps.prisma.device_pairing_request.findFirst.mockResolvedValue(
+      makeRow({ direction: 'device-to-browser', eph_public_key: EPH }) as never,
+    );
+
+    await expect(service.getReverseRequest('1', 'chave-errada')).rejects.toThrow(
+      BadRequestException,
+    );
+    await expect(service.getReverseRequest('1', EPH)).resolves.toMatchObject({
+      issuedIp: '10.0.0.1',
+      issuedUserAgent: 'Chrome',
+    });
+  });
+
+  it('aprovar amarra o registro a quem aprovou', async () => {
+    deps.prisma.$queryRaw.mockResolvedValueOnce([{ id: 1n }] as never);
+
+    await service.approveReverse({
+      userId: USER_ID,
+      id: '1',
+      ephPublicKey: EPH,
+      payloadEnc: 'BLOB',
+    });
+
+    const values = lastSqlValues(deps);
+    expect(values).toContain(USER_ID);
+    expect(values).toContain(EPH);
+    expect(values).toContain('BLOB');
+  });
+
+  it('aprovar com a efêmera errada é recusado', async () => {
+    deps.prisma.$queryRaw.mockResolvedValueOnce([] as never);
+
+    await expect(
+      service.approveReverse({
+        userId: USER_ID,
+        id: '1',
+        ephPublicKey: 'outra',
+        payloadEnc: 'BLOB',
+      }),
+    ).rejects.toThrow(BadRequestException);
+  });
+
+  it('o poll antes da aprovação não consome', async () => {
+    deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+      makeRow({ direction: 'device-to-browser' }) as never,
+    );
+
+    expect(await service.pollReverse({ pollToken: 'T', locale: 'en' })).toEqual({
+      status: 'pending',
+      claimed: false,
+    });
+    expect(deps.prisma.$queryRaw).not.toHaveBeenCalled();
+  });
+
+  it('com want_session, a sessão nasce com o IP do NAVEGADOR, não do celular', async () => {
+    deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+      makeRow({
+        direction: 'device-to-browser',
+        confirmed_at: new Date(),
+      }) as never,
+    );
+    deps.prisma.$queryRaw.mockResolvedValueOnce([
+      {
+        user_id: USER_ID,
+        payload_enc: 'BLOB',
+        want_session: true,
+        issued_ip: '10.0.0.1',
+        issued_user_agent: 'Chrome',
+      },
+    ] as never);
+
+    const result = await service.pollReverse({ pollToken: 'T', locale: 'en' });
+
+    expect(result).toMatchObject({ status: 'confirmed', payload: 'BLOB' });
+    expect(deps.auth.getAuthenticationPayload).toHaveBeenCalledWith(
+      'en',
+      USER_ID,
+      '10.0.0.1',
+      'Chrome',
+    );
+  });
+
+  it('sem want_session não emite sessão nenhuma', async () => {
+    deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+      makeRow({
+        direction: 'device-to-browser',
+        confirmed_at: new Date(),
+      }) as never,
+    );
+    deps.prisma.$queryRaw.mockResolvedValueOnce([
+      {
+        user_id: USER_ID,
+        payload_enc: 'BLOB',
+        want_session: false,
+        issued_ip: null,
+        issued_user_agent: null,
+      },
+    ] as never);
+
+    const result = await service.pollReverse({ pollToken: 'T', locale: 'en' });
+
+    expect(result).toEqual({ status: 'confirmed', payload: 'BLOB' });
+    expect(deps.auth.getAuthenticationPayload).not.toHaveBeenCalled();
+  });
+});
+
+describe('zero-knowledge', () => {
+  it('o serviço não tem como decifrar o payload', () => {
+    // O SecurityService injetado expõe só o hash. Se alguém adicionar
+    // `security.decrypt(payload_enc)` mais tarde, este teste quebra na hora —
+    // e é o único guarda-corpo automático da promessa de zero-knowledge.
+    expect(Object.keys(deps.security)).toEqual(['hashSha256']);
+  });
+
+  it('o blob volta byte a byte como entrou', async () => {
+    const blob = JSON.stringify({ v: 1, c: 'ciphertext', i: 'iv' });
+    deps.prisma.device_pairing_request.findFirst.mockResolvedValueOnce(
+      makeRow({ confirmed_at: new Date() }) as never,
+    );
+    deps.prisma.$queryRaw.mockResolvedValueOnce([
+      { user_id: USER_ID, payload_enc: blob },
+    ] as never);
+
+    const result = await service.redeem({
+      authToken: 'T',
+      clientId: CLIENT_ID,
+      locale: 'en',
+      ipAddress: '',
+      userAgent: '',
+    });
+
+    expect((result as { payload: string }).payload).toBe(blob);
+  });
+});
+
+describe('limpeza', () => {
+  it('apaga o que expirou há mais de um dia', async () => {
+    await service.purgeExpired();
+
+    const where = deps.prisma.device_pairing_request.deleteMany.mock
+      .calls[0][0] as { where: { expires_at: { lt: Date } } };
+    expect(where.where.expires_at.lt.getTime()).toBeLessThan(Date.now());
+  });
+});