Skip to content

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

@MuttleyD

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions