@djangocfg/api 2.1.603 → 2.1.604

package/src/__tests__/sharedCookie.test.ts

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+// @vitest-environment-options {"url": "https://my.example.com/"}
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { readCookie } from '../cookies';
+import { CFG_KEYS, createStorage } from '../storage';
+
+const ACCESS = CFG_KEYS.accessToken.key;
+const REFRESH = CFG_KEYS.refreshToken.key;
+
+function wipe() {
+  localStorage.clear();
+  document.cookie.split('; ').forEach((c) => {
+    const name = c.split('=')[0];
+    document.cookie = `${name}=; Max-Age=0; Path=/`;
+    document.cookie = `${name}=; Max-Age=0; Path=/; Domain=example.com`;
+  });
+}
+
+beforeEach(wipe);
+
+describe('shared cookie domain', () => {
+  it('finds the registrable domain by asking the browser', () => {
+    const storage = createStorage('cfg');
+    expect(storage.cookieDomain()).toBe('example.com');
+  });
+
+  it('round-trips and removes a token cookie on the shared domain', () => {
+    const storage = createStorage('cfg');
+    expect(storage.write(ACCESS, 'jwt', 'cookie')).toBe(true);
+    expect(storage.read(ACCESS, 'cookie')).toBe('jwt');
+    storage.remove(ACCESS, 'cookie');
+    expect(storage.read(ACCESS, 'cookie')).toBeNull();
+    expect(document.cookie).not.toContain('cfg.auth.access_token');
+  });
+
+  it('a host-only cookie from an older build does not shadow the shared one, and sign-out clears both', () => {
+    const storage = createStorage('cfg');
+    document.cookie = `${encodeURIComponent(ACCESS)}=old; Path=/`;
+    storage.write(ACCESS, 'new', 'cookie');
+    expect(storage.read(ACCESS, 'cookie')).toBe('new');
+    document.cookie = `${encodeURIComponent(ACCESS)}=stale; Path=/`; // stray host-only twin again
+    storage.remove(ACCESS, 'cookie');
+    expect(document.cookie).not.toContain('cfg.auth.access_token');
+  });
+
+  it('stays host-only when asked', () => {
+    const storage = createStorage('cfg', { cookieDomain: false });
+    expect(storage.cookieDomain()).toBeNull();
+    storage.write(ACCESS, 'jwt', 'cookie');
+    expect(storage.read(ACCESS, 'cookie')).toBe('jwt');
+  });
+
+  it('honours a forced domain', () => {
+    const storage = createStorage('cfg', { cookieDomain: 'example.com' });
+    expect(storage.cookieDomain()).toBe('example.com');
+  });
+
+  it('clearAll removes the personal cookie keys', () => {
+    const storage = createStorage('cfg', { keys: CFG_KEYS });
+    storage.write(ACCESS, 'a', 'cookie');
+    storage.write(REFRESH, 'r', 'cookie');
+    storage.clearAll();
+    expect(storage.read(ACCESS, 'cookie')).toBeNull();
+    expect(storage.read(REFRESH, 'cookie')).toBeNull();
+  });
+});
+
+describe('readCookie (SSR header)', () => {
+  it('reads an encoded name and value from a Cookie header', () => {
+    const header = `a=1; ${encodeURIComponent(ACCESS)}=${encodeURIComponent('x.y.z')}; b=2`;
+    expect(readCookie(header, ACCESS)).toBe('x.y.z');
+    expect(readCookie(header, 'missing')).toBeNull();
+    expect(readCookie(null, ACCESS)).toBeNull();
+    expect(readCookie('', ACCESS)).toBeNull();
+  });
+});
+
+describe('auth store session', () => {
+  async function loadAuth() {
+    vi.resetModules();
+    return (await import('../_api/generated/helpers/auth')).auth;
+  }
+
+  it('defaults to the cookie backend and writes the pair there', async () => {
+    const auth = await loadAuth();
+    expect(auth.getStorageMode()).toBe('cookie');
+    auth.setSession({ access: 'A', refresh: 'R' });
+    expect(readCookie(document.cookie, ACCESS)).toBe('A');
+    expect(readCookie(document.cookie, REFRESH)).toBe('R');
+    expect(localStorage.getItem(ACCESS)).toBeNull();
+    auth.clearTokens();
+    expect(readCookie(document.cookie, ACCESS)).toBeNull();
+  });
+
+  it('adopts a session an older build kept in localStorage, once', async () => {
+    localStorage.setItem(ACCESS, 'oldA');
+    localStorage.setItem(REFRESH, 'oldR');
+    const auth = await loadAuth();
+    expect(auth.getToken()).toBe('oldA');
+    expect(auth.getRefreshToken()).toBe('oldR');
+    expect(localStorage.getItem(ACCESS)).toBeNull();
+    expect(readCookie(document.cookie, REFRESH)).toBe('oldR');
+  });
+
+  it('keeps the API key in localStorage', async () => {
+    const auth = await loadAuth();
+    auth.setApiKeyPersist('key-1');
+    expect(localStorage.getItem('cfg.auth.api_key')).toBe('key-1');
+    expect(document.cookie).not.toContain('api_key');
+  });
+});

