Інтеграція WalletConnect для підключення криптогаманця до сайту

Інтеграція WalletConnect для підключення криптогаманця до сайту

Ви розробили dApp і зіткнулися з проблемою: користувачі не можуть залогінитися з мобільного гаманця. Браузерні розширення на кшталт MetaMask не працюють на телефонах, а вбудовувати кожен гаманець окремо — безкінечна головна біль. Ми вирішуємо це завдання через WalletConnect — відкритий протокол, який за пару днів дає підключення 400+ гаманців через QR-код або deep link. Нижче — як ми це робимо, з кодом і реальними конфігами. Якщо ви шукаєте готове рішення для Web3-аутентифікації — зв'яжіться з нами: ми реалізуємо інтеграцію з урахуванням ваших вимог.

Чому WalletConnect v2, а не v1?

WalletConnect v2 (через Reown AppKit) повністю замінив першу версію. Він швидший: встановлення з'єднання займає менше секунди проти кількох у v1. Підтримує мультичейн: можна підключитися одночасно до Ethereum, Polygon і Arbitrum (до 5 мереж). І головне — вбудована авторизація через підпис повідомлення (EIP-712). V1 більше не підтримується і не рекомендований для нових проєктів.

Як працює підключення гаманця?

Процес виглядає так:

1. Користувач натискає «Підключити гаманець».
2. Генерується сесія WalletConnect, відображається QR-код або deep link.
3. Гаманець користувача сканує QR, підписує запит на з'єднання.
4. dApp отримує адресу гаманця і може запитувати підписи транзакцій.

Для авторизації ми додатково запитуємо підпис повідомлення (Sign-in with Ethereum): користувач підписує nonce, сервер перевіряє підпис і видає JWT-токен. Жодних паролів.

Як забезпечується безпека авторизації?

WalletConnect Protocol використовує наскрізне шифрування і не зберігає приватні ключі на сервері.

Авторизація через підпис nonce захищає від повторних атак. Nonce генерується сервером, має короткий термін життя (зазвичай 5 хвилин) і анулюється після використання. Додатково можна налаштувати CORS-обмеження на стороні API.

Реалізація на React + Wagmi (AppKit)

Встановлюємо пакети:

npm install @reown/appkit @reown/appkit-adapter-wagmi wagmi [email protected] @tanstack/react-query

Реєструємо проєкт на Reown Cloud (безкоштовний план — до 50 000 активних користувачів на місяць). Отримуємо projectId.

Код підключення:

import { createAppKit } from '@reown/appkit/react';
import { WagmiProvider } from 'wagmi';
import { mainnet, polygon, arbitrum } from '@reown/appkit/networks';
import { WagmiAdapter } from '@reown/appkit-adapter-wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

const projectId = process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID;

const networks = [mainnet, polygon, arbitrum];
const wagmiAdapter = new WagmiAdapter({ networks, projectId });

createAppKit({
  adapters: [wagmiAdapter],
  networks,
  projectId,
  metadata: {
    name: 'My App',
    description: 'My Web3 Application',
    url: 'https://example.com',
    icons: ['https://example.com/icon.png']
  },
  features: {
    analytics: false,
    email: false,
    socials: false
  }
});

function App() {
  return (
    <WagmiProvider config={wagmiAdapter.wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <YourApp />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Кнопка підключення та авторизація

import { useAppKit, useAppKitAccount } from '@reown/appkit/react';
import { useSignMessage } from 'wagmi';

function ConnectButton() {
  const { open } = useAppKit();
  const { address, isConnected } = useAppKitAccount();
  const { signMessageAsync } = useSignMessage();

  const handleLogin = async () => {
    if (!isConnected) {
      await open();
      return;
    }

    // Авторизація через підпис
    const nonce = await fetch(`/api/auth/nonce?address=${address}`)
      .then(r => r.json()).then(d => d.nonce);

    const message = `Авторизація на example.com\nNonce: ${nonce}`;
    const signature = await signMessageAsync({ message });

    const { token } = await fetch('/api/auth/web3', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ address, signature, message })
    }).then(r => r.json());

    setAuthToken(token);
  };

  return (
    <button onClick={handleLogin}>
      {isConnected ? `Увійти як ${address?.slice(0, 6)}...` : 'Підключити гаманець'}
    </button>
  );
}

Налаштування deep link для мобільних гаманців

Deep link дозволяє відкривати гаманець безпосередньо з сайту на мобільному пристрої, минаючи QR-код. Налаштовуємо universal link для iOS та intent для Android. В Reown Cloud вмикаємо deep link у налаштуваннях проєкту та вказуємо підтримувані схеми (наприклад, wc:). Для коректної роботи на Android потрібна обробка intent через WalletConnectBridge.

Обробка помилок з'єднання

