Навигация

Аутентификация в API на Node.js

Почти каждый бэкенд рано или поздно упирается в два вопроса: как понять, кто прислал запрос, и как решить, что ему можно. На этом месте легко наделать дыр — от JWT с alg: none до чужого id в URL, который отдаёт данные другого пользователя. Разберём серверную часть: хранение паролей, сессии и токены, refresh-ротацию, CSRF, OAuth и проверку прав там, где она действительно работает.

Содержание

  1. Аутентификация и авторизация
  2. Пароли: хеш вместо шифрования
  3. Сессии на cookie
  4. JWT: что внутри и чего внутри нет
  5. Access и refresh токены
  6. Сессии или JWT
  7. CSRF и cookie-сессии
  8. OAuth 2.0 и OIDC на сервере
  9. Авторизация: RBAC и ABAC
  10. Практика: TaskFlow
  11. Частые ошибки
  12. Ключевые тезисы для интервью
  13. Заключение
  14. Полезные ссылки

Аутентификация и авторизация

Две задачи похожи только на слух. Аутентификация отвечает на вопрос «кто это», авторизация — «что ему разрешено». В HTTP-конвейере они идут строго по очереди:

запрос → authenticate → authorize → handler
           401              403

authenticate разбирает credential — cookie с идентификатором сессии, Authorization: Bearer <jwt> или API-ключ — и кладёт результат в req.user. Если credential отсутствует или невалиден, дальше идти некуда: 401 Unauthorized и заголовок WWW-Authenticate, описывающий способ входа. authorize уже смотрит на req.user и на конкретный ресурс: если субъект известен, но прав нет — 403 Forbidden.

Разница важна и для клиента. 401 означает «представься заново», 403 — «повторный вход не поможет». Если сервер отвечает 401 на нехватку прав, фронтенд уходит в цикл перелогина, который ничего не исправляет.

Второе правило: личность приходит только из проверенного credential. Не из тела запроса, не из x-user-id, не из query. Как только контроллер начинает брать ownerId из req.body, клиент назначает себя кем угодно — это та же проблема mass assignment, что разбиралась в статье «Конфигурация и валидация». Общая теория аутентификации, OAuth и хранения токенов на клиенте — в статье «Аутентификация и авторизация»; здесь — серверная реализация.


Пароли: хеш вместо шифрования

Пароль нельзя хранить ни в открытом виде, ни в шифре с ключом на сервере: в первом случае его читает любой, кто получил дамп, во втором — любой, кто получил дамп и ключ. Нужен необратимый хеш, по которому нельзя восстановить исходную строку.

Но обычный хеш не подходит. SHA-256 спроектирован быстрым: на видеокарте это миллиарды попыток в секунду, и дамп из миллиона паролей перебирается за часы. Поэтому берут адаптивные функции — argon2id или bcrypt. Они намеренно требуют память и процессорное время, а параметр стоимости (cost) задаёт, сколько именно. Стоимость подбирают так, чтобы один хеш считался примерно 100–250 мс на боевом железе, и повышают по мере роста производительности.

Соль — случайные байты, которые подмешиваются к паролю перед хешированием. Она хранится рядом с хешем и не секретна: её задача в том, чтобы одинаковые пароли давали разные хеши, а заранее посчитанные таблицы («радужные») становились бесполезны. Современные библиотеки генерируют соль сами и пакуют её в строку вместе с параметрами:

$argon2id$v=19$m=19456,t=2,p=1$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG

Из такой строки argon2.verify сам достанет соль и параметры, поэтому отдельного поля salt в схеме не нужно.

// src/auth/passwords.js
import argon2 from 'argon2';
import { randomBytes } from 'node:crypto';

export function hashPassword(password) {
  return argon2.hash(password, {
    type: argon2.argon2id,
    memoryCost: 19456, // 19 MiB
    timeCost: 2,
    parallelism: 1,
  });
}

export function verifyPassword(passwordHash, password) {
  return argon2.verify(passwordHash, password);
}

