contexa-core contexa-iam

Sealed Evidence and Official Verification

How to look again, later, at exactly which prompt and facts a decision was made from. It covers what is sealed and when, how to confirm nothing changed, how to view evidence in the admin console and run official verification and replay, and retention and settings.

At a glance

When the AI model makes a decision, Contexa seals the prompt exactly as sent to the model, its ingredients (request facts, canonical context, behavioral baseline, past decision records) and the decision result into one package with a hash and a signature. This package is the sealed evidence. Sealing never changes the decision and is stored separately after the decision is done.

The life of sealed evidenceSealing and storing are automatic, inspection runs periodically, and official verification and replay run when an administrator asks.
  1. Capture the promptWhen the decision prompt is built, the text the model will get and its original are kept
  2. SealAfter the decision, seven sections become one package with a SHA-256 hash. With a signing key it is signed with HMAC-SHA256 and chained to the previous package's hash
  3. StoreInserted (never updated) into the ctxa_sealed_evidence_package table of the Contexa database (kept 90 days by default)

What the stored packages are used for

  • Automatic inspectionNew packages compared with facts every 30 s
  • Official verificationRule evaluation with 12 metrics (no model call)
  • ReplayAsk the model again from the sealed inputs

What is sealed

One package holds seven sections.

The seven sections of a sealed packageThe prompt is kept both as the uncompressed original and as the text the model actually received, each with its hash.
1Request factsWho did what to which resource
2Authentication stateLogin method, MFA and so on
3Canonical contextEvery fact the decision used (JSON)
4Behavioral baseline summaryA summary of usual behavior
5Past decision record searchSummaries and relevance of the records found
6PromptOriginal, text the model got, each hash, run information
7DecisionAction, risk score, reason codes, hypotheses, model output, retries

Run information longer than 512 characters is kept as its length and hash only.

When it is sealed

  • Only decisions made by the AI model are sealed. A decision made without a model call has no prompt the model received, so nothing is sealed.
  • Requests without a user ID, failed processing and the paths /actuator · /health · /.well-known/ · /sse/ are not sealed.
  • Sampling: the first 1,000 decisions after a server starts are all sealed, otherwise 1% (contexa.pqa.oss.sealed-evidence.full-capture-after-change, sample-percent). When the version decisions run changes (the label moved, a rollback, the setting), the next 1,000 are all sealed as well. A version is told by its name and content hash. A version a canary or a shadow runs has a window of its own: all of its first 1,000 decisions sealed from the first one the server seals, without opening the window of the version in use again. Each server (node) counts on its own.
  • Sealing sits after enforcement (55) and before audit (60) in the decision steps (56), but the package is assembled and stored on a separate thread. If that thread falls behind, the overflowing packages are dropped and the decision is not affected.
  • A captured prompt waits at most 10 minutes (snapshot-ttl) for the decision to finish and be sealed.

Confirming nothing changed

The package hash is SHA-256 over the seven sections, the prompt hashes, the schema number and more. With a signing key the package is schema 3: the tenant, the user, the sealing time and the previous package's hash are also hashed, and the hash is signed with HMAC-SHA256.

ResultMeaning
VERIFIEDThe recomputed hash matches and, for schema 3, so does the signature.
MISMATCHThe recomputed hash differs: the content changed after it was stored. A previous package that is gone without the retention explaining it (LINK_BROKEN) also belongs here.
UNVERIFIABLEThe hash or a prompt hash is empty, or no key can check the signature.

The SEAL_INTEGRITY check of the automatic inspection and official verification perform this check.

Adding signing keys

contexa:
  security:
    evidence:
      signing:
        keys:
          k2026: ${CONTEXA_EVIDENCE_KEY}   # Base64, at least 32 bytes
        active-key-id: k2026               # required with two or more keys
  • Without a key, a temporary key is made at startup and a WARN is logged. Signatures made with it cannot be checked after a restart (UNVERIFIABLE).
  • When you rotate keys, keep the retired key in the list so old signatures can still be checked. With two or more keys and no active-key-id, or one not in the list, the application does not start.
  • The decision audit records (ctxa_audit_log) are chained and signed by the same signer, and the security event log of the admin console shows the result for each record. The result for sealed packages is shown on the inspection and official verification screens, not on the security event log.
  • A sealed package holds the previous package's hash, and when one package is checked its previous package is looked for: if it is gone and the retention does not explain it, the result is MISMATCH (LINK_BROKEN). Nothing walks the whole chain.

Viewing evidence in the admin console

Use the admin console (administrator role).

Screen · APIWhat it does
Menu "Official Inspection"
/contexa/admin/prompt-quality/runtime-evidence
Search sealed packages and open one.
GET /contexa/admin/api/prompt-quality/runtime-evidence/searchPackage search (packageId, tenantId, userId, resourceUrl, resourceId, httpMethod, from, to, page, size)
GET /contexa/admin/api/prompt-quality/runtime-evidence/{packageId}One package (summary, whether the prompt was captured, preview, sealed content)
Menu "Sealed Prompts"
/contexa/admin/prompt-inspection/packages/{packageId}
One package with its inspection result. It has a "Replay with a version" section.

Official verification

Official verification takes one sealed package and evaluates, with 12 metrics, whether that decision's prompt carried what the judgment needed. The evaluation uses rules and does not call the AI model. It first checks the package's integrity, then redraws the context sections of the prompt from the sealed canonical context and compares them with the sealed original (deterministic replay).

MetricWhat it checks
EIRDo the user, authentication, authority, resource and action of the request link into one security event?
CCRCan the information the judgment needs be told apart from what is missing?
CCSRDo values with the same meaning in the input never conflict?
PFRDoes the input carry every material needed to detect an attack?
MTRCan the input record, hashes and contract version be traced?
CORDo RAG and outside context stay out of the instructions and out-of-scope grounds?
RAPIs RAG evidence used only within the authorized scope and placed safely?
RPIDoes reverification or earlier-round information never contaminate the current judgment?
BMACan the judgment know the baseline's trust level and limits?
USNSCan subtle signals that differ from the user's baseline be seen?
BSRCan the session flow and behavior change be judged as a normal exception or an attack sign?
PREIs the target an actual protected resource?

Running official verification

APIWhat it does
POST /contexa/admin/api/prompt-quality/verification/runtime-runs?packageId=...Starts official verification.
GET .../verification/runtime-runs/package/{packageId}/execution-statusProgress
GET .../verification/runtime-runs/package/{packageId}Result (sub-paths such as /summary and /failure-details)
POST .../verification/runtime-runs/package/{packageId}/reverifyVerify again

When a package's verification makes no progress for 15 minutes, the next request marks that run as failed so it can run again (contexa.pqa.official-verification.stale-execution-timeout).

Replay: asking again from the sealed inputs

Replay asks the same decision again from the sealed inputs (request facts, authentication state, baseline summary, past records, canonical context). To compare a new prompt version with the version in use on recent decisions before using it, use the trial decisions of the version screens (Trial decisions).

  • On the "Sealed Prompts" detail screen, choose the version and Layer 2 models under "Replay with a version" and confirm. The list offers the versions of the security decision that are not hidden, newest first.
  • API: POST /contexa/admin/api/sealed-decisions/{requestId}/replay or POST /contexa/admin/api/sealed-decisions/packages/{packageId}/replay, body {"bundleVersion", "secondPassModels", "userBaseline", "organizationBaseline"}, at most 3 Layer 2 models. The {requestId} in the path is the request (correlation) ID of the sealed decision. The names a replay accepts: GET /contexa/admin/api/sealed-decisions/replay-bundles.
  • Layer 1 is asked once; if it answers ESCALATE, Layer 2 is asked for each chosen model. If Layer 1 could not read past records, Layer 2 is not asked.
  • The AI model is really called, so it costs money. The result is not applied, learned or sealed; only the audit record SEALED_DECISION_REPLAYED is written. The time limit is 3 minutes.
  • No sealed decision for that request ID or package gives 404; a name the list does not hold, or a bad request, gives 400; no decision pipeline gives 503.

Retention

  • A package expires 90 days after sealing (contexa.pqa.oss.sealed-evidence.retention.period) and is deleted every day at 03:30.
  • A package whose last inspection result is PASS or NOT_APPLICABLE and that no official verification used is deleted after 30 days (retention.clean-period).

Settings

SettingDefaultMeaningWhen to change
contexa.security.evidence.signing.keysnone (temporary key + WARN log)Key ID → Base64 secret (at least 32 bytes)Always in production (temporary-key signatures cannot be checked after a restart)
contexa.security.evidence.signing.active-key-idnone (the only key, if one)The key for new signaturesWhen rotating keys
contexa.pqa.oss.sealed-evidence.capture-enabledtrueTurns sealing onTo turn sealing off
contexa.pqa.oss.sealed-evidence.sample-percent1Usual sealing rate (1–100)To seal more or less (trades storage)
contexa.pqa.oss.sealed-evidence.full-capture-after-change1000Decisions all sealed after a server starts and after the version decisions run changes (per node). A canary or shadow version has a window of its ownTo see more or fewer decisions after a start or a version change
contexa.pqa.oss.sealed-evidence.snapshot-ttl10mHow long a captured prompt waits to be sealedWhen decisions take over 10 minutes
contexa.pqa.oss.sealed-evidence.max-pending-snapshots
contexa.pqa.oss.sealed-evidence.max-completed-snapshots
1000 / 1000Upper limit of captures held in memoryWhen captures are dropped under load
contexa.pqa.oss.sealed-evidence.retention.enabledtrueTurns retention deletes onfalse to keep everything
contexa.pqa.oss.sealed-evidence.retention.period90dRetentionWhen your retention policy differs
contexa.pqa.oss.sealed-evidence.retention.clean-period30dRetention of packages without problemsWhen your retention policy differs
contexa.pqa.oss.sealed-evidence.retention.cleanup-cron0 30 3 * * *When deletes runTo move the cleanup time
contexa.pqa.official-verification.stale-execution-timeout15mWhen a stalled official verification may run againWhen official verification runs long

When it is on, and extension points

  • Sealing is on by default when contexa-iam is on the classpath and the Contexa database (contexa.datasource.*) is connected.
  • To sign another way (a key management service, an HSM and so on), declare an EvidenceSigner bean. Decision audit records and sealed packages both use that signer.
  • To keep packages elsewhere, declare a SealedEvidencePackageRepository bean; to choose yourself which packages to seal, declare a SealedEvidenceCaptureSampling bean.

The automatic inspection that compares sealed prompts with facts is described in Prompt Inspection and Replay.