protege 0.1.0.alpha.1

data/lib/generators/protege/postfix/templates/deploy/mail/MAIL.md

@@ -0,0 +1,135 @@
+# Deploying self-hosted mail (Postfix + OpenDKIM)
+
+This is the advanced, no-provider path: a Postfix + OpenDKIM MTA runs on your own host, receiving
+inbound mail on port 25 and delivering outbound directly to recipient MX servers. OpenDKIM signs with
+the key **Protege already generates** (`Protege::EmailDomain#dkim_private_key_pem`) — no second key
+source. The engine is transport-agnostic; nothing in it changes.
+
+> Replace `agent.example.com`, `YOUR_VPS_IP`, and `YOUR_REGISTRY` below with your own values.
+
+## Why self-hosting mail is hard
+
+Running your own MTA means owning deliverability: correct **PTR/reverse DNS**, **SPF/DKIM/DMARC**, an
+**unblocked outbound port 25**, and IP reputation. If you just want it to work, use an email provider
+(see the provider path in the docs) — it's the recommended default. Self-host only if you specifically
+want no relay provider.
+
+## 1. Build & publish the image
+
+```sh
+docker build --platform linux/amd64 -t YOUR_REGISTRY/protege-mail:latest deploy/mail
+docker push YOUR_REGISTRY/protege-mail:latest
+```
+
+`.github/workflows/build-mail-image.example.yml` (also generated) automates this in CI — rename it to
+`build-mail-image.yml` and set your registry.
+
+## 2. Run the image as your MTA
+
+`kamal-accessory.example.yml` (also generated) is a ready Kamal accessory. Merge its `mail:` block into
+your `config/deploy.yml`, then set the env it references:
+
+- **clear:** `MAIL_DOMAIN` (the MTA's own FQDN, e.g. `agent.example.com`), `APP_RELAY_URL`
+  (`https://agent.example.com/rails/action_mailbox/relay/inbound_emails`), `DMARC_POLICY`
+  (`enforce` — see [Inbound sender authentication](#inbound-sender-authentication-spf-dkim-dmarc))
+- **secret:** `RAILS_INBOUND_EMAIL_PASSWORD` (the only secret)
+
+**No DKIM key secret.** The DKIM keys live in the app (`Protege::EmailDomain#dkim_private_key_pem`) and
+are **pushed** to the MTA over the internal Kamal network whenever a domain changes (and via the
+dashboard's *Sync now* button) — one image serves every domain, and adding one needs no rebuild or
+reboot. Persist the pushed keys on the `protege_mail_provision` volume (already in the accessory block) so
+they survive restarts; the container re-applies the cached set on boot.
+
+For the app to reach the MTA, set `MAIL_RELAY_HOST: protege-mail` in your **app** service's clear env —
+the same accessory name it already delivers outbound SMTP to. Its presence is also what tells the console
+it's self-hosting (so it shows this domain's own DKIM record and the *Sync now* button).
+
+## 3. Point the app at the MTA (`config/environments/production.rb`)
+
+```ruby
+# Inbound: accept the MTA's relay POST.
+config.action_mailbox.ingress          = :relay
+config.action_mailbox.ingress_password = ENV.fetch('RAILS_INBOUND_EMAIL_PASSWORD', nil)
+
+# Outbound: hand mail to the MTA (resolvable name on your container network).
+config.action_mailer.delivery_method = :smtp
+config.action_mailer.smtp_settings   = {
+  address:              ENV.fetch('MAIL_RELAY_HOST', 'protege-mail'),
+  port:                 ENV.fetch('MAIL_RELAY_PORT', 25).to_i,
+  authentication:       nil,
+  enable_starttls_auto: false
+}
+```
+
+Action Mailbox runs **one** ingress at a time — switching to `:relay` replaces any provider ingress.
+
+## 4. Infrastructure
+
+- **PTR / reverse DNS:** map `YOUR_VPS_IP` → `agent.example.com` in your host's control panel.
+  Verify: `dig +short -x YOUR_VPS_IP` returns `agent.example.com.`
+- **Inbound firewall:** allow inbound TCP `25` from `0.0.0.0/0` so the internet can reach your MX.
+- **Outbound port 25:** many providers (e.g. Hetzner) block outbound 25 by default — request an
+  unblock. Outbound delivery cannot work until it's lifted; inbound is unaffected.
+
+## 5. Domains + DNS records
+
+For **each** agent domain, add it in the dashboard (**Domains → New**). That generates its DKIM keypair,
+shows the exact records to publish, and **pushes the key to the MTA automatically** (no reboot). If you
+add domains while the accessory is down, or you reboot it, click **Sync now** on a domain page to re-push
+(the container also re-applies the last-known set on boot). Read the values off the domain's page, or:
+
+```sh
+kamal app exec --reuse "bin/rails runner 'd=Protege::EmailDomain.find_or_create_by!(domain: %(agent.example.com)); \
+  puts d.dkim_dns_name, d.dkim_txt_record, d.spf_txt_record, d.dmarc_txt_record, d.mx_record'"
+```
+
+Publish per domain (repeat for each):
+
+| Type | Host | Value |
+|---|---|---|
+| `TXT` | `default._domainkey.agent.example.com` | `#dkim_txt_record` |
+| `TXT` | `agent.example.com` | `v=spf1 mx ~all` (`#spf_txt_record`) |
+| `TXT` | `_dmarc.agent.example.com` | `#dmarc_txt_record` |
+| `MX` | `agent.example.com` | `10 agent.example.com.` (`#mx_record`) — change **last**, at cutover |
+
+Pre-stage the TXT records anytime. Do **not** change the MX until you cut over (it routes live inbound).
+
+## 6. Cutover
+
+1. Ensure inbound 25 is open, the TXT records are published, and each domain has been added in the
+   dashboard (which pushes its key to the MTA).
+2. Deploy the app and **boot the accessory** (Kamal `deploy` does not manage accessories):
+   `kamal accessory boot mail`.
+3. Point the **MX** at `agent.example.com` (priority 10). Inbound now arrives at your box.
+4. Validate: `kamal accessory logs mail`; email the persona from Gmail → reply lands with
+   **SPF/DKIM/DMARC = pass** ("Show original"). Score at [mail-tester.com](https://www.mail-tester.com)
+   and iterate on reputation.
+
+## Inbound sender authentication (SPF / DKIM / DMARC)
+
+The MTA authenticates **incoming** mail before it ever reaches the app, so a spoofed `From:` can't slip
+past the engine's inbound access list (which keys off the `From` address). Three checks run at SMTP time:
+
+- **policyd-spf** rejects a hard SPF fail (the sender domain's `-all` disavows the sending IP) and records
+  the SPF result for DMARC.
+- **OpenDKIM** verifies the DKIM signature.
+- **OpenDMARC** evaluates DMARC alignment against the sender domain's published policy and **rejects** the
+  message when that policy is `p=reject` and it fails. Domains publishing `p=none`/`p=quarantine` are not
+  rejected (we honor the stated policy); the verdict is still stamped in `Authentication-Results`.
+
+Our own outbound (the app container, on RFC1918) skips all three — only remote inbound mail is checked.
+
+**The `DMARC_POLICY` toggle** (clear env on the accessory):
+
+- `enforce` (default) — reject failing mail at SMTP.
+- `monitor` — evaluate and stamp `Authentication-Results` headers but reject nothing. Use this for a
+  first-run window: deploy with `monitor`, watch `kamal accessory logs mail` for `dmarc=fail` on
+  legitimate senders, then switch to `enforce` and redeploy (no image rebuild needed).
+
+To verify: from a Gmail account, email the persona and confirm a normal message is delivered with
+`dmarc=pass`; a spoofing attempt against a `p=reject` domain is refused at SMTP (visible in the logs).
+
+## Rollback
+
+Restore the previous inbound ingress + SMTP settings in `production.rb`, restore the MX to your prior
+provider, and redeploy.

data/lib/generators/protege/postfix/templates/deploy/mail/README.md

@@ -0,0 +1,56 @@
+# Self-hosted mail (Postfix + OpenDKIM + OpenDMARC)
+
+These files build a single Docker image that runs **Postfix** (the MTA), **OpenDKIM** (DKIM
+sign/verify), and **OpenDMARC** + **policyd-spf** (inbound SPF/DKIM/DMARC enforcement) — so Protege can
+receive and send mail without a relay provider, and reject spoofed inbound mail at SMTP. One image serves
+**every** agent domain: the DKIM keys and per-domain tables aren't baked in — the Rails app **pushes** the
+current set of domains to the running container whenever you add or remove one (and via the console's
+"Sync now" button), so adding a domain never needs a rebuild or reboot. They were generated by
+`bin/rails g protege:postfix`. Build them into an image, run that image as your MTA (e.g. a Kamal
+accessory), and point your app's mail config at it.
+
+See **MAIL.md** in this directory for the full deployment guide (DNS, reverse DNS, firewall, cutover).
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `Dockerfile` | Builds the image (Debian + `postfix opendkim opendkim-tools opendmarc postfix-policyd-spf-python rsyslog curl`; `python3` for `provision.py` comes in with policyd-spf). |
+| `entrypoint.sh` | Templates the box hostname + DMARC toggle, wires the inbound pipe + SPF policy service, re-applies the cached domain manifest, starts the daemons + the provisioning listener. |
+| `provision.py` | The provisioning listener + apply logic. Receives the domain manifest the app pushes, writes the per-domain DKIM keys + `KeyTable`/`SigningTable`/transport, and reloads. Also runs once at boot from the cached manifest. Internal-only listener (not published); auth via `RAILS_INBOUND_EMAIL_PASSWORD`. |
+| `main.cf` | Postfix config. Accepts mail for the served domains and pipes it to your app; relays outbound directly to recipient MX; runs the SPF policy + DKIM/DMARC milters on inbound. `transport_maps`/`relay_domains` are filled per-domain by `provision.py`. |
+| `opendkim.conf` | OpenDKIM config — signs outbound, verifies inbound, stamps `Authentication-Results` (runs as the `opendkim` user). |
+| `opendmarc.conf` | OpenDMARC config — evaluates DMARC alignment on inbound and rejects failures when the sender publishes `p=reject` (gated by `DMARC_POLICY`). |
+| `opendmarc.ignore.hosts` | Internal ranges OpenDMARC skips (our own outbound). |
+| `policyd-spf.conf` | postfix-policyd-spf-python config — SPF check; rejects hard fails, feeds the result to OpenDMARC. |
+| `KeyTable` / `SigningTable` | Generated-at-runtime stubs — `provision.py` rewrites them, one line per domain, from the pushed manifest. |
+| `TrustedHosts` | Internal ranges OpenDKIM signs for (loopback + RFC1918). |
+| `relay-to-app.sh` | Postfix pipe transport: POSTs each inbound message to your app's Action Mailbox relay ingress. |
+
+`main.cf` contains a `__MAIL_DOMAIN__` placeholder (the MTA's own hostname) that `entrypoint.sh`
+substitutes **at container start** from the `MAIL_DOMAIN` env var — do not edit it in. The DKIM keys and
+per-domain `KeyTable`/`SigningTable`/transport are not templated; the app pushes them at runtime.
+
+## Runtime environment (set when you run the container)
+
+| Var | Required | What |
+|---|---|---|
+| `MAIL_DOMAIN` | yes | The MTA's own FQDN (HELO / PTR / TLS CN), e.g. `agent.example.com`. The **agent domains** it signs/receives for come from the app's push, not this var. |
+| `APP_RELAY_URL` | yes | Your app's relay ingress, e.g. `https://agent.example.com/rails/action_mailbox/relay/inbound_emails`. |
+| `RAILS_INBOUND_EMAIL_PASSWORD` | yes | Shared secret (HTTP Basic). Authenticates both the inbound relay POST (user `actionmailbox`) and the app's provisioning push (user `provision`). Must match `config.action_mailbox.ingress_password`. |
+| `DMARC_POLICY` | no | Inbound enforcement mode: `enforce` (default — reject SPF/DKIM/DMARC failures at SMTP) or `monitor` (evaluate + stamp headers, reject nothing). |
+| `MAIL_PROVISION_PORT` | no | Internal port the provisioning listener binds (default `8025`). Not published — reachable only from the app on the Kamal network. |
+
+Persist `/var/lib/protege-mail` on a volume so the pushed keys + cached manifest survive restarts (the
+container re-applies the cached manifest on boot). No per-domain `DKIM_PRIVATE_KEY` secret is needed
+anymore — the app is the source of truth and pushes the keys.
+
+## Build
+
+```sh
+docker build --platform linux/amd64 -t YOUR_REGISTRY/protege-mail:latest deploy/mail
+docker push YOUR_REGISTRY/protege-mail:latest
+```
+
+`kamal-accessory.example.yml` and `.github/workflows/build-mail-image.example.yml` (also generated)
+are starting points for running the image via Kamal and building it in CI.

data/lib/generators/protege/postfix/templates/deploy/mail/SigningTable

@@ -0,0 +1,3 @@
+# generated at runtime by provision.py — do not edit
+# One line per domain, written from the manifest the Rails app pushes:
+#   *@<domain> <selector>._domainkey.<domain>

data/lib/generators/protege/postfix/templates/deploy/mail/TrustedHosts

@@ -0,0 +1,8 @@
+# Hosts whose outbound mail OpenDKIM signs (rather than treating as external to verify). Covers
+# loopback and the private Docker/Kamal bridge ranges the app container relays through.
+127.0.0.1
+::1
+localhost
+10.0.0.0/8
+172.16.0.0/12
+192.168.0.0/16

data/lib/generators/protege/postfix/templates/deploy/mail/entrypoint.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# Container entrypoint for the Protege mail accessory.
+#
+# Turns the static image into a running multi-domain MTA: substitutes MAIL_DOMAIN (the box's own FQDN)
+# into main.cf, wires the inbound pipe transport, restores the last-known domain set from the cached
+# manifest, then launches OpenDKIM + Postfix. The signing keys + per-domain tables are NOT baked in — the
+# Rails app pushes them to provision.py (boot re-apply + the "Sync now" listener), so one image serves
+# every agent domain and adding one needs no rebuild.
+set -euo pipefail
+
+# --- Required runtime configuration ------------------------------------------------------------------
+: "${MAIL_DOMAIN:?MAIL_DOMAIN not set}"
+: "${APP_RELAY_URL:?APP_RELAY_URL not set}"
+: "${RAILS_INBOUND_EMAIL_PASSWORD:?RAILS_INBOUND_EMAIL_PASSWORD not set}"
+
+# --- Substitute the box hostname into main.cf --------------------------------------------------------
+# Only main.cf carries __MAIL_DOMAIN__ now (myhostname/mydomain — the MTA's own identity for HELO/PTR).
+# The OpenDKIM KeyTable/SigningTable and the Postfix transport are generated per-domain by provision.py.
+sed -i "s/__MAIL_DOMAIN__/${MAIL_DOMAIN}/g" /etc/postfix/main.cf
+chmod 644 /etc/postfix/main.cf
+
+# --- Provisioning bootstrap: keys + per-domain tables come from the app, not the image ----------------
+# The DKIM keys and the Postfix transport/relay_domains are generated by provision.py from the manifest
+# the Rails app pushes (see Protege::Gateway.push_mail_provisioning). Persist them on a volume
+# (/var/lib/protege-mail) so a restart keeps working, and ensure an empty transport map exists so
+# `postfix check` passes before the first push. The apply below restores the last-known domain set from
+# the cached manifest — a no-op on first boot, before any push.
+mkdir -p /var/lib/protege-mail/keys
+touch /etc/postfix/transport
+postmap /etc/postfix/transport
+python3 /usr/local/bin/provision.py apply || true
+
+# --- Inbound DMARC enforcement toggle ----------------------------------------------------------------
+# DMARC_POLICY controls whether OpenDMARC rejects failing mail at SMTP. "enforce" (the default) rejects
+# spoofed/failing mail from domains publishing p=reject; anything else ("monitor") only evaluates and
+# stamps Authentication-Results headers, rejecting nothing — useful for a first-run observation window.
+: "${DMARC_POLICY:=enforce}"
+if [ "$DMARC_POLICY" = "enforce" ]; then dmarc_reject=true; else dmarc_reject=false; fi
+sed -i "s/__DMARC_REJECT__/${dmarc_reject}/" /etc/opendmarc.conf
+echo "protege-mail: DMARC_POLICY=${DMARC_POLICY} (RejectFailures ${dmarc_reject})" >&2
+
+# --- Pass the relay credentials to the pipe transport ------------------------------------------------
+# Postfix's pipe daemon scrubs the environment, so the forwarding script reads these from a file it
+# sources. Readable only by the pipe user (nobody).
+mkdir -p /etc/protege-mail
+cat > /etc/protege-mail/relay.env <<EOF
+APP_RELAY_URL='${APP_RELAY_URL}'
+RAILS_INBOUND_EMAIL_PASSWORD='${RAILS_INBOUND_EMAIL_PASSWORD}'
+EOF
+chown nobody:nogroup /etc/protege-mail/relay.env
+chmod 600 /etc/protege-mail/relay.env
+
+# --- Register the inbound pipe transport in master.cf ------------------------------------------------
+# transport_maps (main.cf) routes the agent domain to "actionmailbox:", which resolves to this service.
+postconf -M "actionmailbox/unix=actionmailbox unix - n n - - pipe flags=Rq user=nobody argv=/usr/local/bin/relay-to-app.sh"
+
+# --- Register the policyd-spf policy service in master.cf --------------------------------------------
+# main.cf's check_policy_service unix:private/policyd-spf resolves to this spawn service. spawn runs the
+# Python daemon per request under its own unprivileged user.
+postconf -M "policyd-spf/unix=policyd-spf unix - n n - 0 spawn user=policyd-spf argv=/usr/bin/policyd-spf"
+
+# --- TLS: self-signed cert so inbound STARTTLS handshakes complete -----------------------------------
+# Postfix advertises STARTTLS (smtpd_tls_security_level = may); without a cert the handshake fails, and
+# TLS-preferring senders (e.g. Gmail) won't downgrade to plaintext, so mail never delivers. A
+# self-signed cert is fine for opportunistic MX TLS — peers encrypt without validating it.
+tls_dir=/etc/postfix/tls
+mkdir -p "$tls_dir"
+if [ ! -s "${tls_dir}/cert.pem" ]; then
+  openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \
+    -subj "/CN=${MAIL_DOMAIN}" \
+    -keyout "${tls_dir}/key.pem" -out "${tls_dir}/cert.pem"
+fi
+chown root:postfix "${tls_dir}/key.pem"
+chmod 640 "${tls_dir}/key.pem"
+# Run all Postfix services un-chrooted. Chrooted services can't reach files outside
+# /var/spool/postfix — the TLS cert (/etc/postfix/tls) and, critically, /etc/resolv.conf, so the smtp
+# delivery agent's MX lookups fail ("Host not found"). The container is the isolation boundary, so
+# chroot only gets in the way.
+postconf -F '*/*/chroot=n'
+
+# --- Minimal syslog so OpenDKIM's logs reach the container stdout ------------------------------------
+# Postfix logs straight to stdout (maillog_file in main.cf); OpenDKIM only speaks syslog, so run a tiny
+# rsyslog that forwards everything to stdout (no imklog — it fails inside containers).
+cat > /etc/rsyslog.conf <<'EOF'
+module(load="imuxsock")
+*.* /dev/stdout
+EOF
+rsyslogd -n &
+
+# --- Launch OpenDKIM + OpenDMARC (background) then Postfix (foreground = container PID) ---------------
+mkdir -p /run/opendkim
+chown opendkim:opendkim /run/opendkim
+opendkim -x /etc/opendkim.conf
+
+mkdir -p /run/opendmarc
+chown opendmarc:opendmarc /run/opendmarc
+opendmarc -c /etc/opendmarc.conf
+
+newaliases 2>/dev/null || true
+
+# Re-assert Postfix queue ownership before starting. The queue persists on a Docker volume, but the
+# dynamically-allocated `postfix` UID can drift when the image is rebuilt (apt may create other system
+# users during the transaction, shifting the uid) — leaving the existing /var/spool/postfix/* dirs owned
+# by the previous uid. Postfix then dies with "scan_dir_push: open directory defer: Permission denied"
+# and crash-loops. set-permissions re-chowns the queue to the current uid (verified to fix it). It also
+# tries to chown the command man pages, which this slim image omits, so it exits non-zero *after* the
+# queue is already fixed — tolerate that (|| true) so `set -e` doesn't abort the boot.
+postfix set-permissions 2>/dev/null || true
+
+# --- Domain provisioning listener ---------------------------------------------------------------------
+# Receives pushes from the app (any EmailDomain change + the console "Sync now" button): it rewrites the
+# OpenDKIM keys/tables and Postfix transport/relay_domains, then reloads. Internal only — bound to the
+# Kamal network, never published (port 25 stays the sole exposed port); auth reuses
+# RAILS_INBOUND_EMAIL_PASSWORD. See provision.py.
+python3 /usr/local/bin/provision.py serve &
+
+postfix check
+exec postfix start-fg

data/lib/generators/protege/postfix/templates/deploy/mail/kamal-accessory.example.yml

@@ -0,0 +1,32 @@
+# Kamal accessory for the self-hosted Postfix + OpenDKIM MTA.
+#
+# Merge this `mail:` entry into the `accessories:` block of your config/deploy.yml, then replace the
+# placeholders (YOUR_REGISTRY, YOUR_VPS_IP, agent.example.com). The image is built from deploy/mail/
+# and published separately — Kamal accessories pull a prebuilt image, they don't build one.
+#
+# Note: `kamal deploy` does NOT boot accessories. After deploying, run: kamal accessory boot mail
+#
+# The only secret is RAILS_INBOUND_EMAIL_PASSWORD (must be present in .kamal/secrets) — it authenticates
+# both the inbound relay POST and the provisioning push from the app. DKIM keys are NOT a secret here:
+# the app pushes them to the accessory's internal provisioning listener whenever a domain changes, and
+# they persist on the protege_mail_provision volume across restarts.
+#
+# For the app to reach this accessory, set MAIL_RELAY_HOST: protege-mail in the APP service's env (the
+# same name it already delivers outbound SMTP to). The provisioning listener is internal-only — do not
+# publish its port; port 25 is the sole exposed port.
+
+accessories:
+  mail:
+    image: YOUR_REGISTRY/protege-mail:latest
+    host: YOUR_VPS_IP
+    port: "25:25"            # MX inbound + direct outbound delivery (provisioning listener stays internal)
+    env:
+      clear:
+        MAIL_DOMAIN: agent.example.com   # the MTA's own FQDN (HELO/PTR); agent domains come from the app
+        APP_RELAY_URL: https://agent.example.com/rails/action_mailbox/relay/inbound_emails
+        DMARC_POLICY: enforce            # inbound SPF/DKIM/DMARC; "monitor" to observe before rejecting
+      secret:
+        - RAILS_INBOUND_EMAIL_PASSWORD   # relay ingress + provisioning-push auth (shared with the app)
+    volumes:
+      - "protege_mail_spool:/var/spool/postfix"        # persist the Postfix queue across restarts
+      - "protege_mail_provision:/var/lib/protege-mail" # persist pushed DKIM keys + cached manifest

data/lib/generators/protege/postfix/templates/deploy/mail/main.cf

@@ -0,0 +1,68 @@
+# Postfix main configuration for the Protege mail accessory.
+#
+# __MAIL_DOMAIN__ is substituted by entrypoint.sh from the MAIL_DOMAIN env var at container start, so
+# the same image works for any agent domain.
+
+# Identity / banner. myhostname must match the PTR (reverse DNS) of the VPS IP for good deliverability.
+myhostname = __MAIL_DOMAIN__
+mydomain = __MAIL_DOMAIN__
+myorigin = $mydomain
+
+# Listen on all interfaces (port 25 is published to the host by the Kamal accessory) and use IPv4.
+inet_interfaces = all
+inet_protocols = ipv4
+
+# Inbound: accept mail addressed to any agent domain we serve. We do NOT deliver locally — the served
+# domains are listed in relay_domains (so reject_unauth_destination permits them) and routed to the
+# action-mailbox pipe (see master.cf) via the transport map, which forwards each to the Rails relay
+# ingress. Both are generated per-domain at runtime by provision.py from the manifest the app pushes —
+# relay_domains is set via `postconf -e`, and transport is a hash map — so one image serves every domain.
+mydestination =
+relay_domains =
+transport_maps = hash:/etc/postfix/transport
+
+# Relay control: the app container (on the Kamal network) hands us outbound mail. Trust RFC1918 ranges
+# so the Docker/Kamal bridge network can relay; reject everything else (no open relay).
+mynetworks = 127.0.0.0/8 [::1]/128 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
+smtpd_relay_restrictions = permit_mynetworks reject_unauth_destination
+
+# Inbound SPF: hand each remote sender to the policyd-spf policy service, which rejects explicit hard
+# fails (the domain's "-all") and stamps an Authentication-Results header for OpenDMARC to consume.
+# permit_mynetworks runs first, so our own outbound (the app container) skips the SPF check. The spawn
+# service is registered in master.cf at runtime by entrypoint.sh; the time limit must exceed its DNS work.
+smtpd_recipient_restrictions =
+  permit_mynetworks,
+  reject_unauth_destination,
+  check_policy_service unix:private/policyd-spf
+policyd-spf_time_limit = 3600
+
+# Outbound: deliver directly to recipient MX (no smarthost / relay provider). Requires outbound port 25.
+relayhost =
+
+# Milters. OpenDKIM (8891) signs outbound + verifies inbound DKIM. OpenDMARC (8893) runs AFTER it on
+# inbound: it reads the SPF (policyd-spf) and DKIM (OpenDKIM) Authentication-Results, evaluates DMARC,
+# and rejects spoofed/failing mail when the sender publishes p=reject (see opendmarc.conf RejectFailures).
+# Order matters — OpenDKIM must precede OpenDMARC so its result is present. milter_default_action = accept
+# fails open: a milter outage lets mail through rather than bouncing everything. non_smtpd_milters stays
+# OpenDKIM-only — locally reinjected/outbound mail is signed, not DMARC-checked.
+milter_default_action = accept
+milter_protocol = 6
+smtpd_milters = inet:127.0.0.1:8891, inet:127.0.0.1:8893
+non_smtpd_milters = inet:127.0.0.1:8891
+
+# TLS for opportunistic encryption. The entrypoint generates a self-signed cert at /etc/postfix/tls so
+# inbound STARTTLS handshakes complete — Postfix advertises STARTTLS, and TLS-preferring senders (e.g.
+# Gmail) refuse to downgrade, so a missing cert means mail never delivers. Opportunistic MX TLS does
+# not validate the peer cert, so self-signed is sufficient.
+smtp_tls_security_level  = may
+smtpd_tls_security_level = may
+smtp_tls_CAfile          = /etc/ssl/certs/ca-certificates.crt
+smtpd_tls_cert_file      = /etc/postfix/tls/cert.pem
+smtpd_tls_key_file       = /etc/postfix/tls/key.pem
+
+# Modern Postfix housekeeping.
+compatibility_level = 3.6
+maillog_file = /dev/stdout
+
+# Size limit (25 MB) — agent mail is text/attachments, not bulk.
+message_size_limit = 26214400

data/lib/generators/protege/postfix/templates/deploy/mail/opendkim.conf

@@ -0,0 +1,36 @@
+# OpenDKIM configuration for the Protege mail accessory.
+#
+# Signs outbound mail for the agent domain with the key materialized from EmailDomain (DKIM_PRIVATE_KEY,
+# selector "default") and verifies inbound signatures. Postfix talks to it over the inet milter socket.
+
+# Sign and verify.
+Mode                    sv
+UserID                  opendkim
+
+# Milter socket — must match smtpd_milters/non_smtpd_milters in main.cf.
+Socket                  inet:8891@127.0.0.1
+
+# Map sender domains to selectors/keys (KeyTable) and decide what to sign (SigningTable). TrustedHosts
+# lists internal hosts whose mail is signed rather than verified.
+KeyTable                /etc/opendkim/KeyTable
+SigningTable            refile:/etc/opendkim/SigningTable
+InternalHosts           /etc/opendkim/TrustedHosts
+ExternalIgnoreList      /etc/opendkim/TrustedHosts
+
+# Canonicalization: relaxed/simple is the widely-compatible default (survives minor in-transit edits to
+# headers without breaking the body hash).
+Canonicalization        relaxed/simple
+
+# Stamp the inbound DKIM verdict into an Authentication-Results header under this authserv-id. OpenDMARC
+# (which runs next in the milter chain) trusts the same id and reads the DKIM result from here for the
+# DKIM-alignment half of DMARC. Keep it identical to opendmarc.conf's AuthservID/TrustedAuthservIDs and
+# policyd-spf.conf's Authserv_Id.
+AuthservID              protege
+
+SignatureAlgorithm      rsa-sha256
+OversignHeaders         From
+
+# Logging to syslog (tailed to stdout via rsyslog).
+Syslog                  yes
+SyslogSuccess           yes
+UMask                   002

data/lib/generators/protege/postfix/templates/deploy/mail/opendmarc.conf

@@ -0,0 +1,32 @@
+# OpenDMARC configuration for the Protege mail accessory.
+#
+# OpenDMARC is the inbound enforcement linchpin: it reads the SPF result (from policyd-spf) and the DKIM
+# result (from OpenDKIM) out of the Authentication-Results headers stamped under our shared authserv-id,
+# evaluates DMARC alignment against the sender domain's published policy, and rejects messages that fail
+# when that policy says p=reject. Runs as a milter AFTER OpenDKIM (see smtpd_milters order in main.cf).
+
+# Shared authserv-id. Both OpenDKIM and policyd-spf stamp Authentication-Results under this name, and
+# OpenDMARC only trusts results bearing it (TrustedAuthservIDs) — so a forged A-R header from a remote
+# sender is ignored.
+AuthservID              protege
+TrustedAuthservIDs      protege
+
+# Milter socket — must match the second entry in main.cf's smtpd_milters.
+Socket                  inet:8893@127.0.0.1
+PidFile                 /run/opendmarc/opendmarc.pid
+UserID                  opendmarc
+
+# Don't DMARC-check mail we ourselves authenticated/relayed, and skip our internal ranges (the app
+# container's outbound mail) — those are listed in ignore.hosts.
+IgnoreAuthenticatedClients true
+IgnoreHosts             /etc/opendmarc/ignore.hosts
+
+# Reject at SMTP when a message fails DMARC and the sender publishes p=reject. The placeholder is
+# substituted from the DMARC_POLICY env var by entrypoint.sh: "enforce" -> true, anything else -> false
+# (monitor mode: evaluate + stamp headers, reject nothing).
+RejectFailures          __DMARC_REJECT__
+
+# Honor the sender's p=quarantine as a soft signal rather than a reject (we have no spam folder; the
+# Authentication-Results header still records the failure for the app/audit).
+SoftwareHeader          true
+Syslog                  true

data/lib/generators/protege/postfix/templates/deploy/mail/opendmarc.ignore.hosts

@@ -0,0 +1,9 @@
+# Hosts OpenDMARC must NOT evaluate — our own infrastructure. The app container relays outbound mail
+# from the Kamal/Docker bridge (RFC1918), and we don't DMARC-check our own outbound. Mirrors the
+# OpenDKIM TrustedHosts and main.cf mynetworks ranges.
+127.0.0.1
+::1
+localhost
+10.0.0.0/8
+172.16.0.0/12
+192.168.0.0/16

data/lib/generators/protege/postfix/templates/deploy/mail/policyd-spf.conf

@@ -0,0 +1,21 @@
+# postfix-policyd-spf-python configuration for the Protege mail accessory.
+#
+# Runs as a Postfix policy service (see the spawn entry registered by entrypoint.sh and the
+# check_policy_service line in main.cf). It checks the sending IP against the envelope domain's SPF
+# record and feeds the result to OpenDMARC. permit_mynetworks runs first in main.cf, so our own
+# outbound (the app container) never reaches this service.
+
+# Reject only an explicit hard fail (the domain published "-all" — it disavows this IP). Soft fails
+# (~all) and neutral/none are NOT rejected here; DMARC arbitrates those so legitimate forwarded mail
+# that still DKIM-aligns can pass.
+HELO_reject = False
+Mail_From_reject = Fail
+
+# Don't reject on transient/permanent SPF lookup problems — annotate and move on (DMARC decides).
+PermError_reject = False
+TempError_Defer = False
+
+# Emit the SPF verdict as an Authentication-Results header under the shared authserv-id so OpenDMARC
+# trusts and consumes it for the SPF-alignment half of DMARC.
+Header_Type = AR
+Authserv_Id = protege