# MVG Org Approval Keyring Spec (Public-safe) — v1.0.0

This document defines a **portable, offline-friendly** JSON format for an organization to publish:
- the set of **approved internal reviewer signing keys** (public keys only), and
- an **approval policy** such as **“2-of-3 security reviewers must countersign”**.

It is designed to be evaluated locally by MVG’s offline verifiers (no network calls).

## Threat model (what this is / is not)
- **This is not an identity system.** Your org is responsible for binding keys to humans/devices (MDM/PKI/KMS/HSM).
- The verifier treats the keyring as an **org-supplied policy input** (e.g., from a controlled internal repo).
- Optional hardening (future): DSSE-signed keyring snapshots + key transparency for org keys.

## File format

### Top-level
- `schema_id` (string, required): `mvg.org_approval_keyring@1`
- `keyring_id` (string, required): stable identifier
- `keyring_version` (string, required): semantic version
- `generated_utc` (ISO 8601, required)
- `organization` (object, optional): metadata
- `policy` (object, required): approval policy
- `keys` (array, required): approved reviewer keys (public)

### policy
- `policy_id` (string, required)
- `threshold` (int, required): e.g., `2`
- `allowed_roles` (array of strings, required): e.g., `["security_reviewer"]`
- `require_distinct_signers` (bool, recommended): distinct key fingerprints only
- `require_ticket_binding` (bool, optional): if true, counted signers must bind the same ticket
- `allowed_ticket_systems` (array, optional)

### keys[]
Each entry:
- `kid` (string, required): org-internal key id
- `role` (string, required): e.g., `security_reviewer`
- `status` (string, required): `active` | `revoked`
- `valid_from_utc` / `valid_to_utc` (optional): validity window
- `public_key_jwk` (object, required): EC P-256 public JWK (x/y)
- `public_key_fingerprint_sha256` (string, required): `sha256:<hex>` of canonical JWK (crv,kty,x,y)

## Policy evaluation (offline verifier)
Given a **Countersigned Verification Receipt**:
1. Verify each countersignature cryptographically.
2. For each valid countersignature:
   - extract `public_key_fingerprint_sha256`
   - match against `keys[]` in this keyring
   - ensure role/status/validity are acceptable
3. Count **distinct** matched fingerprints.
4. PASS if `count >= threshold` and (if required) **ticket binding** is consistent across counted signers.

## Example file
See: `MVG_Org_Approval_Keyring_SAMPLE_v1.0.0.json`

