chore: promote multicloud web frontend to main (1380 commits)

.air.toml

@@ -0,0 +1,49 @@
+# Air configuration for hot reload in development
+# https://github.com/air-verse/air
+
+root = "."
+testdata_dir = "testdata"
+tmp_dir = "tmp"
+
+[build]
+  args_bin = []
+  bin = "./tmp/main"
+  cmd = "go build -o ./tmp/main ./cmd/server"
+  delay = 1000
+  exclude_dir = ["assets", "tmp", "vendor", "testdata", "frontend", "node_modules"]
+  exclude_file = []
+  exclude_regex = ["_test.go"]
+  exclude_unchanged = false
+  follow_symlink = false
+  full_bin = ""
+  include_dir = []
+  include_ext = ["go", "tpl", "tmpl", "html"]
+  include_file = []
+  kill_delay = "0s"
+  log = "build-errors.log"
+  poll = false
+  poll_interval = 0
+  post_cmd = []
+  pre_cmd = []
+  rerun = false
+  rerun_delay = 500
+  send_interrupt = false
+  stop_on_error = false
+
+[color]
+  app = ""
+  build = "yellow"
+  main = "magenta"
+  runner = "green"
+  watcher = "cyan"
+
+[log]
+  main_only = false
+  time = false
+
+[misc]
+  clean_on_exit = false
+
+[screen]
+  clear_on_rebuild = false
+  keep_scroll = true

.dockerignore

@@ -0,0 +1,39 @@
+# Terraform state and providers
+**/.terraform
+*.tfstate
+*.tfstate.backup
+*.tfbackend
+
+# Frontend build artifacts and dependencies
+frontend/node_modules
+frontend/coverage
+frontend/dist
+
+# IDE and OS
+.idea
+.vscode
+.DS_Store
+
+# Git
+.git
+
+# Go vendor (dependencies downloaded at build time)
+vendor/
+
+# Temporary files
+tmp/
+
+# Docker compose dev files
+docker-compose.yml
+Dockerfile.dev
+
+# Secrets and credentials
+.env
+.env.*
+*.pem
+*.key
+*.p12
+credentials/
+*.tfstate
+*.tfstate.backup
+.terraform/

.env.example

