stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
6eb6d5e356c4285d041fb1dee4e0ff18d0df6b8f
git.stella-ops.org/docs/modules/attestor/predicate-schema-registry.md
master 04cacdca8a Gaps fill up, fixes, ui restructuring
2026-02-19 22:10:54 +02:00

4.2 KiB
Raw Blame History

Predicate Schema Registry

Status

  • Status: DRAFT (2026-02-19)
  • Owner: Attestor Guild
  • Sprint: SPRINT_20260219_010

Purpose

Replace hardcoded predicate type URIs scattered across the codebase with a discoverable, versioned, PostgreSQL-backed registry. External tooling (cosign, policy-as-code engines, audit exporters) can query the registry to discover and validate predicate schemas.

Design

Storage

  • Schema: proofchain (alongside existing proof chain tables)
  • Table: proofchain.predicate_type_registry

Data Model

Each registry entry:

Column Type Description
registry_id UUID Primary key
predicate_type_uri TEXT UNIQUE The canonical predicate type URI
display_name TEXT Human-readable name
version TEXT Semver string (e.g., "1.0.0")
category TEXT Category: stella-core, stella-proof, ecosystem, intoto
json_schema JSONB JSON Schema document for payload validation (nullable)
description TEXT Purpose description
is_active BOOLEAN Whether this type accepts new submissions
validation_mode TEXT log-only / warn / reject (default: log-only)
created_at TIMESTAMPTZ Created timestamp
updated_at TIMESTAMPTZ Last update timestamp

Immutability Rule

Once a (predicate_type_uri, version) pair is published, its json_schema MUST NOT change. New versions get new semver.

API Endpoints

  • GET /api/v1/attestor/predicates — List all registered predicate types (paged, filterable by category and is_active)
  • GET /api/v1/attestor/predicates/{uri} — Get schema and metadata for a specific predicate type URI (URI is URL-encoded)
  • POST /api/v1/attestor/predicates — Register a new predicate type (admin-only, OpTok-gated with attestor:admin scope)

Submission Validation

When a DSSE envelope is submitted via POST /api/v1/rekor/entries:

  1. Look up predicate_type in registry
  2. If found and validation_mode = "log-only": validate payload against json_schema, log result (pass/mismatch), proceed
  3. If found and validation_mode = "warn": validate, emit warning metric, proceed
  4. If found and validation_mode = "reject": validate, reject on mismatch (400 Bad Request)
  5. If not found: log unknown predicate type, proceed (don't block unregistered types during rollout)

Seeded Predicate Types (from codebase analysis)

stella-core (Attestor native):

  1. https://stella-ops.org/predicates/sbom-linkage/v1
  2. https://stella-ops.org/predicates/vex-verdict/v1
  3. https://stella-ops.org/predicates/evidence/v1
  4. https://stella-ops.org/predicates/reasoning/v1
  5. https://stella-ops.org/predicates/proof-spine/v1
  6. https://stella-ops.org/predicates/reachability-drift/v1
  7. https://stella-ops.org/predicates/reachability-subgraph/v1
  8. https://stella-ops.org/predicates/delta-verdict/v1
  9. https://stella-ops.org/predicates/policy-decision/v1
  10. https://stella-ops.org/predicates/unknowns-budget/v1
  11. https://stella-ops.org/predicates/ai-code-guard/v1
  12. https://stella-ops.org/predicates/fix-chain/v1
  13. https://stella-ops.org/attestation/graph-root/v1

stella-proof (ProofChain predicates): 14. https://stella.ops/predicates/path-witness/v1 15. https://stella.ops/predicates/runtime-witness/v1 16. https://stella.ops/predicates/policy-decision@v2 17. https://stellaops.dev/predicates/binary-micro-witness@v1 18. https://stellaops.dev/predicates/binary-fingerprint-evidence@v1 19. https://stellaops.io/attestation/budget-check/v1 20. https://stellaops.dev/attestation/vex/v1 21. https://stellaops.dev/attestations/vex-override/v1 22. https://stellaops.dev/predicates/trust-verdict@v1 23. https://stellaops.io/attestation/v1/signed-exception 24. https://stellaops.dev/attestation/verification-report/v1

stella-delta (Delta predicates): 25. stella.ops/changetrace@v1 26. stella.ops/vex-delta@v1 27. stella.ops/sbom-delta@v1 28. stella.ops/verdict-delta@v1 29. stellaops.binarydiff.v1

ecosystem (Standard predicates): 30. https://spdx.dev/Document 31. https://cyclonedx.org/bom 32. https://slsa.dev/provenance

intoto (In-Toto standard): 33. https://in-toto.io/Statement/v1 34. https://in-toto.io/Link/v1 35. https://in-toto.io/Layout/v1