@erikey/react 0.4.26 → 0.4.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erikey/react",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "React SDK for Erikey - B2B authentication and user management. UI components based on better-auth-ui.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],

package/src/__tests__/auth-client.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for React SDK auth-client
+ *
+ * These tests validate:
+ * - Client creation with correct configuration
+ * - Cross-origin detection
+ * - Token storage hooks work correctly
+ *
+ * Note: We're now using better-auth's native API, so we don't test
+ * the internal API methods - those are tested by better-auth itself.
+ */
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { createAuthClient } from '../auth-client';
+import * as crossOriginAuth from '../lib/cross-origin-auth';
+
+// Mock the cross-origin-auth module
+vi.mock('../lib/cross-origin-auth', () => ({
+  shouldUseBearerAuth: vi.fn(),
+  storeToken: vi.fn(),
+  getStoredToken: vi.fn(),
+  clearToken: vi.fn(),
+}));
+
+describe('createAuthClient', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('configuration', () => {
+    it('should create a client with default baseUrl', () => {
+      vi.mocked(crossOriginAuth.shouldUseBearerAuth).mockReturnValue(false);
+
+      const client = createAuthClient({ projectId: 'pk_test_123' });
+
+      expect(client).toBeDefined();
+      expect(client.signIn).toBeDefined();
+      expect(client.signUp).toBeDefined();
+      expect(client.signOut).toBeDefined();
+      expect(client.useSession).toBeDefined();
+    });
+
+    it('should create a client with custom baseUrl', () => {
+      vi.mocked(crossOriginAuth.shouldUseBearerAuth).mockReturnValue(false);
+
+      const client = createAuthClient({
+        projectId: 'pk_test_123',
+        baseUrl: 'http://localhost:7203',
+      });
+
+      expect(client).toBeDefined();
+    });
+
+    it('should detect cross-origin context', () => {
+      vi.mocked(crossOriginAuth.shouldUseBearerAuth).mockReturnValue(true);
+      vi.mocked(crossOriginAuth.getStoredToken).mockReturnValue('test-token');
+
+      const client = createAuthClient({ projectId: 'pk_test_123' });
+
+      expect(crossOriginAuth.shouldUseBearerAuth).toHaveBeenCalledWith(
+        'https://auth.erikey.com'
+      );
+      expect(client).toBeDefined();
+    });
+  });
+
+  describe('cross-origin token handling', () => {
+    it('should use bearer token in cross-origin context', () => {
+      vi.mocked(crossOriginAuth.shouldUseBearerAuth).mockReturnValue(true);
+      vi.mocked(crossOriginAuth.getStoredToken).mockReturnValue('stored-token');
+
+      // Just verify the client is created - actual token usage is tested via integration tests
+      const client = createAuthClient({ projectId: 'pk_test_123' });
+
+      expect(client).toBeDefined();
+      expect(crossOriginAuth.getStoredToken).not.toHaveBeenCalled(); // Called lazily
+    });
+  });
+
+  describe('API surface', () => {
+    it('should expose better-auth client methods', () => {
+      vi.mocked(crossOriginAuth.shouldUseBearerAuth).mockReturnValue(false);
+
+      const client = createAuthClient({ projectId: 'pk_test_123' });
+
+      // Core auth methods
+      expect(client.signIn).toBeDefined();
+      expect(client.signIn.email).toBeDefined();
+      expect(client.signIn.social).toBeDefined();
+      expect(client.signUp).toBeDefined();
+      expect(client.signUp.email).toBeDefined();
+      expect(client.signOut).toBeDefined();
+
+      // Session hook
+      expect(client.useSession).toBeDefined();
+      expect(typeof client.useSession).toBe('function');
+
+      // Other methods
+      expect(client.getSession).toBeDefined();
+    });
+  });
+});

