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 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 no placeholder portal. Volatile use needs no declared local database, but retaining completed sessions across restart also requires the provider to attach to local identity store NAME with a file-backed local store. Runtime state preserves that store's proof epoch; the provider's implicit private-memory attachment loses its identities at restart and cannot validate old session evidence. The direct OAuth policy contract owns those settings; mount callback/logout paths through the same policy.

Named refresh storage

Read Consul companions for shared password accounts, application tickets and Consul-managed refresh families. Consul refresh retains the exclusive root-state requirement and per-root namespace in the linked contract; this module alone does not distribute portal sessions or sandboxes.

A portal selecting named refresh storage must enable this root state block. The SQLite database supplies transactional families and spent history; root state supplies the stable namespace, changing configuration generation and other completed session/identity authority. Retain both through a complete stop/start. Selecting SQLite alone does not retain implicit provider-memory identities or downstream OP grants.

Provisioning freezes declarations and checks known storage/key-reader namespaces; Start repeats those metadata checks before opening runtime handles. The root activates selected views only after complete configuration normalization and loaded trust admission. Same-generation restart preserves deadlines and replay history; changed generations retire that namespace across its portals and reclaim capacity. Complete feature removal/reintroduction also changes the durable epoch. A failed later activation cannot roll back an earlier database retirement: cold startup is not a transaction across all files. Failed candidates publish no root, close their app-owned handles after root disposal and require corrected fresh construction. Root/portals never close borrowed views or snapshot their families.

Keep database files outside managed state/client-registration directories and separate from key readers and other backend files, including aliases/sidecars. Candidate removal does not discard the active graph's ownership until drain. See operations for loss, uncertainty and backup boundaries.

Validation

Check the selected module's public state and managed refresh APIs before changing this contract. Library tests alone do not certify this host.

• caddyfile_state_test.go, caddyfile_authz_oauth_test.go and the testcase_security_state adaptation fixture cover grammar, exact paths, JSON, placeholders, redacted failures and policy-only configuration.
• app_state_test.go covers no-I/O provisioning, single ownership, failed initialization, retry, 503 route admission before startup/after cleanup and drain before storage release.
• TestAuthzResponseContract tests the actual three-outcome route handler.
• TestCaddyRuntimeStateE2E builds an actual Caddy command from testdata/runtime_state_caddy, with standard/production modules and only an isolated test CA pool added to the main program. TLS verification remains enabled; no machine trust is changed. It uses SIGKILL and the same origin, directory and config across fresh processes. It covers direct OAuth, ACLs, lost pending callbacks, sessions/JWKS/signatures, browser/native refresh, OIDC consent/code/access/refresh and replay, logout, password/DB rollback, configuration transitions, competing processes, corrupt/lost storage, permissions, write failures, real snapshot capacity and overlapping reload under admitted callbacks and application traffic. Deferred state-directory resolution preserves its placeholder in autosave. Omitted-state behavior and failed persistence activation retaining the volatile deployment's routes and sessions remain separate phases. The snapshot-capacity fixture writes tens of MiB.

Selected refresh acceptance adds TestCaddySQLiteRefreshPersistenceE2E for real process continuity, replay/logout, capacity-one generation retirement, loaded trust and complete omission/reintroduction. TestCaddySQLiteRefreshUncertaintyE2E checks real attempted-COMMIT failure and browser/native recovery after reopen; local/root readiness and request-drain units remain separate. Use the managed refresh test map for exact fixture scope and limits.

When changing the state parser or runtime implementation, run focused unit/adaptation tests and go test -mod=readonly -race -count=1 -timeout=8m -run 'TestCaddyRuntimeStateE2E|TestPersistentApp' .. Retain the existing OAuth, lifecycle, composition and browser refresh coverage. Ordinary configuration review uses the relevant grammar, path/ownership and deployment checks; skill-only changes need metadata/link/source validation. Full regression/report runs follow testing-and-ci.