Реалізація token-gated доступу: перевірка NFT та ERC-20 балансу

Уявіть: у вас сайт із преміум-аналітикою, відео-курсами або закритою спільнотою. Ви хочете надати доступ лише власникам вашої NFT-колекції або певної кількості токенів ERC-20. Але як зробити це надійно, без витоку даних і з мінімальними витратами на RPC? Ми реалізуємо серверну перевірку балансу з кешуванням та інвалідацією за блокчейн-подіями — готове рішення за 3–5 днів.

Чому серверна перевірка обов'язкова?

Token-gating — це не просто перевірка балансу на фронтенді. Клієнтська перевірка легко обходиться через DevTools. Потрібна серверна валідація, але кожен RPC-виклик платний (близько $0.0001–0.01 на Ethereum Mainnet). Без кешування при 1000 запитів на день ви витратите відчутну суму, а при пікових навантаженнях — сотні доларів. Крім того, баланс може змінитися (користувач продав NFT), тому кеш потрібно інвалідувати.

Інша проблема — підтримка різних стандартів і мереж. ERC-20 та ERC-721 вимагають різних ABI, а RPC-ендпоїнти для Polygon, Arbitrum та інших L2 мають різну вартість та затримки. Ми використовуємо бібліотеку viem — вона уніфікує виклики та підтримує десятки мереж.

Як працює перевірка токенів?

Після підключення гаманця (MetaMask, WalletConnect) сервер отримує адресу з JWT-токена. Middleware перевіряє кеш (Redis), якщо немає — робить RPC-виклик до контракту. Результат кешується на 5 хвилин, а паралельно підписується на Transfer-події для автоматичної інвалідації. Такий підхід забезпечує баланс між безпекою і вартістю.

Перевірка ERC-20 балансу

import { createPublicClient, http, parseAbi } from 'viem';
import { mainnet } from 'viem/chains';

const client = createPublicClient({
  chain: mainnet,
  transport: http(process.env.ETHEREUM_RPC_URL)
});

const ERC20_ABI = parseAbi([
  'function balanceOf(address owner) view returns (uint256)',
  'function decimals() view returns (uint8)'
]);

async function checkERC20Balance(
  walletAddress: string,
  tokenContractAddress: `0x${string}`,
  minBalance: bigint
): Promise<boolean> {
  const balance = await client.readContract({
    address: tokenContractAddress,
    abi: ERC20_ABI,
    functionName: 'balanceOf',
    args: [walletAddress as `0x${string}`]
  });

  return balance >= minBalance;
}

// Приклад: потрібно >= 100 токенів EXAMPLE
const hasAccess = await checkERC20Balance(
  userWalletAddress,
  '0xYourTokenContract',
  100n * 10n ** 18n  // 100 токенів з 18 decimals
);

Перевірка NFT (ERC-721)

const ERC721_ABI = parseAbi([
  'function balanceOf(address owner) view returns (uint256)',
  'function ownerOf(uint256 tokenId) view returns (address)'
]);

async function checkNFTOwnership(
  walletAddress: string,
  nftContract: `0x${string}`,
  specificTokenId?: bigint
): Promise<boolean> {
  if (specificTokenId !== undefined) {
    const owner = await client.readContract({
      address: nftContract,
      abi: ERC721_ABI,
      functionName: 'ownerOf',
      args: [specificTokenId]
    });
    return owner.toLowerCase() === walletAddress.toLowerCase();
  }

  const balance = await client.readContract({
    address: nftContract,
    abi: ERC721_ABI,
    functionName: 'balanceOf',
    args: [walletAddress as `0x${string}`]
  });
  return balance > 0n;
}

Middleware для захисту роутів

