@naculus/connect-appkit-react 0.1.2

package/src/hooks/useSessionKeys.ts

@@ -0,0 +1,356 @@
+"use client";
+
+import { useState, useCallback, useEffect, useRef } from "react";
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+import { getClient } from "../client";
+import { WalletError, SessionKeyManager, MemoryStorageAdapter } from "@naculus/connect-core";
+import type {
+  SessionKeyScope,
+  SessionKeyInfo,
+  SessionKeyManagerConfig,
+} from "@naculus/connect-core";
+
+// ─── Internal singleton for session key management ─────────────────────
+// In a full production setup, this would be injected via context or client config.
+
+let globalSessionKeyManager: SessionKeyManager | null = null;
+
+function getSessionKeyManager(config?: SessionKeyManagerConfig): SessionKeyManager {
+  if (!globalSessionKeyManager) {
+    globalSessionKeyManager = new SessionKeyManager(
+      config,
+      // Use MemoryStorageAdapter for SSR safety; browser integration will use LocalStorageAdapter
+      typeof window !== "undefined" ? undefined : new MemoryStorageAdapter(),
+    );
+  }
+  return globalSessionKeyManager;
+}
+
+// ─── useSessionKeys ────────────────────────────────────────────────────
+
+export interface UseSessionKeysReturn {
+  /** All session keys (active, revoked, expired) */
+  sessions: SessionKeyInfo[];
+  /** Only active session keys */
+  activeSessions: SessionKeyInfo[];
+  /** Whether data is loading */
+  loading: boolean;
+  /** Error from last operation */
+  error: Error | null;
+  /** Refresh the session list from storage */
+  refresh: () => Promise<void>;
+  /** Clear any error */
+  clearError: () => void;
+  /** Whether the storage backend is available */
+  storageAvailable: boolean;
+}
+
+/**
+ * Hook to list and manage session keys.
+ *
+ * @example
+ * ```tsx
+ * const { sessions, activeSessions, refresh } = useSessionKeys();
+ * ```
+ */
+export function useSessionKeys(): UseSessionKeysReturn {
+  const { session } = useWeb3();
+  const [sessions, setSessions] = useState<SessionKeyInfo[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const mountedRef = useRef(true);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const manager = getSessionKeyManager();
+  const storageAvailable = manager.isStorageAvailable();
+
+  const refresh = useCallback(async () => {
+    if (!session) {
+      setSessions([]);
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+    try {
+      const keys = await manager.listSessions();
+      if (mountedRef.current) {
+        setSessions(keys);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error("Failed to load session keys"));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [session, manager]);
+
+  // Load sessions on mount and on session change
+  useEffect(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+
+  const activeSessions = sessions.filter((s) => s.status === "active");
+
+  return {
+    sessions,
+    activeSessions,
+    loading,
+    error,
+    refresh,
+    clearError,
+    storageAvailable,
+  };
+}
+
+// ─── useCreateSessionKey ───────────────────────────────────────────────
+
+export interface UseCreateSessionKeyReturn {
+  /** Create a new session key */
+  createSessionKey: (
+    scope?: Partial<SessionKeyScope>,
+    signerAddress?: `0x${string}`,
+  ) => Promise<SessionKeyInfo>;
+  /** The last created session key info */
+  lastCreated: SessionKeyInfo | null;
+  /** Whether creation is in progress */
+  isCreating: boolean;
+  /** Error from last creation */
+  error: Error | null;
+  /** Clear error */
+  clearError: () => void;
+}
+
+/**
+ * Hook to create new session keys.
+ *
+ * @example
+ * ```tsx
+ * const { createSessionKey, lastCreated, isCreating } = useCreateSessionKey();
+ *
+ * const handleCreate = async () => {
+ *   const session = await createSessionKey({
+ *     expiry: Math.floor(Date.now() / 1000) + 1800, // 30 min
+ *     maxTotalValue: parseEther("0.1"),
+ *   });
+ * };
+ * ```
+ */
+export function useCreateSessionKey(): UseCreateSessionKeyReturn {
+  const { session } = useWeb3();
+  const [lastCreated, setLastCreated] = useState<SessionKeyInfo | null>(null);
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const manager = getSessionKeyManager();
+
+  const createSessionKey = useCallback(
+    async (
+      scope?: Partial<SessionKeyScope>,
+      signerAddress?: `0x${string}`,
+    ): Promise<SessionKeyInfo> => {
+      if (!session) {
+        throw new WalletError("wallet_unavailable", "No active wallet session");
+      }
+
+      setIsCreating(true);
+      setError(null);
+      try {
+        const resolvedSigner = signerAddress ?? undefined;
+        const info = await manager.createSessionKey(scope, resolvedSigner);
+        setLastCreated(info);
+        return info;
+      } catch (err) {
+        const errorObj = err instanceof Error ? err : new Error("Failed to create session key");
+        setError(errorObj);
+        throw errorObj;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [session, manager],
+  );
+
+  return {
+    createSessionKey,
+    lastCreated,
+    isCreating,
+    error,
+    clearError,
+  };
+}
+
+// ─── useRevokeSession ──────────────────────────────────────────────────
+
+export interface UseRevokeSessionReturn {
+  /** Revoke a session key by ID */
+  revokeSession: (sessionId: string) => Promise<void>;
+  /** Whether revoking is in progress */
+  isRevoking: boolean;
+  /** Error from last operation */
+  error: Error | null;
+  /** Clear error */
+  clearError: () => void;
+}
+
+/**
+ * Hook to revoke a session key.
+ *
+ * @example
+ * ```tsx
+ * const { revokeSession, isRevoking } = useRevokeSession();
+ * await revokeSession(sessionId);
+ * ```
+ */
+export function useRevokeSession(): UseRevokeSessionReturn {
+  const [isRevoking, setIsRevoking] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const manager = getSessionKeyManager();
+
+  const revokeSession = useCallback(
+    async (sessionId: string): Promise<void> => {
+      setIsRevoking(true);
+      setError(null);
+      try {
+        await manager.revokeSession(sessionId);
+      } catch (err) {
+        const errorObj = err instanceof Error ? err : new Error("Failed to revoke session key");
+        setError(errorObj);
+        throw errorObj;
+      } finally {
+        setIsRevoking(false);
+      }
+    },
+    [manager],
+  );
+
+  return {
+    revokeSession,
+    isRevoking,
+    error,
+    clearError,
+  };
+}
+
+// ─── useSendWithSession ────────────────────────────────────────────────
+
+export interface UseSendWithSessionReturn {
+  /** Sign a message hash using a session key */
+  signWithSession: (sessionId: string, messageHash: `0x${string}`) => Promise<`0x${string}`>;
+  /** Check if a transaction is within a session's scope */
+  checkScope: (
+    sessionId: string,
+    tx: {
+      to?: string;
+      value?: string;
+      data?: string;
+      chainId?: number;
+      gas?: string;
+    },
+  ) => Promise<{
+    valid: boolean;
+    reason?: string;
+    remainingGas?: bigint;
+    remainingValue?: bigint;
+    remainingTxCount?: number;
+  }>;
+  /** Whether an operation is in progress */
+  isBusy: boolean;
+  /** Error from last operation */
+  error: Error | null;
+  /** Clear error */
+  clearError: () => void;
+}
+
+/**
+ * Hook to sign transactions using session keys and check scope.
+ *
+ * @example
+ * ```tsx
+ * const { signWithSession, checkScope } = useSendWithSession();
+ *
+ * const check = await checkScope(sessionId, tx);
+ * if (check.valid) {
+ *   const sig = await signWithSession(sessionId, messageHash);
+ * }
+ * ```
+ */
+export function useSendWithSession(): UseSendWithSessionReturn {
+  const [isBusy, setIsBusy] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const manager = getSessionKeyManager();
+
+  const signWithSession = useCallback(
+    async (sessionId: string, messageHash: `0x${string}`): Promise<`0x${string}`> => {
+      setIsBusy(true);
+      setError(null);
+      try {
+        return await manager.signWithSessionKey(sessionId, messageHash);
+      } catch (err) {
+        const errorObj = err instanceof Error ? err : new Error("Failed to sign with session key");
+        setError(errorObj);
+        throw errorObj;
+      } finally {
+        setIsBusy(false);
+      }
+    },
+    [manager],
+  );
+
+  const checkScope = useCallback(
+    async (
+      sessionId: string,
+      tx: {
+        to?: string;
+        value?: string;
+        data?: string;
+        chainId?: number;
+        gas?: string;
+      },
+    ) => {
+      setIsBusy(true);
+      setError(null);
+      try {
+        return await manager.checkSessionScope(sessionId, tx);
+      } catch (err) {
+        const errorObj = err instanceof Error ? err : new Error("Failed to check session scope");
+        setError(errorObj);
+        throw errorObj;
+      } finally {
+        setIsBusy(false);
+      }
+    },
+    [manager],
+  );
+
+  return {
+    signWithSession,
+    checkScope,
+    isBusy,
+    error,
+    clearError,
+  };
+}
+
+/**
+ * Reset the global session key manager (useful for testing / cleanup).
+ */
+export function resetSessionKeyManager(): void {
+  globalSessionKeyManager = null;
+}

package/src/hooks/useSignInWithEthereum.test.ts

@@ -0,0 +1,224 @@
+/// <reference types="vitest" />
+/// @vitest-environment jsdom
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+const mockUseWeb3 = vi.fn();
+vi.mock("../provider/Web3ConnectProvider", () => ({
+  useWeb3: () => mockUseWeb3(),
+  Web3ConnectProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+const mockSignMessage = vi.fn();
+const mockGetClient = vi.fn();
+vi.mock("../client", () => ({
+  getClient: () => mockGetClient(),
+}));
+
+import { useSignInWithEthereum } from "./useSignInWithEthereum";
+
+function createEvmSession() {
+  return {
+    topic: "test-topic",
+    namespaces: {
+      eip155: {
+        chains: ["eip155:1"],
+        accounts: ["eip155:1:0x1234567890123456789012345678901234567890"],
+      },
+    },
+  };
+}
+
+describe("useSignInWithEthereum", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should have initial idle state", () => {
+    mockUseWeb3.mockReturnValue({ session: null, chainId: null });
+    mockGetClient.mockReturnValue(null);
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    expect(result.current.isSigningIn).toBe(false);
+    expect(result.current.result).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("should throw when no session", async () => {
+    mockUseWeb3.mockReturnValue({ session: null, chainId: null });
+    mockGetClient.mockReturnValue({
+      signMessage: mockSignMessage,
+    });
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    await expect(result.current.signIn()).rejects.toThrow("No active session");
+  });
+
+  it("should throw when client not initialized", async () => {
+    mockUseWeb3.mockReturnValue({ session: createEvmSession(), chainId: "eip155:1" });
+    mockGetClient.mockReturnValue(null);
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    await expect(result.current.signIn()).rejects.toThrow("Client not initialized");
+  });
+
+  it("should throw when no EVM accounts in session", async () => {
+    const solanaSession = {
+      topic: "test-topic",
+      namespaces: {
+        solana: {
+          chains: ["solana:4sGjMW1s"],
+          accounts: ["solana:4sGjMW1s:5JG7DPRQAxJVCLx3GxsHTxP1KZbSyLmPQBLkLhFZPGrH"],
+        },
+      },
+    };
+
+    mockUseWeb3.mockReturnValue({ session: solanaSession, chainId: null });
+    mockGetClient.mockReturnValue({
+      signMessage: mockSignMessage,
+    });
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    await expect(result.current.signIn()).rejects.toThrow(
+      "No EVM (eip155) accounts found in session"
+    );
+  });
+
+  it("should sign in with Ethereum successfully", async () => {
+    const mockSignature = "0xsiwsignature1234567890abcdef";
+    mockSignMessage.mockResolvedValue(mockSignature);
+    mockUseWeb3.mockReturnValue({
+      session: createEvmSession(),
+      chainId: "eip155:1",
+    });
+    mockGetClient.mockReturnValue({
+      signMessage: mockSignMessage,
+    });
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    let siwxResult: Awaited<ReturnType<typeof result.current.signIn>> | undefined;
+
+    await act(async () => {
+      siwxResult = await result.current.signIn({
+        statement: "Sign in to MyApp",
+      });
+    });
+
+    expect(siwxResult!).toBeDefined();
+    expect(siwxResult!.signature).toBe(mockSignature);
+    expect(siwxResult!.message.domain).toBe("localhost:3000");
+    expect(siwxResult!.message.address).toBe("eip155:1:0x1234567890123456789012345678901234567890");
+    expect(siwxResult!.message.statement).toBe("Sign in to MyApp");
+    expect(siwxResult!.message.version).toBe(1);
+    expect(siwxResult!.message.chainId).toBe("eip155:1");
+    expect(siwxResult!.message.nonce).toHaveLength(16);
+    expect(siwxResult!.message.issuedAt).toBeTruthy();
+    expect(mockSignMessage).toHaveBeenCalledTimes(1);
+    expect(result.current.isSigningIn).toBe(false);
+    expect(result.current.result).toBe(siwxResult);
+  });
+
+  it("should set loading state during signing", async () => {
+    let resolvePromise: (v: string) => void;
+    const signPromise = new Promise<string>((resolve) => {
+      resolvePromise = resolve;
+    });
+    mockSignMessage.mockReturnValue(signPromise);
+    mockUseWeb3.mockReturnValue({
+      session: createEvmSession(),
+      chainId: "eip155:1",
+    });
+    mockGetClient.mockReturnValue({
+      signMessage: mockSignMessage,
+    });
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    let callPromise: Promise<unknown>;
+    act(() => {
+      callPromise = result.current.signIn();
+    });
+
+    expect(result.current.isSigningIn).toBe(true);
+
+    await act(async () => {
+      resolvePromise!("0xsig");
+      await callPromise!;
+    });
+
+    expect(result.current.isSigningIn).toBe(false);
+  });
+
+  it("should capture error on failed signing", async () => {
+    mockSignMessage.mockRejectedValue(new Error("User rejected"));
+    mockUseWeb3.mockReturnValue({
+      session: createEvmSession(),
+      chainId: "eip155:1",
+    });
+    mockGetClient.mockReturnValue({
+      signMessage: mockSignMessage,
+    });
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    await act(async () => {
+      try {
+        await result.current.signIn();
+      } catch {
+        // Expected
+      }
+    });
+
+    expect(result.current.error).not.toBeNull();
+    expect(result.current.error?.message).toBe("User rejected");
+  });
+
+  it("should clear error", () => {
+    mockUseWeb3.mockReturnValue({ session: null, chainId: null });
+    mockGetClient.mockReturnValue(null);
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    act(() => {
+      result.current.clearError();
+    });
+
+    expect(result.current.error).toBeNull();
+  });
+
+  it("should accept custom domain and URI", async () => {
+    const mockSignature = "0xsig";
+    mockSignMessage.mockResolvedValue(mockSignature);
+    mockUseWeb3.mockReturnValue({
+      session: createEvmSession(),
+      chainId: "eip155:1",
+    });
+    mockGetClient.mockReturnValue({
+      signMessage: mockSignMessage,
+    });
+
+    const { result } = renderHook(() => useSignInWithEthereum());
+
+    let siwxResult: Awaited<ReturnType<typeof result.current.signIn>> | undefined;
+
+    await act(async () => {
+      siwxResult = await result.current.signIn({
+        domain: "app.example.com",
+        uri: "https://app.example.com/login",
+        expirySeconds: 3600,
+        resources: ["https://app.example.com/privacy"],
+      });
+    });
+
+    expect(siwxResult!.message.domain).toBe("app.example.com");
+    expect(siwxResult!.message.uri).toBe("https://app.example.com/login");
+    expect(siwxResult!.message.expirationTime).toBeTruthy();
+    expect(siwxResult!.message.resources).toContain("https://app.example.com/privacy");
+  });
+});

package/src/hooks/useSignInWithEthereum.ts

@@ -0,0 +1,46 @@
+import { useSignInWithX } from "./useSignInWithX";
+import type { UseSignInWithXOptions, UseSignInWithXReturn } from "./useSignInWithX";
+import { WalletError } from "@naculus/connect-core";
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+import { useCallback } from "react";
+
+export interface UseSignInWithEthereumOptions extends UseSignInWithXOptions {}
+
+export interface UseSignInWithEthereumReturn extends UseSignInWithXReturn {}
+
+function useEip155SessionGuard(): () => void {
+  const { session } = useWeb3();
+  return useCallback(() => {
+    if (!session) {
+      throw new WalletError("wallet_unavailable", "No active session");
+    }
+    const evmNamespace = session.namespaces["eip155"];
+    if (!evmNamespace || evmNamespace.accounts.length === 0) {
+      throw new WalletError(
+        "namespace_mismatch",
+        "No EVM (eip155) accounts found in session"
+      );
+    }
+  }, [session]);
+}
+
+export function useSignInWithEthereum(): UseSignInWithEthereumReturn {
+  const guard = useEip155SessionGuard();
+  const siwx = useSignInWithX();
+
+  const signIn = useCallback(
+    async (options?: UseSignInWithEthereumOptions) => {
+      guard();
+      return siwx.signIn(options);
+    },
+    [guard, siwx.signIn]
+  );
+
+  return {
+    signIn,
+    isSigningIn: siwx.isSigningIn,
+    result: siwx.result,
+    error: siwx.error,
+    clearError: siwx.clearError,
+  };
+}