// Реальный хеш случайной строки: выравнивает время ответа при отсутствии пользователя
export const DUMMY_HASH = await hashPassword(randomBytes(32).toString('hex'));

Что важно в этом выборе:

  • argon2id — текущая рекомендация OWASP: устойчив и к GPU-перебору, и к атакам по побочным каналам. bcrypt всё ещё допустим, но у него есть ограничение: пароль обрезается до 72 байт. Если разрешены длинные пароли, их предварительно хешируют в SHA-256 и кодируют в base64, иначе два разных пароля с одинаковым началом станут неразличимы.
  • bcrypt с cost 12 — практичный выбор для новых проектов; cost 10 — нижняя допустимая граница. bcryptjs — чистая JS-реализация, она медленнее и блокирует event loop сильнее, чем нативная.
  • Сравнение делает библиотека, через timingSafeEqual внутри. Писать hash === stored руками нельзя: побайтовое сравнение строк завершается на первом несовпадении.
  • Пароль не логируется и не возвращается ни в ответе, ни в сообщении валидации. Схема из статьи про валидацию не должна печатать исходное значение поля.
  • Смена пароля инвалидирует сессии и refresh-токены: иначе украденная сессия переживёт смену пароля.

Отдельная утечка — перечисление пользователей. Если на несуществующий email сервер отвечает «пользователь не найден», а на существующий — «неверный пароль», то за несколько тысяч запросов собирается список зарегистрированных адресов. Правильно — одинаковый 401 в обоих случаях и одинаковая работа:

export async function login(email, password) {
  const user = await users.findByEmail(email);
  // DUMMY_HASH — реальный хеш случайной строки из модуля паролей
  const ok = await verifyPassword(user?.passwordHash ?? DUMMY_HASH, password);

  if (!user || !ok) throw new HttpError(401, 'invalid credentials');
  return user;
}

Проверка dummy-хеша выравнивает время ответа: без неё отсутствие пользователя отвечает заметно быстрее. Дополнительно на логин ставят rate limit по IP и по аккаунту — об этом в статье «Безопасность Node API».


Серверная сессия — самый прямолинейный механизм. После логина сервер создаёт запись в хранилище (Redis, реже таблица в базе) со случайным идентификатором и отдаёт клиенту только этот идентификатор в cookie. Все данные — userId, роли, время создания — лежат на сервере.

// src/app.js
import session from 'express-session';
import { RedisStore } from 'connect-redis';

app.use(session({
  name: 'sid',
  secret: config.SESSION_SECRET,        // ≥ 32 байт, из secret store
  store: new RedisStore({ client: redis }),
  resave: false,
  saveUninitialized: false,
  rolling: true,                        // продлевать при активности
  cookie: {
    httpOnly: true,
    secure: config.NODE_ENV === 'production',
    sameSite: 'lax',
    path: '/',
    maxAge: 1000 * 60 * 60 * 8,
  },
}));

Флаги cookie — не украшение, а граница безопасности:

ФлагЧто делаетЕсли не поставить
HttpOnlyзапрещает чтение из JSXSS сразу крадёт сессию
Securecookie только по HTTPSсессия уезжает в открытом виде
SameSite=Laxне шлёт cookie на cross-site POSTв старых браузерах cookie уходит всегда
Path=/ограничивает областьcookie не уйдёт на нужные пути
Max-Age/Expiresсрок жизни на клиентеcookie живёт до закрытия браузера

Префикс __Host- в имени cookie (__Host-sid) заставляет браузер требовать Secure, Path=/ и отсутствие Domain. Это защита от «cookie tossing»: поддомен не сможет подсунуть cookie с тем же именем.

Две обязательные операции:

  • Регенерация идентификатора при логине. Иначе возникает session fixation: атакующий заранее выдаёт жертве известный sid, жертва логинится, и сессия становится общей. req.session.regenerate() создаёт новую запись, а старая уничтожается.
  • Уничтожение записи при логауте. req.session.destroy() удаляет сессию на сервере, и старый sid сразу перестаёт работать — в отличие от JWT, который живёт до exp.

