4ward 0.1.0

package/crates/4ward-cli/templates/template.yaml

@@ -0,0 +1,388 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: "4ward - zero-idle-cost serverless email engine (SES inbound SRS forwarder + transactional API)"
+
+Parameters:
+  ProjectName:
+    Type: String
+    Default: 4ward
+    Description: Project / stack prefix
+  DomainName:
+    Type: String
+    Description: Primary verified domain (e.g. example.com)
+  RelayDomain:
+    Type: String
+    Description: Relay From domain (defaults to DomainName)
+    Default: ""
+  AliasMapJson:
+    Type: String
+    Default: "{}"
+    Description: JSON map alias@domain -> [destinations]
+  CatchAll:
+    Type: String
+    Default: ""
+    Description: Optional fallback destination
+  BannerEnabled:
+    Type: String
+    Default: "true"
+    AllowedValues: ["true", "false"]
+  ApiEnabled:
+    Type: String
+    Default: "true"
+    AllowedValues: ["true", "false"]
+  AllowedDomains:
+    Type: String
+    Default: ""
+    Description: Comma-separated verified From domains for POST /v1/emails
+  ApiKeysPrefix:
+    Type: String
+    Default: /4ward/api-keys/
+  RetentionDays:
+    Type: Number
+    Default: 1
+  RateLimit:
+    Type: Number
+    Default: 100
+    Description: HTTP API steady-state requests/second (stage throttling)
+  Burst:
+    Type: Number
+    Default: 200
+    Description: HTTP API burst limit (stage throttling)
+  ArcSelector:
+    Type: String
+    Default: ""
+    Description: ARC seal selector (empty = no ARC sealing)
+  ArcKeySsm:
+    Type: String
+    Default: ""
+    Description: SSM SecureString parameter holding the ARC RSA private PEM (empty = no ARC sealing)
+  ForwarderS3Key:
+    Type: String
+    Default: bootstrap.zip
+    Description: S3 key for forwarder lambda zip (same bucket as template or use local packaging)
+  ApiS3Key:
+    Type: String
+    Default: bootstrap.zip
+  LambdaCodeBucket:
+    Type: String
+    Default: ""
+    Description: S3 bucket holding lambda zips; leave empty to skip S3 code (inline placeholder)
+
+Conditions:
+  HasCodeBucket: !Not [!Equals [!Ref LambdaCodeBucket, ""]]
+  HasCatchAll: !Not [!Equals [!Ref CatchAll, ""]]
+  ApiOn: !Equals [!Ref ApiEnabled, "true"]
+  HasRelayDomain: !Not [!Equals [!Ref RelayDomain, ""]]
+  HasArc: !Not [!Equals [!Ref ArcKeySsm, ""]]
+
+Resources:
+  RawBucket:
+    Type: AWS::S3::Bucket
+    DependsOn: S3InvokePermission
+    Properties:
+      BucketName: !Sub "${ProjectName}-raw-${AWS::AccountId}-${AWS::Region}"
+      BucketEncryption:
+        ServerSideEncryptionConfiguration:
+          - ServerSideEncryptionByDefault:
+              SSEAlgorithm: AES256
+      LifecycleConfiguration:
+        Rules:
+          - Id: ExpireRawAfter24h
+            Status: Enabled
+            ExpirationInDays: !Ref RetentionDays
+      PublicAccessBlockConfiguration:
+        BlockPublicAcls: true
+        BlockPublicPolicy: true
+        IgnorePublicAcls: true
+        RestrictPublicBuckets: true
+      NotificationConfiguration:
+        LambdaConfigurations:
+          - Event: s3:ObjectCreated:*
+            Function: !GetAtt ForwarderFunction.Arn
+            Filter:
+              S3KeyFilter:
+                Rules:
+                  - Name: prefix
+                    Value: inbound/
+
+  RawBucketPolicy:
+    Type: AWS::S3::BucketPolicy
+    Properties:
+      Bucket: !Sub "${ProjectName}-raw-${AWS::AccountId}-${AWS::Region}"
+      PolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Sid: AllowSESInboundWrite
+            Effect: Allow
+            Principal:
+              Service: ses.amazonaws.com
+            Action: s3:PutObject
+            Resource: !Sub "arn:aws:s3:::${ProjectName}-raw-${AWS::AccountId}-${AWS::Region}/*"
+
+  EmailIdentity:
+    Type: AWS::SES::EmailIdentity
+    Properties:
+      EmailIdentity: !Ref DomainName
+      DkimSigningAttributes:
+        NextSigningKeyLength: RSA_2048_BIT
+      DkimAttributes:
+        SigningEnabled: true
+
+  ForwarderRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: lambda.amazonaws.com
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+      Policies:
+        - PolicyName: ForwarderAccess
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: [s3:GetObject]
+                Resource: !Sub "arn:aws:s3:::${ProjectName}-raw-${AWS::AccountId}-${AWS::Region}/*"
+              - Effect: Allow
+                Action: [ses:SendEmail, ses:SendRawEmail]
+                Resource: "*"
+
+  ApiRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: lambda.amazonaws.com
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+      Policies:
+        - PolicyName: ApiAccess
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: [ses:SendEmail, ses:SendRawEmail]
+                Resource: "*"
+              - Effect: Allow
+                Action: [ssm:DescribeParameters, ssm:GetParameter]
+                Resource: "*"
+
+  ForwarderFunction:
+    Type: AWS::Lambda::Function
+    Properties:
+      FunctionName: !Sub "${ProjectName}-forwarder"
+      Architectures: [arm64]
+      Runtime: provided.al2023
+      Handler: bootstrap
+      MemorySize: 512
+      Timeout: 30
+      Role: !GetAtt ForwarderRole.Arn
+      Code:
+        S3Bucket: !If [HasCodeBucket, !Ref LambdaCodeBucket, !Ref AWS::NoValue]
+        S3Key: !If [HasCodeBucket, !Ref ForwarderS3Key, !Ref AWS::NoValue]
+        ZipFile: !If
+          - HasCodeBucket
+          - !Ref AWS::NoValue
+          - |
+            #!/bin/sh
+            echo 4ward-forwarder-placeholder
+      Environment:
+        Variables:
+          RELAY_DOMAIN: !If [HasRelayDomain, !Ref RelayDomain, !Ref DomainName]
+          ALIAS_MAP_JSON: !Ref AliasMapJson
+          CATCH_ALL: !Ref CatchAll
+          BANNER_ENABLED: !Ref BannerEnabled
+          CONFIG_SET: !Ref MailConfigSet
+          ARC_SELECTOR: !If [HasArc, !Ref ArcSelector, !Ref "AWS::NoValue"]
+          ARC_PRIVATE_KEY: !If
+            - HasArc
+            - !Sub "{{resolve:ssm-secure:${ArcKeySsm}:1}}"
+            - !Ref "AWS::NoValue"
+          RUST_LOG: info
+
+  ApiFunction:
+    Type: AWS::Lambda::Function
+    Condition: ApiOn
+    Properties:
+      FunctionName: !Sub "${ProjectName}-api"
+      Architectures: [arm64]
+      Runtime: provided.al2023
+      Handler: bootstrap
+      MemorySize: 512
+      Timeout: 30
+      Role: !GetAtt ApiRole.Arn
+      Code:
+        S3Bucket: !If [HasCodeBucket, !Ref LambdaCodeBucket, !Ref AWS::NoValue]
+        S3Key: !If [HasCodeBucket, !Ref ApiS3Key, !Ref AWS::NoValue]
+        ZipFile: !If
+          - HasCodeBucket
+          - !Ref AWS::NoValue
+          - |
+            #!/bin/sh
+            echo 4ward-api-placeholder
+      Environment:
+        Variables:
+          ALLOWED_DOMAINS: !Ref AllowedDomains
+          API_KEYS_PREFIX: !Ref ApiKeysPrefix
+          CONFIG_SET: !Ref MailConfigSet
+          RUST_LOG: info
+
+  S3InvokePermission:
+    Type: AWS::Lambda::Permission
+    Properties:
+      FunctionName: !GetAtt ForwarderFunction.Arn
+      Action: lambda:InvokeFunction
+      Principal: s3.amazonaws.com
+      SourceArn: !Sub "arn:aws:s3:::${ProjectName}-raw-${AWS::AccountId}-${AWS::Region}"
+
+  ReceiptRuleSet:
+    Type: AWS::SES::ReceiptRuleSet
+    Properties:
+      Name: !Sub "${ProjectName}-inbound"
+
+  ReceiptRule:
+    Type: AWS::SES::ReceiptRule
+    Properties:
+      RuleSetName: !Ref ReceiptRuleSet
+      Rule:
+        Name: !Sub "${ProjectName}-forward"
+        Enabled: true
+        ScanEnabled: true
+        Recipients:
+          - !Ref DomainName
+        Actions:
+          # S3 only: the S3 ObjectCreated event triggers the forwarder.
+          # (A LambdaAction here would double-invoke with a non-S3 event.)
+          - S3Action:
+              BucketName: !Ref RawBucket
+              ObjectKeyPrefix: inbound/
+
+  HttpApi:
+    Type: AWS::ApiGatewayV2::Api
+    Condition: ApiOn
+    Properties:
+      Name: !Sub "${ProjectName}-api"
+      ProtocolType: HTTP
+      CorsConfiguration:
+        AllowOrigins: ["*"]
+        AllowMethods: [POST, OPTIONS]
+        AllowHeaders: [authorization, content-type]
+
+  HttpStage:
+    Type: AWS::ApiGatewayV2::Stage
+    Condition: ApiOn
+    Properties:
+      ApiId: !Ref HttpApi
+      StageName: $default
+      AutoDeploy: true
+      DefaultRouteSettings:
+        ThrottlingBurstLimit: !Ref Burst
+        ThrottlingRateLimit: !Ref RateLimit
+
+  HttpIntegration:
+    Type: AWS::ApiGatewayV2::Integration
+    Condition: ApiOn
+    Properties:
+      ApiId: !Ref HttpApi
+      IntegrationType: AWS_PROXY
+      IntegrationUri: !GetAtt ApiFunction.Arn
+      PayloadFormatVersion: "2.0"
+
+  HttpRoute:
+    Type: AWS::ApiGatewayV2::Route
+    Condition: ApiOn
+    Properties:
+      ApiId: !Ref HttpApi
+      RouteKey: POST /v1/emails
+      Target: !Sub "integrations/${HttpIntegration}"
+
+  ApiInvokePermission:
+    Type: AWS::Lambda::Permission
+    Condition: ApiOn
+    Properties:
+      FunctionName: !Ref ApiFunction
+      Action: lambda:InvokeFunction
+      Principal: apigateway.amazonaws.com
+      SourceArn: !Sub "arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${HttpApi}/*/*"
+
+  BounceTopic:
+    Type: AWS::SNS::Topic
+    Properties:
+      TopicName: !Sub "${ProjectName}-bounces"
+
+  ComplaintTopic:
+    Type: AWS::SNS::Topic
+    Properties:
+      TopicName: !Sub "${ProjectName}-complaints"
+
+  MailConfigSet:
+    Type: AWS::SES::ConfigurationSet
+    Properties:
+      Name: !Sub "${ProjectName}-mail"
+
+  BounceEventDestination:
+    Type: AWS::SES::ConfigurationSetEventDestination
+    Properties:
+      ConfigurationSetName: !Ref MailConfigSet
+      EventDestination:
+        Name: bounce-to-sns
+        Enabled: true
+        MatchingEventTypes: [bounce]
+        SnsDestination:
+          TopicARN: !Ref BounceTopic
+
+  ComplaintEventDestination:
+    Type: AWS::SES::ConfigurationSetEventDestination
+    Properties:
+      ConfigurationSetName: !Ref MailConfigSet
+      EventDestination:
+        Name: complaint-to-sns
+        Enabled: true
+        MatchingEventTypes: [complaint]
+        SnsDestination:
+          TopicARN: !Ref ComplaintTopic
+
+  BounceAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: !Sub "${ProjectName}-bounce-rate"
+      Namespace: AWS/SES
+      MetricName: Reputation.BounceRate
+      Statistic: Average
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 0.05
+      ComparisonOperator: GreaterThanThreshold
+      Dimensions: []
+
+  ComplaintAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: !Sub "${ProjectName}-complaint-rate"
+      Namespace: AWS/SES
+      MetricName: Reputation.ComplaintRate
+      Statistic: Average
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 0.001
+      ComparisonOperator: GreaterThanThreshold
+      Dimensions: []
+
+Outputs:
+  RawBucketName:
+    Value: !Ref RawBucket
+  ForwarderName:
+    Value: !Ref ForwarderFunction
+  ApiEndpoint:
+    Condition: ApiOn
+    Value: !Sub "https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}"
+  DkimNote:
+    Value: Fetch DKIM CNAME tokens via SES console or `4ward dns` after deploy.

