基于 SIWX (CAIP-122) 的跨链统一身份认证

┌────────────────────────────────────────────────────────┐│               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.tsimport 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 SiwxSessionStoreconst 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 attacksconst 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.tsimport { 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() };}