feat(API Keys): Chaves de integração user-scoped (FIXR-35)

[felipemartinezmelo]

Implementa chaves de API para acesso programático ao Fixr (FIXR-35), cobrindo schema, API, autenticação e tela de gerenciamento.

Modelo de acesso

As chaves são user-scoped: pertencem a quem as criou e carregam exatamente as permissões do cargo desse usuário.

• O cargo é resolvido em tempo de request, nunca copiado para a chave. Rebaixar ou remover um funcionário estreita automaticamente todas as chaves dele.
• scopes[] é opcional e só restringe — nunca amplia além do que o criador possui. Vazio significa "herda o cargo como está".
• Cada funcionário vê e revoga apenas as próprias chaves, admins incluídos. Uma chave de outro dono responde 404 em vez de 403, para o endpoint não virar um oráculo de IDs.
• apiKeys:read|create|revoke entrou em baseEmployee, então é self-service para todo funcionário (guest segue sem).

A issue original descrevia o recurso como restrito a admins e gerentes, sobre um pool compartilhado da empresa. A descrição no Linear foi atualizada para o modelo acima.

Endpoints

Método	Rota
GET	/companies/:subdomain/api-keys — lista as chaves do próprio usuário (só o prefixo público)
POST	/companies/:subdomain/api-keys — cria e devolve o secret uma única vez
DELETE	/companies/:subdomain/api-keys/:id — revoga (soft delete, preserva auditoria)

Autenticação via x-api-key ou Authorization: Bearer <token>.

Decisão técnica: HMAC-SHA256 em vez de bcrypt

A issue pedia bcrypt. Bcrypt é lento de propósito, o que é correto para senha de usuário (baixa entropia), mas custa ~100ms em toda requisição autenticada — inviável numa API de integração e um vetor de DoS.

Chaves têm 256 bits de entropia aleatória: não há dicionário a atacar, então a lentidão não compra segurança. HMAC-SHA256 com pepper (API_KEY_SECRET) mantém a verificação em microssegundos e torna um dump da tabela inútil sem a env var. É o que GitHub, Stripe e AWS fazem.

Está isolado em hashApiKeySecret / verifyApiKeySecret, em um único arquivo, caso a decisão mude.

Performance e segurança

• Lookup por prefix com índice único: uma query por autenticação, e só então a verificação do secret em tempo constante (timingSafeEqual).
• last_used_at com throttle de 60s via SET NX no Redis — sem isso, toda chamada de leitura viraria uma escrita, com uma linha sob contenção constante.
• O secret em texto puro nunca é persistido nem devolvido de novo; no frontend ele sai do estado assim que o diálogo fecha.

Frontend

/dashboard/:subdomain/settings/api-keys, seguindo o módulo de funcionários (react-query + TanStack Table + dialogs). O seletor de permissões só oferece o que o usuário logado possui, então a UI nem consegue expressar uma chave que supere o criador.

Correções de bugs pré-existentes

Três defeitos que bloqueavam o build e vieram de commits anteriores nesta base. Estão em commits separados para facilitar cherry-pick:

• 3075673 — marcadores de merge (<<<<<<<) commitados em account/repositories, quebrando o build do server
• 2a8374c — use-as-ref.ts indentado com espaços, quebrando o biome check que roda antes do next build

⚠️ Pendência conhecida (não corrigida aqui)

bun run db:migrate não roda num banco limpo. A migration 0012_wooden_goliath faz RENAME COLUMN uploads.purpose e MODIFY model_images.upload_id — colunas que nenhuma migration anterior cria. Ela foi gerada contra um banco sincronizado via db:push. Isso quebra CI e qualquer ambiente novo, e merece uma issue própria.

Setup necessário

Nova env var obrigatória no server (já documentada no .env.example):

API_KEY_SECRET='' # mínimo 32 caracteres

Validação

• Lint e type-check passando nos 5 workspaces
• Build de produção do web OK, rota em 15.9 kB
• Endpoints verificados contra MySQL e Redis reais, com as rotas registradas no /openapi.json

Fora de escopo

Rate limiting foi extraído para a FIXR-44, em branch própria. É uma capacidade transversal a toda a API e não deveria entrar como efeito colateral desta feature.

Testes automatizados. A cobertura que eu priorizaria: scope não pode escalar privilégio, e chave revogada/expirada é recusada.

[linear-code]

FIXR-35

[risixdzn]

Ajustes

API

Ainda dá o mesmo erro na hora de revogar as chaves
500 DELETE /companies/acme/api-keys/raegm5rlhmw2qdb5kdz2f4f2

{"status":500,"error":"Internal Server Error","message":"[\n  {\n    \"expected\": \"string\",\n    \"code\": \"invalid_type\",\n    \"path\": [\n      \"subdomain\"\n    ],\n    \"message\": \"Invalid input: expected string, received undefined\"\n  }\n]","code":"internal_error","data":{"message":"[\n  {\n    \"expected\": \"string\",\n    \"code\": \"invalid_type\",\n    \"path\": [\n      \"subdomain\"\n    ],\n    \"message\": \"Invalid input: expected string, received undefined\"\n  }\n]","stack":"ZodError: [\n  {\n    \"expected\": \"string\",\n    \"code\": \"invalid_type\","}}

Não consigo acessar os endpoints da aplicação com o token gerado.
O comportamento desejado é que o token possa ser utilizado em TODOS endpoints, da mesma forma que um usuário interagiria com seu Bearer + refreshToken

O request seguinte

curl /account/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer fxr_Ytr-MUHCCu3P_SvcQmaiJVBOArSwxcb8m9I--NwskvikComL2xexTlcU'

Tem essa resposta (mesma coisa para todos outros endpoints que testei)

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Authorization token is invalid or expired.",
  "code": "auth_jwt_invalid",
  "data": null
}

---

Front

Ficou legal a Sheet no formulário de criação mas acho que ficaria melhor se fosse replicado o mesmo comportamento do form de nova ordem de serviço.
Uma rota /new que usa o conceito de parallel routes do NextJS, interceptada por um dialog / vaul headless que aparece com o formulário acima da página atual.

Também falta feedback de Toast na hora de criar.