Proveïdor de secrets propi

Com pots fer servir Envilder amb un magatzem de secrets que no suporta, o provar el codi d'arrencada sense compte al núvol? Als SDKs, passa el teu propi proveïdor al builder. El fitxer de mapatge, la validació del contracte i la injecció funcionen igual que amb AWS SSM o Azure Key Vault.

Quan fer-lo servir

Un proveïdor propi substitueix el client d'AWS o Azure que l'SDK construiria a partir de $config. Dos motius habituals:

  • Els teus secrets són en un magatzem que Envilder encara no suporta (HashiCorp Vault, 1Password, una base de dades, una API interna).
  • Vols provar el codi d'arrencada amb un fake en memòria: sense compte al núvol, sense emulador i sense variables d'entorn.

Només els SDKs (1.2+) accepten un proveïdor propi. El CLI i la GitHub Action suporten AWS SSM i Azure Key Vault.

Com funciona

Un proveïdor implementa una interfície i, opcionalment, una segona per a la validació del contracte:

InterfícieMètode (Node.js · Python · .NET)Per a què serveix
ISecretProvidergetSecrets · get_secret · GetSecretResoldre els valors que s'injecten. Els secrets que falten s'ometen, no llancen cap error.
ISecretExistenceCheckercheckSecretsExist · check_secrets_exist · CheckSecretsExistAsyncOpcional. Validació del contracte: respondre exists o missing per a cada clau sense llegir cap valor.

Passa la instància amb withSecretProvider() (with_secret_provider() a Python, WithSecretProvider() a .NET). L'SDK ja no construeix cap proveïdor a partir de $config, però continua validant el fitxer de mapatge, així que un error al fitxer que l'app fa servir a producció també falla als tests que fan servir un fake.

Exemple

Un proveïdor en memòria que implementa les dues interfícies, connectat a una càrrega amb validació del contracte:

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ó del contracte amb un proveïdor propi

  • Si el proveïdor implementa ISecretExistenceChecker, validateContract() i withContractValidation() hi comproven cada clau, com amb els proveïdors inclosos.
  • Si no, totes les claus surten com a provider_error ("The provider cannot check whether a secret exists."), i una càrrega amb validació del contracte falla en lloc de passar en silenci.
  • El camp provider de cada clau manté el tipus configurat: l'override de withProvider(), després $config.provider i, si no, aws.

Consulta la referència d'envilder validate per a tots els estats →

Exemples executables

envilder-examples té un exemple per SDK: un proveïdor sobre un fitxer local xifrat amb AES-256-GCM, amb tests de càrrega, de fallada a l'arrencada quan falta un secret i de validació del contracte sense desxifrar res.