docs: add VSA verification security model documentation

[ralphbean]

Summary

I got confused when trying to figure out why verifycommit didn't have a --use_local_policy option while checktag, level, and leveprov did. Here, trying to expand documentation on the security model to explain that.

New Documentation: docs/VERIFICATION.md

This document explains:

• Policy Binding Principle: VSAs are cryptographically signed claims bound to specific policies
• Creation vs Verification: Different trust models for commands that create vs verify attestations
• Security Anti-Pattern: Why allowing policy override in verifycommit would enable policy substitution attacks
• Consumer Guidelines: What consumers should verify when evaluating VSAs
• Policy Evolution: How to handle policy changes and migrations safely

Why This Matters

Currently, the tool's security model is implicit in the code design:

• Creation commands (checktag, checklevel, checklevelprov) have --use_local_policy
• Verification command (verifycommit) intentionally lacks this flag

This PR documents the security reasoning behind this design, making it clear that:

1. Creation commands let you specify which policy you're claiming compliance with
2. Verification commands validate existing claims against the policy referenced in the VSA
3. Allowing policy override in verification would defeat the purpose of attestations

Changes

• New: docs/VERIFICATION.md - Comprehensive verification security model documentation
• Updated: docs/DESIGN.md - Added reference to verification security model in VSA section
• Updated: README.md - Added link to verification documentation

Related Issues

• verifycommit command doesn't actually check the VSA #148 - Improve VSA verification implementation

---

Generated with assistance from Claude Code

[TomHennen]

Hey, thanks for taking an interest in this project.

The suggested change doesn't match the official model for how VSAs are verified though.

Notably, users are not expected to check policy.uri, and are instead expected to check resourceUri.

You can see some of the details here and also this discussion.

This doc also has a draft threat model that we haven't had time to formalize. You can get access if you join https://groups.google.com/g/slsa-discussion, you can also just request access and I'll grant it.