# Contrato de integración para preservadores

Este contrato mantiene al portal desacoplado de los capturadores. El navegador crea un
trabajo mediante la API; el orquestador valida permisos y políticas; un worker aislado
ejecuta la captura y publica eventos.

## 1. Crear trabajo

`POST /v1/capture-jobs`

Cabeceras:

```http
Authorization: Bearer <access-token>
Idempotency-Key: <uuid-v7>
Content-Type: application/json
```

Cuerpo mínimo:

```json
{
  "caseId": "case_01J...",
  "connector": "web",
  "target": {
    "url": "https://example.com/publicacion/428"
  },
  "policyId": "policy_web_standard_v1",
  "requestedArtifacts": ["screenshot", "pdf", "html", "warc"],
  "operatorContext": {
    "reason": "Preservación solicitada por el responsable del caso"
  }
}
```

Respuesta `202 Accepted`:

```json
{
  "id": "job_01J...",
  "status": "queued",
  "createdAt": "2026-07-27T14:32:08.123Z",
  "links": {
    "self": "/v1/capture-jobs/job_01J...",
    "events": "/v1/capture-jobs/job_01J.../events"
  }
}
```

## 2. Estados normalizados

```text
queued
validated
dispatched
capturing
processing
sealing
completed
failed
cancelled
```

Los cambios de estado son monotónicos. Una reejecución crea un nuevo intento y nunca
sobrescribe artefactos previos.

## 3. Resultado del worker

Cada artefacto se sube con una URL prefirmada de un solo uso. El worker informa:

```json
{
  "jobId": "job_01J...",
  "attemptId": "attempt_01J...",
  "connector": {
    "name": "truevi-web-capture",
    "version": "1.0.0",
    "imageDigest": "sha256:..."
  },
  "startedAt": "2026-07-27T14:32:10.010Z",
  "finishedAt": "2026-07-27T14:33:02.222Z",
  "artifacts": [
    {
      "id": "artifact_01J...",
      "kind": "screenshot",
      "mediaType": "image/png",
      "size": 1830422,
      "sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
      "storageKey": "tenant/case/job/artifact.png"
    }
  ],
  "observations": [],
  "errors": []
}
```

## 4. Eventos y webhooks

Los callbacks deben incluir:

```http
Truevi-Event-Id: evt_01J...
Truevi-Timestamp: 1785162782
Truevi-Signature: v1=<hmac-sha256>
```

El receptor:

1. rechaza timestamps con una diferencia mayor a cinco minutos;
2. calcula la firma sobre `timestamp + "." + rawBody`;
3. compara en tiempo constante;
4. guarda `eventId` para evitar repetidos;
5. responde rápido y procesa en segundo plano.

Para integraciones de mayor criticidad, preferir firma asimétrica (Ed25519) y rotación de
claves publicada por JWKS.

## 5. Reglas de seguridad obligatorias

- El target se valida en servidor: esquema, DNS, redireccionamientos y rangos IP.
- Bloquear loopback, metadata cloud, redes privadas y destinos no autorizados para evitar SSRF.
- Resolver DNS nuevamente en el worker y fijar la IP durante el trabajo.
- Un contenedor o microVM efímera por intento, sin credenciales permanentes.
- Egreso de red por lista permitida y límites de tiempo, tamaño, CPU y memoria.
- Los artefactos no atraviesan la API como cuerpos grandes; van directo al almacenamiento.
- El worker no decide permisos, retención ni identidad del operador.
- Todos los payloads se validan con JSON Schema versionado.
- Nunca reutilizar cookies o sesiones entre organizaciones o trabajos.

## 6. API del formulario público

`POST /v1/leads` recibe:

```json
{
  "name": "Nombre Apellido",
  "email": "persona@organizacion.com",
  "organization": "Organización",
  "role": "peritaje",
  "monthlyVolume": "11-50",
  "message": "Capturas web y redes",
  "plan": "Profesional",
  "consent": true,
  "source": "truevi-public-site",
  "locale": "es"
}
```

Aplicar validación, límite por IP y fingerprint prudente, honeypot, cola de correo/CRM,
registro de consentimiento y política de retención corta. La API debe permitir CORS
únicamente desde el origen público definitivo.
