Repository navigation
Description
Current published status (2026-11-21): The opt-in
vary_headerscontract was released in fastapi-cache-stable 0.5.0 (tag v0.5.0, merge PR #81). Its returned-ResponseVary/ETag/304 regression checks are shipped. This issue remains OPEN only for residual hidden context / middleware / custom credentials / tenant identity, reverse-proxy header trust and unbounded attacker-controlled header cardinality. The library does NOT auto-detect arbitrary user/tenant/permission dimensions. Reproduce a package-owned privacy defect before changing runtime defaults; otherwise document application-owned mitigations. These residuals have priority over optional 0.6.0 features tracked in #86. Earlier discussion below is historical and includes superseded pre-release statements.
Status update (2026-11-19): a partial mitigation shipped in 0.3.1 (see below). This issue remains open for the residual
Vary/hidden-context scope.
Priority: P0 investigation / security-correctness; remediation targeted to 0.3.x only if reproducible without breaking migration
Observed code and nuance
The published 0.3.0 default_key_builder hashes func.__module__, func.__name__, args and kwargs but does not read request headers directly. In the decorator, injected Request and Response are removed from the key kwargs before this hash. A route can therefore produce different data by reading request.headers, request.state or a middleware/context variable not represented in args/kwargs. Authorization/Cookie bypass protects two header types, not all tenant/locale/content-negotiation mechanisms.
Do not claim all Header(...) inputs are excluded: when FastAPI resolves such a header into the endpoint's kwargs, it may already distinguish keys. Original upstream issue #558 reports an interaction seen in Swagger UI but curl in that very report demonstrated separate MISS→HIT per injected header value. Reproduce that particular case rather than treating it as conclusive proof of a general defect.
Reproduction and threat model
- Test two anonymous requests with identical path/query but different
Accept-Language,Acceptand customX-Tenant/locale headers, where the endpoint reads them throughRequest, middleware or a dependency whose value is not captured in the key. Observe output and cache status. - Separate this case from
header: str = Header(...)(parameter captured), identity in kwargs (may be captured), and Authorization/Cookie (currently bypass). - Test returned
Response/JSONResponsewithVary,Cache-Control: private/no-store, and normal injected-response headers, including HIT/ETag/304. Verify whetherVaryis preserved and respected; do not assume HTTPVaryby itself partitions our internal cache. - Determine if this is only wrong-language content or can become a cross-tenant/private-information leak when applications use nonstandard auth headers or request.state.
- Include cache-data migration: changing the default key globally can make old entries inaccessible. Prefer a narrow safe bypass for uncertain variants, or explicit allowlisted
vary_headers/scoped key builder opt-in with documented namespace rotation and full privacy tests.
Exit criteria
A reproducible source-level/integration test, an explicit security classification, fix/design with key-compatibility plan, tests on default privacy behavior and documented safe custom-key examples. If a directly exploitable data leak is demonstrated in package-owned behavior, do not defer it merely to hit a 0.4.0 schedule.
Source: key_builder.py, decorator.py, upstream #558.
Confirmed reproduction (local auditor, 2026-11-19)
The independent local agent reported this test with two sequential requests and distinct Accept-Language headers:
| Endpoint pattern | Cache statuses | Returned languages |
|---|---|---|
language: str = Header(...) |
MISS, MISS |
en, es |
request: Request and request.headers read indirectly |
MISS, HIT |
en, en (wrong for second request) |
This confirms a cache-correctness defect for the indirect header path. It does not by itself prove a cross-tenant data leak. A custom X-Tenant/X-API-Key or authorization scheme read indirectly could elevate impact and must be assessed separately. The local auditor's original tests/logs are not independently archived in GitHub; add a regression in a focused PR.
Proposed narrow safe patch (review before merging)
- When an endpoint explicitly declares
Requestand uses the library's default key builder, conservatively bypass storage and retrieval rather than sharing a potentially incomplete key. This is not applied to merely auto-injected internal__fastapi_cache_requestor normalHeader(...)args. - An application wanting cached
Requestendpoints must supply a custom key builder incorporating all response-determining request/identity/tenant/locale dimensions and consider backend namespaces; a custom key builder is an explicit application contract, not automatically guaranteed safe. - Existing cached entries for bypassed endpoints remain in Redis until expiry or targeted cleanup, but must not be read by the new default path. No global MD5 key format change.
- Add tests for headers via FastAPI
Header(...), indirectRequest, middlewarerequest.state, custom variation builder, the existing privacy/auth rules and response headers. - Explain the performance/behavior change for applications that used
request: Requestonly for benign metadata: they will bypass by default and must opt into a correct custom builder to recover cache hits. - Residual limitation: hidden
contextvars, app-global state or dependency contexts not represented in endpoint arguments cannot always be detected. No static auto-bypass can prove arbitrary app behavior safe. Document this boundary.
Do not merge a runtime patch until modern/legacy CI and a real consumer regression review pass. An intentional patch-level security default change is appropriate only when evidence supports it. Reassess whether a smaller mitigation is feasible if test impact is too broad.
Implementation status — partial mitigation published in 0.3.1
PR #56 merged the narrow explicit-Request/default-builder bypass. It shipped in 0.3.1 (tag v0.3.1, f55d534e9ed99d74229d8c152bd5d21a26b65b43) with regression tests, migration/security documentation and consumer verification. The fix is intentionally partial: an endpoint that explicitly declares Request and uses the default key builder now bypasses cache reads/writes; endpoints with a reviewed custom key builder still cache.
This issue remains open for the residual scope:
Vary-aware caching and header-variation policy.- Headers/state read indirectly by dependencies, middleware,
contextvarsor application-global state. - Per-user/tenant key design and safe opt-in variation with namespace/key migration.
- Clear guidance for custom key builders and the existing-cache cleanup/rollout contract.
The 0.3.1 change does not prove arbitrary application behavior safe and does not close these scenarios.
Activity
[-]security(cache): verify request-header variants and Vary-safe caching[/-][+]fix(cache): prevent unkeyed Request-header variants from sharing responses[/+]chore(release): prepare 0.3.1 (#57)
docs: sync 0.3.1 status, roadmap and provenance (#58)
docs(roadmap): prioritize confirmed #68 correctness and focus 0.5.0 r…
test(vary): add RED contract for explicit header variation and safe b…
feat(cache): opt-in validated hashed vary_headers without changing de…
docs(vary): document explicit header variation and migration boundary (…
docs(vary): document explicit header variation and migration boundary (…
docs(vary): document explicit header variation and migration boundary (…
docs(changelog): record opt-in vary_headers contract (#53)
test(vary): ensure opt-in never reads old entries or defeats auth and…
test(vary): prove installed-wheel header isolation with real Redis (#53)
14 remaining items
fix(vary): limit returned-Response stamping to explicit opt-in routes (…
docs(vary): clarify returned-Response metadata and custom header thre…
docs(vary): clarify returned-Response metadata and custom header thre…
docs(vary): clarify returned-Response metadata and custom header thre…
docs(vary): clarify returned-Response metadata and custom header thre…
docs(vary): clarify returned-Response metadata and custom header thre…
docs(vary): clarify returned-Response metadata and custom header thre…
test(vary): verify returned JSONResponse and PickleCoder Response on …
agustin18 commentedon Nov 20, 2026
2026-11-20: Independent review of #81 identified a real HTTP Vary contract bug on cacheable endpoints returning their own
Response: the injected FastAPI response hadVary, but the actual returned JSONResponse/Response could lack it, especially on MISS. This is a potential intermediate HTTP cache mis-variation (not demonstrated to be a FastAPICache internal key crossover).Corrected on draft HEAD
3fa1d6414b8bd63be6da1cc41d6aaee8d987d8c1: add generatedVaryto a returned Response after coder eligibility but before encoding; stamp cache/ETag/Vary metadata on the returned object on MISS/HIT, preserving 304 behavior. Non-opt-in paths unaffected. Added new JSONResponse/JsonCoder and plain Response/PickleCoder MISS/HIT/304 regressions, factory-route composition test (#68) and matching real Redis installed-wheel consumer checks. Clarified customX-API-Keyis not rejected/authenticated automatically and client header cardinality may cause cache flooding.Exact-head seven workflows success: CI 44836005291 27/27 (Python 3.12: 363 passed, 18 skipped, changed-line 100%), Redis 44836005336 17/17, installed security profiles 44836005265 7/7, historical published 0.2.2→0.4.1 parity 44836005274 2/2, CodeQL/changelog/PR title green (56/56 jobs total).
#81 remains DRAFT and #53 OPEN: request independent security/semantic review of response metadata and tenant/proxy trust before merge. Historical published parity does not exercise #81 code; new branch wheel is covered by Redis tests. No merge, lock/metadata change, tag or publication. #69 exact 0.5.0 phase B and #66 final security signoff remain release gates.
fix(cache): add opt-in vary_headers isolation (#81)
agustin18 commentedon Nov 20, 2026
Bounded #53 implementation merged in #81 at 58fd446. Opt-in
vary_headersnow isolates explicitly listed request headers under versioned hashed keys, preserves default/legacy keys for non-opted routes, keeps the explicit-Request and auth bypasses, and fails closed for wildcard/undeclared Vary. Returned JSONResponse/Response headers were corrected and covered by InMemory and installed-wheel Redis tests. This issue is not closed automatically: hidden contextvars/middleware/tenant identity beyond the declared header list, custom credential headers and key-cardinality controls remain application responsibilities documented in README/MIGRATION/COMPATIBILITY.docs(roadmap): reconcile completed #53/#67/#68/#69-A and isolate #69-B/…
agustin18 commentedon Nov 21, 2026
0.5.0 is published (2026-11-21, tag
v0.5.0), sovary_headersis available from PyPI. This issue remains open only for the documented residual: hidden tenant/identity/context, proxy trust and header-cardinality controls. It is not an automatic tenant-isolation guarantee.[-]fix(cache): prevent unkeyed Request-header variants from sharing responses[/-][+]security(cache): residual hidden tenant/identity context and header-cardinality safety after 0.5.0[/+]agustin18 commentedon Nov 21, 2026
0.6.0 risk review preflight (2026-11-21) — classification still open
This is a source-and-test inventory, not a final security signoff or a claim of universal tenant isolation. Current published 0.5.0 and merged post-release
stableshare the relevant privacy behavior; #85 changes InMemory eviction/capacity but not the decorator, key builder or authorization policy.Observed source-backed mitigations
fastapi_cache/decorator.py: an incomingAuthorizationorCookieheader bypasses cache reads and writes whencache_authenticated=False(default); authenticated caching with the default builder raises rather than silently accepting a shared key.Requestand uses the default key builder bypasses caching. This conservatively avoids unknown header/state dimensions accessed inside the endpoint, at the cost of cache hits.vary_headerscreates versioned hashed variant keys and emits a matching HTTPVaryon covered MISS/HIT/304. Credential-bearing namesauthorization,cookieandproxy-authorizationare blocked and the field-name count is limited to 32. A returned responseVaryoutside the selected allowlist bypasses storage.tests/test_auth_privacy.py,tests/test_request_variants.py,tests/test_vary_headers.py; these tests verify the known syntactic/header scope, not every app's hidden context.Residual cases / ownership decisions required before 0.6.0 GO
X-API-Key, custom tenant header, proxy identityrequest.state/ middleware /ContextVar/ dependency hidden valuesRequestor expose the dimension in kwargs. A default shared key may return the wrong tenant/locale representation. Document bypass or a validated complete custom key builder; include positive and negative tests in #91 external exercises.vary_headershigh-cardinality inputFastAPICacheconfiguration is process-global. Reviewinit(force=True)/reset()and backend instances; do not claim app-scoped isolation.Proposed completion evidence
vary_headersor custom key mitigation, plus Authorization/Cookie default bypass and explicit-Request fallback. Keep all identities and data fictional.Do not add tags/locks/events just for competitor parity while this remains unresolved. The feature-scoped source for #85 is merged; #93 updates release-accurate
max_entriesdocumentation, not this security contract.