Хранилище должно быть общим для всех инстансов. С MemoryStore из express-session сессия живёт в памяти одного процесса: после рестарта все разлогинены, а за балансировщиком запрос на другой инстанс выглядит как «сессия пропала». Redis решает обе проблемы и заодно даёт список активных сессий пользователя, чтобы отзывать их по одной.


JWT: что внутри и чего внутри нет

JWT — это три сегмента, соединённые точками: header.payload.signature. Первые два — base64url-кодированный JSON, третий — подпись. Кодирование не является шифрованием: любой, у кого есть токен, прочитает payload без ключа. Подпись гарантирует только целостность — что токен не изменили и выдан он вашим ключом.

{
  "sub": "8f14e45f-ea6b-4c1b-9c3a-1f2d3c4b5a69",
  "role": "member",
  "iss": "taskflow",
  "aud": "taskflow-api",
  "iat": 1762339200,
  "exp": 1762340100
}

Поэтому в payload не кладут ни секретов, ни лишних персональных данных: токен видят клиент, прокси и логи. sub — идентификатор пользователя, role или scope — грубые права, jti — уникальный идентификатор токена (нужен для deny-list).

Проверка токена — это не только «подпись сошлась». Обязательный набор:

// src/auth/tokens.js
import { SignJWT, jwtVerify } from 'jose';
import { config } from '../config.js';

const key = new TextEncoder().encode(config.JWT_SECRET);
const ISSUER = 'taskflow';
const AUDIENCE = 'taskflow-api';

export function issueAccessToken(user) {
  return new SignJWT({ role: user.role })
    .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
    .setSubject(user.id)
    .setIssuer(ISSUER)
    .setAudience(AUDIENCE)
    .setIssuedAt()
    .setExpirationTime('15m')
    .sign(key);
}

export async function verifyAccessToken(token) {
  const { payload } = await jwtVerify(token, key, {
    algorithms: ['HS256'], // явный allowlist
    issuer: ISSUER,
    audience: AUDIENCE,
    clockTolerance: 5,
  });

  return { id: payload.sub, role: payload.role };
}

Четыре пункта, без которых проверка бесполезна:

  • algorithms задан явно. Классическая атака — подменить alg на none или заставить сервер проверить HMAC-токен публичным RSA-ключом. Библиотека не должна выбирать алгоритм по заголовку токена.
  • iss и aud проверяются. Иначе токен, выпущенный для другого сервиса тем же ключом, подойдёт и здесь.
  • exp проверяется библиотекой, но часы на инстансах должны быть синхронизированы; небольшой clockTolerance скрывает дрейф.
  • jti не обязателен, пока нет deny-list, но без него отзыв одного токена невозможен.

Главное свойство JWT — stateless: проверка не ходит в базу, поэтому любой инстанс валидирует токен одинаково и горизонтальное масштабирование не требует общего хранилища сессий. Обратная сторона — сервер не помнит, что токен выдал. Отзыв возможен только обходными путями:

  • короткий exp (5–15 минут) — основной механизм;
  • deny-list по jti в Redis на время жизни токена — точечный отзыв, но снова состояние;
  • tokenVersion в записи пользователя: при смене пароля или «выйти на всех устройствах» версия растёт, и все старые токены перестают проходить проверку;
  • refresh-токен, который хранится на сервере и отзывается мгновенно.

Отсюда правило: JWT подходит для короткоживущего access-токена, а не для долгой сессии. Долгая жизнь требует состояния — либо серверной сессии, либо refresh-записи.


Access и refresh токены

Пара токенов разделяет две разные задачи. Access-токен нужен на каждом запросе к API: он короткоживущий, поэтому его кража даёт атакующему считанные минуты. Refresh-токен нужен только для выпуска нового access: он долгоживущий, но принимается единственным эндпоинтом и хранится на сервере.

