Harden Go edge services and centralize shared runtime policy

Author: borisolver

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # CleanApp Backend Architecture
 
-> Last updated: February 16, 2026
+> Last updated: March 6, 2026
 
 ## Overview
 
@@ -228,7 +228,7 @@ graph TB
         AREAS[Areas Service<br/>:9086]
         EMAIL[Email Service<br/>:9089]
         TAGS[Tags Service<br/>:9098]
-        OWN[Ownership Service<br/>:9090]
+        OWN[Ownership Service<br/>:9096 (prod)]
     end
     
     MOBILE --> CS
@@ -242,9 +242,20 @@ graph TB
     RL --> RAP
     RAP --> TAGS
     RAP --> EMAIL
-    RP --> TAGS
+RP --> TAGS
 ```
 
+### Shared Go Platform Layer (`go-common/`)
+
+The backend now has a small shared Go module for repeated cross-cutting behavior:
+
+- `go-common/appenv`: environment detection, required-secret loading, migration defaults
+- `go-common/edge`: centralized CORS, WebSocket origin checks, request-size limits, in-memory token-bucket rate limiting, security headers
+- `go-common/serverx`: hardened `http.Server` bootstrap with consistent timeouts
+- `go-common/jwtx`: shared JWT parsing helpers for local token validation
+
+This keeps security policy and service bootstrap logic consistent across the Go edge services instead of copying slight variants into each service.
+
 ### Public Ingest CLI (`@cleanapp/cli`)
 
 CleanApp ships a public npm CLI package for fetchers/agents:
@@ -479,12 +490,12 @@ graph LR
 | Service | Port | Language | Purpose |
 |---------|------|----------|---------|
 | `cleanapp_report_listener` | 9081 | Go | Receives reports via REST API |
-| `cleanapp_report_listener_v4` | 9099 | Go | Updated listener with bulk ingest |
+| `cleanapp_report_listener_v4` | 9097 | Rust | Read-optimized v4 API / OpenAPI surface |
 | `cleanapp_report_analyze_pipeline` | 9082 | Go | AI analysis (Gemini/OpenAI) |
 | `cleanapp_report_processor` | 9087 | Go | Additional processing logic |
 | `cleanapp_report_renderer_service` | 9093 | Rust | Image generation |
 | `cleanapp_report_tags_service` | 9098 | Rust | Tag management |
-| `cleanapp_report_ownership_service` | 9090 | Go | Report assignment |
+| `cleanapp_report_ownership_service` | 9096 (prod), 9090 (dev) | Go | Report assignment |
 
 ### Social Media & Web Indexing
 
@@ -761,6 +772,20 @@ Repo tooling:
 - Installer/uninstaller: `platform_blueprint/ops/watchdog/`
 - Laptop-run golden path: `platform_blueprint/tests/golden_path/golden_path_prod_vm.sh`
 
+### Runtime Migrations
+
+Runtime schema mutation is no longer the default for the hardened Go services.
+
+- Control flag: `DB_RUN_MIGRATIONS`
+- Default in production: `false`
+- Default in local dev / CI-style environments: `true`
+
+This means:
+
+1. production services fail fast on missing required secrets instead of inventing insecure defaults
+2. schema changes should happen through explicit migration/deploy steps
+3. service boot is more deterministic and requires fewer database privileges
+
 ### Deployment Process
 ```bash
 # Build & tag image
@@ -798,7 +823,7 @@ This flow:
 1. **Single database** - All services share one MySQL instance
 2. **No auto-scaling** - Manual VM management
 3. **No service mesh** - Direct container networking
-4. **Limited observability** - Basic Docker logs only (plus VM-local watchdog/smoke checks)
+4. **Partial observability** - Public uptime snapshot + VM-local watchdog exist, but centralized logs/traces are still limited
 5. **Container conflicts** - Docker Compose naming collisions on redeploy
 
 ---

README.md

@@ -247,7 +247,7 @@ where <env> is `LOCAL`, `DEV` or `PROD`.
 | report_processor | 9087 | 8080 | Report processing |
 | report_renderer_service | 9093 | 8080 | Image rendering |
 | report_tags_service | 9098 | 8080 | Tag management |
-| report_ownership_service | 9090 | 8080 | Ownership tracking |
+| report_ownership_service | 9096 (prod), 9090 (dev) | 8080 | Ownership tracking |
 
 ### Authentication & Customer Services
 | Service | Host Port | Container Port |

