Aggregation-Only Contract (AOC) Invariants

Scope. The Aggregation-Only Contract is the rule that Stella Ops ingestion and verification services aggregate, validate, and verify evidence without ever making severity or policy decisions. This page is the authoritative checklist of the invariants every AOC-bound component must uphold, plus the Attestor-specific verification contract. It is written for implementers of ingestion/verification surfaces and for auditors verifying that those guarantees hold.

Audience & related reading. Start from the security index. The raw-ingestion guard (aoc:verify) lives on Concelier/Excititor; the verification report contract lives in the Attestor module dossier (../modules/attestor/architecture.md).

Last updated: 2026-05-30 (reconciled against src/Attestor).

Core invariants (all components)

• Tenant isolation: API calls carry the platform tenant header X-StellaOps-TenantId; storage and caches are keyed by tenant. In the Attestor WebService the value is resolved via StellaOpsTenantResolver.ResolveTenantIdOrDefault(httpContext) (it falls back to the default tenant when the header is absent rather than hard-rejecting). The verdict-ledger endpoints (Endpoints/VerdictEndpoints.cs) currently read a placeholder X-Tenant-Id header — see the audit-checklist note below.
• Append-only inputs: Evidence, advisories, and attestations are stored immutably; no in-place edits.
• Determinism: Sorting and pagination are stable; timestamps are UTC ISO-8601; hashes are lowercase hex.
• No consensus: Components enforce validation/verification only; no severity or policy decisions inside AOC services.
• Offline-first: External data (feeds, keys, checkpoints) is supplied via bundled inputs. Attestor verification can be forced fully offline per request via the Offline flag on AttestorVerificationRequest (StellaOps.Attestor.Core.Verification.AttestorVerificationRequest), which suppresses external transparency-log calls and surfaces issues for missing proofs instead. There is no Attestor__Offline__Enabled global config switch in the current code (see “Pending / not-yet-implemented” below).
• AOC ingestion scope: The aoc:verify scope (StellaOpsScopes.AocVerify) guards the ingestion-guard verification path on the raw-ingestion services (Concelier /aoc/verify, Excititor) and the CLI stella aoc verify command — not the Attestor service. The Attestor WebService authorizes its own endpoints with the attestor.verify / attestor.read / attestor.write scope strings (see Attestor-specific invariants).

Attestor-specific invariants

• Trust roots: Verification keys/anchors come from configured local material — Security.SignerIdentity.FulcioRoots, AllowedSans, and KmsKeys in AttestorOptions (StellaOps.Attestor.Core.Options.AttestorOptions). Keyless chains are built with X509ChainTrustMode.CustomRootTrust and X509RevocationMode.NoCheck against the configured Fulcio roots; no network key discovery is performed by AttestorVerificationEngine.
• DSSE only: Bundles are DSSE envelopes (bundle.Dsse with PayloadType, PayloadBase64, and inline Signatures). The engine reconstructs the DSSE PAE (DSSEv1 ...) and verifies each signature; payloads that fail base64 decoding raise the bundle_payload_invalid_base64 issue and the signature section fails. (Detached-payload references exist as a distinct envelope feature — StellaOps.Attestor.Envelope.DsseDetachedPayloadReference — and are not part of the inline verification path.)
• Signature modes: Verification dispatches on signer mode. kms verifies HMAC (HS256/HS384/HS512 via CryptoInterop) against Security.SignerIdentity.KmsKeys; unsupported algs fail closed with signature_alg_unsupported:<alg> (the regional HSGost3411/HSSm3 ids are explicitly rejected here). keyless verifies the leaf certificate (ECDSA/RSA over the PAE) and validates the chain/SAN. Unknown modes emit signer_mode_unknown / signer_mode_unsupported:<mode>.
• Transparency, gated by config: Inclusion proof, checkpoint, and witness endorsement are evaluated by EvaluateTransparency. Whether a missing proof/checkpoint/witness fails the request depends on Verification.RequireTransparencyInclusion (default true), Verification.RequireCheckpoint (default true), and Verification.RequireWitnessEndorsement (default false); when not required, the gap downgrades the section to Warn instead of Fail. Issue codes include proof_missing, proof_inclusion_missing, checkpoint_missing, proof_root_mismatch, witness_missing, and witness_root_mismatch. There is no transparency=skipped scalar output field; the transparency section carries a VerificationSectionStatus (Pass / Warn / Fail / Skipped) plus a WitnessStatus string.
• Structured report (not a free-form rationale): Each verification produces a VerificationReport (StellaOps.Attestor.Core.Verification.VerificationReport) with five sections — Policy, Issuer, Freshness, Signatures, Transparency — each exposing a VerificationSectionStatus and a typed Issues list of stable diagnostic codes (e.g. signature_invalid, bundle_hash_mismatch, freshness_stale, policy_blocked:<component>). OverallStatus is the max-severity roll-up (any Fail ⇒ Fail; any Warn ⇒ Warn; all Skipped ⇒ Skipped). There is no field literally named rationale[], and the tokens key.match / transparency.included / transparency.skipped do not exist in code — replays should key off the section statuses and issue codes above.
• Immutability: Verified entries and audit rows are recorded append-only; retries must not overwrite prior entries.

Guardrails for implementers

• Never permit unsigned or partially signed payloads to proceed past parsing. MinimumSignatures (default 1, Verification.MinimumSignatures) gates the signature section; total == 0 fails closed.
• When a request sets Offline, do not attempt outbound transparency-log calls — surface a missing-proof issue instead.
• Keep secret material out of logs; log statement digests and key ids only. KMS key comparisons use CryptographicOperations.FixedTimeEquals.
• Round numeric scores/weights only at the presentation boundary; internal math stays high-precision.

Pending / not-yet-implemented (forward-looking — verify before relying on these)

• Attestor__Offline__Enabled / Attestor__TrustBundlePath / Attestor__Verification__DisableHttpFetch / Attestor__Transparency__CheckpointPath are NOT implemented. These env keys appear only in docs/modules/attestor/airgap.md, not in AttestorOptions. The implemented offline control is the per-request AttestorVerificationRequest.Offline boolean; trust material is configured under Security.SignerIdentity.* and Rekor endpoints under Rekor.* / TrustRepo.*.
• Risk-scoring provenance guarantees (DOCS-RISK-68-002) are still pending once Export/Risk inputs land. Include a deterministic hash list for any new examples or schemas. (The original 2025-12-11 sprint due date is stale; treat as roadmap.)

Audit checklist

• [ ] Tenant resolution is correct per request. NOTE: Attestor main endpoints use ResolveTenantIdOrDefault (default-tenant fallback, not a hard reject) and VerdictEndpoints reads a placeholder X-Tenant-Id; a missing X-StellaOps-TenantId does not currently 4xx in the Attestor service.
• [ ] Configured trust material (FulcioRoots, AllowedSans, KmsKeys) is present and current on disk.
• [ ] Transparency section status + issue codes are captured per request (inclusion, checkpoint, witness).
• [ ] Verification entries and audit rows are append-only and carry section statuses + trace ids.