СвойствоAccessRefresh
Время жизни5–15 минут7–30 дней
Где используетсякаждый запрос к APIтолько /auth/refresh
Где хранится на серверенигде (JWT)хеш в базе или Redis
Проверкаподпись + claimsпоиск по хешу + срок
Отзывdeny-list или expмгновенный

Ротация делает refresh одноразовым. При каждом обмене старый токен помечается использованным, выдаётся новый, и оба привязаны к одной «семье» (familyId). Если старый токен предъявляют повторно — это почти наверняка кража: легитимный клиент уже получил замену. Тогда отзывается вся семья, и пользователь входит заново.

// POST /auth/refresh
const presented = req.validated.body.refreshToken;
const row = await refreshTokens.findByHash(sha256(presented));

if (!row) throw new HttpError(401, 'invalid refresh token');

if (row.usedAt || row.revokedAt) {
  await refreshTokens.revokeFamily(row.familyId); // признак компрометации
  throw new HttpError(401, 'refresh token reuse detected');
}

if (row.expiresAt <= new Date()) throw new HttpError(401, 'refresh token expired');

const nextToken = randomBytes(32).toString('base64url'); // непрозрачная случайная строка

await db.transaction(async (tx) => {
  await refreshTokens.markUsed(tx, row.id);
  await refreshTokens.insert(tx, {
    userId: row.userId,
    familyId: row.familyId,
    tokenHash: sha256(nextToken),
    expiresAt: new Date(Date.now() + REFRESH_TTL_MS),
  });
});

const user = await users.findById(row.userId);

res.json({
  accessToken: await issueAccessToken(user), // роль читается заново, не из старого токена
  refreshToken: nextToken,
});

Детали, которые легко упустить:

  • В базе лежит хеш, а не сам токен. Утечка таблицы не даёт готовых credential — так же, как утечка паролей не даёт паролей.
  • Обмен идёт в транзакции. Иначе два параллельных запроса с одним refresh оба увидят его неиспользованным и выпустят две цепочки. Практично — UPDATE ... WHERE used_at IS NULL RETURNING *: кто обновил, тот и выиграл.
  • markUsed не удаляет запись сразу. Она нужна, чтобы отличить «токен просрочен» от «токен уже использован»; чистить можно позже по expiresAt.
  • Refresh передаётся в HttpOnly cookie, а не в теле. Тогда JS его не прочитает, но появляется CSRF-поверхность — её закрывают тем же способом, что и cookie-сессии. В примере выше токен в теле только для наглядности.
  • Logout отзывает refresh и удаляет cookie. Access-токен доигрывает свои 15 минут; если это неприемлемо, добавляют deny-list по jti.

Refresh-токен не должен быть JWT «на всякий случай». Его задача — быть непрозрачной ссылкой на запись в базе; подпись ничего не добавляет, а размер и лишние claims только мешают.


Сессии или JWT

Спор «сессии против JWT» часто ведётся как выбор идеологии, хотя это выбор под задачу. Сравнение по делу:

КритерийСерверная сессияJWT access
СостояниеRedis или БДтолько подпись
Отзывмгновенныйдо истечения exp
Проверка на запрособращение к storeвычисление подписи
Масштабированиенужен общий storeлюбой инстанс
Размердесятки байт в cookieсотни байт в каждом запросе
CSRFнужна защитанет при Authorization, но токен доступен JS
Смена ролейприменяется сразупосле перевыпуска токена
Мобильные клиентыcookie менее удобнызаголовок естественен

Практические выводы:

  • Обычное веб-приложение с одним бэкендом — cookie-сессия. Мгновенный отзыв, никакой возни с refresh, меньше кода. Redis уже есть под кеш и очереди.
  • Несколько сервисов и resource servers — короткий JWT, чтобы каждый сервис проверял токен локально, не дергая auth-сервис на каждый запрос. Внутри периметра это заметно дешевле.
  • Мобильные приложения и сторонние клиенты — JWT в Authorization, потому что cookie там неудобны и плохо контролируются.
  • Гибрид — самый частый продовый вариант: браузер держит HttpOnly cookie с идентификатором сессии, а бэкенд для внутренних вызовов выпускает короткий JWT. Клиент не видит ни того, ни другого.

