@djangocfg/api 2.1.582 → 2.1.584

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

@@ -5,10 +5,14 @@
 // DO NOT EDIT — re-run `make gen`.
 
 import { APIError } from './errors';
+import { cfgStorage, createStorage, type KeyStore } from './keys';
 
-const ACCESS_KEY = 'cfg.access_token';
-const REFRESH_KEY = 'cfg.refresh_token';
-const API_KEY_KEY = 'cfg.api_key';
+const ACCESS_KEY = 'cfg.auth.access_token';
+const REFRESH_KEY = 'cfg.auth.refresh_token';
+const API_KEY_KEY = 'cfg.auth.api_key';
+
+// The framework's own keys use the shared registry; a custom owner gets the same guarded helpers.
+const storage = 'cfg' === 'cfg' ? cfgStorage : createStorage('cfg');
 
 const isBrowser = typeof window !== 'undefined';
 
@@ -21,68 +25,24 @@ interface KVStore {
   set(key: string, value: string | null): void;
 }
 
-const localStorageBackend: KVStore = {
-  get(key) {
-    if (!isBrowser) return null;
-    try { return window.localStorage.getItem(key); } catch { return null; }
-  },
-  set(key, value) {
-    if (!isBrowser) return;
-    try {
-      if (value === null) window.localStorage.removeItem(key);
-      else window.localStorage.setItem(key, value);
-    } catch {}
-  },
-};
-
-const sessionStorageBackend: KVStore = {
-  get(key) {
-    if (!isBrowser) return null;
-    try { return window.sessionStorage.getItem(key); } catch { return null; }
-  },
-  set(key, value) {
-    if (!isBrowser) return;
-    try {
-      if (value === null) window.sessionStorage.removeItem(key);
-      else window.sessionStorage.setItem(key, value);
-    } catch {}
-  },
-};
-
-/** 30 days, matches typical refresh-token lifetime. */
-const COOKIE_MAX_AGE = 60 * 60 * 24 * 30;
-
-const cookieBackend: KVStore = {
-  get(key) {
-    if (!isBrowser) return null;
-    try {
-      const re = new RegExp(`(?:^|;\\s*)${encodeURIComponent(key)}=([^;]*)`);
-      const m = document.cookie.match(re);
-      const value = m?.[1];
-      return value === undefined ? null : decodeURIComponent(value);
-    } catch { return null; }
-  },
-  set(key, value) {
-    if (!isBrowser) return;
-    try {
-      const k = encodeURIComponent(key);
-      const secure = window.location.protocol === 'https:' ? '; Secure' : '';
-      if (value === null) {
-        document.cookie = `${k}=; Path=/; Max-Age=0; SameSite=Lax${secure}`;
-      } else {
-        const v = encodeURIComponent(value);
-        document.cookie = `${k}=${v}; Path=/; Max-Age=${COOKIE_MAX_AGE}; SameSite=Lax${secure}`;
-      }
-    } catch {}
-  },
+// 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.
+const STORE_OF: Record<StorageMode, KeyStore> = {
+  localStorage: 'local',
+  sessionStorage: 'session',
+  cookie: 'cookie',
 };
 
 function backendFor(mode: StorageMode): KVStore {
-  return mode === 'cookie'
-    ? cookieBackend
-    : mode === 'sessionStorage'
-      ? sessionStorageBackend
-      : localStorageBackend;
+  const store = STORE_OF[mode];
+  return {
+    get: (key) => storage.read(key, store),
+    set(key, value) {
+      if (value === null) storage.remove(key, store);
+      else storage.write(key, value, store);
+    },
+  };
 }
 
 /**
@@ -96,7 +56,7 @@ function backendFor(mode: StorageMode): KVStore {
  * to the client, and every request would go out unauthenticated.
  *
  * Session LENGTH is therefore not a client concern. The server decides it when
- * minting the refresh token (`remember_me`); the client just stores whatever it
+ * minting the refresh token; the client just stores whatever it
  * was given, in one place.
  */
 let _storageMode: StorageMode = 'localStorage';
@@ -411,10 +371,13 @@ export const auth = {
     // Clear every backend, not just the active one. Sign-out must leave nothing
     // behind anywhere — including tokens an older build stranded in
     // sessionStorage — or the next page load could resurrect a dead session.
-    for (const backend of [localStorageBackend, sessionStorageBackend, cookieBackend]) {
+    for (const mode of ['localStorage', 'sessionStorage', 'cookie'] as const) {
+      const backend = backendFor(mode);
       backend.set(ACCESS_KEY, null);
       backend.set(REFRESH_KEY, null);
     }
+    // The rest of the signed-in user's keys (profile cache, OAuth leftovers) go with the tokens.
+    storage.clearAll();
     notifySessionChanged();
   },
   /** Session-aware: token PRESENT and not past its `exp` (or a live refresh
@@ -679,7 +642,7 @@ function dpopEnabled(): boolean {
   } catch { return false; }
 }
 
-const _DPOP_DB = 'cfg-auth';
+const _DPOP_DB = 'cfg.auth.dpop';
 const _DPOP_STORE = 'keys';
 const _DPOP_KEY_ID = 'dpop-ec-p256';
 

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

@@ -9,6 +9,18 @@ export {
   CookieStorageAdapter,
 } from './storage';
 export { APIError, NetworkError } from './errors';
+export {
+  CFG_KEYS,
+  CFG_FAMILIES,
+  cfgStorage,
+  createStorage,
+  normalizeSegment,
+  type KeySpec,
+  type FamilySpec,
+  type KeyStore,
+  type GuardedStorage,
+  type StorageOptions,
+} from './keys';
 export {
   APILogger,
   defaultLogger,

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

@@ -0,0 +1,327 @@
+// AUTO-GENERATED by django_generator / ts_extras.wrapper
+// Browser-storage key registry: one scheme, guarded access.
+// DO NOT EDIT — re-run `make gen`.
+//
+// Rules for agents and apps: @docs/STORAGE_KEYS.md in @djangocfg/api.
+//
+// Scheme: `<owner>.<area>.<name>` — lower case, dots between levels,
+// `snake_case` inside a level. The framework's owner is `cfg`; an app picks its
+// own with `createStorage('<owner>')`. Third-party keys (a library's own
+// prefix, `NEXT_LOCALE`) are not ours to rename and stay as they are.
+
+export type KeyStore = 'local' | 'session' | 'cookie';
+
+export interface KeySpec {
+  /** The canonical key. */
+  readonly key: string;
+  readonly store: KeyStore;
+  /** Removed by `clearAll()` (sign-out). Preferences are kept. */
+  readonly personal: boolean;
+}
+
+export interface FamilySpec {
+  /** Canonical prefix ending in a dot; the id is appended in normalised form. */
+  readonly prefix: string;
+  readonly store: 'local' | 'session';
+  readonly personal: boolean;
+}
+
+const k = (
+  key: string,
+  store: KeyStore,
+  personal: boolean,
+): KeySpec => ({ key, store, personal });
+
+const f = (
+  prefix: string,
+  store: 'local' | 'session',
+  personal: boolean,
+): FamilySpec => ({ prefix, store, personal });
+
+/** 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),
+  apiKey: k('cfg.auth.api_key', 'local', true),
+  email: k('cfg.auth.email', 'local', false),
+  emailTs: k('cfg.auth.email_ts', 'local', false),
+  redirectUrl: k('cfg.auth.redirect_url', 'session', true),
+  redirectUrlTs: k('cfg.auth.redirect_url_ts', 'session', true),
+  oauthState: k('cfg.auth.oauth_state', 'session', true),
+  oauthProvider: k('cfg.auth.oauth_provider', 'session', true),
+  profileCache: k('cfg.profile.cache', 'local', true),
+  monitorSessionId: k('cfg.monitor.session_id', 'local', false),
+  monitorSessionCookie: k('cfg.monitor.session_id', 'cookie', false),
+  monitorDebug: k('cfg.monitor.debug', 'local', false),
+  uiTabId: k('cfg.ui.tab_id', 'session', false),
+  uiRouterSerial: k('cfg.ui.router_serial', 'session', false),
+  uiState: k('cfg.ui.state', 'local', false),
+  chatSpeechLanguage: k('cfg.chat.speech_language', 'local', false),
+  chatRecentTools: k('cfg.chat.recent_tools', 'local', false),
+  formsSpeechDebug: k('cfg.forms.speech_debug', 'local', false),
+  formsSpeechPrefs: k('cfg.forms.speech_prefs', 'local', false),
+  agentPlaygroundApiKeyId: k('cfg.agent.playground_api_key_id', 'session', true),
+  agentPlaygroundBearer: k('cfg.agent.playground_bearer', 'session', true),
+  agentEndpointDoc: k('cfg.agent.endpoint_doc', 'session', false),
+} as const satisfies Record<string, KeySpec>;
+
+/** Keys with a caller-supplied id part: one per room, tree, endpoint. */
+export const CFG_FAMILIES = {
+  chatDraft: f('cfg.chat.draft.', 'session', true),
+  dataTree: f('cfg.data.tree.', 'local', false),
+  agentEndpointDraft: f('cfg.agent.endpoint_draft.', 'local', false),
+} as const satisfies Record<string, FamilySpec>;
+
+const OWNER_RE = /^[a-z][a-z0-9_]*$/;
+
+/** One segment of a key: lower case, `[a-z0-9_]`, anything else folded to `_`. */
+export function normalizeSegment(raw: string): string {
+  return raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+export interface StorageOptions {
+  /** Named keys of this owner. */
+  readonly keys?: Readonly<Record<string, KeySpec>>;
+  readonly families?: Readonly<Record<string, FamilySpec>>;
+  /** Cookie lifetime for the `cookie` store. Default 30 days. */
+  readonly cookieMaxAgeSeconds?: number;
+}
+
+export interface GuardedStorage {
+  readonly owner: string;
+  /** Builds `<owner>.<part>.<part>` from free-form parts; throws if a part is empty. */
+  key(...parts: string[]): string;
+  /** Builds a family member key: the prefix plus the normalised id. */
+  familyKey(family: FamilySpec, id: string): string;
+  /** `^(cfg|<owner>)(\.[a-z0-9_]+)+$`. */
+  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;
+  /** Removes the key. */
+  remove(key: string, store?: KeyStore): void;
+  readJSON<T>(key: string, store?: KeyStore): T | null;
+  writeJSON(key: string, value: unknown, store?: KeyStore): boolean;
+  /** Keys this owner holds in `store`. */
+  keys(store?: Exclude<KeyStore, 'cookie'>): string[];
+  /** Sign-out: removes the `personal` keys. `{ all: true }` removes everything under this owner. */
+  clearAll(options?: { all?: boolean }): void;
+  /** 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';
+
+function nativeStorage(store: 'local' | 'session'): Storage | null {
+  if (!hasWindow()) return null;
+  try {
+    return store === 'session' ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function cookieNames(): string[] {
+  if (!hasWindow()) return [];
+  try {
+    return document.cookie
+      .split('; ')
+      .map((part) => decodeURIComponent(part.split('=')[0] ?? ''))
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function createStorage(owner: string, options: StorageOptions = {}): GuardedStorage {
+  if (!OWNER_RE.test(owner)) {
+    throw new TypeError(`createStorage: owner "${owner}" must match ${OWNER_RE}`);
+  }
+  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;
+  const specs = Object.values(options.keys ?? {});
+  const families = Object.values(options.families ?? {});
+  const specByKey = new Map<string, KeySpec[]>();
+  for (const spec of specs) specByKey.set(spec.key, [...(specByKey.get(spec.key) ?? []), spec]);
+  // Held in memory when the browser refuses a write (quota, private mode), so the page still works until reload.
+  const memory: Record<KeyStore, Map<string, string>> = {
+    local: new Map(),
+    session: new Map(),
+    cookie: new Map(),
+  };
+
+  const isValid = (key: string) => pattern.test(key);
+  const assertValid = (key: string) => {
+    if (!isValid(key)) throw new TypeError(`storage key "${key}" must match ${pattern}`);
+  };
+  const assertOwned = (key: string) => {
+    assertValid(key);
+    if (!key.startsWith(prefix)) throw new TypeError(`storage key "${key}" is not owned by "${owner}"`);
+  };
+
+  function rawGet(store: KeyStore, key: string): string | null {
+    if (!hasWindow()) return null;
+    if (store === 'cookie') {
+      try {
+        const escaped = encodeURIComponent(key).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${escaped}=([^;]*)`));
+        if (match?.[1] !== undefined) return decodeURIComponent(match[1]);
+      } catch {
+        /* fall through to memory */
+      }
+      return memory.cookie.get(key) ?? null;
+    }
+    try {
+      const value = nativeStorage(store)?.getItem(key) ?? null;
+      if (value !== null) return value;
+    } catch {
+      /* fall through to memory */
+    }
+    return memory[store].get(key) ?? null;
+  }
+
+  function rawSet(store: KeyStore, key: string, value: string): 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}`;
+        if (rawGet('cookie', key) === value && !memory.cookie.has(key)) return true;
+        memory.cookie.set(key, value);
+        return false;
+      }
+      const native = nativeStorage(store);
+      if (!native) throw new Error('storage unavailable');
+      native.setItem(key, value);
+      memory[store].delete(key);
+      return true;
+    } catch {
+      memory[store].set(key, value);
+      return false;
+    }
+  }
+
+  function rawRemove(store: KeyStore, key: string): void {
+    memory[store].delete(key);
+    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}`;
+      } else {
+        nativeStorage(store)?.removeItem(key);
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function resolveStore(key: string, store?: KeyStore): KeyStore {
+    return store ?? specByKey.get(key)?.[0]?.store ?? 'local';
+  }
+
+  function listKeys(store: 'local' | 'session', startsWith: string): string[] {
+    const out: string[] = [];
+    try {
+      const native = nativeStorage(store);
+      if (native) {
+        for (let i = 0; i < native.length; i += 1) {
+          const name = native.key(i);
+          if (name?.startsWith(startsWith)) out.push(name);
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+    for (const name of memory[store].keys()) if (name.startsWith(startsWith) && !out.includes(name)) out.push(name);
+    return out;
+  }
+
+  const familyKey = (family: FamilySpec, id: string) => {
+    const part = normalizeSegment(id);
+    if (!part) throw new TypeError('storage family id is empty after normalisation');
+    return family.prefix + part;
+  };
+
+  const api: GuardedStorage = {
+    owner,
+    key(...parts) {
+      const segments = parts.map(normalizeSegment);
+      if (segments.length === 0 || segments.some((segment) => !segment)) {
+        throw new TypeError(`storage key parts must be non-empty: ${JSON.stringify(parts)}`);
+      }
+      return `${prefix}${segments.join('.')}`;
+    },
+    familyKey,
+    isValid,
+    read(key, store) {
+      assertValid(key);
+      const target = resolveStore(key, store);
+      return rawGet(target, key);
+    },
+    write(key, value, store) {
+      assertOwned(key);
+      const target = resolveStore(key, store);
+      return rawSet(target, key, value);
+    },
+    remove(key, store) {
+      assertOwned(key);
+      const target = resolveStore(key, store);
+      rawRemove(target, key);
+    },
+    readJSON<T>(key: string, store?: KeyStore): T | null {
+      const raw = api.read(key, store);
+      if (raw === null) return null;
+      try {
+        return JSON.parse(raw) as T;
+      } catch {
+        return null;
+      }
+    },
+    writeJSON(key, value, store) {
+      return api.write(key, JSON.stringify(value), store);
+    },
+    keys(store = 'local') {
+      return listKeys(store, prefix);
+    },
+    clearAll({ all = false } = {}) {
+      for (const spec of specs) {
+        if (!all && !spec.personal) continue;
+        rawRemove(spec.store, spec.key);
+      }
+      for (const family of families) {
+        if (!all && !family.personal) continue;
+        for (const name of listKeys(family.store, family.prefix)) rawRemove(family.store, name);
+      }
+      if (all) {
+        for (const store of ['local', 'session'] as const) {
+          for (const name of listKeys(store, prefix)) rawRemove(store, name);
+        }
+        for (const name of cookieNames()) if (name.startsWith(prefix)) rawRemove('cookie', name);
+      }
+    },
+    onChange(key, listener, store = 'local') {
+      assertValid(key);
+      if (!hasWindow()) return () => {};
+      const handler = (event: StorageEvent) => {
+        if (event.storageArea !== nativeStorage(store)) return;
+        if (event.key === null || event.key === key) listener(event.key === null ? null : event.newValue);
+      };
+      window.addEventListener('storage', handler);
+      return () => window.removeEventListener('storage', handler);
+    },
+  };
+  return api;
+}
+
+/** The framework's own storage: every `cfg.*` key. */
+export const cfgStorage: GuardedStorage = createStorage('cfg', {
+  keys: CFG_KEYS,
+  families: CFG_FAMILIES,
+});
+

package/src/_api/generated/openapi.json

@@ -2098,11 +2098,6 @@
             "type": "string",
             "format": "uri",
             "description": "Same redirect_uri used in authorize request. If not provided, uses config's site_url + callback_path"
-          },
-          "remember_me": {
-            "type": "boolean",
-            "default": false,
-            "description": "Keep this browser signed in for 30 days"
           }
         },
         "required": [
@@ -2282,10 +2277,6 @@
           "should_prompt_2fa": {
             "type": "boolean",
             "description": "True if user should be prompted to enable 2FA"
-          },
-          "persistent_session": {
-            "type": "boolean",
-            "description": "Whether this login should persist across browser restarts"
           }
         }
       },
