@mirta/env-loader 0.0.1 → 0.4.1

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,45 +1,306 @@
-# @mirta/env-loader
+# `@mirta/env-loader`
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![en](https://img.shields.io/badge/lang-en-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-env-loader/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-env-loader/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/env-loader?style=flat-square)](https://npmjs.com/package/@mirta/env-loader)
+[![NPM Downloads](https://img.shields.io/npm/dm/@mirta/env-loader?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/env-loader)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+> Internal environment variable loader based on `@dotenvx/dotenvx`, used by Mirta tools.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+`@mirta/env-loader` provides a unified way to load and filter environment variables within the Mirta framework.
 
-## Purpose
+Supports:
+- `.env` files with modes (`development`, `test`, `production`) and `.local` variants
+- Environment variables from the OS and CLI overrides
+- Prefix-based filtering (`MIRTA_`, `APP_`)
+- `.env` file encryption via `@dotenvx/dotenvx`
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@mirta/env-loader`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+Used in `@mirta/rollup`, `@mirta/testing`, and other internal tools.
 
-## What is OIDC Trusted Publishing?
+**Not intended for execution in the Duktape environment on Wiren Board controllers.**
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+---
+
+## 📦 Installation
+
+```bash
+# Not required directly — used internally by Mirta
+pnpm add -D @mirta/env-loader
+```
+
+⚠️ This package is part of Mirta's internal infrastructure. It is usually not used directly.
+
+## 🚀 Quick Start
+
+```ts
+import { loadEnv, loadEnvReplacements } from '@mirta/env-loader'
+
+// Load environment variables
+const env = loadEnv({ mode: 'development' })
+
+// For code replacement (e.g., with @rollup/plugin-replace)
+const replacements = loadEnvReplacements({ mode: 'production' })
+```
+
+## 🧰 API
+
+### `loadEnv(options?: EnvLoaderOptions): Record<string, string>`
+
+Synchronously loads and filters environment variables.
+
+#### Parameters
+
+| Field | Type | Description |
+|------|-----|----------|
+| `mode` | `string` | Environment mode. Defaults to `process.env.NODE_ENV` |
+| `prefix` | `string \| string[]` | Prefixes for filtering. Default: `['MIRTA_', 'APP_']` |
+| `cwd` | `string` | Current working directory. Defaults to `process.cwd()` |
+| `rootDir` | `string` | Root directory of the project (e.g., in a monorepo).<br/>If specified and differs from `cwd`, files are also searched in the root |
+| `envFile` | `string \| string[]` | Base `.env` file name. Default: `.env` |
+ | `keepNodeEnv` | `boolean` | Whether to include `NODE_ENV`. Default: `true`.<br/>If `false`, it is removed from the returned object.<br/>⚠️ Note: does not affect the global `process.env.NODE_ENV` value |
+ | `dotenv` | `DotenvOptions` | Additional `@dotenvx/dotenvx` settings, see below |
+
+#### ⚠️ **Security: `prefix` cannot be fully disabled**
+
+The `prefix` option **cannot be disabled** (e.g., via `prefix: false`, `prefix: ''`, `prefix: []`, or `prefix: ['']`) to prevent **automatic secret leakage**.
+
+Even when loading variables, filtering remains active, and default prefixes (`MIRTA_`, `APP_`) are applied.
+
+If you need to load variables with other prefixes, explicitly specify them:
+
+```ts
+loadEnv({
+  prefix: ['MIRTA_', 'APP_', 'CUSTOM_', 'SECRET_'] // ← explicit allowance
+})
+```
+This ensures that **only expected variables** are included in the result and — when using `loadEnvReplacements` — in the client-side code.
+
+#### ⚙️ Dotenv Options
+
+Type: `DotenvOptions` — passed directly to `@dotenvx/dotenvx`, but with limitations.
+
+`@mirta/env-loader` controls key aspects of loading, so some options are overridden or ignored to ensure predictable behavior.
 
-## Setup Instructions
+✅ **Supported and safe options**
 
-To properly configure OIDC trusted publishing for this package:
+| Option | Description |
+|--------|-------------|
+| `overload` | If `true`, later files overwrite variables from earlier ones. Default: `false` (earlier files have higher priority) |
+| `encoding` | Encoding of `.env` files. Default: `'utf8'` |
+| `strict` | If `true`, throws an error on parsing failures. Default: `false` |
+| `debug` | Enables debug output. Useful for diagnostics. Default: `false` |
+| `verbose` | Increases log verbosity |
+| `quiet` | Suppresses console output (including errors) |
+| `envKeysFile` | Path to `.env.keys` — useful in monorepos |
+| `logLevel` | Log level: `'error'`, `'warn'`, `'info'`, etc. Partially overridden — see below |
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+❌ **Ignored or overridden options**
 
-## DO NOT USE THIS PACKAGE
+| Option | What happens | Reason |
+|--------|--------------|--------|
+| `path` | Ignored | File order and list are determined by `@mirta/env-loader` |
+| `processEnv` | Overridden | To avoid polluting `process.env` and to apply filtering |
+| `convention` | Ignored | To prevent conflicts with built-in priority logic |
+| `logLevel` | Default is `'warn'`, but can be overridden | To avoid suppressing important warnings (e.g., missing `.env.keys`) |
+| `ignore` | `'MISSING_ENV_FILE'` is enforced | `.env` files are optional — missing files are not an error |
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+📌 **Recommendations**
+- Use `overload`, `debug`, `encoding` — they work as expected.
+- Do not rely on `convention` or `path` — they are disabled.
+- To change load order, configure `envFile`, `mode`, and `.env` file structure.
 
-## More Information
+Example
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```ts
+const env = loadEnv({
+  mode: 'production',
+  dotenv: {
+    overload: true,     // ✅ allowed: reverses file processing priority
+    debug: true,        // ✅ allowed: console output
+    encoding: 'utf16',  // ✅ rare, but possible
+    // convention: 'nextjs'  // ❌ ignored
+  }
+})
+```
+
+### File Loading Order
+
+Files are processed in descending order of priority:
+
+1. **First — all `.env` files in `cwd`** (current directory):
+   - `.env.${mode}.local`
+   - `.env.${mode}`
+   - `.env.local`
+   - `.env`
+2. **Then — all `.env` files in `rootDir`** (project root), in the same order.
+
+#### ⚠️ Local package settings take precedence over root ones
+
+For example:
+- A project is built in `development` mode,
+- The package file `packages/my-app/.env` contains `PORT=3000`
+- The project's root file `.env.development` contains `PORT=4000`
+
+In this case, `PORT=3000` will be used,<br/>
+because the local context is considered more specific.
+
+#### ⚠️ Behavior on key collision depends on `dotenv.overload`
+
+- `dotenv.overload`: `false` (default)
+
+  Variables from earlier files are not overwritten by later ones.<br/>
+  → The earlier a file appears in the list, the higher its priority.
+
+- `dotenv.overload`: `true`
+
+  Later files overwrite earlier ones.<br/>
+  → The later a file appears in the list, the higher its priority.
+
+By default, `overload`: `false` is used, so .env.${mode}.local has the highest priority.
+
+---
+
+### `loadEnvReplacements(options?: EnvLoaderOptions): Record<string, string>`
+
+Returns an object like:
+
+```ts
+{
+  'process.env.APP_PORT': '"3000"',
+  'import.meta.env.APP_PORT': '"3000"'
+}
+```
+
+Suitable for integration with `@rollup/plugin-replace`.
 
 ---
 
-**Maintained for OIDC setup purposes only**
+### DEFAULT_ENV_PREFIXES
+
+```ts
+['MIRTA_', 'APP_']
+```
+
+Default list of prefixes for variable filtering.
+Can be overridden via `options.prefix`.
+
+## 🛡️ Security and Configuration Best Practices
+
+### ❌ Do not use system environment variables directly
+
+Directly loading system environment variables — such as `PATH`, `HOME`, `USER`, `NODE_VERSION` — is **not recommended**, even if they are available in the environment.
+
+👉 Why:
+- **Breaks portability**: behavior will differ across machines.
+- **Security risk**: sensitive data may accidentally leak into the build.
+- **Non-deterministic behavior**: application behavior depends on the environment, not configuration.
+
+---
+
+### ✅ Option 1: Explicit override in `.env`
+
+If you truly need a system environment variable, **explicitly declare it in your `.env` file**:
+
+```env
+# .env
+MIRTA_PATH=${PATH}
+MIRTA_HOME=${HOME}
+APP_NODE_VERSION=${NODE_VERSION}
+```
+👉 This way:
+- You **control** which variables enter the application,
+- You **document** the intent explicitly,
+- You can **override** the value per environment.
+
+⚠️ Important: `@mirta/env-loader` does not expose variables outside allowed prefixes — even if `${PATH}` is used in `.env`, the `PATH` variable itself will not be included unless it starts with `MIRTA_` or `APP_`.
+
+---
+
+### ✅ Option 2: Explicit configuration (recommended)
+
+Better yet — **avoid relying on system variables altogether**, and define paths and settings explicitly:
+
+```env
+# .env
+MIRTA_BINARY_PATH=/usr/local/bin/custom-tool
+APP_CONFIG_DIR=/etc/myapp
+APP_CACHE_DIR=./temp/cache
+```
+👉 Benefits:
+
+**Portability**: the app behaves consistently across environments,
+**Readability**: all settings are visible in `.env`,
+**Security**: no surprises from the environment,
+**Testability**: easy to emulate different setups.
+
+---
+
+🧩 Example of a secure .env
+
+```env
+# Environment mode
+NODE_ENV=development
+
+# Binaries and paths
+MIRTA_BINARY_PATH=/opt/tools/cli
+MIRTA_CONFIG_ROOT=./config
+
+# Application settings
+APP_PORT=3000
+APP_API_KEY=dev-key-7x29qn
+APP_FEATURE_TOGGLES=auth,logging,metrics
+
+# Logging
+MIRTA_LOG_LEVEL=debug
+```
+
+---
+
+📌 Summary
+- ❌ **Do not rely** on system environment variables directly.
+- ✅ **Explicitly** declare everything you need in .env.
+- ✅ **Use clear, fixed values**.
+
+This way, you build a **predictable, secure, and portable** application.
+
+## 🔐 Working with Encrypted Variables
+
+`@mirta/env-loader` uses `@dotenvx/dotenvx` to load and decrypt `.env` files.
+
+> ⚠️ **Deprecated: `DOTENV_KEY` and `.env.vault`**
+>
+> The legacy encryption flow using `DOTENV_KEY` and `.env.vault` is **deprecated**.  
+> While still supported for backward compatibility, it is no longer recommended.
+
+
+✅ **Current mechanism: Key-pair encryption**
+
+`dotenvx` now uses public-key cryptography:
+- **`DOTENV_PUBLIC_KEY`** — used to **encrypt** `.env` files.
+- **`DOTENV_PRIVATE_KEY`** — used to **decrypt** them at runtime.
+
+When enabled:
+- Your `.env` files are **fully encrypted on disk**.
+- Only the public key is needed for encryption (safe to commit).
+- The private key is required for decryption (kept secret in CI/CD or local env).
+
+🔍 How it works:
+- `@dotenvx/dotenvx` performs all cryptographic operations using the key pair.
+- `@mirta/env-loader` receives **already decrypted values** — it does not handle keys or crypto directly.
+
+👉 We recommend migrating to the new key-pair system.
+ 
+For setup, see: [dotenvx — Encryption Guide](https://github.com/dotenvx/dotenvx#encryption)
+
+## ✅ Testing
+
+The package is covered with unit tests (Vitest):
+- Loading `.env` files in the correct order
+- Prefix filtering
+- `rootDir` support
+- Integration with `DOTENV_KEY` (via mocks)
+- Cross-platform compatibility
+
+## ⚠️ Limitations
+
+**Works only in Node.js** (not in Duktape).

package/README.ru.md

@@ -0,0 +1,300 @@
+# `@mirta/env-loader`
+
+[![en](https://img.shields.io/badge/lang-en-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-env-loader/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-env-loader/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/env-loader?style=flat-square)](https://npmjs.com/package/@mirta/env-loader)
+[![NPM Downloads](https://img.shields.io/npm/dm/@mirta/env-loader?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/env-loader)
+
+> Внутренний загрузчик переменных окружения на базе `@dotenvx/dotenvx`, используемый инструментами Mirta.
+
+`@mirta/env-loader` обеспечивает единый способ загрузки и фильтрации переменных окружения в рамках фреймворка Mirta.
+
+Поддерживает:
+- `.env`-файлы с режимами (`development`, `test`, `production`) и `.local`-файлами
+- Переменные из операционной системы и CLI-переопределения
+- Фильтрацию по префиксам (`MIRTA_`, `APP_`)
+- Шифрование `.env`-файлов через `@dotenvx/dotenvx`
+
+Используется в `@mirta/rollup`, `@mirta/testing` и других внутренних инструментах.
+
+**Не предназначен для выполнения в среде Duktape на контроллерах Wiren Board.**
+
+## 📦 Установка
+
+```bash
+# Не требуется напрямую — используется внутри Mirta
+pnpm add -D @mirta/env-loader
+```
+
+⚠️ Этот пакет — часть внутренней инфраструктуры фреймворка Mirta. Обычно он не используется напрямую.
+
+## 🚀 Быстрый старт
+
+```ts
+import { loadEnv, loadEnvReplacements } from '@mirta/env-loader'
+
+// Загрузка переменных окружения
+const env = loadEnv({ mode: 'development' })
+
+// Для подстановки в код (например, @rollup/plugin-replace)
+const replacements = loadEnvReplacements({ mode: 'production' })
+```
+
+## 🧰 API
+
+### `loadEnv(options?: EnvLoaderOptions): Record<string, string>`
+Синхронно загружает и фильтрует переменные окружения.
+
+#### Параметры
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `mode` | `string` | Режим окружения. По умолчанию — `process.env.NODE_ENV` |
+| `prefix` | `string \| string[]` | Префиксы для фильтрации. По умолчанию — `['MIRTA_', 'APP_']` |
+| `cwd` | `string` | Текущая рабочая директория. По умолчанию — `process.cwd()` |
+| `rootDir` | `string` | Корневая директория проекта (например, в монорепозитории).<br/>Если значение указано и отличается от `cwd`, файлы ищутся также и в корне |
+| `envFile` | `string \| string[]` | Базовое имя `.env`-файла. По умолчанию — `.env` |
+| `keepNodeEnv` | `boolean` | Сохранять ли `NODE_ENV`. По умолчанию — `true`, при `false` удаляется из возвращаемого объекта.<br/>⚠️ Примечание: не влияет на глобальное значение `process.env.NODE_ENV` |
+| `dotenv` | `DotenvOptions` | Дополнительные настройки `@dotenvx/dotenvx`, см. ниже |
+
+#### ⚠️ **Безопасность: `prefix` нельзя отключить полностью**
+
+Параметр `prefix` **не может быть отключён** (например, через `prefix: false`, `prefix: ''`, `prefix: []` или `prefix: ['']`), чтобы предотвратить **автоматическую утечку секретов**.
+
+Даже при загрузке всех переменных, фильтрация остаётся включённой, и применяются префиксы по умолчанию (`MIRTA_`, `APP_`).
+
+Если вам нужно загрузить переменные с другими префиксами — явно укажите их:
+
+```ts
+loadEnv({
+  prefix: ['MIRTA_', 'APP_', 'CUSTOM_', 'SECRET_'] // ← явное разрешение
+})
+```
+Это гарантирует, что **только ожидаемые переменные** попадут в результат и, при использовании `loadEnvReplacements`, — в клиентский код.
+
+#### ⚙️ **Опции dotenv****
+
+Тип: `DotenvOptions` — передаётся напрямую в `@dotenvx/dotenvx`, но с ограничениями.
+
+`@mirta/env-loader` контролирует ключевые аспекты загрузки, поэтому некоторые опции переопределяются или игнорируются, чтобы гарантировать предсказуемое поведение.
+
+✅ **Поддерживаемые и безопасные опции**
+
+| Опция | Описание |
+|------|---------|
+| `overload` | Если `true` — последующие файлы перезаписывают переменные из предыдущих. По умолчанию `false` (приоритет у первых файлов) |
+| `encoding` | Кодировка `.env`-файлов. По умолчанию `'utf8'` |
+| `strict` | Если `true` — выбрасывает ошибку при сбоях парсинга. По умолчанию `false` |
+| `debug` | Включает отладочный вывод. Полезно для диагностики. По умолчанию `false` |
+| `verbose` | Увеличивает детализацию логов |
+| `quiet` | Подавляет вывод в консоль (включая ошибки) |
+| `envKeysFile` | Путь к `.env.keys` — полезно в монорепозиториях |
+| `logLevel` | Уровень логирования: `'error'`, `'warn'`, `'info'` и т.д. Частично переопределён — см. ниже |
+
+❌ **Опции, которые игнорируются или переопределяются**
+
+| Опция | Что происходит | Причина |
+|------|----------------|--------|
+| `path` | Игнорируется | Порядок и список файлов задаётся `@mirta/env-loader` |
+| `processEnv` | Игнорируется | Внутренний объект, чтобы не загрязнять `process.env` и применить фильтрацию |
+| `convention` | Игнорируется | Чтобы избежать конфликта с собственной логикой приоритетов |
+| `logLevel` | По умолчанию `'warn'`, но может быть переопределён | Чтобы не подавлять важные предупреждения, например, о пропущенных `.env.keys` |
+| `ignore` | Принудительно включает `'MISSING_ENV_FILE'` | `.env`-файлы не обязательны — отсутствие не является ошибкой |
+
+📌 **Рекомендации**
+
+- Используйте `overload`, `debug`, `encoding` — они работают как ожидается,
+- Не полагайтесь на `convention` или `path` — они отключены,
+- Если вы хотите изменить порядок загрузки — настройте envFile, mode и структуру `.env`-файлов.
+
+Пример
+
+```ts
+const env = loadEnv({
+  mode: 'production',
+  dotenv: {
+    overload: true,     // ✅ разрешено: инвертирует приоритет обработки файлов
+    debug: true,        // ✅ разрешено: вывод в консоль
+    encoding: 'utf16',  // ✅ редко, но возможно
+    // convention: 'nextjs'  // ❌ проигнорировано
+  }
+})
+```
+
+### Порядок загрузки файлов
+
+Файлы обрабатываются в порядке убывания приоритета:
+
+1. **Сначала — все `.env`-файлы в `cwd`** (текущей директории):
+   - `.env.${mode}.local`
+   - `.env.${mode}`
+   - `.env.local`
+   - `.env`
+
+2. **Затем — все `.env`-файлы в `rootDir`** (корне проекта), в том же порядке.
+
+#### ⚠️ **Локальные настройки пакета имеют приоритет над корневыми**
+
+Предположим, что:
+- некий разрабатываемый проект собирается в режиме `development`,
+- файл пакета `packages/my-app/.env` содержит `PORT=3000`,
+- корневой файл проекта `.env.development` содержит `PORT=4000`.
+
+В этом случае будет использовано значение `PORT=3000`,<br/>
+потому что локальный контекст считается более специфичным.
+
+#### ⚠️ **Поведение при совпадении ключей зависит от значения `dotenv.overload`**
+
+- **`dotenv.overload`: `false`** (по умолчанию)
+
+  Переменные из **первых** файлов **не перезаписываются** последующими.<br/>
+  → Чем **раньше** файл в списке — тем **выше** его приоритет.
+
+- **`dotenv.overload`: `true`**
+
+  Последующие файлы **перезаписывают** предыдущие.<br/>
+  → Чем **позже** файл в списке — тем **выше** его приоритет.
+
+По умолчанию используется `overload`: `false`, поэтому `.env.${mode}.local` имеет наивысший приоритет.
+
+---
+
+### `loadEnvReplacements(options?: EnvLoaderOptions): Record<string, string>`
+
+Возвращает объект вида:
+
+```ts
+{
+  'process.env.APP_PORT': '"3000"',
+  'import.meta.env.APP_PORT': '"3000"'
+}
+```
+Подходит для интеграции с `@rollup/plugin-replace`
+
+---
+
+### `DEFAULT_ENV_PREFIXES`
+
+```ts
+['MIRTA_', 'APP_']
+```
+Список префиксов по умолчанию для фильтрации переменных.
+Можно переопределить через `options.prefix`.
+
+## 🛡️ Рекомендации по безопасности и проектированию
+
+### ❌ Не используйте системные переменные напрямую
+
+Прямая загрузка системных переменных окружения — таких как `PATH`, `HOME`, `USER`, `NODE_VERSION`, **не рекомендуется**. Даже если они доступны в среде выполнения.
+
+👉 Почему:
+- Это **нарушает переносимость**: поведение будет отличаться на разных машинах.
+- Это **риск безопасности**: в сборку может случайно попасть приватная информация.
+- Это **нарушает детерминированность**: поведение приложения зависит от окружения, а не от конфигурации.
+
+---
+
+### ✅ Вариант 1: Явное переопределение в `.env`
+
+Если вам действительно нужно значение системной переменной — **явно объявите его в `.env`-файле**:
+
+```env
+# .env
+MIRTA_PATH=`${PATH}`
+MIRTA_HOME=`${HOME}`
+APP_NODE_VERSION=`${NODE_VERSION}`
+```
+👉 Так:
+- Вы **контролируете**, какие переменные попадают в приложение,
+- Вы **логируете** это намерение явно,
+- Вы можете **переопределить** значение для конкретного окружения.
+
+⚠️ Важно: `@mirta/env-loader` не раскрывает переменные вне указанных префиксов — даже если `${PATH}` используется в `.env`, сам `PATH` не попадёт в результат, если не начинается с `MIRTA_` или `APP_`.
+
+---
+
+### ✅ Вариант 2: Явная конфигурация (рекомендуется)
+
+Лучше — вообще не полагаться на системные переменные, а задавать пути и настройки явно:
+
+```env
+# .env
+MIRTA_BINARY_PATH=/usr/local/bin/custom-tool
+APP_CONFIG_DIR=/etc/myapp
+APP_CACHE_DIR=./temp/cache
+```
+
+👉 Преимущества:
+- **Переносимость**: приложение работает одинаково на всех машинах,
+- **Читаемость**: все настройки видны в `.env`,
+- **Безопасность**: никаких сюрпризов из окружения,
+- **Тестируемость**: легко эмулировать разные окружения.
+
+---
+
+🧩 Пример безопасного `.env`
+
+```env
+# Режим окружения
+NODE_ENV=development
+
+# Пути и бинарники
+MIRTA_BINARY_PATH=/opt/tools/cli
+MIRTA_CONFIG_ROOT=./config
+
+# Пользовательские настройки
+APP_PORT=3000
+APP_API_KEY=dev-key-7x29qn
+APP_FEATURE_TOGGLES=auth,logging,metrics
+
+# Логирование
+MIRTA_LOG_LEVEL=debug
+```
+
+📌 Итог
+- ❌ **Не полагайтесь** на системные переменные напрямую.
+- ✅ **Явно объявляйте** всё, что нужно, в .env.
+- ✅ **Используйте понятные, зафиксированные значения**.
+
+Так вы строите **предсказуемое, безопасное и переносимое** приложение.
+
+## 🔐 Работа с зашифрованными переменными
+
+`@mirta/env-loader` использует `@dotenvx/dotenvx` для загрузки и расшифровки `.env`-файлов.
+
+> ⚠️ **Устарело: `DOTENV_KEY` и `.env.vault`**
+>
+> Старый механизм шифрования через `DOTENV_KEY` и `.env.vault` **устарел**.  
+> Поддерживается только для обратной совместимости. Не рекомендуется к использованию.
+
+✅ **Новый механизм: шифрование с парой ключей**
+
+`dotenvx` теперь использует асимметричное шифрование:
+- **`DOTENV_PUBLIC_KEY`** — для **шифрования** `.env`-файлов.
+- **`DOTENV_PRIVATE_KEY`** — для **расшифровки** в рантайме.
+
+При использовании:
+- `.env`-файлы **полностью зашифрованы на диске**.
+- Публичный ключ можно фиксировать в репозитории.
+- Приватный ключ остаётся в CI/CD или локальном окружении.
+
+🔍 Как это работает:
+- `@dotenvx/dotenvx` выполняет все криптографические операции.
+- `@mirta/env-loader` получает **уже расшифрованные значения** — не работает с ключами напрямую.
+
+👉 Рекомендуется перейти на новую систему.  
+Подробнее: [dotenvx — Encryption Guide](https://github.com/dotenvx/dotenvx#encryption)
+
+## ✅ Тестирование
+
+Пакет покрыт юнит-тестами (Vitest):
+
+- Загрузка `.env`-файлов в правильном порядке
+- Фильтрация по префиксам
+- Поддержка `rootDir`
+- Интеграция с `DOTENV_KEY` (через моки)
+- Кроссплатформенность
+
+## ⚠️ Ограничения
+
+**Работает только в Node.js** (не в Duktape).<br/>

package/dist/index.d.mts

@@ -0,0 +1,186 @@
+/**
+ * Набор префиксов для переменных окружения, которые будут загружены в проект.
+ *
+ * @description
+ * Константа используется для фильтрации переменных окружения по их префиксам:
+ * - `MIRTA_` — системные настройки фреймворка (например, логирование, таймауты).
+ * - `APP_` — пользовательские сценарии и параметры автоматизаций (например, расписания, пороговые значения).
+ *
+ * @example
+ * ```env
+ * # Пример переменной окружения, которая будет учтена
+ * MIRTA_LOG_LEVEL=debug
+ * APP_LIVING_ROOM_LIGHTS_SCHEDULE='18:00-22:00'
+ *
+ * ```
+ * @remarks
+ * Эта константа предназначена для использования в конфигурации `loadEnv`, где указывается фильтр для загрузки `.env`-файлов.
+ * Может быть переопределена через пользовательскую конфигурацию, если требуется изменить список допустимых префиксов.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare const DEFAULT_ENV_PREFIXES: readonly ["MIRTA_", "APP_"];
+/**
+ * Интерфейс для настройки параметров `dotenvx`.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface DotenvOptions {
+    /**
+     * Кодировка файла `.env`, по умолчанию `'utf-8'`
+     *
+     **/
+    encoding?: string;
+    /**
+     * Перезаписывает любые существующие переменные окружения значениями из файла `.env`
+     *
+     * @default false
+     *
+     **/
+    overload?: boolean;
+    /**
+     * Выбрасывает ошибку сразу при её возникновении — например, при отсутствии файла `.env`.
+     *
+     * @default false
+     *
+     **/
+    strict?: boolean;
+    /**
+     * Подавляет конкретные ошибки, например `MISSING_ENV_FILE`.
+     *
+     * Ключи ошибок можно найти в [исходном коде](https://github.com/dotenvx/dotenvx/blob/main/src/lib/helpers/errors.js) библиотеки `dotenvx`.
+     *
+     **/
+    ignore?: string[];
+    /**
+     * Путь к файлу с приватными ключами `.env.keys`, полезно для монорепозиториев.
+     *
+     **/
+    envKeysFile?: string;
+    /**
+     * Включает логирование для диагностики причин, почему определённые ключи или значения не устанавливаются.
+     *
+     * @default false
+     *
+     **/
+    debug?: boolean;
+    /**
+     * Увеличивает уровень детализации логов.
+     *
+     * @default false
+     *
+     **/
+    verbose?: boolean;
+    /**
+     * Подавляет все сообщения в консоль, даже ошибки.
+     *
+     * @default false
+     *
+     **/
+    quiet?: boolean;
+    /**
+     * Уровень логирования. Определяет, какие сообщения будут выводиться в консоль.
+     *
+     **/
+    logLevel?: 'error' | 'warn' | 'success' | 'successv' | 'info' | 'help' | 'verbose' | 'debug';
+}
+/**
+ * Позволяет настроить поведение загрузки и фильтрации переменных окружения.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface EnvLoaderOptions {
+    /**
+     * Режим окружения (например, `'development'`, `'production'`, `'test'`).
+     *
+     * По умолчанию используется значение из `process.env.NODE_ENV`.
+     *
+     **/
+    mode?: string;
+    /**
+     * Префиксы для фильтрации переменных окружения.
+     *
+     * Если не указано, используется значение по умолчанию из {@link DEFAULT_ENV_PREFIXES}..
+     *
+     * @remarks
+     * Полностью отключить фильтрацию нельзя — это мера защиты от утечки секретов
+     * (например, `DB_PASSWORD`, `API_KEY`) в клиентский код.
+     *
+     * Чтобы использовать другие префиксы, перечислите их явно.
+     *
+     * @example
+     * // Фильтрация по одному префиксу
+     * prefix: 'APP_'
+     * // → включаются только переменные, начинающиеся с `APP_`
+     *
+     * @example
+     * // Фильтрация по нескольким префиксам
+     * prefix: ['MIRTA_', 'CUSTOM_']
+     * // → включаются переменные с `MIRTA_` или `CUSTOM_`
+     *
+     **/
+    prefix?: string | string[];
+    /**
+     * Текущая рабочая директория для обнаружения и загрузки файлов `.env`.
+     *
+     **/
+    cwd?: string;
+    /**
+     * Корневая директория проекта.
+     *
+     * Используется для обнаружения и загрузки общих `.env`-файлов.
+     * Если не указана или совпадает с `cwd`, поиск в корне не выполняется.
+     *
+     **/
+    rootDir?: string;
+    /**
+     * Префикс файла с переменными окружения, по умолчанию `'.env'`.
+     *
+     **/
+    envFile?: string | string[];
+    /**
+     * Определяет, нужно ли включать переменную `NODE_ENV` в результат.
+     *
+     * @default true
+     *
+     * @remarks
+     *
+     * Используется для изоляции тестовой среды или предотвращения
+     * утечки режима выполнения в клиентский код.
+     *
+     **/
+    keepNodeEnv?: boolean;
+    /**
+     * Дополнительные параметры библиотеки `dotenvx`.
+     *
+     **/
+    dotenv?: DotenvOptions;
+}
+/**
+ * Загружает и фильтрует переменные окружения из dotenv-файлов.
+ * @param options Опции загрузки и фильтрации переменных окружения (см. {@link EnvLoaderOptions}).
+ * @returns Набор переменных окружения.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function loadEnv(options?: EnvLoaderOptions): Record<string, string>;
+
+/**
+ * Загружает и фильтрует переменные окружения из dotenv-файлов.
+ * Используется совместно с `@rollup/plugin-replace` для замены значений в коде.
+ *
+ * @param options Опции загрузки и фильтрации переменных окружения (см. {@link EnvLoaderOptions}).
+ * @returns Объект с ключами вида `process.env.KEY` и `import.meta.env.KEY`, где `KEY` — имя переменной окружения.
+ *
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function loadEnvReplacements(options?: EnvLoaderOptions): Record<string, string>;
+
+export { DEFAULT_ENV_PREFIXES, loadEnv, loadEnvReplacements };
+export type { EnvLoaderOptions };

package/dist/index.mjs

@@ -0,0 +1,195 @@
+import nodePath from 'node:path';
+import dotenvx from '@dotenvx/dotenvx';
+import { ensureCompactArray, ensureArray } from '@mirta/basics/array';
+import { existsSync } from 'node:fs';
+
+/**
+ * Набор префиксов для переменных окружения, которые будут загружены в проект.
+ *
+ * @description
+ * Константа используется для фильтрации переменных окружения по их префиксам:
+ * - `MIRTA_` — системные настройки фреймворка (например, логирование, таймауты).
+ * - `APP_` — пользовательские сценарии и параметры автоматизаций (например, расписания, пороговые значения).
+ *
+ * @example
+ * ```env
+ * # Пример переменной окружения, которая будет учтена
+ * MIRTA_LOG_LEVEL=debug
+ * APP_LIVING_ROOM_LIGHTS_SCHEDULE='18:00-22:00'
+ *
+ * ```
+ * @remarks
+ * Эта константа предназначена для использования в конфигурации `loadEnv`, где указывается фильтр для загрузки `.env`-файлов.
+ * Может быть переопределена через пользовательскую конфигурацию, если требуется изменить список допустимых префиксов.
+ *
+ * @since 0.4.0
+ *
+ **/
+const DEFAULT_ENV_PREFIXES = ['MIRTA_', 'APP_'];
+/**
+ * Возвращает возможные имена .env-файлов в зависимости от режима окружения.
+ *
+ * @param mode - Название текущего режима (например, `'development'`, `'production'`, `'test'`).
+ *               Если значение не определено, возвращается только базовый файл.
+ * @param envFile - Базовое имя файла, которое будет дополнено (по умолчанию `.env`).
+ * @returns Массив строк с путями к файлам окружения, отсортированный в порядке убывания приоритета загрузки.
+ *
+ * @since 0.4.0
+ *
+ **/
+function getEnvFileVariantsByMode(mode, envFile) {
+    if (mode === 'test' && envFile.endsWith('.local'))
+        return [];
+    const envFiles = [];
+    if (mode) {
+        // 1. Формируем файлы с суффиксом .local для конкретного окружения (кроме test)
+        if (mode !== 'test')
+            envFiles.push(`${envFile}.${mode}.local`);
+        // 2. Формируем файл для конкретного окружения без .local
+        envFiles.push(`${envFile}.${mode}`);
+    }
+    // 3. Формируем глобальный .local-файл (кроме test)
+    if (mode !== 'test')
+        envFiles.push(`${envFile}.local`);
+    // 4. Базовый файл
+    envFiles.push(envFile);
+    // Собираем список и убираем пустые элементы
+    return envFiles;
+}
+/**
+ * Формирует список существующих файлов окружения для загрузки на основе режима, текущей и корневой директорий.
+ *
+ * @param options - Опции разрешения путей: `mode` (env mode), `cwd` (текущая рабочая директория), `rootDir` (опциональная корневая директория для общих .env), `envFile` (имя или список базовых файлов, по умолчанию `.env`), `quiet` (подавлять предупреждения о дубликатах)
+ * @returns Массив абсолютных путей к существующим файлам окружения, в порядке поиска (сначала по `cwd`, затем по `rootDir` при наличии)
+ *
+ * @since 0.4.0
+ */
+function resolveEnvFiles(options) {
+    const { mode, cwd, rootDir, envFile = '.env', quiet } = options;
+    // Сначала — все файлы из cwd
+    const lookupDirs = [cwd];
+    // Потом — все файлы из rootDir, если директория указана
+    if (rootDir && rootDir !== cwd)
+        lookupDirs.push(rootDir);
+    // Преобразует envFile в массив уникальных значений:
+    // удаляет дубликаты с помощью `Set`.
+    //
+    const envFiles = [
+        ...new Set(ensureArray(envFile)),
+    ];
+    const envFilesVariants = new Set();
+    for (const file of envFiles) {
+        for (const variant of getEnvFileVariantsByMode(mode, file)) {
+            if (envFilesVariants.has(variant) && !quiet) {
+                console.warn(`[@mirta/env-loader] Redundant env file entry detected: "${file}" may be unnecessary, as it generates a file already covered by another entry.`);
+                continue;
+            }
+            envFilesVariants.add(variant);
+        }
+    }
+    const result = [];
+    // Перечисляем директории, в которых нужно выполнить поиск.
+    for (const dir of lookupDirs) {
+        // Перемножаем на варианты .env-файлов (обычно это все вариации `.env`)
+        for (const file of envFilesVariants) {
+            const path = nodePath.join(dir, file).replaceAll('\\', '/');
+            // Самостоятельно отсеиваем несуществующие файлы,
+            // чтобы предотвратить падение производительности.
+            //
+            if (existsSync(path))
+                result.push(path);
+        }
+    }
+    return result;
+}
+/**
+ * Отбирает из заданного набора только допустимые переменные окружения и возвращает их в детерминированном порядке.
+ *
+ * Фильтрация пропускает только пары, у которых есть определённое строковое значение; ключы, совпадающие с любым из указанных префиксов, и (опционально) `NODE_ENV` включаются в результат.
+ *
+ * @param env - Объект переменных окружения, значения могут быть `undefined`; только пары с определёнными строковыми значениями рассматриваются.
+ * @param prefixes - Список префиксов; ключ включается, если начинается с любого из этих префиксов.
+ * @param keepNodeEnv - Если `true`, ключ `NODE_ENV` будет включён в результат независимо от префиксов.
+ * @returns Объект с отфильтрованными парами ключ/значение; ключи отсортированы лексикографически с учётом числовых частей.
+ *
+ * @since 0.4.0
+ */
+function filterEnvKeys(env, prefixes, keepNodeEnv) {
+    // Типовой гвард для проверки ключа и значения.
+    const isValidEntry = (entry) => {
+        const [key, value] = entry;
+        if (value === undefined)
+            return false;
+        if (key === 'NODE_ENV')
+            return keepNodeEnv;
+        return prefixes.some(prefix => key.startsWith(prefix));
+    };
+    // Фильтрация и сортировка пар "ключ-значение", гарантирует
+    // детерминированный порядок ключей.
+    //
+    const filteredEntries = Object.entries(env)
+        .filter(isValidEntry)
+        .sort(([keyA], [keyB]) => keyA.localeCompare(keyB, 'en-US', {
+        sensitivity: 'base', // Игнорирует регистр и диакритики
+        numeric: true, // Числа в строках сравниваются как числа
+    }));
+    // Преобразует массив `[ключ, значение]` обратно в объект.
+    // Гарантирует детерминированный порядок ключей.
+    //
+    return Object.fromEntries(filteredEntries);
+}
+/**
+ * Загружает и фильтрует переменные окружения из dotenv-файлов.
+ * @param options Опции загрузки и фильтрации переменных окружения (см. {@link EnvLoaderOptions}).
+ * @returns Набор переменных окружения.
+ *
+ * @since 0.4.0
+ *
+ **/
+function loadEnv(options = {}) {
+    const { mode = process.env.NODE_ENV, prefix = [...DEFAULT_ENV_PREFIXES], cwd = process.cwd(), rootDir, envFile = '.env', keepNodeEnv = true, dotenv, } = options;
+    // Хранилище для загруженных переменных окружения.
+    let processEnv = { ...process.env };
+    const files = resolveEnvFiles({ cwd, rootDir, mode, envFile, quiet: dotenv?.quiet });
+    if (files.length > 0)
+        dotenvx.config({
+            // Переопределяемые параметры конфигурации:
+            logLevel: 'warn',
+            ignore: [
+                'MISSING_ENV_FILE',
+            ],
+            // Пользовательская конфигурация.
+            ...dotenv,
+            // Параметры, которые переопределить нельзя:
+            path: files,
+            processEnv,
+            convention: undefined,
+        });
+    // Фильтрация переменных по заданным префиксам.
+    processEnv = filterEnvKeys(processEnv, ensureCompactArray(prefix), keepNodeEnv);
+    return processEnv;
+}
+
+/**
+ * Загружает и фильтрует переменные окружения из dotenv-файлов.
+ * Используется совместно с `@rollup/plugin-replace` для замены значений в коде.
+ *
+ * @param options Опции загрузки и фильтрации переменных окружения (см. {@link EnvLoaderOptions}).
+ * @returns Объект с ключами вида `process.env.KEY` и `import.meta.env.KEY`, где `KEY` — имя переменной окружения.
+ *
+ *
+ * @since 0.4.0
+ *
+ **/
+function loadEnvReplacements(options = {}) {
+    const env = loadEnv(options);
+    const result = {};
+    for (const [key, rawValue] of Object.entries(env)) {
+        const value = JSON.stringify(rawValue);
+        result[`process.env.${key}`] = value;
+        result[`import.meta.env.${key}`] = value;
+    }
+    return result;
+}
+
+export { DEFAULT_ENV_PREFIXES, loadEnv, loadEnvReplacements };

package/package.json

@@ -1,10 +1,56 @@
 {
   "name": "@mirta/env-loader",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @mirta/env-loader",
+  "version": "0.4.1",
+  "sideEffects": false,
+  "description": "Internal dotenvx-based environment loader, used by Mirta Framework",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "mirta",
+    "env",
+    "environment",
+    "loader",
+    "dotenv",
+    "dotenvx",
+    "nodejs",
+    "utility",
+    "tooling"
+  ],
+  "license": "Unlicense",
+  "homepage": "https://github.com/wb-mirta/core#readme",
+  "bugs": {
+    "url": "https://github.com/wb-mirta/core/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wb-mirta/core.git",
+    "directory": "packages/mirta-env-loader"
+  },
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "imports": {
+    "#src": "./src/index.js",
+    "#src/*": "./src/*.js"
+  },
+  "dependencies": {
+    "@dotenvx/dotenvx": "^1.51.1",
+    "@mirta/basics": "0.4.1"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  },
+  "scripts": {
+    "build:mono": "rollup -c node:@mirta/rollup/config-package"
+  }
+}