Что не работает: «мы поставим JWT, и stateless сам всё решит». Отзыв, роли и logout всё равно требуют состояния, просто оно переезжает в refresh-таблицу и deny-list. Если состояние нужно в любом случае, честная сессия проще.


CSRF эксплуатирует ambient credentials: браузер автоматически прикладывает cookie к запросу, даже если запрос инициирован со стороннего сайта. Атакующему не нужен доступ к токену — достаточно, чтобы жертва открыла страницу со скрытой формой POST /tasks/42/delete или картинкой на мутирующий GET.

SameSite — первый барьер. Lax (значение по умолчанию в современных браузерах) не отправляет cookie на cross-site POST, но отправляет на top-level GET-переход — переход по ссылке с чужого сайта. Отсюда правило: GET не меняет состояние. Никогда. Удаление через GET /tasks/42/delete обходится одной ссылкой в письме.

Что SameSite не закрывает:

  • Поддомены. SameSite сравнивает registrable domain, поэтому evil.example.com и app.example.com для браузера — один сайт. Если любой поддомен можно захватить или он отдаёт пользовательский контент, Lax не спасёт.
  • Старые клиенты и нестандартные браузеры, где атрибут игнорируется.
  • SameSite=None, который обязателен для кросс-доменных сценариев и требует Secure, — там защита целиком ложится на токен.

Поэтому защита строится слоями:

  1. Проверка Origin и Sec-Fetch-Site на всех небезопасных методах. Браузер подставляет их сам, и подделать их из JS нельзя.
  2. CSRF-токен — синхронизирующий (значение в сессии и в форме/заголовке) или double-submit (случайное значение в cookie и в заголовке). Токен привязан к сессии и проверяется на сервере.
  3. Отказ от мутирующих GET и от text/plain/form-urlencoded там, где API ждёт JSON: простые формы не проходят preflight, а application/json — проходит.
const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);

export function csrfGuard(req, res, next) {
  if (SAFE_METHODS.has(req.method)) return next();

  const origin = req.get('origin');
  if (!origin || !config.ALLOWED_ORIGINS.includes(origin)) {
    return next(new HttpError(403, 'origin not allowed'));
  }

  next();
}

Здесь отсутствие Origin на небезопасном методе считается подозрительным. Это верно для браузерного API: современные браузеры шлют Origin и на same-origin POST. Серверные и мобильные клиенты, которые его не шлют, должны ходить с Bearer-токеном, а не с cookie, — и тогда CSRF им не страшен, потому что ambient credentials нет.

Важно не путать: API с Authorization: Bearer не подвержен CSRF, потому что браузер не прикладывает заголовок автоматически. Зато он уязвим к XSS, который этот токен украдёт. Именно поэтому «перенести токен в localStorage» не является исправлением CSRF — это обмен одной проблемы на другую.


OAuth 2.0 и OIDC на сервере

OAuth 2.0 — про делегированный доступ: пользователь разрешает приложению действовать от своего имени у провайдера, не передавая пароль. OpenID Connect надстраивается сверху и добавляет аутентификацию: ID-токен говорит, кто пользователь.

Роли: resource owner (пользователь), client (ваш сервис), authorization server (Google, GitHub, Keycloak), resource server (API провайдера). Для бэкенда рабочий сценарий — authorization code flow с PKCE:

  1. Бэкенд генерирует state и code_verifier, сохраняет их в сессии и отправляет браузер на authorization endpoint с client_id, redirect_uri, scope и code_challenge.
  2. Провайдер возвращает пользователя на redirect_uri с code и тем же state. state сверяется с сохранённым — иначе можно принять чужой ответ на свой запрос.
  3. Бэкенд со своего сервера обменивает code на токены, предъявляя client_secret и code_verifier.
  4. Из ID-токена берутся sub, email, name; подпись проверяется по JWKS провайдера, а также iss, aud (ваш client_id), exp и nonce.
  5. Дальше бэкенд выдаёт свою сессию или свой JWT — клиент работает с вашим API, а не с токенами провайдера.

