@nestlingjs/config.vault 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eonae
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,79 @@
+# @nestlingjs/config.vault
+
+A config source on top of HashiCorp Vault: a KV v2 secret is read with a
+single request in phase 0, and the coordinates of the storage come from
+another source — from `.env`, for example.
+
+> 🚧 Active development, the API may change.
+> Design: [`docs/en/design/config.md`](../../docs/en/design/config.md).
+> Recipe: [config sources](../../docs/en/recipes/config-sources.md).
+
+## Install
+
+```bash
+npm install @nestlingjs/config.vault zod
+```
+
+The package takes no Vault client: the request goes through the standard
+`fetch`. `zod` installs next to it: the package writes the schema of its own
+section in it, and one copy of the validator serves the package and the
+application.
+
+## Minimal example
+
+```typescript
+import { bind, defaultSources, makeApp } from '@nestlingjs/app';
+import { vault, VaultConfig } from '@nestlingjs/config.vault';
+
+export const app = makeApp({
+  features: [OrdersFeature],
+  transports: [http()],
+});
+
+await app.build().run({
+  config: [
+    bind(vault(VaultConfig, { retries: 2 }), { timeout: 3000 }),
+    ...defaultSources,
+  ],
+});
+```
+
+The order of the list is the priority of key resolution: the value from
+Vault beats the value from the environment. The order of raising is
+another one and follows on its own: `VAULT_ADDR` and `VAULT_TOKEN` are
+named by the `VaultConfig` section, so Vault is raised after `env()` and
+`dotenv('.env')`, which cover those keys.
+
+## Exports
+
+| Name | What it is |
+| --- | --- |
+| `vault` | the source: the section of coordinates first, options second |
+| `VaultConfig` | the ready section of coordinates with the `vault` prefix |
+| `VaultCoordinates` | the shape of values `vault(section)` requires |
+| `VaultOptions` | the options of the source: `retries` |
+
+The `VaultConfig` section declares `VAULT_ADDR`, `VAULT_TOKEN`
+(`secret()`), `VAULT_MOUNT` (defaults to `secret`) and `VAULT_PATH`. An
+application with two storages declares its own section of any shape that
+fits `VaultCoordinates` and passes it as the same argument: the keys take
+its prefix.
+
+`retries` is the number of extra attempts on a network failure and on a
+`5xx` answer; the pause starts at 250 ms and doubles. Answers `401`, `403`
+and `404` cause no retry. The time limit of raising is set by the binding
+with the `timeout` option.
+
+## Package boundaries
+
+There is one way to authenticate — the `X-Vault-Token` header. AppRole,
+Kubernetes and AWS are not in the package: the minimal source goes with a
+token it already has, and the way to get it stays with the environment.
+
+There is no watching of the secret: the value is read once in phase 0 and
+lives in the snapshot, like the value of any source. Dynamic secrets and
+lease renewal are not supported — a rotated secret reaches the process on
+a restart.
+
+One engine is read — KV v2 at the `{mount}/data/{path}` path. A KV v1
+answer fails the raise: it carries no `data.data` record.

package/README.ru.md

