Summary
I18nPreferences.storageStrategy defaults to 'cookie'. As a result, mounting <AsgardeoProvider> writes an asgardeo-i18n-language cookie to the user's browser on the very first render, before the user has interacted with the app, regardless of whether the app exposes a language switcher.
This puts every SDK consumer serving EU users (and equivalent jurisdictions) into non-compliant-by-default territory under ePrivacy Directive Article 5(3) and GDPR. And the consumer cannot fix it themselves, because the write happens before any consent UI can react.
Proposing: change the default to 'none'. Apps that genuinely surface language selection can opt into persistence with one line of config.
The regulatory problem
Under the EU ePrivacy Directive (Art. 5(3)) and GDPR (recital 30 + Art. 7), cookies fall into two categories:
- Strictly necessary: required for a service the user explicitly requested (auth session, CSRF, shopping cart). Allowed without consent.
- Non-essential: everything else (analytics, preferences, marketing). Require prior, freely given, specific, informed, unambiguous consent before the cookie is written.
A language-preference cookie is unambiguously non-essential:
- It doesn't gate authentication. The OAuth flow works without it.
- It's a UI preference. The 2020 European Data Protection Board guidance (01/2020 on consent) is explicit that preference cookies require opt-in unless the user actively set the preference themselves.
- Many apps that mount
<AsgardeoProvider> never expose any language UI at all, in which case the cookie isn't even reflecting a user choice, just a stored browser-locale guess.
Equivalent regimes that apply the same rule: UK GDPR + PECR, Brazil LGPD, Switzerland nFADP, and in spirit CCPA/CPRA (less strict on cookies specifically but converging).
Why consumers can't fix this themselves
The cookie is written inside an useEffect in I18nProvider, which runs on the first render of <AsgardeoProvider>. That render happens at the top of the React tree, typically before any consent banner has loaded, let alone been interacted with.
No amount of consumer-side code can hook in between <AsgardeoProvider> mounting and the cookie being written. The opt-out paths available today (passing preferences.i18n.storageStrategy: 'none') require the consumer to know that:
- The cookie exists at all (it has no console warning, no docs callout).
- The exact nested config shape (which changed between SDK 0.22.x and 0.23.x without prominent changelog flagging).
- To set it before the provider mounts (only
'none' actually stops the write; 'localStorage' still writes to some store on mount).
Even teams that find the cookie and try to disable it routinely ship 2-3 no-op patches before getting the nesting right, because any mistake silently falls back to the cookie default with no warning.
Current behavior
packages/javascript/src/models/config.ts:
export type I18nStorageStrategy = 'cookie' | 'localStorage' | 'none';
/**
* The storage strategy to use for persisting the user's language selection.
* @default 'cookie'
*/
storageStrategy?: I18nStorageStrategy;
packages/react/src/contexts/I18n/I18nProvider.tsx:
const storageStrategy = preferences?.storageStrategy ?? 'cookie';
The cookie writer uses a 365-day Max-Age, scoped to the eTLD+1 of the current hostname (so app.example.com writes for .example.com, affecting every subdomain), SameSite=Lax + Secure.
Proposed change
/**
* The storage strategy to use for persisting the user's language selection.
*
* Defaults to `'none'` so the SDK does not write client-side storage without
* the consuming app explicitly asking for it. This keeps consumers compliant
* with cookie-consent regimes (EU ePrivacy / GDPR, UK PECR, LGPD, etc.) by
* default, since a non-essential preference cookie may not be set before the
* user has consented.
*
* Set explicitly to `'cookie'` or `'localStorage'` if your app exposes a
* language switcher and wants the choice to persist across sessions. In that
* case the consuming app is responsible for gating the call behind user
* consent where required.
*
* @default 'none'
*/
storageStrategy?: I18nStorageStrategy;
Runtime default:
const storageStrategy = preferences?.storageStrategy ?? 'none';
Why this is the right fix (vs. alternatives)
- Keep
'cookie', document it more loudly. Doesn't address that consumers physically cannot avoid the cookie via configuration. Documentation does not satisfy ePrivacy Art. 5(3).
- Default to
'localStorage'. Better on consent grounds (some regulators treat localStorage and cookies identically under ePrivacy, though enforcement has been less consistent), but still writes client-side state for apps that don't use the feature. Doesn't fix principle-of-least-surprise.
- Default to
'none' (this proposal). Side-effect free on mount. Apps that want persistence opt in explicitly and take responsibility for consent. Matches how most modern SDKs handle optional preference persistence.
Principle of least surprise (secondary argument)
Beyond the legal angle: SDKs should not write persistent client-side state for features the consuming app isn't actively using. An app that mounts <AsgardeoProvider> purely for OAuth, with no useTranslation call anywhere and no language switcher UI, gets a year-long cookie under the parent domain. That's surprising behavior.
Migration impact
For consumers who do surface language selection today and rely on persistence, the default change is a behavior change: they'd need to add
preferences: { i18n: { storageStrategy: 'localStorage' } } // or 'cookie' if they want the current behaviorto keep the prior behavior. Worth a prominent callout in the release notes. Could be staged as:
- Emit a console warning whenever the default is being used (so consumers see "you're getting a cookie you may not have asked for; set
storageStrategy explicitly").
- Flip the default to
'none' in the next minor.
Refs
Happy to send a PR if maintainers are on board.
Summary
I18nPreferences.storageStrategydefaults to'cookie'. As a result, mounting<AsgardeoProvider>writes anasgardeo-i18n-languagecookie to the user's browser on the very first render, before the user has interacted with the app, regardless of whether the app exposes a language switcher.This puts every SDK consumer serving EU users (and equivalent jurisdictions) into non-compliant-by-default territory under ePrivacy Directive Article 5(3) and GDPR. And the consumer cannot fix it themselves, because the write happens before any consent UI can react.
Proposing: change the default to
'none'. Apps that genuinely surface language selection can opt into persistence with one line of config.The regulatory problem
Under the EU ePrivacy Directive (Art. 5(3)) and GDPR (recital 30 + Art. 7), cookies fall into two categories:
A language-preference cookie is unambiguously non-essential:
<AsgardeoProvider>never expose any language UI at all, in which case the cookie isn't even reflecting a user choice, just a stored browser-locale guess.Equivalent regimes that apply the same rule: UK GDPR + PECR, Brazil LGPD, Switzerland nFADP, and in spirit CCPA/CPRA (less strict on cookies specifically but converging).
Why consumers can't fix this themselves
The cookie is written inside an
useEffectinI18nProvider, which runs on the first render of<AsgardeoProvider>. That render happens at the top of the React tree, typically before any consent banner has loaded, let alone been interacted with.No amount of consumer-side code can hook in between
<AsgardeoProvider>mounting and the cookie being written. The opt-out paths available today (passingpreferences.i18n.storageStrategy: 'none') require the consumer to know that:'none'actually stops the write;'localStorage'still writes to some store on mount).Even teams that find the cookie and try to disable it routinely ship 2-3 no-op patches before getting the nesting right, because any mistake silently falls back to the cookie default with no warning.
Current behavior
packages/javascript/src/models/config.ts:packages/react/src/contexts/I18n/I18nProvider.tsx:The cookie writer uses a 365-day
Max-Age, scoped to the eTLD+1 of the current hostname (soapp.example.comwrites for.example.com, affecting every subdomain),SameSite=Lax+Secure.Proposed change
Runtime default:
Why this is the right fix (vs. alternatives)
'cookie', document it more loudly. Doesn't address that consumers physically cannot avoid the cookie via configuration. Documentation does not satisfy ePrivacy Art. 5(3).'localStorage'. Better on consent grounds (some regulators treat localStorage and cookies identically under ePrivacy, though enforcement has been less consistent), but still writes client-side state for apps that don't use the feature. Doesn't fix principle-of-least-surprise.'none'(this proposal). Side-effect free on mount. Apps that want persistence opt in explicitly and take responsibility for consent. Matches how most modern SDKs handle optional preference persistence.Principle of least surprise (secondary argument)
Beyond the legal angle: SDKs should not write persistent client-side state for features the consuming app isn't actively using. An app that mounts
<AsgardeoProvider>purely for OAuth, with nouseTranslationcall anywhere and no language switcher UI, gets a year-long cookie under the parent domain. That's surprising behavior.Migration impact
For consumers who do surface language selection today and rely on persistence, the default change is a behavior change: they'd need to add
to keep the prior behavior. Worth a prominent callout in the release notes. Could be staged as:
storageStrategyexplicitly").'none'in the next minor.Refs
packages/react/src/contexts/I18n/I18nProvider.tsx(setCookie,createStorageAdapter)Happy to send a PR if maintainers are on board.