@startsimpli/auth 0.4.14 → 0.4.16

package/src/client/mock-backend.ts

@@ -0,0 +1,258 @@
+/**
+ * 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');
+      }
+      if (payload.password !== payload.passwordConfirm) {
+        throw new Error('Passwords do not match');
+      }
+      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) */
+  }
+}

package/src/client/session-storage.ts

@@ -0,0 +1,142 @@
+/**
+ * Async persistence for a serialized {@link Session}.
+ *
+ * Backends that own their session (the mock backend, offline-first clients)
+ * use this to survive reloads/app-restarts. The Django web client persists via
+ * httpOnly cookies instead and does not need it.
+ *
+ * Implementations here are platform-neutral (memory, Web Storage). The
+ * secure-store (iOS Keychain / Android Keystore) implementation lives in
+ * secure-session-storage.native.ts and is resolved by Metro on native builds.
+ */
+
+import type { Session } from '../types';
+
+export interface SessionStorage {
+  /** Return the persisted session, or null if none / unreadable. */
+  load(): Promise<Session | null>;
+  /** Persist the session. */
+  save(session: Session): Promise<void>;
+  /** Remove any persisted session. */
+  clear(): Promise<void>;
+}
+
+/** Default storage key. */
+export const SESSION_STORAGE_KEY = 'startsimpli.auth.session';
+
+function isSession(value: unknown): value is Session {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.accessToken === 'string' &&
+    typeof v.expiresAt === 'number' &&
+    !!v.user &&
+    typeof v.user === 'object'
+  );
+}
+
+/**
+ * In-memory storage. Lost on reload — the safe default for SSR and tests, and
+ * a graceful fallback when no Web Storage is available.
+ */
+export function createMemorySessionStorage(): SessionStorage {
+  let current: Session | null = null;
+  return {
+    async load() {
+      return current;
+    },
+    async save(session) {
+      current = session;
+    },
+    async clear() {
+      current = null;
+    },
+  };
+}
+
+/**
+ * Web Storage (localStorage by default) backed storage. Persists across
+ * reloads. Falls back to in-memory when no Storage is available (SSR).
+ */
+export function createWebSessionStorage(opts: {
+  key?: string;
+  storage?: Storage;
+} = {}): SessionStorage {
+  const key = opts.key ?? SESSION_STORAGE_KEY;
+  const resolveStorage = (): Storage | null => {
+    if (opts.storage) return opts.storage;
+    try {
+      const s = (globalThis as unknown as { localStorage?: Storage }).localStorage;
+      return s && typeof s.getItem === 'function' ? s : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const memoryFallback = createMemorySessionStorage();
+
+  return {
+    async load() {
+      const storage = resolveStorage();
+      if (!storage) return memoryFallback.load();
+      try {
+        const raw = storage.getItem(key);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        return isSession(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    async save(session) {
+      const storage = resolveStorage();
+      if (!storage) return memoryFallback.save(session);
+      try {
+        storage.setItem(key, JSON.stringify(session));
+      } catch {
+        /* quota / serialization failure — non-fatal for a demo session */
+      }
+    },
+    async clear() {
+      const storage = resolveStorage();
+      if (!storage) return memoryFallback.clear();
+      try {
+        storage.removeItem(key);
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+/**
+ * "Remember me" wrapper. When `shouldRemember()` is true at save time, the
+ * session is written to `persistent` storage (survives restarts); otherwise it
+ * is kept only in `transient` (in-memory) storage and `persistent` is cleared,
+ * so a restart starts unauthenticated. `load` always reads `persistent`, so a
+ * session is restored only if the last save was a "remembered" one.
+ */
+export function createRememberAwareSessionStorage(
+  persistent: SessionStorage,
+  shouldRemember: () => boolean,
+  transient: SessionStorage = createMemorySessionStorage()
+): SessionStorage {
+  return {
+    load() {
+      return persistent.load();
+    },
+    async save(session) {
+      if (shouldRemember()) {
+        await transient.clear();
+        await persistent.save(session);
+      } else {
+        await persistent.clear();
+        await transient.save(session);
+      }
+    },
+    async clear() {
+      await persistent.clear();
+      await transient.clear();
+    },
+  };
+}