Собираем токен: три части, подпись, срок, подделка

В части IV личность приходила кукой, и кука несла только ключ: кто за ним стоит, сервер искал в своей таблице сессий (««Кто» приходит другим каналом»). У токена такой таблицы нет. Всё, что серверу нужно знать о человеке на каждом запросе, лежит в самой строке, а рядом — доказательство, что строку выдал этот сервер. Формат описан в RFC 7519 и называется JWT, JSON Web Token; его же выдаёт API автора учебника.

Слово «токен» в этой главе — не то же, что в главах 5–6: там токен — ключ, по которому объект просят у контейнера («Собираем контейнер: разрешение вглубь, один экземпляр, токены»: сервис знает только токен, а что под ним лежит, решает сборщик). Здесь токен — подписанная строка, которую клиент предъявляет через сеть. Эти два значения не связаны: ключ контейнера не подписан, а сетевой сертификат не используется для запроса зависимостей.

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

// такую строку API отдаёт в ответе на вход, а телефон хранит её и прикладывает к каждому запросу
const token =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3ZjNjMmE5ZS01YjFkLTRlOGYtYTZjMC0yZDliOGUxZjRhMzciLCJyb2xlIjoidXNlciIsImlhdCI6MTc4OTQ2MjgwMCwiZXhwIjoxNzkyMDU0ODAwfQ.e5fn1owiYza7Ui1RxZbQsvo_rMWGUhYG1aXVo9rJ3Yw";

function textFromBase64Url(part: string): string {
  // atob понимает только обычный base64, а в base64url вместо «+» и «/» стоят «-» и «_»
  const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
  const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

const parts = token.split(".");
console.log("частей:", parts.length);

const [header, payload, signature] = parts;
console.log("заголовок:", JSON.parse(textFromBase64Url(header)));
const claims = JSON.parse(textFromBase64Url(payload));
console.log("нагрузка:", claims);
console.log("выдан:", new Date(claims.iat * 1000).toISOString());
console.log("годен до:", new Date(claims.exp * 1000).toISOString());
console.log("подпись, символов:", signature.length);

Прочиталось всё, кроме подписи. Первая часть — заголовок: алгоритм подписи и тип токена. Вторая — нагрузка: sub — чей токен (у автора это users.id), role, iat — когда выдан и exp — до какого момента годен, оба в секундах с 1970 года. Третья — подпись: 32 байта, записанные 43 символами. Все три части закодированы base64url — это base64, в котором «+» и «/» заменены на «-» и «_», а «=» на конце выброшены, чтобы токен без экранирования ехал и в адресе, и в заголовке. Той же записью телефон сверял SHA-256 скачанного файла («hash: телефон не верит файлу на слово»).

Кодирование — не шифрование, это было сказано ещё про cookie («Пароли, токены и чужие скрипты»), и токен — тот же случай. Роль, идентификатор и срок видит каждый, через чьи руки токен прошёл: владелец телефона, прокси, записавший заголовки в журнал, скрипт на странице, сотрудник поддержки со скриншотом. Поэтому в нагрузку кладут только то, что не жалко показать: ни почты, ни телефона, ни внутренних пометок вроде «подозрительный».

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

Раз нагрузку может прочитать каждый, переписать её тоже может каждый: раскодировать, заменить "user" на "admin", закодировать обратно. Значит, третья часть должна зависеть от первых двух так, чтобы пересчитать её мог только сервер. Простой хеш не годится, и это уже встречалось в том же разделе про манифест: хеш спасает от битого файла, но не от чужого — кто подменил данные, пересчитает и хеш. Нужен хеш с секретом внутри. Это HMAC (RFC 2104): два прохода SHA-256, в каждый из которых подмешан ключ, — тот самый, что PBKDF2 из прошлой статьи повторял сотни тысяч раз. Подписываются байты заголовок.нагрузка — первые две части в base64url вместе с точкой, так велит RFC 7515.

Сервер в примере знает секрет и подписывает первые две части токена из прошлого раздела. Злоумышленник пишет себе роль admin и пробует три подписи: прежнюю, SHA-256 без ключа и HMAC секретом-заглушкой из .env.example. Прогноз: сколько байт даст HMAC, совпадёт ли он с третьей частью и какие из четырёх токенов сервер признает своими?

declare const token: string;
declare function textFromBase64Url(part: string): string;
declare function textToBase64Url(text: string): string;
declare function toBase64Url(bytes: Uint8Array): string;
declare function sameText(a: string, b: string): boolean;

// секрет знает только сервер, который выдаёт токены
const SECRET = "учебный-секрет-сервера-не-для-прода";

async function hmacSha256(secret: string, data: string): Promise<Uint8Array> {
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
  return new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(data)));
}

async function sha256(data: string): Promise<Uint8Array> {
  return new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(data)));
}

async function isGenuine(candidate: string): Promise<boolean> {
  const [header, payload, signature] = candidate.split(".");
  return sameText(toBase64Url(await hmacSha256(SECRET, `${header}.${payload}`)), signature);
}

async function main() {
  const [header, payload, signature] = token.split(".");
  const mac = await hmacSha256(SECRET, `${header}.${payload}`);
  console.log("HMAC-SHA256, байт:", mac.length);
  console.log("в base64url это третья часть токена:", toBase64Url(mac) === signature);

  // читать нагрузку злоумышленнику не мешает ничто, переписать — тоже
  const admin = textToBase64Url(JSON.stringify({ ...JSON.parse(textFromBase64Url(payload)), role: "admin" }));
  const forgeries: [string, string][] = [
    ["подпись прежняя", signature],
    ["подпись — SHA-256 без ключа", toBase64Url(await sha256(`${header}.${admin}`))],
    ["подпись секретом из .env.example", toBase64Url(await hmacSha256("dev-secret-change-me", `${header}.${admin}`))],
  ];

  console.log("токен сервера →", await isGenuine(token));
  for (const [how, forged] of forgeries) {
    console.log(`role: admin, ${how} →`, await isGenuine(`${header}.${admin}.${forged}`));
  }
}

main();

Что именно доказывает подпись, стоит сказать точно: от этого зависит всё остальное. Она доказывает, что заголовок и нагрузку составил тот, кто знает секрет, и с тех пор в них не поменялось ни байта. Она не доказывает, что токен предъявил его владелец. Токен и ездит в заголовке Authorization: Bearer, а bearer — это «предъявитель»: украденный токен у вора работает так же, как у хозяина. И она не доказывает, что написанное в нагрузке всё ещё правда: роль user была правдой в момент выдачи, а за месяц учётку могли удалить или роль понизить. Как сервер живёт с этим на каждом запросе — в статье «Проверка личности на каждом запросе».

Осталось сравнение. isGenuine сравнивает подписи через sameText, без выхода на первом расхождении. Для солёного хеша пароля это было страховкой: подобрать пароль под нужное начало хеша нельзя («Строка, которая помнит свою стоимость»). С подписью дело хуже. Нагрузку злоумышленник выбирает сам, а подпись к ней может подбирать по символу: сравнение с ранним выходом отвечает чуть дольше, когда начало совпало. По сети эта разница тонет в шуме, и вытаскивать её пришлось бы статистикой по множеству повторов, а защита стоит одной функции. В Node она называется timingSafeEqual, и у неё своя ловушка — её покажет прогон в конце статьи.

HMAC — не шифр и не «хеш посолиднее». Это хеш, который без секрета не посчитать, поэтому проверить такую подпись может только тот, кто умеет её поставить.

Выданных токенов сервер не хранит — в этом весь смысл. У этого есть обратная сторона: верная подпись верна всегда. HMAC от тех же байтов завтра, через месяц и через десять лет — те же 32 байта, а забыть токен сервер не может, потому что никогда его не помнил. Жизнь украденного токена ограничивает только поле exp в самой нагрузке — и то если проверка его читает.

Сравним две проверки: одна смотрит только на подпись, вторая ещё и на exp. Часы передаются параметром, и пример проверяет токен через час, через 31 день и через год после выдачи. В четвёртой строке другой токен: подписан тем же секретом, но без exp — такой выдаёт скрипт, написанный «на один раз», скажем, для соседнего сервиса. Прогноз для каждой строки: кто пустит, а кто откажет?

declare const token: string;
declare function textFromBase64Url(part: string): string;
declare function isGenuine(candidate: string): Promise<boolean>;
declare function issue(claims: object): Promise<string>;

interface Claims {
  sub: string;
  role: string;
  iat: number;
  exp?: number;
}

const DAY = 24 * 60 * 60;

async function signatureOnly(candidate: string): Promise<Claims | null> {
  if (!(await isGenuine(candidate))) return null;
  return JSON.parse(textFromBase64Url(candidate.split(".")[1]));
}

