Skip to content

security(cache): residual hidden tenant/identity context and header-cardinality safety after 0.5.0 #53

Open

Description

@agustin18

Current published status (2026-11-21): The opt-in vary_headers contract was released in fastapi-cache-stable 0.5.0 (tag v0.5.0, merge PR #81). Its returned-Response Vary/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, Accept and custom X-Tenant/locale headers, where the endpoint reads them through Request, 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/JSONResponse with Vary, Cache-Control: private/no-store, and normal injected-response headers, including HIT/ETag/304. Verify whether Vary is preserved and respected; do not assume HTTP Vary by 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 Request and 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_request or normal Header(...) args.
  • An application wanting cached Request endpoints 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(...), indirect Request, middleware request.state, custom variation builder, the existing privacy/auth rules and response headers.
  • Explain the performance/behavior change for applications that used request: Request only 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, contextvars or 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

  1. changed the title [-]security(cache): verify request-header variants and Vary-safe caching[/-] [+]fix(cache): prevent unkeyed Request-header variants from sharing responses[/+] on Nov 19, 2026
  2. 14 remaining items

  3. agustin18 commented on Nov 20, 2026

    @agustin18
    OwnerAuthor

    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 had Vary, 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 generated Vary to 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 custom X-API-Key is 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.

  4. agustin18 commented on Nov 20, 2026

    @agustin18
    OwnerAuthor

    Bounded #53 implementation merged in #81 at 58fd446. Opt-in vary_headers now 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.

  5. added a commit that references this issue on Nov 21, 2026
  6. agustin18 commented on Nov 21, 2026

    @agustin18
    OwnerAuthor

    0.5.0 is published (2026-11-21, tag v0.5.0), so vary_headers is 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.

  7. changed the title [-]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[/+] on Nov 21, 2026
  8. agustin18 commented on Nov 21, 2026

    @agustin18
    OwnerAuthor

    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 stable share 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 incoming Authorization or Cookie header bypasses cache reads and writes when cache_authenticated=False (default); authenticated caching with the default builder raises rather than silently accepting a shared key.
    • An endpoint that explicitly declares Request and uses the default key builder bypasses caching. This conservatively avoids unknown header/state dimensions accessed inside the endpoint, at the cost of cache hits.
    • Opt-in vary_headers creates versioned hashed variant keys and emits a matching HTTP Vary on covered MISS/HIT/304. Credential-bearing names authorization, cookie and proxy-authorization are blocked and the field-name count is limited to 32. A returned response Vary outside the selected allowlist bypasses storage.
    • Existing regressions include 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

    Residual Assessment / needed proof
    X-API-Key, custom tenant header, proxy identity Application-controlled and potentially private. These are not covered by the built-in Authorization/Cookie test; their appearance in a key/validation is not automatic. Verify a consumer that intentionally uses a different scheme; if a library-owned default promises isolation and fails, classify as release-blocking.
    request.state / middleware / ContextVar / dependency hidden values Not automatically detected if the decorated endpoint does not declare Request or 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.
    Reverse proxy trust / forwarded Host App/network configuration must authenticate trusted proxies; syntactically accepting a forwarded header is not validation. Reproduce misrouting before changing library default key format.
    vary_headers high-cardinality input The 32-field limit constrains names, not the number of attacker-controlled values. Rate-limit, canonicalize/allowlist values, bound TTL and backend capacity. #85 per-process entry cap is source-merged but not a replacement for rate limiting and not in published 0.5.0.
    Persisted legacy private Redis entries / rollback Cache bypass is not retroactive. Require scoped invalidation/rotation and a rollback plan that does not restore unsafe authenticated response caching.
    Multiple FastAPI apps or event loops FastAPICache configuration is process-global. Review init(force=True) / reset() and backend instances; do not claim app-scoped isolation.

    Proposed completion evidence

    1. Add or cite an exact-source test against the final release candidate showing the unsafe hidden-dependency variant and the safe vary_headers or custom key mitigation, plus Authorization/Cookie default bypass and explicit-Request fallback. Keep all identities and data fictional.
    2. Record which failure cases are library-owned (runtime fix needed) vs application-owned (documentation, non-automatic safety warning). Do not close security(cache): residual hidden tenant/identity context and header-cardinality safety after 0.5.0 #53 simply because regression tests pass.
    3. For any demonstrated unmitigated library-owned cross-tenant private response disclosure, NO-GO until a focused code fix passes independent review and the migration compatibility matrix.
    4. Carry accepted residuals, user-facing warnings and exact source SHA into #92 release gate. Obtain an explicit maintainer risk decision; tests under test(0.6): two genuinely independent consumer exercises and evidence gate #91 must provide independent consumer evidence, not internal-only simulations.

    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_entries documentation, not this security contract.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions