@itcor-kz/im-auth

Модуль авторизации @itcor-kz/im-auth

Модуль авторизации и регистрации пользователей для приложений на Vue 3 + Vuetify 3.
Поставляется как набор готовых страниц и стора, которые можно встроить в хост‑приложение.

Экспортируемые сущности

Из сборочного файла модуля экспортируются:

• страницы
  • AuthPage – авторизация
  • RegisterPage – регистрация
  • RecoverPasswordPage – восстановление пароля
  • EndSessionMessage – диалог об окончании сессии
• store
  • useAuthStore – работа с API авторизации, регистрацией, восстановлением пароля, TOTP и т.п.
  • useLocalAuthStore – локальные настройки модуля (маршруты, фон/логотип, вариант лейаута, языки, цвета)
  • useUserStore – информация о пользователе и рабочих местах
• функции инициализации
  • initAuthModule – инициализация модуля с конфигурацией
  • initAuthModuleRuntime – инициализация runtime-настроек (router)

Инициализация модуля

При использовании пакета желательно настроить модуль через функции инициализации initAuthModule() и initAuthModuleRuntime(). Это влияет только на локальные настройки авторизации (маршруты, фон/логотип, вариант лейаута, языки, цвета и т.п.).

Модуль будет работать и без вызова этих функций — store создастся с дефолтными значениями, и компоненты отрендерятся. Однако для предотвращения мелькания дефолтных значений (логотип, вариант лейаута) при первом рендере рекомендуется задавать конфигурацию до первого использования store.

Рекомендуемый способ: initAuthModule + initAuthModuleRuntime

initAuthModule применяет конфигурацию модуля и должна быть вызвана до первого использования store.
initAuthModuleRuntime настраивает runtime-параметры (router) и должна быть вызвана после app.use(router):

// App.vue или main.ts
import { initAuthModule, initAuthModuleRuntime } from "@itcor-kz/im-auth";
import { useRouter } from "vue-router";

// 1) Инициализация модуля с конфигурацией (до первого использования store)
initAuthModule({
  layoutVariant: "center",
  backgroundImg: "/animals-bg-yellow.jpg",
  authUrl: "/auth",
  regUrl: "/registration",
  restorePasswordUrl: "/restore/password/",
  // ... остальные настройки, в самом низу есть полный пример
});

// 2) Инициализация runtime-настроек (после создания router)
const router = useRouter();
initAuthModuleRuntime(router);

Изменение конфигов после инициализации

Для изменения конфигурации после инициализации используйте метод applyConfig() на store:

import { useLocalAuthStore } from "@itcor-kz/im-auth";

const l_auth = useLocalAuthStore();

// Изменение настроек после инициализации
l_auth.applyConfig({
  layoutVariant: "split", // изменить вариант лейаута
  backgroundImg: "/new-background.jpg", // изменить фон
  ui: {
    enableLanguageSwitcher: false, // отключить переключатель языка
  },
  // ... любые другие настройки из конфига
});

Примечание: Использование applyConfig() после первого рендера может привести к кратковременному отображению старых значений. Для начальной настройки рекомендуется использовать initAuthModule().

Варианты лейаута

Для страниц:

• AuthPage
• RegisterPage
• RecoverPasswordPage

используется настройка:

• l_auth.layoutVariant ('split' | 'center')
  • 'split' – классический вариант: форма и фоновый блок в двух колонках.
  • 'center' – форма по центру, фон на всю страницу.

Установка:

// Рекомендуемый способ (через initAuthModule при инициализации)
initAuthModule({
  layoutVariant: "center",
});

// Изменение после инициализации (через applyConfig)
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  layoutVariant: "center",
});

// Альтернативный способ (через метод store)
l_auth.setLayoutVariant("center"); // или "split"

Настройки фона и логотипа

• Фон страниц авторизации

// Рекомендуемый способ (через initAuthModule при инициализации)
initAuthModule({
  backgroundImg: "/animals-bg-yellow.jpg",
});

