95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
# 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`
|