@@ -0,0 +1,77 @@
+# @nestlingjs/config.vault
+
+Источник конфигурации поверх HashiCorp Vault: секрет KV v2 читается одним
+запросом на фазе 0, а координаты хранилища приходят из другого источника —
+например из `.env`.
+
+> 🚧 Активная разработка, API может меняться.
+> Дизайн: [`docs/design/config.md`](../../docs/design/config.md).
+> Рецепт: [источники конфигурации](../../docs/recipes/config-sources.md).
+
+## Установка
+
+```bash
+npm install @nestlingjs/config.vault zod
+```
+
+Клиента Vault пакет не берёт: запрос идёт штатным `fetch`. Рядом ставится
+`zod`: схему своей секции пакет пишет им, и копия валидатора у него и у
+приложения одна.
+
+## Минимальный пример
+
+```typescript
+import { bind, defaultSources, makeApp } from '@nestlingjs/app';
+import { vault, VaultConfig } from '@nestlingjs/config.vault';
+
+export const app = makeApp({
+  features: [OrdersFeature],
+  transports: [http()],
+});
+
+await app.build().run({
+  config: [
+    bind(vault(VaultConfig, { retries: 2 }), { timeout: 3000 }),
+    ...defaultSources,
+  ],
+});
+```
+
+Порядок списка — приоритет разрешения ключа: значение из Vault побеждает
+значение из окружения. Очерёдность подъёма другая и выводится сама:
+`VAULT_ADDR` и `VAULT_TOKEN` называет секция `VaultConfig`, поэтому Vault
+поднимается после `env()` и `dotenv('.env')`, которые эти ключи покрывают.
+
+## Экспорты
+
+| Имя | Что это |
+| --- | --- |
+| `vault` | источник: секция координат аргументом, опции — вторым |
+| `VaultConfig` | готовая секция координат с префиксом `vault` |
+| `VaultCoordinates` | форма значений, которую требует `vault(section)` |
+| `VaultOptions` | опции источника: `retries` |
+
+Секция `VaultConfig` объявляет `VAULT_ADDR`, `VAULT_TOKEN` (`secret()`),
+`VAULT_MOUNT` (умолчание `secret`) и `VAULT_PATH`. Приложение с двумя
+хранилищами объявляет свою секцию любой формы, подходящей под
+`VaultCoordinates`, и передаёт её тем же аргументом: ключи получат её
+префикс.
+
+`retries` — число дополнительных попыток при сетевом отказе и ответе
+`5xx`; пауза начинается с 250 мс и удваивается. Ответы `401`, `403` и
+`404` повтора не вызывают. Границу времени подъёма задаёт привязка опцией
+`timeout`.
+
+## Границы пакета
+
+Аутентификация одна — заголовок `X-Vault-Token`. AppRole, Kubernetes и
+AWS в пакет не входят: минимальный источник ходит с готовыми учётными
+данными, а способ их получить остаётся за стендом.
+
+Наблюдения за секретом нет: значение читается один раз на фазе 0 и живёт
+в снимке, как у любого источника. Динамические секреты и продление аренды
+пакет не поддерживает — обновление секрета доходит до процесса
+перезапуском.
+
+Движок читается один — KV v2 по пути `{mount}/data/{path}`. Ответ KV v1
+отказывает подъём: у него нет рекорда `data.data`.

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Секция координат хранилища и её форма.
+ *
+ * Секция передаётся источнику аргументом, а не берётся им из себя: связь
+ * «источник ↔ его координаты» видна в строке вызова. `VaultConfig` —
+ * готовая секция на обычный случай; приложение с двумя хранилищами
+ * объявляет свою секцию любой формы, подходящей под {@link VaultCoordinates}.
+ */
+import type { ConfigSectionToken } from '@nestlingjs/app';
+/**
+ * Значения, которые источник берёт из секции.
+ *
+ * Тип ограничивает аргумент {@link vault}: секция без адреса или без пути
+ * не компилируется, а секция с лишними полями годится — источник читает
+ * только эти четыре.
+ */
+export interface VaultCoordinates {
+    /** Адрес сервера: `https://vault.internal:8200` */
+    readonly addr: string;
+    /** Учётные данные: уходят заголовком `X-Vault-Token` */
+    readonly token: string;
+    /** Точка монтирования движка KV v2 */
+    readonly mount: string;
+    /** Путь секрета внутри точки монтирования */
+    readonly path: string;
+}
+/**
+ * Секция координат: `VAULT_ADDR`, `VAULT_TOKEN`, `VAULT_MOUNT`, `VAULT_PATH`.
+ *
+ * Поле `token` объявлено `secret()`, поэтому его значение не попадает ни в
+ * снимок реестра, ни в диагностику. Точка монтирования по умолчанию — `secret`,
+ * то есть движок KV, который Vault поднимает сам.
+ *
+ * @example
+ * ```typescript
+ * await app.build().run({
+ *   config: [bind(vault(VaultConfig)), ...defaultSources],
+ * });
+ * ```
+ */
+export declare const VaultConfig: ConfigSectionToken<VaultCoordinates, 'vault'>;