package/src/__tests__/security/localStorage-encryption.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Security tests for localStorage token encryption
+ *
+ * NOTE: These tests require the encryption functions to be exported from auth-client.ts
+ * Add these exports to make tests pass:
+ *
+ * export { storeToken, getStoredToken, clearToken };
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+
+// Mock localStorage for Node environment
+const localStorageMock = (() => {
+  let store: Record<string, string> = {};
+  return {
+    getItem: (key: string) => store[key] || null,
+    setItem: (key: string, value: string) => {
+      store[key] = value;
+    },
+    removeItem: (key: string) => {
+      delete store[key];
+    },
+    clear: () => {
+      store = {};
+    },
+  };
+})();
+
+// @ts-ignore
+global.localStorage = localStorageMock;
+
+// These imports will fail until encryption functions are implemented and exported
+// This is intentional - the tests guide the implementation (TDD approach)
+let storeToken: any;
+let getStoredToken: any;
+let clearToken: any;
+
+try {
+  // Try to import the functions (will fail initially)
+  const authClient = await import('../../auth-client');
+  storeToken = (authClient as any).storeToken;
+  getStoredToken = (authClient as any).getStoredToken;
+  clearToken = (authClient as any).clearToken;
+} catch (error) {
+  console.warn('⚠️  Encryption functions not yet exported from auth-client.ts');
+  console.warn('   Add: export { storeToken, getStoredToken, clearToken };');
+}
+
+describe('localStorage Token Encryption', () => {
+  const projectId = 'test-project-123';
+  const mockSession = {
+    id: 'session-123',
+    token: 'super-secret-token-12345',
+    expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+  };
+
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it('should encrypt tokens before storing', async () => {
+    if (!storeToken) {
+      console.warn('⚠️  Skipping test: storeToken not implemented');
+      return;
+    }
+
+    await storeToken(projectId, mockSession);
+
+    const rawStored = localStorage.getItem(`erikey.session.${projectId}`);
+    expect(rawStored).not.toBeNull();
+
+    const stored = JSON.parse(rawStored!);
+
+    // Token should NOT be stored in plain text
+    expect(stored.token).not.toBe(mockSession.token);
+    expect(stored.token).toMatch(/^[A-Za-z0-9+/=]+$/); // Base64 format
+  });
+
+  it('should decrypt tokens when retrieving', async () => {
+    if (!storeToken || !getStoredToken) {
+      console.warn('⚠️  Skipping test: encryption functions not implemented');
+      return;
+    }
+
+    await storeToken(projectId, mockSession);
+    const retrieved = await getStoredToken(projectId);
+
+    // Should decrypt back to original token
+    expect(retrieved).toBe(mockSession.token);
+  });
+
+  it('should return null for expired tokens', async () => {
+    if (!storeToken || !getStoredToken) {
+      console.warn('⚠️  Skipping test: encryption functions not implemented');
+      return;
+    }
+
+    const expiredSession = {
+      ...mockSession,
+      expiresAt: new Date(Date.now() - 1000).toISOString(), // Expired
+    };
+
+    await storeToken(projectId, expiredSession);
+    const retrieved = await getStoredToken(projectId);
+
+    expect(retrieved).toBeNull();
+    // Should also clean up localStorage
+    expect(localStorage.getItem(`erikey.session.${projectId}`)).toBeNull();
+  });
+
+  it('should handle decryption errors gracefully', async () => {
+    if (!getStoredToken) {
+      console.warn('⚠️  Skipping test: getStoredToken not implemented');
+      return;
+    }
+
+    // Manually corrupt the stored data
+    localStorage.setItem(`erikey.session.${projectId}`, JSON.stringify({
+      token: 'corrupted-data!!!',
+      expiresAt: mockSession.expiresAt,
+    }));
+
+    const retrieved = await getStoredToken(projectId);
+
+    expect(retrieved).toBeNull();
+    // Should clean up corrupted data
+    expect(localStorage.getItem(`erikey.session.${projectId}`)).toBeNull();
+  });
+
+  it('should clear tokens completely', async () => {
+    if (!storeToken || !getStoredToken || !clearToken) {
+      console.warn('⚠️  Skipping test: encryption functions not implemented');
+      return;
+    }
+
+    await storeToken(projectId, mockSession);
+    clearToken(projectId);
+
+    expect(localStorage.getItem(`erikey.session.${projectId}`)).toBeNull();
+    const retrieved = await getStoredToken(projectId);
+    expect(retrieved).toBeNull();
+  });
+
+  it('should use different encryption per project', async () => {
+    if (!storeToken) {
+      console.warn('⚠️  Skipping test: storeToken not implemented');
+      return;
+    }
+
+    const projectId1 = 'project-1';
+    const projectId2 = 'project-2';
+
+    await storeToken(projectId1, mockSession);
+    await storeToken(projectId2, mockSession);
+
+    const stored1 = localStorage.getItem(`erikey.session.${projectId1}`);
+    const stored2 = localStorage.getItem(`erikey.session.${projectId2}`);
+
+    // Encrypted values should be different (different encryption keys)
+    expect(stored1).not.toBe(stored2);
+  });
+
+  it('should handle non-existent tokens', async () => {
+    if (!getStoredToken) {
+      console.warn('⚠️  Skipping test: getStoredToken not implemented');
+      return;
+    }
+
+    const retrieved = await getStoredToken('non-existent-project');
+    expect(retrieved).toBeNull();
+  });
+});

