Метод unseal: параметры и возвращаемые значения

Операция восстановления данных из защищённой строки в библиотеке Iron используется для обратного преобразования результата seal. Метод unseal выполняет проверку целостности, аутентичности и срока действия зашифрованного контейнера, после чего возвращает исходный объект.

Ключевая особенность подхода Iron заключается в том, что данные не просто шифруются, а дополнительно защищаются механизмом MAC (message authentication code), что исключает возможность незаметной подмены содержимого.

Сигнатура метода unseal

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

await Iron.unseal(sealed, password, options)

Метод возвращает Promise, который резолвится в исходное значение, восстановленное из защищённого контейнера.

Параметры метода unseal

sealed

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

Формат строки строго определён библиотекой Iron и включает несколько частей:

  • зашифрованный payload
  • HMAC-подпись
  • метаданные (алгоритмы, параметры, временные метки)

Особенности:

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

password

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

Роль параметра:

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

Рекомендации по безопасности:

  • использовать длинные случайные строки
  • хранить вне кода (ENV, secret storage)
  • регулярно ротировать

options

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

Основные поля options

ttl

Время жизни токена в миллисекундах.

ttl: 24 * 60 * 60 * 1000

Если срок действия истёк, unseal выбросит ошибку, даже если подпись корректна.

timestampSkewSec

Допустимое отклонение времени между системами в секундах.

Используется для компенсации:

  • рассинхронизации серверных часов
  • сетевых задержек
timestampSkewSec: 60
localtime

Функция, возвращающая текущее время.

Позволяет переопределить источник времени (например, для тестов):

localtime: () => Date.now()
encryption

Алгоритм шифрования, применённый к данным.

Обычно задаётся автоматически, но может быть зафиксирован:

  • aes-256-cbc
  • aes-128-cbc
integrity

Алгоритм обеспечения целостности (MAC).

Например:

  • sha256
  • sha1 (устаревший, не рекомендуется)
password (в options)

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

Возвращаемое значение

Метод unseal возвращает Promise, который резолвится в исходный JavaScript-объект:

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

Тип возвращаемого значения

Любой сериализуемый объект:

  • object
  • string
  • number
  • boolean
  • null
  • массивы

Пример результата

Если исходные данные были:

{ userId: 42, role: "admin" }

После unseal возвращается:

{
  userId: 42,
  role: "admin"
}

Поведение при ошибках

Метод прерывает выполнение и выбрасывает исключение в следующих случаях:

1. Некорректная подпись (integrity check failed)

Возникает при:

  • изменении строки sealed
  • неверном password
  • повреждении данных

2. Истёкший срок действия

Если задан ttl и время жизни контейнера вышло:

  • данные считаются недействительными
  • выбрасывается ошибка истечения срока

3. Невалидный формат sealed

Если строка не соответствует формату Iron:

  • отсутствуют части контейнера
  • нарушена структура кодирования

4. Несовпадение алгоритмов

Если параметры encryption или integrity не совпадают с теми, что использовались при seal.

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

import Iron from '@hapi/iron'

const password = 'super-secure-password'

const sealed = await Iron.seal(
  { userId: 1, role: 'admin' },
  password,
  Iron.defaults
)

const unsealed = await Iron.unseal(
  sealed,
  password,
  {
    ttl: 1000 * 60 * 10,
    timestampSkewSec: 60
  }
)

console.log(unsealed)

Важные особенности работы метода

Проверка целостности выполняется первой

До расшифровки данных выполняется:

  • проверка MAC
  • сверка структуры
  • валидация алгоритмов

Если проверка не проходит, дешифрование не выполняется вообще.

Двухуровневая защита

Iron сочетает:

  • симметричное шифрование данных
  • криптографическую подпись

Это означает, что:

  • данные нельзя прочитать без ключа
  • данные нельзя незаметно изменить

Зависимость от времени

При использовании ttl важны:

  • синхронизация серверных часов
  • корректная настройка timestampSkewSec

Ошибка времени приводит к недействительности даже корректных данных.

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

Восстановление сессионных данных

const session = await Iron.unseal(cookie, password, options)

Декодирование токенов состояния

Используется для:

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

Валидация защищённых payload

try {
  const data = await Iron.unseal(token, password, options)
} catch (err) {
  // обработка недействительного токена
}

Взаимосвязь с методом seal

Метод unseal является строго обратной операцией к seal:

  • seal → преобразует объект в защищённую строку
  • unseal → восстанавливает исходный объект

Несовместимость параметров между ними приводит к невозможности восстановления данных.

Особенности работы с асинхронностью

Современная реализация основана на Promise:

  • поддерживается await
  • возможна цепочка .then()
  • блокирует поток только логически, не физически
Iron.unseal(sealed, password, options)
  .then(value => {
    console.log(value)
  })
  .catch(err => {
    console.error(err)
  })
Оглавление