// часы приходят параметром, а не из Date.now(): так пример проживает год за одну строку
async function signatureAndExpiry(candidate: string, now: number): Promise<Claims | null> {
  const claims = await signatureOnly(candidate);
  if (claims === null || typeof claims.exp !== "number" || now >= claims.exp) return null;
  return claims;
}

async function main() {
  const { sub, role, iat }: Claims = JSON.parse(textFromBase64Url(token.split(".")[1]));
  // тем же секретом, но без exp: так выдаёт токен скрипт, написанный «на один раз»
  const forever = await issue({ sub, role, iat });

  const checks: [string, string, number][] = [
    ["через час", token, iat + 3600],
    ["через 31 день", token, iat + 31 * DAY],
    ["через год", token, iat + 365 * DAY],
    ["без exp, через год", forever, iat + 365 * DAY],
  ];
  for (const [when, candidate, now] of checks) {
    const loose = await signatureOnly(candidate);
    const strict = await signatureAndExpiry(candidate, now);
    console.log(when, "| только подпись:", loose ? "пустить" : "отказ", "| подпись и срок:", strict ? "пустить" : "отказ");
  }
}

main();

Проверка одной подписи пустила всех, включая токен годовой давности: возраста для неё не существует. Проверка со сроком отказала через 31 день, через год и токену без exp, хотя подпись у него настоящая. Последняя строка важнее, чем кажется. В RFC 7519 поле exp необязательное, и библиотеки проверяют его, только если оно есть: jsonwebtoken 9.0.3, на котором стоит API автора, пропускает подписанный токен без exp и через десять лет. Срок у токенов есть, пока его не забывает ставить никто из тех, кто знает секрет. Своя проверка может требовать exp всегда, как signatureAndExpiry.

Две мелочи, на которых ошибаются. exp — секунды, а не миллисекунды, как у Date.now(): jsonwebtoken сравнивает его с Math.floor(Date.now() / 1000). И токен перестаёт действовать в ту самую секунду, что записана в exp: по RFC 7519 — «в момент или после». Часы на разных серверах немного расходятся, поэтому RFC разрешает небольшой допуск, «обычно не больше нескольких минут»; у jsonwebtoken это опция clockTolerance в секундах.

Сколько жить токену — компромисс. У автора JWT_EXPIRY по умолчанию 30d, а отдельного refresh-токена нет: через месяц телефон получит 401 и попросит войти. Украденный токен все эти 30 дней работает. Отозвать его раньше можно, только вернув серверу память: короткий токен доступа в паре с долгим refresh-токеном, который лежит в таблице и удаляется при выходе, или список отозванных токенов, который хранят до их exp. Остаётся ещё смена секрета, но она выкидывает из системы сразу всех. Удалённую учётку и пониженную роль API автора ловит иначе: middleware процедур tRPC после подписи сверяет пользователя и роль с базой, — и это тема следующей статьи главы.

Подпись отвечает на вопрос «наш ли это токен», срок — на вопрос «не слишком ли он старый». Проверка, которая задаёт только первый, годами пускает по токену, однажды утёкшему.

Подделать токен можно, и не подбирая секрет, — достаточно убедить сервер, что подпись не нужна. Заголовок сообщает, каким алгоритмом токен подписан, и соблазн велик: прочитать alg и выбрать проверку по нему. Тогда проверка «поддерживает стандарт» и не меняется, когда появится второй алгоритм. А в стандарте, в RFC 7518, есть алгоритм none — токен без подписи. RFC 8725 оставляет его для случаев, когда целостность токена уже защищена чем-то другим.

Две проверки: одна выбирает алгоритм по заголовку, другая знает свой — HS256. Кандидатов три: настоящий токен, токен с ролью admin и пустой подписью и тот же токен с none в заголовке. Прогноз: что ответит каждая проверка каждому?

declare const token: string;
declare const SECRET: string;
declare function hmacSha256(secret: string, data: string): Promise<Uint8Array>;
declare function toBase64Url(bytes: Uint8Array): string;
declare function textToBase64Url(text: string): string;
declare function textFromBase64Url(part: string): string;
declare function sameText(a: string, b: string): boolean;

type Signer = (data: string) => Promise<string>;

// всё, что определяет RFC 7518, включая none: проверка «поддерживает стандарт»
const signers: Record<string, Signer> = {
  HS256: async (data) => toBase64Url(await hmacSha256(SECRET, data)),
  none: async () => "",
};