@@ -0,0 +1,120 @@
+# CUDly local development env template
+#
+# Copy this file to `.env.local` (already in .gitignore) and fill in
+# the placeholders. Loaded by: load-env.sh / your IDE / `direnv` —
+# CUDly itself reads these via os.Getenv at runtime.
+#
+# All values here are PLACEHOLDERS. Never commit real secrets to .env*
+# files; the .gitignore at the repo root already excludes everything
+# matching `.env*` except this template.
+
+# ---------------------------------------------------------------------
+# Required: secrets resolver
+# ---------------------------------------------------------------------
+# SECRET_PROVIDER selects which secret store the resolver fetches from.
+#   aws  | gcp | azure  — production: real Secrets Manager / Key Vault
+#   env                 — local dev: resolve secret names to env vars
+# In `env` mode, every secret-ref var (ADMIN_PASSWORD_SECRET,
+# API_KEY_SECRET_ARN, etc.) holds the NAME of another env var whose
+# value is the actual secret. See `internal/secrets/env_resolver.go`.
+# Pairs with EMAIL_ENABLED=false so the email factory's no-op sender
+# kicks in (see PR #333) — otherwise `env` is not a recognised email
+# backend and the factory would fail dispatch.
+SECRET_PROVIDER=env
+
+# ---------------------------------------------------------------------
+# Required: scheduled-task auth mode (no default — must be explicit)
+# ---------------------------------------------------------------------
+# Selects how the internal /api/scheduled/* endpoints authenticate.
+#   oidc      — production: verify Google-issued OIDC ID tokens
+#   bearer    — shared-secret token in Authorization header
+#   disabled  — local dev: no auth check
+# Required by `internal/server/scheduledauth/config.go`; app refuses
+# to start when unset.
+SCHEDULED_TASK_AUTH_MODE=disabled
+
+# ---------------------------------------------------------------------
+# Required: email gate (factory short-circuit, see PR #333)
+# ---------------------------------------------------------------------
+# When `false`, internal/email/factory.go returns a no-op sender that
+# logs each invocation at debug level instead of dispatching to a
+# cloud-specific backend. Pair with SECRET_PROVIDER=env for local dev.
+EMAIL_ENABLED=false
+
+# ---------------------------------------------------------------------
+# Required: credential encryption key
+# ---------------------------------------------------------------------
+# In production exactly ONE of the per-cloud secret refs is set; the
+# Go side reads them in priority order (ARN → NAME → ID → raw KEY).
+# For local dev set CREDENTIAL_ENCRYPTION_ALLOW_DEV_KEY=1 to use the
+# all-zero dev key without touching a Secrets Manager / Key Vault.
+CREDENTIAL_ENCRYPTION_ALLOW_DEV_KEY=1
+
+# CREDENTIAL_ENCRYPTION_KEY_SECRET_ARN=arn:aws:secretsmanager:us-east-1:000000000000:secret:cudly-cred-enc-key-PLACEHOLDER
+# CREDENTIAL_ENCRYPTION_KEY_SECRET_NAME=cudly-credential-encryption-key
+# CREDENTIAL_ENCRYPTION_KEY_SECRET_ID=cudly-credential-encryption-key
+# CREDENTIAL_ENCRYPTION_KEY=<64-hex-chars>
+
+# ---------------------------------------------------------------------
+# Required: admin auth + API
+# ---------------------------------------------------------------------
+# With SECRET_PROVIDER=env, the *_SECRET / *_SECRET_ARN vars hold the
+# NAME of another env var whose value is the actual secret. The matched
+# env var must then be defined below. Two reasons for the indirection:
+# (1) production uses the same var name pointing at a real ARN/name;
+# (2) the dev value is co-located with its lookup key so future readers
+# can trace the chain in one file.
+ADMIN_EMAIL=admin@cudly.local
+ADMIN_PASSWORD_SECRET=ADMIN_PASSWORD_DEV
+ADMIN_PASSWORD_DEV=LocalDev!Pass123
+API_KEY_SECRET_ARN=ADMIN_API_KEY_DEV
+ADMIN_API_KEY_DEV=cudly-local-dev-api-key-not-for-prod
+# Production examples (override SECRET_PROVIDER and these):
+# ADMIN_PASSWORD_SECRET=arn:aws:secretsmanager:us-east-1:000000000000:secret:cudly-admin-password-PLACEHOLDER
+# API_KEY_SECRET_ARN=arn:aws:secretsmanager:us-east-1:000000000000:secret:cudly-api-key-PLACEHOLDER
+
+# ---------------------------------------------------------------------
+# Optional: web frontend / CORS / dashboard
+# ---------------------------------------------------------------------
+CORS_ALLOWED_ORIGIN=http://localhost:3000
+DASHBOARD_URL=http://localhost:3000
+# ENABLE_DASHBOARD=true
+# DASHBOARD_BUCKET=cudly-dashboard-PLACEHOLDER
+
+# ---------------------------------------------------------------------
+# Optional: PostgreSQL (lazy — unset to skip)
+# ---------------------------------------------------------------------
+# DB_HOST=localhost
+# DB_PORT=5432
+# DB_USER=cudly
+# DB_NAME=cudly
+# DB_PASSWORD_SECRET=arn:aws:secretsmanager:us-east-1:000000000000:secret:cudly-db-PLACEHOLDER
+# CUDLY_MIGRATION_TIMEOUT=2m
+
+# ---------------------------------------------------------------------
+# Optional: cloud-provider profiles for multi-cloud onboarding
+# ---------------------------------------------------------------------
+# AWS_CONFIG_FILE=$HOME/.aws/config
+# AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
+# AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
+# AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
+# AZURE_KEY_VAULT_URL=https://cudly-vault-placeholder.vault.azure.net/
+# GCP_PROJECT_ID=cudly-placeholder
+# AWS_REGION=us-east-1
+
+# ---------------------------------------------------------------------
+# Optional: SES / Azure ACS / SendGrid email config
+# ---------------------------------------------------------------------
+# EMAIL_ADDRESS=noreply@cudly.example
+# AZURE_SMTP_HOST=smtp.azurecomm.net
+# AZURE_SMTP_USERNAME_SECRET=arn:aws:secretsmanager:us-east-1:000000000000:secret:cudly-smtp-user-PLACEHOLDER
+# AZURE_SMTP_PASSWORD_SECRET=arn:aws:secretsmanager:us-east-1:000000000000:secret:cudly-smtp-pass-PLACEHOLDER
+
+# ---------------------------------------------------------------------
+# Optional: tunables
+# ---------------------------------------------------------------------
+# CUDLY_RECOMMENDATION_CACHE_TTL=15m
+# CUDLY_MAX_ACCOUNT_PARALLELISM=8
+# DEFAULT_PAYMENT_OPTION=no-upfront
+# DEFAULT_RAMP_SCHEDULE=quarterly
+# ENVIRONMENT=local

.gitallowed