Важно обробляти помилки: відмова користувача, таймаут, непідтримувана мережа. Wagmi AppKit надає хуки useWalletInfo та useConnectionError. Ми додаємо fallback: якщо підключення не вдалося, пропонуємо вибір використати браузерне розширення. Також логуємо події для налагодження.

Project ID

WalletConnect v2 вимагає реєстрації проєкту на Reown Cloud для отримання projectId. Безкоштовний план: до 50 000 активних користувачів/місяць. Цього достатньо для більшості стартапів. Якщо потрібен великий обсяг, передбачені платні тарифи.

Підтримувані гаманці

WalletConnect працює з MetaMask Mobile, Trust Wallet, Rainbow, Coinbase Wallet, Ledger Live, Argent, Safe та сотнями інших. Для мобільних — QR-код або universal link.

Порівняння планів Reown Cloud

Що входить в роботу?

• Реєстрація проєкту та налаштування API-ключів.
• Розробка компонента підключення гаманця (кнопка, модалка, обробка станів).
• Реалізація авторизації через підпис повідомлення (Sign-in with Ethereum).
• Підтримка мультичейну (до 5 мереж).
• Документація з інтеграції та інструкція для користувача.
• Гарантія сумісності з основними гаманцями.

Строки

Базова інтеграція WalletConnect з авторизацією — 3–5 днів. Якщо потрібна кастомна модалка, підтримка deep link або реферальні посилання — до 2 тижнів. Оцінимо ваш проєкт безкоштовно — зв'яжіться, щоб обговорити деталі.

Отримайте консультацію з інтеграції WalletConnect — обговоримо ваш проєкт і запропонуємо оптимальний план. Замовте інтеграцію під ключ з гарантією сумісності: наші інженери з багаторічним досвідом у блокчейні реалізують все швидко та безпечно.

Аутентифікація та авторизація: OAuth, JWT, сесії, RBAC, 2FA

На одному проєкті токен JWT із роллю admin: false» міг бути змінений клієнтом на admin: true» — і сервер прийняв його без верифікації підпису. Ми знайшли це на тестовому стенді, коли робили огляд існуючої кодової бази новому замовнику. Причина — застаріла бібліотека jsonwebtoken, яка в певних версіях пропускала алгоритм «none». Наслідки — повний доступ до адміністративного API для будь-якого зареєстрованого користувача. Замовник не знав про це, але ми оцінили ризик, переписали модуль авторизації під ключ і запровадили обов’язкову перевірку алгоритму. Тепер подібних інцидентів немає. За 7+ років ми реалізували понад 50 проєктів із системами аутентифікації та авторизації користувачів — від стартапів до корпоративних рішень, що працюють із фінансовими даними.

Чому JWT не варто зберігати в localStorage?

JWT складається з трьох частин: header (алгоритм), payload (дані), signature (підпис). Підпис верифікує, що payload не змінено. Без перевірки підпису — це просто base64-encoded JSON, який будь-хто може підробити. Помилки, які бачимо в коді регулярно:

• Зберігання в localStorage. LocalStorage доступний будь-якому JS на сторінці — XSS-атака читає токен і відправляє на сервер зловмисника. Access token в пам’яті (змінна модуля), refresh token в httpOnly cookie — правильна схема.
• Довгоживучі access-токени. Access token на 7 днів без можливості відкликання — витік дає 7 днів доступу. Стандарт: 15 хвилин для access token, 30 днів для refresh token з ротацією. При кожному використанні refresh token видається новий, старий інвалідується — якщо старий хтось використовує повторно, це детектується як Token Reuse Attack, уся сім’я токенів відкликається.
• Зберігання секретних даних у payload. JWT payload не зашифровано, лише підписано — його видно в base64. Паролі, платіжні дані, особиста інформація — не в JWT. Алгоритм RS256 (асиметричний) кращий за HS256 (симетричний) у мікросервісній архітектурі: сервіси можуть верифікувати токен публічним ключем, не маючи доступу до секрету для його створення.

Як обрати між сесіями та токенами?

Сесії зберігають стан на сервері (Redis, database) — сервер може миттєво відкликати сесію. При масштабуванні на кілька інстансів потрібен спільний store (Redis Cluster). Cookie з session ID — httpOnly, Secure, SameSite=Strict.

Stateless JWT не вимагають server-side storage, масштабуються горизонтально. Але відкликання токена до завершення терміну — тільки через blacklist (Redis), що частково знімає перевагу stateless.

Для більшості веб-додатків сесії простіші та безпечніші. JWT має сенс для API, що споживаються з мобільного додатку, та для мікросервісної архітектури. Оцініть ваш сценарій — ми допоможемо обрати правильний підхід.

OAuth 2.0 та OpenID Connect

OAuth 2.0 — протокол делегованої авторизації, не аутентифікації. «Увійти через Google» — це OpenID Connect поверх OAuth 2.0, який додає id_token з даними користувача. Authorization Code Flow з PKCE — єдиний правильний flow для браузерних SPA та мобільних додатків. Implicit Flow застарів і небезпечний. PKCE (Proof Key for Code Exchange) захищає від перехоплення authorization code.