Почему именно так:

  • client_secret остаётся на сервере. SPA и мобильное приложение — публичные клиенты, они не могут хранить секрет: любой, кто открыл DevTools или распаковал APK, его увидит. Бэкенд — конфиденциальный клиент, у него есть защищённое хранилище.
  • redirect_uri сверяется точно. Иначе code уедет на чужой домен. Никаких wildcard и подстановок из query.
  • PKCE (code_challenge/code_verifier) защищает от перехвата code. Для публичных клиентов он обязателен, для конфиденциальных рекомендуется: код в URL может утечь через логи, историю и referer.
  • nonce защищает от повторного использования ID-токена, а state — от CSRF на самом flow.

Access-токен провайдера — не доказательство личности: он даёт доступ к API и может быть выдан не тому клиенту. Личность подтверждает ID-токен, проверенный по всем полям. Если нужен только вход, достаточно openid email profile и ID-токена; хранить токены провайдера «на будущее» не стоит.

Свой authorization server писать почти никогда не нужно: для «войти через Google» хватает библиотеки вроде openid-client или стратегии Passport. Самописная реализация обычно теряет именно те проверки, которые не видны в happy path.


Авторизация: RBAC и ABAC

Аутентификация заканчивается на req.user = { id, role }, и дальше начинается самое частое место ошибок. RBAC отвечает на вопрос «какая роль и какие права»: admin, member, viewer. ABAC смотрит на атрибуты: владелец ли это ресурса, тот же ли тенант, в каком состоянии объект.

Грубая проверка живёт на маршруте:

const ROLE_PERMISSIONS = {
  admin: ['task:read', 'task:write', 'task:delete', 'user:manage'],
  member: ['task:read', 'task:write'],
  viewer: ['task:read'],
};

export function requirePermission(permission) {
  return (req, res, next) => {
    const permissions = ROLE_PERMISSIONS[req.user.role] ?? [];
    if (!permissions.includes(permission)) {
      return next(new HttpError(403, 'forbidden'));
    }
    next();
  };
}

tasksRouter.delete('/:id',
  requirePermission('task:delete'),
  deleteTask,
);

Но роль не отвечает на вопрос «эта задача — его?». Если GET /tasks/:id делает findById(id) и отдаёт результат, то любой member читает чужие задачи, подставляя UUID. Это IDOR (insecure direct object reference) — в OWASP API Security Top 10 он идёт первым пунктом, как BOLA.

Проверка владения должна быть частью запроса к базе, а не фильтром после выборки:

// src/services/tasks.js
export async function getTask({ taskId, user }) {
  const task = await db.task.findFirst({
    where: { id: taskId, ownerId: user.id }, // ограничение в запросе
  });

  if (!task) throw new HttpError(404, 'task not found'); // не 403
  return task;
}

Три решения в этом коде:

  • ownerId в where, а не if (task.ownerId !== user.id). Иначе данные уже загружены, а забытая проверка отдаёт их наружу. С ограничением в запросе забыть невозможно.
  • 404, а не 403. 403 подтверждает существование чужого объекта; 404 не даёт перебирать идентификаторы.
  • Сервис, а не только роут. Проверка прав на маршруте не видит, к какому объекту идёт обращение; проверка в сервисе видит и объект, и пользователя.

Для мультитенантности (tenantId) правило то же: тенант берётся из проверенной сессии и добавляется в каждый запрос. Отдельный слой абстракции — policy-функции вида canEditTask(user, task), которые тестируются без HTTP и переиспользуются в разных эндпоинтах.

Ещё две ловушки:

  • Роль из JWT устаревает. Пока токен жив, понижение в правах не действует. Для критичных операций (деньги, удаление, админка) роль перечитывают из базы, а не берут из payload.
  • Права проверяются на сервере, а не в UI. Скрытая кнопка — это удобство, а не защита: запрос всё равно можно отправить руками.

Практика: TaskFlow