package/src/auth-client.ts

@@ -0,0 +1,158 @@
+/**
+ * @erikey/react - Auth Client
+ *
+ * Wraps better-auth/react with Erikey-specific enhancements:
+ * - X-Project-Id header injection for multi-tenant routing
+ * - Bearer token auth for cross-origin iframes (Sandpack)
+ * - localStorage token storage when cookies are blocked
+ *
+ * Architecture:
+ * - Uses better-auth's native reactivity (nanostores + useSyncExternalStore)
+ * - Hooks into fetchOptions.onSuccess to store tokens for cross-origin
+ * - No Proxy wrapper - uses better-auth's useSession directly
+ */
+
+import { createAuthClient as createBetterAuthClient } from 'better-auth/react';
+import { siweClient } from 'better-auth/client/plugins';
+import {
+  shouldUseBearerAuth,
+  storeToken,
+  getStoredToken,
+  clearToken,
+  type StoredSession,
+} from './lib/cross-origin-auth';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AuthClientConfig {
+  /**
+   * Your Erikey project ID (pk_live_xxx or pk_test_xxx)
+   */
+  projectId: string;
+
+  /**
+   * Base URL for the auth API
+   * @default 'https://auth.erikey.com'
+   */
+  baseUrl?: string;
+}
+
+// Re-export better-auth types
+export type { Session, User } from 'better-auth';
+
+// ============================================================================
+// Auth Client
+// ============================================================================
+
+/**
+ * Create an auth client for end-user authentication
+ *
+ * Uses better-auth/react with Erikey-specific configuration.
+ * Automatically detects cross-origin contexts (Sandpack, deployed sites)
+ * and uses Bearer tokens instead of cookies.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { createAuthClient } from '@erikey/react';
+ *
+ * const auth = createAuthClient({
+ *   projectId: 'pk_live_xxx',
+ * });
+ *
+ * // Email auth
+ * await auth.signIn.email({ email, password });
+ * await auth.signUp.email({ email, password, name });
+ *
+ * // Social OAuth
+ * await auth.signIn.social({ provider: 'google' });
+ *
+ * // Reactive session hook (React) - uses better-auth's nanostores
+ * const { data: session, isPending } = auth.useSession();
+ *
+ * // Sign out
+ * await auth.signOut();
+ * ```
+ */
+export function createAuthClient(config: AuthClientConfig) {
+  const { projectId, baseUrl = 'https://auth.erikey.com' } = config;
+
+  // Detect if we're in a cross-origin context (Sandpack iframe, deployed site)
+  const useBearerAuth = shouldUseBearerAuth(baseUrl);
+
+  // Build fetch options with Erikey-specific configuration
+  const fetchOptions: NonNullable<Parameters<typeof createBetterAuthClient>[0]>['fetchOptions'] = {
+    // Use onRequest hook to inject headers into EVERY request
+    // (better-auth doesn't pass fetchOptions.headers through correctly)
+    onRequest: (context) => {
+      // Always inject project ID for multi-tenant routing
+      context.headers.set('X-Project-Id', projectId);
+
+      // For cross-origin contexts, inject Bearer token
+      if (useBearerAuth) {
+        const token = getStoredToken(projectId);
+        if (token) {
+          context.headers.set('Authorization', `Bearer ${token}`);
+        }
+      }
+
+      return context;
+    },
+
+    // Hook into successful responses to handle token storage
+    onSuccess: async (context) => {
+      if (!useBearerAuth) return;
+
+      // Get the request path from the URL
+      const url = context.response?.url || '';
+      const path = new URL(url, baseUrl).pathname;
+
+      // Store token after successful sign-in or sign-up
+      // The server returns { token, session, user } for auth endpoints
+      const token = (context.data as any)?.token;
+      if (token && (path.includes('/sign-in') || path.includes('/sign-up'))) {
+        const session: StoredSession = {
+          id: (context.data as any)?.session?.id || 'session',
+          token,
+          expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+        };
+        storeToken(projectId, session);
+      }
+
+      // Clear token after sign-out
+      if (path.includes('/sign-out')) {
+        clearToken(projectId);
+      }
+    },
+
+    // Handle errors - clear token on auth errors
+    onError: async (context) => {
+      if (!useBearerAuth) return;
+
+      // If we get a 401, token is invalid - clear it
+      if (context.response?.status === 401) {
+        clearToken(projectId);
+      }
+    },
+  };
+
+  // Create and return the better-auth client
+  // No Proxy needed - better-auth's useSession uses nanostores which are reactive
+  // The atomListeners system will trigger session refetch after sign-in/sign-up/sign-out
+  const client = createBetterAuthClient({
+    baseURL: baseUrl,
+    fetchOptions,
+    // For same-origin, include cookies (cross-origin uses Bearer from fetchOptions.auth)
+    ...(!useBearerAuth && { credentials: 'include' as const }),
+    // Enable SIWE (Sign-In with Ethereum) support
+    plugins: [siweClient()],
+  });
+
+  return client;
+}
+
+/**
+ * Type helper for inferring the auth client type
+ */
+export type AuthClient = ReturnType<typeof createAuthClient>;

