Connectors

Connectors de producción

Los connectors incorporan external source evidence a Proofstream sin exponer tenant sessions. Cada connector tiene authentication real, replay handling, diagnostics y revoke behavior.

Modelo de connector

Un connector es un adaptador source-to-evidence. Observa algo en un source system real, valida que la source esté autorizada a hablar, normaliza la observation y escribe un event Proofstream con una source reference estable. Los connectors deben elegirse cuando la evidence se origina fuera del código de su aplicación o cuando un source system debe mantener su propia identidad en el evidence trail.

Autenticar la source delivery o provider API.
Normalizar la source reference y el event type.
Rechazar replay conflicts para la misma source reference.
Escribir el event en el stream configurado.
Devolver o almacenar el Attesto receipt.
Exponer diagnostics sin filtrar provider secrets ni raw private payloads.

Familia de connector	Tenant management route	Ingress route	Notas
Signed webhook	`GET/POST /v2/tenant/connectors/signed-webhooks`, `DELETE /v2/tenant/connectors/signed-webhooks/{connector_id}`	`POST /v2/connectors/signed-webhooks/{connector_id}/events`	La creación puede revelar el connector secret una sola vez. Guárdelo solo server-side.
GitHub/GitLab repository webhook	`GET/POST /v2/tenant/connectors/repository-webhooks`, `DELETE /v2/tenant/connectors/repository-webhooks/{connector_id}`	`POST /v2/connectors/repository-webhooks/{connector_id}/events`	Las provider delivery signatures se validan antes de escribir repository evidence normalizada.
S3/R2 object commitment	`GET/POST /v2/tenant/connectors/s3-objects`, `DELETE /v2/tenant/connectors/s3-objects/{connector_id}`	`POST /v2/tenant/connectors/s3-objects/{connector_id}/commit`	Usa tenant session para commit metadata e integrity evidence; los object bytes permanecen en el source store.

Cada connector event debe preservar source system id, source object id, source event type, source timestamp con timezone u offset UTC, connector received time, idempotency/source reference y normalized payload commitment. Si un provider no puede producir un source timestamp timezone-aware, el connector debe fallar validación en vez de inventarlo.

Signed webhook connector

Use el signed webhook connector cuando una source externa pueda hacer POST de un signed JSON body a Attesto. La source reference es la idempotency key dentro del stream. El dashboard crea y revoca connector records mediante /v2/tenant/connectors/signed-webhooks; el source system envía events solo al public connector ingress endpoint.

POST /v2/connectors/signed-webhooks/{connectorId}/events
Content-Type: application/json
X-Attesto-Connector-Timestamp: <unix-seconds>
X-Attesto-Connector-Signature: <hex-hmac-sha256>

{
  "source_ref": "source-system-2026-0001",
  "event_type": "source.observation",
  "occurred_at": "2026-06-07T12:00:00Z",
  "payload": {
    "control": "policy-check",
    "result": "passed",
    "policy_id": "policy-2026-01"
  }
}

GitHub repository connector

El connector de GitHub valida X-Hub-Signature-256 sobre el raw provider body y commit metadata repository-change normalizada al Proofstream configurado.

{
  "provider": "github",
  "event": "push",
  "repository": "owner/repository",
  "ref": "refs/heads/main",
  "before": "sha-before",
  "after": "sha-after",
  "delivery_id": "provider-delivery-id"
}

GitLab repository connector

El connector de GitLab valida el signing token configurado sobre la raw provider delivery. Las instalaciones existentes pueden mantener su legacy token mode hasta la rotación.

{
  "provider": "gitlab",
  "event": "push",
  "project_path": "group/project",
  "ref": "refs/heads/main",
  "before": "sha-before",
  "after": "sha-after",
  "delivery_id": "provider-delivery-id"
}

S3/R2 object commitment connector

Use object commitments cuando la evidence ya vive en AWS S3, Cloudflare R2 o un store S3-compatible. Attesto realiza una llamada real HeadObject, genera receipt de object identity e integrity metadata, y no proxy de object content.

POST /v2/tenant/connectors/s3-objects/{connectorId}/commit
Content-Type: application/json

{
  "key": "evidence/input.json",
  "versionId": "$OBJECT_VERSION_ID",
  "metadata": {
    "source": "case-file"
  }
}

Object commitments debe incluir solo metadata segura para almacenar como evidence. Object content permanece en el customer object store. Use credentials read-only limitadas al bucket prefix requerido, y commit versioned object metadata cuando el store soporte object versions.

Distribución marketplace

Los manifests validados de connectors first-party están disponibles en https://marketplace.attesto.eu. Los visitantes públicos pueden explorar el catálogo. Descargar un manifest, adquirir un entitlement o crear una installation requiere una Attesto tenant session. El marketplace y los connector kits usan las mismas reglas de validación de manifest attesto.connector.v2.

Los primeros listings Attesto first-party gratuitos son Signed Webhook Evidence, GitHub Repository Evidence, GitLab Repository Evidence y S3/R2 Object Commitment. Cada listing vincula su resultado de validación marketplace a una garantía canary de connector-assurance, para que el Evidence Score y las insignias Verified sean release evidence reproducible y no etiquetas de marketing.

Connector diagnostics

Los diagnostics visibles para tenant muestran si un connector está enabled, se usó recientemente, tiene failing auth, failing replay checks o está revoked. No revelan connector credentials, raw provider payloads ni private object content.

Status	Significado
`healthy`	Una signed delivery o source check reciente tuvo éxito.
`auth_failed`	La signature del provider o HMAC no se verificó.
`replay_conflict`	La misma source reference se reprodujo con contenido diferente.
`revoked`	Ingress está disabled y debe fail closed.

Safety boundaries

Los endpoints connector rechazan replay conflicts.
Los connectors revoked devuelven not found en ingress.
Outbound URLs debe ser HTTPS y publicly routable.
Las credentials S3-compatible del connector deben ser read-only y limitadas al bucket prefix requerido.
No ponga raw object content, private material ni customer secrets en connector metadata.