Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

GET /api/v1/decisions/:id/provenance — admin-gated.

​
Response

// X-Provenance-Schema: kaireon.provenance.v1
// X-Provenance-Digest: <sha256 hex>
// X-Provenance-Signature: <base64 | "unsigned">
{
  "schemaVersion": "kaireon.provenance.v1",
  "generatedAt": "...",
  "decisionTrace": { /* PII-redacted DecisionTrace */ },
  "modelSnapshots": [
    { "modelId": "...", "modelType": "gradient_boosted", "modelStateHashSha256": "..." }
  ],
  "effectiveRulesByOffer": {
    "OFFER_X": { /* lib/effective-rules.ts result with explainCascade trace */ }
  },
  "auditLog": [
    { "id": "...", "action": "...", "prevHash": "...", "integrityHash": "...", "timestamp": "..." }
  ],
  "buildIdentity": {
    "gitSha": "...",
    "gitRepo": "...",
    "imageName": "...",
    "imageDigest": "...",
    "sbomDigestSha256": "...",
    "slsaAttestation": { /* in-toto v1 statement when env vars set */ }
  },
  "fairnessSlice": { /* latest fairness_evaluate / fairness_report row */ }
}

​
Why a separate endpoint

The bundle is a point-in-time snapshot of every artifact a regulator or auditor needs to reconstruct one decision: the trace itself, the model versions referenced, the rule cascade that produced the candidate set, the audit chain, the build identity (so they can verify the code that ran), and the fairness slice in effect at the time. Returning these via the existing /decision-traces/:id route would either bloat the trace endpoint or require N+1 fetches. The bundle endpoint runs all the joins server-side and emits a stable, hash-friendly document.

​
Reproducible digest

Output is canonicalized — JSON with sorted object keys — so the X-Provenance-Digest is deterministic. The same trace re-emitted from any pod produces the same digest. Verifiers can re-fetch the bundle days later and confirm bit-identity.

​
Sigstore signing

When COSIGN_KEY is set in the environment, the bundle is signed via cosign and the signature lands in X-Provenance-Signature. V1 ships a deterministic placeholder (a hash-of-hash) so unit tests can verify “signature was emitted” without requiring cosign in CI. Production deployments must replace the placeholder with a real cosign invocation gated on COSIGN_KEY. The header value "unsigned" indicates the bundle was generated in a deployment that did not have COSIGN_KEY set — consumers can use this signal to refuse unsigned bundles in compliance workflows.

​
Build identity inputs

The route reads these env vars and includes them in buildIdentity:
EnvDefault if unsetPurpose
GIT_SHAnullCommit SHA the running pod was built from
GIT_REPOnullRepository URL
IMAGE_NAMEnullOCI image reference
IMAGE_DIGESTnullOCI image digest (sha256:…)
SBOM_DIGEST_SHA256nullSBOM hex digest from W3 release pipeline
BUILDER_IDkaireon.platform.runtimeSLSA builder.id
BUILDER_VERSIONunknownSLSA builder.version
BUILD_STARTED_ON / BUILD_FINISHED_ONnow()SLSA buildStartedOn/Finished
GITHUB_RUN_IDtrace idSLSA invocationId
When all of GIT_SHA / GIT_REPO / IMAGE_NAME / IMAGE_DIGEST are set, buildIdentity.slsaAttestation is populated via buildSlsaProvenance() from lib/supply-chain/cosign-metadata.ts.

​
Audit trail

Every bundle emission writes one AuditLog row with action: "decision_provenance_emit", entityId: <traceId>, and changes: { digestSha256, signed, modelCount, auditLogCount }. DSAR exports cite these rows.

​
Honest limits

  • Bundle includes per-modelType snapshots (the hash of each modelState), not the full state. Auditors who need bit-exact model reproduction request the model record separately via the registry endpoint.
  • The signing path is currently a placeholder — see “Sigstore signing” above.
  • Effective-rules cascade is computed at bundle-emission time, not at decision time. Rule edits between the decision and the bundle request will surface in the cascade trace; the trace itself records what rules fired at decision time via qualificationResults / contactPolicyResults.
  • PII redaction runs over the trace before signing. The redactor is lib/explanations/pii-redact.ts; bugs there could leak PII into provenance bundles. Treat unsigned bundles as untrusted.