// Изменение после инициализации (через applyConfig)
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  backgroundImg: "/animals-bg-yellow.jpg",
});

// Альтернативный способ (через метод store)
l_auth.setAuthBackgroundImg("/animals-bg-yellow.jpg"); // принимает только путь, без url()

Значение попадает в background-image для всех auth‑страниц (в обоих режимах лейаута). Метод setAuthBackgroundImg принимает только путь к изображению (без url()), обёртка добавляется автоматически.

• Логотип

// Рекомендуемый способ (через initAuthModule при инициализации)
initAuthModule(
  {
    logo: {
      default: "/images/custom-logo.svg", // базовый логотип (приоритет)
      light: "/images/logo-light.svg", // для светлой темы
      dark: "/images/logo-dark.svg", // для тёмной темы
    },
  },
  router
);

// Изменение после инициализации (через applyConfig)
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  logo: {
    default: "/images/custom-logo.svg",
    light: "/images/logo-light.svg",
    dark: "/images/logo-dark.svg",
  },
});

// Альтернативный способ (через метод store)
l_auth.setAuthLogo("/images/custom-logo.svg"); // базовый логотип

Приоритет логотипов:

1. logo.default (или authLogo через setAuthLogo) — используется всегда, если задан
2. logo.light / logo.dark — используются в зависимости от темы, если default не задан

Логотип показывается:

• в IAuthHeader (верхнее меню) — светлый/тёмный вариант в зависимости от темы;
• в мобильных версиях шагов регистрации (IRegisterSteps) и восстановления пароля (IPassRecovery) над формой.

Шапка IAuthHeader

Компонент IAuthHeader:

• верхнее меню
  • по умолчанию ссылки «Главная» и «Контакты» (через props homeRoute / contactsRoute);
  • можно полностью переопределить список пунктов через конфиг:

// Рекомендуемый способ (через initAuthModule при инициализации)
initAuthModule(
  {
    ui: {
      topMenu: [
        { label: "Главная", route: "/" },
        { label: "Поддержка", route: "/support" },
      ],
    },
  },
  router
);

// Изменение после инициализации (через applyConfig)
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  ui: {
    topMenu: [
      { label: "Главная", route: "/" },
      { label: "Поддержка", route: "/support" },
    ],
  },
});

• логотип
  • берётся из l_auth.logoLight / l_auth.logoDark (если заданы) или из l_auth.authLogo.
• переключение языка
  • список языков берётся из l_auth.languages;
  • текущий язык хранится в l_auth.currentLocale и кэшируется в localStorage.Locale;
  • для изменения языка можно использовать l_auth.setLocale('ru') или l_auth.setLocale('kz');
  • желательно синхронизировать l_auth.currentLocale с локалью в основном проекте
  • можно полностью выключить язык‑переключатель (и в шапке, и в мобильном меню):

// При инициализации
initAuthModule(
  {
    ui: {
      enableLanguageSwitcher: false,
    },
  },
  router
);

// Или после инициализации
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  ui: {
    enableLanguageSwitcher: false,
  },
});

• цвета и тема
  • палитра берётся из l_auth.themeColors (локализованные названия цветов на русском и казахском);
  • выбранный цвет и тема сохраняются в localStorage.Color и localStorage.Theme;
  • можно отдельно отключать:

// При инициализации
initAuthModule(
  {
    ui: {
      enableColorSchemeSettings: false, // скрыть выбор цвета
      enableThemeSwitcher: false, // скрыть переключатель светлая/тёмная тема
    },
  },
  router
);

// Или после инициализации
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  ui: {
    enableColorSchemeSettings: false,
    enableThemeSwitcher: false,
  },
});

Настройки авторизации и регистрации

• Включение/выключение способов авторизации (номер / ЭЦП):

// При инициализации
initAuthModule(
  {
    auth: {
      enableNumber: true,
      enableEcp: false, // например, оставить только вход по номеру
    },
  },
  router
);

