Установка и настройка окружения

Библиотека jose реализует современные стандарты работы с JSON Web Token (JWT), JSON Web Signature (JWS) и JSON Web Encryption (JWE). Она ориентирована на строгую поддержку спецификаций JOSE и активно используется в серверных и клиентских JavaScript-приложениях, где требуется криптографическая подпись, верификация и шифрование данных.

Требования к окружению

Перед установкой необходимо учитывать базовые требования к среде выполнения:

  • Node.js версии 16 и выше (рекомендуется 18+ или 20+)
  • Поддержка ES Modules (ESM)
  • Современный runtime с реализацией Web Crypto API (в Node.js он встроен, но в некоторых окружениях может требовать полифиллы)
  • Понимание работы асинхронных функций (async/await)

Библиотека не поддерживает устаревшие версии Node.js без ESM и современных криптографических API.

Установка библиотеки

Установка через npm

npm install jose

Установка через yarn

yarn add jose

Установка через pnpm

pnpm add jose

После установки пакет становится доступен как модуль ES:

import { jwtVerify, SignJWT } from 'jose'

Особенности модульной системы

Библиотека jose распространяется исключительно как ESM-модуль. Это означает:

  • Использование import вместо require
  • Невозможность прямого подключения через CommonJS без дополнительных настроек
  • Требование к корректной конфигурации package.json

Пример минимальной конфигурации:

{
  "type": "module"
}

Без этого параметра Node.js может не распознать ESM-синтаксис.

Настройка проекта Node.js

Инициализация проекта

npm init -y

Установка jose

npm install jose

Включение ESM

В package.json необходимо указать:

{
  "type": "module"
}

После этого можно использовать import в любом .js файле.

Проверка корректной установки

Создаётся файл index.js:

import { generateSecret } from 'jose'

console.log('jose установлен корректно')

Запуск:

node index.js

Если ошибок нет — окружение настроено правильно.

Работа в TypeScript-проекте

Библиотека полностью поддерживает TypeScript без необходимости дополнительных типов.

Установка TypeScript

npm install typescript --save-dev

Инициализация конфигурации:

npx tsc --init

Рекомендуемые настройки tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

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

import { SignJWT } from 'jose'

const secret = new TextEncoder().encode('secret-key')

const token = await new SignJWT({ userId: 123 })
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuedAt()
  .setExpirationTime('2h')
  .sign(secret)

console.log(token)

Поддержка Web Crypto API

Библиотека активно использует Web Crypto API, который встроен в Node.js:

  • crypto.subtle
  • crypto.randomUUID
  • crypto.getRandomValues

Если среда не поддерживает Web Crypto API (например, старые версии Node.js или специфические окружения), потребуется полифилл.

Пример проверки доступности:

if (!globalThis.crypto?.subtle) {
  throw new Error('Web Crypto API недоступен')
}

Настройка в браузере

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

Однако важно учитывать:

  • Необходимо современное окружение (Chrome 60+, Firefox 60+, Safari 14+)
  • Доступ к crypto.subtle
  • Использование сборщиков (Vite, Webpack, Rollup)

Пример импорта:

import { jwtVerify } from 'jose'

Настройка через Vite

Vite корректно работает с jose без дополнительных плагинов.

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

import { decodeJwt } from 'jose'

const token = 'eyJhbGciOi...'

const payload = decodeJwt(token)

console.log(payload)

Настройка Webpack

Для Webpack важно убедиться, что используется ESM-сборка.

webpack.config.js

export default {
  experiments: {
    outputModule: true
  },
  output: {
    module: true
  }
}

Также необходимо:

  • Использовать type: module в package.json
  • Включить поддержку ESM-зависимостей

Работа с переменными окружения

При использовании jose часто требуется хранить секреты:

  • ключи подписи JWT
  • приватные ключи RSA/ECDSA
  • ключи шифрования

Пример через .env

JWT_SECRET=super-secret-key

Загрузка:

import 'dotenv/config'

const secret = new TextEncoder().encode(process.env.JWT_SECRET)

Генерация криптографических ключей

Библиотека предоставляет инструменты для создания ключей:

import { generateSecret } from 'jose'

const secret = await generateSecret('HS256')

console.log(secret)

Для асимметричных алгоритмов:

import { generateKeyPair } from 'jose'

const { publicKey, privateKey } = await generateKeyPair('RS256')

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

1. Использование CommonJS

Ошибка:

Error [ERR_REQUIRE_ESM]: require() of ES Module

Решение:

  • заменить require на import
  • включить "type": "module"

2. Отсутствие Web Crypto API

Ошибка:

crypto.subtle is undefined

Решение:

  • обновить Node.js
  • использовать Node 18+

3. Неверная кодировка ключей

Частая проблема — использование строк вместо Uint8Array:

const secret = new TextEncoder().encode('key')

Организация структуры проекта

Рекомендуемая структура:

project/
 ├── src/
 │   ├── auth/
 │   │   ├── jwt.js
 │   │   ├── keys.js
 │   ├── utils/
 │   ├── app.js
 ├── package.json
 ├── .env

Базовая инициализация библиотеки в проекте

import { jwtVerify, SignJWT } from 'jose'

const secret = new TextEncoder().encode(process.env.JWT_SECRET)

export async function createToken(payload) {
  return await new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('1h')
    .sign(secret)
}

export async function verifyToken(token) {
  const { payload } = await jwtVerify(token, secret)
  return payload
}

Рекомендации по безопасности окружения

  • не хранить ключи в коде
  • использовать переменные окружения
  • регулярно ротировать секреты
  • ограничивать срок жизни токенов
  • использовать асимметричную криптографию в production (RS256, ES256)

Совместимость с CI/CD

В пайплайнах (GitHub Actions, GitLab CI, Jenkins) важно:

  • использовать Node.js 18+
  • задавать переменные окружения через secrets
  • избегать логирования токенов и ключей
  • фиксировать версию jose в lock-файлах

Итоговая проверка окружения

Корректно настроенное окружение характеризуется следующими признаками:

  • отсутствуют ошибки ESM
  • доступен crypto.subtle
  • корректно выполняются SignJWT и jwtVerify
  • поддерживается TypeScript без дополнительных типов
  • сборщик (если используется) не требует специальных плагинов для jose
Оглавление