Multi-Chain Authentication with SIWX (CAIP-122 Beyond EVM Silos)

┌────────────────────────────────────────────────────────┐
│               Divergent Auth Spaghetti                 │
├───────────────────────────┬────────────────────────────┤
│ EVM Stack                 │ Solana Stack               │
├───────────────────────────┼────────────────────────────┤
│ • EIP-4361 Message Format │ • Arbitrary raw text/JSON  │
│ • viem / ethers verify    │ • tweetnacl / ed25519 hook │
│ • Hex Address Encoding    │ • Base58 Address Encoding  │
│ • Custom Session Cookie A │ • Custom Session Cookie B  │
└───────────────────────────┴────────────────────────────┘

eip155:1:0x1234567890abcdef1234567890abcdef12345678     <-- Ethereum Mainnet (CAIP-10)
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:9WzDXwBbmkg...  <-- Solana Mainnet (CAIP-10)

┌────────────────────────────────────────────────────────────────────────┐
│                   TUWA SIWX Modular Architecture                       │
├────────────────────────────────────────────────────────────────────────┤
│ L1: Pure Core Engine                                                   │
│   • @tuwaio/siwx-core         CAIP-122 Builder & Parser (+orbit-core)  │
├────────────────────────────────────────────────────────────────────────┤
│ L2: Network Adapters (Multi-Chain Primitives)                          │
│   • @tuwaio/siwx-evm          EVM: EIP-191 / EIP-1271 / ERC-6492       │
│   • @tuwaio/siwx-solana       Solana: @solana/kit / SubtleCrypto       │
├────────────────────────────────────────────────────────────────────────┤
│ L2: Presentation & Bindings                                            │
│   • @tuwaio/siwx-react        React Hooks & Zustand Session Store      │
│   • @tuwaio/siwx-server       Verifier, Next.js Handlers, JWT + JWKS   │
└────────────────────────────────────────────────────────────────────────┘

// src/components/SignInButton.tsx
'use client';
 
import { createEvmSiwxSigner } from '@tuwaio/evm-sdk/siwx';
import { useSatelliteConnectStore } from '@tuwaio/sdk/satellite';
import {
  createSatelliteSiwxSigner,
  getSatelliteSiwxFields,
  isSessionMatchingConnection,
  useSiwx,
  useSiwxSession,
} from '@tuwaio/sdk/siwx';
import type { SolanaConnection } from '@tuwaio/solana-sdk/satellite';
 
import { wagmiConfig } from '@/configs/appConfig';
 
export function SignInButton() {
  const activeConnection = useSatelliteConnectStore((state) => state.activeConnection);
  const { signIn, signOut } = useSiwx();
  const { session, status } = useSiwxSession();
 
  if (!activeConnection?.isConnected) return null;
  // The SIWX helpers read the account and the chain of the connection
  const account = { address: activeConnection.address, chainId: activeConnection.chainId };
 
  // The session was issued for this account and chain: an account or network switch shows "Sign in" again
  if (isSessionMatchingConnection(session, account)) {
    return (
      <button
        onClick={async () => {
          await fetch('/api/siwx/logout', { method: 'POST' });
          signOut();
        }}
      >
        Sign out
      </button>
    );
  }
 
  const handleSignIn = async () =>
    signIn({
      // EVM wallets sign through wagmi; a Solana connection carries the signMessage of its Wallet Standard wallet
      signer: activeConnection.connectorType.startsWith('evm:')
        ? createEvmSiwxSigner(wagmiConfig)
        : await createSatelliteSiwxSigner(activeConnection as SolanaConnection),
      getNonce: async () => {
        const res = await fetch('/api/siwx/nonce');
        return ((await res.json()) as { nonce: string }).nonce;
      },
      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;
      },
      // eip155:11155111:0x… for an EVM wallet, solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1:… for a Solana devnet one
      fields: getSatelliteSiwxFields(account, { statement: 'Sign in to access TUWA sovereign services.' }),
      onSuccess: (session) => console.log('[SIWX] Signed in:', session.address),
    });
 
  return (
    <button onClick={handleSignIn} disabled={status !== 'idle' && status !== 'error'}>
      Sign in
    </button>
  );
}

// src/providers/SatelliteConnectProviders.tsx
'use client';
 
import { EVMConnectorsWatcher } from '@tuwaio/evm-sdk/nova-connect';
import { satelliteEVMAdapter } from '@tuwaio/evm-sdk/satellite';
import { NovaConnectProvider } from '@tuwaio/sdk/nova-connect';
import { SatelliteConnectProvider } from '@tuwaio/sdk/nova-connect/satellite';
import { SolanaConnectorsWatcher } from '@tuwaio/solana-sdk/nova-connect';
import { satelliteSolanaAdapter } from '@tuwaio/solana-sdk/satellite';
 
import { appEVMChains, solanaRPCUrls, wagmiConfig } from '@/configs/appConfig';
 