async function trustsHeader(candidate: string): Promise<boolean> {
  const [header, payload, signature] = candidate.split(".");
  const { alg } = JSON.parse(textFromBase64Url(header));
  const signer = signers[alg];
  return signer !== undefined && sameText(await signer(`${header}.${payload}`), signature);
}

async function pinsAlgorithm(candidate: string): Promise<boolean> {
  const [header, payload, signature] = candidate.split(".");
  const { alg } = JSON.parse(textFromBase64Url(header));
  return alg === "HS256" && sameText(await signers.HS256(`${header}.${payload}`), signature);
}

async function main() {
  const [header, payload] = token.split(".");
  const admin = textToBase64Url(JSON.stringify({ ...JSON.parse(textFromBase64Url(payload)), role: "admin" }));
  const none = textToBase64Url(JSON.stringify({ alg: "none", typ: "JWT" }));

  const candidates: [string, string][] = [
    ["токен сервера", token],
    ["role: admin, alg: HS256, подписи нет", `${header}.${admin}.`],
    ["role: admin, alg: none, подписи нет", `${none}.${admin}.`],
  ];
  for (const [name, candidate] of candidates) {
    console.log(name, "| алгоритм из заголовка:", await trustsHeader(candidate), "| алгоритм свой:", await pinsAlgorithm(candidate));
  }
}

main();

Проверка со своим алгоритмом отвергла обе подделки. Проверка по заголовку отвергла пустую подпись при HS256 — и пустила ту же пустую подпись, стоило написать в заголовке none. Злоумышленник ничего не подбирал: он дописал в токен, как его проверять, и проверка послушалась. Заголовок — такой же ввод злоумышленника, как нагрузка, только читается он раньше подписи, и верить ему нельзя точно так же. Эту атаку и соседнюю, из фолда ниже, разбирает RFC 8725 — «лучшие практики» JWT 2020 года. Правило оттуда короткое: какие алгоритмы допустимы, решает проверяющий, и каждый ключ служит ровно одному алгоритму.

Заголовок токена пишет тот, кто токен прислал. Всё, что там сказано об алгоритме, — просьба, а не инструкция.

Всё выше считал браузер. На сервере алгоритм тот же, меняется обёртка: вместо crypto.subtle — createHmac из node:crypto, вместо atob с заменами — Buffer с кодировкой base64url, вместо самодельного сравнения — timingSafeEqual. Прогон берёт токен, подписанный в песочнице, и проверяет его вместе с подделками из этой статьи; часы и здесь отсчитаны от iat, поэтому вывод не зависит от дня запуска. Последней строкой он зовёт timingSafeEqual на подписи и на той же подписи без последнего символа. Прогноз: что ответит verify на пять токенов и чем кончится последний вызов?

import { createHmac, timingSafeEqual } from 'node:crypto';

// секрет и токен — те же, что в песочнице статьи; в настоящем API секрет приходит из окружения
const SECRET = 'учебный-секрет-сервера-не-для-прода';
const token =
  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3ZjNjMmE5ZS01YjFkLTRlOGYtYTZjMC0yZDliOGUxZjRhMzciLCJyb2xlIjoidXNlciIsImlhdCI6MTc4OTQ2MjgwMCwiZXhwIjoxNzkyMDU0ODAwfQ.e5fn1owiYza7Ui1RxZbQsvo_rMWGUhYG1aXVo9rJ3Yw';

const DAY = 24 * 60 * 60;
const decode = (part) => JSON.parse(Buffer.from(part, 'base64url').toString());
const encode = (object) => Buffer.from(JSON.stringify(object)).toString('base64url');

function verify(candidate, now) {
  const [header, payload, signature = ''] = candidate.split('.');
  let alg;
  try {
    ({ alg } = decode(header));
  } catch {
    return 'отказ — не токен';
  }
  if (alg !== 'HS256') return `отказ — алгоритм ${alg}, а ждали HS256`;

  // сравниваются строки base64url, а не байты: Buffer.from(…, 'base64url') молча пропускает
  // посторонние символы, и у одной подписи появились бы разные записи
  const expected = Buffer.from(createHmac('sha256', SECRET).update(`${header}.${payload}`).digest('base64url'));
  const received = Buffer.from(signature);
  if (received.length !== expected.length || !timingSafeEqual(received, expected)) return 'отказ — подпись не сошлась';

  const claims = decode(payload);
  if (typeof claims.exp !== 'number' || now >= claims.exp) return 'отказ — срок истёк или его нет';
  return `пустить, роль ${claims.role}`;
}