Реалізація OAuth сервера: не пишемо з нуля. Keycloak (open source, self-hosted), Auth0, Okta — готові рішення. Laravel Passport або Laravel Sanctum для серверних додатків. NextAuth.js для Next.js — підтримує 50+ провайдерів з коробки. Для B2B продуктів з корпоративними клієнтами — SAML 2.0 SSO. Корпоративні IT-відділи часто вимагають його замість OAuth. @boxyhq/saml-jackson — node.js бібліотека для SAML → OAuth2 адаптера.

RBAC, ABAC, ReBAC — що і коли застосовувати

Role-Based Access Control — у користувача є ролі, у ролей — права. Проста реалізація: user → roles → permissions. Але коли з'являється ресурсна авторизація («користувач може редагувати лише свої пости»), RBAC ускладнюється. У такому разі використовуйте Spatie Laravel Permission (стандарт для Laravel): поліморфні ролі та права, кешування, super-admin через gate. Інтеграція з Eloquent — $user->can('edit posts'), $user->hasRole('editor').

ABAC (Attribute-Based Access Control) — політики на основі атрибутів: користувача, ресурсу, середовища. Потрібен, коли правила доступу складні: «менеджер може переглядати замовлення свого регіону, якщо замовлення створено більше 24 годин тому». Casbin — популярна cross-language бібліотека для ABAC.

ReBAC (Relationship-Based Access Control) — Google Zanzibar model. Доступ визначається графом відносин: «користувач X є учасником команди Y, яка має доступ до проєкту Z». OpenFGA — open source реалізація від Okta.

Як ми це робимо: кейс із впровадження 2FA

Проєкт — платіжний шлюз для маркетплейсу. Потрібно було захистити доступ до операцій виводу коштів. Ми спроєктували систему:

• Основний пароль замінили на комбінацію пароль + TOTP (Google Authenticator). Використали otplib (Node.js) для генерації та верифікації кодів.
• Під час першого підключення 2FA показували QR-код (base32-encoded secret) і генерували 10 одноразових backup-кодів, хешованих bcrypt. Відображали коди лише один раз.
• Secret для TOTP зберігали у зашифрованому вигляді в базі даних (AES-256-GCM, ключ у AWS KMS).
• На стороні фронтенду інтегрували @simplewebauthn/browser для passkeys — біометрична аутентифікація як альтернатива паролю. Публічний ключ зберігали на сервері, private key на пристрої користувача.
• Результат: час на логін зріс на 5 секунд, але кількість зламаних акаунтів упала до нуля за пів року роботи. Гарантія безпеки — на рівні OWASP ASVS Level 2.

Також варто зазначити, що TOTP значно надійніше за SMS-верифікацію через SIM-swapping, тому для фінансових даних ми рекомендуємо TOTP або апаратні ключі.

Типові вразливості, які ми знаходимо

• Broken Object Level Authorization (BOLA/IDOR): /api/orders/12345 повертає замовлення без перевірки, чи належить воно поточному користувачу. Найпоширеніша вразливість API за OWASP. Кожен запит до ресурсу — перевірка через $user->can('view', $order).
• Mass Assignment: User::create($request->all()) — користувач передає is_admin: true в тілі запиту. Laravel вирішує через $fillable / $guarded, але часто забувають.
• Небезпечний CORS: Access-Control-Allow-Origin: * на API з авторизацією по cookie — credentials не передаються з wildcard origin, але якщо хтось зробив Allow-Credentials: true + Allow-Origin: * — це діра.

Penetration testing обов’язковий для продуктів з фінансовими даними або персональними даними користувачів. Ми проводимо аудит коду й інфраструктури на етапі приймання.

Що входить у роботу

Ми передаємо замовнику:

• Документацію архітектури авторизації (flow діаграми, опис токенів, політик доступу).
• Репозиторій із вихідним кодом, покритий unit- та integration-тестами.
• Конфігурацію для CI/CD (GitHub Actions/ GitLab CI) із перевірками безпеки.
• Доступи до середовищ (staging, production) із правами адміністратора.
• Інструкцію з експлуатації та супроводу.
• Підтримку після впровадження — 2 тижні безкоштовних консультацій.

Терміни та вартість

Базова аутентифікація (email/password + OAuth + JWT/сесії): 1–3 тижні. RBAC з детальними політиками доступу: 2–4 тижні. 2FA (TOTP + SMS): 1–2 тижні. WebAuthn/Passkeys: 2–3 тижні. Повна система аутентифікації для SaaS з multi-tenancy: 4–8 тижнів.

Вартість розраховується індивідуально залежно від обсягу та складності. Замовте консультацію — оцінимо ваш проєкт безкоштовно. Отримайте гарантію безпеки вашої авторизації користувачів.