package/src/dashboard-client.ts

@@ -0,0 +1,60 @@
+/**
+ * @erikey/react - Dashboard Client
+ *
+ * Thin wrapper around better-auth/react for the Erikey dashboard.
+ */
+import { createAuthClient as createBetterAuthClient } from 'better-auth/react';
+import { siweClient } from 'better-auth/client/plugins';
+
+export interface DashboardClientConfig {
+  /**
+   * Base URL for the auth API
+   * @default process.env.NEXT_PUBLIC_AUTH_URL || 'https://api.erikey.com'
+   */
+  baseURL?: string;
+
+  /**
+   * Whether to include credentials in requests
+   * @default 'include'
+   */
+  credentials?: RequestCredentials;
+}
+
+/**
+ * Create dashboard client with better-auth
+ *
+ * This is for the Erikey dashboard (erikey.com) - NOT for end-user auth.
+ * For end-user auth in customer apps, use `createAuthClient` instead.
+ *
+ * NOTE: For dashboard user signup (which creates org + project), use the
+ * typed API client (signupApi.dashboard) from @/lib/api/typed-api instead.
+ * This client only handles Better Auth operations (signIn, session, etc.)
+ *
+ * @example
+ * ```tsx
+ * import { createDashboardClient } from '@erikey/react';
+ *
+ * export const auth = createDashboardClient({
+ *   baseURL: process.env.NEXT_PUBLIC_AUTH_URL
+ * });
+ *
+ * // Use Better Auth methods
+ * export const { useSession, signIn, signOut } = auth;
+ * ```
+ */
+export function createDashboardClient(config?: DashboardClientConfig) {
+  const baseURL = config?.baseURL || 'https://api.erikey.com';
+
+  return createBetterAuthClient({
+    baseURL,
+    credentials: config?.credentials || 'include',
+    plugins: [
+      siweClient(), // Enable Sign-In with Ethereum
+    ],
+  });
+}
+
+/**
+ * Type helper for inferring the dashboard client type
+ */
+export type DashboardClient = ReturnType<typeof createDashboardClient>;

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * @erikey/react - React SDK for Erikey
+ *
+ * Two auth clients for different use cases:
+ *
+ * 1. `createDashboardClient` - For the Erikey dashboard (Better Auth)
+ * 2. `createAuthClient` - For customer apps to authenticate end-users
+ *
+ * @example Dashboard (erikey.com)
+ * ```tsx
+ * import { createDashboardClient } from '@erikey/react';
+ *
+ * export const auth = createDashboardClient({
+ *   baseUrl: process.env.NEXT_PUBLIC_AUTH_URL
+ * });
+ *
+ * export const { useSession, signIn, signOut, organization } = auth;
+ * ```
+ *
+ * @example Customer App (end-user auth)
+ * ```tsx
+ * import { createAuthClient } from '@erikey/react';
+ *
+ * const auth = createAuthClient({
+ *   projectId: process.env.NEXT_PUBLIC_ERIKEY_PROJECT_ID!, // pk_live_xxx
+ *   baseUrl: process.env.NEXT_PUBLIC_ERIKEY_BASE_URL,      // Optional
+ * });
+ *
+ * // Email auth
+ * await auth.signIn.email({ email, password });
+ * await auth.signUp.email({ email, password, name });
+ *
+ * // Social OAuth
+ * await auth.signIn.social({ provider: 'google' });
+ *
+ * // Reactive session hook
+ * const { data: session, isPending } = auth.useSession();
+ *
+ * // Sign out
+ * await auth.signOut();
+ * ```
+ *
+ * @example KV Store (per-user storage)
+ * ```tsx
+ * import { createKvClient } from '@erikey/react';
+ *
+ * const kv = createKvClient({
+ *   projectId: process.env.NEXT_PUBLIC_ERIKEY_PROJECT_ID!,
+ * });
+ *
+ * await kv.setValue('preferences', { theme: 'dark' });
+ * const { data } = await kv.getValue('preferences');
+ * ```
+ */
+
+// Dashboard auth (for Erikey dashboard - uses Better Auth)
+export { createDashboardClient } from './dashboard-client';
+export type {
+  DashboardClient,
+  DashboardClientConfig,
+} from './dashboard-client';
+
+// End-user auth (for customer apps - wraps Better Auth with Erikey enhancements)
+export { createAuthClient } from './auth-client';
+export type {
+  AuthClient,
+  AuthClientConfig,
+  Session,
+  User,
+} from './auth-client';
+
+// KV Store (Erikey-specific per-user storage)
+export { createKvClient } from './kv-client';
+export type {
+  KvClient,
+  KvClientConfig,
+  KvPair,
+  KvBulkSetInput,
+  SetValueResponse,
+  GetValueResponse,
+  GetValuesResponse,
+  DeleteValueResponse,
+  DeleteValuesResponse,
+  SetValuesResponse,
+} from './kv-client';
+
+// Export shared types from core (for dashboard client compatibility)
+export type { SessionData, Organization, APIKey, Permission } from './types';