package/dist/config.js

@@ -0,0 +1,28 @@
+/**
+ * Секция координат хранилища и её форма.
+ *
+ * Секция передаётся источнику аргументом, а не берётся им из себя: связь
+ * «источник ↔ его координаты» видна в строке вызова. `VaultConfig` —
+ * готовая секция на обычный случай; приложение с двумя хранилищами
+ * объявляет свою секцию любой формы, подходящей под {@link VaultCoordinates}.
+ */ import { makeConfig, secret } from '@nestlingjs/app';
+import { z } from 'zod';
+/**
+ * Секция координат: `VAULT_ADDR`, `VAULT_TOKEN`, `VAULT_MOUNT`, `VAULT_PATH`.
+ *
+ * Поле `token` объявлено `secret()`, поэтому его значение не попадает ни в
+ * снимок реестра, ни в диагностику. Точка монтирования по умолчанию — `secret`,
+ * то есть движок KV, который Vault поднимает сам.
+ *
+ * @example
+ * ```typescript
+ * await app.build().run({
+ *   config: [bind(vault(VaultConfig)), ...defaultSources],
+ * });
+ * ```
+ */ export const VaultConfig = makeConfig('vault', {
+    addr: z.url(),
+    token: secret(z.string()),
+    mount: z.string().default('secret'),
+    path: z.string()
+});

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@nestlingjs/config.vault`: источник конфигурации поверх HashiCorp Vault.
+ *
+ * Барель перечисляет имена поимённо, а не через `export *`. Наружу выходят
+ * источник, готовая секция координат и два типа — остальное остаётся
+ * внутренним, и менять его можно без ломающей правки для тех, кто
+ * установил пакет.
+ */
+export { VaultConfig } from './config.js';
+export type { VaultCoordinates } from './config.js';
+export { vault } from './source.js';
+export type { VaultOptions } from './source.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@nestlingjs/config.vault`: источник конфигурации поверх HashiCorp Vault.
+ *
+ * Барель перечисляет имена поимённо, а не через `export *`. Наружу выходят
+ * источник, готовая секция координат и два типа — остальное остаётся
+ * внутренним, и менять его можно без ломающей правки для тех, кто
+ * установил пакет.
+ */ // ./config.js — 2
+export { VaultConfig } from './config.js';
+// ./source.js — 2
+export { vault } from './source.js';

