spec: issue-3549 Browser cache for CAS downloads

[jiparis]

Summary

The CAS download endpoint will let a browser keep a copy of a downloaded artifact and check that copy before each use. The endpoint will accept the download token in an Authorization: Bearer header, so that the download URL stays the same for a given digest. The response will tell the browser the digest of the content and how to cache it. When the browser already has the content, the CAS will answer "not modified" and will not copy the object from the storage backend. The Chainloop platform viewers need this change to show large artifacts, such as AI coding session transcripts, with no full download on each open.

Open questions for reviewers

None. These decisions were made while drafting and are open to challenge:

• D-004: when a request has both a header token and a query token, the header wins. A bad header does not fall back to the query.
• D-005: before a 304, the CAS checks with a metadata call that the object exists in the storage backend.
• D-006: a 304 does not record a download audit event.

Refs #3549

This spec was written with AI assistance (Claude Code).

🤖 Generated with Claude Code

[chainloop-platform]

PR validation — ✅ 3 passing

Status	Policy	Material	Messages
✅ Passed	pr-min-approvals	pr-info	-
✅ Passed	pr-description-required	pr-info	-
✅ Passed	pr-user-story-linked	pr-info	-

_{View attestation ↗}

AI Session Checks — ⚠️ no AI session found

Missing AI Coding Sessions

This organization requires every PR to be backed by a Chainloop Trace AI coding session, and none was found for this one.

Please make sure the AI coding session evidence has been sent by the Chainloop CLI, or add the skip-ai-session label to this PR to bypass this check.

Learn more about Chainloop Trace.

Security Checks — ✅ 5 passing

✅ secret-scan

Status	Policy	Messages
✅ Passed	secrets-detection	-

✅ sast-scan

Status	Policy	Messages
✅ Passed	owasp-top10-2025	-
✅ Passed	sast	-
✅ Passed	cwe-top25	-
✅ Passed	cwe-top26-40-cusp	-

Scans not applied (3)

Scan	Reason
vulnerability-scan	no manifest/lockfile changed
github-actions-scan	no workflow files changed
iac-scan	no IaC files changed

_{View attestation ↗}

Security context

✅ Nothing this change touches has a recorded security-fix history.

_{View in Chainloop ↗ · How this works ↗}

---

Powered by Chainloop and Chainloop Trace