0002 — JWT RS256 com nimbus-jose-jwt

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-30 · Decidido em: 2026-04-01

Contexto

O PowerSync valida os tokens dos apps buscando uma chave pública no JWKS do emissor. Precisamos de um algoritmo de assinatura que o PowerSync aceite e de uma biblioteca já testada no ecossistema.

Decisão

Emitir JWT RS256 (RSA-2048) com a biblioteca nimbus-jose-jwt — a mesma do integrador. O JWKS expõe a chave pública com alg=RS256 explícito e um kid configurável (AUTH_KEY_ID).

Consequências

• O PowerSync valida os tokens sem a chave privada, só com o JWKS público.
• alg=RS256 precisa ser adicionado à mão ao montar o JWKS — o nimbus-jose-jwt não o inclui por padrão, e o PowerSync recusa chaves sem alg. É um ponto a não esquecer ao mexer no JwtService.
• O kid configurável habilita rotação futura de chaves (ver runbook de rotação).

Alternativas consideradas

• HS256 (simétrico): o PowerSync precisaria da chave secreta — inviável para validação por terceiros. Descartado.
• EC256: não testado com o PowerSync nesta versão; sem ganho que justifique o risco. Descartado.