package/dist/source.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Источник конфигурации поверх Vault: секрет KV v2 читается одним запросом
+ * на фазе 0.
+ *
+ * Координаты приходят значениями секции, объявленной в `needs`, поэтому
+ * читалка поднимает Vault после источников, которые эти ключи покрывают.
+ * Запрос идёт штатным `fetch` — клиента Vault в зависимостях пакета нет.
+ */
+import type { VaultCoordinates } from './config.js';
+import type { ConfigSectionToken, ConfigSource } from '@nestlingjs/app';
+/** Опции {@link vault} */
+export interface VaultOptions {
+    /**
+     * Число дополнительных попыток при сетевом отказе и ответе `5xx`.
+     *
+     * Умолчание `0` — попытка одна. Пауза перед первым повтором 250 мс и
+     * дальше удваивается. Ответы `401`, `403` и `404` повтора не вызывают:
+     * сами они не проходят. Границу времени подъёма задаёт привязка опцией
+     * `timeout`, а не источник.
+     */
+    readonly retries?: number;
+}
+/**
+ * Источник значений из секрета Vault.
+ *
+ * Секция координат приходит аргументом: `vault(VaultConfig)` берёт готовую
+ * секцию пакета, а приложение с двумя хранилищами объявляет свою секцию
+ * любой формы, подходящей под `VaultCoordinates`. Она же становится полем
+ * `needs` источника, поэтому фаза 0 поднимает Vault после источников,
+ * покрывающих её ключи.
+ *
+ * `init()` делает один запрос `GET {addr}/v1/{mount}/data/{path}` с
+ * заголовком `X-Vault-Token` и запоминает рекорд `data.data`. Дальше
+ * `get(key)` читает из этого рекорда, не обращаясь к сети.
+ *
+ * @param section - DI-токен секции координат
+ * @param options - Число повторов при временном отказе
+ * @returns Источник для `bind()`
+ *
+ * @example
+ * ```typescript
+ * await app.build().run({
+ *   config: [
+ *     bind(vault(VaultConfig, { retries: 2 }), { timeout: 3000 }),
+ *     ...defaultSources,
+ *   ],
+ * });
+ * ```
+ */
+export declare const vault: <T extends VaultCoordinates>(section: ConfigSectionToken<T>, options?: VaultOptions) => ConfigSource<T>;

package/dist/source.js

