Configuration Registrations

Purpose

Use this skill to configure user signup. Read SQLite enrollment for user registration sqlite <name>: confirmation creates a login account with a fixed policy and requires explicit portal selection. The legacy user registration <name> flow below writes a separate approval dropbox. OAuth client registrations retain their own configuration owner.

Legacy dispatch starts in caddyfile_user.go; registration instructions are collected by caddyfile_user_registration.go. The Caddyfile parser injects name <block-name> and kind local, then forwards the block instructions to authcrunch for validation.

Registration flows attach to the target identity store declared by identity store <name> [<realm>]. During authcrunch validation, portals using that identity store get registration enabled for that store and the registry is attached at runtime. Legacy registrations are selected automatically for eligible portals unless a nonempty explicit enable user registration <name> [<name>...] selection is supplied. The portal must also enable each selected registry's identity store. SQLite workflows require explicit registration selection.

Shape

{
	security {
		user registration signup {
			title "User Registration"
			code {env.REGISTER_CODE}
			dropbox assets/config/registrations_local.json
			require accept terms
			require domain mx
			email provider smtp
			admin email admin@example.com
			identity store localdb
			link terms https://example.com/terms
			link privacy https://example.com/privacy
			allow domain example.com
		}

		local identity store localdb {
			realm local
			path assets/config/users.json
		}

		authentication portal myportal {
			enable identity store localdb
		}
	}
}

Required and Defaulted Fields

Authcrunch requires the effective registry config to have name, kind, dropbox, email provider, at least one admin email address, and identity store. In Caddyfile configuration, name comes from the block name and kind local is injected by caddy-security.

title is optional and defaults to Sign Up. code is optional; when present, the registration form requires the exact configured value. require accept terms and require domain mx are optional boolean flags.

The authcrunch parser accepts exactly one admin email address per instruction: admin email <address> or admin emails <address>. Multiple addresses on one line are invalid, and repeated admin-email lines overwrite rather than append.

Supported Lines

The parser forwards registration lines to authcrunch. Supported patterns in authcrunch include:

• title <name>
• code <value>
• dropbox <path>
• require accept terms
• require domain mx
• email provider <name>
• admin email <address>
• admin emails <address>
• identity store <name> [<realm>]
• link terms <url>
• link privacy <url>
• allow domain <string>
• deny domain <string>
• allow <exact|partial|prefix|suffix|regex> domain <string>
• deny <exact|partial|prefix|suffix|regex> domain <string>

Domain restrictions are validated by authcrunch. Matching stops at the first rule that matches the email domain; if no rule matches, the default action is the opposite of the last configured rule. For a simple allow list, use only allow rules. For a simple deny list, use only deny rules.

Coordinate the email provider value with configuration-messaging; despite the directive name, authcrunch can notify through a matching email or file messaging provider or a bound SQLite outbox. Coordinate identity store names with configuration-identity-stores.

Workflow Notes

Registration is not the same as immediate account activation. The user reaches the form from the portal's register link, submits username, password, email, name, optional registration code, and required terms acceptance, then receives an email confirmation link and short passcode. The confirmation passcode is time-limited in authcrunch; when it expires, the user must register again.

After email confirmation, the handler consumes the pending registration, adds the user to the dropbox database and attempts an administrator notification. That database is separate from the target login store. Approval and transfer into the login store remain a separate management operation; no full approval UI is implemented here. Do not edit a serving identity database as a routine approval step. Use a supported management path or arrange an offline import and explicit reload. A notification failure after the dropbox commit is logged and does not undo the committed registration.

Pending registrations are held in the registry's in-memory cache. Reload or restart discards them; the durable dropbox only contains confirmed entries. An expired or lost pending registration must be started again. A supplied password must be plaintext: the selected AuthCrunch rejects reserved password-hash import prefixes on the public registration path, while trusted static-user imports are separate. The HTML form reports invalid input inline with localized messages. Tests should check the rendered message and absence of delivery or persisted users, rather than expecting the internal validator's error text to appear verbatim.

When multiple registrations target different identity stores or realms, use separate dropbox paths. The portal exposes realm-specific registration URLs, for example:

/auth/register/local
/auth/register/userpool1.localdomain

For local validation without SMTP, point email provider at a file messaging provider whose root_dir is a disposable path under this checkout's tmp/. Inspect the confirmation link and passcode in its .eml output using synthetic identities and separate temporary dropbox/login databases. This does not check SMTP authentication, TLS, sender headers or BCC delivery; the messaging skill documents those limits.

Fixtures

Use these examples:

• testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile.
• assets/config/registrations_local.json.

The adaptation/resolution fixture verifies configuration shape and defaults, not a registration journey. TestCaddyPasswordArgon2E2E/public-registration uses the actual executable and a disposable file sender to reject valid, malformed and whitespace-padded bcrypt/Argon2 imports without a message or persisted user; ordinary plaintext reaches confirmation-message delivery. TestCaddySQLiteMessagingE2E also qualifies legacy confirmation, the separate dropbox and administrator notification through real TLS Caddy and SMTP, including restart and worker cleanup. It deliberately verifies that confirmation alone does not create a login account. The lifecycle tests exercise registry ownership and replacement. Do not confuse TestCaddyRegistrationE2E, which covers persisted OAuth client registrations, with user signup. Retain separate acceptance for wrong codes, domain policy, replay/lost pending state and the management activation boundary.