@@ -2399,11 +2390,6 @@
             "type": "string",
             "format": "uri",
             "description": "Source URL for tracking login (e.g., https://my.djangocfg.com)"
-          },
-          "remember_me": {
-            "type": "boolean",
-            "default": false,
-            "description": "Keep this browser signed in for 30 days"
           }
         },
         "required": [
@@ -2456,10 +2442,6 @@
           "should_prompt_2fa": {
             "type": "boolean",
             "description": "Whether user should be prompted to enable 2FA"
-          },
-          "persistent_session": {
-            "type": "boolean",
-            "description": "Whether this login should persist across browser restarts"
           }
         }
       },
@@ -2490,13 +2472,8 @@
       },
       "PasswordLoginRequest": {
         "type": "object",
-        "description": "Validate email+password against live accounts only.\n\nSubclasses SimpleJWT so the field/validation contract stays theirs, but\nreplaces ``validate()`` — the token pair itself is minted by the view via\n``mint_tokens_for_request`` so the DPoP binding and remembered-session\nlifetime match OTP, OAuth and TOTP exactly.",
+        "description": "Validate email+password against live accounts only.\n\nSubclasses SimpleJWT so the field/validation contract stays theirs, but\nreplaces ``validate()`` — the token pair itself is minted by the view via\n``mint_tokens_for_request`` so the DPoP binding and token\nlifetime match OTP, OAuth and TOTP exactly.",
         "properties": {
-          "remember_me": {
-            "type": "boolean",
-            "default": false,
-            "description": "Keep this browser signed in for 30 days"
-          },
           "email": {
             "type": "string",
             "format": "email",
@@ -2558,10 +2535,6 @@
           "should_prompt_2fa": {
             "type": "boolean",
             "description": "Whether user should be prompted to enable 2FA"
-          },
-          "persistent_session": {
-            "type": "boolean",
-            "description": "Whether this login should persist across browser restarts"
           }
         }
       },
@@ -3029,10 +3002,6 @@
             ],
             "description": "User profile data"
           },
-          "persistent_session": {
-            "type": "boolean",
-            "description": "Whether this login should persist across browser restarts"
-          },
           "remaining_backup_codes": {
             "type": "integer",
             "description": "Number of remaining backup codes (if backup code was used)"
@@ -3045,7 +3014,6 @@
         "required": [
           "access_token",
           "message",
-          "persistent_session",
           "refresh_token",
           "user"
         ]