Connectors

Production connectors

Connectors committen externe source evidence naar Proofstream zonder tenant sessions bloot te stellen. Elke connector heeft echte authentication, replay handling, diagnostics en revoke behavior.

Connector model

Een connector is een source-to-evidence adapter. De connector observeert iets in een echt source system, valideert dat de source mag spreken, normaliseert de observation en schrijft een Proofstream event met een stabiele source reference. Kies connectors wanneer evidence buiten je applicatiecode ontstaat of wanneer een source system zijn eigen identiteit in het evidence trail moet behouden.

Authenticeer de source delivery of provider API.
Normaliseer de source reference en event type.
Verwerp replay conflicts voor dezelfde source reference.
Schrijf het event naar de geconfigureerde stream.
Retourneer of bewaar de Attesto receipt.
Toon diagnostics zonder provider secrets of raw private payloads te lekken.

Connectorfamilie	Tenant management route	Ingress route	Notities
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`	Creatie kan het connector secret één keer tonen. Bewaar het alleen 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`	Provider delivery signatures worden gevalideerd voordat genormaliseerde repository evidence wordt geschreven.
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`	Gebruikt tenant session om objectmetadata en integrity evidence vast te leggen; object bytes blijven in de bronstore.

Elk connector event moet source system id, source object id, source event type, source timestamp met timezone of UTC-offset, connector received time, idempotency/source reference en normalized payload commitment bewaren. Als een provider geen timezone-aware source timestamp kan leveren, moet de connector validatie falen in plaats van er een te verzinnen.

Signed webhook connector

Gebruik de signed webhook connector wanneer een externe source een signed JSON body naar Attesto kan POSTen. De source reference is de idempotency key binnen de stream. Het dashboard maakt en revoket connector records via /v2/tenant/connectors/signed-webhooks; het bronsysteem stuurt events alleen naar het publieke 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

De GitHub connector valideert X-Hub-Signature-256 over de raw provider body en commit genormaliseerde repository-change metadata naar de geconfigureerde Proofstream.

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

De GitLab connector valideert de geconfigureerde signing token over de raw provider delivery. Bestaande installations kunnen hun legacy token mode behouden tot rotatie.

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

Gebruik object commitments wanneer evidence al in AWS S3, Cloudflare R2 of een S3-compatible store staat. Attesto voert een echte HeadObject call uit, receiptt object identity en integrity metadata, en proxyt geen 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 mogen alleen metadata bevatten die veilig is om als evidence op te slaan. Object content blijft in de customer object store. Gebruik read-only credentials beperkt tot de vereiste bucket prefix, en commit versioned object metadata wanneer de store object versions ondersteunt.

Marketplace distribution

Gevalideerde first-party connector manifests zijn beschikbaar via https://marketplace.attesto.eu. Publieke bezoekers kunnen de catalogus bekijken. Een manifest downloaden, een entitlement verkrijgen of een installation maken vereist een Attesto tenant session. De marketplace en connector kits gebruiken dezelfde attesto.connector.v2 manifest validation rules.

De eerste gratis Attesto first-party listings zijn Signed Webhook Evidence, GitHub Repository Evidence, GitLab Repository Evidence en S3/R2 Object Commitment. Elke listing koppelt het marketplace-validatieresultaat aan een connector-assurance canary guarantee, zodat Evidence Score en Verified badges reproduceerbare release evidence zijn in plaats van marketinglabels.

Connector diagnostics

Tenant-visible diagnostics tonen of een connector enabled, recent gebruikt, failing auth, failing replay checks of revoked is. Ze tonen geen connector credentials, raw provider payloads of private object content.

Status	Betekenis
`healthy`	Recente signed delivery of source check is geslaagd.
`auth_failed`	Provider- of HMAC-signature kon niet worden geverifieerd.
`replay_conflict`	Dezelfde source reference werd opnieuw aangeboden met andere content.
`revoked`	Ingress is disabled en moet fail-closed werken.

Safety boundaries

Connector endpoints verwerpen replay conflicts.
Revoked connectors geven not found terug op ingress.
Outbound URLs moeten HTTPS en publicly routable zijn.
S3-compatible connector credentials moeten read-only zijn en beperkt tot de vereiste bucket prefix.
Plaats geen raw object content, private material of customer secrets in connector metadata.