const [header, payload, signature] = token.split('.');
const { iat } = decode(payload);
const admin = encode({ ...decode(payload), role: 'admin' });

const checks = [
  ['токен из песочницы через час', token, iat + 3600],
  ['он же через 31 день', token, iat + 31 * DAY],
  ['role: admin, подпись прежняя', `${header}.${admin}.${signature}`, iat + 3600],
  ['role: admin, alg: none', `${encode({ alg: 'none', typ: 'JWT' })}.${admin}.`, iat + 3600],
  ['подпись без последнего символа', token.slice(0, -1), iat + 3600],
];
for (const [name, candidate, now] of checks) console.log(`${name}: ${verify(candidate, now)}`);

try {
  timingSafeEqual(Buffer.from(signature), Buffer.from(signature.slice(0, -1)));
} catch (err) {
  console.log('timingSafeEqual на буферах разной длины:', err.code);
}

токен из песочницы через час: пустить, роль user
он же через 31 день: отказ — срок истёк или его нет
role: admin, подпись прежняя: отказ — подпись не сошлась
role: admin, alg: none: отказ — алгоритм none, а ждали HS256
подпись без последнего символа: отказ — подпись не сошлась
timingSafeEqual на буферах разной длины: ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH

Токен из браузера сошёлся в Node байт в байт: HMAC-SHA256 — стандарт, и неважно, кто его считает. Подделки отвергнуты тем же порядком проверок, что в песочнице: алгоритм, подпись, срок. Интереснее последняя строка. timingSafeEqual сравнивает только буферы одной длины, а на разных бросает исключение с кодом ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH. Без проверки длины перед ней обрезанная подпись получила бы не отказ, а исключение из стража — в Nest это ответ 500 и стек в журнале на каждый мусорный заголовок. Длина подписи не секрет, и сравнивать её заранее безопасно.

Комментарий в verify тоже не для порядка. Buffer.from(подпись, "base64url") молча пропускает посторонние символы: подпись с «!» или «=» на конце раскодируется в те же 32 байта. Проверка, которая сравнивает байты, признала бы все такие строки одним токеном, а список отозванных токенов, где лежат строки, пропустил бы любую из них.

В API автора подпись своими руками не считают: там jsonwebtoken 9, и подпись со сроком в verifyToken проверяет одна его строка.

// apps/api/src/common/jwt.ts, выдержка
/** Принимает и «голый» токен, и `Bearer <токен>`. Бросает при невалидном. */
export function verifyToken(config: ConfigService, raw: string): JwtPayload {
  const token = raw.startsWith('Bearer ') ? raw.slice(7) : raw;
  const payload = jwt.verify(token, jwtSecret(config));
  // подпись сошлась — но содержимое всё равно проверяем: токен мог быть выпущен
  // прошлой версией приложения с другим набором полей или ролей
  if (
    typeof payload !== 'object' ||
    typeof payload.sub !== 'string' ||
    !(USER_ROLES as readonly string[]).includes((payload as Record<string, unknown>).role as string)
  ) {
    throw new Error('Invalid token payload');
  }
  return payload as unknown as JwtPayload;
}

jwt.verify делает то же, что наш verify, кроме одного: exp он не требует, как было сказано в разделе о сроке. Алгоритмы он выводит из ключа: для строки-секрета разрешены только HS256, HS384 и HS512. Токен с none и пустой подписью отсекается ещё раньше, отказом «jwt signature is required»; подделанная нагрузка получает «invalid signature», истёкший срок — «jwt expired». Токен из этой статьи он выдал бы символ в символ: jwt.sign с тем же секретом, теми же sub и role, сроком 30d и часами, остановленными на iat, возвращает ту же строку. Всё это проверено на 9.0.3 из apps/api. Правило RFC 8725 здесь выполняет умолчание библиотеки; явная опция { algorithms: ["HS256"] } оставляет из трёх алгоритмов один и уже не зависит от того, что решат её следующие версии.

И обратите внимание на проверку после подписи. Подпись говорит «этот токен выдали мы», но не «его выдала нынешняя версия приложения»: токен, выпущенный месяц назад, может нести поля и роли, которых сейчас нет, поэтому форму нагрузки проверяют, как любой ввод. А существует ли ещё пользователь и та ли у него роль, решает уже база.