feat(webhooks): provision pending signing secrets

Author: alpesdigital-adm

README.md

@@ -172,6 +172,19 @@ secret internamente, persiste apenas seu envelope AES-256-GCM autenticado e
 devolve metadados redigidos. O endpoint nasce pendente; sua ativação depende do
 challenge explícito, que não é disparado silenciosamente durante o cadastro.
 
+Antes do challenge, o administrador deve provisionar a chave de verificação no
+receptor por `POST /v1/webhooks/endpoints/{endpointId}/signing-secrets`, enviando
+`baseRevision` e `Idempotency-Key`. A primeira resposta devolve
+`secretBase64url` e `secretAvailable: true`; esse valor representa exatamente os
+32 bytes da chave HMAC em Base64URL e deve ser transferido para o secret manager
+do receptor sem entrar em logs. Replay da mesma requisição devolve os mesmos
+metadados, mas nunca repete a chave (`secretAvailable: false`). Se a primeira
+resposta for perdida, deve-se consultar a nova revisão do endpoint e provisionar
+outra versão com uma nova chave idempotente. A versão anterior é aposentada na
+mesma transação. Neste incremento, o command só aceita endpoint ainda pendente;
+rotação de endpoint ativo exige overlap para proteger deliveries em voo e será
+um contrato separado.
+
 A ativação é solicitada por
 `POST /v1/webhooks/endpoints/{endpointId}/challenge`, sem body. O Apollo faz um
 POST HTTPS para a URL cadastrada com JSON canônico no formato

TODO.md

@@ -496,7 +496,7 @@
 - [x] Modelar endpoint, subscription, secret, filter e delivery attempt. Evidência F0-034: domínios canônicos, registro transacional, cinco tabelas, constraints e regressões de segurança.
 - [x] Implementar challenge, assinatura, timestamp e anti-replay. Evidência F0-035/F0-036: challenge durável one-shot, HMAC dos bytes exatos, janela de timestamp, receipt anti-replay e transporte HTTPS pinado com resolução DNS fail-closed.
 - [x] Implementar at-least-once, backoff, dead-letter e replay controlado. Evidência F0-031/F0-046: render possui lease/fencing, backoff, checkpoint, dead-letter e retry manual; webhooks possuem outbox/fan-out, claim/lease/fencing, dispatch assinado, transporte DNS-pinado, heartbeat, discovery, coordenação durável de shards, secret provider configurado, entrypoint operacional, backoff, dead-letter e replay idempotente individual ou por evento exato. Replay por intervalo permanece enhancement administrativo separado.
-- [ ] Criar UI/API administrativa de status, attempts e rotação de secret. Parcial F0-042/F0-044/F0-047/F0-048/F0-049/F0-050/F0-051/F0-052: API externa cria/lista/lê endpoints e subscriptions, consulta deliveries, executa challenge/ativação, replay e lifecycle; UI e rotação de secret continuam abertas.
+- [ ] Criar UI/API administrativa de status, attempts e rotação de secret. Parcial F0-042/F0-044/F0-047/F0-048/F0-049/F0-050/F0-051/F0-052/F0-053: API externa cria/lista/lê endpoints e subscriptions, provisiona chave HMAC pendente, executa challenge/ativação, replay e lifecycle; UI e rotação com overlap de endpoint ativo continuam abertas.
 - [x] Criar integration tests de duplicação, timeout, assinatura inválida e replay. Evidência F0-035/F0-043: assinatura adulterada, anti-replay durável, deadline absoluto, DNS/rebinding, claim concorrente, lease/fencing, retry/dead-letter e replay administrativo idempotente estão cobertos em contratos, Prisma e HTTP.
 
 ### F0.039 — Idempotência e concorrência externa [FR-245]
@@ -539,7 +539,7 @@
 ### F0.043 — Governança da API [FR-249]
 
 - [ ] Criar administração de clients, scopes, secrets, environments e status.
-- [ ] Criar administração de webhooks, subscriptions e delivery diagnostics. Parcial F0-042/F0-044/F0-047/F0-048/F0-049/F0-050/F0-051/F0-052: capabilities entregam cadastro idempotente, consultas, challenge/ativação, lifecycle com cascatas e replay workspace-scoped; rotação e UI continuam abertas.
+- [ ] Criar administração de webhooks, subscriptions e delivery diagnostics. Parcial F0-042/F0-044/F0-047/F0-048/F0-049/F0-050/F0-051/F0-052/F0-053: capabilities entregam cadastro idempotente, provisionamento one-shot da chave pendente, consultas, challenge/ativação, lifecycle com cascatas e replay workspace-scoped; rotação ativa e UI continuam abertas.
 - [ ] Implementar rate limits, quotas, concurrency e spend budgets por client/workspace.
 - [ ] Criar usage e audit queries paginadas com redaction.
 - [ ] Criar sandbox isolado com provider fakes e custos simulados.
