@startsimpli/auth 0.4.15 → 0.4.17

package/src/client/backend.ts

@@ -0,0 +1,67 @@
+/**
+ * Backend-agnostic authentication contract.
+ *
+ * AuthProvider drives all of its state from one object satisfying this
+ * interface. The Django/JWT implementation is {@link AuthClient}; backendless
+ * apps (demos, offline-first, Storybook) can inject any other implementation
+ * — e.g. `createMockAuthBackend` — without the provider knowing the difference.
+ *
+ * The method set is exactly what AuthProvider needs; nothing here is
+ * Django-specific.
+ */
+
+import type { Session, AuthUser } from '../types';
+
+export interface RegisterPayload {
+  email: string;
+  password: string;
+  name?: string;
+  firstName?: string;
+  lastName?: string;
+}
+
+export interface AuthBackend {
+  /** Authenticate and open a session. Rejects on bad credentials. */
+  login(email: string, password: string): Promise<Session>;
+  /** End the session and clear any persisted state. */
+  logout(): Promise<void>;
+  /** Create an account and open a session. */
+  register(payload: RegisterPayload): Promise<Session>;
+  /** Re-fetch the current user (e.g. after a profile change). */
+  getCurrentUser(): Promise<AuthUser>;
+  /** Return a valid access token, refreshing if needed; null if unauthenticated. */
+  getAccessToken(): Promise<string | null>;
+  /** Synchronous current session, or null. May clear+return null if expired. */
+  getSession(): Session | null;
+  /** Adopt an externally-acquired session (SSR/hydration/OAuth callback). */
+  setSession(session: Session): void;
+  /**
+   * Restore a persisted session on mount. Web/Django reads the refresh-token
+   * cookie; native/mock backends read secure storage. Returns null when there
+   * is nothing to restore.
+   */
+  restoreSession(): Promise<Session | null>;
+  /** Begin an OAuth flow; returns the authorization URL to redirect to. */
+  signInWithGoogle(redirectTo?: string): Promise<string>;
+  /** Complete an OAuth flow by exchanging the code+state for a session. */
+  completeGoogleCallback(code: string, state: string): Promise<Session>;
+  /**
+   * Begin a Microsoft OAuth flow; returns the authorization URL to redirect
+   * to. Optional — backends that don't speak Microsoft can omit it.
+   */
+  signInWithMicrosoft?(redirectTo?: string): Promise<string>;
+  /**
+   * Complete a Microsoft OAuth callback. Optional — backends that don't speak
+   * Microsoft can omit it.
+   */
+  completeMicrosoftCallback?(code: string, state: string): Promise<Session>;
+  /**
+   * Optional. Register the provider's session-expiry handler. The Django
+   * AuthClient wires this through AuthConfig.onSessionExpired instead, so it
+   * is optional — backends that don't take an AuthConfig (e.g. the mock) use
+   * this to notify the provider when a session goes away out-of-band.
+   */
+  setOnSessionExpired?(cb: (() => void) | null): void;
+  /** Release timers/listeners. Called on AuthProvider unmount. */
+  destroy(): void;
+}

package/src/client/functions.ts

@@ -12,6 +12,9 @@
  */
 
 import { deleteCookie } from '../utils/cookies';
+// Local binding for internal use; also re-exported below to preserve this
+// module's public surface.
+import { extractApiError } from '../utils/api-error';
 import { decodeToken } from '../utils/token';
 
 // --- Types ---
@@ -71,6 +74,8 @@ const AUTH_PATHS = {
   RESEND_VERIFICATION: `${API_BASE}/auth/resend-verification/`,
   OAUTH_GOOGLE_INITIATE: `${API_BASE}/auth/oauth/google/initiate/`,
   OAUTH_GOOGLE_CALLBACK: `${API_BASE}/auth/oauth/google/callback/`,
+  OAUTH_MICROSOFT_INITIATE: `${API_BASE}/auth/oauth/microsoft/initiate/`,
+  OAUTH_MICROSOFT_CALLBACK: `${API_BASE}/auth/oauth/microsoft/callback/`,
   ME: `${API_BASE}/auth/me/`,
 } as const;
 
