From 7ee609913973c74f02c782da5b16e430bcda97d8 Mon Sep 17 00:00:00 2001
From: Will Anderson <will@neuralplatform.ai>
Date: Fri, 1 May 2026 22:49:32 -0500
Subject: [PATCH] dns: document email auth records and rationale for
 out-of-band management

SPF / DKIM / DMARC for neurontechnologies.ai are managed via the Cloudflare
API rather than Terraform because the cloudflare_record provider rewrites
name="@" on apply, which forces replacement of the apex SPF record and
opens a propagation gap. A duplicate (malformed-quoted) apex SPF that was
causing Gmail to fail SPF was also removed via the API; the surviving
record is the canonical one and is documented here for traceability.
---
 servers/gcp/dns-gcp.tf | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/servers/gcp/dns-gcp.tf b/servers/gcp/dns-gcp.tf
index 94e49be..8a09562 100644
--- a/servers/gcp/dns-gcp.tf
+++ b/servers/gcp/dns-gcp.tf
@@ -28,3 +28,36 @@ resource "cloudflare_record" "soma_wildcard" {
   proxied = true
   ttl     = 1
 }
+
+# ── Email authentication (managed via Cloudflare API, NOT Terraform) ─────────
+# Transactional email goes through Resend (smtp.resend.com) using the
+# `send.neurontechnologies.ai` subdomain as envelope-from. Workspace mail
+# flows through Google MX. Both signing domains (resend, google) DKIM-align
+# with the apex via the d= header so DMARC passes regardless of route.
+#
+# These records are intentionally NOT defined as Terraform resources:
+#   - The Cloudflare provider canonicalises `name = "@"` differently than the
+#     API's stored `name = "neurontechnologies.ai"`, which forces replacement
+#     of SPF on every `terraform apply` and would create a propagation gap.
+#   - Workspace MX/DKIM and the Resend records are stable enough that
+#     out-of-band Cloudflare-API management is safer than risking deletion
+#     during a routine apply.
+#
+# Current records (as of 2026-05-01):
+#   TXT  @                      v=spf1 include:_spf.google.com ~all
+#   TXT  send                   v=spf1 include:amazonses.com ~all
+#   MX   send                   feedback-smtp.us-east-1.amazonses.com (10)
+#   TXT  resend._domainkey      Resend DKIM key (verified in Resend dash)
+#   TXT  google._domainkey      Workspace DKIM key
+#   TXT  _dmarc                 v=DMARC1; p=quarantine; rua=mailto:admin@…
+#   MX   @ (x5)                 aspmx.l.google.com + 4 alt MX (Workspace)
+#
+# To change any of these, use the Cloudflare API directly:
+#   set -a; source ~/Secrets/credentials/infrastructure.env; set +a
+#   ZONE_ID=e844374f203dca4944d77d40ca0710ae
+#   curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/<id>" \
+#     -H "X-Auth-Email: $CF_EMAIL" -H "X-Auth-Key: $CF_API_KEY" \
+#     -d '{"content":"..."}'
+#
+# DO NOT remove or modify SPF / DKIM / DMARC without verifying replacements
+# first — losing any one will cause Gmail to junk transactional mail.