Соберём аутентификацию для API из статей «Express и middleware» и «Конфигурация и валидация». Пароли — argon2id, access — JWT на 15 минут, refresh — случайная строка с хешем в базе.

// src/auth/tokens.js
import { SignJWT, jwtVerify } from 'jose';
import { createHash, randomBytes } from 'node:crypto';
import { config } from '../config.js';

const key = new TextEncoder().encode(config.JWT_SECRET);

export const sha256 = (value) =>
  createHash('sha256').update(value).digest('hex');

export function issueAccessToken(user) {
  return new SignJWT({ role: user.role })
    .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
    .setSubject(user.id)
    .setIssuer('taskflow')
    .setAudience('taskflow-api')
    .setIssuedAt()
    .setExpirationTime('15m')
    .sign(key);
}

export async function verifyAccessToken(token) {
  const { payload } = await jwtVerify(token, key, {
    algorithms: ['HS256'],
    issuer: 'taskflow',
    audience: 'taskflow-api',
  });
  return { id: payload.sub, role: payload.role };
}

export const newRefreshToken = () => randomBytes(32).toString('base64url');
export const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 дней
// src/middleware/authenticate.js
import { HttpError } from '../errors.js';
import { verifyAccessToken } from '../auth/tokens.js';

export function authenticate(req, res, next) {
  const header = req.get('authorization') ?? '';
  const [scheme, token] = header.split(' ');

  if (scheme !== 'Bearer' || !token) {
    return next(new HttpError(401, 'missing bearer token'));
  }

  verifyAccessToken(token)
    .then((user) => {
      req.user = user;
      next();
    })
    .catch(() => next(new HttpError(401, 'invalid token')));
}
// src/routes/auth.js
import { Router } from 'express';
import { randomUUID } from 'node:crypto';
import { z } from 'zod';
import { validate } from '../middleware/validate.js';
import { hashPassword, verifyPassword, DUMMY_HASH } from '../auth/passwords.js';
import { issueAccessToken, newRefreshToken, sha256, REFRESH_TTL_MS } from '../auth/tokens.js';
import { HttpError } from '../errors.js';

export const authRouter = Router();

const CredentialsSchema = z.strictObject({
  email: z.email(),
  password: z.string().min(8).max(128),
});

authRouter.post('/register', validate({ body: CredentialsSchema }), async (req, res) => {
  const { email, password } = req.validated.body;

  if (await users.findByEmail(email)) {
    throw new HttpError(409, 'email already registered');
  }

  const user = await users.create({
    email,
    passwordHash: await hashPassword(password),
    role: 'member',
  });

  res.status(201).json({ id: user.id, email: user.email });
});

authRouter.post('/login', validate({ body: CredentialsSchema }), async (req, res) => {
  const { email, password } = req.validated.body;
  const user = await users.findByEmail(email);
  const ok = await verifyPassword(user?.passwordHash ?? DUMMY_HASH, password);

  if (!user || !ok) throw new HttpError(401, 'invalid credentials');

  const refreshToken = newRefreshToken();

  await refreshTokens.insert({
    userId: user.id,
    familyId: randomUUID(),
    tokenHash: sha256(refreshToken),
    expiresAt: new Date(Date.now() + REFRESH_TTL_MS),
  });

  res.json({
    accessToken: await issueAccessToken(user),
    refreshToken, // в проде — HttpOnly cookie, а не тело ответа
  });
});

Дальше маршруты задач закрываются двумя слоями: authenticate на всём роутере и requirePermission на конкретных операциях. Владение проверяется в сервисе, как в предыдущем разделе:

// до регистрации маршрутов
tasksRouter.use(authenticate);

tasksRouter.get('/:id', validate({ params: TaskIdParams }), async (req, res) => {
  const task = await getTask({
    taskId: req.validated.params.id,
    user: req.user, // из проверенного токена, не из body
  });
  res.json(toTaskResponse(task));
});

