feat: link external wallet

[lwin-kyaw]

Jira Link

https://consensyssoftware.atlassian.net/browse/EMBED-85?atlOrigin=eyJpIjoiM2UxZDY3YTZlOGFkNGU2Nzg0YjFjYjliOTc5N2I1MjAiLCJwIjoiaiJ9

Description

This PR adds external wallet account linking to Web3Auth.

Users authenticated through the AUTH connector can now link and unlink external wallets, retrieve connected account metadata from user info, and access framework-level React/Vue helpers for the flow. The change also updates the demo apps to showcase the new linking UX.

What Changed

• Added linkAccount(params) and unlinkAccount(address) to Web3AuthNoModal.
• Introduced account-linking types and REST helpers for Citadel-backed /v1/link/wallet and /v1/unlink/wallet requests.
• Added dedicated AccountLinkingError error codes and analytics events for linking/unlinking start, success, and failure.
• Extended connector interfaces with generateChallengeAndSign() so external wallets can produce proof-of-ownership signatures for linking.
• Refactored EVM, Solana, and WalletConnect v2 connectors to support reusable challenge/sign flows.
• Implemented isolated connector creation during linking so external wallet proof generation does not mutate the main SDK session state.
• Updated AuthConnector.getUserInfo() to include connectedAccounts fetched from Citadel /v1/user.
• Added and exported useLinkAccount hooks/composables for:
  • @web3auth/modal/react
  • @web3auth/modal/vue
  • @web3auth/no-modal/react
  • @web3auth/no-modal/vue
• Updated the Vue and Wagmi React demo apps to:
  • display connected wallets from user info
  • link external wallets
  • unlink linked wallets
  • show success/error state for the flow

User-Facing Features

• Authenticated users can link an external wallet to their Web3Auth account.
• Linked wallets can be unlinked later by address.
• User info now includes connected account metadata, including primary account state and linked wallet details.
• React and Vue consumers get a simplified useLinkAccount API with loading, error, and linked account state.

Notes

• Account linking/unlinking is only supported when the active session is connected with the AUTH connector.
• Automatic wallet linking currently supports METAMASK and WALLET_CONNECT_V2.
• Linking uses signed wallet challenges and refreshed identity tokens returned from Citadel.

How has this been tested?

• Authenticate with the AUTH connector.
• Call getUserInfo() and verify connectedAccounts is returned.
• Link a MetaMask wallet and confirm the linked account appears in the response.
• Link a WalletConnect wallet and confirm the linked account appears in the response.
• Unlink a previously linked wallet and confirm it is removed from the returned linked accounts.
• Verify React/Vue demo flows show loading, success, and error states correctly.

Screenshots (if appropriate)

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• My code follows the code style of this project. (run lint)
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

---

Note

High Risk
Adds new Citadel-backed wallet linking/unlinking flows and active-account switching, touching auth token handling, connector interfaces, and connection state updates that can affect login/session behavior across EVM/Solana and Wagmi integrations.

Overview
Adds external wallet account linking to the SDK: Web3AuthNoModal.linkAccount() / unlinkAccount() call new Citadel endpoints and update stored tokens, with new account-linking types, error codes (AccountLinkingError), and analytics events for link/unlink/switch flows.

Introduces framework helpers (useLinkAccount, useSwitchAccount) for React/Vue and updates Wagmi providers to resync when connection changes (supporting account switching without relying on provider identity).

Updates demo apps to showcase linking UX: the Vue dashboard now displays userInfo.connectedAccounts, supports linking/unlinking wallets, and switching the active connected wallet; demo dependencies are bumped (notably @toruslabs/*-controllers, @metamask/smart-accounts-kit, Solana/viem/ox), and a root .npmrc pins the npm registry.

^{Reviewed by Cursor Bugbot for commit c067c42. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
web3auth-web	Ready	Preview, Comment	Apr 9, 2026 10:30am

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7506233. Configure here.}