config

Documentation

Overview

Package config implements the Viper-backed configuration loader for Orjanda. It reads orjanda.yaml and ORJANDA_-prefixed environment variables and deserialises them into strongly-typed Config structs.

See TAD §1.3 for the configuration schema.

Index

• Constants
• func GenerateDevJWTSecret() string
• func ValidateJWTSecret(secret string) error
• type AuthConfig
• type Config
  • func Load(cfgFile string) (*Config, string, error)
• type DatabaseConfig
• type LLMConfig
• type LLMProviderConfig
• type LLMSafetyConfig
• type ServerConfig

Constants

const (
	// EnvDevelopment is the default environment. It is the local-first
	// configuration: forgiving Registry compile (warn-and-continue), missing
	// tables auto-created, an ephemeral JWT secret generated when none is
	// configured, and an admin bootstrapped on first run.
	EnvDevelopment = "development"

	// EnvProduction is the fail-fast environment: any Registry error, pending
	// schema migration, or stale committed frontend codegen aborts startup,
	// and a valid persistent auth.jwt_secret is mandatory.
	EnvProduction = "production"

	// EnvDefault is the value used when neither the env config key nor
	// ORJANDA_ENV is set. Development matches the framework's dev-first model:
	// the former `orjanda serve` command was always a dev server, a bare
	// application binary still defaults to serving (cli/main.go), and the
	// scaffolded orjanda.yaml ships dev defaults. Production is explicit
	// opt-in via ORJANDA_ENV=production, exactly as it used to be explicit
	// opt-in via the former `orjanda bench` command.
	EnvDefault = EnvDevelopment
)

Deployment environments. Only these two values are accepted for the "env" config key / ORJANDA_ENV environment variable (TAD §16).

const MinJWTSecretLength = 32

MinJWTSecretLength is the minimum accepted length for auth.jwt_secret. HS256 signing keys shorter than this offer negligible forgery resistance.

Functions

func GenerateDevJWTSecret

func GenerateDevJWTSecret() string

GenerateDevJWTSecret returns a cryptographically random signing key of at least MinJWTSecretLength bytes (base64-URL encoded), intended only for ephemeral local development secrets.

func ValidateJWTSecret

func ValidateJWTSecret(secret string) error

ValidateJWTSecret returns an error unless secret is a strong JWT signing key. It rejects empty and short values so a misconfigured site fails fast instead of silently operating with a guessable key (see TAD §1.3, PRD §15.1).

Types

type AuthConfig

type AuthConfig struct {
	// JWTSecret is the HMAC-SHA256 signing key for access and refresh JWTs.
	// It is required: at least MinJWTSecretLength characters, supplied via
	// orjanda.yaml (auth.jwt_secret) or the ORJANDA_AUTH_JWT_SECRET
	// environment variable. There is deliberately no default — a derived or
	// hardcoded default key would let anyone forge administrator tokens
	// (REVIEW-2026-08-12 finding 1).
	JWTSecret string `mapstructure:"jwt_secret"`
}

AuthConfig holds authentication and token signing settings.

type Config

type Config struct {
	// Env selects the deployment environment: EnvDevelopment or EnvProduction.
	// Default: EnvDevelopment. Set via orjanda.yaml (env) or ORJANDA_ENV.
	Env      string         `mapstructure:"env"`
	Server   ServerConfig   `mapstructure:"server"`
	Database DatabaseConfig `mapstructure:"database"`
	Auth     AuthConfig     `mapstructure:"auth"`
	LLM      LLMConfig      `mapstructure:"llm"`
}

Config is the root configuration object. It is populated by Load() from orjanda.yaml and/or ORJANDA_-prefixed environment variables. Struct tags bind the fields to Viper keys; env-var names are derived by uppercasing the key and replacing dots/underscores as needed.

See TAD §1.3 for the authoritative schema.

func Load

func Load(cfgFile string) (*Config, string, error)

Load reads configuration from the supplied file path (pass "" to automatically discover orjanda.yaml in the current directory, or skip the file and rely on defaults + environment variables if not found) and from ORJANDA_-prefixed environment variables, which override file values.

When cfgFile is empty, Load first checks for "./orjanda.yaml" in the current working directory and loads it if present. This matches the behavior expected after `orjanda init`, which generates an orjanda.yaml in the app directory. An explicit --config flag takes precedence over automatic discovery.

