SIWX Authentication (Headless)

The @tuwaio/sdk/siwx module provides a headless, CAIP-122 compliant React hook useSiwx to handle multi-chain session authentication automatically on the frontend.

The Headless Approach

The modern TUWA stack separates the visual connection button (Nova UI) from the background authentication logic (SIWX). There are no “Bridge” UI components to render; you simply trigger sign-in flows after a wallet connects.

When a user connects their wallet (EVM or Solana), you can automatically prompt them to sign a CAIP-122 standard authentication message. Upon successful signature, a secure HTTP-Only cookie session is established with the backend API.

Implementation

For a React application, NovaConnectProvider handles auto-authentication natively via NovaSiwxWatcher. Simply provide your verifier function in the siwx prop of NovaConnectProvider.

// src/components/Providers.tsx
'use client';
 
import { ReactNode } from 'react';
import { SatelliteConnectProvider } from '@tuwaio/sdk/satellite';
import { NovaConnectProvider } from '@tuwaio/sdk/nova-connect';
import { satelliteEVMAdapter } from '@tuwaio/evm-sdk/satellite';
import { satelliteSolanaAdapter } from '@tuwaio/solana-sdk/satellite';
import { wagmiConfig, appEVMChains, solanaRPCUrls } from '@/configs/appConfig';
 
export function Providers({ children }: { children: ReactNode }) {
  return (
    <SatelliteConnectProvider
      adapter={[satelliteEVMAdapter(wagmiConfig, appEVMChains), satelliteSolanaAdapter({ rpcUrls: solanaRPCUrls })]}
      autoConnect={true}
    >
      <NovaConnectProvider
        appChains={appEVMChains}
        solanaRPCUrls={solanaRPCUrls}
        siwx={{
          verifier: async (payload) => {
            const res = await fetch('/api/siwx/verify', {
              method: 'POST',
              headers: { 'Content-Type': 'application/json' },
              body: JSON.stringify(payload),
            });
            return res.ok ? res.json() : null;
          },
          destroyer: async () => {
            await fetch('/api/siwx/logout', { method: 'POST' });
          },
        }}
      >
        {children}
      </NovaConnectProvider>
    </SatelliteConnectProvider>
  );
}

Behavior

1. Connection: The Satellite state machine establishes a new active wallet connection.
2. Auto-Auth Trigger: NovaSiwxWatcher inside NovaConnectProvider detects the active connection and automatically presents the user with a CAIP-122 signature request.
3. Verification: The signature is submitted to your verifier endpoint /api/siwx/verify, validating the signature and issuing an encrypted session cookie.
4. Session Active: The session state is updated globally across useSiwxSessionStore.

If the user disconnects their wallet or switches accounts, SIWX session state updates accordingly.