@djangocfg/api 2.1.581 → 2.1.583

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

@@ -0,0 +1,328 @@
+// 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),
+  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),
+} 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/auth/__tests__/authRedirect.test.ts

@@ -37,7 +37,7 @@ function installSessionStorage() {
   return map;
 }
 
-const KEY = 'auth_redirect_url';
+const KEY = 'cfg.auth.redirect_url';
 
 describe('useAuthRedirectManager (storage-backed paths)', () => {
   beforeEach(() => {

package/src/auth/__tests__/profileCache.test.ts

@@ -30,7 +30,7 @@ function installBrowserStorage() {
   return map;
 }
 
-const CACHE_KEY = 'user_profile_cache';
+const CACHE_KEY = 'cfg.profile.cache';
 const NOW = 1_800_000_000_000;
 
 // Minimal User-shaped object; the cache is generic over its shape.

package/src/auth/context/AuthContext.tsx

@@ -30,6 +30,7 @@ import React, {
 
 import { auth } from '../../_api/generated/helpers/auth';
 import { APIError } from '../../_api/generated/helpers';
+import { CFG_KEYS } from '../../_api/generated/helpers/keys';
 import { applyRoleLogPolicy } from '../../log-control';
 import { useCfgRouter, useLocalStorage, useQueryParams, useSession } from '../hooks';
 import { clearProfileCache } from '../hooks/useProfileCache';
@@ -68,7 +69,7 @@ export const resolveAuthRoutes = (
   defaultAuthCallback: routes?.defaultAuthCallback || routes?.auth || defaultRoutes.defaultAuthCallback,
 });
 
-const EMAIL_STORAGE_KEY = 'auth_email';
+const EMAIL_STORAGE_KEY = CFG_KEYS.email.key;
 
 const AuthContext = createContext<AuthContextType | undefined>(undefined);
 

package/src/auth/hooks/useAuthRedirect.ts

@@ -1,6 +1,7 @@
+import { CFG_KEYS } from '../../_api/generated/helpers/keys';
 import { useSessionStorage } from './useSessionStorage';
 
-const AUTH_REDIRECT_KEY = 'auth_redirect_url';
+const AUTH_REDIRECT_KEY = CFG_KEYS.redirectUrl.key;
 
 export interface AuthRedirectOptions {
   fallbackUrl?: string;
@@ -28,7 +29,7 @@ const clearRedirectFromStorage = (): void => {
   if (typeof window === 'undefined') return;
   try {
     window.sessionStorage.removeItem(AUTH_REDIRECT_KEY);
-    window.sessionStorage.removeItem(`${AUTH_REDIRECT_KEY}_timestamp`);
+    window.sessionStorage.removeItem(`${AUTH_REDIRECT_KEY}_ts`);
   } catch {
     // Ignore errors
   }

package/src/auth/hooks/useGithubAuth.ts

@@ -3,6 +3,7 @@
 import { useCallback, useState } from 'react';
 
 import { auth } from '../../_api/generated/helpers/auth';
+import { CFG_KEYS } from '../../_api/generated/helpers/keys';
 import { CfgAccountsOauth } from '../../_api/generated/sdk.gen';
 import type { OAuthTokenResponse } from '../../_api/generated/types.gen';
 import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
@@ -10,6 +11,10 @@ import { formatAuthError } from '../utils/errors';
 import { authLogger } from '../utils/logger';
 import { useCfgRouter } from './useCfgRouter';
 
+const OAUTH_STATE_KEY = CFG_KEYS.oauthState.key;
+const OAUTH_PROVIDER_KEY = CFG_KEYS.oauthProvider.key;
+const OAUTH_REMEMBER_KEY = CFG_KEYS.oauthRememberMe.key;
+
 /**
  * The user payload as the OAuth endpoint declares it.
  *
@@ -107,9 +112,9 @@ export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuth
       authLogger.info('Redirecting to GitHub...', response.authorization_url);
 
       if (typeof window !== 'undefined') {
-        sessionStorage.setItem('oauth_state', response.state);
-        sessionStorage.setItem('oauth_provider', 'github');
-        sessionStorage.setItem('cfg.oauth.remember_me', String(rememberMe));
+        sessionStorage.setItem(OAUTH_STATE_KEY, response.state);
+        sessionStorage.setItem(OAUTH_PROVIDER_KEY, 'github');
+        sessionStorage.setItem(OAUTH_REMEMBER_KEY, String(rememberMe));
       }
 
       window.location.href = response.authorization_url;
@@ -146,15 +151,15 @@ export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuth
       // Verify state matches what we stored
       let rememberMeForSession = false;
       if (typeof window !== 'undefined') {
-        const storedState = sessionStorage.getItem('oauth_state');
+        const storedState = sessionStorage.getItem(OAUTH_STATE_KEY);
         if (storedState && storedState !== state) {
           throw new Error('Invalid OAuth state - possible CSRF attack');
         }
-        rememberMeForSession = sessionStorage.getItem('cfg.oauth.remember_me') === 'true';
+        rememberMeForSession = sessionStorage.getItem(OAUTH_REMEMBER_KEY) === 'true';
         // Clear stored state
-        sessionStorage.removeItem('oauth_state');
-        sessionStorage.removeItem('oauth_provider');
-        sessionStorage.removeItem('cfg.oauth.remember_me');
+        sessionStorage.removeItem(OAUTH_STATE_KEY);
+        sessionStorage.removeItem(OAUTH_PROVIDER_KEY);
+        sessionStorage.removeItem(OAUTH_REMEMBER_KEY);
 
       }
 

package/src/auth/hooks/useLocalStorage.ts

@@ -49,7 +49,7 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
             const key = keys[i];
             if (key) {
               localStorage.removeItem(key);
-              localStorage.removeItem(`${key}_timestamp`);
+              localStorage.removeItem(`${key}_ts`);
             }
           } catch {
             // Ignore errors when removing items
@@ -88,7 +88,7 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
         // Remove the key if data is too large
         try {
           window.localStorage.removeItem(key);
-          window.localStorage.removeItem(`${key}_timestamp`);
+          window.localStorage.removeItem(`${key}_ts`);
         } catch {
           // Ignore errors when removing
         }
@@ -109,7 +109,7 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
             window.localStorage.setItem(key, JSON.stringify(valueToStore));
           }
           // Add timestamp for cleanup
-          window.localStorage.setItem(`${key}_timestamp`, Date.now().toString());
+          window.localStorage.setItem(`${key}_ts`, Date.now().toString());
         } catch (storageError: unknown) {
           // If quota exceeded, clear old data and try again
           if (isQuotaExceededError(storageError)) {
@@ -124,7 +124,7 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
               } else {
                 window.localStorage.setItem(key, JSON.stringify(valueToStore));
               }
-              window.localStorage.setItem(`${key}_timestamp`, Date.now().toString());
+              window.localStorage.setItem(`${key}_ts`, Date.now().toString());
             } catch (retryError) {
               authLogger.error(`Failed to set localStorage key "${key}" after clearing old data:`, retryError);
               // If still fails, force clear all and try one more time
@@ -136,7 +136,7 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
                 } else {
                   window.localStorage.setItem(key, JSON.stringify(valueToStore));
                 }
-                window.localStorage.setItem(`${key}_timestamp`, Date.now().toString());
+                window.localStorage.setItem(`${key}_ts`, Date.now().toString());
               } catch (finalError) {
                 authLogger.error(`Failed to set localStorage key "${key}" after force clearing:`, finalError);
                 // If still fails, just update the state without localStorage
@@ -163,7 +163,7 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
       if (typeof window !== 'undefined') {
         try {
           window.localStorage.removeItem(key);
-          window.localStorage.removeItem(`${key}_timestamp`);
+          window.localStorage.removeItem(`${key}_ts`);
         } catch (removeError: unknown) {
           // If removal fails due to quota, try to clear some data first
           if (isQuotaExceededError(removeError)) {
@@ -172,7 +172,7 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
             
             try {
               window.localStorage.removeItem(key);
-              window.localStorage.removeItem(`${key}_timestamp`);
+              window.localStorage.removeItem(`${key}_ts`);
             } catch (retryError) {
               authLogger.error(`Failed to remove localStorage key "${key}" after clearing:`, retryError);
               // If still fails, force clear all

package/src/auth/hooks/useProfileCache.ts

@@ -11,10 +11,11 @@
 
 import type { User } from '../../';
 import { authLogger as profileLogger } from '../utils/logger';
+import { CFG_KEYS } from '../../_api/generated/helpers/keys';
 import { decodeBase64, encodeBase64 } from './useBase64';
 
 // Cache configuration
-const CACHE_KEY = 'user_profile_cache';
+const CACHE_KEY = CFG_KEYS.profileCache.key;
 const CACHE_VERSION = 1;
 const DEFAULT_TTL = 14400000; // 4 hours in milliseconds (reduced API calls, more resilient)
 

package/src/auth/hooks/useSessionStorage.ts

@@ -39,7 +39,7 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
             const key = keys[i];
             if (key) {
               sessionStorage.removeItem(key);
-              sessionStorage.removeItem(`${key}_timestamp`);
+              sessionStorage.removeItem(`${key}_ts`);
             }
           } catch {
             // Ignore errors when removing items
@@ -78,7 +78,7 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
         // Remove the key if data is too large
         try {
           window.sessionStorage.removeItem(key);
-          window.sessionStorage.removeItem(`${key}_timestamp`);
+          window.sessionStorage.removeItem(`${key}_ts`);
         } catch {
           // Ignore errors when removing
         }
@@ -94,7 +94,7 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
         try {
           window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
           // Add timestamp for cleanup
-          window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+          window.sessionStorage.setItem(`${key}_ts`, Date.now().toString());
         } catch (storageError: unknown) {
           // If quota exceeded, clear old data and try again
           if (isQuotaExceededError(storageError)) {
@@ -104,14 +104,14 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
             // Try again after clearing
             try {
               window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
-              window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+              window.sessionStorage.setItem(`${key}_ts`, Date.now().toString());
             } catch (retryError) {
               authLogger.error(`Failed to set sessionStorage key "${key}" after clearing old data:`, retryError);
               // If still fails, force clear all and try one more time
               try {
                 forceClearAll();
                 window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
-                window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+                window.sessionStorage.setItem(`${key}_ts`, Date.now().toString());
               } catch (finalError) {
                 authLogger.error(`Failed to set sessionStorage key "${key}" after force clearing:`, finalError);
                 // If still fails, just update the state without sessionStorage
@@ -138,7 +138,7 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
       if (typeof window !== 'undefined') {
         try {
           window.sessionStorage.removeItem(key);
-          window.sessionStorage.removeItem(`${key}_timestamp`);
+          window.sessionStorage.removeItem(`${key}_ts`);
         } catch (removeError: unknown) {
           // If removal fails due to quota, try to clear some data first
           if (isQuotaExceededError(removeError)) {
@@ -147,7 +147,7 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
             
             try {
               window.sessionStorage.removeItem(key);
-              window.sessionStorage.removeItem(`${key}_timestamp`);
+              window.sessionStorage.removeItem(`${key}_ts`);
             } catch (retryError) {
               authLogger.error(`Failed to remove sessionStorage key "${key}" after clearing:`, retryError);
               // If still fails, force clear all

package/src/storage.ts

@@ -0,0 +1,21 @@
+/**
+ * `@djangocfg/api/storage` — the browser-storage key registry on its own.
+ *
+ * Zero dependencies and no client: packages that only need a key, a guarded
+ * read/write or `createStorage('<owner>')` import this, not the generated SDK.
+ * The source is the generated `helpers/keys.ts`.
+ */
+export {
+  CFG_FAMILIES,
+  CFG_KEYS,
+  cfgStorage,
+  createStorage,
+  normalizeSegment,
+} from './_api/generated/helpers/keys';
+export type {
+  FamilySpec,
+  GuardedStorage,
+  KeySpec,
+  KeyStore,
+  StorageOptions,
+} from './_api/generated/helpers/keys';