package/src/_api/generated/helpers/auth.ts

@@ -25,6 +25,12 @@ interface KVStore {
   set(key: string, value: string | null): void;
 }
 
+/** Seconds until a JWT's `exp`, for the cookie lifetime; undefined when it has none. */
+function secondsUntilExp(token: string): number | undefined {
+  const exp = jwtExpMs(token);
+  return exp === null ? undefined : Math.max(1, Math.floor((exp - Date.now()) / 1000));
+}
+
 // Every read and write goes through the registry's guarded storage: SSR-safe,
 // private-mode and quota safe, and a key written under an older spelling is
 // moved to its `cfg.auth.*` name on first read.
@@ -40,17 +46,22 @@ function backendFor(mode: StorageMode): KVStore {
     get: (key) => storage.read(key, store),
     set(key, value) {
       if (value === null) storage.remove(key, store);
-      else storage.write(key, value, store);
+      // The refresh cookie lives as long as the refresh token; everything else takes the default.
+      else storage.write(key, value, store, store === 'cookie' && key === REFRESH_KEY ? { maxAgeSeconds: secondsUntilExp(value) } : undefined);
     },
   };
 }
 
 /**
- * The session backend. `localStorage` by default and for every login path.
+ * The session backend: a cookie shared by every subdomain of the registrable
+ * domain (`Domain=example.com`, found by asking the browser), so signing in on
+ * `my.example.com` signs in `example.com` and `studio.example.com`, and so
+ * Next.js `cookies()` can read the token during SSR. Django never reads this
+ * cookie (the API authenticates the `Authorization` header), so it is no CSRF
+ * surface.
  *
- * `setStorageMode` exists for a host that must relocate the whole session once
- * at bootstrap — e.g. 'cookie' so Next.js `cookies()` can read the token during
- * SSR. It is NOT a per-login switch: this value lives in module memory and
+ * `setStorageMode('localStorage')` opts a host out, once at bootstrap. It is NOT
+ * a per-login switch: this value lives in module memory and
  * resets to the default on every page load, so tokens written to a non-default
  * backend after startup would be stranded — present in the browser, invisible
  * to the client, and every request would go out unauthenticated.
@@ -59,8 +70,27 @@ function backendFor(mode: StorageMode): KVStore {
  * minting the refresh token; the client just stores whatever it
  * was given, in one place.
  */
-let _storageMode: StorageMode = 'localStorage';
+let _storageMode: StorageMode = 'cookie';
 let _storage: KVStore = backendFor(_storageMode);
+// The API key is per browser, not per domain family: always localStorage.
+const _apiKeyStore: KVStore = backendFor('localStorage');
+
+/** One-time move of a session an older build kept in localStorage into the shared cookie. */
+function adoptLegacySession(): void {
+  if (!isBrowser || _storageMode !== 'cookie') return;
+  try {
+    if (_storage.get(ACCESS_KEY) !== null || _storage.get(REFRESH_KEY) !== null) return;
+    const legacy = backendFor('localStorage');
+    const access = legacy.get(ACCESS_KEY);
+    const refresh = legacy.get(REFRESH_KEY);
+    if (access === null && refresh === null) return;
+    if (access !== null) _storage.set(ACCESS_KEY, access);
+    if (refresh !== null) _storage.set(REFRESH_KEY, refresh);
+    legacy.set(ACCESS_KEY, null);
+    legacy.set(REFRESH_KEY, null);
+  } catch {}
+}
+adoptLegacySession();
 
 /** Detect locale from `NEXT_LOCALE` cookie or `navigator.language`. */
 function detectLocale(): string | null {
@@ -277,6 +307,15 @@ function ensureStorageSync(): void {
     }
   });
   window.addEventListener(SESSION_SYNC_EVENT, () => notifySessionChanged());
