asgardeo / asgardeo/javascript

i18n: change `storageStrategy` default to `'none'` (regulatory + opt-in)

Offen
#522 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
TypeScript
Sterne
18
Forks
67
Ø Merge
4 Std. 6 Min.
Gemergte PRs (30 T.)
13

Beschreibung

## Summary

`I18nPreferences.storageStrategy` defaults to `'cookie'`. As a result, mounting `` 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](https://edpb.europa.eu/sites/default/files/files/file1/edpb_guidelines_202005_consent_en.pdf)) is explicit that preference cookies require opt-in unless the user actively set the preference themselves.
- Many apps that mount `` 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 ``. 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 `` mounting and the cookie being written. The opt-out paths available today (passing `preferences.i18n.storageStrategy: 'none'`) require the consumer to know that:

1. The cookie exists at all (it has no console warning, no docs callout).
2. The exact nested config shape (which changed between SDK 0.22.x and 0.23.x without prominent changelog flagging).
3. 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`](https://github.com/asgardeo/javascript/blob/main/packages/javascript/src/models/config.ts):

```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`](https://github.com/asgardeo/javascript/blob/main/packages/react/src/contexts/I18n/I18nProvider.tsx):

```ts
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

```ts
/**
* 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:

```ts
const storageStrategy = preferences?.storageStrategy ?? 'none';
```

## Why this is the right fix (vs. alternatives)

1. **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).
2. **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.
3. **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 `` 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

```ts
preferences: { i18n: { storageStrategy: 'localStorage' } } // or 'cookie' if they want the current behavior
```

to keep the prior behavior. Worth a prominent callout in the release notes. Could be staged as:

1. 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").
2. Flip the default to `'none'` in the next minor.

## Refs

- Cookie writer + storage adapter: `packages/react/src/contexts/I18n/I18nProvider.tsx` (`setCookie`, `createStorageAdapter`)
- EDPB Guidelines 01/2020 on consent: https://edpb.europa.eu/sites/default/files/files/file1/edpb_guidelines_202005_consent_en.pdf
- ePrivacy Directive Art. 5(3): https://eur-lex.europa.eu/eli/dir/2002/58/oj

Happy to send a PR if maintainers are on board.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne in packages/javascript/src/models/config.ts und packages/react/src/contexts/I18n/I18nProvider.tsx damit, den storageStrategy-Typ, die Dokumentation, das Laufzeit-Fallback, setCookie und die createStorageAdapter-Pfade zu lesen. Bestätige, dass die deklarierten und zur Laufzeit verwendeten Standardwerte zu 'none' werden, dass explizite cookie- und localStorage-Auswahlen weiterhin funktionieren und dass betroffene Release Notes oder Dokumentation aktualisiert werden; validiere dies mit den bestehenden Checks des React-Pakets.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
react, typescript
Bereich
frontend
Issue-Typ
Feature
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Ruhig
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
56/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.