@@ -0,0 +1,45 @@
+# git-secrets allowlist: regexes that should NOT trigger the AWS-secret scanner.
+#
+# The scanner's `--register-aws` adds a 12-digit account-ID pattern that
+# matches our test fixtures. The values below are obvious test placeholders
+# (sequential 123456789012, all-same-digit blocks like 111111111111, and
+# countdown patterns like 999888777666) — chosen specifically because they
+# cannot be real customer accounts. Adding these is safer than disabling the
+# AWS-account check entirely.
+#
+# DO NOT add a real account ID here. If a real account ID lands in the repo,
+# rotate it and treat the leak seriously instead of silencing the scanner.
+#
+# Format: one regex per line, matched against each line of file content
+# (path-scoping is not supported by .gitallowed).
+
+# Sequential test placeholders (ascending and descending).
+123456789012
+210987654321
+
+# All-same-digit blocks of 12 — used as table-row distinctions in fixtures.
+# Listed explicitly rather than via a regex back-reference because not every
+# git-secrets build supports back-refs in its allowlist regexes.
+000000000000
+111111111111
+222222222222
+333333333333
+444444444444
+555555555555
+666666666666
+777777777777
+888888888888
+999999999999
+
+# Group-block placeholders used in cmd/helpers_test.go variants and
+# cmd/multi_service_helpers_test.go.
+111222333444
+555666777888
+999888777666
+# Descending-step fixture added in #956 tests (store_postgres_pgxmock_test.go,
+# handler_analytics_test.go, handler_history_test.go, handler_dashboard_test.go).
+999988887777
+
+# UUID-shaped account ID used in handler_accounts_test.go (synthetic, not a
+# real subscription/account).
+11111111-1111-1111-1111-111111111111

.github/runbooks/compromised-dependency.md

@@ -0,0 +1,138 @@
+# Runbook: Compromised Dependency
+
+**Trigger**: A Go module, npm package, Docker base image, or GitHub Action used by CUDly has been found to be malicious or critically vulnerable.
+
+**Owner**: On-call engineer
+**Severity**: P1 (active exploitation) / P2 (known critical CVE, no evidence of exploitation)
+
+---
+
+## Step 1: Assess Impact
+
+```bash
+# For Go dependency CVE
+govulncheck ./...
+
+# For npm dependency CVE
+cd frontend && npm audit
+
+# For Docker image CVE
+trivy image <IMAGE_URI>
+
+# For GitHub Actions compromise
+# Check: https://github.com/advisories (filter by Actions category)
+```
+
+Questions to answer:
+
+- Is the vulnerable code path reachable in production?
+- Does exploitation require authentication?
+- Is there evidence of active exploitation in logs?
+
+---
+
+## Step 2: Pin to Safe Version Immediately
+
+### Go Dependency
+
+```bash
+# Pin to last known-good version
+go get github.com/affected/package@v1.2.3-safe
+
+# If no safe version exists, pin to a known commit hash
+go get github.com/affected/package@<SAFE_COMMIT_SHA>
+
+go mod tidy
+go mod verify
+
+# Run tests
+go test ./...
+```
+
+### npm Dependency
+
+```bash
+cd frontend
+
+# Force a specific version
+npm install affected-package@<SAFE_VERSION>
+
+# Or use npm audit fix
+npm audit fix
+
+# Verify
+npm audit
+npm test
+```
+
+### Docker Base Image
+
+Update the `FROM` line in Dockerfile(s) to a patched version:
+
+```dockerfile
+# Before
+FROM golang:1.25.4-alpine3.21
+
+# After (example: patch to new minor that fixes CVE)
+FROM golang:1.25.5-alpine3.21
+```
+
+Rebuild and push the container image.
+
+### GitHub Action
+
+Pin the compromised action to the last known-good commit SHA:
+
+```yaml
+# Before (vulnerable)
+- uses: some-org/some-action@v1.2.3
+
+# After (pinned to safe commit)
+- uses: some-org/some-action@<SAFE_COMMIT_SHA>
+```
+
+Or remove the action entirely and replace with equivalent logic using trusted actions or shell commands.
+
+---
+
+## Step 3: Deploy the Fix
+
+```bash
+# Tag and push
+git add go.mod go.sum Dockerfile
+git commit -m "security: pin <package> to safe version (CVE-YYYY-XXXXX)"
+git push
+
+# CI/CD will build and deploy
+# If CI is also affected by the compromised dependency, run manually:
+make build && make push
+```
+
+---
+
+## Step 4: Investigate for Active Exploitation
+
+```bash
+# Check application logs for exploitation patterns
+aws logs filter-log-events \
+  --log-group-name /aws/lambda/cudly \
+  --filter-pattern "<exploitation_signature>" \
+  --start-time <CVE_DISCLOSURE_EPOCH_MS>
+
+# Check CloudTrail for unexpected API calls from application role
+aws cloudtrail lookup-events \
+  --lookup-attributes AttributeKey=Username,AttributeValue=<APP_ROLE_NAME> \
+  --start-time <CVE_DISCLOSURE_TIME>
+```
+
+---
+
+## Step 5: Verify & Post-Mortem
+
+- [ ] Confirm `govulncheck` / `npm audit` / `trivy` no longer report the CVE
+- [ ] Run full test suite
+- [ ] Deploy to staging, then production
+- [ ] Document the incident timeline
+- [ ] Add the CVE to monitoring rules (detect if patched version is reverted)
+- [ ] Review dependency update cadence — consider automating with Dependabot/Renovate
+- [ ] Review GitHub Actions pinning strategy → see SC-003 recommendation