export function SatelliteConnectProviders({ children }: { children: React.ReactNode }) {
  return (
    <SatelliteConnectProvider
      adapter={[satelliteEVMAdapter(wagmiConfig, appEVMChains), satelliteSolanaAdapter({ rpcUrls: solanaRPCUrls })]}
      autoConnect={true}
    >
      {/* The watchers follow account and network changes made in the wallet */}
      <EVMConnectorsWatcher wagmiConfig={wagmiConfig} />
      <SolanaConnectorsWatcher />
 
      <NovaConnectProvider
        appChains={appEVMChains}
        solanaRPCUrls={solanaRPCUrls}
        siwx={{
          expirationSeconds: 1800,
          getNonce: async () => {
            const res = await fetch('/api/siwx/nonce');
            return ((await res.json()) as { nonce: string }).nonce;
          },
          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>
  );
}

// src/app/api/siwx/[...siwx]/route.ts
import type { SiwxNonceStore, SiwxSession, SiwxSessionRecord, SiwxSessionStore } from '@tuwaio/sdk/siwx/server';
import { createSiwxApiHandler } from '@tuwaio/sdk/siwx/server-next';
 
import { redisClient } from '@/lib/redis';
 
// Atomic Redis session store conforming to SiwxSessionStore
const sessionStore: SiwxSessionStore = {
  async get(id: string): Promise<SiwxSessionRecord | null> {
    const data = await redisClient.get(`siwx:sess:${id}`);
    return data ? (JSON.parse(data) as SiwxSessionRecord) : null;
  },
  async create({ session, ttlSeconds }: { session: SiwxSession; ttlSeconds: number }): Promise<SiwxSessionRecord> {
    const id = crypto.randomUUID();
    const createdAt = Date.now();
    const expiresAt = createdAt + ttlSeconds * 1000;
    const record: SiwxSessionRecord = { id, session, createdAt, expiresAt };
    await redisClient.set(`siwx:sess:${id}`, JSON.stringify(record), 'EX', ttlSeconds);
    return record;
  },
  // Links the wallet session to your own user record after sign-in; SIWX itself never calls it
  async bindSubject(id: string, subjectId: string): Promise<boolean> {
    const data = await redisClient.get(`siwx:sess:${id}`);
    if (!data) return false;
    const record = { ...(JSON.parse(data) as SiwxSessionRecord), subjectId };
    await redisClient.set(`siwx:sess:${id}`, JSON.stringify(record), 'KEEPTTL');
    return true;
  },
  async revoke(id: string): Promise<void> {
    await redisClient.del(`siwx:sess:${id}`);
  },
};
 
// Atomic Redis nonce store preventing replay attacks
const nonceStore: SiwxNonceStore = {
  async issue({ nonce, ttlSeconds }: { nonce: string; ttlSeconds: number }) {
    await redisClient.set(`siwx:nonce:${nonce}`, '1', 'EX', ttlSeconds);
  },
  async consume({ nonce }: { nonce: string }) {
    const result = await redisClient.del(`siwx:nonce:${nonce}`);
    return result === 1; // Atomic consumption prevents double-spend/replay
  },
};
 
const handler = createSiwxApiHandler({
  sessionStore,
  nonceStore,
  policy: {
    expectedDomain: process.env.NEXT_PUBLIC_APP_DOMAIN!,
    requireExpirationTime: true,
    maxIssuedAtAgeSeconds: 300, // 5 minutes
    maxSessionLifetimeSeconds: 60 * 60 * 24 * 7, // 7 days
    clockSkewSeconds: 60,
  },
  cookieOptions: {
    name: 'siwx-session',
    secure: process.env.NODE_ENV === 'production',
  },
});
 
export const { GET, POST, DELETE } = handler;

// src/app/api/siwx/[...siwx]/route.ts
import { createStatelessDemoSiwxHandler } from '@tuwaio/sdk/siwx/server-next';
 
const handler = createStatelessDemoSiwxHandler({
  signingSecret: process.env.SIWX_SIGNING_SECRET!, // Minimum 32 characters
  policy: {
    expectedDomain: ['localhost:3000', process.env.NEXT_PUBLIC_APP_DOMAIN!],
    requireExpirationTime: true,
    maxSessionLifetimeSeconds: 1800, // 30 minutes
  },
  cookieOptions: {
    name: 'siwx-demo-session',
    secure: process.env.NODE_ENV === 'production',
  },
});
 
export const { GET, POST, DELETE } = handler;

// src/app/actions/transaction.ts
'use server';
 
import { getSiwxServerSession, isSessionMatchingTarget } from '@tuwaio/sdk/siwx/server';
import { cookies } from 'next/headers';
 
import { sessionStore } from '@/lib/authStores';
 
export async function submitProtectedOperation({
  targetAddress,
  chainId,
  actionPayload,
}: {
  targetAddress: string;
  chainId: string;
  actionPayload: Record<string, unknown>;
}) {
  const cookieStore = await cookies();
 
  // 1. Resolve active session from durable store or signed cookie
  const session = await getSiwxServerSession({
    cookieSource: cookieStore,
    cookieName: 'siwx-session',
    sessionStore, // Or `signingSecret` when using stateless profile
    policy: {
      expectedDomain: process.env.NEXT_PUBLIC_APP_DOMAIN!,
    },
  });
 
  if (!session) {
    throw new Error('Unauthorized: No active or valid SIWX session found.');
  }
 
  // 2. Cryptographic claim verification: assert wallet ownership matches target
  const isMatch = isSessionMatchingTarget(session, targetAddress, chainId);
  if (!isMatch) {
    throw new Error(
      `Forbidden: Session wallet (${session.address}) does not match transaction sender (${targetAddress}).`,
    );
  }
 
  // 3. Proceed with authorized operation
  console.log(`[Authorized] Dispatched for ${session.address} on ${session.chainId}`);
  return { success: true, processedAt: new Date().toISOString() };
}