@djangocfg/api 2.1.582 → 2.1.583

package/dist/storage.mjs

@@ -0,0 +1,248 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/_api/generated/helpers/keys.ts
+var k = /* @__PURE__ */ __name((key, store, personal) => ({ key, store, personal }), "k");
+var f = /* @__PURE__ */ __name((prefix, store, personal) => ({ prefix, store, personal }), "f");
+var 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),
+  oauthRememberMe: k("cfg.auth.oauth_remember_me", "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)
+};
+var CFG_FAMILIES = {
+  chatDraft: f("cfg.chat.draft.", "session", true),
+  dataTree: f("cfg.data.tree.", "local", false),
+  agentEndpointDraft: f("cfg.agent.endpoint_draft.", "local", false)
+};
+var OWNER_RE = /^[a-z][a-z0-9_]*$/;
+function normalizeSegment(raw) {
+  return raw.trim().toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+}
+__name(normalizeSegment, "normalizeSegment");
+var hasWindow = /* @__PURE__ */ __name(() => typeof window !== "undefined", "hasWindow");
+function nativeStorage(store) {
+  if (!hasWindow()) return null;
+  try {
+    return store === "session" ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+__name(nativeStorage, "nativeStorage");
+function cookieNames() {
+  if (!hasWindow()) return [];
+  try {
+    return document.cookie.split("; ").map((part) => decodeURIComponent(part.split("=")[0] ?? "")).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+__name(cookieNames, "cookieNames");
+function createStorage(owner, options = {}) {
+  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 = /* @__PURE__ */ new Map();
+  for (const spec of specs) specByKey.set(spec.key, [...specByKey.get(spec.key) ?? [], spec]);
+  const memory = {
+    local: /* @__PURE__ */ new Map(),
+    session: /* @__PURE__ */ new Map(),
+    cookie: /* @__PURE__ */ new Map()
+  };
+  const isValid = /* @__PURE__ */ __name((key) => pattern.test(key), "isValid");
+  const assertValid = /* @__PURE__ */ __name((key) => {
+    if (!isValid(key)) throw new TypeError(`storage key "${key}" must match ${pattern}`);
+  }, "assertValid");
+  const assertOwned = /* @__PURE__ */ __name((key) => {
+    assertValid(key);
+    if (!key.startsWith(prefix)) throw new TypeError(`storage key "${key}" is not owned by "${owner}"`);
+  }, "assertOwned");
+  function rawGet(store, key) {
+    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] !== void 0) return decodeURIComponent(match[1]);
+      } catch {
+      }
+      return memory.cookie.get(key) ?? null;
+    }
+    try {
+      const value = nativeStorage(store)?.getItem(key) ?? null;
+      if (value !== null) return value;
+    } catch {
+    }
+    return memory[store].get(key) ?? null;
+  }
+  __name(rawGet, "rawGet");
+  function rawSet(store, key, value) {
+    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;
+    }
+  }
+  __name(rawSet, "rawSet");
+  function rawRemove(store, key) {
+    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 {
+    }
+  }
+  __name(rawRemove, "rawRemove");
+  function resolveStore(key, store) {
+    return store ?? specByKey.get(key)?.[0]?.store ?? "local";
+  }
+  __name(resolveStore, "resolveStore");
+  function listKeys(store, startsWith) {
+    const out = [];
+    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 {
+    }
+    for (const name of memory[store].keys()) if (name.startsWith(startsWith) && !out.includes(name)) out.push(name);
+    return out;
+  }
+  __name(listKeys, "listKeys");
+  const familyKey = /* @__PURE__ */ __name((family, id) => {
+    const part = normalizeSegment(id);
+    if (!part) throw new TypeError("storage family id is empty after normalisation");
+    return family.prefix + part;
+  }, "familyKey");
+  const api = {
+    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(key, store) {
+      const raw = api.read(key, store);
+      if (raw === null) return null;
+      try {
+        return JSON.parse(raw);
+      } 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"]) {
+          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 = /* @__PURE__ */ __name((event) => {
+        if (event.storageArea !== nativeStorage(store)) return;
+        if (event.key === null || event.key === key) listener(event.key === null ? null : event.newValue);
+      }, "handler");
+      window.addEventListener("storage", handler);
+      return () => window.removeEventListener("storage", handler);
+    }
+  };
+  return api;
+}
+__name(createStorage, "createStorage");
+var cfgStorage = createStorage("cfg", {
+  keys: CFG_KEYS,
+  families: CFG_FAMILIES
+});
+export {
+  CFG_FAMILIES,
+  CFG_KEYS,
+  cfgStorage,
+  createStorage,
+  normalizeSegment
+};
+//# sourceMappingURL=storage.mjs.map

