Версия 3.0, декабрь 2025

Что улучшили

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

2. Добавили возможность экспорта и импорта юнитов. Теперь обновления обучающего контента будут приходить отдельно от обновлений системы. Чтобы вы могли их устанавливать, мы добавили возможность экспорта и импорта юнитов. Эти изменения позволят поддерживать контент в актуальном состоянии без ожидания выхода новых версий системы.

☝ Доступно пользователям с ролью «Администратор».

Экспорт юнита

Функция позволяет выгрузить юнит в формате зашифрованного ZIP-файла для дальнейшего импорта в систему.

Чтобы выгрузить юнит из системы:

1. Перейдите в раздел Настройки → Управление контентом в Знаниях и нажмите Экспорт.

2. Выберите один или несколько юнитов.

☝ Если нужно скачать все юниты, активируйте чекбокс Выбрать все юниты.

3. Нажмите кнопку Экспорт.

4. Придумайте и введите пароль для шифрования. В дальнейшем он понадобится для импорта юнита.

☝ Введенный пароль сохранится в архиве с юнитом в файле encryptKey.txt.

5. Дождитесь завершения экспорта. По завершению процесса в системе отобразится уведомление «Экспорт завершен». На компьютер скачается один общий архив, внутри которого будут зашифрованные .zip-файлы каждого выбранного юнита.

Импорт юнита

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

Чтобы загрузить юнит в систему:

1. Перейдите в раздел Настройки → Управление контентом в Знаниях и нажмите Импорт.

2. Загрузите файлы в систему. Для этого перетащите ZIP-файлы в указанную область или нажмите на область загрузки и выберите файлы, которые нужно импортировать.

⚡Загружайте отдельные zip-файлы юнитов, а не общий архив.

3. При необходимости отредактируйте список загруженных файлов для импорта:

• Чтобы удалить все файлы, нажмите кнопку Удалить все;
• Чтобы удалить один юнит, нажмите на иконку корзины рядом с файлом.

☝ Если вы загрузите один и тот же файл повторно, система сообщит об этом.

4. Перед запуском импорта убедитесь, что параметр Обновить зависимости подходит для всех загружаемых юнитов:

• при включенном параметре — будут сброшены кастомные настройки в разделах «Характеристика АС» и «Проектные роли».
• при отключенном параметре — зависимости обновляться не будут.

☝ Содержание юнитов обновится при импорте независимо от этой опции.

5. Нажмите кнопку Импорт.

6. Введите пароль, который был указан при экспорте.

☝Если юниты передала наша команда, пароль будет находиться в файле encryptKey.txt.

3. Изменили логику авторизации и хранения токенов. Рассказываем об изменениях:

1) Токен авторизации (ранее «JWT») теперь называется accessToken.

2) Токенов авторизации теперь два — accessToken + refreshToken.

• accessToken — токен доступа (авторизации);
• refreshToken — токен обновления.
  ☝Обновить пару accessToken + refreshToken можно только при наличии валидного refreshToken.

3) Сгорание токенов. Инвалидация.

• accessToken
  После смены пароля все ранее выданные accessToken становятся недействительными. При выходе из аккаунта accessToken продолжает быть действительным, пока не будет отозван сменой пароля.
• refreshToken
  Токен отзывается в следующих случаях:

  — при достижении времени, указанного в поле exp (Expiration time) в JWT;

  — при выходе пользователя из аккаунта (в этом случае отзывается только его собственный токен);

  — при изменении пароля.

Для удаления истекших refreshToken добавили фоновой процесс (cron), который запускается каждые 30 минут.

После смены пароля система формирует новую валидную пару — accessToken и refreshToken.

TTL

Время жизни (TTL) accessToken всегда короче, чем у refreshToken. 

TTL токенов (access, refresh и csrf) необходимо указывать в формате: '30s', '15m' , '1h' , '3d' , '4w'. Далее эти значения автоматически переведутся в миллисекунды.

4) Хранение JWT токенов

JWT токены (access и refresh) теперь не хранятся в localStorage браузера, а сохраняются в cookies.

Важно:

• accessToken и refreshToken хранятся в HttpOnly cookies;
• csrfToken (для защиты от CSRF) хранится не в HttpOnly, чтобы к нему мог обращаться код клиента;
• у всех токенов выставлены настройки:
  Secure: true,
  SameSite='strict'

5) Внедрение защиты от CSRF

Так как токены авторизации (accessToken и refreshToken) теперь хранятся в HttpOnly cookies (вместо localStorage, которое уязвимо к XSS — Cross-Site Scripting), потребовалась реализация защиты от CSRF (Cross-Site Request Forgery, межсайтовой подделки запросов).

Механизм защиты реализован в соответствии с рекомендациями OWASP. Подробное описание доступно по ссылке.

6) Для корректной работы нового механизма авторизации необходимо добавить следующие переменные окружения (env) в файл .env для сервера Start EDU (start_learning).

# Адрес системы, по которой она открывается в браузере (адрес «хоста»)
# Указывать без протокола (http/https) и без разделителей (://)
FRONTEND_LINK='reqedu.startx.team'

# Уникальный секрет в 64 знака 
ACCESS_TOKEN_SECRET='access-token-secret'

# Время жизни JWT accessToken
ACCESS_TOKEN_TTL='15m'

# Уникальный секрет в 64 знака
REFRESH_TOKEN_SECRET='access-token-secret'

# время жизни JWT refreshToken
REFRESH_TOKEN_TTL='1h'

# Уникальный секрет в 256 знаков
CSRF_SECRET='csrf-token-long-and-unique-secret'

# Время жизни CSRF токена в cookies
X_CSRF_TOKEN_COOKIE_MAX_AGE='15m'

# Кастомный префикс для ключа CSRF токена в cookies, по умолчанию будет `__Host-startx.x-csrf-token`, но если указать в этом .env, например, qa, тогда данный cookie будет называться __Host-qa.x-csrf-token
CSRF_CUSTOM_CLIENT_SECURE_PREFIX='startx'

# Кто выдал JWT токен (приложение/сервис)
JWT_ISSUER='*'

# Кто будет пользоваться токеном (приложение/сервис)
JWT_AUDIENCE='*'

# Контекст использования токена
JWT_REALM='*'

Чтобы сгенерировать секреты:

1. Проверьте версию с помощью команды:

node -v

nvm use 22

node

const {
  randomBytes,
} = await import('node:crypto');

// Первым параметром идет числовое значение количества случайных байт
randomBytes(128, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});

//если указать 128 — получится секрет, где 256 знаков
//если указать 256 — получится 512 знаков
//если указать 64 — получится 128 знаков
//то есть, количество знаков = количество случайных байт * 2