Connectors

Production connectors

Connectors commit external source evidence into Proofstream without exposing tenant sessions. Every connector has real authentication, replay handling, diagnostics, and revoke behavior.

Connector model

A connector is a source-to-evidence adapter. It observes something in a real source system, validates that the source is allowed to speak, normalizes the observation, and writes a Proofstream event with a stable source reference. Connectors should be chosen when evidence originates outside your application code or when a source system must keep its own identity in the evidence trail.

Authenticate the source delivery or provider API.
Normalize the source reference and event type.
Reject replay conflicts for the same source reference.
Write the event into the configured stream.
Return or store the Attesto receipt.
Expose diagnostics without leaking provider secrets or raw private payloads.

Connector family	Tenant management route	Ingress route	Notes
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`	Creation may reveal the connector secret once. Store it server-side only.
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 are validated before normalized repository evidence is written.
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`	Uses tenant session to commit object metadata and integrity evidence; object bytes stay in the source store.

Every connector event must preserve the source system id, source object id, source event type, source timestamp with timezone or UTC offset, connector received time, idempotency/source reference, and normalized payload commitment. If a provider cannot produce a timezone-aware source timestamp, the connector must fail validation instead of inventing one.

Signed webhook connector

Use the signed webhook connector when an external source can POST a signed JSON body to Attesto. The source reference is the idempotency key inside the stream. The dashboard creates and revokes connector records through /v2/tenant/connectors/signed-webhooks; the source system sends events only to the 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

The GitHub connector validates X-Hub-Signature-256 over the raw provider body and commits normalized repository-change metadata to the configured 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

The GitLab connector validates the configured signing token over the raw provider delivery. Existing installations can keep their legacy token mode until rotated.

{
  "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 when evidence already lives in AWS S3, Cloudflare R2, or an S3-compatible store. Attesto performs a real HeadObject call, receipts object identity and integrity metadata, and does not proxy 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 should include only metadata that is safe to store as evidence. Object content remains in the customer object store. Use read-only credentials scoped to the required bucket prefix, and commit versioned object metadata whenever the store supports object versions.

Marketplace distribution

Validated first-party connector manifests are available through https://marketplace.attesto.eu. Public visitors can browse the catalog. Downloading a manifest, acquiring an entitlement, or creating an installation requires an Attesto tenant session. The marketplace and connector kits use the same attesto.connector.v2 manifest validation rules.

The first free Attesto first-party listings are Signed Webhook Evidence, GitHub Repository Evidence, GitLab Repository Evidence, and S3/R2 Object Commitment. Each listing binds its marketplace validation result to a connector-assurance canary guarantee, so Evidence Score and Verified badges are reproducible release evidence rather than marketing labels.

Connector diagnostics

Tenant-visible diagnostics show whether a connector is enabled, recently used, failing auth, failing replay checks, or revoked. They do not reveal connector credentials, raw provider payloads, or private object content.

Status	Meaning
`healthy`	Recent signed delivery or source check succeeded.
`auth_failed`	Provider or HMAC signature did not verify.
`replay_conflict`	The same source reference was replayed with different content.
`revoked`	Ingress is disabled and should fail closed.

Safety boundaries

Connector endpoints reject replay conflicts.
Revoked connectors return not found on ingress.
Outbound URLs must be HTTPS and publicly routable.
S3-compatible connector credentials should be read-only and scoped to the required bucket prefix.
Do not put raw object content, private material, or customer secrets in connector metadata.