async function tokenGateMiddleware(req, res, next) {
  const user = req.user;

  if (!user?.walletAddress) {
    return res.status(401).json({ error: 'Wallet not connected' });
  }

  const cacheKey = `token_gate:${user.walletAddress}:${TOKEN_CONTRACT}`;
  const cached = await redis.get(cacheKey);

  if (cached !== null) {
    if (cached === '0') return res.status(403).json({ error: 'Token required' });
    return next();
  }

  const hasToken = await checkNFTOwnership(user.walletAddress, TOKEN_CONTRACT);
  await redis.setex(cacheKey, 300, hasToken ? '1' : '0');

  if (!hasToken) {
    return res.status(403).json({
      error: 'Access denied',
      requiredToken: TOKEN_CONTRACT,
      purchaseUrl: 'https://opensea.io/collection/your-nft'
    });
  }

  next();
}

app.get('/premium/content', authenticate, tokenGateMiddleware, getContent);
app.get('/members-only/*', authenticate, tokenGateMiddleware, handleMemberRoute);

Кейс із практики: прискорення в 24 рази

Для одного NFT-спільноти (10 000 holders) ми спочатку зробили прямі RPC-виклики при кожному запиті — LCP виріс до 4 секунд, TTFB — 1.2 с. Після впровадження Redis-кешу з TTL 5 хвилин TTFB впав до 50 мс для закешованих користувачів. Інвалідація за Transfer-подіями гарантує, що якщо власник продасть NFT, доступ закриється протягом 15 секунд. У підсумку вартість RPC знизилася в 10 разів (економія близько $500 на місяць), а користувачі перестали скаржитися на гальма.

Як кешування знижує витрати?

Без кешування кожен запит преміум-контенту викликав би RPC-виклик до блокчейну. Це не тільки дорого (близько $0.01 за виклик на Ethereum Mainnet), але й повільно: відповідь від Ethereum може приходити 2–5 секунд. Кеш на Redis з TTL 5 хвилин вирішує обидві проблеми. А інвалідація за Transfer-подіями гарантує, що доступ закривається миттєво після продажу токена.

Як реалізувати інвалідацію кешу?

const ERC721_TRANSFER_ABI = parseAbi([
  'event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)'
]);

client.watchContractEvent({
  address: TOKEN_CONTRACT,
  abi: ERC721_TRANSFER_ABI,
  eventName: 'Transfer',
  onLogs: async (logs) => {
    for (const log of logs) {
      await redis.del(`token_gate:${log.args.from}:${TOKEN_CONTRACT}`);
      await redis.del(`token_gate:${log.args.to}:${TOKEN_CONTRACT}`);
    }
  }
});

Порівняння типів токенів і кешування

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

• Архітектурна схема кешування та вибору мережі.
• Middleware для Express/NestJS з інтеграцією JWT і Redis.
• Підписка на Transfer-події з автоматичною інвалідацією.
• Фронтенд-компонент підключення гаманця (MetaMask, WalletConnect).
• Документація API та інструкція з деплою.
• Тестування під навантаженням і пост-релізний моніторинг (2 тижні).

Як налаштувати token-gating: покрокова інструкція

1. Підготувати RPC-ендпоінт і контракти токенів.
2. Встановити Redis і залежності (viem, ethers).
3. Реалізувати middleware згідно з прикладами вище.
4. Налаштувати веб-хуки або listen для Transfer-подій.
5. Протестувати сценарії: підключення, зміна власника, помилки RPC.
6. Розгорнути на сервері з моніторингом.

Типові помилки при реалізації

• Перевірка тільки на фронтенді — легко обходиться.
• Відсутність кешу — високі витрати на RPC і повільне завантаження.
• Ігнорування інвалідації — доступ залишається після продажу токена.
• Необроблені помилки RPC (rate limit, timeout) — користувач бачить «доступ заборонено» навіть при наявності токена.

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

Token Gating з ERC-20/ERC-721 перевіркою, кешуванням і middleware — 3–5 днів. Якщо потрібен власний контракт та інтеграція з декількома мережами — до 2 тижнів. Вартість розраховується індивідуально, наш досвід — 5+ років в Ethereum і Polygon, реалізовано 20+ gating-рішень. Отримайте консультацію щодо інтеграції token-gating у ваш проект.

Аутентифікація та авторизація: 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 тижнів.

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