Установка ttl

TTL (time-to-live) в контексте библиотеки @hapi/iron определяет время жизни «запечатанных» (sealed) данных. После истечения заданного интервала такие данные становятся недействительными и не могут быть успешно расшифрованы через unseal. Это ключевой механизм контроля актуальности токенов, сессий и временных объектов.

В Iron TTL задаётся через опции при вызове Iron.seal. Значение указывается в миллисекундах и определяет максимальное время, в течение которого зашифрованные данные считаются валидными.

Основная форма использования:

import Iron from '@hapi/iron';

const password = 'very-secure-password';

const sealed = await Iron.seal(
  { userId: 42 },
  password,
  {
    ttl: 60 * 1000 // 1 минута
  }
);

После истечения 60 секунд попытка расшифровать строку приведёт к ошибке истечения срока действия.

Поведение ttl при unseal

При вызове Iron.unseal библиотека проверяет временные ограничения, заложенные в sealed-структуру. Если TTL истёк, операция завершится исключением.

const unsealed = await Iron.unseal(
  sealed,
  password,
  Iron.defaults
);

Если время жизни истекло, будет выброшена ошибка вида Expired seal.

Разница между ttl и maxAge

В Iron используются два близких по смыслу параметра:

ttl — абсолютное время жизни объекта с момента создания
maxAge — максимальный возраст данных относительно момента проверки

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

Пример комбинированной конфигурации:

{
  ttl: 5 * 60 * 1000,     // 5 минут общего срока жизни
  maxAge: 2 * 60 * 1000   // не старше 2 минут при проверке
}

В такой конфигурации данные могут быть отклонены даже до истечения ttl, если превышен maxAge.

Влияние TTL на структуру sealed-данных

При вызове seal библиотека добавляет служебные метаданные:

временную метку создания
параметры алгоритма
контрольные значения целостности

TTL не хранится как фиксированное поле, а вычисляется на основе времени создания и переданных опций. Это важно для понимания того, что изменение системного времени может повлиять на проверку.

Пример типичного сценария использования TTL

Чаще всего TTL применяется для:

временных токенов авторизации
одноразовых ссылок подтверждения
защищённых cookie с ограниченным сроком жизни
краткоживущих API-ключей

Пример:

const sessionToken = await Iron.seal(
  { sessionId: 'abc123' },
  password,
  {
    ttl: 15 * 60 * 1000 // 15 минут
  }
);

Особенности работы при истечении TTL

После истечения времени:

данные считаются недействительными
расшифровка невозможна даже при правильном ключе
ошибка возникает до возврата полезной нагрузки

Это обеспечивает криптографическую защиту от повторного использования устаревших данных.

Типичные ошибки при настройке TTL

Слишком большой TTL

Долгоживущие sealed-объекты увеличивают риск использования устаревших данных, особенно в системах с авторизацией.

Слишком маленький TTL

Короткое время жизни может приводить к:

частым ошибкам истечения срока
необходимости постоянного перевыпуска токенов
повышенной нагрузке на сервер

Игнорирование разницы между TTL и maxAge

Использование только одного параметра без понимания их взаимодействия может приводить к неожиданному поведению при валидации.