package/dist/storage.mjs.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.582",
+  "version": "2.1.583",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -50,6 +50,11 @@
       "import": "./dist/auth-server.mjs",
       "require": "./dist/auth-server.cjs"
     },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.mjs",
+      "require": "./dist/storage.cjs"
+    },
     "./clients": {
       "types": "./dist/clients.d.ts",
       "import": "./dist/clients.mjs",
@@ -64,6 +69,7 @@
   "files": [
     "dist",
     "src",
+    "@docs",
     "README.md",
     "LICENSE"
   ],
@@ -85,7 +91,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.582",
+    "@djangocfg/typescript-config": "^2.1.583",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/__tests__/noStorageLiterals.test.ts

@@ -0,0 +1,27 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+// Storage keys are defined once, in the registry. A literal anywhere else is a bug.
+const FORBIDDEN = [
+  'user_profile_cache', 'auth_email', 'auth_redirect_url', 'fm_session_id', 'oauth_state',
+  'oauth_provider', 'cfg.access_token', 'cfg.refresh_token', 'cfg.api_key',
+];
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      if (name !== '__tests__' && name !== 'generated') walk(path, out);
+    } else if (/\.tsx?$/.test(name)) out.push(path);
+  }
+  return out;
+}
+
+describe('no key literals outside the registry', () => {
+  const files = walk(join(__dirname, '..'));
+  it.each(FORBIDDEN)('"%s" is not spelled in source', (literal) => {
+    const hits = files.filter((f) => readFileSync(f, 'utf8').includes(`'${literal}'`) || readFileSync(f, 'utf8').includes(`"${literal}"`));
+    expect(hits).toEqual([]);
+  });
+});

package/src/__tests__/storage.test.ts

