Аутентификация в API на Node.js
Почти каждый бэкенд рано или поздно упирается в два вопроса: как понять, кто прислал запрос, и как решить, что ему можно. На этом месте легко наделать дыр — от JWT с alg: none до чужого id в URL, который отдаёт данные другого пользователя. Разберём серверную часть: хранение паролей, сессии и токены, refresh-ротацию, CSRF, OAuth и проверку прав там, где она действительно работает.
Содержание
- Аутентификация и авторизация
- Пароли: хеш вместо шифрования
- Сессии на cookie
- JWT: что внутри и чего внутри нет
- Access и refresh токены
- Сессии или JWT
- CSRF и cookie-сессии
- OAuth 2.0 и OIDC на сервере
- Авторизация: RBAC и ABAC
- Практика: TaskFlow
- Частые ошибки
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Аутентификация и авторизация
Две задачи похожи только на слух. Аутентификация отвечает на вопрос «кто это», авторизация — «что ему разрешено». В 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».
Сессии на cookie
Серверная сессия — самый прямолинейный механизм. После логина сервер создаёт запись в хранилище (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 | запрещает чтение из JS | XSS сразу крадёт сессию |
Secure | cookie только по 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: он долгоживущий, но принимается единственным эндпоинтом и хранится на сервере.
| Свойство | Access | Refresh |
|---|---|---|
| Время жизни | 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 передаётся в
HttpOnlycookie, а не в теле. Тогда 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 там неудобны и плохо контролируются. - Гибрид — самый частый продовый вариант: браузер держит
HttpOnlycookie с идентификатором сессии, а бэкенд для внутренних вызовов выпускает короткий JWT. Клиент не видит ни того, ни другого.
Что не работает: «мы поставим JWT, и stateless сам всё решит». Отзыв, роли и logout всё равно требуют состояния, просто оно переезжает в refresh-таблицу и deny-list. Если состояние нужно в любом случае, честная сессия проще.
CSRF и cookie-сессии
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, — там защита целиком ложится на токен.
Поэтому защита строится слоями:
- Проверка
OriginиSec-Fetch-Siteна всех небезопасных методах. Браузер подставляет их сам, и подделать их из JS нельзя. - CSRF-токен — синхронизирующий (значение в сессии и в форме/заголовке) или double-submit (случайное значение в cookie и в заголовке). Токен привязан к сессии и проверяется на сервере.
- Отказ от мутирующих 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:
- Бэкенд генерирует
stateиcode_verifier, сохраняет их в сессии и отправляет браузер на authorization endpoint сclient_id,redirect_uri,scopeиcode_challenge. - Провайдер возвращает пользователя на
redirect_uriсcodeи тем жеstate.stateсверяется с сохранённым — иначе можно принять чужой ответ на свой запрос. - Бэкенд со своего сервера обменивает
codeна токены, предъявляяclient_secretиcode_verifier. - Из ID-токена берутся
sub,email,name; подпись проверяется по JWKS провайдера, а такжеiss,aud(вашclient_id),expиnonce. - Дальше бэкенд выдаёт свою сессию или свой 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 должен быть вHttpOnlycookie. - 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 в
HttpOnlycookie плюс запись в 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-запроса.
Полезные ссылки
- OWASP: Password Storage Cheat Sheet — argon2id, bcrypt и параметры стоимости
- OWASP: CSRF Prevention Cheat Sheet — синхронизирующий токен, double-submit,
SameSite - RFC 7519: JSON Web Token — структура и claims
- RFC 9700: OAuth 2.0 Security Best Current Practice — PKCE, ротация refresh, запрет implicit flow
- jose — JWT и JWKS для Node без нативных зависимостей
- node-argon2 — argon2id в Node
- Аутентификация и авторизация — общая теория и клиентская часть
- CSRF: анатомия атаки — как устроена атака и чем её закрывают