SDK Node.js

Carga secretos directamente en una aplicación Node.js al iniciarse.

Node.js SDK

Carga secretos directamente en tu aplicación Node.js al inicio. API asíncrona con fachada de una línea o constructor fluido para control total.

Instalación

npm install @envilder/sdk

Inicio rápido: una línea

Carga secretos desde un archivo de mapeo e inyéctalos en process.env:

import { Envilder } from '@envilder/sdk';

// Resolve secrets and inject into process.env
await Envilder.load('envilder.json');

const dbPassword = process.env.DB_PASSWORD;

Resolver sin inyectar

Obtén secretos como un Map sin modificar el entorno:

import { Envilder } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
const dbPassword = secrets.get('DB_PASSWORD');

Constructor fluido con sobreescrituras

Sobreescribe la configuración del proveedor de forma programática con la API fluida:

import { Envilder, SecretProviderType } from '@envilder/sdk';

const secrets = await Envilder.fromMapFile('envilder.json')
  .withProvider(SecretProviderType.Azure)
  .withVaultUrl('https://my-vault.vault.azure.net')
  .resolve();

// Or inject directly
await Envilder.fromMapFile('envilder.json')
  .withProfile('staging')
  .inject();

Carga basada en entorno

Recomendado para aplicaciones multi-entorno. Mapea cada entorno a su archivo de secretos:

import { Envilder } from '@envilder/sdk';

const env = process.env.APP_ENV ?? 'development';

await Envilder.load(env, {
  production: 'prod-secrets.json',
  development: 'dev-secrets.json',
  test: null,  // no secrets loaded
});

Validación de secretos

Validación opcional que asegura que todos los secretos resueltos tienen valores no vacíos:

import { Envilder, validateSecrets } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
validateSecrets(secrets); // throws SecretValidationError if any value is empty

Validación del contrato del fichero de mapeo

Comprueba, sin cargar nada y sin usar ni mostrar ningún valor, que el fichero de mapeo es válido y que cada secreto declarado existe con las credenciales actuales: la misma comprobación que envilder validate. Los errores de validación esperados se devuelven en el resultado en lugar de lanzarse; un fichero de mapeo inexistente sí lanza un error. Cada clave informa exists, missing, access_denied, authentication_failed o provider_error:

Consulta la referencia de envilder validate para los estados y los permisos que necesita la comprobación →

import { Envilder } from '@envilder/sdk';

const result = await Envilder.fromMapFile('envilder.json').validateContract();
if (!result.isValid) {
  for (const error of result.mapFileErrors) {
    console.log(`${error.key}: ${error.message}`);
  }
  for (const key of result.keys.filter((k) => k.status !== 'exists')) {
    console.log(`${key.variable} (${key.path}): ${key.status}`);
  }
}

Para que la carga falle, activa la validación del contrato en el builder. La comprobación se ejecuta una vez antes de resolver y el error nombra las claves que fallan, nunca sus valores. Está desactivada por defecto, así que una carga normal no hace ninguna llamada extra al proveedor. A diferencia de la validación de secretos, que revisa los valores resueltos, revisa el fichero de mapeo y las claves antes de resolver:

await Envilder.fromMapFile('envilder.json')
  .withContractValidation()
  .inject(); // throws ContractValidationError

Proveedor propio y fakes para tests

Pasa al builder tu propia instancia de proveedor en lugar de la que construye a partir de $config. El fichero de mapeo se sigue validando igual, así que puedes probar el código de arranque con un fake en memoria, sin cuenta en la nube, emulador ni variables de entorno. Implementa también el comprobador de existencia para que la validación del contrato pueda revisar cada clave; sin él, todas las claves salen como provider_error:

import {
  Envilder,
  type ISecretExistenceChecker,
  type ISecretProvider,
} from '@envilder/sdk';

const fakeSecrets = new Map([['/app/db-url', 'postgres://localhost/test']]);

class InMemoryProvider implements ISecretProvider, ISecretExistenceChecker {
  async getSecrets(names: string[]) {
    return new Map(
      names.flatMap((name) => {
        const value = fakeSecrets.get(name);
        return value === undefined ? [] : [[name, value] as const];
      }),
    );
  }

  async checkSecretsExist(names: readonly string[]) {
    return new Map(
      names.map((name) => [
        name,
        { status: fakeSecrets.has(name) ? 'exists' : 'missing' } as const,
      ]),
    );
  }
}

await Envilder.fromMapFile('envilder.json')
  .withSecretProvider(new InMemoryProvider())
  .withContractValidation()
  .inject();

Guía completa: proveedor de secretos propio →

💡
Ejemplos ejecutables. Un proyecto Vitest con Testcontainers y un AppHost de Aspire en TypeScript que resuelven un archivo de mapeo contra AWS SSM y Azure Key Vault (emulados con LocalStack for AWS y LocalStack for Azure) y pasan los valores a los contenedores, sin ningún archivo .env: typescript-testcontainers · typescript-aspire

Documentación completa →