git.stella-ops.org/docs/modules/excititor/attestation-plan.md

Excititor Attestation Plan (Sprint 110)

Goals

• Align Excititor chunk API and attestation envelopes with Evidence Locker contract.
• Provide offline-ready chunk submission/attestation flow for VEX evidence.

Chunk API shape (/vex/evidence/chunks)

• POST body (NDJSON, deterministic order by chunk_id):

  {
    "chunk_id": "uuid",
    "tenant": "acme",
    "source": "ghsa",
    "schema": "stellaops.vex.chunk.v1",
    "items": [ {"advisory_id":"GHSA-123","status":"affected","purl":"pkg:npm/foo@1.0.0"} ],
    "provenance": {"fetched_at":"2025-11-20T00:00:00Z","artifact_sha":"abc"}
  }
  

• At submission, Excititor returns chunk_digest (sha256 of canonical JSON) and queue id.

Attestation envelope

• Subject: chunk_digest from above.
• Predicates attached:
  • stellaops.vex.chunk.meta.v1 (tenant, source, schema version, item count).
  • stellaops.vex.chunk.integrity.v1 (sha256 per item block, canonical order).
  • Optional stellaops.transparency.v1 (Rekor UUID/logIndex) when online.
• Envelope format: DSSE using Evidence Locker provider registry; signing profile mirrors Evidence Locker bundle profile for tenant.

DSSE bundling rules

• Deterministic JSON (sorted keys) before hashing.
• Canonical NDJSON for chunk payload; no gzip inside envelope.
• Attach verification report alongside attestation as chunk-verify.json (hashes + signature check results).

Sample payloads

• docs/modules/excititor/samples/chunk-sample.ndjson
• docs/modules/excititor/samples/chunk-attestation-sample.json

Integration points

• Evidence Locker contract v1 (see docs/modules/evidence-locker/attestation-contract.md).
• Concelier LNM schemas (observations remain aggregation-only; attestation is evidence, not merge).

Ownership

• Excititor Guild (primary); Evidence Locker Guild reviewer.