Environment variable names are derived from Viper keys by uppercasing and replacing dots with underscores, then prepending "ORJANDA_". For example, the key "llm.providers.openai.api_key" maps to ORJANDA_LLM_PROVIDERS_OPENAI_API_KEY. The env key maps to ORJANDA_ENV.

The deployment environment (env / ORJANDA_ENV) decides how the JWT signing secret is handled (TAD §16):

• development: a missing or too-short auth.jwt_secret is tolerated — a fresh random secret is generated in its place and returned as the second result. The generated secret is ephemeral; tokens signed with it are invalidated on restart, which is acceptable for local development but never for production. When the configured secret is already valid, the returned string is "".
• production: a missing or too-short auth.jwt_secret is a hard error and no secret is generated.

Load satisfies the Phase 0 completion criterion:

• Correctly parses the example orjanda.yaml from TAD §1.3.
• Env-var override verified for at least one nested key (ORJANDA_OPENAI_API_KEY maps to llm.providers.openai.api_key).

type DatabaseConfig

type DatabaseConfig struct {
	// Driver selects the database dialect. Must be "postgres" or "sqlite".
	Driver string `mapstructure:"driver"`

	// DSN is the connection string passed to the underlying driver.
	DSN string `mapstructure:"dsn"`

	// MaxOpenConns is the maximum number of open connections in the pool.
	// Default: 25.
	MaxOpenConns int `mapstructure:"max_open_conns"`

	// MaxIdleConns is the maximum number of idle connections in the pool.
	// Default: 5.
	MaxIdleConns int `mapstructure:"max_idle_conns"`
}

DatabaseConfig holds database connection settings.

type LLMConfig

type LLMConfig struct {
	// DefaultProvider is the key into Providers to use when no explicit
	// provider is specified. Default: "openai".
	DefaultProvider string `mapstructure:"default_provider"`

	// Providers maps provider names (e.g. "openai", "anthropic") to their
	// individual settings.
	Providers map[string]LLMProviderConfig `mapstructure:"providers"`

	// Safety holds agent safety-related limits.
	Safety LLMSafetyConfig `mapstructure:"safety"`
}

LLMConfig holds large-language-model provider settings.

type LLMProviderConfig

type LLMProviderConfig struct {
	// APIKey is the provider's secret API key.
	// Loaded from the environment via e.g. ORJANDA_LLM_PROVIDERS_OPENAI_API_KEY
	// or the ${ORJANDA_OPENAI_API_KEY} interpolation in orjanda.yaml.
	APIKey string `mapstructure:"api_key"`

	// Model is the model identifier to use (e.g. "gpt-4o").
	Model string `mapstructure:"model"`

	// MaxTokens caps the number of tokens per LLM completion request.
	// Default: 4096.
	MaxTokens int `mapstructure:"max_tokens"`

	// BaseURL overrides the provider endpoint. Required for
	// "openai_compatible"; empty means the provider's official default
	// endpoint (TAD §1.3).
	BaseURL string `mapstructure:"base_url"`

	// Auth selects the provider authentication mode: "bearer" (always send
	// the Authorization: Bearer header), "bearer_if_key" (only when api_key
	// is set), or "none" (never). Empty means the provider default.
	// Honored by the OpenAI and openai_compatible adapters (TAD §1.3).
	Auth string `mapstructure:"auth"`

	// ToolCalling and StructuredOutput override the adapter's capability
	// report; OpenAI-compatible servers vary in support, so a self-hosted
	// endpoint can disable a feature it lacks. nil = adapter default.
	ToolCalling      *bool `mapstructure:"tool_calling"`
	StructuredOutput *bool `mapstructure:"structured_output"`
}

LLMProviderConfig holds the per-provider LLM settings.

type LLMSafetyConfig

type LLMSafetyConfig struct {
	// MaxBulkOperations is the number of records above which a bulk agent
	// operation always requires human approval (TAD §12.1 step 2).
	// Default: 5. This default is non-configurable to "always" by PRD §28.1.
	MaxBulkOperations int `mapstructure:"max_bulk_operations"`
}

LLMSafetyConfig holds safety-related knobs for the agent runtime.

type ServerConfig

type ServerConfig struct {
	// Port is the TCP port the HTTP server listens on. Default: 8080.
	Port int `mapstructure:"port"`

	// Host is the bind address. Default: "0.0.0.0".
	Host string `mapstructure:"host"`

	// CORSOrigins is the list of allowed CORS origin patterns.
	// Default: ["*"].
	CORSOrigins []string `mapstructure:"cors_origins"`
}

ServerConfig holds HTTP server settings.