Proveedor de secretos propio
¿Cómo usas Envilder con un almacén de secretos que no soporta, o pruebas el código de arranque sin cuenta en la nube? En los SDKs, pasa tu propio proveedor al builder. El fichero de mapeo, la validación del contrato y la inyección funcionan igual que con AWS SSM o Azure Key Vault.
Cuándo usarlo
Un proveedor propio sustituye el cliente de AWS o Azure que el SDK construiría a partir de $config. Dos motivos habituales:
- Tus secretos están en un almacén que Envilder aún no soporta (HashiCorp Vault, 1Password, una base de datos, una API interna).
- Quieres probar el código de arranque con un fake en memoria: sin cuenta en la nube, sin emulador y sin variables de entorno.
Solo los SDKs (1.2+) aceptan un proveedor propio. El CLI y la GitHub Action soportan AWS SSM y Azure Key Vault.
Cómo funciona
Un proveedor implementa una interfaz y, opcionalmente, una segunda para la validación del contrato:
| Interfaz | Método (Node.js · Python · .NET) | Para qué sirve |
|---|---|---|
ISecretProvider | getSecrets · get_secret · GetSecret | Resolver los valores que se inyectan. Los secretos que faltan se omiten, no lanzan ningún error. |
ISecretExistenceChecker | checkSecretsExist · check_secrets_exist · CheckSecretsExistAsync | Opcional. Validación del contrato: responder exists o missing para cada clave sin leer ningún valor. |
Pasa la instancia con withSecretProvider() (with_secret_provider() en Python, WithSecretProvider() en .NET). El SDK ya no construye ningún proveedor a partir de $config, pero sigue validando el fichero de mapeo, así que un error en el fichero que la app usa en producción también falla en los tests que usan un fake.
Ejemplo
Un proveedor en memoria que implementa las dos interfaces, conectado a una carga con validación del contrato:
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();from envilder import (
Envilder,
ISecretExistenceChecker,
ISecretProvider,
SecretExistence,
SecretExistenceStatus,
)
FAKE_SECRETS = {'/app/db-url': 'postgres://localhost/test'}
class InMemoryProvider(ISecretProvider, ISecretExistenceChecker):
def get_secret(self, name):
return FAKE_SECRETS.get(name)
def check_secrets_exist(self, names):
return {
name: SecretExistence(
SecretExistenceStatus.EXISTS
if name in FAKE_SECRETS
else SecretExistenceStatus.MISSING
)
for name in names
}
(
Envilder.from_map_file('envilder.json')
.with_secret_provider(InMemoryProvider())
.with_contract_validation()
.inject()
)using Envilder;
using Envilder.Domain.Ports;
await Env.FromMapFile("envilder.json")
.WithSecretProvider(new InMemoryProvider())
.WithContractValidation()
.InjectAsync();
public sealed class InMemoryProvider : ISecretProvider, ISecretExistenceChecker
{
private readonly Dictionary<string, string> _secrets = new()
{
["/app/db-url"] = "Server=localhost;Database=test",
};
public string? GetSecret(string name) => _secrets.GetValueOrDefault(name);
public Task<string?> GetSecretAsync(string name, CancellationToken ct = default)
=> Task.FromResult(GetSecret(name));
public Task<IReadOnlyDictionary<string, SecretExistence>> CheckSecretsExistAsync(
IReadOnlyCollection<string> names, CancellationToken ct)
=> Task.FromResult<IReadOnlyDictionary<string, SecretExistence>>(names.ToDictionary(
name => name,
name => new SecretExistence(_secrets.ContainsKey(name)
? SecretExistenceStatus.Exists
: SecretExistenceStatus.Missing)));
}Validación del contrato con un proveedor propio
- Si el proveedor implementa ISecretExistenceChecker, validateContract() y withContractValidation() comprueban cada clave con él, como con los proveedores incluidos.
- Si no, todas las claves salen como provider_error ("The provider cannot check whether a secret exists."), y una carga con validación del contrato falla en lugar de pasar en silencio.
- El campo provider de cada clave mantiene el tipo configurado: el override de withProvider(), luego $config.provider y, si no, aws.
Consulta la referencia de envilder validate para todos los estados →
Ejemplos ejecutables
envilder-examples tiene un ejemplo por SDK: un proveedor sobre un fichero local cifrado con AES-256-GCM, con tests de carga, de fallo en el arranque cuando falta un secreto y de validación del contrato sin descifrar nada.