Configuration State

Persistent Runtime State

Use this skill for security { state { ... } }, native config.state JSON, restart persistence, and its lifecycle boundary. OAuth client registrations and identity databases retain their existing owners. Keep changes and test output in this repository; sibling AuthCrunch source is a read-only reference under the repository scope.

Configuration

Add one optional block inside the global security app:

{
	security {
		state {
			directory /var/lib/authcrunch/runtime
		}
		# Existing providers, portals and/or authorization policies follow.
	}
}

This is a fragment: a usable security app also needs a portal or policy. The JSON field is apps.security.config.state, with the library's shape: "state":{"directory":"/var/lib/authcrunch/runtime"}. Paths must be absolute, non-root and private. Quote spaces. Omission retains volatile behavior; an empty block, duplicate block/setting, extra arguments, unknown settings and nested blocks are errors. Closing braces end their lines. Use {$VARIABLE} for adaptation-time substitution. {env.VARIABLE} and whole secrets:manager:key references remain declarative until provisioning; an empty or invalid resolved directory fails instead of disabling persistence.

caddyfile_state.go owns traversal and cfgutil.EncodeArgs encoding; go-authcrunch/pkg/state/parser.NewStateConfigFromDirectives owns grammar and normalization. Deferred values use a validation-only stand-in, retain their original token in Config.State, and are resolved/revalidated in the private configuration copy. Never open the stand-in, choose a process-specific directory, implement another directory grammar, or copy the library's records, encryption, session DTOs, replay history or locks into Caddy.

Lifecycle and operation

Pending cross-device interactions are always volatile. Reload or complete stop/start discards them even when completed sessions use persistent state. The existing rejection of overlapping persistent reload still applies. See cross-device lifecycle.

Read operator guidance when enabling persistence, planning deployment/recovery, or explaining its guarantees. Persistent runtimes are constructed by App.Start, not Provision, so adaptation and validation do not initialize keys or state files. Route provisioning validates declared names; admission stays closed until NewServer succeeds.

Caddy v2.11.7 provisions and starts a replacement before retiring the old app. There is no atomic drain/construct/rollback facility. A candidate persistent app checks Caddy's active app during provisioning and rejects replacement of a live persistent runtime before candidate HTTP routes start. This deliberately also rejects changing directories by reload. Use a complete stop/start. The library independently enforces exclusive directory ownership across processes. Do not add a host storage lock or shared runtime/snapshot map.

App.Cleanup closes admission, drains every admitted portal/gatekeeper call (including callbacks, token and profile APIs), then closes the root. A failed candidate never closes the serving root. Failed construction unwinds its own resources. Close neither flushes nor deletes committed data. Preserve handled 503/protocol failures and never issue fallback credentials or retry rotations.

Policy-only OAuth needs neither a placeholder portal nor a local database. The direct OAuth policy contract owns those settings; mount callback/logout paths through the same policy.