Merge pull request #258 from RaymondAbiola/Automated_Sanctions_Screening

Automated Sanctions Screening via OFAC Integration

Author: elizabetheonoja-art

middleware/sanctionsBlock.js

@@ -0,0 +1,73 @@
+/**
+ * sanctionsBlock middleware
+ *
+ * Rejects every authenticated request whose underlying wallet is BLOCKED by
+ * the sanctions screening pipeline. Designed to be the cheapest possible
+ * gate — relies on the SanctionsScreeningService's in-process LRU cache so
+ * a typical hit is a single Map lookup, not a DB query.
+ *
+ * Mount AFTER the auth middleware (so req.user is populated) on every route
+ * we want structurally protected, e.g.
+ *
+ *   app.use('/api', authenticateToken);
+ *   app.use('/api', createSanctionsBlockMiddleware({ service: sanctionsScreeningService }));
+ *
+ * Non-authenticated requests are passed through — they are screened at SEP-10
+ * verify time before they ever get a token.
+ */
+function createSanctionsBlockMiddleware({ service, getWalletAddress } = {}) {
+  if (!service) {
+    throw new Error(
+      'createSanctionsBlockMiddleware: service (SanctionsScreeningService) is required'
+    );
+  }
+  const extract = getWalletAddress || defaultExtract;
+
+  return function sanctionsBlockMiddleware(req, res, next) {
+    let walletAddress;
+    try {
+      walletAddress = extract(req);
+    } catch (_e) {
+      walletAddress = null;
+    }
+
+    if (!walletAddress) {
+      return next();
+    }
+
+    let blocked;
+    try {
+      blocked = service.isBlocked(walletAddress);
+    } catch (err) {
+      // Don't fail-closed on a DB hiccup — log and continue. The screening
+      // step at SEP-10 verify is the authoritative gate; this middleware is
+      // a defence-in-depth net.
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[sanctionsBlock] isBlocked check failed:',
+        err && err.message ? err.message : err
+      );
+      return next();
+    }
+
+    if (blocked) {
+      return res.status(403).json({
+        success: false,
+        error: 'ACCOUNT_BLOCKED',
+        message:
+          'This account is blocked due to sanctions screening. Contact the compliance officer to request a review.',
+      });
+    }
+
+    return next();
+  };
+}
+
+function defaultExtract(req) {
+  if (!req || !req.user) return null;
+  return req.user.walletAddress || req.user.publicKey || req.user.address || null;
+}
+
+module.exports = {
+  createSanctionsBlockMiddleware,
+};

migrations/knex/019_create_sanctions_screening_tables.js

@@ -0,0 +1,98 @@
+/**
+ * Sanctions Screening Tables
+ *
+ * Stores the result of every OFAC / global-sanctions check we run, plus the
+ * status of every screened wallet (so requests from BLOCKED accounts can be
+ * rejected at the middleware layer without re-querying the upstream provider).
+ *
+ * - screened_users         : the per-wallet status row (the "User" status the
+ *                            issue refers to). account_status is the gate
+ *                            checked by the request-time middleware.
+ * - security_audit         : append-only audit log of every screening event,
+ *                            with provider identity, risk score, and reason
+ *                            for the flag. Satisfies regulatory reporting.
+ * - sanctions_review_queue : compliance-officer worklist for false-positive
+ *                            review. cleared addresses are unblocked and
+ *                            re-screening is suppressed via override_until.
+ */
+exports.up = async function up(knex) {
+  const hasScreenedUsers = await knex.schema.hasTable('screened_users');
+  if (!hasScreenedUsers) {
+    await knex.schema.createTable('screened_users', (table) => {
+      table.string('wallet_address').primary();
+      table.string('account_status').notNullable().defaultTo('ACTIVE');
+      table.string('risk_level').nullable();
+      table.decimal('risk_score', 10, 4).nullable();
+      table.text('flagged_lists').nullable();
+      table.text('block_reason').nullable();
+      table.string('blocking_provider').nullable();
+      table.timestamp('last_screened_at').nullable();
+      table.string('last_audit_id').nullable();
+      table.timestamp('blocked_at').nullable();
+      table.timestamp('unblocked_at').nullable();
+      table.string('unblocked_by').nullable();
+      table.timestamp('override_until').nullable();
+      table.timestamp('created_at').notNullable().defaultTo(knex.fn.now());
+      table.timestamp('updated_at').notNullable().defaultTo(knex.fn.now());
+
+      table.index(['account_status']);
+      table.index(['risk_level']);
+      table.index(['last_screened_at']);
+    });
+  }
+
+  const hasSecurityAudit = await knex.schema.hasTable('security_audit');
+  if (!hasSecurityAudit) {
+    await knex.schema.createTable('security_audit', (table) => {
+      table.string('id').primary();
+      table.string('wallet_address').notNullable().index();
+      table.string('event_type').notNullable();
+      table.string('provider').nullable();
+      table.string('risk_level').nullable();
+      table.decimal('risk_score', 10, 4).nullable();
+      table.text('flagged_lists').nullable();
+      table.text('reason').nullable();
+      table.text('provider_response').nullable();
+      table.string('triggering_action').nullable();
+      table.string('actor').nullable();
+      table.string('ip_address').nullable();
+      table.timestamp('created_at').notNullable().defaultTo(knex.fn.now());
+
+      table.index(['wallet_address', 'created_at']);
+      table.index(['event_type', 'created_at']);
+      table.index(['provider', 'created_at']);
+    });
+  }
+
+  const hasReviewQueue = await knex.schema.hasTable('sanctions_review_queue');
+  if (!hasReviewQueue) {
+    await knex.schema.createTable('sanctions_review_queue', (table) => {
+      table.string('id').primary();
+      table.string('wallet_address').notNullable();
+      table.string('triggering_audit_id').nullable();
+      table.string('status').notNullable().defaultTo('open');
+      table.string('risk_level').nullable();
+      table.decimal('risk_score', 10, 4).nullable();
+      table.text('flagged_lists').nullable();
+      table.text('reason').nullable();
+      table.timestamp('submitted_at').notNullable().defaultTo(knex.fn.now());
+      table.timestamp('reviewed_at').nullable();
+      table.string('reviewed_by').nullable();
+      table.text('decision_notes').nullable();
+
+      table.index(['wallet_address', 'status']);
+      table.index(['status', 'submitted_at']);
+    });
+
+    await knex.raw(
+      `CREATE UNIQUE INDEX IF NOT EXISTS idx_sanctions_review_queue_one_open_per_wallet
+         ON sanctions_review_queue (wallet_address) WHERE status = 'open'`
+    );
+  }
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists('sanctions_review_queue');
+  await knex.schema.dropTableIfExists('security_audit');
+  await knex.schema.dropTableIfExists('screened_users');
+};

