feat: declarative secret generation with type and generate fields

Secrets can now be auto-generated when missing by adding `type` and
`generate` fields to the secret config. Supported types: password, hex,
base64, uuid, and command. Generation triggers during check/run when a
secret is missing and stores the value via the configured provider.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: domenkozar

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Declarative secret generation: secrets can now be auto-generated when missing by adding
+  `type` and `generate` fields to secret config. Supported types: `password`, `hex`, `base64`,
+  `uuid`, and `command` (for arbitrary shell commands). Generation triggers during `check`/`run`
+  when a secret is missing, and the generated value is stored via the configured provider.
+
 ### Changed
 - OnePassword provider: Significant performance improvement by caching authentication status
   and using batch fetching with parallel threads. Reduces CLI calls from 2N sequential to

Cargo.lock

@@ -40,6 +40,9 @@ google-cloud-secretmanager-v1 = "1.2"
 tokio = { version = "1", features = ["rt"] }
 secretspec-derive = { version = "0.6.2", path = "./secretspec-derive" }
 secretspec = { version = "0.6.2", path = "./secretspec" }
+rand = "0.9"
+uuid = { version = "1", features = ["v4"] }
+data-encoding = "2"
 
 # The profile that 'dist' will build with
 [profile.dist]

Cargo.toml

@@ -35,6 +35,8 @@ SECRET_NAME = {
 - `description`: Explains the secret's purpose (required)
 - `required`: Whether the secret must be provided (default: `true`)
 - `default`: Fallback value for optional secrets
+- `type`: Secret type for auto-generation (`password`, `hex`, `base64`, `uuid`, `command`)
+- `generate`: Enable auto-generation when the secret is missing (`true` or a table with options)
 
 ## Configuration Inheritance
 
@@ -89,6 +91,19 @@ extends = ["../../shared/base", "../../shared/database", "../../shared/auth"]
 - Each profile is merged independently
 - Paths are relative to the containing file
 
+## Secret Generation
+
+Secrets can be declared with `type` and `generate` to be auto-generated when missing. This is useful for passwords, tokens, and keys that don't need to be shared:
+
+```toml
+[profiles.default]
+DB_PASSWORD = { description = "Database password", type = "password", generate = true }
+API_TOKEN = { description = "API token", type = "hex", generate = { bytes = 32 } }
+SESSION_KEY = { description = "Session key", type = "base64", generate = { bytes = 64 } }
+```
+
+Generated values are stored via the configured provider and reused on subsequent runs. See the [configuration reference](/reference/configuration/#secret-generation) for all generation types and options.
+
 ## Best Practices
 
 1. **Descriptive names**: Use `STRIPE_API_KEY` instead of generic `API_KEY`

docs/src/content/docs/concepts/declarative.md

@@ -50,6 +50,12 @@ TLS_CERT = { description = "TLS certificate", as_path = true }
 
 Secrets with `as_path = true` are written to temporary files - useful for credentials that must be passed as file paths (TLS certs, service account keys).
 
+Secrets with `type` and `generate` are automatically created when missing — no manual setup needed for passwords, tokens, and keys:
+
+```toml
+DB_PASSWORD = { description = "Database password", type = "password", generate = true }
+```
+
 ```bash
 # Initialize secretspec.toml, possibly from `.env`
 $ secretspec init --from dotenv

docs/src/content/docs/index.mdx

@@ -47,9 +47,12 @@ Each secret variable is defined as a table with the following fields:
 | `default` | string | No** | Default value if not provided |
 | `providers` | array[string] | No | List of provider aliases to use in fallback order |
 | `as_path` | boolean | No | Write secret to temp file and return file path (default: false) |
+| `type` | string | No*** | Secret type for generation: `password`, `hex`, `base64`, `uuid`, `command` |
+| `generate` | boolean or table | No*** | Enable auto-generation when secret is missing |
 
 *If `default` is provided, `required` defaults to false
 **Only valid when `required = false`
+***`type` is required when `generate` is enabled; `generate` and `default` cannot both be set
 
 ## Complete Example
 
@@ -123,6 +126,45 @@ GOOGLE_APPLICATION_CREDENTIALS = { description = "GCP service account", as_path
 | Rust SDK | Files cleaned up when `ValidatedSecrets` is dropped; use `keep_temp_files()` to persist |
 | Rust SDK types | `PathBuf` or `Option<PathBuf>` instead of `String` |
 
+### Secret Generation
+
+When `type` and `generate` are set, missing secrets are automatically generated during `check` or `run` and stored via the configured provider:
+
+```toml
+[profiles.default]
+# Simple: generate with type defaults
+DB_PASSWORD = { description = "Database password", type = "password", generate = true }
+REQUEST_ID = { description = "Request ID prefix", type = "uuid", generate = true }
+
+# Custom options
+API_TOKEN = { description = "API token", type = "hex", generate = { bytes = 32 } }
+SESSION_KEY = { description = "Session key", type = "base64", generate = { bytes = 64 } }
+
+# Shell command
+MONGO_KEY = { description = "MongoDB keyfile", type = "command", generate = { command = "openssl rand -base64 765" } }
+
+# Type without generate: informational only, no auto-generation
+MANUAL_SECRET = { description = "Manually managed", type = "password" }
+```
+
+#### Generation Types
+
+| Type | Default Output | Options |
+|------|---------------|---------|
+| `password` | 32 alphanumeric chars | `length` (int), `charset` (`"alphanumeric"` or `"ascii"`) |
+| `hex` | 64 hex chars (32 bytes) | `bytes` (int) |
+| `base64` | 44 chars (32 bytes) | `bytes` (int) |
+| `uuid` | UUID v4 (36 chars) | none |
+| `command` | stdout of command | `command` (string, required) |
+
+#### Behavior
+
+- Generation only triggers when a secret is **missing** — existing secrets are never overwritten
+- Generated values are stored via the secret's configured provider (or the default provider)
+- Subsequent runs find the stored value and skip generation (idempotent)
+- `generate` and `default` cannot both be set on the same secret
+- `type = "command"` requires `generate = { command = "..." }` (not just `generate = true`)
+
 ## Profile Inheritance
 
 - All profiles automatically inherit from `[profiles.default]`