+  // Cookies fire no `storage` event: a sign-in or sign-out on another subdomain is
+  // picked up when this page is looked at again (or at once where `cookieStore` exists).
+  window.addEventListener('focus', () => notifySessionChanged());
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'visible') notifySessionChanged();
+  });
+  try {
+    (window as unknown as { cookieStore?: EventTarget }).cookieStore?.addEventListener('change', () => notifySessionChanged());
+  } catch {}
 }
 
 /**
@@ -366,6 +405,16 @@ export const auth = {
     notifySessionChanged();
   },
 
+  // ── Shared cookie domain ──────────────────────────────────────────
+  /** `'auto'` (default): the registrable domain of the page. A domain forces it; `null` keeps
+   *  cookies host-only (no sign-in sharing between subdomains). Call before sign-in. */
+  setCookieDomain(domain: 'auto' | string | null): void {
+    storage.setCookieDomain(domain === null ? false : domain);
+    notifySessionChanged();
+  },
+  /** The `Domain` the session cookie is written with; `null` = host-only. */
+  getCookieDomain(): string | null { return storage.cookieDomain(); },
+
   // ── Bearer token ──────────────────────────────────────────────────
   getToken(): string | null { return _storage.get(ACCESS_KEY); },
   setToken(token: string | null): void {
@@ -447,14 +496,14 @@ export const auth = {
 
   // ── API key ───────────────────────────────────────────────────────
   getApiKey(): string | null {
-    return _apiKeyOverride ?? _storage.get(API_KEY_KEY) ?? defaultApiKey();
+    return _apiKeyOverride ?? _apiKeyStore.get(API_KEY_KEY) ?? defaultApiKey();
   },
   setApiKey(key: string | null): void { _apiKeyOverride = key; },
   setApiKeyPersist(key: string | null): void {
     _apiKeyOverride = key;
-    _storage.set(API_KEY_KEY, key);
+    _apiKeyStore.set(API_KEY_KEY, key);
   },
-  clearApiKey(): void { _apiKeyOverride = null; _storage.set(API_KEY_KEY, null); },
+  clearApiKey(): void { _apiKeyOverride = null; _apiKeyStore.set(API_KEY_KEY, null); },
 
   // ── Locale ────────────────────────────────────────────────────────
   getLocale(): string | null { return _localeOverride ?? detectLocale(); },

package/src/_api/generated/helpers/keys.ts

@@ -40,8 +40,8 @@ const f = (
 
 /** Every key the framework writes. No legacy spellings are read: old keys are simply ignored. */
 export const CFG_KEYS = {
-  accessToken: k('cfg.auth.access_token', 'local', true),
-  refreshToken: k('cfg.auth.refresh_token', 'local', true),
+  accessToken: k('cfg.auth.access_token', 'cookie', true),
+  refreshToken: k('cfg.auth.refresh_token', 'cookie', true),
   apiKey: k('cfg.auth.api_key', 'local', true),
   email: k('cfg.auth.email', 'local', false),
   emailTs: k('cfg.auth.email_ts', 'local', false),
@@ -90,6 +90,17 @@ export interface StorageOptions {
   readonly families?: Readonly<Record<string, FamilySpec>>;
   /** Cookie lifetime for the `cookie` store. Default 30 days. */
   readonly cookieMaxAgeSeconds?: number;
+  /**
+   * Cookie `Domain`. `'auto'` (default): the registrable domain of the page, so every subdomain
+   * shares the cookie (`example.com` for `my.example.com`). A string forces a domain; `false`
+   * keeps cookies host-only.
+   */
+  readonly cookieDomain?: 'auto' | string | false;
+}
+
+export interface WriteOptions {
+  /** Cookie store: lifetime of this write. Default: the owner's `cookieMaxAgeSeconds`. */
+  readonly maxAgeSeconds?: number;
 }
 
 export interface GuardedStorage {
@@ -102,7 +113,7 @@ export interface GuardedStorage {
   isValid(key: string): boolean;
   read(key: string, store?: KeyStore): string | null;
   /** True when the value reached the browser's storage; false means it is held in memory for this page only. */
-  write(key: string, value: string, store?: KeyStore): boolean;
+  write(key: string, value: string, store?: KeyStore, options?: WriteOptions): boolean;
   /** Removes the key. */
   remove(key: string, store?: KeyStore): void;
   readJSON<T>(key: string, store?: KeyStore): T | null;
@@ -111,12 +122,48 @@ export interface GuardedStorage {
   keys(store?: Exclude<KeyStore, 'cookie'>): string[];
   /** Sign-out: removes the `personal` keys. `{ all: true }` removes everything under this owner. */
   clearAll(options?: { all?: boolean }): void;
+  /** Cookie store: change the `Domain` policy (`'auto'`, a domain, or `false` for host-only cookies). */
+  setCookieDomain(domain: 'auto' | string | false): void;
+  /** The `Domain` cookies are written with right now; `null` means host-only. */
+  cookieDomain(): string | null;
   /** Cross-tab: calls `listener` with the new value when ANOTHER tab changes `key`. Cookies fire no events. */
   onChange(key: string, listener: (value: string | null) => void, store?: Exclude<KeyStore, 'cookie'>): () => void;
 }
 
 const hasWindow = () => typeof window !== 'undefined';
 
+const domainByHost = new Map<string, string | null>();
+
+/**
+ * The broadest domain this page may set cookies on (`example.com` for `my.example.com`,
+ * `example.co.uk` for `a.example.co.uk`), found by asking the browser: it refuses a cookie for a
+ * public suffix, so no suffix list lives in our code. `null` for an IP, `localhost`, a single label
+ * or when cookies are blocked (the cookie is then host-only).
+ */
+function detectCookieDomain(): string | null {
+  if (!hasWindow() || typeof document === 'undefined') return null;
+  const host = window.location.hostname.toLowerCase();
+  if (!host || !host.includes('.') || host.includes(':') || /^[0-9.]+$/.test(host)) return null;
+  const cached = domainByHost.get(host);
+  if (cached !== undefined) return cached;
+  const labels = host.split('.');
+  const secure = window.location.protocol === 'https:' ? '; Secure' : '';
+  let found: string | null = null;
+  try {
+    for (let i = labels.length - 2; i >= 0 && found === null; i -= 1) {
+      const candidate = labels.slice(i).join('.');
+      const probe = 'cfg_probe_' + Math.random().toString(36).slice(2);
+      document.cookie = probe + '=1; Domain=' + candidate + '; Path=/; Max-Age=30; SameSite=Lax' + secure;
+      if (document.cookie.includes(probe + '=1')) found = candidate;
+      document.cookie = probe + '=; Domain=' + candidate + '; Path=/; Max-Age=0; SameSite=Lax' + secure;
+    }
+  } catch {
+    found = null;
+  }
+  domainByHost.set(host, found);
+  return found;
+}
+
 function nativeStorage(store: 'local' | 'session'): Storage | null {
   if (!hasWindow()) return null;
   try {
@@ -145,6 +192,15 @@ export function createStorage(owner: string, options: StorageOptions = {}): Guar
   const prefix = `${owner}.`;
   const pattern = owner === 'cfg' ? /^cfg(\.[a-z0-9_]+)+$/ : new RegExp(`^(cfg|${owner})(\\.[a-z0-9_]+)+$`);
   const cookieMaxAge = options.cookieMaxAgeSeconds ?? 60 * 60 * 24 * 30;
+  let cookiePolicy: 'auto' | string | false = options.cookieDomain ?? 'auto';
+  const resolveCookieDomain = (): string | null =>
+    cookiePolicy === false ? null : cookiePolicy === 'auto' ? detectCookieDomain() : cookiePolicy;
+  // A cookie is identified by name AND Domain: expire the twin without a domain and the one with it.
+  const expireCookie = (key: string, domain: string | null) => {
+    const secure = window.location.protocol === 'https:' ? '; Secure' : '';
+    document.cookie =
+      encodeURIComponent(key) + '=; Path=/; Max-Age=0; SameSite=Lax' + (domain ? '; Domain=' + domain : '') + secure;
+  };
   const specs = Object.values(options.keys ?? {});
   const families = Object.values(options.families ?? {});
   const specByKey = new Map<string, KeySpec[]>();
@@ -186,12 +242,16 @@ export function createStorage(owner: string, options: StorageOptions = {}): Guar
     return memory[store].get(key) ?? null;
   }
 
-  function rawSet(store: KeyStore, key: string, value: string): boolean {
+  function rawSet(store: KeyStore, key: string, value: string, maxAgeSeconds?: number): boolean {
     if (!hasWindow()) return false;
     try {
       if (store === 'cookie') {
         const secure = window.location.protocol === 'https:' ? '; Secure' : '';
-        document.cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value)}; Path=/; Max-Age=${cookieMaxAge}; SameSite=Lax${secure}`;
+        const domain = resolveCookieDomain();
+        const domainPart = domain ? `; Domain=${domain}` : '';
+        document.cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value)}; Path=/; Max-Age=${Math.max(1, Math.floor(maxAgeSeconds ?? cookieMaxAge))}; SameSite=Lax${domainPart}${secure}`;
+        // A host-only cookie written earlier would shadow the shared one: drop that twin.
+        if (domain) expireCookie(key, null);
         if (rawGet('cookie', key) === value && !memory.cookie.has(key)) return true;
         memory.cookie.set(key, value);
         return false;
@@ -212,8 +272,9 @@ export function createStorage(owner: string, options: StorageOptions = {}): Guar
     if (!hasWindow()) return;
     try {
       if (store === 'cookie') {
-        const secure = window.location.protocol === 'https:' ? '; Secure' : '';
-        document.cookie = `${encodeURIComponent(key)}=; Path=/; Max-Age=0; SameSite=Lax${secure}`;
+        expireCookie(key, null);
+        const domain = resolveCookieDomain();
+        if (domain) expireCookie(key, domain);
       } else {
         nativeStorage(store)?.removeItem(key);
       }
@@ -265,10 +326,10 @@ export function createStorage(owner: string, options: StorageOptions = {}): Guar
       const target = resolveStore(key, store);
       return rawGet(target, key);
     },
-    write(key, value, store) {
+    write(key, value, store, writeOptions) {
       assertOwned(key);
       const target = resolveStore(key, store);
-      return rawSet(target, key, value);
+      return rawSet(target, key, value, writeOptions?.maxAgeSeconds);
     },
     remove(key, store) {
       assertOwned(key);
@@ -306,6 +367,10 @@ export function createStorage(owner: string, options: StorageOptions = {}): Guar
         for (const name of cookieNames()) if (name.startsWith(prefix)) rawRemove('cookie', name);
       }
     },
+    setCookieDomain(domain) {
+      cookiePolicy = domain;
+    },
+    cookieDomain: resolveCookieDomain,
     onChange(key, listener, store = 'local') {
       assertValid(key);
       if (!hasWindow()) return () => {};

package/src/cookies.ts

@@ -0,0 +1,22 @@
+/**
+ * Server-safe cookie header parsing, for SSR code that has the raw `Cookie` header
+ * (Next.js `headers()`, a Node request) and wants the shared session cookie.
+ * No DOM, no dependencies.
+ */
+
+/** The value of cookie `name` in a `Cookie` request header, or `null`. */
+export function readCookie(cookieHeader: string | null | undefined, name: string): string | null {
+  if (!cookieHeader) return null;
+  const wanted = encodeURIComponent(name);
+  for (const part of cookieHeader.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    if (part.slice(0, eq).trim() !== wanted) continue;
+    try {
+      return decodeURIComponent(part.slice(eq + 1).trim());
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}

package/src/storage.ts

@@ -5,6 +5,7 @@
  * read/write or `createStorage('<owner>')` import this, not the generated SDK.
  * The source is the generated `helpers/keys.ts`.
  */
+export { readCookie } from './cookies';
 export {
   CFG_FAMILIES,
   CFG_KEYS,
@@ -18,4 +19,5 @@ export type {
   KeySpec,
   KeyStore,
   StorageOptions,
+  WriteOptions,
 } from './_api/generated/helpers/keys';