Connectors

Connectors di produzione

I connectors committono external source evidence in Proofstream senza esporre tenant sessions. Ogni connector ha authentication reale, replay handling, diagnostics e revoke behavior.

Connector model

Un connector è un adattatore source-to-evidence. Osserva qualcosa in un source system reale, valida che la source sia autorizzata a parlare, normalizza l'observation e scrive un Proofstream event con una source reference stabile. I connectors vanno scelti quando l'evidence nasce fuori dal codice applicativo o quando un source system deve mantenere la propria identità nell'evidence trail.

Autentica la source delivery o provider API.
Normalizza la source reference e l'event type.
Rifiuta replay conflicts per la stessa source reference.
Scrivi l'event nello stream configurato.
Restituisci o archivia l'Attesto receipt.
Esponi diagnostics senza esporre provider secrets o raw private payloads.

Famiglia connector	Tenant management route	Ingress route	Note
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 creazione può rivelare il connector secret una sola volta. Conservalo 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`	Le provider delivery signatures sono validate prima di scrivere repository evidence normalizzata.
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 per commit metadata e integrity evidence; gli object bytes restano nel source store.

Ogni connector event deve preservare source system id, source object id, source event type, source timestamp con timezone o offset UTC, connector received time, idempotency/source reference e normalized payload commitment. Se un provider non può produrre un source timestamp timezone-aware, il connector deve fallire la validazione invece di inventarlo.

Signed webhook connector

Usa il signed webhook connector quando una source esterna può fare POST di un signed JSON body ad Attesto. La source reference è la idempotency key nello stream. La dashboard crea e revoca connector records tramite /v2/tenant/connectors/signed-webhooks; il source system invia 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

Il GitHub connector valida X-Hub-Signature-256 sul raw provider body e committe metadata repository-change normalizzata nel Proofstream configurato.

{
  "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

Il GitLab connector valida il signing token configurato sulla raw provider delivery. Le installations esistenti possono mantenere il legacy token mode fino alla rotazione.

{
  "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

Usa object commitments quando l'evidence vive già in AWS S3, Cloudflare R2 o in uno store S3-compatible. Attesto esegue una vera chiamata HeadObject, receiptta object identity e integrity metadata, e non fa proxy del contenuto dell'oggetto.

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 dovrebbe includere solo metadata sicuri da archiviare come evidence. Object content resta nel customer object store.

Marketplace distribution

I manifest dei connector first-party validati sono disponibili tramite https://marketplace.attesto.eu. I visitatori pubblici possono esplorare il catalogo. Scaricare un manifest, acquisire un entitlement o creare una installation richiede una Attesto tenant session. Marketplace e connector kits usano le stesse manifest validation rules attesto.connector.v2.

I primi listing Attesto first-party gratuiti sono Signed Webhook Evidence, GitHub Repository Evidence, GitLab Repository Evidence e S3/R2 Object Commitment. Ogni listing collega il risultato di marketplace validation a una connector-assurance canary guarantee, così Evidence Score e badge Verified sono release evidence riproducibile e non etichette di marketing.

Connector diagnostics

I diagnostics visibili al tenant mostrano se un connector è enabled, recently used, failing auth, failing replay checks o revoked. Non rivelano connector credentials, raw provider payloads o private object content.

Status	Significato
`healthy`	Una recent signed delivery o source check è riuscita.
`auth_failed`	La provider o HMAC signature non è stata verificata.
`replay_conflict`	La stessa source reference è stata riprodotta con contenuto diverso.
`revoked`	Ingress è disabled e deve fail closed.

Safety boundaries

Connector endpoints rifiutano replay conflicts.
Revoked connectors restituiscono not found su ingress.
Outbound URLs devono essere HTTPS e publicly routable.
Le S3-compatible connector credentials devono essere read-only e limitate al bucket prefix richiesto.
Non inserire raw object content, private material o customer secrets nei connector metadata.