routes/sanctionsCompliance.js

@@ -0,0 +1,132 @@
+const express = require('express');
+const { SanctionsScreeningService } = require('../src/services/sanctionsScreeningService');
+
+/**
+ * Compliance officer surface for reviewing sanctions hits.
+ *
+ *   GET    /api/compliance/sanctions/queue          - list open review tickets
+ *   POST   /api/compliance/sanctions/:address/false-positive
+ *                                                   - clear an address (unblock)
+ *   POST   /api/compliance/sanctions/:address/confirm
+ *                                                   - confirm sanction (stay blocked)
+ *   GET    /api/compliance/sanctions/:address/audit - full audit trail
+ *   GET    /api/compliance/sanctions/:address       - current account status
+ *
+ * The router is service-injectable so the main app and tests can share a
+ * single SanctionsScreeningService (and its in-process cache).
+ */
+function createSanctionsComplianceRoutes(deps = {}) {
+  const router = express.Router();
+
+  const getService = (req) => {
+    if (deps.sanctionsScreeningService) return deps.sanctionsScreeningService;
+    const fromApp = req.app.get('sanctionsScreeningService');
+    if (fromApp) return fromApp;
+
+    const database = deps.database || req.app.get('database');
+    if (!database) {
+      throw new Error('SanctionsScreeningService unavailable: no database configured');
+    }
+    const service = new SanctionsScreeningService({ database });
+    req.app.set('sanctionsScreeningService', service);
+    return service;
+  };
+
+  router.get('/queue', (req, res) => {
+    try {
+      const { status, limit } = req.query;
+      const service = getService(req);
+      const queue = service.listReviewQueue({ status, limit });
+      return res.status(200).json({ success: true, data: queue });
+    } catch (error) {
+      return res
+        .status(500)
+        .json({ success: false, error: error.message || 'Queue lookup failed' });
+    }
+  });
+
+  router.post('/:address/false-positive', async (req, res) => {
+    try {
+      const { address } = req.params;
+      const { reviewedBy, decisionNotes } = req.body || {};
+      if (!reviewedBy) {
+        return res
+          .status(400)
+          .json({ success: false, error: 'reviewedBy is required' });
+      }
+      const service = getService(req);
+      const result = await service.markFalsePositive({
+        walletAddress: address,
+        reviewedBy,
+        decisionNotes,
+      });
+      return res.status(200).json({ success: true, data: result });
+    } catch (error) {
+      const status = /not currently blocked/i.test(error.message) ? 409 : 500;
+      return res
+        .status(status)
+        .json({ success: false, error: error.message || 'Review failed' });
+    }
+  });
+
+  router.post('/:address/confirm', async (req, res) => {
+    try {
+      const { address } = req.params;
+      const { reviewedBy, decisionNotes } = req.body || {};
+      if (!reviewedBy) {
+        return res
+          .status(400)
+          .json({ success: false, error: 'reviewedBy is required' });
+      }
+      const service = getService(req);
+      const result = await service.confirmSanction({
+        walletAddress: address,
+        reviewedBy,
+        decisionNotes,
+      });
+      return res.status(200).json({ success: true, data: result });
+    } catch (error) {
+      const status = /not currently blocked/i.test(error.message) ? 409 : 500;
+      return res
+        .status(status)
+        .json({ success: false, error: error.message || 'Review failed' });
+    }
+  });
+
+  router.get('/:address/audit', (req, res) => {
+    try {
+      const { address } = req.params;
+      const { limit } = req.query;
+      const service = getService(req);
+      const audit = service.getAuditTrail(address, { limit });
+      return res.status(200).json({ success: true, data: audit });
+    } catch (error) {
+      return res
+        .status(500)
+        .json({ success: false, error: error.message || 'Audit lookup failed' });
+    }
+  });
+
+  router.get('/:address', (req, res) => {
+    try {
+      const { address } = req.params;
+      const service = getService(req);
+      const status = service.getAccountStatus(address);
+      if (!status) {
+        return res.status(404).json({
+          success: false,
+          error: `No screening record for ${address}`,
+        });
+      }
+      return res.status(200).json({ success: true, data: status });
+    } catch (error) {
+      return res
+        .status(500)
+        .json({ success: false, error: error.message || 'Status lookup failed' });
+    }
+  });
+
+  return router;
+}
+
+module.exports = createSanctionsComplianceRoutes;

routes/stellarAuth.js

@@ -73,14 +73,42 @@ router.post('/verify', async (req, res) => {
 
     // Verify the challenge
     const verification = await stellarService.verifyChallenge(challengeXDR, publicKey);
-    
+
     if (!verification.success) {
       return res.status(400).json({
         success: false,
         error: verification.error
       });
     }
 
+    // OFAC / global-sanctions screening — must complete BEFORE we issue a
+    // JWT, otherwise a flagged wallet would have a valid token in the wild.
+    const sanctionsService = req.app.get('sanctionsScreeningService');
+    if (sanctionsService) {
+      try {
+        const screen = await sanctionsService.screenAddress(publicKey, {
+          triggeringAction: 'sep10_verify',
+          ipAddress: req.ip,
+        });
+        if (!screen.allowed) {
+          return res.status(403).json({
+            success: false,
+            error: 'ACCOUNT_BLOCKED',
+            message:
+              'This wallet is blocked by sanctions screening. Contact compliance for review.',
+            auditId: screen.auditId,
+          });
+        }
+      } catch (screenError) {
+        console.error('Sanctions screening error during SEP-10 verify:', screenError);
+        // Treat unexpected service errors as fail-closed at the gate.
+        return res.status(503).json({
+          success: false,
+          error: 'Sanctions screening unavailable; please retry shortly.',
+        });
+      }
+    }
+
     // Determine user tier (in production, fetch from database)
     // For now, assign bronze tier to all users
     const userTier = 'bronze';

routes/subscription.js

@@ -24,6 +24,42 @@ router.post('/events', async (req, res) => {
       return res.status(400).json({ success: false, error: 'Missing required fields: type, creatorId' });
     }
 
+    // OFAC / global-sanctions screening for subscription initialization. We
+    // only screen on 'subscribed' (the act of initializing a subscription).
+    // Already-blocked wallets are rejected with zero latency via the cached
+    // isBlocked() check; new wallets get a full provider call.
+    if (walletAddress && String(type).toLowerCase() === 'subscribed') {
+      const sanctionsService = app.get('sanctionsScreeningService');
+      if (sanctionsService) {
+        try {
+          const screen = await sanctionsService.screenAddress(walletAddress, {
+            triggeringAction: 'subscription_init',
+            ipAddress: ipAddress || req.ip,
+            actor: creatorId,
+          });
+          if (!screen.allowed) {
+            return res.status(403).json({
+              success: false,
+              error: 'ACCOUNT_BLOCKED',
+              message:
+                'Subscription rejected: wallet is blocked by sanctions screening.',
+              auditId: screen.auditId,
+            });
+          }
+        } catch (screenError) {
+          // eslint-disable-next-line no-console
+          console.error(
+            'Sanctions screening error during subscription init:',
+            screenError && screenError.stack ? screenError.stack : screenError
+          );
+          return res.status(503).json({
+            success: false,
+            error: 'Sanctions screening unavailable; please retry shortly.',
+          });
+        }
+      }
+    }
+
     const result = await subscriptionService.handleEvent({ type, creatorId, walletAddress, timestamp, ipAddress });
 
     return res.status(200).json({ success: true, data: result });