Assinatura de Relatórios

O servidor permite assinar relatórios digitalmente por papel (role), verificar assinaturas existentes e portar relatórios entre diferentes implantações (deployers).

Requer ENCRYPTION_KEY configurado para habilitar o ReportSigner.

Assinar — POST /api/v1/reports/:id/sign

Permissão: canSettings ou canInsert

Body:

{
  "role": "deployer",
  "origin": "My Company"
}

Campo	Obrigatório	Descrição
role	Sim	Papel da assinatura (ex: author, deployer, reviewer)
origin	Não	Identificador da origem (ex: nome da empresa)

Resposta 200:

{
  "signed": true,
  "role": "deployer",
  "signatures": { ... }
}

Status	Erro	Quando
400	validation_error	role ausente
404	not_found	Relatório não encontrado
422	no_definition	Relatório sem definição
422	parse_error	Definição malformada
503	not_configured	ENCRYPTION_KEY não configurado

Verificar — GET /api/v1/reports/:id/signatures

Permissão: canList

Relatório assinado

{
  "byRole": {
    "deployer": {
      "valid": true,
      "origin": "My Company"
    },
    "author": {
      "valid": true,
      "origin": "Dev Team"
    },
    "export": {
      "valid": true,
      "origin": "verified-export",
      "identity": {
        "email": "user@acme.com",
        "verified_at": "2026-04-09T10:00:00.000Z",
        "domain": "acme.com"
      }
    }
  }
}

O campo identity está presente quando a assinatura foi gerada via Exportação Verificada (fluxo OTP). Ele registra o email verificado, o domínio e o momento da verificação — útil para auditoria e rastreabilidade.

Relatório não assinado

{
  "unsigned": true,
  "byRole": {}
}

Status	Erro	Quando
404	not_found	Relatório não encontrado
422	parse_error	Definição malformada
503	not_configured	ENCRYPTION_KEY não configurado

Portar — POST /api/v1/reports/:id/port

Permissão: canSettings

Permite transferir um relatório entre implantações diferentes, mantendo assinaturas selecionadas e adicionando uma nova.

Body:

{
  "keepRoles": ["author"],
  "newRole": "deployer",
  "newOrigin": "New Company"
}

Campo	Obrigatório	Default	Descrição
keepRoles	Não	["author"]	Roles a manter na portabilidade
newRole	Sim	—	Role da nova assinatura
newOrigin	Não	—	Origem da nova assinatura

Resposta 200:

{
  "ported": true,
  "newRole": "deployer",
  "keepRoles": ["author"],
  "signatures": { ... }
}

Status	Erro	Quando
400	validation_error	newRole ausente
404	not_found	Relatório não encontrado
422	no_definition	Relatório sem definição
422	parse_error	Definição malformada
503	not_configured	ENCRYPTION_KEY não configurado

Fluxo típico

Desenvolvedor (author)          Empresa A (deployer)         Empresa B (deployer)
        │                              │                            │
   sign(author)                        │                            │
        │──────── entrega ────────────▶│                            │
        │                         sign(deployer)                    │
        │                              │                            │
        │                              │──── port(keep:author) ────▶│
        │                              │                       sign(deployer)
        │                              │                            │
        │                         verify:                      verify:
        │                          author ✅                    author ✅
        │                          deployer ✅                  deployer ✅