4ward 0.1.0

package/crates/4ward-core/src/dns.rs

@@ -0,0 +1,126 @@
+//! DNS record generation for SES verification, reception and deliverability.
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
+pub struct DnsRecord {
+    /// e.g. "MX", "TXT", "CNAME"
+    pub record_type: String,
+    /// Host / name (relative `@` means apex).
+    pub name: String,
+    /// Record value / rdata.
+    pub value: String,
+    pub ttl: u32,
+    pub purpose: String,
+}
+
+/// MX endpoint for SES inbound in a region.
+pub fn inbound_mx(region: &str) -> String {
+    format!("10 inbound-smtp.{region}.amazonaws.com")
+}
+
+/// SPF value authorizing SES for the domain.
+pub fn spf_value() -> String {
+    "v=spf1 include:amazonses.com ~all".to_string()
+}
+
+/// DMARC record value (reporting-only default).
+pub fn dmarc_value(rua: &str) -> String {
+    format!("v=DMARC1; p=none; rua=mailto:{rua}")
+}
+
+/// DKIM CNAME records issued by SES EasyDKIM (tokens resolved at deploy time).
+/// `tokens` are the 3 DkimTokens returned by SES; each maps to
+/// `<token>._domainkey.<domain> CNAME <token>.dkim.amazonses.com`.
+pub fn dkim_cnames(domain: &str, tokens: &[String]) -> Vec<DnsRecord> {
+    tokens
+        .iter()
+        .map(|t| DnsRecord {
+            record_type: "CNAME".to_string(),
+            name: format!("{t}._domainkey.{domain}"),
+            value: format!("{t}.dkim.amazonses.com"),
+            ttl: 300,
+            purpose: "SES EasyDKIM signing".to_string(),
+        })
+        .collect()
+}
+
+/// Full record set for an external-DNS domain (DKIM tokens optional/placeholder).
+pub fn records_for_domain(domain: &str, region: &str, dkim_tokens: &[String]) -> Vec<DnsRecord> {
+    let mut out = vec![
+        DnsRecord {
+            record_type: "MX".to_string(),
+            name: domain.to_string(),
+            value: inbound_mx(region),
+            ttl: 300,
+            purpose: "SES inbound reception".to_string(),
+        },
+        DnsRecord {
+            record_type: "TXT".to_string(),
+            name: domain.to_string(),
+            value: spf_value(),
+            ttl: 300,
+            purpose: "SPF authorize SES".to_string(),
+        },
+        DnsRecord {
+            record_type: "TXT".to_string(),
+            name: format!("_dmarc.{domain}"),
+            value: dmarc_value(&format!("dmarc@{domain}")),
+            ttl: 300,
+            purpose: "DMARC policy".to_string(),
+        },
+    ];
+    out.extend(dkim_cnames(domain, dkim_tokens));
+    out
+}
+
+/// Placeholder DKIM tokens for `4ward dns` output before SES issues real ones.
+pub fn placeholder_dkim_tokens() -> Vec<String> {
+    vec![
+        "token1".to_string(),
+        "token2".to_string(),
+        "token3".to_string(),
+    ]
+}
+
+/// ARC seal DNS record: same DKIM TXT format under `{selector}._domainkey`.
+/// `pubkey_b64` is the base64 DER of the RSA public key (`keys arc` prints it).
+pub fn arc_record(selector: &str, domain: &str, pubkey_b64: &str) -> DnsRecord {
+    DnsRecord {
+        record_type: "TXT".to_string(),
+        name: format!("{selector}._domainkey.{domain}"),
+        value: format!("v=DKIM1; k=rsa; p={pubkey_b64}"),
+        ttl: 300,
+        purpose: "4ward ARC seal signing".to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn mx_shape() {
+        assert_eq!(
+            inbound_mx("us-east-1"),
+            "10 inbound-smtp.us-east-1.amazonaws.com"
+        );
+    }
+
+    #[test]
+    fn spf_authorizes_ses() {
+        assert!(spf_value().contains("amazonses.com"));
+    }
+
+    #[test]
+    fn full_set_has_mx_spf_dmarc_plus_dkim() {
+        let recs = records_for_domain("example.com", "us-east-1", &placeholder_dkim_tokens());
+        assert_eq!(recs.len(), 6);
+        assert!(recs.iter().any(|r| r.record_type == "MX"));
+        assert!(recs.iter().any(|r| r.name.starts_with("_dmarc.")));
+        assert_eq!(
+            recs.iter().filter(|r| r.record_type == "CNAME").count(),
+            3
+        );
+    }
+}

package/crates/4ward-core/src/lib.rs

@@ -0,0 +1,5 @@
+pub mod config;
+pub mod dns;
+
+pub use config::*;
+pub use dns::*;

package/docs/assets/arch.svg

@@ -0,0 +1,44 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 470">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#FF7700"/>
+    </marker>
+  </defs>
+  <rect width="1280" height="470" fill="#0B0C0E"/>
+  <text x="60" y="52" font-family="Menlo,Consolas,monospace" font-size="22" letter-spacing="5" fill="#F5F5F7" opacity="0.6">HOW IT FLOWS</text>
+  <!-- inbound lane -->
+  <text x="60" y="118" font-family="Menlo,Consolas,monospace" font-size="24" letter-spacing="3" fill="#FF7700">INBOUND</text>
+  <g font-family="Arial,Helvetica,sans-serif" font-size="23" fill="#F5F5F7" text-anchor="middle">
+    <rect x="60" y="140" width="220" height="66" rx="10" fill="#1E2025"/>
+    <text x="170" y="181">SES Inbound</text>
+    <rect x="360" y="140" width="220" height="66" rx="10" fill="#1E2025"/>
+    <text x="470" y="181">S3 &#183; 24h TTL</text>
+    <rect x="660" y="140" width="260" height="66" rx="10" fill="#1E2025"/>
+    <text x="790" y="181">SRS Forwarder (arm64)</text>
+    <rect x="1000" y="140" width="220" height="66" rx="10" fill="#1E2025"/>
+    <text x="1110" y="181">Gmail / Outlook</text>
+  </g>
+  <g stroke="#FF7700" stroke-width="3">
+    <line x1="280" y1="173" x2="352" y2="173" marker-end="url(#arr)"/>
+    <line x1="580" y1="173" x2="652" y2="173" marker-end="url(#arr)"/>
+    <line x1="920" y1="173" x2="992" y2="173" marker-end="url(#arr)"/>
+  </g>
+  <!-- outbound lane -->
+  <text x="60" y="288" font-family="Menlo,Consolas,monospace" font-size="24" letter-spacing="3" fill="#FF7700">OUTBOUND</text>
+  <g font-family="Arial,Helvetica,sans-serif" font-size="23" fill="#F5F5F7" text-anchor="middle">
+    <rect x="60" y="310" width="220" height="66" rx="10" fill="#1E2025"/>
+    <text x="170" y="351">POST /v1/emails</text>
+    <rect x="360" y="310" width="260" height="66" rx="10" fill="#1E2025"/>
+    <text x="490" y="351">API Lambda + SSM keys</text>
+    <rect x="700" y="310" width="260" height="66" rx="10" fill="#1E2025"/>
+    <text x="830" y="351">SESv2 SendEmail</text>
+    <rect x="1040" y="310" width="180" height="66" rx="10" fill="#FF7700"/>
+    <text x="1130" y="351" fill="#0B0C0E">200 sent</text>
+  </g>
+  <g stroke="#FF7700" stroke-width="3">
+    <line x1="280" y1="343" x2="352" y2="343" marker-end="url(#arr)"/>
+    <line x1="620" y1="343" x2="692" y2="343" marker-end="url(#arr)"/>
+    <line x1="960" y1="343" x2="1032" y2="343" marker-end="url(#arr)"/>
+  </g>
+  <text x="60" y="430" font-family="Menlo,Consolas,monospace" font-size="20" fill="#F5F5F7" opacity="0.45">s3 + lambda + apigw + ses + cloudwatch alarms &#183; zero idle cost</text>
+</svg>

package/lambdas/api/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "lambda-api"
+version = "0.1.0"
+edition = "2021"
+
+[[bin]]
+name = "bootstrap"
+path = "src/main.rs"
+
+[dependencies]
+lambda_http = "0.14"
+aws-config = "1"
+aws-sdk-sesv2 = "1"
+aws-sdk-ssm = "1"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["full"] }
+base64 = { version = "0.22", features = ["std"] }
+mail-builder = "0.3"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }
+fourward-core = { path = "../../crates/4ward-core" }

