envsec

Безопасное управление секретами окружения с использованием встроенных хранилищ учётных данных ОС.

Демо

Возможности

• Хранение секретов во встроенном хранилище учётных данных ОС (а не в текстовых файлах)
• Кроссплатформенность: macOS, Linux, Windows
• Организация секретов по контекстам (например, myapp.dev, stripe-api.prod, work.staging)
• Отслеживание метаданных секретов (имена ключей, временные метки) через SQLite
• Поиск контекстов и секретов с помощью glob-шаблонов
• Запуск команд с подстановкой секретов
• Сохранение и повторный запуск команд с помощью cmd (поиск, список, запуск, удаление)
• Экспорт секретов в файлы .env (с отслеживанием генерации через audit)
• Экспорт секретов в виде переменных окружения оболочки (eval $(envsec env))
• Загрузка секретов из файлов .env (с обнаружением конфликтов)
• Обмен секретами, зашифрованными с помощью GPG, для членов команды
• Интерактивный терминальный интерфейс (envsec tui) для управления секретами без запоминания команд

Пакеты

Это монорепозиторий, содержащий следующие пакеты:

Пакет	Описание	npm
envsec	CLI-инструмент для управления секретами
@envsec/sdk	SDK для Node.js / Bun для программной загрузки секретов
@envsec/core	Ядро — адаптеры хранилища учётных данных ОС + база метаданных
@envsec/tui	Интерактивный терминальный интерфейс для управления секретами

Быстрый старт с SDK

Для программного доступа к секретам из Node.js или Bun используйте @envsec/sdk:

npm install @envsec/sdk

import { loadSecrets } from "@envsec/sdk";

// Load and inject into process.env
await loadSecrets({ context: "myapp.dev", inject: true });

// Or use the client for full control
import { EnvsecClient } from "@envsec/sdk";
const client = await EnvsecClient.create({ context: "myapp.dev" });
const apiKey = await client.get("api.key");
await client.close();

Полную документацию SDK со всеми API, поддержкой нескольких контекстов и опциями см. в соответствующем разделе.

Требования

• Node.js >= 22

macOS

Дополнительные зависимости не требуются. Используется встроенная связка ключей через CLI-утилиту security.

Linux

Требуется libsecret-tools (предоставляет команду secret-tool), которая взаимодействует с GNOME Keyring, KDE Wallet или любым провайдером Secret Service API через D-Bus.

# Debian / Ubuntu
sudo apt install libsecret-tools

# Fedora
sudo dnf install libsecret

# Arch
sudo pacman -S libsecret

Для работы требуется активный сеанс D-Bus и демон keyring (например, gnome-keyring-daemon). В большинстве окружений рабочего стола это обрабатывается автоматически.

Windows

Дополнительные зависимости не требуются. Используется встроенный Windows Credential Manager через cmdkey и PowerShell.

Установка

Homebrew (macOS / Linux)

brew tap davidnussio/homebrew-tap
brew install envsec

npm

npm install -g envsec

npx (без установки)

npx envsec

mise

mise use -g npm:envsec

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

Большинство команд требуют указания контекста через --context (или -c). Контекст — это произвольная метка для группировки секретов, например myapp.dev, stripe-api.prod, work.staging.

Глобальные параметры

Эти параметры доступны для всех команд:

• --context, -c — Имя контекста (например, myapp.dev, stripe-api.prod). Также читает переменную окружения ENVSEC_CONTEXT
• --debug, -d — Включить отладочное логирование
• --json — Вывод в формате JSON для скриптов
• --db — Путь к файлу базы данных SQLite (по умолчанию: ~/.envsec/store.sqlite). Также читает переменную окружения ENVSEC_DB

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

По умолчанию метаданные хранятся в ~/.envsec/store.sqlite. Вы можете переопределить это с помощью --db или переменной окружения ENVSEC_DB:

# Use a project-local database
envsec --db ./local-store.sqlite -c myapp.dev list

# Or via environment variable
export ENVSEC_DB=/shared/team/envsec.sqlite
envsec -c myapp.dev list

Флаг --db имеет приоритет над ENVSEC_DB. Варианты использования включают базы данных для отдельных проектов, общие базы данных команды на сетевых дисках и CI/CD с эфемерным хранилищем.

Добавить секрет

Сохранить секрет в хранилище учётных данных ОС.

• <key> — Имя ключа секрета (например, api.key, db.password)
• --value, -v — Значение для сохранения (опустите для интерактивного скрытого ввода)
• --expires, -e — Срок действия (например, 30m, 2h, 7d, 4w, 3mo, 1y)

# Store a value inline
envsec -c myapp.dev add api.key --value "sk-abc123"

# Or use the short alias
envsec -c myapp.dev add api.key -v "sk-abc123"

# Omit --value for an interactive masked prompt
envsec -c myapp.dev add api.key

# Set an expiry duration with --expires (-e)
envsec -c myapp.dev add api.key -v "sk-abc123" --expires 30d

# Supported duration units: m (minutes), h (hours), d (days), w (weeks), mo (months), y (years)
# Combinable: 1y6mo, 2w3d, 1d12h
envsec -c myapp.dev add api.key -v "sk-abc123" -e 6mo

Получить секрет

Извлечь значение секрета из хранилища учётных данных ОС.

• <key> — Имя ключа секрета для извлечения
• --quiet, -q — Выводить только необработанное значение (без предупреждений и лишнего вывода)
• --json — Вывод в формате JSON (включает context, key, value, expires_at)

envsec -c myapp.dev get api.key

# Print only the raw value (no warnings or extra output)
envsec -c myapp.dev get api.key --quiet
envsec -c myapp.dev get api.key -q

Удаление секрета

Удалить секрет из хранилища учётных данных ОС.

• <key> — Имя ключа секрета для удаления (необязательно, если используется --all)
• --yes, -y — Пропустить запрос подтверждения
• --all — Удалить все секреты в контексте

envsec -c myapp.dev delete api.key

# or use the alias
envsec -c myapp.dev del api.key

Переименование секрета

Переименование ключа секрета в том же контексте. Значение и метаданные срока действия сохраняются.

• <old-key> — Текущее имя ключа секрета
• <new-key> — Новое имя ключа секрета
• --force, -f — Перезаписать целевой объект, если он уже существует

# Rename a key
envsec -c myapp.dev rename old.key new.key

# Overwrite target if it already exists
envsec -c myapp.dev rename old.key existing.key --force

Список всех секретов в контексте

Выводит список всех ключей секретов и метаданных в контексте.

• --json — Вывод в формате JSON

envsec -c myapp.dev list

Список всех контекстов

Выводит список всех доступных контекстов с количеством секретов.

• --json — Вывод в формате JSON

# Without --context, lists all available contexts with secret counts
envsec list

Поиск секретов

Поиск секретов или контекстов с использованием glob-шаблонов.

• <pattern> — Glob-шаблон для поиска (например, api.*, myapp.*)
• --json — Вывод в формате JSON