iron.unseal

Метод iron.unseal используется для обратной операции по отношению к iron.seal и предназначен для восстановления исходного объекта из защищённой строки, созданной библиотекой @hapi/iron. Эта операция включает проверку целостности данных, аутентификацию через HMAC и расшифровку содержимого, если оно было зашифровано.

В актуальных версиях библиотеки функция может использоваться в асинхронном виде:

Iron.unseal(sealed, password, options)

или через callback-стиль:

Iron.unseal(sealed, password, options, (err, unsealed) => {})

Возвращаемое значение — объект, восстановленный из защищённого контейнера.

Назначение метода

iron.unseal решает сразу несколько задач:

  • проверка целостности данных (HMAC-валидация)
  • проверка корректности ключа
  • извлечение исходного объекта
  • расшифровка данных при использовании шифрования
  • защита от подмены и повреждения payload

Строка, передаваемая в метод, обычно была ранее создана через iron.seal, где объект сериализуется, подписывается и при необходимости шифруется.

Аргументы метода

sealed

Строка, содержащая защищённые данные.

Формат обычно включает несколько частей:

  • версия протокола
  • зашифрованный payload
  • IV (если используется шифрование)
  • HMAC подпись

Любое изменение строки приводит к ошибке проверки целостности.

password

Ключ или пароль, используемый для:

  • генерации HMAC
  • расшифровки данных (если включено шифрование)

Типичный параметр безопасности. От его качества напрямую зависит устойчивость всей схемы защиты.

options

Объект конфигурации, управляющий поведением алгоритма.

Основные параметры:

encryption

  • true — включает шифрование payload
  • false — используется только подпись без шифрования

ttlSec

  • время жизни токена в секундах
  • после истечения срока данные считаются недействительными

algorithm

  • алгоритм шифрования (например, aes-256-cbc)

password

  • альтернативный способ передачи ключа (в некоторых реализациях)

integrity

  • настройки HMAC-подписи

Поведение метода

При вызове iron.unseal происходит последовательный процесс:

  1. Разбор входной строки
  2. Проверка структуры токена
  3. Проверка HMAC-подписи
  4. Проверка срока действия (TTL)
  5. Расшифровка payload (если включено шифрование)
  6. Десериализация JSON-объекта
  7. Возврат исходной структуры

Если любой этап не проходит проверку, операция завершается ошибкой.

Ошибки и исключения

Метод может выбрасывать или возвращать следующие типы ошибок:

Bad HMAC

  • подпись не совпадает
  • данные были изменены

Bad Encryption

  • неправильный ключ
  • невозможность расшифровки

Expired

  • превышен TTL

Bad Format

  • строка не соответствует формату Iron

Decryption Failure

  • повреждённые или неполные данные

Пример использования

import Iron from '@hapi/iron';

const sealed = 'Fe26.2**...';

const password = 'super-secure-password';

const options = {
  encryption: true,
  ttlSec: 3600
};

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

console.log(unsealed);

Результатом будет исходный объект, например:

{
  userId: 42,
  role: 'admin',
  session: {
    valid: true
  }
}

Асинхронная модель выполнения

Хотя операция кажется синхронной по логике, современные версии библиотеки поддерживают Promise-обёртку. Это важно, поскольку внутри может использоваться криптографический API Node.js, который оптимизирован под асинхронное выполнение.

Iron.unseal(sealed, password, options)
  .then(data => {
    console.log(data);
  })
  .catch(err => {
    console.error(err);
  });

Безопасность и криптографическая модель

Механизм unseal опирается на комбинацию двух принципов:

  1. Конфиденциальность (encryption)
  2. Целостность (HMAC)

Если включено только подписание без шифрования, данные остаются читаемыми, но защищены от подмены.

Если включено шифрование:

  • payload становится недоступным без ключа
  • любые изменения ломают расшифровку

Ключевой момент: даже незначительное изменение одного байта делает строку недействительной.

Работа с TTL

Параметр ttlSec добавляет временную ограниченность данным.

При проверке выполняется:

  • сравнение текущего времени
  • анализ временной метки внутри sealed-строки

Если срок истёк, метод прекращает выполнение и возвращает ошибку Expired.

Типичные сценарии использования

Сессии пользователя

{
  userId: 10,
  sessionId: 'abc123'
}

JWT-подобные токены без JWT

{
  scope: ['read', 'write'],
  expires: 1710000000
}

Защищённые cookies

  • хранение состояния пользователя
  • предотвращение подмены клиентом

Отличие от iron.seal

seal создаёт защищённую строку из объекта.

unseal выполняет обратное преобразование.

Ключевое различие:

  • seal → сериализация + защита
  • unseal → проверка + восстановление

Особенности реализации

  • используется строгая структура формата
  • криптографические операции завязаны на Node.js crypto API
  • поддерживается версия протокола Iron
  • совместимость зависит от версии библиотеки

Любое несоответствие версии может привести к невозможности расшифровки даже при правильном ключе.

Обработка результата

После успешного вызова возвращается JavaScript-объект без дополнительной обёртки. Он уже десериализован, и дальнейшая работа с ним не требует дополнительных преобразований.

const data = await Iron.unseal(...);

if (data.role === 'admin') {
  // доступ разрешён
}

Частые причины ошибок при использовании

  • изменение sealed-строки (даже пробел)
  • неверный пароль
  • несоответствие алгоритма шифрования
  • истечение TTL
  • попытка расшифровать данные другой версией Iron

Поведение при некорректных данных

Метод не пытается “исправить” повреждённые данные. Любое отклонение от ожидаемого формата приводит к отказу выполнения операции, что является частью модели безопасности: предпочтение отдается отказу, а не восстановлению с возможной компрометацией данных.

Оглавление