@@ -210,58 +215,10 @@ function _syncAuthCookie(token: string | null): void {
 
 const AUTH_TIMEOUT_MS = 15_000;
 
-/**
- * Extract a human-readable message from a Django REST Framework error response body.
- *
- * Handles the shapes we've seen in practice:
- *   { detail: "..." }                                 → the string
- *   { detail: ["...", "..."] }                        → first string
- *   { detail: { token: ["Invalid..."] } }             → first nested string
- *   { email: ["already exists"] }                     → first field-level string
- *   { non_field_errors: ["..."] }                     → first field-level string
- *   { error: "CODE", detail: { field: ["..."] } }     → first nested string
- *
- * @internal Shared with AuthClient; still considered implementation detail
- * of the auth package. Do not rely on from outside `@startsimpli/auth`.
- */
-export function extractApiError(d: Record<string, unknown>, fallback: string): string {
-  const pluck = (val: unknown): string | null => {
-    if (typeof val === 'string') return val
-    if (Array.isArray(val) && val.length > 0) {
-      for (const item of val) {
-        const s = pluck(item)
-        if (s) return s
-      }
-    }
-    if (val && typeof val === 'object') {
-      for (const v of Object.values(val as Record<string, unknown>)) {
-        const s = pluck(v)
-        if (s) return s
-      }
-    }
-    return null
-  }
-
-  // Standard DRF: { detail: "..." }
-  const fromDetail = pluck(d.detail)
-  if (fromDetail) return fromDetail
-  // Some backend shapes use `error` as the human-readable message (e.g.
-  // our Django auth errors: { "error": "No active account...", "code": "unauthorized" }).
-  // Prefer this over field-level probing so we don't accidentally return a
-  // code like "unauthorized" from a sibling field.
-  const fromError = pluck(d.error)
-  if (fromError) return fromError
-  // Field-level: { email: ["already exists"] } or { non_field_errors: ["..."] }
-  // Skip known meta/code fields so `{ code: "unauthorized" }` doesn't leak
-  // an internal identifier as a user-facing message.
-  const META_KEYS = new Set(['detail', 'error', 'code', 'statusCode', 'status', 'timestamp'])
-  for (const [key, val] of Object.entries(d)) {
-    if (META_KEYS.has(key)) continue
-    const s = pluck(val)
-    if (s) return s
-  }
-  return fallback
-}
+// extractApiError moved to ../utils/api-error (DOM-free, shared with the
+// platform-neutral token-auth core). Imported above for internal use and
+// re-exported here to preserve this module's public surface (e.g. AuthClient).
+export { extractApiError }
 
 function fetchWithTimeout(url: string, options: RequestInit): Promise<Response> {
   const controller = new AbortController();
@@ -342,7 +299,6 @@ export async function signInWithCredentials(email: string, password: string) {
 export async function registerAccount(payload: {
   email: string;
   password: string;
-  passwordConfirm: string;
   name?: string;
   firstName?: string;
   lastName?: string;
@@ -361,7 +317,6 @@ export async function registerAccount(payload: {
     body: JSON.stringify({
       email: payload.email,
       password: payload.password,
-      password_confirm: payload.passwordConfirm,
       first_name: payload.firstName ?? firstFromName ?? undefined,
       last_name: payload.lastName ?? lastFromName ?? undefined,
     }),
@@ -398,7 +353,6 @@ export async function requestPasswordReset(email: string): Promise<void> {
 export async function resetPassword(payload: {
   token: string;
   password: string;
-  passwordConfirm: string;
   email?: string;
 }): Promise<void> {
   const response = await fetchWithTimeout(resolveAuthUrl(AUTH_PATHS.RESET_PASSWORD), {
@@ -407,7 +361,6 @@ export async function resetPassword(payload: {
     body: JSON.stringify({
       token: payload.token,
       password: payload.password,
-      password_confirm: payload.passwordConfirm,
       ...(payload.email ? { email: payload.email } : {}),
     }),
   });
@@ -472,9 +425,37 @@ export async function initiateGoogleOAuth(redirectUri: string): Promise<any> {
 }
 
 export async function completeGoogleOAuth(code: string, state: string) {
+  return _completeOAuthCallback(AUTH_PATHS.OAUTH_GOOGLE_CALLBACK, code, state);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function initiateMicrosoftOAuth(redirectUri: string): Promise<any> {
+  const response = await fetch(resolveAuthUrl(AUTH_PATHS.OAUTH_MICROSOFT_INITIATE), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    credentials: 'include',
+    body: JSON.stringify({ redirect_uri: redirectUri }),
+  });
+
+  const data = await response.json().catch(() => ({}));
+
+  if (!response.ok) {
+    const d = data as Record<string, unknown>;
+    const message = (d?.detail || d?.error || 'Failed to initiate Microsoft OAuth') as string;
+    throw new Error(message);
+  }
+
+  return data;
+}
+
+export async function completeMicrosoftOAuth(code: string, state: string) {
+  return _completeOAuthCallback(AUTH_PATHS.OAUTH_MICROSOFT_CALLBACK, code, state);
+}
+
+async function _completeOAuthCallback(callbackPath: string, code: string, state: string) {
   const response = await fetchWithTimeout(
     resolveAuthUrl(
-      `${AUTH_PATHS.OAUTH_GOOGLE_CALLBACK}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(state)}`
+      `${callbackPath}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(state)}`
     ),
     { credentials: 'include' }
   );

package/src/client/index.ts

@@ -1,4 +1,19 @@
 export { AuthClient } from './auth-client';
+export type { AuthBackend, RegisterPayload } from './backend';
+export {
+  createMockAuthBackend,
+  type MockAuthBackend,
+  type MockAuthBackendOptions,
+  type MockAccount,
+} from './mock-backend';
+export {
+  createMemorySessionStorage,
+  createWebSessionStorage,
+  createRememberAwareSessionStorage,
+  SESSION_STORAGE_KEY,
+  type SessionStorage,
+} from './session-storage';
+export { createSecureSessionStorage } from './secure-session-storage';
 export { AuthProvider, useAuthContext } from './auth-context';
 export { useAuth, useRequireAuth, type UseAuthReturn, type UseRequireAuthReturn, type UseRequireAuthOptions } from './use-auth';
 export { usePermissions, type UsePermissionsReturn } from './use-permissions';

package/src/client/mock-backend.ts

@@ -0,0 +1,255 @@
+/**
+ * In-memory AuthBackend for backendless apps (demos, offline-first, Storybook).
+ *
+ * Implements the full {@link AuthBackend} contract plus mock-only helpers for
+ * password-reset and email-verification flows. No network, no JWT — sessions
+ * carry a synthetic token and an explicit expiry the backend manages itself.
+ * Pair it with a {@link SessionStorage} to survive reloads/app-restarts.
+ */
+
+import type { Session, AuthUser } from '../types';
+import type { AuthBackend, RegisterPayload } from './backend';
+import { createMemorySessionStorage, type SessionStorage } from './session-storage';
+
+export interface MockAccount {
+  email: string;
+  password: string;
+  user: AuthUser;
+}
+
+export interface MockAuthBackendOptions {
+  /** Seed accounts that can sign in immediately. */
+  accounts?: MockAccount[];
+  /** Where to persist the session. Defaults to in-memory (lost on reload). */
+  storage?: SessionStorage;
+  /** Simulated round-trip latency in ms for auth operations. Default 0. */
+  latencyMs?: number;
+  /** Synthetic session lifetime in ms. Default 24h. */
+  sessionTtlMs?: number;
+  /** Injectable clock (tests). Default Date.now. */
+  now?: () => number;
+  /** Build the AuthUser for a brand-new registration. */
+  createUser?: (payload: RegisterPayload) => AuthUser;
+}
+
+export interface MockAuthBackend extends AuthBackend {
+  /** Issue a reset token for an existing account (no email service in mock). */
+  requestPasswordReset(email: string): Promise<{ token: string }>;
+  /** Complete a reset using a token from requestPasswordReset. */
+  resetPassword(token: string, newPassword: string): Promise<void>;
+  /** Issue an email-verification token for an account. */
+  requestEmailVerification(email: string): Promise<{ token: string }>;
+  /** Mark an account verified; updates the live session if it's the current user. */
+  verifyEmail(token: string): Promise<void>;
+  /** Add or replace an account at runtime. */
+  upsertAccount(account: MockAccount): void;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const sleep = (ms: number) =>
+  ms > 0 ? new Promise<void>((r) => setTimeout(r, ms)) : Promise.resolve();
+
+let _tokenSeq = 0;
+function genToken(prefix: string): string {
+  _tokenSeq += 1;
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `${prefix}.${Date.now().toString(36)}.${_tokenSeq}.${rand}`;
+}
+
+function normalizeEmail(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+function defaultCreateUser(payload: RegisterPayload, now: number): AuthUser {
+  const fromName = payload.name?.trim();
+  const fromParts = [payload.firstName, payload.lastName].filter(Boolean).join(' ');
+  const display = fromName || fromParts || payload.email.split('@')[0];
+  const [first, ...rest] = display.split(/\s+/);
+  const iso = new Date(now).toISOString();
+  return {
+    id: `mock-${normalizeEmail(payload.email).replace(/[^a-z0-9]+/g, '-')}`,
+    email: payload.email,
+    firstName: payload.firstName ?? first ?? '',
+    lastName: payload.lastName ?? rest.join(' '),
+    isEmailVerified: false,
+    createdAt: iso,
+    updatedAt: iso,
+    name: display,
+  };
+}
+
+export function createMockAuthBackend(
+  options: MockAuthBackendOptions = {}
+): MockAuthBackend {
+  const storage = options.storage ?? createMemorySessionStorage();
+  const latencyMs = options.latencyMs ?? 0;
+  const ttl = options.sessionTtlMs ?? DAY_MS;
+  const now = options.now ?? (() => Date.now());
+  const createUser =
+    options.createUser ?? ((payload: RegisterPayload) => defaultCreateUser(payload, now()));
+
+  interface Record_ {
+    password: string;
+    user: AuthUser;
+  }
+  const accounts = new Map<string, Record_>();
+  for (const a of options.accounts ?? []) {
+    accounts.set(normalizeEmail(a.email), { password: a.password, user: a.user });
+  }
+
+  const resetTokens = new Map<string, string>(); // token -> email
+  const verifyTokens = new Map<string, string>(); // token -> email
+
+  let session: Session | null = null;
+  let onSessionExpired: (() => void) | null = null;
+
+  function makeSession(user: AuthUser): Session {
+    return { user, accessToken: genToken('mock-access'), expiresAt: now() + ttl };
+  }
+
+  function isExpired(s: Session): boolean {
+    return s.expiresAt <= now();
+  }
+
+  /** Validated current session: clears + notifies if expired. */
+  function currentSession(): Session | null {
+    if (!session) return null;
+    if (isExpired(session)) {
+      session = null;
+      void storage.clear();
+      onSessionExpired?.();
+      return null;
+    }
+    return session;
+  }
+
+  function requireAccount(email: string): Record_ {
+    const account = accounts.get(normalizeEmail(email));
+    if (!account) throw new Error('No account found for that email');
+    return account;
+  }
+
+  const backend: MockAuthBackend = {
+    async login(email, password) {
+      await sleep(latencyMs);
+      const account = accounts.get(normalizeEmail(email));
+      if (!account || account.password !== password) {
+        throw new Error('Invalid email or password');
+      }
+      session = makeSession(account.user);
+      await storage.save(session);
+      return session;
+    },
+
+    async logout() {
+      session = null;
+      await storage.clear();
+    },
+
+    async register(payload) {
+      await sleep(latencyMs);
+      const key = normalizeEmail(payload.email);
+      if (accounts.has(key)) {
+        throw new Error('An account with this email already exists');
+      }
+      const user = createUser(payload);
+      accounts.set(key, { password: payload.password, user });
+      session = makeSession(user);
+      await storage.save(session);
+      return session;
+    },
+
+    async getCurrentUser() {
+      if (!session) throw new Error('Not authenticated');
+      return session.user;
+    },
+
+    async getAccessToken() {
+      return currentSession()?.accessToken ?? null;
+    },
+
+    getSession() {
+      return currentSession();
+    },
+
+    setSession(s) {
+      session = s;
+      void storage.save(s);
+    },
+
+    async restoreSession() {
+      const loaded = await storage.load();
+      if (loaded && !isExpired(loaded)) {
+        session = loaded;
+        return session;
+      }
+      if (loaded) await storage.clear();
+      return null;
+    },
+
+    async signInWithGoogle() {
+      throw new Error('OAuth is not supported by the mock auth backend');
+    },
+
+    async completeGoogleCallback() {
+      throw new Error('OAuth is not supported by the mock auth backend');
+    },
+
+    setOnSessionExpired(cb) {
+      onSessionExpired = cb;
+    },
+
+    destroy() {
+      onSessionExpired = null;
+    },
+
+    // --- mock-only flows ---
+
+    async requestPasswordReset(email) {
+      await sleep(latencyMs);
+      requireAccount(email);
+      const token = genToken('mock-reset');
+      resetTokens.set(token, normalizeEmail(email));
+      return { token };
+    },
+
+    async resetPassword(token, newPassword) {
+      await sleep(latencyMs);
+      const email = resetTokens.get(token);
+      if (!email) throw new Error('Invalid or expired reset token');
+      requireAccount(email).password = newPassword;
+      resetTokens.delete(token);
+    },
+
+    async requestEmailVerification(email) {
+      await sleep(latencyMs);
+      requireAccount(email);
+      const token = genToken('mock-verify');
+      verifyTokens.set(token, normalizeEmail(email));
+      return { token };
+    },
+
+    async verifyEmail(token) {
+      await sleep(latencyMs);
+      const email = verifyTokens.get(token);
+      if (!email) throw new Error('Invalid or expired verification token');
+      const account = requireAccount(email);
+      account.user = { ...account.user, isEmailVerified: true };
+      verifyTokens.delete(token);
+      if (session && normalizeEmail(session.user.email) === email) {
+        session = { ...session, user: { ...session.user, isEmailVerified: true } };
+        void storage.save(session);
+      }
+    },
+
+    upsertAccount(account) {
+      accounts.set(normalizeEmail(account.email), {
+        password: account.password,
+        user: account.user,
+      });
+    },
+  };
+
+  return backend;
+}

package/src/client/optional-secure-store.ts

@@ -0,0 +1,21 @@
+/**
+ * Loads expo-secure-store — an OPTIONAL peer (see peerDependenciesMeta).
+ *
+ * Returns null when the native module isn't in the build (a dev client compiled
+ * before the dependency was added, Expo Go without it) instead of throwing
+ * during module evaluation, which would take down the whole auth package and
+ * crash the app at launch. The native secure-storage implementations share this
+ * one guarded load and fall back to in-memory when it returns null.
+ *
+ * The require uses a static string so Metro still bundles the module; the
+ * try/catch turns a missing native module into a graceful null.
+ */
+export type SecureStoreModule = typeof import('expo-secure-store');
+
+export function loadSecureStore(): SecureStoreModule | null {
+  try {
+    return require('expo-secure-store') as SecureStoreModule;
+  } catch {
+    return null;
+  }
+}

package/src/client/secure-session-storage.native.ts

@@ -0,0 +1,53 @@
+import type { Session } from '../types';
+import {
+  SESSION_STORAGE_KEY,
+  createMemorySessionStorage,
+  type SessionStorage,
+} from './session-storage';
+import { loadSecureStore } from './optional-secure-store';
+
+/**
+ * SessionStorage backed by expo-secure-store (iOS Keychain / Android Keystore).
+ *
+ * Native counterpart to the web's localStorage session storage. Metro resolves
+ * this file over secure-session-storage.ts on React Native builds.
+ *
+ * expo-secure-store is an OPTIONAL peer ({@link loadSecureStore}). When its
+ * native module isn't present — a dev client compiled before the dependency was
+ * added, Expo Go without it — loadSecureStore returns null and we fall back to
+ * in-memory storage: the app keeps working, the session just won't survive a
+ * restart until the build includes the module.
+ */
+export function createSecureSessionStorage(
+  key: string = SESSION_STORAGE_KEY
+): SessionStorage {
+  const SecureStore = loadSecureStore();
+  if (!SecureStore) return createMemorySessionStorage();
+
+  return {
+    async load() {
+      try {
+        const raw = await SecureStore.getItemAsync(key);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw) as Session;
+        return parsed && typeof parsed === 'object' ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    async save(session) {
+      try {
+        await SecureStore.setItemAsync(key, JSON.stringify(session));
+      } catch {
+        /* secure store unavailable at runtime — non-fatal for a session */
+      }
+    },
+    async clear() {
+      try {
+        await SecureStore.deleteItemAsync(key);
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}

package/src/client/secure-session-storage.ts

@@ -0,0 +1,20 @@
+import {
+  SESSION_STORAGE_KEY,
+  createWebSessionStorage,
+  type SessionStorage,
+} from './session-storage';
+
+/**
+ * Web resolution of createSecureSessionStorage.
+ *
+ * expo-secure-store is React Native-only; Metro resolves
+ * secure-session-storage.native.ts on native builds. On the web there is no
+ * Keychain, so sessions persist in localStorage instead. This keeps the import
+ * site identical across platforms (unlike the throwing token-storage web stub —
+ * sessions *should* persist on the web, where there's no httpOnly cookie).
+ */
+export function createSecureSessionStorage(
+  key: string = SESSION_STORAGE_KEY
+): SessionStorage {
+  return createWebSessionStorage({ key });
+}

package/src/client/secure-token-storage.native.ts

@@ -0,0 +1,55 @@
+import type { TokenStorage } from './token-auth-core';
+import { loadSecureStore } from './optional-secure-store';
+
+/** Keychain/Keystore key under which the refresh token is persisted. */
+export const REFRESH_TOKEN_KEY = 'startsimpli.auth.refresh';
+
+/**
+ * TokenStorage backed by expo-secure-store (iOS Keychain / Android Keystore).
+ *
+ * Native counterpart to the web's httpOnly refresh-token cookie. Metro resolves
+ * this file over secure-token-storage.ts on React Native builds.
+ *
+ * expo-secure-store is an OPTIONAL peer ({@link loadSecureStore}): if its native
+ * module isn't in the build, loadSecureStore returns null and we fall back to
+ * in-memory — tokens won't survive a restart, but nothing crashes.
+ */
+export class SecureTokenStorage implements TokenStorage {
+  private readonly store = loadSecureStore();
+  private memory: string | null = null;
+
+  constructor(private readonly key: string = REFRESH_TOKEN_KEY) {}
+
+  async getRefreshToken(): Promise<string | null> {
+    if (!this.store) return this.memory;
+    try {
+      return await this.store.getItemAsync(this.key);
+    } catch {
+      return null;
+    }
+  }
+
+  async setRefreshToken(token: string): Promise<void> {
+    if (!this.store) {
+      this.memory = token;
+      return;
+    }
+    try {
+      await this.store.setItemAsync(this.key, token);
+    } catch {
+      /* secure store unavailable at runtime — non-fatal */
+    }
+  }
+
+  async clear(): Promise<void> {
+    if (!this.store) {
+      this.memory = null;
+      return;
+    }
+    try {
+      await this.store.deleteItemAsync(this.key);
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/src/client/secure-token-storage.ts

@@ -0,0 +1,32 @@
+import type { TokenStorage } from './token-auth-core';
+
+export const REFRESH_TOKEN_KEY = 'startsimpli.auth.refresh';
+
+/**
+ * Web stub for SecureTokenStorage.
+ *
+ * expo-secure-store is React Native-only. On the web the refresh token lives in
+ * an httpOnly cookie managed by the browser (see the cookie-based AuthClient),
+ * so this throws if constructed. Metro resolves secure-token-storage.native.ts
+ * on native builds; this file is what web bundlers see.
+ */
+export class SecureTokenStorage implements TokenStorage {
+  constructor(_key: string = REFRESH_TOKEN_KEY) {
+    throw new Error(
+      'SecureTokenStorage is React Native-only (expo-secure-store). On the web, ' +
+        'use the cookie-based AuthClient instead.'
+    );
+  }
+
+  async getRefreshToken(): Promise<string | null> {
+    return null;
+  }
+
+  async setRefreshToken(_token: string): Promise<void> {
+    /* no-op: never reached (constructor throws) */
+  }
+
+  async clear(): Promise<void> {
+    /* no-op: never reached (constructor throws) */
+  }
+}