Configuration Messaging

Purpose

Use this skill to configure messaging <kind> provider <name> blocks. The built-in parser is caddyfile_messaging.go; companion modules use caddyfile_messaging_backend.go. The app owns runtime bindings and delivery.

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.

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.

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 email, file or a bound SQLite outbox. AuthCrunch selects it by exact name at send time. An outbox receives no SMTP credentials; its independently selected delivery transport receives them only when the worker sends.

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

The registration block belongs to configuration-registrations.

SQLite outbox

{
 security {
  messaging email provider smtp-local {
   address 127.0.0.1:1025
   protocol smtp
   passwordless
   sender auth@example.test
  }
  messaging sqlite provider notifications {
   path /var/lib/caddy-security/mail/outbox.db
   timeout 1s
   delivery smtp-local
  }
 }
}

The security.messaging.sqlite module appears in native JSON under apps.security.messaging_providers, with driver, name, path, optional timeout and optional delivery. Names must be unique across modules and built-ins. The public SQLite parser owns name/path/timeout validation. Fields are literal; they do not expand Caddy placeholders or secret lookups. Existing email-provider and credential instructions retain runtime resolution.

path is an absolute local POSIX database in an existing private 0700 parent; its database and sidecars use 0600. Use a separate file from other plugin categories. Runtime construction can create the outbox; parsing and module validation perform no storage I/O. Storage is pure Go and requires no SQLite process or cgo. Bodies, recipients and confirmation codes are plaintext on disk. timeout defaults to 1s and accepts 1ms through 30s for database operations.

Optional delivery selects an existing email provider, whose sender, protocol and credentials apply to every message in this queue. It cannot select another outbox or a file provider. Missing or ambiguous credentials fail before storage opens. Omission queues messages without starting a delivery worker; an external consumer must own delivery. Registration references the queue using email provider notifications.

Send success means durable local acceptance. The shared file permits 1000 outstanding messages across all named queues; full storage rejects admission without eviction. Transactions obtain exclusive access before mutation; ordinary reader/writer contention waits within the database deadline before admission. Failed or uncertain acceptance must not be blindly retried. The app rebuilds private runtime bindings after JSON restoration and never serializes handles or delivery credentials into message records.

Workers start only in App.Start. Each claim has a one-minute exclusive lease; the worker uses its exact persisted expiry, reserves five seconds for acknowledgement, and caps an SMTP attempt at fifteen seconds. Claim and acknowledgement contexts are bounded to five seconds, subject to any shorter queue timeout. Empty or failed attempts poll at one-second intervals. Failed or uncertain delivery remains leased until expiry; there is no immediate resend, lease renewal or dead-letter queue. A commit error can quarantine its handle; drain and reopen the runtime before reconciling uncertain work. The worker does not automatically reopen storage or reinterpret an error as non-acceptance. Independent workers can share a named queue. A crash after SMTP acceptance and before acknowledgement may duplicate delivery; applications needing deduplication must provide it downstream.

Cleanup closes request admission and drains producers, then cancels and joins workers before closing the root and queues. Cancellation closes the actual SMTP socket, including greeting, TLS handshake, DATA and QUIT stalls. A successful send still gets a bounded acknowledgement when cleanup starts concurrently. Validation-only candidates never send mail. A candidate that reaches Start may deliver before an unrelated app fails; Caddy startup has no transaction spanning external SMTP side effects. Queued work and outstanding leases survive restart. Other restrictions, including local identity/dropbox overlap, still apply.

Registration renders quoted-printable HTML. The worker preserves those bytes and the email sender supplies matching MIME headers; it does not double encode or reinterpret content. General queue callers must honor that body contract. Logs report fixed failure phases without recipients, bodies, codes, credentials, leases or raw transport diagnostics. bcc retains the built-in sender limitation above; queue delivery does not turn a header into an envelope recipient.

Validation surfaces

messaging_sqlite_test.go covers public parsing, native modules, private storage, queue isolation, stale leases and durable reopen. app_messaging_test.go covers binding validation, candidate cleanup and producer drain; app_messaging_worker_test.go covers budgets, cancellation, failure redaction and concurrent workers. app_messaging_e2e_test.go exercises actual TLS Caddy registration, SMTP envelope/body delivery, queue errors, restart and shutdown. Legacy registration confirmation writes a dropbox record; it does not implicitly activate a login account. Dedicated registration workflows have their own owner.

Adaptation cases include testcase_messaging_sqlite and testcase_authenticate_with_registration in testdata/caddyfile_adapt/. File output checks alone do not verify SMTP authentication, TLS or recipients. Use a disposable loopback server and synthetic credentials for transport tests; inspect RCPT TO separately from headers and close all test-owned connections.