package/lambdas/api/src/main.rs

@@ -0,0 +1,360 @@
+use base64::{engine::general_purpose::STANDARD as B64, Engine};
+use lambda_http::{run, service_fn, Body, Error, Request, RequestExt, Response};
+use mail_builder::MessageBuilder;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+use std::time::{Duration, Instant};
+
+#[derive(Debug, Deserialize, Clone)]
+pub struct AttachmentIn {
+    pub filename: String,
+    pub content: String, // base64
+    #[serde(default = "default_ctype")]
+    pub content_type: String,
+}
+
+fn default_ctype() -> String {
+    "application/octet-stream".to_string()
+}
+
+#[derive(Debug, Deserialize, Clone)]
+pub struct SendRequest {
+    pub from: String,
+    pub to: Vec<String>,
+    #[serde(default)]
+    pub cc: Vec<String>,
+    #[serde(default)]
+    pub bcc: Vec<String>,
+    #[serde(default)]
+    pub reply_to: Option<String>,
+    pub subject: String,
+    #[serde(default)]
+    pub html: Option<String>,
+    #[serde(default)]
+    pub text: Option<String>,
+    #[serde(default)]
+    pub attachments: Vec<AttachmentIn>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct SendResponse {
+    pub id: String,
+    pub status: String,
+}
+
+#[derive(Debug, Serialize)]
+struct ErrBody {
+    error: String,
+}
+
+// 60s in-memory SSM token cache: name -> (value, fetched_at)
+static TOKEN_CACHE: OnceLock<Mutex<HashMap<String, (String, Instant)>>> = OnceLock::new();
+fn cache() -> &'static Mutex<HashMap<String, (String, Instant)>> {
+    TOKEN_CACHE.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+pub fn bearer_token(auth: Option<&str>) -> Option<String> {
+    let h = auth?;
+    let h = h.trim();
+    let tok = h.strip_prefix("Bearer ").or_else(|| h.strip_prefix("bearer "))?;
+    let tok = tok.trim();
+    if tok.is_empty() {
+        None
+    } else {
+        Some(tok.to_string())
+    }
+}
+
+pub fn from_domain(from: &str) -> Option<String> {
+    let addr = if let Some(a) = from.rfind('<') {
+        from[a + 1..].trim_end_matches('>').trim().to_string()
+    } else {
+        from.trim().to_string()
+    };
+    addr.split_once('@').map(|(_, d)| d.trim().to_lowercase())
+}
+
+pub fn allowed_domains() -> Vec<String> {
+    std::env::var("ALLOWED_DOMAINS")
+        .unwrap_or_default()
+        .split(',')
+        .map(|s| s.trim().to_lowercase())
+        .filter(|s| !s.is_empty())
+        .collect()
+}
+
+pub fn validate_payload(req: &SendRequest) -> Result<(), String> {
+    if req.to.is_empty() {
+        return Err("to must contain at least one recipient".into());
+    }
+    if req.subject.trim().is_empty() {
+        return Err("subject is required".into());
+    }
+    if req.html.is_none() && req.text.is_none() {
+        return Err("html or text is required".into());
+    }
+    let dom = from_domain(&req.from).ok_or("invalid from address")?;
+    let allowed = allowed_domains();
+    if !allowed.is_empty() && !allowed.iter().any(|d| d == &dom) {
+        return Err(format!("from domain '{dom}' is not a verified identity"));
+    }
+    for a in &req.attachments {
+        if a.filename.trim().is_empty() {
+            return Err("attachment filename is required".into());
+        }
+        if B64.decode(a.content.trim()).is_err() {
+            return Err(format!("attachment '{}' is not valid base64", a.filename));
+        }
+    }
+    Ok(())
+}
+
+/// Build raw MIME for SESv2 SendEmail(Raw).
+pub fn build_raw(req: &SendRequest) -> Result<Vec<u8>, String> {
+    let mut b = MessageBuilder::new()
+        .from(req.from.as_str())
+        .to(req.to.iter().map(|s| s.as_str()).collect::<Vec<_>>())
+        .subject(req.subject.as_str());
+    if !req.cc.is_empty() {
+        b = b.cc(req.cc.iter().map(|s| s.as_str()).collect::<Vec<_>>());
+    }
+    if !req.bcc.is_empty() {
+        b = b.bcc(req.bcc.iter().map(|s| s.as_str()).collect::<Vec<_>>());
+    }
+    if let Some(r) = req.reply_to.as_deref() {
+        b = b.reply_to(r);
+    }
+    if let Some(t) = req.text.as_deref() {
+        b = b.text_body(t);
+    }
+    if let Some(h) = req.html.as_deref() {
+        b = b.html_body(h);
+    }
+    if req.text.is_none() && req.html.is_none() {
+        b = b.text_body("");
+    }
+    let mut decoded: Vec<(String, String, Vec<u8>)> = Vec::with_capacity(req.attachments.len());
+    for a in &req.attachments {
+        decoded.push((
+            a.content_type.clone(),
+            a.filename.clone(),
+            B64.decode(a.content.trim()).map_err(|e| e.to_string())?,
+        ));
+    }
+    for (ctype, fname, bytes) in &decoded {
+        b = b.attachment(ctype.as_str(), fname.as_str(), bytes.as_slice());
+    }
+    b.write_to_vec().map_err(|e| e.to_string())
+}
+
+async fn ssm_get(name: &str) -> Result<Option<String>, String> {
+    // Cache hit (60s TTL).
+    if let Ok(map) = cache().lock() {
+        if let Some((v, t)) = map.get(name) {
+            if t.elapsed() < Duration::from_secs(60) {
+                return Ok(Some(v.clone()));
+            }
+        }
+    }
+    let config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
+    let client = aws_sdk_ssm::Client::new(&config);
+    let prefix = std::env::var("API_KEYS_PREFIX").unwrap_or("/4ward/api-keys/".into());
+    // `name` here is the full token id suffix; we list keys and compare values.
+    // Tokens are stored as SecureString values; lookup by listing parameters under prefix.
+    let mut next: Option<String> = None;
+    loop {
+        let mut req = client.describe_parameters().parameter_filters(
+            aws_sdk_ssm::types::ParameterStringFilter::builder()
+                .key("Name")
+                .option("BeginsWith")
+                .values(&prefix)
+                .build()
+                .map_err(|e| e.to_string())?,
+        );
+        if let Some(t) = next {
+            req = req.next_token(t);
+        }
+        let out = req.send().await.map_err(|e| e.to_string())?;
+        let names: Vec<String> = out.parameters().iter().filter_map(|p| p.name().map(|s| s.to_string())).collect();
+        for n in names {
+            let v = client.get_parameter().name(&n).with_decryption(true).send().await;
+            if let Ok(v) = v {
+                if let Some(val) = v.parameter().and_then(|p| p.value()) {
+                    if val == name {
+                        if let Ok(mut map) = cache().lock() {
+                            map.insert(name.to_string(), (n.clone(), Instant::now()));
+                        }
+                        return Ok(Some(n));
+                    }
+                }
+            }
+        }
+        next = out.next_token().map(|s| s.to_string());
+        if next.is_none() {
+            break;
+        }
+    }
+    Ok(None)
+}
+
+async fn verify_bearer(token: &str) -> Result<bool, String> {
+    // Cache hit means previously validated.
+    if let Ok(map) = cache().lock() {
+        if let Some((_, t)) = map.get(token) {
+            if t.elapsed() < Duration::from_secs(60) {
+                return Ok(true);
+            }
+        }
+    }
+    Ok(ssm_get(token).await?.is_some())
+}
+
+fn json_resp(status: u16, body: impl Serialize) -> Result<Response<Body>, Error> {
+    let s = serde_json::to_string(&body).unwrap_or("{}".into());
+    Ok(Response::builder()
+        .status(status)
+        .header("content-type", "application/json")
+        .body(Body::from(s))
+        .unwrap())
+}
+
+async fn handler(event: Request) -> Result<Response<Body>, Error> {
+    // Only POST /v1/emails
+    let path = event.raw_http_path().to_string();
+    if event.method() != "POST" || !path.ends_with("/v1/emails") {
+        return json_resp(404, ErrBody { error: "not found".into() });
+    }
+    let auth = event.headers().get("authorization").and_then(|v| v.to_str().ok()).map(|s| s.to_string());
+    let token = bearer_token(auth.as_deref());
+    let token = match token {
+        None => return json_resp(401, ErrBody { error: "missing bearer token".into() }),
+        Some(t) => t,
+    };
+    if !token.starts_with("4w_live_") {
+        return json_resp(401, ErrBody { error: "invalid token".into() });
+    }
+    match verify_bearer(&token).await {
+        Ok(true) => {},
+        Ok(false) => return json_resp(401, ErrBody { error: "invalid token".into() }),
+        Err(e) => {
+            tracing::warn!(error = %e, "ssm verify failed");
+            return json_resp(500, ErrBody { error: "auth backend error".into() });
+        }
+    }
+    let body = match event.body() {
+        Body::Text(s) => s.as_bytes().to_vec(),
+        Body::Binary(b) => b.clone(),
+        Body::Empty => Vec::new(),
+    };
+    let req: SendRequest = match serde_json::from_slice(&body) {
+        Ok(r) => r,
+        Err(e) => return json_resp(400, ErrBody { error: format!("invalid payload: {e}") }),
+    };
+    if let Err(e) = validate_payload(&req) {
+        return json_resp(400, ErrBody { error: e });
+    }
+    let raw = match build_raw(&req) {
+        Ok(r) => r,
+        Err(e) => return json_resp(400, ErrBody { error: e }),
+    };
+    let config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
+    let ses = aws_sdk_sesv2::Client::new(&config);
+    let from_addr = if let Some(a) = req.from.rfind('<') {
+        req.from[a + 1..].trim_end_matches('>').trim().to_string()
+    } else {
+        req.from.trim().to_string()
+    };
+    let mut to_all = req.to.clone();
+    to_all.extend(req.cc.clone());
+    to_all.extend(req.bcc.clone());
+    let config_set = std::env::var("CONFIG_SET").ok().filter(|s| !s.trim().is_empty());
+    let out = ses
+        .send_email()
+        .from_email_address(&from_addr)
+        .set_configuration_set_name(config_set)
+        .set_destination(Some(
+            aws_sdk_sesv2::types::Destination::builder()
+                .set_to_addresses(Some(to_all))
+                .build(),
+        ))
+        .content(
+            aws_sdk_sesv2::types::EmailContent::builder()
+                .raw(aws_sdk_sesv2::types::RawMessage::builder().data(aws_sdk_sesv2::primitives::Blob::new(raw)).build().map_err(|e| format!("{e:?}"))?)
+                .build(),
+        )
+        .send()
+        .await;
+    match out {
+        Ok(o) => json_resp(200, SendResponse { id: o.message_id().unwrap_or("").to_string(), status: "sent".into() }),
+        Err(e) => {
+            tracing::warn!(error = %e, "ses send failed");
+            json_resp(502, ErrBody { error: "ses send failed".into() })
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing_subscriber::fmt()
+        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
+        .json()
+        .init();
+    run(service_fn(handler)).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn bearer_parsing() {
+        assert_eq!(bearer_token(Some("Bearer 4w_live_abc")).as_deref(), Some("4w_live_abc"));
+        assert!(bearer_token(Some("Bearer ")).is_none());
+        assert!(bearer_token(None).is_none());
+    }
+
+    #[test]
+    fn from_domain_parse() {
+        assert_eq!(from_domain("Acme <alerts@example.com>").as_deref(), Some("example.com"));
+        assert_eq!(from_domain("a@x.io").as_deref(), Some("x.io"));
+    }
+
+    #[test]
+    fn payload_validation() {
+        let good = SendRequest {
+            from: "Acme <alerts@example.com>".into(),
+            to: vec!["customer@domain.com".into()],
+            cc: vec![], bcc: vec![],
+            reply_to: Some("support@example.com".into()),
+            subject: "System Verification".into(),
+            html: Some("<p>Your code is: <strong>849201</strong></p>".into()),
+            text: Some("Your code is: 849201".into()),
+            attachments: vec![AttachmentIn { filename: "document.pdf".into(), content: "JVBERi0xLjQK".into(), content_type: "application/pdf".into() }],
+        };
+        assert!(validate_payload(&good).is_ok());
+        let mut bad = good.clone();
+        bad.to.clear();
+        assert!(validate_payload(&bad).is_err());
+        let mut bad2 = good.clone();
+        bad2.attachments[0].content = "!!!not-base64!!!".into();
+        assert!(validate_payload(&bad2).is_err());
+    }
+
+    #[test]
+    fn raw_build_includes_attachment() {
+        let req = SendRequest {
+            from: "Acme <alerts@example.com>".into(),
+            to: vec!["c@d.com".into()],
+            cc: vec![], bcc: vec![],
+            reply_to: None,
+            subject: "t".into(),
+            html: Some("<p>hi</p>".into()),
+            text: None,
+            attachments: vec![AttachmentIn { filename: "document.pdf".into(), content: "aGVsbG8=".into(), content_type: "application/pdf".into() }],
+        };
+        let raw = build_raw(&req).unwrap();
+        let s = String::from_utf8_lossy(&raw);
+        assert!(s.contains("document.pdf"), "attachment kept:\n{s}");
+    }
+}

package/lambdas/forwarder/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "lambda-forwarder"
+version = "0.1.0"
+edition = "2021"
+
+[[bin]]
+name = "bootstrap"
+path = "src/main.rs"
+
+[dependencies]
+lambda_runtime = "0.14"
+aws_lambda_events = "0.18"
+aws-config = "1"
+aws-sdk-s3 = "1"
+aws-sdk-sesv2 = "1"
+mail-parser = "0.11"
+mail-builder = "0.3"
+rsa = { version = "0.9", features = ["sha2"] }
+sha2 = "0.10"
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }
+fourward-core = { path = "../../crates/4ward-core" }
+base64 = "0.22"
+
+[dev-dependencies]
+rand = "0.8"