@@ -4093,7 +4093,7 @@ Limites explícitos desta slice:
 
 ### Slice F0-052 — Challenge público e ativação convergente de endpoint
 
-**Status:** concluído localmente em 15 de julho de 2026; ainda não commitado.
+**Status:** publicado no `main` em 15 de julho de 2026 (`1f93e3e`); hosted CI `29449277660` aprovada.
 
 Entregas:
 
@@ -4125,3 +4125,38 @@ Limites explícitos desta slice:
 - o challenge é síncrono e limitado pelo deadline; operação assíncrona será necessária apenas se providers futuros excederem essa janela;
 - alteração de URL e rotação de signing secret permanecem commands separados futuros;
 - UI administrativa, audit query, métricas, circuit breaker e alertas continuam futuros.
+
+### Slice F0-053 — Provisionamento one-shot da chave HMAC pendente
+
+**Status:** concluído localmente em 15 de julho de 2026; ainda não commitado.
+
+Entregas:
+
+- capability `apollo.webhooks.endpoints.signing-secrets.provision` expõe `POST /v1/webhooks/endpoints/{endpointId}/signing-secrets` sob `webhooks:admin`;
+- o fluxo corrige o pré-requisito criptográfico do HMAC: o receptor passa a receber os 32 bytes necessários para verificar deliveries;
+- body fechado exige `baseRevision` e o header exige `Idempotency-Key`;
+- somente endpoint `pending-verification` pode provisionar; endpoint ativo, suspenso ou revogado falha antes da mutação;
+- nova chave é gerada, fingerprinted e cifrada em AES-256-GCM; a versão ativa anterior é aposentada e a nova versão é persistida atomicamente;
+- endpoint recebe nova revisão na mesma transação, impedindo challenge ou provisionamentos concorrentes sobre estado obsoleto;
+- primeira resposta retorna 201, `secretBase64url` one-shot e `secretAvailable: true`;
+- replay idêntico retorna 200 com o mesmo endpoint/secret metadata, `secretAvailable: false` e sem material HMAC;
+- mesma chave idempotente com revisão diferente retorna conflito de payload; nova chave com revisão antiga retorna conflito de revisão;
+- ledger persiste apenas IDs e metadados seguros, nunca a chave retornada;
+- ADR-042 formaliza provisionamento, recuperação após resposta perdida e separação da rotação ativa com overlap.
+
+Regressões e evidências locais:
+
+- suíte global passa com 115 testes; 47 são contratos de webhook;
+- testes cobrem disclosure único, bytes temporários zerados, replay redigido e validação antes da geração;
+- integração Prisma cobre retirement da v1, criação/abertura cifrada da v2, replay, conflitos, ledger redigido e revisão obsoleta;
+- jornada HTTP cobre OpenAPI, 201/200, chave one-shot, fingerprint, body/header inválido, endpoint ativo, revisão antiga e 403 sem scope;
+- contratos públicos passam com 41 capabilities, 51 schemas, 70 exemplos e 36 paths;
+- build registra `POST /v1/webhooks/endpoints/{endpointId}/signing-secrets`;
+- schema/migration permanecem com 27 tabelas, 102 índices e 57 chaves estrangeiras.
+
+Limites explícitos desta slice:
+
+- perda da primeira resposta exige consultar a revisão atual e gerar outra versão; a chave nunca pode ser recuperada novamente;
+- endpoint ativo ainda não pode rotacionar porque deliveries em voo exigem período de overlap e escolha de versão explícita;
+- o consumidor deve decodificar Base64URL para os 32 bytes HMAC e armazená-los em seu próprio secret manager;
+- alteração de URL, UI administrativa, audit query, métricas e alertas continuam futuros.

docs/adr/ADR-042-one-time-pending-webhook-secret-provisioning.md

