Структура пакета и точки входа

Библиотека jsrsasign представляет собой монолитный JavaScript-пакет криптографических инструментов, собранных вокруг реализации стандартов PKI, X.509, JWT/JWS/JWE, ASN.1 и базовых криптографических операций. Архитектурно пакет не следует модульной ES6-структуре с дроблением на отдельные импортируемые части в классическом современном смысле, а поставляется как набор готовых сборок и пространств имён, объединённых в единый глобальный объект.

Основная идея организации заключается в предоставлении единого API-пространства KJUR, внутри которого сгруппированы функциональные области: криптография, работа с сертификатами, подписи, ключи и кодирование структур ASN.1.

Дистрибутивы и варианты поставки

В составе npm-пакета и CDN-дистрибутива присутствует несколько ключевых сборок, отличающихся степенью объединения и предназначением:

Полная сборка

Файл вида:

  • jsrsasign-all-min.js
  • jsrsasign-all-min.js.map

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

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

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

Исходная сборка

  • jsrsasign-all-src.js

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

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

  • для анализа кода
  • для дебага криптографических операций
  • для понимания внутренней архитектуры KJUR

Частичные сборки

В некоторых версиях пакета присутствуют разделённые модули (внутренние файлы), однако они не являются полноценными ES-модулями и чаще всего используются только внутри сборочного процесса.

Точки входа в браузере

Глобальный объект

При подключении через <script> основная точка входа формирует глобальный объект:

  • KJUR
  • KEYUTIL
  • X509
  • ASN1HEX

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

Пример структуры после загрузки:

  • KJUR.crypto
  • KJUR.jws
  • KJUR.jws.JWS
  • KJUR.asn1
  • KEYUTIL

CDN-подключение

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

<script src="https://cdnjs.cloudflare.com/ajax/libs/jsrsasign/x.x.x/jsrsasign-all-min.js"></script>

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

Особенности браузерной модели

Библиотека использует UMD-подход, обеспечивая совместимость с:

  • браузерным окружением
  • Node.js
  • legacy-сборщиками

При этом в браузере приоритет отдан глобальному объекту, а не модульной системе.

Точки входа в Node.js

CommonJS импорт

Основной способ использования:

const jsrsasign = require("jsrsasign");

или частичное извлечение:

const { KJUR, KEYUTIL } = require("jsrsasign");

Внутри Node.js пакет также создаёт те же глобальные структуры, что и в браузере, но с возможностью локального использования через экспорт.

Поведение экспорта

Экспорт в Node.js реализован через CommonJS-модель:

  • module.exports = ...
  • либо объект с вложенными пространствами имён

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

  • отсутствует полноценная tree-shaking совместимость
  • импорт всегда тянет значительную часть библиотеки

Глобальные пространства имён

Ключевой архитектурный элемент jsrsasign — это иерархия глобальных объектов.

KJUR

Центральное пространство имён:

  • криптографические операции
  • генерация подписей
  • работа с ключами
  • JWT/JWS/JWE

Структура:

  • KJUR.crypto
  • KJUR.jws
  • KJUR.jwe
  • KJUR.asn1

KEYUTIL

Утилиты для работы с ключами:

  • импорт PEM
  • экспорт ключей
  • преобразование форматов

X509

Модуль для работы с сертификатами X.509:

  • парсинг сертификатов
  • извлечение полей
  • проверка цепочек

ASN1HEX

Низкоуровневые операции с ASN.1:

  • декодирование HEX-структур
  • разбор бинарных сертификатов
  • работа с DER

Внутренняя структура KJUR

Криптография

KJUR.crypto содержит:

  • хэш-функции (SHA-1, SHA-256, SHA-512)
  • HMAC
  • RSA операции
  • AES (в некоторых сборках)

JWS (JSON Web Signature)

KJUR.jws.JWS реализует:

  • создание подписей JWT
  • проверку подписей
  • поддержку алгоритмов RS256, HS256 и других

JWE (JSON Web Encryption)

KJUR.jwe.JWE обеспечивает:

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

ASN.1 модуль

KJUR.asn1:

  • построение ASN.1 структур
  • генерация DER
  • кодирование X.509 элементов

Разделение функциональности внутри пакета

Несмотря на монолитный вид, библиотека логически разделена на слои:

1. Низкоуровневый слой

  • ASN.1 кодирование
  • HEX обработка
  • бинарные преобразования

2. Криптографический слой

  • хэширование
  • симметричное шифрование
  • асимметричные операции

3. PKI слой

  • сертификаты
  • ключи
  • цепочки доверия

4. Прикладной слой

  • JWT
  • JWS
  • JWE

Особенности построения сборки

Отсутствие строгого ES-модульного разбиения

Библиотека исторически развивалась до стандартизации ES Modules, поэтому:

  • используется UMD
  • глобальные пространства имён
  • минимальная модульная изоляция

Монолитность

Главная особенность структуры:

  • один большой bundle
  • отсутствие динамического импорта частей
  • все зависимости внутри одного файла

Совместимость

Архитектура ориентирована на:

  • старые браузеры
  • серверный Node.js
  • CDN-подключение без сборщика

Поведение при подключении в разных средах

Браузер

  • создаётся window.KJUR
  • доступ через глобальные переменные
  • отсутствие импортов

Node.js

  • CommonJS экспорт
  • возможность локального require
  • дублирование глобальных объектов внутри модуля

Сборщики (Webpack, Vite)

Поведение:

  • импортируется как CommonJS
  • tree-shaking неэффективен
  • итоговый бандл увеличивается

Взаимосвязь компонентов внутри пакета

Компоненты связаны через общий namespace, а не через импортные зависимости:

  • KJUR.crypto используется в KJUR.jws
  • ASN1 используется в X509
  • KEYUTIL связывает криптографические операции с сертификатами

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

Итоговая логика структуры

Архитектура jsrsasign строится вокруг следующих принципов:

  • единое глобальное пространство имён
  • монолитная сборка
  • поддержка нескольких сред исполнения
  • разделение функциональности через вложенные объекты
  • отсутствие строгой модульной декомпозиции на уровне импорта
Оглавление