Skip to content

fix(auth)!: stop handing signed storage URLs to unverified tokens - #309

Merged
LouisHaftmann merged 2 commits into
devfrom
fix/token-validation-safeguards
Oct 28, 2026
Merged

LouisHaftmann merged 2 commits into
devfrom
fix/token-validation-safeguards

Conversation

@LouisHaftmann

Copy link
Copy Markdown
Collaborator

📝 Summary

A direct-download URL is a bearer credential for the stored object, and the runtime token is the only thing guarding it. With SKIP_TOKEN_VALIDATION=true the token's claims are trusted unverified, so anyone who can reach the server could get a signed URL for any repository's cache. Verified tokens had gaps too: a token without exp never expired, a write-only scope was used for reads, and the debug log printed decoded claims.

This PR ports the intent of @chenrui333's branch from #294 to the Rust server:

 startup
+  ENABLE_DIRECT_DOWNLOADS && SKIP_TOKEN_VALIDATION -> refuse to start
+    unless UNSAFE_ALLOW_DIRECT_DOWNLOADS_WITHOUT_TOKEN_VALIDATION=true
 verify token
-  require iss
+  require iss, exp
+  ACTIONS_TOKEN_AUDIENCE set -> require aud, one of the listed values
 ac claim
-  Permission >= 2 -> write; every scope -> read
+  Permission & 2 -> write; Permission & 1 -> read
+  empty Scope / non-integer Permission -> 401
 reject
-  log the error (could quote claim values)
+  log the error kind and claim name only
 direct download
-  URL and Storage Reader Lease: 10 minutes
+  URL: DIRECT_DOWNLOAD_URL_TTL_SECONDS (1-3600, default 600)
+  Storage Reader Lease: URL lifetime + 10 minutes

The lease now outlives the URL because storage authenticates a GET when it starts, so a transfer that starts just before the URL expires keeps reading after it. Recorded in the new ADR-0013 and an updated ADR-0002. The Helm chart exposes config.directDownloadUrlTtlSeconds.

✅ Verification

  • Before: a token without exp, a token with "Permission": -1, or a write-only scope used for lookups were all accepted. Direct downloads started fine with SKIP_TOKEN_VALIDATION=true.
    After: new tests check that each of these is now rejected, using tokens signed with a test Ed25519 key and a JWKS served by the test:
    • scope::tests::verified_tokens_need_exp_and_well_formed_scopes
    • scope::tests::a_configured_audience_is_required
    • scope::tests::permissions_are_bit_flags
    • config::tests::direct_downloads_require_token_validation
    • config::tests::bounds_the_direct_download_url_lifetime
    • config::tests::parses_the_token_audience
    • tests::downloads::a_direct_download_lease_outlives_the_signed_url (S3): X-Amz-Expires equals the configured TTL, and the lease lasts at least TTL + 10 min.
  • cargo +nightly fmt --check, cargo clippy --all-targets --locked: clean
  • cargo test on sqlite × filesystem and sqlite × s3: 82 passed
  • helm template renders DIRECT_DOWNLOAD_URL_TTL_SECONDS: "600"

🔍 Reviews

Review Found Fixed
bug 0 0
spec 1 1
simplicity 1 1

ACTIONS_TOKEN_AUDIENCE is not exposed in the Helm chart. The chart doesn't expose the issuer or SKIP_TOKEN_VALIDATION either; use extraEnv to set it.

🔗 Issues

Closes #298

💥 Merge danger

Door: two-way

Reverting restores the old behavior. No data or schema changes.

Blast Radius: startup

Deployments that run ENABLE_DIRECT_DOWNLOADS=true together with SKIP_TOKEN_VALIDATION=true stop at startup and need a release note. Tokens without exp or with a malformed ac claim are now rejected; GitHub-issued tokens always carry well-formed ones.

⚠️ Needs attention

  • Release note for the breaking startup guard.
  • Document DIRECT_DOWNLOAD_URL_TTL_SECONDS, ACTIONS_TOKEN_AUDIENCE and UNSAFE_ALLOW_DIRECT_DOWNLOADS_WITHOUT_TOKEN_VALIDATION in falcondev-oss/docs.

🤖 Generated with Claude Code

LouisHaftmann and others added 2 commits October 28, 2026 08:33
…ut it

- refuse ENABLE_DIRECT_DOWNLOADS=true with SKIP_TOKEN_VALIDATION=true unless
  UNSAFE_ALLOW_DIRECT_DOWNLOADS_WITHOUT_TOKEN_VALIDATION=true
- require `exp` on verified tokens; optional ACTIONS_TOKEN_AUDIENCE
- treat scope permissions as read/write bit flags and reject malformed scopes
- log only the token error kind and claim name
- DIRECT_DOWNLOAD_URL_TTL_SECONDS (default 600); the reader lease outlives
  the URL by a fixed margin

BREAKING CHANGE: setups running ENABLE_DIRECT_DOWNLOADS=true together with
SKIP_TOKEN_VALIDATION=true no longer start.

Closes #298

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(auth): harden token validation and refuse direct downloads without it

1 participant