package/crates/4ward-core/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "fourward-core"
+version = "0.1.0"
+edition = "2021"
+description = "Domain logic, models and configuration schemas for 4ward"
+
+[lib]
+name = "fourward_core"
+path = "src/lib.rs"
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "2"
+validator = { version = "0.20", features = ["derive"] }

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

@@ -0,0 +1,261 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use thiserror::Error;
+
+fn default_profile() -> String {
+    "default".to_string()
+}
+
+fn default_true() -> bool {
+    true
+}
+
+fn default_retention() -> u32 {
+    1
+}
+
+fn default_sender_format() -> String {
+    "{name} (via {alias}) <relay@{domain}>".to_string()
+}
+
+#[derive(Debug, Error)]
+pub enum ConfigError {
+    #[error("failed to parse config: {0}")]
+    Parse(#[from] serde_json::Error),
+    #[error("validation error: {0}")]
+    Validation(String),
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct FourwardConfig {
+    #[serde(default = "default_version")]
+    pub version: String,
+    pub project: String,
+    pub aws: AwsConfig,
+    pub api: ApiConfig,
+    #[serde(default)]
+    pub settings: EngineSettings,
+    pub domains: Vec<DomainConfig>,
+}
+
+fn default_version() -> String {
+    "1".to_string()
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct AwsConfig {
+    pub region: String,
+    #[serde(default = "default_profile")]
+    pub profile: String,
+    pub stack_name: String,
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct ApiConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+    #[serde(default)]
+    pub cors: Vec<String>,
+    #[serde(default)]
+    pub rate_limit: RateLimitConfig,
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone, Default)]
+pub struct RateLimitConfig {
+    #[serde(default = "default_rps")]
+    pub requests_per_second: u32,
+    #[serde(default = "default_burst")]
+    pub burst: u32,
+}
+
+fn default_rps() -> u32 {
+    100
+}
+
+fn default_burst() -> u32 {
+    200
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct EngineSettings {
+    #[serde(default = "default_true")]
+    pub banner_enabled: bool,
+    #[serde(default = "default_retention")]
+    pub retention_days: u32,
+    #[serde(default = "default_sender_format")]
+    pub sender_format: String,
+}
+
+impl Default for EngineSettings {
+    fn default() -> Self {
+        Self {
+            banner_enabled: true,
+            retention_days: 1,
+            sender_format: default_sender_format(),
+        }
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum DnsProvider {
+    #[default]
+    Route53,
+    External,
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct DomainConfig {
+    pub domain: String,
+    #[serde(default)]
+    pub dns_provider: DnsProvider,
+    pub catch_all: Option<String>,
+    #[serde(default)]
+    pub routes: HashMap<String, Vec<String>>,
+}
+
+impl FourwardConfig {
+    pub fn from_json(s: &str) -> Result<Self, ConfigError> {
+        let cfg: Self = serde_json::from_str(s)?;
+        cfg.validate()?;
+        Ok(cfg)
+    }
+
+    pub fn from_file_contents(s: &str) -> Result<Self, ConfigError> {
+        Self::from_json(s)
+    }
+
+    pub fn validate(&self) -> Result<(), ConfigError> {
+        if self.project.trim().is_empty() {
+            return Err(ConfigError::Validation("project must not be empty".into()));
+        }
+        if self.domains.is_empty() {
+            return Err(ConfigError::Validation(
+                "at least one domain is required".into(),
+            ));
+        }
+        for d in &self.domains {
+            if !d.domain.contains('.') {
+                return Err(ConfigError::Validation(format!(
+                    "invalid domain: {}",
+                    d.domain
+                )));
+            }
+            for (alias, dests) in &d.routes {
+                if alias.trim().is_empty() {
+                    return Err(ConfigError::Validation("alias must not be empty".into()));
+                }
+                if dests.is_empty() {
+                    return Err(ConfigError::Validation(format!(
+                        "alias '{alias}' must have at least one destination"
+                    )));
+                }
+                for dest in dests {
+                    if !dest.contains('@') {
+                        return Err(ConfigError::Validation(format!(
+                            "invalid destination email: {dest}"
+                        )));
+                    }
+                }
+            }
+            if let Some(catch) = &d.catch_all {
+                if !catch.contains('@') {
+                    return Err(ConfigError::Validation(format!(
+                        "invalid catch_all email: {catch}"
+                    )));
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// Resolve destinations for `alias@domain`. Falls back to catch-all.
+    pub fn resolve(&self, alias: &str, domain: &str) -> Vec<String> {
+        for d in &self.domains {
+            if d.domain.eq_ignore_ascii_case(domain) {
+                if let Some(dests) = d.routes.get(alias) {
+                    return dests.clone();
+                }
+                // case-insensitive alias lookup
+                for (k, v) in &d.routes {
+                    if k.eq_ignore_ascii_case(alias) {
+                        return v.clone();
+                    }
+                }
+                if let Some(catch) = &d.catch_all {
+                    return vec![catch.clone()];
+                }
+                return vec![];
+            }
+        }
+        vec![]
+    }
+
+    /// Render the `From:` display address for a relayed message.
+    pub fn render_sender(&self, sender_name: &str, alias: &str, domain: &str) -> String {
+        let name = if sender_name.trim().is_empty() {
+            alias.to_string()
+        } else {
+            sender_name.to_string()
+        };
+        self.settings
+            .sender_format
+            .replace("{name}", &name)
+            .replace("{alias}", alias)
+            .replace("{domain}", domain)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample() -> &'static str {
+        r#"{
+            "version": "1",
+            "project": "demo",
+            "aws": {"region": "us-east-1", "profile": "default", "stack_name": "fourward-demo"},
+            "api": {"enabled": true, "cors": ["*"], "rate_limit": {"requests_per_second": 100, "burst": 200}},
+            "settings": {"banner_enabled": true, "retention_days": 1, "sender_format": "{name} (via {alias}) <relay@{domain}>"},
+            "domains": [
+                {"domain": "example.com", "dns_provider": "route53", "catch_all": "me@gmail.com", "routes": {"support": ["a@x.com", "b@x.com"]}}
+            ]
+        }"#
+    }
+
+    #[test]
+    fn parses_and_validates() {
+        let cfg = FourwardConfig::from_json(sample()).unwrap();
+        assert_eq!(cfg.project, "demo");
+        assert_eq!(cfg.domains.len(), 1);
+    }
+
+    #[test]
+    fn rejects_empty_domains() {
+        let mut cfg = FourwardConfig::from_json(sample()).unwrap();
+        cfg.domains.clear();
+        assert!(cfg.validate().is_err());
+    }
+
+    #[test]
+    fn resolves_routes_and_catch_all() {
+        let cfg = FourwardConfig::from_json(sample()).unwrap();
+        assert_eq!(
+            cfg.resolve("support", "example.com"),
+            vec!["a@x.com".to_string(), "b@x.com".to_string()]
+        );
+        assert_eq!(
+            cfg.resolve("unknown", "example.com"),
+            vec!["me@gmail.com".to_string()]
+        );
+        assert!(cfg.resolve("support", "other.com").is_empty());
+    }
+
+    #[test]
+    fn renders_sender() {
+        let cfg = FourwardConfig::from_json(sample()).unwrap();
+        let from = cfg.render_sender("Acme", "support", "example.com");
+        assert!(from.contains("relay@example.com"));
+        assert!(from.contains("via support"));
+    }
+}