Live proof

Live proof is optional. It mints a short-lived token for one disposable repository, verifies the token's effective scope, reruns one accepted scenario, and executes applicable negative controls.

What it verifies

1. The exact tool, API, and catalog identity match, and every accepted route DNF rebinds to the current pinned catalog before credentials are loaded.
2. The accepted schema-v3 contract contains the named scenario.
3. Requested permissions equal that scenario's selected permissions plus all manual keeps.
4. Effective permissions equal the request plus mandatory metadata:read.
5. The token covers exactly one expected repository and has a fresh, approximately one-hour expiry.
6. The recorded child reproduces the accepted scenario slice exactly.
7. Applicable safe negative controls reject access as expected.
8. Cleanup completes.

Production proof has no broad-token discovery or feasibility path. It mints only the restricted positive token and applicable restricted negative-control tokens after contract/catalog validation succeeds.

When the accepted contract uses an explicitly selected frontier candidate, the scenario projection follows the compatible branch of that candidate. Live proof therefore requests the committed policy choice, not the default branch.

Setup

Follow the live-proof setup to create the disposable installation and configure nonsecret selectors plus exactly one private-key provider.

GrantTrace does not load .env files itself. Export or inject the documented variables through your shell, secret manager, or CI runner.

Run one scenario

GrantTrace injects its recorder into the restricted Node child, so standard global-fetch and Octokit traffic needs no source edit. A custom fetch implementation, transport, or runtime needs the explicit fallback.

npx granttrace doctor
npx granttrace prove issue-triage -- \
  npm test -- issue-triage

Proof defaults to 15 minutes and accepts --timeout values from one second through 30 minutes using ms, s, or m. A terminal interrupt remains an interrupt even if the child handles the signal and exits zero; descendants are terminated after a bounded grace period where the platform supports process groups.

After the accepted-contract preflight succeeds, proof execution writes an identity-free local report to .granttrace/reports/<scenario>.json. Do not commit or upload .granttrace/. The write-only report artifact uses schema v3 and requires the derived proofStrength field; GrantTrace does not claim a compatibility reader for older reports.

The report's sourceCommit is HEAD only when Git reports a clean index and worktree. It is null when tracked files, staged files, or untracked files are present, when the source is not in a Git checkout, or when Git is unavailable. This prevents modified code from being attributed to the last commit.

Read the proof strength

The CLI and report state one derived proof-strength value:

Coverage is computed over scenario-selected permission names. Manual keeps and GitHub's mandatory baseline are never counted as tested necessity. A level of necessity_tested describes only the named scenario and the built-in controls that were applicable; it does not widen the scenario or control coverage. These values test removal of permission names. They do not prove that a selected write level is minimal relative to read; the current controls do not perform access-level downgrades.

Understand failures

Authentication, authorization, rate limiting, token expiry, hidden resources, GitHub outages, child-test failure, timeout, negative-control failure, and cleanup failure remain separate classifications. A generic nonzero child exit is never interpreted as evidence that a permission is missing.

See security and privacy for the trust boundary and limitations for current negative-control coverage.