@@ -0,0 +1,128 @@
+/**
+ * Источник конфигурации поверх Vault: секрет KV v2 читается одним запросом
+ * на фазе 0.
+ *
+ * Координаты приходят значениями секции, объявленной в `needs`, поэтому
+ * читалка поднимает Vault после источников, которые эти ключи покрывают.
+ * Запрос идёт штатным `fetch` — клиента Vault в зависимостях пакета нет.
+ */ /** Пауза перед первым повтором, мс; перед каждым следующим удваивается */ const FIRST_RETRY_DELAY = 250;
+/**
+ * Отказ запроса к Vault.
+ *
+ * Флаг `retryable` отделяет временное от постоянного: повторяются сетевой
+ * отказ и `5xx`, а отказ прав или отсутствие секрета сами не пройдут.
+ */ let VaultRequestError = class VaultRequestError extends Error {
+    retryable;
+    constructor(message, /** Отказ временный: повтор имеет смысл */ retryable, cause){
+        super(message, cause === undefined ? undefined : {
+            cause
+        }), this.retryable = retryable;
+        this.name = 'VaultRequestError';
+    }
+};
+/** Адрес секрета KV v2; лишние слэши адреса отбрасываются */ const secretUrl = (coordinates)=>`${coordinates.addr.replaceAll(/\/+$/g, '')}/v1/${coordinates.mount}/data/${coordinates.path}`;
+/**
+ * Хранилище в тексте отказа: адрес, точка монтирования и путь.
+ *
+ * Учётных данных здесь нет и не будет: ошибка старта попадает в лог
+ * целиком.
+ */ const describeTarget = (coordinates)=>`Vault at ${coordinates.addr} (mount '${coordinates.mount}', path '${coordinates.path}')`;
+/** Что означает ответ, который сам по себе не пройдёт */ const explainStatus = (status)=>{
+    if (status === 401 || status === 403) {
+        return `: the token is not allowed to read this path`;
+    }
+    if (status === 404) {
+        return `: there is no secret at this path, or the mount is another one`;
+    }
+    return '';
+};
+const sleep = (ms)=>new Promise((resolve)=>{
+        setTimeout(resolve, ms);
+    });
+/** Один запрос секрета: рекорд `data.data` ответа или отказ */ const requestSecret = async (coordinates)=>{
+    const target = describeTarget(coordinates);
+    let response;
+    try {
+        response = await fetch(secretUrl(coordinates), {
+            headers: {
+                'X-Vault-Token': coordinates.token
+            }
+        });
+    } catch (error) {
+        throw new VaultRequestError(`${target} is unreachable`, true, error);
+    }
+    if (!response.ok) {
+        throw new VaultRequestError(`${target} answered ${response.status}${explainStatus(response.status)}`, response.status >= 500);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    } catch (error) {
+        throw new VaultRequestError(`${target} answered with a body that is not JSON`, false, error);
+    }
+    const data = payload.data?.data;
+    if (!data) {
+        throw new VaultRequestError(`${target} answered without 'data.data': the path holds no secret, or the mount runs the KV v1 engine`, false);
+    }
+    return data;
+};
+/**
+ * Читает секрет, повторяя временные отказы.
+ *
+ * Повтор принадлежит источнику, а не ядру: ядру нечем отличить временный
+ * отказ от постоянного, а источник знает свой протокол.
+ */ const readSecret = async (coordinates, retries)=>{
+    let delay = FIRST_RETRY_DELAY;
+    for(let attempt = 0;; attempt += 1){
+        try {
+            return await requestSecret(coordinates);
+        } catch (error) {
+            if (attempt >= retries || !(error instanceof VaultRequestError)) {
+                throw error;
+            }
+            if (!error.retryable) {
+                throw error;
+            }
+            await sleep(delay);
+            delay *= 2;
+        }
+    }
+};
+/**
+ * Источник значений из секрета Vault.
+ *
+ * Секция координат приходит аргументом: `vault(VaultConfig)` берёт готовую
+ * секцию пакета, а приложение с двумя хранилищами объявляет свою секцию
+ * любой формы, подходящей под `VaultCoordinates`. Она же становится полем
+ * `needs` источника, поэтому фаза 0 поднимает Vault после источников,
+ * покрывающих её ключи.
+ *
+ * `init()` делает один запрос `GET {addr}/v1/{mount}/data/{path}` с
+ * заголовком `X-Vault-Token` и запоминает рекорд `data.data`. Дальше
+ * `get(key)` читает из этого рекорда, не обращаясь к сети.
+ *
+ * @param section - DI-токен секции координат
+ * @param options - Число повторов при временном отказе
+ * @returns Источник для `bind()`
+ *
+ * @example
+ * ```typescript
+ * await app.build().run({
+ *   config: [
+ *     bind(vault(VaultConfig, { retries: 2 }), { timeout: 3000 }),
+ *     ...defaultSources,
+ *   ],
+ * });
+ * ```
+ */ export const vault = (section, options = {})=>{
+    const retries = options.retries ?? 0;
+    let values = {};
+    return {
+        name: `vault(${section.keys.prefix})`,
+        needs: section,
+        init: async (coordinates)=>{
+            values = await readSecret(coordinates, retries);
+        },
+        get: (key)=>values[key]
+    };
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@nestlingjs/config.vault",
+  "version": "0.4.0",
+  "description": "Источник конфигурации поверх HashiCorp Vault: секрет KV v2 читается на фазе 0 по координатам из другой секции",
+  "keywords": [
+    "nestling",
+    "typescript",
+    "esm",
+    "config",
+    "vault",
+    "secrets"
+  ],
+  "license": "MIT",
+  "author": "eonae",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eonae/nestling.git",
+    "directory": "packages/nestling.config.vault"
+  },
+  "homepage": "https://github.com/eonae/nestling/tree/main/packages/nestling.config.vault#readme",
+  "bugs": {
+    "url": "https://github.com/eonae/nestling/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clear": "rm -rf dist",
+    "vault:up": "docker compose up -d --wait",
+    "vault:down": "docker compose down -v",
+    "typecheck": "run -T tsc -p tsconfig.json",
+    "build": "node ../../scripts/build-package.mjs",
+    "lint": "run -T eslint .",
+    "lint:fix": "yarn run lint --fix",
+    "test": "run -T vitest run"
+  },
+  "dependencies": {
+    "@nestlingjs/app": "0.4.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "5.7.3",
+    "zod": "^4.0.0"
+  }
+}