auth-service/config/config.go

@@ -1,11 +1,9 @@
 package config
 
 import (
-	"crypto/rand"
-	"encoding/hex"
-	"log"
-	"os"
 	"strings"
+
+	"cleanapp-common/appenv"
 )
 
 type Config struct {
@@ -20,8 +18,12 @@ type Config struct {
 	JWTSecret     string
 
 	// Server
-	Port           string
-	TrustedProxies []string
+	Port            string
+	TrustedProxies  []string
+	AllowedOrigins  []string
+	RunDBMigrations bool
+	RateLimitRPS    float64
+	RateLimitBurst  int
 
 	// OAuth Configuration
 	GoogleClientID     string
@@ -42,58 +44,69 @@ type Config struct {
 	FrontendURL string
 }
 
-func Load() *Config {
-	cfg := &Config{
-		DBUser:             getEnv("DB_USER", "root"),
-		DBPassword:         getEnv("DB_PASSWORD", "password"),
-		DBHost:             getEnv("DB_HOST", "localhost"),
-		DBPort:             getEnv("DB_PORT", "3306"),
-		JWTSecret:          getEnv("JWT_SECRET", "your-secret-key-here"),
-		Port:               getEnv("PORT", "8080"),
-		GoogleClientID:     getEnv("GOOGLE_CLIENT_ID", ""),
-		GoogleClientSecret: getEnv("GOOGLE_CLIENT_SECRET", ""),
-		FacebookAppID:      getEnv("FACEBOOK_APP_ID", ""),
-		FacebookAppSecret:  getEnv("FACEBOOK_APP_SECRET", ""),
-		AppleClientID:      getEnv("APPLE_CLIENT_ID", ""),
-		AppleTeamID:        getEnv("APPLE_TEAM_ID", ""),
-		AppleKeyID:         getEnv("APPLE_KEY_ID", ""),
-		ApplePrivateKey:    getEnv("APPLE_PRIVATE_KEY", ""),
+func Load() (*Config, error) {
+	dbPassword, err := appenv.Secret("DB_PASSWORD", "password")
+	if err != nil {
+		return nil, err
 	}
-
-	// Handle encryption key
-	encryptionKey := os.Getenv("ENCRYPTION_KEY")
-	if encryptionKey == "" {
-		// Generate a random key for demo - in production, use a fixed key
-		key := make([]byte, 32)
-		rand.Read(key)
-		encryptionKey = hex.EncodeToString(key)
-		log.Printf("WARNING: Generated temporary encryption key. Set ENCRYPTION_KEY environment variable for production.")
+	jwtSecret, err := appenv.Secret("JWT_SECRET", "dev-jwt-secret")
+	if err != nil {
+		return nil, err
+	}
+	encryptionKey, err := appenv.Secret("ENCRYPTION_KEY", devEncryptionKey())
+	if err != nil {
+		return nil, err
+	}
+	cfg := &Config{
+		DBUser:             appenv.String("DB_USER", "root"),
+		DBPassword:         dbPassword,
+		DBHost:             appenv.String("DB_HOST", "localhost"),
+		DBPort:             appenv.String("DB_PORT", "3306"),
+		JWTSecret:          jwtSecret,
+		EncryptionKey:      encryptionKey,
+		Port:               appenv.String("PORT", "8080"),
+		GoogleClientID:     appenv.String("GOOGLE_CLIENT_ID", ""),
+		GoogleClientSecret: appenv.String("GOOGLE_CLIENT_SECRET", ""),
+		FacebookAppID:      appenv.String("FACEBOOK_APP_ID", ""),
+		FacebookAppSecret:  appenv.String("FACEBOOK_APP_SECRET", ""),
+		AppleClientID:      appenv.String("APPLE_CLIENT_ID", ""),
+		AppleTeamID:        appenv.String("APPLE_TEAM_ID", ""),
+		AppleKeyID:         appenv.String("APPLE_KEY_ID", ""),
+		ApplePrivateKey:    appenv.String("APPLE_PRIVATE_KEY", ""),
+		AllowedOrigins:     authAllowedOrigins(),
+		RunDBMigrations:    appenv.Bool("DB_RUN_MIGRATIONS", appenv.DefaultRunMigrations()),
+		RateLimitRPS:       float64(appenv.Int("RATE_LIMIT_RPS", 10)),
+		RateLimitBurst:     appenv.Int("RATE_LIMIT_BURST", 20),
 	}
-	cfg.EncryptionKey = encryptionKey
 
 	// Handle trusted proxies
-	trustedProxies := os.Getenv("TRUSTED_PROXIES")
-	if trustedProxies != "" {
-		cfg.TrustedProxies = strings.Split(trustedProxies, ",")
-		for i, proxy := range cfg.TrustedProxies {
-			cfg.TrustedProxies[i] = strings.TrimSpace(proxy)
-		}
+	if trustedProxies := appenv.Strings("TRUSTED_PROXIES"); len(trustedProxies) > 0 {
+		cfg.TrustedProxies = trustedProxies
 	}
 
 	// Email configuration (SendGrid)
-	cfg.SendGridAPIKey = getEnv("SENDGRID_API_KEY", "")
-	cfg.SendGridFromName = getEnv("SENDGRID_FROM_NAME", "CleanApp")
-	cfg.SendGridFromEmail = getEnv("SENDGRID_FROM_EMAIL", "info@cleanapp.io")
+	cfg.SendGridAPIKey = appenv.String("SENDGRID_API_KEY", "")
+	cfg.SendGridFromName = appenv.String("SENDGRID_FROM_NAME", "CleanApp")
+	cfg.SendGridFromEmail = appenv.String("SENDGRID_FROM_EMAIL", "info@cleanapp.io")
 
 	// Frontend URL for password reset links
-	cfg.FrontendURL = getEnv("FRONTEND_URL", "https://cleanapp.io")
+	cfg.FrontendURL = appenv.String("FRONTEND_URL", "https://cleanapp.io")
 
-	return cfg
+	return cfg, nil
 }
 
-func getEnv(key, defaultValue string) string {
-	if value := os.Getenv(key); value != "" {
-		return value
+func authAllowedOrigins() []string {
+	if origins := appenv.Strings("ALLOWED_ORIGINS"); len(origins) > 0 {
+		return origins
+	}
+	frontendURL := appenv.String("FRONTEND_URL", "https://cleanapp.io")
+	origins := []string{frontendURL}
+	if strings.Contains(frontendURL, "://cleanapp.io") {
+		origins = append(origins, strings.Replace(frontendURL, "://cleanapp.io", "://www.cleanapp.io", 1))
 	}
-	return defaultValue
+	return origins
+}
+
+func devEncryptionKey() string {
+	return strings.Repeat("0", 64)
 }

auth-service/go.mod

@@ -1,18 +1,20 @@
 module auth-service
 
-go 1.23.0
+go 1.24.0
 
-toolchain go1.23.10
+toolchain go1.24.1
 
 require (
+	cleanapp-common v0.0.0
 	github.com/gin-gonic/gin v1.10.1
 	github.com/go-sql-driver/mysql v1.7.1
 	github.com/golang-jwt/jwt/v5 v5.2.0
-	github.com/sendgrid/rest v2.6.9+incompatible
 	github.com/sendgrid/sendgrid-go v3.14.0+incompatible
 	golang.org/x/crypto v0.36.0
 )
 
+replace cleanapp-common => ../go-common
+
 require (
 	github.com/bytedance/sonic v1.11.6 // indirect
 	github.com/bytedance/sonic/loader v0.1.1 // indirect
@@ -31,12 +33,14 @@ require (
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
+	github.com/sendgrid/rest v2.6.9+incompatible // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.12 // indirect
 	golang.org/x/arch v0.8.0 // indirect
 	golang.org/x/net v0.25.0 // indirect
 	golang.org/x/sys v0.31.0 // indirect
 	golang.org/x/text v0.23.0 // indirect
+	golang.org/x/time v0.12.0 // indirect
 	google.golang.org/protobuf v1.34.1 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

auth-service/go.sum

@@ -34,10 +34,6 @@ github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
-github.com/sendgrid/rest v2.6.9+incompatible h1:1EyIcsNdn9KIisLW50MKwmSRSK+ekueiEMJ7NEoxJo0=
-github.com/sendgrid/rest v2.6.9+incompatible/go.mod h1:kXX7q3jZtJXK5c5qK83bSGMdV6tsOE70KbHoqJls4lE=
-github.com/sendgrid/sendgrid-go v3.14.0+incompatible h1:KDSasSTktAqMJCYClHVE94Fcif2i7P7wzISv1sU6DUA=
-github.com/sendgrid/sendgrid-go v3.14.0+incompatible/go.mod h1:QRQt+LX/NmgVEvmdRw0VT/QgUn499+iza2FnDca9fg8=
 github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/klauspost/cpuid/v2 v2.2.7 h1:ZWSB3igEs+d0qvnxR/ZBzXVmxkgt8DdzP6m9pfuVLDM=
 github.com/klauspost/cpuid/v2 v2.2.7/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws=
@@ -55,6 +51,10 @@ github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6
 github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/sendgrid/rest v2.6.9+incompatible h1:1EyIcsNdn9KIisLW50MKwmSRSK+ekueiEMJ7NEoxJo0=
+github.com/sendgrid/rest v2.6.9+incompatible/go.mod h1:kXX7q3jZtJXK5c5qK83bSGMdV6tsOE70KbHoqJls4lE=
+github.com/sendgrid/sendgrid-go v3.14.0+incompatible h1:KDSasSTktAqMJCYClHVE94Fcif2i7P7wzISv1sU6DUA=
+github.com/sendgrid/sendgrid-go v3.14.0+incompatible/go.mod h1:QRQt+LX/NmgVEvmdRw0VT/QgUn499+iza2FnDca9fg8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
@@ -84,6 +84,8 @@ golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
 golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/text v0.23.0 h1:D71I7dUrlY+VX0gQShAThNGHFxZ13dGLBHQLVl1mJlY=
 golang.org/x/text v0.23.0/go.mod h1:/BLNzu4aZCJ1+kcD0DNRotWKage4q2rGVAg4o22unh4=
+golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
+golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=

auth-service/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"cleanapp-common/serverx"
 	"database/sql"
 	"fmt"
 	"log"
@@ -22,7 +23,10 @@ import (
 
 func main() {
 	// Load configuration
-	cfg := config.Load()
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("Failed to load config: %v", err)
+	}
 
 	// Database connection
 	db, err := setupDatabase(cfg)
@@ -31,10 +35,13 @@ func main() {
 	}
 	defer db.Close()
 
-	// Initialize database schema
-	log.Println("Initializing database schema and running migrations...")
-	if err := database.InitializeSchema(db); err != nil {
-		log.Fatalf("Failed to initialize database schema: %v", err)
+	if cfg.RunDBMigrations {
+		log.Println("Initializing database schema and running migrations...")
+		if err := database.InitializeSchema(db); err != nil {
+			log.Fatalf("Failed to initialize database schema: %v", err)
+		}
+	} else {
+		log.Println("Skipping runtime database migrations (DB_RUN_MIGRATIONS=false)")
 	}
 
 	// Initialize encryptor
@@ -51,13 +58,13 @@ func main() {
 
 	// Start server
 	log.Printf("Auth service starting on port %s", cfg.Port)
-	if err := router.Run(":" + cfg.Port); err != nil {
+	if err := serverx.New(":"+cfg.Port, router).ListenAndServe(); err != nil {
 		log.Fatalf("Failed to start server: %v", err)
 	}
 }
 
 func setupDatabase(cfg *config.Config) (*sql.DB, error) {
-	dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/cleanapp?parseTime=true&multiStatements=true",
+	dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/cleanapp?parseTime=true",
 		cfg.DBUser, cfg.DBPassword, cfg.DBHost, cfg.DBPort)
 
 	db, err := sql.Open("mysql", dsn)
@@ -128,9 +135,9 @@ func setupRouter(service *database.AuthService, cfg *config.Config) *gin.Engine
 	router.SetTrustedProxies(cfg.TrustedProxies)
 
 	// Apply global middleware
-	router.Use(middleware.CORSMiddleware())
+	router.Use(middleware.CORSMiddleware(cfg.AllowedOrigins))
 	router.Use(middleware.SecurityHeaders())
-	router.Use(middleware.RateLimitMiddleware())
+	router.Use(middleware.RateLimitMiddleware(cfg.RateLimitRPS, cfg.RateLimitBurst))
 
 	// Initialize email sender (if SendGrid is configured)
 	var emailSender *email.Sender