@@ -0,0 +1,39 @@
+# ADR-042 — Provisionamento one-shot da chave HMAC pendente
+
+> **Status:** Accepted
+>
+> **Data:** 15 de julho de 2026
+
+## Contexto
+
+O Apollo gerava e cifrava o signing secret de cada endpoint, mas não existia um canal para provisionar a mesma chave no receptor. Como HMAC exige segredo compartilhado, o receptor podia responder ao challenge, porém não conseguia verificar assinaturas das deliveries. Expor novamente uma chave após replay também criaria risco de persistência acidental em ledger, cache ou logs.
+
+## Decisão
+
+- A capability `apollo.webhooks.endpoints.signing-secrets.provision` expõe `POST /v1/webhooks/endpoints/{endpointId}/signing-secrets` sob `webhooks:admin` e confirmação humana.
+- O body contém somente `baseRevision`; `Idempotency-Key` é obrigatória e vinculada a workspace, actor, endpoint e revisão solicitada.
+- Somente endpoint `pending-verification` pode usar o command. Assim, nenhuma delivery assinada pode estar em voo durante a substituição.
+- A operação lê a maior versão, gera 32 bytes aleatórios para a próxima, calcula SHA-256, cifra o valor Base64URL com AES-256-GCM e contexto autenticado e zera o buffer temporário.
+- Na mesma transação serializável, o endpoint avança de revisão, o único secret ativo é aposentado, a nova versão e seu payload cifrado são criados e o ledger é concluído.
+- A primeira resposta retorna `secretBase64url`, `secretAvailable: true` e 201. Esse é o único momento em que a chave deixa a fronteira protegida do Apollo.
+- Replay idêntico retorna 200, os mesmos metadados, `secretAvailable: false` e omite completamente `secretBase64url`.
+- O ledger armazena apenas `endpointId` e `secretId`. Plaintext, Base64URL, `keyRef`, nonce, ciphertext e auth tag não entram na resposta persistida.
+- Se a primeira resposta for perdida, a chave não é recuperada. O administrador consulta a nova revisão e executa outro provisionamento com nova `Idempotency-Key`, aposentando a versão desconhecida.
+- Endpoint ativo, suspenso ou revogado retorna conflito. Rotação ativa será outro contrato, com validade sobreposta e versão de assinatura explícita para proteger deliveries em voo.
+
+## Consequências
+
+- O workflow externo completo passa a ser: criar endpoint, provisionar chave no receptor, configurar verificação HMAC, executar challenge e somente então receber deliveries.
+- Agentes externos podem automatizar o provisionamento sem acesso ao banco, `keyRef` ou chave mestra do Apollo.
+- A resposta one-shot deve usar `Cache-Control: no-store`, TLS e um cliente que não registre bodies sensíveis.
+- A versão v1 criada junto do endpoint pode ser aposentada sem nunca ter sido divulgada; a primeira chave operacional normalmente será v2.
+
+## Evidências exigidas
+
+- primeira resposta contém exatamente 32 bytes em Base64URL e fingerprint correspondente;
+- replay nunca contém a chave e devolve o mesmo secret ID/version;
+- ledger e payload durável não contêm plaintext;
+- retirement, criação do payload, nova revisão e idempotência são atômicos;
+- revisão antiga, lifecycle incompatível, workspace ausente e falta de scope falham fechado;
+- bytes temporários são zerados e provider abre somente a versão ativa exata;
+- OpenAPI, schemas, exemplos, Prisma e jornada HTTP descrevem o mesmo contrato.

docs/adr/README.md

@@ -43,3 +43,4 @@ Estados usados:
 - [ADR-039 — Criação idempotente de subscriptions de webhook](./ADR-039-idempotent-webhook-subscription-creation.md)
 - [ADR-040 — Cadastro de endpoint com secret dinâmico cifrado](./ADR-040-encrypted-dynamic-webhook-endpoint-registration.md)
 - [ADR-041 — Challenge público e ativação convergente de webhook](./ADR-041-public-webhook-challenge-and-convergent-activation.md)
+- [ADR-042 — Provisionamento one-shot da chave HMAC pendente](./ADR-042-one-time-pending-webhook-secret-provisioning.md)

src/app/v1/webhooks/endpoints/[endpointId]/signing-secrets/route.ts

