Secret

Secrets are under active development and are not yet stable. Breaking changes may happen between releases without warning. Feedback and bug reports are welcome via GitHub Issues .

Secrets providers resolve structured secret refs before the rest of the server starts. That lets provider config, OAuth app secrets, DSNs, and other sensitive values stay out of the main YAML file while still being injected into the final runtime config.

Configuring `providers.secrets`

Use the built-in env provider to resolve secrets from environment variables:


providers:
  secrets:
    default:
      source: env
      config:
        prefix: GESTALT_
 
server:
  encryptionKey:
    secret:
      provider: default
      name: GESTALT_ENCRYPTION_KEY

Use the built-in file provider to resolve one secret per mounted file:


providers:
  secrets:
    default:
      source: file
      config:
        dir: /run/secrets

External secret managers use the same providers.secrets.<name> shape with a package source. For package names, config fields, and auth behavior, see Config File.

Gestalt resolves structured secret refs through the configured provider before any auth provider, app provider, or datastore provider receives its config.

Building your own secrets provider

Manifest

A secrets provider manifest declares kind: secrets:


kind: secrets
source: github.com/your-org/secrets/google
version: 0.0.1
displayName: Google Secret Manager
description: Resolves secrets from Google Cloud Secret Manager.
spec:
  configSchemaPath: ./secrets_config.json

The optional spec.configSchemaPath field points to a JSON Schema that validates the config block in the server config.

Provider interface

Implement the SDK’s secrets provider surface. configure receives the provider name and config block when the entry starts. get_secret / GetSecret receives a logical secret name and returns the resolved plaintext value.

Method	Purpose
Configure	Read provider config and initialize backing clients.
Get secret	Resolve one named secret to a string value.

Go


package examplesecrets
 
import (
    "context"
    "fmt"
 
    gestalt "github.com/valon-technologies/gestalt/sdk/go"
)
 
type Provider struct {
    values map[string]string
}
 
func New() *Provider { return &Provider{values: map[string]string{}} }
 
func (p *Provider) Configure(_ context.Context, _ string, config map[string]any) error {
    values := map[string]string{}
    if raw, ok := config["values"].(map[string]any); ok {
        for name, value := range raw {
            values[name] = fmt.Sprint(value)
        }
    }
    p.values = values
    return nil
}
 
func (p *Provider) GetSecret(_ context.Context, name string) (string, error) {
    value, ok := p.values[name]
    if !ok {
        return "", fmt.Errorf("%w: %s", gestalt.ErrSecretNotFound, name)
    }
    return value, nil
}

Python


from gestalt import SecretsProvider
 
class ExampleSecrets(SecretsProvider):
    def __init__(self) -> None:
        self.values: dict[str, str] = {}
 
    def configure(self, name: str, config: dict) -> None:
        self.values = {
            str(key): str(value)
            for key, value in config.get("values", {}).items()
        }
 
    def get_secret(self, name: str) -> str:
        try:
            return self.values[name]
        except KeyError as error:
            raise KeyError(f"secret {name!r} not found") from error
 
provider = ExampleSecrets()

Rust


use std::collections::BTreeMap;
use std::sync::Mutex;
 
#[derive(Default)]
pub struct ExampleSecrets {
    values: Mutex<BTreeMap<String, String>>,
}
 
#[gestalt::async_trait]
impl gestalt::SecretsProvider for ExampleSecrets {
    async fn configure(
        &self, _name: &str, config: serde_json::Map<String, serde_json::Value>,
    ) -> gestalt::Result<()> {
        let values = config
            .get("values")
            .and_then(|value| value.as_object())
            .map(|object| {
                object
                    .iter()
                    .map(|(name, value)| {
                        (name.clone(), value.as_str().unwrap_or_default().to_string())
                    })
                    .collect()
            })
            .unwrap_or_default();
        *self.values.lock().unwrap() = values;
        Ok(())
    }
 
    async fn get_secret(&self, name: &str) -> gestalt::Result<String> {
        self.values
            .lock()
            .unwrap()
            .get(name)
            .cloned()
            .ok_or_else(|| gestalt::Error::not_found(format!("secret {name} not found")))
    }
}
 
gestalt::export_secrets_provider!(constructor = ExampleSecrets::default);

TypeScript


import { defineSecretsProvider } from "@valon-technologies/gestalt";
 
let values: Record<string, string> = {};
 
export const provider = defineSecretsProvider({
  configure(_name, config) {
    const raw = config.values;
    values =
      typeof raw === "object" && raw !== null
        ? Object.fromEntries(
            Object.entries(raw as Record<string, unknown>).map(([name, value]) => [
              name,
              String(value),
            ]),
          )
        : {};
  },
  async getSecret(name) {
    const value = values[name];
    if (value === undefined) throw new Error(`secret ${name} not found`);
    return value;
  },
});

Release flow

For packaging, lock/sync, and release behavior, see Releasing provider packages.