Merge pull request #274 from Mrchinedum/feature/sep12-kyc-persistence

feat: implement SEP-12 KYC persistence layer

Author: elizabetheonoja-art

index.js

@@ -483,6 +483,12 @@ async function createApp(dependencies = {}) {
     app.use('/auth', require('./routes/auth'));
     app.use('/auth', require('./routes/stellarAuth'));
 
+    // ── SEP-12 Customer Identification (KYC) routes ─────────────────────────────
+    app.use('/sep12', require('./routes/sep12'));
+
+    // ── SumSub KYC Webhook ───────────────────────────────────────────────────────
+    app.use('/webhooks', require('./routes/sumsubWebhook'));
+
     // ── SEP-24 Interactive Flow routes ───────────────────────────────────────────
     app.use('/sep24', require('./routes/sep24'));
 

migrations/knex/020_create_sep12_kyc_tables.js

@@ -0,0 +1,57 @@
+/**
+ * SEP-12 KYC Tables
+ *
+ * customer_profiles        : Stores encrypted PII per Stellar pubkey.
+ *                            All sensitive fields are AES-256 ciphertext blobs.
+ * merchant_kyc_requirements: Per-merchant tier requirements that drive
+ *                            "requirement masking" — which fields are needed
+ *                            before a customer is cleared for a given plan.
+ */
+exports.up = async function up(knex) {
+  await knex.schema.createTable('customer_profiles', (table) => {
+    table.string('id').primary().defaultTo(knex.raw("(lower(hex(randomblob(16))))"));
+    table.string('stellar_account').notNullable().unique();
+
+    // Encrypted PII blobs (AES-256-GCM, base64-encoded: iv:authTag:ciphertext)
+    table.text('enc_full_name').nullable();
+    table.text('enc_address').nullable();
+    table.text('enc_date_of_birth').nullable();
+    table.text('enc_id_photo_cid').nullable();   // IPFS CID of uploaded ID document
+
+    // KYC status managed by SumSub webhook
+    table.string('verification_status').notNullable().defaultTo('NEEDS_INFO');
+    // NEEDS_INFO | PENDING | APPROVED | REJECTED
+
+    table.string('sumsub_applicant_id').nullable().unique();
+    table.text('rejection_reason').nullable();
+
+    table.timestamp('created_at').notNullable().defaultTo(knex.fn.now());
+    table.timestamp('updated_at').notNullable().defaultTo(knex.fn.now());
+
+    table.index(['stellar_account']);
+    table.index(['verification_status']);
+  });
+
+  await knex.schema.createTable('merchant_kyc_requirements', (table) => {
+    table.string('id').primary().defaultTo(knex.raw("(lower(hex(randomblob(16))))"));
+    table.string('merchant_id').notNullable();
+    table.string('tier_name').notNullable();   // e.g. 'Tier_1', 'Tier_2'
+
+    // Which fields are required for this merchant/tier combination
+    table.boolean('requires_full_name').notNullable().defaultTo(true);
+    table.boolean('requires_address').notNullable().defaultTo(false);
+    table.boolean('requires_date_of_birth').notNullable().defaultTo(false);
+    table.boolean('requires_id_photo').notNullable().defaultTo(false);
+
+    table.timestamp('created_at').notNullable().defaultTo(knex.fn.now());
+    table.timestamp('updated_at').notNullable().defaultTo(knex.fn.now());
+
+    table.unique(['merchant_id', 'tier_name']);
+    table.index(['merchant_id']);
+  });
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists('merchant_kyc_requirements');
+  await knex.schema.dropTableIfExists('customer_profiles');
+};

routes/sep12.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * SEP-12 Customer Identification Routes
+ *
+ * GET  /sep12/customer          – retrieve KYC status (with requirement masking)
+ * PUT  /sep12/customer          – submit / update PII fields
+ * PUT  /sep12/customer/requirements – admin: set merchant KYC requirements
+ *
+ * All endpoints require a valid JWT (authenticateToken).
+ * The authenticated wallet address is used as the Stellar account unless an
+ * admin explicitly passes ?account= (future extension).
+ */
+
+const express = require('express');
+const router = express.Router();
+const { authenticateToken } = require('../middleware/auth');
+const { CustomerService } = require('../src/services/customerService');
+const logger = require('../src/utils/logger');
+
+// Stellar public key regex (G + 55 uppercase alphanumeric chars)
+const STELLAR_ACCOUNT_RE = /^G[A-Z0-9]{55}$/;
+
+function getService(req) {
+  const db = req.app.get('database');
+  return new CustomerService(db);
+}
+
+// ─── GET /sep12/customer ────────────────────────────────────────────────────
+
+/**
+ * @query account       Stellar public key (defaults to authenticated user)
+ * @query merchant_id   Optional – enables requirement masking
+ * @query tier          Optional – tier name for requirement masking
+ */
+router.get('/customer', authenticateToken, async (req, res) => {
+  try {
+    const account = req.query.account || req.user?.id;
+    if (!account || !STELLAR_ACCOUNT_RE.test(account)) {
+      return res.status(400).json({ error: 'Invalid or missing Stellar account' });
+    }
+
+    const { merchant_id, tier } = req.query;
+    const svc = getService(req);
+    const result = await svc.getCustomer(account, merchant_id || null, tier || null);
+
+    return res.json(result);
+  } catch (err) {
+    logger.error('[SEP-12] GET /customer error', { error: err.message });
+    return res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// ─── PUT /sep12/customer ────────────────────────────────────────────────────
+
+/**
+ * @body account        Stellar public key (defaults to authenticated user)
+ * @body full_name      string
+ * @body address        string
+ * @body date_of_birth  string  YYYY-MM-DD
+ * @body id_photo_cid   string  IPFS CID
+ */
+router.put('/customer', authenticateToken, async (req, res) => {
+  try {
+    const account = req.body.account || req.user?.id;
+    if (!account || !STELLAR_ACCOUNT_RE.test(account)) {
+      return res.status(400).json({ error: 'Invalid or missing Stellar account' });
+    }
+
+    const { full_name, address, date_of_birth, id_photo_cid } = req.body;
+    const fields = {};
+    if (full_name !== undefined) fields.full_name = full_name;
+    if (address !== undefined) fields.address = address;
+    if (date_of_birth !== undefined) fields.date_of_birth = date_of_birth;
+    if (id_photo_cid !== undefined) fields.id_photo_cid = id_photo_cid;
+
+    if (Object.keys(fields).length === 0) {
+      return res.status(400).json({ error: 'No KYC fields provided' });
+    }
+
+    const svc = getService(req);
+    const result = await svc.putCustomer(account, fields);
+
+    return res.status(202).json(result);
+  } catch (err) {
+    logger.error('[SEP-12] PUT /customer error', { error: err.message });
+    return res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// ─── PUT /sep12/customer/requirements ──────────────────────────────────────
+
+/**
+ * Admin endpoint: define which fields a merchant requires for a given tier.
+ *
+ * @body merchant_id
+ * @body tier_name
+ * @body requires_full_name       boolean
+ * @body requires_address         boolean
+ * @body requires_date_of_birth   boolean
+ * @body requires_id_photo        boolean
+ */
+router.put('/customer/requirements', authenticateToken, async (req, res) => {
+  try {
+    const { merchant_id, tier_name, ...rest } = req.body;
+    if (!merchant_id || !tier_name) {
+      return res.status(400).json({ error: 'merchant_id and tier_name are required' });
+    }
+
+    const allowed = ['requires_full_name', 'requires_address', 'requires_date_of_birth', 'requires_id_photo'];
+    const requirements = {};
+    for (const key of allowed) {
+      if (rest[key] !== undefined) requirements[key] = Boolean(rest[key]);
+    }
+
+    const svc = getService(req);
+    await svc.setMerchantRequirements(merchant_id, tier_name, requirements);
+
+    return res.json({ success: true, merchant_id, tier_name, requirements });
+  } catch (err) {
+    logger.error('[SEP-12] PUT /customer/requirements error', { error: err.message });
+    return res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+module.exports = router;

routes/sumsubWebhook.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * SumSub Webhook Handler
+ *
+ * POST /webhooks/sumsub
+ *
+ * SumSub sends a signed payload whenever an applicant's review status changes.
+ * We verify the HMAC-SHA256 signature, map the SumSub review result to our
+ * internal STATUS, then call CustomerService.updateVerificationStatus().
+ *
+ * Signature verification:
+ *   X-App-Token  : SumSub app token (identifies the sender)
+ *   X-App-Access-Sig : HMAC-SHA256(secret, timestamp + body)
+ *   X-App-Access-Ts  : Unix timestamp (used in signature)
+ *
+ * Env vars:
+ *   SUMSUB_WEBHOOK_SECRET  – shared secret for HMAC verification
+ *   SUMSUB_APP_TOKEN       – expected app token header value
+ */
+
+const express = require('express');
+const crypto = require('crypto');
+const router = express.Router();
+const { CustomerService, STATUS } = require('../src/services/customerService');
+const logger = require('../src/utils/logger');
+
+// SumSub reviewResult → internal STATUS
+const REVIEW_RESULT_MAP = {
+  GREEN: STATUS.APPROVED,
+  RED: STATUS.REJECTED,
+  // Intermediate states
+  PENDING: STATUS.PENDING,
+  RETRY: STATUS.NEEDS_INFO,
+};
+
+/**
+ * Verify SumSub HMAC-SHA256 signature.
+ * Signature = HMAC-SHA256(secret, timestamp + rawBody)
+ */
+function verifySignature(rawBody, timestamp, sig) {
+  const secret = process.env.SUMSUB_WEBHOOK_SECRET;
+  if (!secret) {
+    logger.warn('[SumSub] SUMSUB_WEBHOOK_SECRET not set — skipping signature verification');
+    return true; // allow in dev; enforce in prod via env
+  }
+  const expected = crypto
+    .createHmac('sha256', secret)
+    .update(timestamp + rawBody)
+    .digest('hex');
+  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
+}
+
+// Raw body is needed for HMAC verification — mount before express.json()
+router.post(
+  '/sumsub',
+  express.raw({ type: 'application/json' }),
+  async (req, res) => {
+    const sig = req.headers['x-app-access-sig'];
+    const ts = req.headers['x-app-access-ts'];
+    const appToken = req.headers['x-app-token'];
+
+    // Validate app token if configured
+    const expectedToken = process.env.SUMSUB_APP_TOKEN;
+    if (expectedToken && appToken !== expectedToken) {
+      logger.warn('[SumSub] Webhook rejected: invalid app token');
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+
+    const rawBody = req.body.toString('utf8');
+
+    if (sig && ts && !verifySignature(rawBody, ts, sig)) {
+      logger.warn('[SumSub] Webhook rejected: invalid signature');
+      return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    let payload;
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      return res.status(400).json({ error: 'Invalid JSON' });
+    }
+
+    const { applicantId, externalUserId, type, reviewResult } = payload;
+
+    // We only care about applicantReviewed events
+    if (type !== 'applicantReviewed') {
+      return res.status(200).json({ received: true });
+    }
+
+    if (!externalUserId) {
+      logger.warn('[SumSub] Webhook missing externalUserId', { applicantId });
+      return res.status(400).json({ error: 'externalUserId required' });
+    }
+
+    const reviewAnswer = reviewResult?.reviewAnswer; // GREEN | RED
+    const internalStatus = REVIEW_RESULT_MAP[reviewAnswer] || STATUS.PENDING;
+    const rejectionReason = reviewResult?.rejectLabels?.join(', ') || null;
+
+    try {
+      const db = req.app.get('database');
+      const svc = new CustomerService(db);
+      await svc.updateVerificationStatus(externalUserId, internalStatus, {
+        applicantId,
+        rejectionReason,
+      });
+
+      logger.info('[SumSub] Verification status updated', {
+        stellarAccount: externalUserId,
+        status: internalStatus,
+        applicantId,
+      });
+
+      return res.status(200).json({ received: true });
+    } catch (err) {
+      logger.error('[SumSub] Failed to update verification status', { error: err.message });
+      return res.status(500).json({ error: 'Internal server error' });
+    }
+  }
+);
+
+module.exports = router;