Require Server-signed BLAKE3 grants for Cache ZIP reads

[ScottArbeit]

Pull Request

Linked issue, outcome, and delivery mode

• Closes GC-CAL-05: Require Server-signed BLAKE3 grants for Cache ZIP reads #1035.
• Parent epic: none. This is the first post-Issue Epic: Grace Cache Factory V2 calibration and Product V1 increments #597 Product V1 Cache tracer.
• Outcome: an authenticated CLI user can retrieve the exact Server-approved DirectoryVersionZip through a loopback Grace Cache. Cache validates a Server-signed grant before lookup, and the CLI verifies the signed BLAKE3 value before extraction or Working Directory Update.
• Why this matters for Grace: a Cache hit is no longer an unauthenticated repository-content endpoint, and stale or substituted ZIP bytes cannot satisfy a grant for another artifact generation.
• Delivery mode: independently correct mainline slice to main.

Baseline admissibility

• Base branch and exact SHA: origin/main@10f4ff71a9e4a96ca2902641bae0376dc716f76f.
• Eventual delivery target: main.
• Baseline result: root and issue worktrees were clean, base and origin/main were identical, and no Issue GC-CAL-05: Require Server-signed BLAKE3 grants for Cache ZIP reads #1035 branch or PR existed.
• Semantic merge or rebase conflicts: none.
• Prior lineage: legacy Cache work was source and test salvage only. No legacy branch was merged, rebased, or cherry-picked wholesale.
• Verdict: ADMISSIBLE.

Supported world and quality contract

• Quality contract: Product V1.
• Supported actor and topology: one authenticated Grace CLI user, one Grace Server, and one loopback Grace Cache through configured GRACE_SERVER_URI, using the existing Linux x64 Cache-required Connect path.
• Supported producer: authenticated grace connect for one immutable DirectoryVersionZip.
• Non-goals preserved: Direct fallback, CachePreferred, Cache status or persisted configuration, FileVersion or ContentBlock retrieval, non-loopback Cache, durable or rotating signing keys, replay tracking, retirement delivery, prefetch, Watch, HA/DR, and generalized recovery.

Primary invariant and algorithm readiness

• Invariant: Cache checks for or serves a ZIP only after locally validating a Server-signed grant for the exact repository ID, directory-version ID, and BLAKE3 value. The CLI accepts the ZIP only after recomputing the same BLAKE3 value.
• Server decision source: current authenticated repository access plus the confirmed Blob ZIP metadata.
• Cache decision source: the configured Server public validation key, the signed grant, and the exact local artifact generation.
• Local completion point: the existing SQLite Complete transaction after verified final-file publication.
• Algorithm prototype: 29/29 deterministic checks passed before production edits and are recorded in the Issue GC-CAL-05: Require Server-signed BLAKE3 grants for Cache ZIP reads #1035 prototype comment.

Scope and contract propagation

• Added typed artifact, grant, public P-256 JWK, validation-key, and preparation contracts.
• Added one process-lifetime Server ES256 signer and a public validation-key route.
• Prepared and signed the exact BLAKE3-bound ZIP before the first Cache GET.
• Required Bearer grant admission before Cache lookup, with local known-key validation and one refresh for an unknown key ID.
• Changed Cache storage identity and reopen checks to repository ID, directory-version ID, and BLAKE3.
• Kept the read grant and fill permit separate and non-substitutable.
• Verified the whole ZIP with BLAKE3 before extraction or Working Directory Update.
• Updated Server and Cache routes, SDK facade, OpenAPI, composed specifications, static bundles, generated TypeScript/Python/Rust clients, tests, and both Cache documents.
• Owned-path compliance: yes. No Working Directory Update source changed.
• Owner-approved expansion: none.
• Three-dot issue delta checked against the exact base: yes.
• Accidental or unrelated changes checked: yes.

Surface	Disposition	Validation or reason
Public DTO, route, CLI, and SDK contracts	Updated	Focused tests, Release builds, SDK freshness
Cache SQLite and filesystem generation identity	Updated	28/28 storage tests including reopen and mismatch behavior
OpenAPI and generated clients	Updated	OpenAPI checks and full TypeScript/Python/Rust generator matrix
Runtime and Aspire topology	Unchanged	Existing loopback Server/Cache fixture passed 7/7
Documentation	Updated	Markdown lint passed with MD013 disabled
Direct Connect and WDU transaction	Unchanged	No WDU source change; focused Connect composition tests passed

Proof

