Add gzip compression option for consent cookies

[gilluminate]

ENG-2232

Description Of Changes

Adds optional gzip compression for consent cookies to reduce cookie size, particularly beneficial for TCF implementations with large vendor lists.

Code Changes

• Added fidesCookieCompression option to FidesOptions ("gzip" or "none")
• Implemented compression/decompression utilities using browser's native CompressionStream API
• Added browser feature detection with automatic fallback to uncompressed cookies
• Updated getFidesConsentCookie and saveFidesCookie to handle async compression (CompressionStream requires this)
• Added runtime validation for compression option values
• Updated React components (TcfOverlay, NoticeOverlay) to handle async cookie operations
• Added comprehensive unit test coverage for compression functionality
• Added FIDES_COOKIE_COMPRESSION environment variable to Privacy Center

Steps to Confirm

1. Configure TCF experience in AdminUI
2. Load demo page with override enabled (/fides-js-demo.html?geolocation=eea&fides_cookie_compression=gzip)
3. Accept or save consent preferences
4. Inspect the fides_consent cookie - it should be prefixed with gzip: and base64url-encoded
5. Verify cookie reads back correctly on page reload
6. Verify backward compatibility with existing cookie

Pre-Merge Checklist

• Issue requirements met
• All CI pipelines succeeded
• CHANGELOG.md updated
  • Add a db-migration This indicates that a change includes a database migration label to the entry if your change includes a DB migration
  • Add a high-risk This issue suggests changes that have a high-probability of breaking existing code label to the entry if your change includes a high-risk change (i.e. potential for performance impact or unexpected regression) that should be flagged
  • Updates unreleased work already in Changelog, no new entry necessary
• UX feedback:
  • All UX related changes have been reviewed by a designer
  • No UX review needed
• Followup issues:
  • Followup issues created
  • No followup issues
• Database migrations:
  • Ensure that your downrev is up to date with the latest revision on main
  • Ensure that your downgrade() migration is correct and works
    • If a downgrade migration is not possible for this change, please call this out in the PR description!
  • No migrations
• Documentation:
  • Documentation complete, PR opened in fidesdocs
  • Documentation issue created in fidesdocs
  • If there are any new client scopes created as part of the pull request, remember to update public-facing documentation that references our scope registry
  • No documentation updates required

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
fides-plus-nightly	Ignored	Preview	Dec 17, 2025 9:07pm
fides-privacy-center	Ignored		Dec 17, 2025 9:07pm

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds optional gzip compression for Fides consent cookies to address cookie size limitations, particularly for TCF (Transparency & Consent Framework) implementations with large vendor lists that can exceed browser cookie limits. The feature introduces a new fidesCookieCompression configuration option with "gzip" or "none" values, defaulting to "none" for backward compatibility.

The implementation uses the browser's native CompressionStream API with automatic feature detection and graceful fallback to uncompressed cookies. Since the CompressionStream API is inherently asynchronous, this required converting all cookie operations throughout the codebase from synchronous to async, affecting 23 files across the FidesJS SDK, Privacy Center, and test suites. React components were updated to handle async cookie loading using useState/useEffect patterns. The change includes comprehensive test coverage and environment variable support for the Privacy Center.

Important Files Changed

Filename	Score	Overview
clients/fides-js/src/lib/cookie.ts	4/5	Core implementation of compression/decompression utilities with browser feature detection
clients/fides-js/src/components/tcf/TcfOverlay.tsx	4/5	Major refactor to async cookie operations with proper React state management
clients/fides-js/src/components/notices/NoticeOverlay.tsx	4/5	Updated to handle async cookie loading with useState/useEffect pattern
clients/privacy-center/components/consent/notice-driven/NoticeDrivenConsent.tsx	4/5	Converted to async cookie operations with proper null checking
clients/fides-js/src/fides-tcf.ts	4/5	Made TCF initialization async to support cookie compression
clients/fides-js/tests/lib/cookie-compression.test.ts	5/5	New comprehensive test file for compression functionality
clients/fides-js/src/docs/fides-options.ts	5/5	Added new fidesCookieCompression option to TypeScript interface
clients/fides-js/src/lib/consent-types.ts	5/5	Updated type definitions to include compression option
clients/fides-js/src/lib/consent-constants.ts	5/5	Added validation configuration for compression override
clients/privacy-center/app/server-environment.ts	5/5	Added environment variable support for compression setting
clients/fides-js/src/lib/init-utils.ts	5/5	Set default compression value to "none"
clients/privacy-center/app/server-utils/PrivacyCenterSettings.ts	5/5	Added TypeScript interface for compression configuration
clients/privacy-center/app/server-utils/loadEnvironmentVariables.ts	5/5	Environment variable loading with type validation
clients/privacy-center/pages/api/fides-js.ts	5/5	Configuration pass-through for client-side bundle
clients/fides-js/tests/lib/cookie.test.ts	5/5	Updated existing cookie tests to handle async operations
clients/privacy-center/components/consent/useConsentRequestForm.ts	5/5	Properly handles async cookie loading with React hooks

Confidence score: 4/5

• This PR involves significant architectural changes but appears well-implemented with proper async handling and fallback mechanisms
• Score reflects the complexity of converting synchronous operations to async across 23 files and potential for subtle timing issues in React components
• Pay close attention to the React component changes in TcfOverlay.tsx and NoticeOverlay.tsx which involve complex async state management

[greptile-apps]

Additional Comments (1)

1. clients/privacy-center/components/modals/consent-request-modal/useConsentRequestForm.ts, line 141 (link)

   logic: The saveFidesCookie call should be awaited since it may now be async for compression operations

   Should this saveFidesCookie call be awaited since compression operations are async?

_{28 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[tvandort]

Thanks for getting this done so quick!

Outside of the specific feedback I do think we want cypress tests around this given that we can't actually test the compression in jest unit tests / Node.

[tvandort]

Do we need tests for the changes in this file?

[gilluminate]

I'd say tests are not strictly required for this PR, but would be a good follow-up task since there's no existing test file for this component in general. The changes are low-risk defensive programming that makes the component safer with async cookie operations.

[tvandort]

meant to request changes on the prior review 🙃

[gilluminate]

Outside of the specific feedback I do think we want cypress tests around this given that we can't actually test the compression in jest unit tests / Node.

@tvandort I actually started doing that, but in the end it felt like I was testing the browser's ability to compress, not necessarily testing our code. Probably doesn't hurt though.

[gilluminate]

@tvandort thanks! ready for another pass