Skip to content

Add a short guide for validating evidence integrity after an evaluation #69

Description

@MuttleyD

Context

MIDAS records an evidence envelope for every governed evaluation. The control-plane example walkthrough already shows how to run evaluations, but new users may not immediately understand what to do with the returned envelope_id.

A short guide or section explaining how to inspect and verify evidence would help users understand one of the most important MIDAS capabilities.

Scope

Add a concise evidence validation section to docs/examples/control-plane.md.

The section should explain:

  • /v1/evaluate returns an envelope_id;
  • the envelope records the submitted request, resolved authority, outcome, and audit evidence;
  • users can retrieve the decision by request ID/source;
  • users can check the envelope integrity endpoint;
  • valid: true means the stored audit chain matches the envelope integrity metadata;
  • evidence integrity verification does not require application secrets.

Include example commands for:

  • retrieving a decision by request ID/source;
  • checking evidence integrity;
  • retrieving the evidence packet, if already documented.

Acceptance Criteria

  • docs/examples/control-plane.md clearly explains what to do with an envelope_id.
  • The evidence integrity check is easy to find after the evaluation examples.
  • Example commands use the local quickstart tokens and example request IDs.
  • The wording does not overclaim cryptographic guarantees beyond the current implementation.
  • Links to docs/core/envelope-integrity.md where deeper explanation is needed.
  • No runtime behaviour is changed.
  • No real secrets are added.
  • git diff --check passes.

Out of Scope

  • Changing the evidence envelope schema.
  • Changing audit-chain behaviour.
  • Adding new evidence endpoints.
  • Adding automation or scripts.
  • Changing runtime evaluation behaviour.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions