Fix TOTP brute-force, broken deploy pipeline, inconsistent error shapes, and stored XSS gaps

- Tighten 2FA challenge rate limiting (3/30s per IP + per account), add
  account lockout after 10 consecutive failures, and audit-log failed
  attempts (closes Savitura#378)
- Replace placeholder echo deploy steps with real SSH + docker compose
  deploy, DB migrations, and a post-deploy health check (closes Savitura#381)
- Normalize express-validator errors into the canonical
  { error: { code, message, fields } } shape and document it in the
  OpenAPI specs (closes Savitura#382)
- Sanitize milestone and reward-tier title/description on write (they
  previously bypassed stripHtml) and backfill any HTML already stored
  in campaigns/milestones/reward_tiers (closes Savitura#383)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: devsimze

.github/workflows/deploy.yml

@@ -6,52 +6,66 @@ on:
     branches: [main]
     types:
       - completed
+  workflow_dispatch: {}
 
 jobs:
   deploy:
     name: Deploy to Production
     runs-on: ubuntu-latest
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
-    
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    environment: production
 
-      - name: Build and push backend image
-        uses: docker/build-push-action@v5
+    steps:
+      - name: Write production env file and deploy via docker compose
+        uses: appleboy/ssh-action@v1.0.3
         with:
-          context: ./backend
-          push: true
-          tags: ghcr.io/${{ github.repository }}/backend:latest
+          host: ${{ secrets.DEPLOY_HOST }}
+          username: ${{ secrets.DEPLOY_USER }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          envs: DATABASE_URL,JWT_SECRET,API_KEY_PEPPER,PLATFORM_SECRET_KEY,USDC_ISSUER,STELLAR_NETWORK,STELLAR_HORIZON_URL,FRONTEND_URL,DEPLOY_PATH
+          env:
+            DATABASE_URL: ${{ secrets.DATABASE_URL }}
+            JWT_SECRET: ${{ secrets.JWT_SECRET }}
+            API_KEY_PEPPER: ${{ secrets.API_KEY_PEPPER }}
+            PLATFORM_SECRET_KEY: ${{ secrets.PLATFORM_SECRET_KEY }}
+            USDC_ISSUER: ${{ secrets.USDC_ISSUER }}
+            STELLAR_NETWORK: ${{ secrets.STELLAR_NETWORK }}
+            STELLAR_HORIZON_URL: ${{ secrets.STELLAR_HORIZON_URL }}
+            FRONTEND_URL: ${{ secrets.FRONTEND_URL }}
+            DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
+          script: |
+            set -euo pipefail
+            cd "$DEPLOY_PATH"
+            git fetch origin main
+            git reset --hard origin/main
 
-      - name: Deploy backend
-        run: echo "Deploying backend to hosting provider..."
-        # Replace with actual deploy command, e.g., Fly.io:
-        # flyctl deploy --image ghcr.io/${{ github.repository }}/backend:latest
-        env:
-          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
-
-      - name: Setup Node.js for migrations
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
+            cat > backend/.env <<EOF
+            NODE_ENV=production
+            DATABASE_URL=${DATABASE_URL}
+            JWT_SECRET=${JWT_SECRET}
+            API_KEY_PEPPER=${API_KEY_PEPPER}
+            PLATFORM_SECRET_KEY=${PLATFORM_SECRET_KEY}
+            USDC_ISSUER=${USDC_ISSUER}
+            STELLAR_NETWORK=${STELLAR_NETWORK}
+            STELLAR_HORIZON_URL=${STELLAR_HORIZON_URL}
+            FRONTEND_URL=${FRONTEND_URL}
+            EOF
 
-      - name: Run DB migrations
-        env:
-          DATABASE_URL: ${{ secrets.DATABASE_URL }}
-        run: node migrate.js
+            docker compose -f docker-compose.prod.yml up -d --build
+            docker compose -f docker-compose.prod.yml exec -T backend node db/migrate.js
 
-      - name: Deploy frontend
-        run: echo "Deploying frontend to static hosting..."
-        # Replace with actual deploy action, e.g., Vercel:
-        # npx vercel --prod --token ${{ secrets.VERCEL_TOKEN }}
+      - name: Wait for backend to become healthy
+        run: |
+          for i in $(seq 1 10); do
+            if curl -fsS "${{ secrets.DEPLOY_HEALTH_URL }}/health"; then
+              echo "Health check passed"
+              exit 0
+            fi
+            echo "Health check attempt $i failed, retrying in 5s..."
+            sleep 5
+          done
+          echo "Health check failed after 10 attempts"
+          exit 1
 
       - name: Post deploy status to Slack
         uses: 8398a7/action-slack@v3

backend/db/migrations/20260628_add_totp_lockout.sql

@@ -0,0 +1,3 @@
+ALTER TABLE users
+ADD COLUMN totp_failed_attempts INTEGER NOT NULL DEFAULT 0,
+ADD COLUMN totp_locked_until TIMESTAMPTZ;

backend/db/migrations/20260628_sanitize_existing_html_content.sql

@@ -0,0 +1,25 @@
+-- Backfill: strip any HTML tags left over from before input sanitization was
+-- applied to campaign/milestone/reward-tier text fields (issue #383).
+UPDATE campaigns
+SET description = TRIM(regexp_replace(description, '<[^>]*>', '', 'g'))
+WHERE description ~ '<[^>]*>';
+
+UPDATE campaigns
+SET title = TRIM(regexp_replace(title, '<[^>]*>', '', 'g'))
+WHERE title ~ '<[^>]*>';
+
+UPDATE milestones
+SET title = TRIM(regexp_replace(title, '<[^>]*>', '', 'g'))
+WHERE title ~ '<[^>]*>';
+
+UPDATE milestones
+SET description = TRIM(regexp_replace(description, '<[^>]*>', '', 'g'))
+WHERE description ~ '<[^>]*>';
+
+UPDATE reward_tiers
+SET title = TRIM(regexp_replace(title, '<[^>]*>', '', 'g'))
+WHERE title ~ '<[^>]*>';
+
+UPDATE reward_tiers
+SET description = TRIM(regexp_replace(description, '<[^>]*>', '', 'g'))
+WHERE description ~ '<[^>]*>';

backend/src/index.js

@@ -127,6 +127,33 @@ const openApiSpec = swaggerJsdoc({
           bearerFormat: "JWT",
         },
       },
+      schemas: {
+        Error: {
+          type: "object",
+          properties: {
+            error: {
+              type: "object",
+              properties: {
+                code: { type: "string", example: "VALIDATION_ERROR" },
+                message: { type: "string", example: "Invalid email format" },
+                fields: {
+                  type: "array",
+                  nullable: true,
+                  items: {
+                    type: "object",
+                    properties: {
+                      field: { type: "string" },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+              required: ["code", "message"],
+            },
+          },
+          required: ["error"],
+        },
+      },
     },
   },
   apis: ["./src/routes/*.js"],
@@ -150,6 +177,33 @@ const v1OpenApiSpec = swaggerJsdoc({
           bearerFormat: "cp_live_…",
         },
       },
+      schemas: {
+        Error: {
+          type: "object",
+          properties: {
+            error: {
+              type: "object",
+              properties: {
+                code: { type: "string", example: "VALIDATION_ERROR" },
+                message: { type: "string", example: "Invalid email format" },
+                fields: {
+                  type: "array",
+                  nullable: true,
+                  items: {
+                    type: "object",
+                    properties: {
+                      field: { type: "string" },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+              required: ["code", "message"],
+            },
+          },
+          required: ["error"],
+        },
+      },
     },
   },
   apis: ["./src/routes/v1.js"],

backend/src/middleware/validation.js

@@ -321,7 +321,18 @@ function validateRequest(req, res, next) {
   const result = validationResult(req);
   if (result.isEmpty()) return next();
 
-  return res.status(400).json({ errors: result.array() });
+  const fields = result.array().map((e) => ({
+    field: e.path || e.param,
+    message: e.msg,
+  }));
+
+  return res.status(400).json({
+    error: {
+      code: 'VALIDATION_ERROR',
+      message: fields[0]?.message || 'Validation failed',
+      fields,
+    },
+  });
 }
 
 function validateRequestAsError(req, res, next) {

backend/src/routes/auth.js

@@ -101,15 +101,30 @@ const loginLimiter = rateLimit({
   skip: () => isTest,
 });
 
+// Per-IP: 3 TOTP attempts per 30 seconds.
 const totpChallengeLimiter = rateLimit({
-  windowMs: 15 * 60 * 1000,
-  max: isTest ? 100000 : 10,
+  windowMs: 30 * 1000,
+  max: isTest ? 100000 : 3,
+  message: { error: 'Too many 2FA attempts, please try again later.' },
+  standardHeaders: true,
+  legacyHeaders: false,
+  skip: () => isTest,
+});
+
+// Per-account (by email): 3 TOTP attempts per 30 seconds, independent of IP.
+const totpChallengeEmailLimiter = rateLimit({
+  windowMs: 30 * 1000,
+  max: isTest ? 100000 : 3,
   message: { error: 'Too many 2FA attempts, please try again later.' },
   standardHeaders: true,
   legacyHeaders: false,
   skip: () => isTest,
+  keyGenerator: (req) => String((req.body?.email || '').trim().toLowerCase()),
 });
 
+const TOTP_MAX_CONSECUTIVE_FAILURES = 10;
+const TOTP_LOCKOUT_MS = 15 * 60 * 1000;
+
 function hashToken(token) {
   return crypto.createHash('sha256').update(token, 'utf8').digest('hex');
 }
@@ -438,7 +453,7 @@ router.post('/login', loginLimiter, loginValidation, validateRequest, async (req
   });
 });
 
-router.post('/2fa/challenge', totpChallengeLimiter, validateRequest, async (req, res) => {
+router.post('/2fa/challenge', totpChallengeLimiter, totpChallengeEmailLimiter, validateRequest, async (req, res) => {
   const { email, password, code } = req.body;
   if (!email || !password || !code) {
     return res.status(400).json({ error: 'Email, password, and code are required' });
@@ -455,6 +470,15 @@ router.post('/2fa/challenge', totpChallengeLimiter, validateRequest, async (req,
     return res.status(400).json({ error: '2FA is not enabled for this account' });
   }
 
+  if (user.totp_locked_until && new Date(user.totp_locked_until) > new Date()) {
+    logger.warn('TOTP challenge blocked: account locked', {
+      event: 'totp_locked',
+      userId: user.id,
+      ip: req.ip,
+    });
+    return res.status(423).json({ error: 'Too many failed 2FA attempts. Try again later.' });
+  }
+
   let codeValid = false;
 
   if (code.length === 6) {
@@ -472,9 +496,33 @@ router.post('/2fa/challenge', totpChallengeLimiter, validateRequest, async (req,
   }
 
   if (!codeValid) {
+    const failedAttempts = (user.totp_failed_attempts || 0) + 1;
+    const lockingOut = failedAttempts >= TOTP_MAX_CONSECUTIVE_FAILURES;
+    await db.query(
+      'UPDATE users SET totp_failed_attempts = $1, totp_locked_until = $2 WHERE id = $3',
+      [
+        lockingOut ? 0 : failedAttempts,
+        lockingOut ? new Date(Date.now() + TOTP_LOCKOUT_MS) : null,
+        user.id,
+      ]
+    );
+    logger.warn('Failed 2FA attempt', {
+      event: 'totp_failed_attempt',
+      userId: user.id,
+      ip: req.ip,
+      consecutiveFailures: failedAttempts,
+      lockedOut: lockingOut,
+    });
     return res.status(401).json({ error: 'Invalid 2FA code' });
   }
 
+  if (user.totp_failed_attempts) {
+    await db.query(
+      'UPDATE users SET totp_failed_attempts = 0, totp_locked_until = NULL WHERE id = $1',
+      [user.id]
+    );
+  }
+
   const { accessToken } = generateTokens(user);
   const { token: refreshToken, expiresAt } = await createRefreshToken(user.id);
 

backend/src/routes/campaigns.js

@@ -134,8 +134,8 @@ function normalizeMilestonesInput(input) {
   }
 
   const normalized = input.map((milestone, index) => {
-    const title = String(milestone?.title || '').trim();
-    const description = String(milestone?.description || '').trim();
+    const title = stripHtml(milestone?.title || '');
+    const description = stripHtml(milestone?.description || '');
     if (!title) {
       throw new Error(`Milestone ${index + 1} title is required`);
     }

backend/src/routes/users.test.js

@@ -106,8 +106,9 @@ test('POST /api/auth/register returns 400 with validation errors for invalid inp
     .send({ email: 'not-an-email', password: 'short', name: '' });
 
   assert.equal(res.status, 400);
-  assert.ok(Array.isArray(res.body.errors));
-  assert.ok(res.body.errors.length >= 1);
+  assert.equal(res.body.error.code, 'VALIDATION_ERROR');
+  assert.ok(Array.isArray(res.body.error.fields));
+  assert.ok(res.body.error.fields.length >= 1);
 });
 
 test('POST /api/auth/login returns 400 with validation errors for invalid email', async () => {
@@ -120,7 +121,8 @@ test('POST /api/auth/login returns 400 with validation errors for invalid email'
     .send({ email: 'bad-email', password: '' });
 
   assert.equal(res.status, 400);
-  assert.ok(Array.isArray(res.body.errors));
+  assert.equal(res.body.error.code, 'VALIDATION_ERROR');
+  assert.ok(Array.isArray(res.body.error.fields));
 });
 
 test('POST /api/auth/forgot-password returns generic message for unknown email', async () => {

backend/src/services/rewardTierService.js

@@ -1,4 +1,5 @@
 const db = require('../config/database');
+const { stripHtml } = require('../lib/sanitize');
 
 const MAX_TIERS_PER_CAMPAIGN = 10;
 
@@ -24,7 +25,7 @@ function validateTiersInput(tiers, campaignAssetType) {
   return tiers.map((tier, index) => {
     const label = `reward_tiers[${index}]`;
 
-    const title = typeof tier.title === 'string' ? tier.title.trim() : '';
+    const title = stripHtml(tier.title || '');
     if (!title) throw new Error(`${label}: title is required`);
 
     const minAmount = Number(tier.min_amount);
@@ -57,7 +58,7 @@ function validateTiersInput(tiers, campaignAssetType) {
 
     return {
       title,
-      description: typeof tier.description === 'string' ? tier.description.trim() : null,
+      description: typeof tier.description === 'string' ? stripHtml(tier.description) || null : null,
       min_amount: minAmount,
       asset_type: assetType,
       tier_limit: tierLimit,