Configuration Messaging

Purpose

Use this skill to configure messaging <kind> provider <name> blocks. The parser is caddyfile_messaging.go.

Messaging is most often needed by registration flows, password recovery, MFA OTP, or administrative notifications.

caddyfile_messaging.go forwards provider subdirectives directly to go-authcrunch/pkg/messaging. Use the authcrunch instruction names exactly; for example, file providers use root_dir, not rootdir.

Email Provider

{
	security {
		messaging email provider localhost-smtp-server {
			address 127.0.0.1:1025
			protocol smtp
			credentials smtp_root
			sender root@example.com "Example Auth Portal"
			bcc admin@example.com audit@example.com
			template password_recovery templates/password_recovery.tmpl
			template registration_confirmation templates/registration_confirmation.tmpl
			template registration_ready templates/registration_ready.tmpl
			template registration_verdict templates/registration_verdict.tmpl
			template mfa_otp templates/mfa_otp.tmpl
		}
	}
}

Email providers require:

• address <host:port>.
• protocol smtp or protocol smtps.
• Exactly one of credentials <name> or passwordless.
• sender <email> [display_name].

Use passwordless instead of credentials <name> when the SMTP server does not require authentication.

In selected go-authcrunch v1.3.4, smtp opens a plaintext SMTP connection; the sender does not negotiate STARTTLS. smtps uses implicit TLS with certificate verification. A server requiring STARTTLS is not supported by switching protocol smtp to port 587. Use an endpoint that supports the chosen transport; there is no Caddyfile STARTTLS or custom SMTP CA directive here.

The referenced credentials <name> object follows configuration-credentials.

For local registration message checks, use the built-in file provider below with a disposable root_dir under this checkout's tmp/; no SMTP tool install is needed. This verifies rendered content, not SMTP authentication, TLS or recipient delivery. When the task requires SMTP evidence, use an explicitly configured loopback test server and synthetic credentials, inspect its envelope recipients as well as message headers, and stop it after the check. Keep any added test tooling and its output in the repository and pin its version.

File Provider

messaging file provider local_outbox {
	root_dir tmp/registration-messages
	sender root@example.com "Example Auth Portal"
	template registration_confirmation templates/registration_confirmation.tmpl
	template registration_ready templates/registration_ready.tmpl
	template registration_verdict templates/registration_verdict.tmpl
}

File providers write .eml messages under root_dir. Authcrunch requires both root_dir <path> and sender <email> [display_name]. File providers do not use credentials or passwordless.

In v1.3.4, email providers put bcc <email>... into a Bcc message header but do not add those addresses to SMTP RCPT TO. Do not rely on it for copy delivery or recipient privacy: recipients can see that header. This is an upstream sender limitation, not configurable Caddy behavior. File providers parse and preserve bcc, but the file sender writes only To; it also omits the configured sender from the .eml content.

Both email and file providers validate and preserve these template IDs:

• password_recovery.
• registration_confirmation.
• registration_ready.
• registration_verdict.
• mfa_otp.

Template Directive

Use template <id> <path> to add an entry to the provider's templates map. Authcrunch validates the ID and preserves the path, but the provider parser does not check that the path exists.

Current registration notification rendering does not load provider template paths. It uses embedded English subject/body templates from the sibling go-authcrunch repository, then sends the rendered message through the configured provider.

Default messaging template files live under: https://github.com/greenpau/go-authcrunch/tree/main/pkg/messaging/email_templates/en The embedded asset loader strips email_templates/ and .template, so registration_confirmation_subject.template is looked up as en/registration_confirmation_subject.

Default files by validated template ID:

• registration_confirmation: registration_confirmation_subject.template and registration_confirmation_body.template.
• registration_ready: registration_ready_subject.template and registration_ready_body.template.
• registration_verdict: registration_verdict_subject.template and registration_verdict_body.template.
• password_recovery: no default messaging subject/body file in pkg/messaging/email_templates; password recovery UI lives in the portal sandbox template, not in the messaging template library.
• mfa_otp: no default messaging subject/body file in pkg/messaging/email_templates.

Registration Wiring

Registration flows reference messaging providers by name with the historical email provider <name> directive. The referenced provider may be either kind; authcrunch resolves whether it is an email or file messaging provider at send time.

user registration signup {
	email provider localhost-smtp-server
	admin email admin@example.com
}

The registration block belongs to configuration-registrations.

Fixtures

Use these examples:

• caddyfile_messaging_test.go.
• testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile.

The parser test checks encoded instructions. Adapt/resolution and lifecycle tests verify configuration and replacement, not message delivery. This checkout has no complete user-registration SMTP E2E. Acceptance for a sender change needs a disposable recipient server that observes the negotiated transport, authentication, envelope recipients and rendered confirmation link; a Bcc header alone is not delivery evidence. File-provider acceptance checks private .eml output and content, and reports SMTP behavior as untested.