configuration-secrets

Configuration Secrets

Purpose

Use this skill to configure secrets <plugin_name> <secret_id> blocks and secret-backed Caddyfile values. The parser is caddyfile_secrets.go; runtime replacement is in caddyfile_resolve.go.

Secrets managers are Caddy modules under the security.secrets namespace. SQLite is bundled; static and AWS managers require external modules. The security app loads them through SecretsManagerConfigs; each module must expose GetConfig(ctx)["id"], GetSecret(ctx), and GetSecretByKey(ctx, key).

Authcrunch does not resolve secrets:*:* values itself. Caddy-security replaces them during app provisioning, before the authcrunch config is validated and used to build the server. A secret lookup must therefore resolve to the final string that authcrunch expects, such as a bcrypt password hash, API key hash, OAuth client secret, SMTP password, or crypto shared secret.

Shape

{
	security {
		secrets static_secrets_manager access_token {
			shared_secret {env.JWT_SHARED_KEY}
		}

		authentication portal myportal {
			crypto key sign-verify "secrets:access_token:shared_secret"
		}
	}
}

The block form is:

secrets <secrets_plugin_name> <secret_id> {
	...
}

The third token is the manager ID, also called the secret ID in plugin logs and docs. It must match the middle segment of every lookup: secrets:<secret_id>:<key>. The inner block is owned by the selected secrets manager module; do not invent manager-specific fields. Manager IDs must be nonempty and unique across the app.

SQLite Secrets Manager

Use the SQLite secrets reference to configure the bundled security.secrets.sqlite module, provision records with security secrets, rotate consumers through explicit reload, and verify failure/restart behavior. The module reads one coherent record during provisioning and closes the database before consumers start. Backend writes do not change an existing runtime.

Static Secrets Manager