// Или после инициализации
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  auth: {
    enableNumber: true,
    enableEcp: false,
  },
});

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

• Упрощённая регистрация без ЭЦП:

// При инициализации
initAuthModule(
  {
    auth: {
      registrationSimpleWithoutEcp: true,
    },
  },
  router
);

// Или после инициализации
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  auth: {
    registrationSimpleWithoutEcp: true,
  },
});

В этом режиме страница регистрации (RegisterPage) сразу отправляет данные на бэкенд без шага выбора и подписи через ЭЦП.

Настройки восстановления пароля

Поле ИИН и передача ИИН на сервер зависят от включения авторизации по ЭЦП:

• если auth.enableEcp: true — при восстановлении пароля в форме требуются номер и ИИН, и ИИН передаётся в методы восстановления;
• если auth.enableEcp: false — при восстановлении запрашивается только номер, ИИН не показывается и на сервер уходит пустым.

Чекбокс политики конфиденциальности

При входе можно включить отображение чекбокса с политикой конфиденциальности:

// При инициализации
initAuthModule({
  pollConfAuth: true,
});

// Или после инициализации
const l_auth = useLocalAuthStore();
l_auth.applyConfig({
  pollConfAuth: true,
});

Полный пример конфигурации

Рекомендуемый способ (через initAuthModule и initAuthModuleRuntime):

import { initAuthModule, initAuthModuleRuntime } from "@itcor-kz/im-auth";
import { useRouter } from "vue-router";

// 1) Инициализация модуля с конфигурацией (до первого использования store)
initAuthModule({
  {
    // Вариант лейаута
    layoutVariant: "center", // или "split"

    // Фоновое изображение (только путь, без url())
    backgroundImg: "/animals-bg-yellow.jpg",

    // Чекбокс политики конфиденциальности
    pollConfAuth: true,

    // URL для страниц авторизации
    regUrl: "/registration",
    authUrl: "/auth",
    restorePasswordUrl: "/restore/password/",

    // UI-настройки
    ui: {
      enableLanguageSwitcher: true,
      enableColorSchemeSettings: true,
      enableThemeSwitcher: true,
      topMenu: [
        { label: "Главная", route: "/" },
        { label: "Поддержка", route: "/support" },
      ],
    },

    // Логотипы
    logo: {
      default: "/images/custom-logo.svg", // базовый (приоритет)
      light: "/images/logo-light.svg", // для светлой темы
      dark: "/images/logo-dark.svg", // для тёмной темы
    },

    // Настройки авторизации
    auth: {
      enableNumber: true,
      enableEcp: true,
      registrationSimpleWithoutEcp: false,
    },

    // Языки (опционально)
    languages: [
      { value: "ru", label: "Русский" },
      { value: "kz", label: "Казахский" },
    ],

    // Цвета темы (опционально)
    themeColors: [
      {
        value: "#FF0000",
        title: { ru: "Красный", kz: "Қызыл" },
      },
      // ... другие цвета
    ],
});

// 2) Инициализация runtime-настроек (после создания router)
const router = useRouter();
initAuthModuleRuntime(router);

// Теперь можно использовать store
const l_auth = useLocalAuthStore();

Изменение конфигурации после инициализации (через applyConfig):

import { useLocalAuthStore } from "@itcor-kz/im-auth";

const l_auth = useLocalAuthStore();

// Изменение любых настроек после инициализации
l_auth.applyConfig({
  layoutVariant: "split", // изменить вариант лейаута
  backgroundImg: "/new-background.jpg", // изменить фон
  pollConfAuth: false, // изменить настройку
  ui: {
    enableLanguageSwitcher: false, // отключить переключатель языка
    topMenu: [
      { label: "О нас", route: "/about" },
      { label: "Контакты", route: "/contacts" },
    ],
  },
  auth: {
    enableEcp: false, // изменить способ авторизации
  },
  // ... любые другие настройки из конфига
});