@@ -0,0 +1,134 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { CFG_FAMILIES, CFG_KEYS, cfgStorage, createStorage, normalizeSegment } from '../storage';
+
+const SCHEME = /^cfg(\.[a-z0-9_]+)+$/;
+
+beforeEach(() => {
+  localStorage.clear();
+  sessionStorage.clear();
+  document.cookie.split('; ').forEach((c) => {
+    document.cookie = `${c.split('=')[0]}=; Max-Age=0; Path=/`;
+  });
+  cfgStorage.clearAll({ all: true });
+});
+
+describe('registry', () => {
+  it.each(Object.entries(CFG_KEYS))('%s follows the scheme and round-trips', (_name, spec) => {
+    expect(spec.key).toMatch(SCHEME);
+    expect(cfgStorage.write(spec.key, 'v', spec.store)).toBe(true);
+    expect(cfgStorage.read(spec.key, spec.store)).toBe('v');
+    cfgStorage.remove(spec.key, spec.store);
+    expect(cfgStorage.read(spec.key, spec.store)).toBeNull();
+  });
+
+  it('has no duplicate key within one store', () => {
+    const seen = new Set<string>();
+    for (const spec of Object.values(CFG_KEYS)) {
+      const id = `${spec.store}:${spec.key}`;
+      expect(seen.has(id)).toBe(false);
+      seen.add(id);
+    }
+  });
+
+  it.each(Object.entries(CFG_FAMILIES))('family %s prefix follows the scheme', (_name, family) => {
+    expect(family.prefix).toMatch(/^cfg(\.[a-z0-9_]+)+\.$/);
+    expect(cfgStorage.familyKey(family, 'Room 1/A')).toBe(`${family.prefix}room_1_a`);
+  });
+
+  it('does not read old spellings', () => {
+    localStorage.setItem('cfg.access_token', 'old');
+    expect(cfgStorage.read(CFG_KEYS.accessToken.key)).toBeNull();
+  });
+});
+
+describe('validation', () => {
+  it('rejects keys outside the scheme', () => {
+    for (const bad of ['auth_email', 'cfg', 'cfg.', 'cfg.Auth.x', 'cfg.auth-x', 'other.x']) {
+      expect(() => cfgStorage.read(bad)).toThrow(TypeError);
+    }
+  });
+
+  it('app storage reads cfg and own keys, writes only its own', () => {
+    const app = createStorage('kino');
+    expect(app.isValid('kino.player.volume')).toBe(true);
+    expect(app.isValid('cfg.auth.email')).toBe(true);
+    expect(app.isValid('other.x')).toBe(false);
+    expect(() => app.write('cfg.auth.email', 'x')).toThrow(TypeError);
+    expect(app.write('kino.player.volume', '3')).toBe(true);
+    expect(app.read('kino.player.volume')).toBe('3');
+  });
+
+  it('builds and normalises keys from parts', () => {
+    const app = createStorage('kino');
+    expect(app.key('Player', 'Last Volume')).toBe('kino.player.last_volume');
+    expect(() => app.key('player', '  ')).toThrow(TypeError);
+    expect(() => createStorage('Bad-Owner')).toThrow(TypeError);
+    expect(normalizeSegment(' A-b c ')).toBe('a_b_c');
+  });
+});
+
+describe('guarded I/O', () => {
+  it('keeps the value in memory when the browser refuses a write', () => {
+    const spy = vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('full', 'QuotaExceededError');
+    });
+    expect(cfgStorage.write(CFG_KEYS.email.key, 'a@b.c')).toBe(false);
+    expect(cfgStorage.read(CFG_KEYS.email.key)).toBe('a@b.c');
+    spy.mockRestore();
+  });
+
+  it('survives a throwing storage getter', () => {
+    const spy = vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new Error('denied');
+    });
+    expect(cfgStorage.read(CFG_KEYS.email.key)).toBeNull();
+    spy.mockRestore();
+  });
+
+  it('readJSON returns null on garbage', () => {
+    localStorage.setItem(CFG_KEYS.uiState.key, '{oops');
+    expect(cfgStorage.readJSON(CFG_KEYS.uiState.key)).toBeNull();
+    cfgStorage.writeJSON(CFG_KEYS.uiState.key, { a: 1 });
+    expect(cfgStorage.readJSON(CFG_KEYS.uiState.key)).toEqual({ a: 1 });
+  });
+});
+
+describe('clearAll', () => {
+  it('removes personal keys and family members, keeps preferences', () => {
+    cfgStorage.write(CFG_KEYS.accessToken.key, 't');
+    cfgStorage.write(CFG_KEYS.chatSpeechLanguage.key, 'ru');
+    cfgStorage.write(cfgStorage.familyKey(CFG_FAMILIES.chatDraft, 'r1'), 'draft', 'session');
+    cfgStorage.write(cfgStorage.familyKey(CFG_FAMILIES.dataTree, 't1'), 'tree');
+    cfgStorage.clearAll();
+    expect(cfgStorage.read(CFG_KEYS.accessToken.key)).toBeNull();
+    expect(cfgStorage.read(cfgStorage.familyKey(CFG_FAMILIES.chatDraft, 'r1'), 'session')).toBeNull();
+    expect(cfgStorage.read(CFG_KEYS.chatSpeechLanguage.key)).toBe('ru');
+    expect(cfgStorage.read(cfgStorage.familyKey(CFG_FAMILIES.dataTree, 't1'))).toBe('tree');
+  });
+
+  it('{ all: true } wipes the owner namespace but not foreign keys', () => {
+    localStorage.setItem('NEXT_LOCALE', 'en');
+    cfgStorage.write(CFG_KEYS.chatSpeechLanguage.key, 'ru');
+    cfgStorage.write('cfg.custom.thing', '1');
+    cfgStorage.clearAll({ all: true });
+    expect(localStorage.getItem('cfg.custom.thing')).toBeNull();
+    expect(localStorage.getItem('NEXT_LOCALE')).toBe('en');
+  });
+});
+
+describe('cross-tab', () => {
+  it('onChange fires for the key from another tab only', () => {
+    const listener = vi.fn();
+    const off = cfgStorage.onChange(CFG_KEYS.accessToken.key, listener);
+    window.dispatchEvent(new StorageEvent('storage', { key: 'cfg.other.x', newValue: '1', storageArea: localStorage }));
+    window.dispatchEvent(new StorageEvent('storage', { key: CFG_KEYS.accessToken.key, newValue: 'n', storageArea: sessionStorage }));
+    expect(listener).not.toHaveBeenCalled();
+    window.dispatchEvent(new StorageEvent('storage', { key: CFG_KEYS.accessToken.key, newValue: 'n', storageArea: localStorage }));
+    expect(listener).toHaveBeenCalledWith('n');
+    off();
+    window.dispatchEvent(new StorageEvent('storage', { key: null, storageArea: localStorage }));
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/storageSsr.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+
+import { CFG_KEYS, cfgStorage } from '../storage';
+
+describe('storage on the server', () => {
+  it('never throws and never holds state', () => {
+    expect(typeof window).toBe('undefined');
+    expect(cfgStorage.read(CFG_KEYS.accessToken.key)).toBeNull();
+    expect(cfgStorage.write(CFG_KEYS.accessToken.key, 'x')).toBe(false);
+    expect(cfgStorage.read(CFG_KEYS.accessToken.key)).toBeNull();
+    expect(() => cfgStorage.clearAll({ all: true })).not.toThrow();
+    expect(cfgStorage.onChange(CFG_KEYS.accessToken.key, () => {})).toBeTypeOf('function');
+  });
+});

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);
+    },
+  };
 }
 
 /**
@@ -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,