Что закрыто в этом наборе:

  • пароль не хранится в открытом виде, а логин не различает «нет пользователя» и «неверный пароль»;
  • access-токен проверяется с явным алгоритмом, iss, aud и exp;
  • refresh-токен хранится хешем и ротируется при каждом использовании;
  • ownerId берётся из req.user, а не из тела запроса;
  • права проверяются и на маршруте, и в сервисе по конкретному объекту.

Чего здесь ещё нет и что добавляют в проде: rate limit на /login и /register, отзыв refresh-токенов при смене пароля, CSRF-защита, если refresh переезжает в cookie, аудит-лог входов и метрики неуспешных попыток. Следующий шаг — статья «Логирование и наблюдаемость»: без request-id и структурных логов разбор инцидента с аутентификацией превращается в гадание.


Частые ошибки

  • JWT_SECRET короче 32 байт или лежит в коде. Подпись подбирается, а секрет утекает в git.
  • jwtVerify без algorithms. Токен с alg: none или подменой алгоритма проходит проверку.
  • Проверка только подписи. Без iss, aud и exp подойдёт токен от другого сервиса или просроченный.
  • Долгоживущий access-токен. Кража даёт доступ на недели, отозвать нельзя.
  • Refresh-токен в localStorage. XSS крадёт долгую сессию; refresh должен быть в HttpOnly cookie.
  • Refresh без ротации и без хранения на сервере. Токен нельзя отозвать, а кража остаётся незамеченной.
  • Пароли в SHA-256 или MD5. Перебираются на GPU; соль не спасает от слабого хеша.
  • bcrypt без учёта 72-байтного лимита. Длинные пароли с одинаковым началом неразличимы.
  • Разные ответы на «нет пользователя» и «неверный пароль». Перечисление аккаунтов и разное время ответа.
  • sameSite как единственная защита от CSRF. Мутирующий GET и поддомены остаются дырой.
  • cors({ origin: true, credentials: true }). Любой сайт ходит с cookie пользователя.
  • Роль из req.body. Клиент назначает себя админом.
  • findById(id) без ownerId в запросе. IDOR: чужие данные по подобранному UUID.

Ключевые тезисы для интервью

  • Аутентификация устанавливает субъекта и заканчивается на req.user, авторизация проверяет права на конкретный ресурс; 401 и 403 означают разные вещи и не взаимозаменяемы.
  • Серверная сессия — непрозрачный id в HttpOnly cookie плюс запись в Redis: отзывается мгновенно, но требует общего хранилища. JWT проверяется по подписи без состояния, зато не отзывается — поэтому access короткий, а refresh хранится на сервере.
  • Проверка JWT — это подпись с явным algorithms плюс iss, aud и exp; payload читается кем угодно, поэтому секретам и лишним персональным данным там не место.
  • Refresh-токен одноразовый: ротация и общая семья позволяют заметить повторное использование и отозвать всю цепочку; в базе лежит хеш, а не сам токен.
  • Cookie-сессии требуют CSRF-защиты: SameSite — базовый барьер, а не замена проверке Origin и CSRF-токену; мутирующих GET быть не должно.
  • Пароли хранят адаптивным хешем с солью (argon2id, bcrypt), cost подбирают под железо; логин не должен различать отсутствующего пользователя и неверный пароль.
  • Права проверяются на маршруте для грубого доступа и в сервисе для владения и тенанта; ownerId в where защищает от IDOR, а 404 не выдаёт существование чужого объекта.

Заключение

Аутентификация в API — это набор решений о доверии: что считать credential, где он хранится, сколько живёт и как отзывается. Сессия и JWT решают разные задачи, и выбор между ними определяется не модой, а тем, нужно ли мгновенное отзывание, сколько сервисов проверяют токен и какие клиенты с ним работают. Пароли, refresh-ротация, CSRF и проверка владения — не отдельные фичи, а части одной границы, каждая из которых закрывает свой класс атак. Дальше логично перейти к WebSocket и SSE: там та же проверка credential выполняется один раз при установке соединения, а дальше состояние живёт вне HTTP-запроса.

Полезные ссылки