@rockerone/xprnkit 0.3.1 → 0.3.3

package/README.md

@@ -519,6 +519,147 @@ function ExistingComponent() {
 }
 ```
 
+## Authentication Persistence and SSR
+
+### Overview
+
+XPRNKit automatically restores **wallet sessions** via the `restoreSession` config option, but **authentication data** (tokens, permissions, etc.) is **not automatically persisted** to give you full control over your security model.
+
+This design is intentional:
+- ✅ **Wallet Connection** = Handled by XPRNKit (via Proton Web SDK)
+- ❌ **Authentication State** = Your responsibility (localStorage, cookies, server sessions, etc.)
+
+### Storage Helper Utilities
+
+XPRNKit provides optional helper utilities:
+
+```typescript
+import { authStorage } from 'xprnkit';
+
+// Save authentication data
+authStorage.save('user@proton', {
+  actor: 'user@proton',
+  publicKey: 'PUB_K1_...',
+  data: { token: 'jwt-token' },
+  expiresAt: Date.now() + 86400000,
+});
+
+// Load/clear/list
+const auth = authStorage.load('user@proton');
+authStorage.clear('user@proton');
+authStorage.clearAll();
+const actors = authStorage.listActors();
+```
+
+### Implementation Patterns
+
+#### Pattern 1: Client-Side (localStorage)
+
+**Use Case:** Simple apps, prototypes
+
+```typescript
+import { useXPRN, authStorage } from 'xprnkit';
+
+function MyApp() {
+  const { session, authenticate } = useXPRN();
+
+  const handleAuth = () => {
+    authenticate(
+      (authData) => {
+        authStorage.save(session.auth.actor.toString(), {
+          actor: session.auth.actor.toString(),
+          publicKey: session.publicKey.toString(),
+          data: authData,
+          expiresAt: Date.now() + 86400000,
+        });
+      },
+      (error) => console.error(error)
+    );
+  };
+}
+```
+
+#### Pattern 2: SSR with Cookies (Next.js)
+
+**Use Case:** Next.js apps, production
+
+**Client:**
+```typescript
+'use client';
+import { useXPRN } from 'xprnkit';
+
+function MyApp() {
+  const { session, authenticate } = useXPRN();
+
+  const handleAuth = () => {
+    authenticate(
+      async (authData) => {
+        await fetch('/api/auth/session', {
+          method: 'POST',
+          body: JSON.stringify({ actor: session.auth.actor, authData }),
+        });
+      },
+      (error) => console.error(error)
+    );
+  };
+}
+```
+
+**Server:**
+```typescript
+// app/api/auth/session/route.ts
+import { NextResponse } from 'next/server';
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const response = NextResponse.json({ success: true });
+  
+  response.cookies.set('xprn_session', createToken(body), {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: 86400,
+  });
+  
+  return response;
+}
+```
+
+#### Pattern 3: Server Sessions (Redis/DB)
+
+**Use Case:** Scalable production apps
+
+```typescript
+// app/api/session/create/route.ts
+import { redis } from '@/lib/redis';
+import { randomUUID } from 'crypto';
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const sessionId = randomUUID();
+  
+  await redis.setex(\`session:\${sessionId}\`, 86400, JSON.stringify(body));
+  
+  const response = NextResponse.json({ success: true });
+  response.cookies.set('session_id', sessionId, { httpOnly: true });
+  return response;
+}
+```
+
+### Comparison
+
+| Approach | Security | SSR | Best For |
+|----------|----------|-----|----------|
+| **localStorage** | Medium | ❌ | Client apps |
+| **Cookies** | High | ✅ | SSR apps |
+| **Server Sessions** | Very High | ✅ | Production |
+
+### Full Examples
+
+See the `examples/` directory for complete implementations:
+- `auth-localstorage.example.tsx` - Client-side with localStorage
+- `auth-cookies-ssr.example.tsx` - SSR with httpOnly cookies
+- `auth-server-session.example.tsx` - Server sessions with Redis/PostgreSQL
+
 # Components Documentation
 
 # XRPNContainer

package/build/index.d.ts

@@ -1,5 +1,6 @@
 export * from './providers/XPRNProvider';
 export * from './components';
 export * from './utils';
+export * from './services';
 export type { Link, LinkSession, ProtonWebLink } from "@proton/web-sdk";
 export type { Api, ApiInterfaces, JsonRpc, JsSignatureProvider } from "@proton/js";

package/build/index.js

@@ -1,3 +1,4 @@
 export * from './providers/XPRNProvider';
 export * from './components';
 export * from './utils';
+export * from './services';

package/build/providers/XPRNProvider.d.ts

@@ -1,6 +1,7 @@
 import type { Link, LinkSession, ProtonWebLink } from "@proton/web-sdk";
 import React from "react";
 import { JsonRpc } from "@proton/js";
+import { type IdentityProofStatus } from "../services/identity-proof";
 export type XPRNAuthentication = {
     actor: string;
     publicKey: string;
@@ -53,6 +54,8 @@ type XPRNProviderContext = {
     switchSession: (actor: string) => void;
     getSessionById: (actor: string) => XPRNSession | null;
     getSessionByActor: (actor: string) => XPRNSession | null;
+    authStatus: IdentityProofStatus;
+    getAuthStatus: (actor?: string) => IdentityProofStatus;
 };
 export declare const XPRNProvider: React.FunctionComponent<XPRNProviderProps>;
 export declare function useXPRN(): XPRNProviderContext;

package/build/providers/XPRNProvider.js

@@ -5,7 +5,7 @@ import ConnectWallet from "@proton/web-sdk";
 import React, { useCallback, useContext, useEffect, useMemo, useReducer, useRef, } from "react";
 import { JsonRpc } from "@proton/js";
 import { parseTransactionErrorMessage } from "../utils";
-import { proton_wrap } from "../interfaces/proton_wrap";
+import { createIdentityProof, verifyIdentityProof, } from "../services/identity-proof";
 const XPRNContext = React.createContext({
     session: null,
     link: null,
@@ -14,7 +14,7 @@ const XPRNContext = React.createContext({
     txErrorsStack: null,
     connect: () => { },
     disconnect: () => { },
-    addTransactionError(rawMessage) { },
+    addTransactionError() { },
     authentication: null,
     authenticate: () => { },
     getActiveSession: () => null,
@@ -25,6 +25,8 @@ const XPRNContext = React.createContext({
     switchSession: () => { },
     getSessionById: () => null,
     getSessionByActor: () => null,
+    authStatus: "idle",
+    getAuthStatus: () => "idle",
 });
 export const XPRNProvider = ({ children, config, }) => {
     // Force update mechanism - only triggers re-render when active session changes
@@ -37,19 +39,32 @@ export const XPRNProvider = ({ children, config, }) => {
     const onSessionRef = useRef();
     const onProfileRef = useRef();
     const isRestoringRef = useRef(false);
+    // Authentication refs - for duplicate prevention and cancellation
+    const authStatusRef = useRef(new Map());
+    const authenticatingRef = useRef(new Set());
+    const authAbortControllersRef = useRef(new Map());
     // Derived values - recomputed only when version changes (active session affected)
-    const { activeSession, session, link, profile, authentication } = useMemo(() => {
+    const { activeSession, session, link, profile, authentication, authStatus } = useMemo(() => {
         const active = activeSessionIdRef.current
             ? sessionsRef.current.get(activeSessionIdRef.current) ?? null
             : null;
+        const status = activeSessionIdRef.current
+            ? authStatusRef.current.get(activeSessionIdRef.current) ?? "idle"
+            : "idle";
         return {
             activeSession: active,
             session: active?.session ?? null,
             link: active?.link ?? null,
             profile: active?.profile ?? null,
             authentication: active?.authentication ?? null,
+            authStatus: status,
         };
     }, [version]);
+    // Get auth status for any actor
+    const getAuthStatus = useCallback((actor) => {
+        const target = actor || activeSessionIdRef.current;
+        return target ? authStatusRef.current.get(target) ?? "idle" : "idle";
+    }, []);
     // Session management methods - stable callbacks using refs
     const getActiveSession = useCallback(() => {
         return activeSessionIdRef.current
@@ -187,7 +202,7 @@ export const XPRNProvider = ({ children, config, }) => {
     const addTxError = useCallback((message) => {
         errorsStackRef.current.push(parseTransactionErrorMessage(message));
     }, []);
-    const authenticate = useCallback((success, fail, actor) => {
+    const authenticate = useCallback(async (success, fail, actor) => {
         // Use provided actor or active session
         const targetActor = actor || activeSessionIdRef.current;
         if (!targetActor) {
@@ -203,69 +218,77 @@ export const XPRNProvider = ({ children, config, }) => {
             fail(new Error("Authentication URL not configured"));
             return;
         }
-        const authenticationAction = proton_wrap.generateauth([
-            {
-                actor: targetSession.session.auth.actor.toString(),
-                permission: targetSession.session.auth.permission.toString(),
-            },
-        ], {
-            protonAccount: targetSession.session.auth.actor.toString(),
-            time: new Date().toISOString().slice(0, -1),
-        });
+        // Prevent duplicate requests
+        if (authenticatingRef.current.has(targetActor)) {
+            fail(new Error(`Authentication already in progress for ${targetActor}`));
+            return;
+        }
+        // Cancel any previous request for this actor
+        authAbortControllersRef.current.get(targetActor)?.abort();
+        const abortController = new AbortController();
+        authAbortControllersRef.current.set(targetActor, abortController);
+        authenticatingRef.current.add(targetActor);
+        // Update status
+        const updateStatus = (status) => {
+            authStatusRef.current.set(targetActor, status);
+            if (activeSessionIdRef.current === targetActor) {
+                forceUpdate();
+            }
+        };
         try {
-            targetSession.session
-                .transact({ actions: [authenticationAction] }, { broadcast: false })
-                .then(res => {
-                const identityProofBody = {
-                    signer: {
-                        actor: targetSession.session.auth.actor,
-                        permission: targetSession.session.auth.permission,
-                        public_key: targetSession.session.publicKey,
-                    },
-                    transaction: res.resolvedTransaction,
-                    signatures: res.signatures,
-                };
-                if (config.authenticationUrl)
-                    fetch(config.authenticationUrl, {
-                        method: "post",
-                        body: JSON.stringify(identityProofBody),
-                    })
-                        .then(res => res.json())
-                        .then(authRes => {
-                        const authData = {
-                            publicKey: targetSession.session.publicKey.toString(),
-                            actor: targetSession.session.auth.actor.toString(),
-                            data: authRes,
-                        };
-                        // Update session with authentication data (mutate ref)
-                        const existingSession = sessionsRef.current.get(targetActor);
-                        if (existingSession) {
-                            sessionsRef.current.set(targetActor, {
-                                ...existingSession,
-                                authentication: authData,
-                            });
-                        }
-                        // Only trigger re-render if this is the active session
-                        if (activeSessionIdRef.current === targetActor) {
-                            forceUpdate();
-                        }
-                        success(authRes);
-                    })
-                        .catch(fail);
-            })
-                .catch(fail);
+            // Step 1: Sign with wallet
+            updateStatus("signing");
+            const proof = await createIdentityProof(targetSession.session, {
+                signal: abortController.signal,
+            });
+            // Step 2: Verify with backend
+            updateStatus("verifying");
+            const authRes = await verifyIdentityProof(proof, { authenticationUrl: config.authenticationUrl }, { signal: abortController.signal });
+            // Step 3: Update session with authentication data
+            const authData = {
+                publicKey: proof.signer.publicKey,
+                actor: proof.signer.actor,
+                data: authRes,
+            };
+            const existingSession = sessionsRef.current.get(targetActor);
+            if (existingSession) {
+                sessionsRef.current.set(targetActor, {
+                    ...existingSession,
+                    authentication: authData,
+                });
+            }
+            // Success
+            updateStatus("success");
+            success(authRes);
         }
-        catch (e) {
-            fail(e);
+        catch (error) {
+            // Handle abort silently
+            if (error instanceof Error && error.name === "AbortError") {
+                updateStatus("idle");
+                return;
+            }
+            // Handle other errors
+            updateStatus("error");
+            fail(error);
         }
-    }, [config, forceUpdate]);
+        finally {
+            authenticatingRef.current.delete(targetActor);
+            if (authAbortControllersRef.current.get(targetActor) === abortController) {
+                authAbortControllersRef.current.delete(targetActor);
+            }
+        }
+    }, [config.authenticationUrl, forceUpdate]);
     // Handle authentication for active session
     useEffect(() => {
         if (session && activeSessionIdRef.current) {
             const currentSession = sessionsRef.current.get(activeSessionIdRef.current);
             if (currentSession && !currentSession.authentication) {
                 if (config.enforceAuthentication && config.authenticationUrl) {
-                    authenticate(() => { }, () => { });
+                    authenticate(() => {
+                        console.log(`[XPRNProvider] Auto-authenticated: ${activeSessionIdRef.current}`);
+                    }, error => {
+                        console.error("[XPRNProvider] Auto-authentication failed:", error);
+                    });
                 }
             }
         }
@@ -273,7 +296,19 @@ export const XPRNProvider = ({ children, config, }) => {
             onSessionRef.current(session);
             onSessionRef.current = undefined; // Reset the ref
         }
-    }, [session, authenticate, config.enforceAuthentication, config.authenticationUrl]);
+    }, [
+        session,
+        authenticate,
+        config.enforceAuthentication,
+        config.authenticationUrl,
+    ]);
+    // Cleanup abort controllers on unmount
+    useEffect(() => {
+        return () => {
+            authAbortControllersRef.current.forEach(controller => controller.abort());
+            authAbortControllersRef.current.clear();
+        };
+    }, []);
     // Handle profile callbacks
     useEffect(() => {
         if (profile && onProfileRef.current) {
@@ -318,6 +353,9 @@ export const XPRNProvider = ({ children, config, }) => {
             switchSession,
             getSessionById,
             getSessionByActor,
+            // Authentication status
+            authStatus,
+            getAuthStatus,
         };
     }, [
         // Reactive values (change when active session changes)
@@ -325,6 +363,7 @@ export const XPRNProvider = ({ children, config, }) => {
         link,
         profile,
         authentication,
+        authStatus,
         // Stable callbacks (only change when their specific deps change)
         addTxError,
         connect,
@@ -338,6 +377,7 @@ export const XPRNProvider = ({ children, config, }) => {
         switchSession,
         getSessionById,
         getSessionByActor,
+        getAuthStatus,
     ]);
     return (_jsx(XPRNContext.Provider, { value: providerValue, children: children }));
 };

package/build/services/identity-proof/create-identity-proof.d.ts

@@ -0,0 +1,23 @@
+import type { LinkSession } from "@proton/web-sdk";
+import type { IdentityProof } from "./types";
+export type CreateIdentityProofOptions = {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+};
+/**
+ * Creates an identity proof by signing a generateauth action with the wallet.
+ *
+ * This is a pure function that handles only the wallet signing step.
+ * It does NOT send the proof to any backend - use `verifyIdentityProof` for that.
+ *
+ * @param session - The LinkSession from the connected wallet
+ * @param options - Optional configuration (abort signal)
+ * @returns Promise resolving to the signed IdentityProof
+ *
+ * @example
+ * ```typescript
+ * const proof = await createIdentityProof(session);
+ * // proof contains: { signer, transaction, signatures }
+ * ```
+ */
+export declare function createIdentityProof(session: LinkSession, options?: CreateIdentityProofOptions): Promise<IdentityProof>;

package/build/services/identity-proof/create-identity-proof.js

@@ -0,0 +1,47 @@
+import { proton_wrap } from "../../interfaces/proton_wrap";
+/**
+ * Creates an identity proof by signing a generateauth action with the wallet.
+ *
+ * This is a pure function that handles only the wallet signing step.
+ * It does NOT send the proof to any backend - use `verifyIdentityProof` for that.
+ *
+ * @param session - The LinkSession from the connected wallet
+ * @param options - Optional configuration (abort signal)
+ * @returns Promise resolving to the signed IdentityProof
+ *
+ * @example
+ * ```typescript
+ * const proof = await createIdentityProof(session);
+ * // proof contains: { signer, transaction, signatures }
+ * ```
+ */
+export async function createIdentityProof(session, options) {
+    // Check for abort before starting
+    if (options?.signal?.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+    }
+    const actor = session.auth.actor.toString();
+    const permission = session.auth.permission.toString();
+    // Generate the authentication action
+    const authenticationAction = proton_wrap.generateauth([{ actor, permission }], {
+        protonAccount: actor,
+        time: new Date().toISOString().slice(0, -1),
+    });
+    // Sign the transaction without broadcasting
+    const txResult = await session.transact({ actions: [authenticationAction] }, { broadcast: false });
+    // Check for abort after wallet interaction
+    if (options?.signal?.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+    }
+    // Build the identity proof
+    const proof = {
+        signer: {
+            actor,
+            permission,
+            publicKey: session.publicKey.toString(),
+        },
+        transaction: txResult.resolvedTransaction,
+        signatures: txResult.signatures.map(sig => sig.toString()),
+    };
+    return proof;
+}

package/build/services/identity-proof/index.d.ts

@@ -0,0 +1,6 @@
+export type { IdentityProof, IdentityProofConfig, IdentityProofResult, IdentityProofSigner, IdentityProofStatus, UseIdentityProofOptions, UseIdentityProofReturn, } from "./types";
+export { createIdentityProof } from "./create-identity-proof";
+export type { CreateIdentityProofOptions } from "./create-identity-proof";
+export { verifyIdentityProof } from "./verify-identity-proof";
+export type { VerifyIdentityProofOptions } from "./verify-identity-proof";
+export { useIdentityProof } from "./use-identity-proof";

package/build/services/identity-proof/index.js

@@ -0,0 +1,5 @@
+// Pure functions
+export { createIdentityProof } from "./create-identity-proof";
+export { verifyIdentityProof } from "./verify-identity-proof";
+// React hook
+export { useIdentityProof } from "./use-identity-proof";

package/build/services/identity-proof/types.d.ts

@@ -0,0 +1,62 @@
+import type { LinkSession } from "@proton/web-sdk";
+/**
+ * Signer information for identity proof
+ */
+export type IdentityProofSigner = {
+    actor: string;
+    permission: string;
+    publicKey: string;
+};
+/**
+ * Identity proof generated from wallet signing
+ */
+export type IdentityProof = {
+    signer: IdentityProofSigner;
+    transaction: any;
+    signatures: string[];
+};
+/**
+ * Result of identity proof verification
+ */
+export type IdentityProofResult<T = any> = {
+    proof: IdentityProof;
+    response: T;
+};
+/**
+ * Configuration for identity proof verification
+ */
+export type IdentityProofConfig = {
+    authenticationUrl: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+};
+/**
+ * Status of identity proof process
+ */
+export type IdentityProofStatus = "idle" | "signing" | "verifying" | "success" | "error";
+/**
+ * Options for useIdentityProof hook
+ */
+export type UseIdentityProofOptions = {
+    session: LinkSession | null;
+    config?: IdentityProofConfig;
+    onSuccess?: (result: IdentityProofResult) => void;
+    onError?: (error: Error) => void;
+};
+/**
+ * Return type for useIdentityProof hook
+ */
+export type UseIdentityProofReturn = {
+    /** Trigger authentication flow */
+    authenticate: () => Promise<IdentityProofResult | null>;
+    /** Current status of the authentication process */
+    status: IdentityProofStatus;
+    /** Error if authentication failed */
+    error: Error | null;
+    /** Result if authentication succeeded */
+    result: IdentityProofResult | null;
+    /** Reset state to idle */
+    reset: () => void;
+    /** Convenience boolean for loading states */
+    isAuthenticating: boolean;
+};

package/build/services/identity-proof/types.js

@@ -0,0 +1 @@
+export {};

package/build/services/identity-proof/use-identity-proof.d.ts

@@ -0,0 +1,38 @@
+import type { UseIdentityProofOptions, UseIdentityProofReturn } from "./types";
+/**
+ * React hook for identity proof authentication.
+ *
+ * This is the primary API for authentication in XPRNKit.
+ * It combines wallet signing and backend verification into a single flow
+ * with state management, duplicate prevention, and cleanup handling.
+ *
+ * @param options - Configuration options
+ * @returns Object with authenticate function and state
+ *
+ * @example
+ * ```tsx
+ * function AuthButton() {
+ *   const { session } = useXPRN();
+ *   const {
+ *     authenticate,
+ *     status,
+ *     error,
+ *     isAuthenticating
+ *   } = useIdentityProof({
+ *     session,
+ *     config: { authenticationUrl: '/api/auth' },
+ *     onSuccess: (result) => console.log('Authenticated!', result),
+ *   });
+ *
+ *   return (
+ *     <button onClick={authenticate} disabled={isAuthenticating}>
+ *       {status === 'signing' && 'Sign in wallet...'}
+ *       {status === 'verifying' && 'Verifying...'}
+ *       {status === 'idle' && 'Authenticate'}
+ *       {status === 'error' && 'Retry'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useIdentityProof(options: UseIdentityProofOptions): UseIdentityProofReturn;

package/build/services/identity-proof/use-identity-proof.js

@@ -0,0 +1,143 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createIdentityProof } from "./create-identity-proof";
+import { verifyIdentityProof } from "./verify-identity-proof";
+/**
+ * React hook for identity proof authentication.
+ *
+ * This is the primary API for authentication in XPRNKit.
+ * It combines wallet signing and backend verification into a single flow
+ * with state management, duplicate prevention, and cleanup handling.
+ *
+ * @param options - Configuration options
+ * @returns Object with authenticate function and state
+ *
+ * @example
+ * ```tsx
+ * function AuthButton() {
+ *   const { session } = useXPRN();
+ *   const {
+ *     authenticate,
+ *     status,
+ *     error,
+ *     isAuthenticating
+ *   } = useIdentityProof({
+ *     session,
+ *     config: { authenticationUrl: '/api/auth' },
+ *     onSuccess: (result) => console.log('Authenticated!', result),
+ *   });
+ *
+ *   return (
+ *     <button onClick={authenticate} disabled={isAuthenticating}>
+ *       {status === 'signing' && 'Sign in wallet...'}
+ *       {status === 'verifying' && 'Verifying...'}
+ *       {status === 'idle' && 'Authenticate'}
+ *       {status === 'error' && 'Retry'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useIdentityProof(options) {
+    const { session, config, onSuccess, onError } = options;
+    // State
+    const [status, setStatus] = useState("idle");
+    const [error, setError] = useState(null);
+    const [result, setResult] = useState(null);
+    // Refs for cleanup and duplicate prevention
+    const abortControllerRef = useRef(null);
+    const isAuthenticatingRef = useRef(false);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            abortControllerRef.current?.abort();
+        };
+    }, []);
+    // Reset function
+    const reset = useCallback(() => {
+        abortControllerRef.current?.abort();
+        abortControllerRef.current = null;
+        isAuthenticatingRef.current = false;
+        setStatus("idle");
+        setError(null);
+        setResult(null);
+    }, []);
+    // Main authenticate function
+    const authenticate = useCallback(async () => {
+        // Validate inputs
+        if (!session) {
+            const err = new Error("No session available for authentication");
+            setError(err);
+            setStatus("error");
+            onError?.(err);
+            return null;
+        }
+        if (!config?.authenticationUrl) {
+            const err = new Error("Authentication URL not configured");
+            setError(err);
+            setStatus("error");
+            onError?.(err);
+            return null;
+        }
+        // Prevent duplicate requests
+        if (isAuthenticatingRef.current) {
+            const err = new Error("Authentication already in progress");
+            onError?.(err);
+            return null;
+        }
+        // Cancel any previous request
+        abortControllerRef.current?.abort();
+        const abortController = new AbortController();
+        abortControllerRef.current = abortController;
+        isAuthenticatingRef.current = true;
+        try {
+            // Step 1: Sign with wallet
+            setStatus("signing");
+            setError(null);
+            const proof = await createIdentityProof(session, {
+                signal: abortController.signal,
+            });
+            // Step 2: Verify with backend
+            setStatus("verifying");
+            const response = await verifyIdentityProof(proof, config, {
+                signal: abortController.signal,
+            });
+            // Success
+            const identityResult = {
+                proof,
+                response,
+            };
+            setResult(identityResult);
+            setStatus("success");
+            onSuccess?.(identityResult);
+            return identityResult;
+        }
+        catch (err) {
+            // Handle abort silently
+            if (err instanceof Error && err.name === "AbortError") {
+                setStatus("idle");
+                return null;
+            }
+            // Handle other errors
+            const error = err instanceof Error ? err : new Error(String(err));
+            setError(error);
+            setStatus("error");
+            onError?.(error);
+            return null;
+        }
+        finally {
+            isAuthenticatingRef.current = false;
+            if (abortControllerRef.current === abortController) {
+                abortControllerRef.current = null;
+            }
+        }
+    }, [session, config, onSuccess, onError]);
+    return {
+        authenticate,
+        status,
+        error,
+        result,
+        reset,
+        isAuthenticating: status === "signing" || status === "verifying",
+    };
+}

package/build/services/identity-proof/verify-identity-proof.d.ts

@@ -0,0 +1,25 @@
+import type { IdentityProof, IdentityProofConfig } from "./types";
+export type VerifyIdentityProofOptions = {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+};
+/**
+ * Verifies an identity proof by sending it to the authentication backend.
+ *
+ * This is a pure function that handles only the backend verification step.
+ * Use `createIdentityProof` first to generate the proof.
+ *
+ * @param proof - The identity proof from createIdentityProof
+ * @param config - Configuration with authentication URL
+ * @param options - Optional configuration (abort signal)
+ * @returns Promise resolving to the backend response
+ *
+ * @example
+ * ```typescript
+ * const proof = await createIdentityProof(session);
+ * const response = await verifyIdentityProof(proof, {
+ *   authenticationUrl: '/api/auth/verify'
+ * });
+ * ```
+ */
+export declare function verifyIdentityProof<T = any>(proof: IdentityProof, config: IdentityProofConfig, options?: VerifyIdentityProofOptions): Promise<T>;

package/build/services/identity-proof/verify-identity-proof.js

@@ -0,0 +1,59 @@
+/**
+ * Verifies an identity proof by sending it to the authentication backend.
+ *
+ * This is a pure function that handles only the backend verification step.
+ * Use `createIdentityProof` first to generate the proof.
+ *
+ * @param proof - The identity proof from createIdentityProof
+ * @param config - Configuration with authentication URL
+ * @param options - Optional configuration (abort signal)
+ * @returns Promise resolving to the backend response
+ *
+ * @example
+ * ```typescript
+ * const proof = await createIdentityProof(session);
+ * const response = await verifyIdentityProof(proof, {
+ *   authenticationUrl: '/api/auth/verify'
+ * });
+ * ```
+ */
+export async function verifyIdentityProof(proof, config, options) {
+    // Check for abort before starting
+    if (options?.signal?.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+    }
+    // Build request body
+    const requestBody = {
+        signer: {
+            actor: proof.signer.actor,
+            permission: proof.signer.permission,
+            public_key: proof.signer.publicKey,
+        },
+        transaction: proof.transaction,
+        signatures: proof.signatures,
+    };
+    // Build fetch options
+    const fetchOptions = {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...config.headers,
+        },
+        body: JSON.stringify(requestBody),
+        signal: options?.signal,
+    };
+    // Make the request
+    const response = await fetch(config.authenticationUrl, fetchOptions);
+    // Check for abort after fetch
+    if (options?.signal?.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+    }
+    // Handle non-OK responses
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "Unknown error");
+        throw new Error(`Authentication failed: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+    // Parse and return response
+    const result = await response.json();
+    return result;
+}

package/build/services/index.d.ts

@@ -0,0 +1 @@
+export * from "./identity-proof";

package/build/services/index.js

@@ -0,0 +1,2 @@
+// Identity Proof Service
+export * from "./identity-proof";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rockerone/xprnkit",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "source": "src/index.ts",
   "main": "build/index.js",
   "type": "module",