• Disposable algorithm prototype: 29/29.
• Artifact-grant Types tests: 3/3.
• Server signer and fill-permit tests: 2/2.
• Cache storage tests: 28/28.
• Cache host and endpoint tests: 12/12.
• CLI Connect and ConnectCache tests: 30/30.
• Cache/Server Aspire integration fixture: 7/7.
• Server integration project Release build: zero warnings and errors.
• OpenAPI projection generation and complete owned-surface checks: passed.
• TypeScript, Python, and Rust generated-client matrix: passed.
• SDK generated-client freshness: passed.
• Markdown lint: zero errors.
• Branch-wide Fantomas and git diff --check: passed.
• Local Fast/Full: intentionally skipped because the tracked run selected focused Release validation and required current-head GitHub Validate.
• Local full Server integration suite: intentionally skipped; GitHub Validate ran the broad suite on the final head, including 284/284 Server integration tests.

Factory run

• Execution mode: controller/worker with one continuing implementation owner and no parallel writers.
• Child context policy: fork_turns = "none".
• Diagnostic scout: not used.
• Replacement worker: not used.
• Owner stop encountered: no.
• Initial candidate head: 0c21fe58582d456aabc8510ccf6e5ab1380f5b0d.
• Final repaired head: a92b176588ed79feb4b8cbf115ba0cd9ef0fddff.
• Consolidated R1 repair commit: a92b176588ed79feb4b8cbf115ba0cd9ef0fddff.

Current-head gates

• Exact final head: a92b176588ed79feb4b8cbf115ba0cd9ef0fddff.
• GitHub Validate: run 33029192070 passed on the exact final head.
• Shape Review: selected GPT-5.6-Terra Medium hybrid report issue-1035-shape-review-gpt-5.6-terra-medium-encoded-format.html, complete on the exact final head with zero owner questions and successful 1440, 1024, and 768 CSS-pixel inspection.
• R1 discovery review: REPAIR on the initial candidate with two accepted P2 items covering the validation-key response envelope and Cache schema-version test.
• Repair: both accepted items were corrected in the consolidated final commit.
• R2 review: VERIFIED on the exact final head with no discovery escape, scope expansion, new owner decision, or direct repair regression.
• Owner approval: Scott approved the unchanged final head and selected Shape Review on 2026-08-26.

Residual risk and skipped proof

• A bearer grant can be replayed for the same immutable artifact during its five-minute lifetime.
• Server restart replaces the ephemeral key and may require a fresh preparation.
• Unmatched old generations may remain until future retirement work, but cannot satisfy a new exact-generation grant.
• Four repository-wide OpenAPI gates remain pending and unchanged: Storage operation tags, the existing /openApi error-response pair, stable SDK package export/import validation, and protocol vectors.

Merge readiness

• Issue GC-CAL-05: Require Server-signed BLAKE3 grants for Cache ZIP reads #1035 still describes the implemented outcome and supported world.
• Baseline admissibility is current and no semantic conflict remains unresolved.
• Explicit non-goals remain absent and no half-active capability was introduced.
• Public, persisted, generated, runtime, documentation, and focused test surfaces are synchronized.
• Final-head GitHub Validate passes.
• Shape Review covers the final head.
• R1 discovery review is complete.
• Accepted R1 findings are repaired and verified by R2.
• Scott approved the unchanged final revision and its Shape Review.

[ScottArbeit]

Landing report

• Approved head: a92b176588ed79feb4b8cbf115ba0cd9ef0fddff.
• Merge commit on main: 5d6e2cbe3c53e4a1d4c058da1eac978c99dce35f.
• GitHub Validate: run 33029192070 passed on the approved head.
• R1: two accepted P2 items, both repaired in the approved head.
• R2: VERIFIED on the approved head.
• Selected Shape Review: GPT-5.6-Terra Medium hybrid report issue-1035-shape-review-gpt-5.6-terra-medium-encoded-format.html, zero owner questions, with successful 1440, 1024, and 768 CSS-pixel inspection.
• Delivery composition: main advanced only in .github/PULL_REQUEST_TEMPLATE.md; it overlapped none of the 114 Issue GC-CAL-05: Require Server-signed BLAKE3 grants for Cache ZIP reads #1035 paths, and GitHub's merge tree matched Git's computed merge tree.
• Issue GC-CAL-05: Require Server-signed BLAKE3 grants for Cache ZIP reads #1035 closed automatically.
• Cleanup: remote issue branch deleted, issue worktree removed, local issue branch deleted, refs pruned, and local main updated with --ff-only.

Accepted residual risks remain unchanged: five-minute same-artifact bearer replay, a fresh preparation after a Server restart, unmatched older generations retained until later retirement, and four pre-existing repository-wide OpenAPI pending gates.

Local Fast and Full validation remained intentionally skipped. Focused Release validation and required GitHub Validate covered the approved head.