@@ -0,0 +1,81 @@
+import { randomUUID } from 'node:crypto'
+
+import { NextRequest, NextResponse } from 'next/server'
+
+import { requireScope } from '@/v2/application/authenticate-api-client'
+import { provisionWebhookSigningSecretService } from '@/v2/application/provision-webhook-signing-secret'
+import { readWebhookEndpointService } from '@/v2/application/read-webhook-administration'
+import { DomainError } from '@/v2/domain/errors'
+import {
+  createConfiguredWebhookSigningSecretProtector,
+  createWebhookAdministrationQueryRepository,
+  createWebhookSigningSecretProvisioningRepository,
+} from '@/v2/infrastructure/repository-factory'
+import { authenticateExternalRequest } from '@/v2/public-api/authentication'
+import { publicApiHeaders, resolveRequestId, respondPublicError } from '@/v2/public-api/errors'
+import { presentSuccess, presentWebhookEndpointSummary } from '@/v2/public-api/presenters'
+
+export const dynamic = 'force-dynamic'
+
+export async function POST(
+  request: NextRequest,
+  context: { params: Promise<{ endpointId: string }> },
+) {
+  const requestId = resolveRequestId(request)
+  try {
+    const actor = await authenticateExternalRequest(request)
+    requireScope(actor, 'webhooks:admin')
+    let body: { baseRevision?: unknown }
+    try {
+      body = await request.json() as typeof body
+    } catch {
+      throw new DomainError('INVALID_ARGUMENT', 'Request body must be valid JSON')
+    }
+    if (
+      typeof body !== 'object' ||
+      body === null ||
+      Array.isArray(body) ||
+      Object.keys(body).sort().join(',') !== 'baseRevision' ||
+      typeof body.baseRevision !== 'string'
+    ) {
+      throw new DomainError(
+        'INVALID_ARGUMENT',
+        'Request body must contain only baseRevision',
+      )
+    }
+    const { endpointId } = await context.params
+    const provision = provisionWebhookSigningSecretService({
+      repository: createWebhookSigningSecretProvisioningRepository(),
+      secrets: createConfiguredWebhookSigningSecretProtector(),
+      clock: () => new Date(),
+      createId: () => randomUUID(),
+    })
+    const result = await provision({
+      workspaceId: actor.workspaceId,
+      endpointId,
+      actorClientId: actor.clientId,
+      baseRevision: body.baseRevision,
+      idempotencyKey: request.headers.get('idempotency-key') ?? '',
+    })
+    const read = readWebhookEndpointService({
+      repository: createWebhookAdministrationQueryRepository(),
+    })
+    const endpoint = await read({ workspaceId: actor.workspaceId, endpointId })
+    return NextResponse.json(
+      presentSuccess({
+        endpoint: presentWebhookEndpointSummary(endpoint),
+        ...(result.secretAvailable
+          ? { secretBase64url: result.secretBase64url }
+          : {}),
+        secretAvailable: result.secretAvailable,
+        replayed: result.replayed,
+      }),
+      {
+        status: result.replayed ? 200 : 201,
+        headers: publicApiHeaders(requestId),
+      },
+    )
+  } catch (error) {
+    return respondPublicError(error, requestId)
+  }
+}

src/v2/application/ports/webhook-signing-secret-protector.ts

@@ -14,8 +14,16 @@ export interface ProtectedWebhookSigningSecretMaterial {
   payload: Readonly<WebhookSigningSecretPayload>
 }
 
+export interface DisclosedWebhookSigningSecretMaterial
+  extends ProtectedWebhookSigningSecretMaterial {
+  secretBase64url: string
+}
+
 export interface WebhookSigningSecretProtector {
   protect(
     request: Readonly<ProtectWebhookSigningSecretRequest>,
   ): Promise<Readonly<ProtectedWebhookSigningSecretMaterial>>
+  protectForOneTimeDisclosure(
+    request: Readonly<ProtectWebhookSigningSecretRequest>,
+  ): Promise<Readonly<DisclosedWebhookSigningSecretMaterial>>
 }

src/v2/application/ports/webhook-signing-secret-provisioning-repository.ts

@@ -0,0 +1,39 @@
+import type { WebhookEndpoint, WebhookSigningSecret } from '../../domain/webhook.ts'
+import type { WebhookSigningSecretPayload } from '../../domain/webhook-signing-secret-payload.ts'
+
+export interface WebhookSigningSecretProvisioningTarget {
+  endpoint: Readonly<WebhookEndpoint>
+  latestSecretVersion: number
+}
+
+export interface WebhookSigningSecretProvisioningCommand {
+  workspaceId: string
+  endpointId: string
+  actorClientId: string
+  baseRevision: string
+  secret: Readonly<WebhookSigningSecret>
+  secretPayload: Readonly<WebhookSigningSecretPayload>
+  idempotency: Readonly<{
+    id: string
+    key: string
+    requestFingerprint: string
+    requestedAt: string
+    expiresAt: string
+  }>
+}
+
+export interface WebhookSigningSecretProvisioningResult {
+  endpoint: Readonly<WebhookEndpoint>
+  secret: Readonly<WebhookSigningSecret>
+  replayed: boolean
+}
+
+export interface WebhookSigningSecretProvisioningRepository {
+  getTarget(
+    workspaceId: string,
+    endpointId: string,
+  ): Promise<Readonly<WebhookSigningSecretProvisioningTarget> | null>
+  provisionOrReplay(
+    command: Readonly<WebhookSigningSecretProvisioningCommand>,
+  ): Promise<Readonly<WebhookSigningSecretProvisioningResult>>
+}