SumSub KYC integration · diseño non-custodial

Cuandeoro NO custodia documentos · SumSub es processor único · Marco scope 2026-06-01

1. Separación de roles

2. Datos permitidos vs prohibidos

3. Flujos

3.1 · Flujo normal (KYC documental via SumSub)

3.2 · Flujo privacidad reforzada (KYC sin docs visibles para Cuandeoro)

4. Modelo PostgreSQL

Schema completo idempotente generado en /srv/cuandeoro_kyc/schema.sql. Resumen:

4.1 · kyc_profiles

4.2 · kyc_provider_events

4.3 · kyc_attestations

4.4 · kyc_audit_log

5. Endpoints backend

{
  "stellar_address": "GAB...XYZ",
  "verification_level": "basic_kyc" | "enhanced_due_diligence" | "kyb_corporate",
  "country_of_residence": "ES",
  "enhanced_privacy": false
}

1. Verificar que stellar_address pertenece a la sesión
2. Crear applicant en SumSub vía POST /resources/applicants?levelName=...
3. INSERT kyc_profiles (status='init', applicant_id, level, country)
4. INSERT kyc_audit_log (operation='profile_create')
5. Generar accessToken SumSub para SDK del frontend
6. Devolver al frontend: { sumsub_token, sdk_init_params }

{
  "kyc_profile_id": "uuid",
  "sumsub_token": "_act-jwt-...",
  "sumsub_level": "basic-kyc-level",
  "sdk_config": { ... }
}

X-Payload-Digest: <HMAC-SHA256 hex del body con secret compartido>
X-Payload-Digest-Alg: HMAC_SHA256_HEX
X-Sumsub-Webhook-Timestamp: 1717221234
Content-Type: application/json

1. Leer body raw + headers
2. Verificar X-Sumsub-Webhook-Timestamp dentro de skew (±5 min)
3. Calcular HMAC-SHA256(body, SUMSUB_WEBHOOK_SECRET)
   → compare constant-time con X-Payload-Digest
4. Si firma inválida:
   - INSERT kyc_provider_events (signature_valid=false, status='rejected_invalid_signature')
   - return 401
5. Si firma OK:
   - extract event_id, applicant_id del body
   - INSERT kyc_provider_events ON CONFLICT (provider, provider_event_id) DO NOTHING
   - si duplicado: return 200 (idempotente)
   - si nuevo: procesar según event_type
     · applicantReviewed → UPDATE kyc_profiles SET status='approved'|'rejected', risk_score, etc.
     · applicantPending → status='pending'
     · applicantOnHold → status='on_hold'
6. INSERT kyc_audit_log (operation='webhook_processed', external_event_ref=event_id)
7. return 200 { "status": "ok" } SIEMPRE (SumSub reintenta si no es 2xx)

1. Verificar stellar_address ∈ sesión
2. SELECT desde kyc_profiles_active WHERE stellar_address = $1
3. NO devolver: applicant_id raw (PII proxy), hashes binarios
4. SÍ devolver: status, level, risk_band (no score exacto al usuario),
   country, timestamp_verified, timestamp_expires
5. INSERT kyc_audit_log (operation='profile_read', actor=user)

{
  "verification_status": "approved",
  "verification_level": "basic_kyc",
  "risk_band": "low",
  "country_of_residence": "ES",
  "timestamp_verified": "2026-05-30T10:00:00Z",
  "timestamp_expires": "2027-05-30T10:00:00Z",
  "compliance_flags": {
    "pep": "clear",
    "sanctions": "clear",
    "adverse_media": "clear"
  }
}

{
  "stellar_address": "GAB...XYZ",
  "reason": "user_request" | "periodic_review" | "risk_signal" | "regulatory_inquiry"
}

1. SELECT kyc_profile_id FROM kyc_profiles WHERE stellar_address=$1 AND deleted_at IS NULL
2. POST a SumSub /resources/applicants/{applicant_id}/reset/{rejection_label}
   o /resources/applicants/{applicant_id}/proceed
3. UPDATE kyc_profiles SET verification_status='recheck_required', timestamp_last_reviewed=NOW()
4. INSERT kyc_audit_log (operation='profile_update_status', details={reason, triggered_by})
5. SumSub eventualmente dispara nuevo webhook con estado actualizado

6. Validación webhook SumSub

Algoritmo de verificación (Python)

import hmac, hashlib, time
from fastapi import Request, HTTPException

SUMSUB_WEBHOOK_SECRET = os.environ['SUMSUB_WEBHOOK_SECRET']  # de Vault
MAX_TIMESTAMP_SKEW_SEC = 300  # 5 min

async def verify_sumsub_webhook(request: Request) -> bytes:
    body = await request.body()
    signature_hex = request.headers.get('x-payload-digest')
    digest_alg    = request.headers.get('x-payload-digest-alg', '')
    timestamp_str = request.headers.get('x-sumsub-webhook-timestamp')

    if not signature_hex or not timestamp_str:
        raise HTTPException(401, 'missing signature headers')

    if digest_alg != 'HMAC_SHA256_HEX':
        raise HTTPException(401, f'unsupported alg {digest_alg}')

    # Skew check
    try:
        ts = int(timestamp_str)
    except ValueError:
        raise HTTPException(401, 'invalid timestamp')
    if abs(time.time() - ts) > MAX_TIMESTAMP_SKEW_SEC:
        raise HTTPException(401, 'timestamp skew exceeded')

    # HMAC en bytes · constant-time compare
    expected = hmac.new(
        SUMSUB_WEBHOOK_SECRET.encode(),
        body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature_hex):
        raise HTTPException(401, 'invalid signature')

    return body

7. Idempotencia de eventos

Mecanismo

-- Tabla kyc_provider_events tiene:
CONSTRAINT one_event_per_provider_id UNIQUE (provider, provider_event_id)

-- En el handler:
INSERT INTO kyc_provider_events (...)
VALUES (...)
ON CONFLICT (provider, provider_event_id) DO NOTHING
RETURNING id;

-- Si RETURNING devuelve 0 filas:
--   → evento ya procesado (duplicado · idempotente)
--   → responder 200 con {"status":"already_processed"}
-- Si RETURNING devuelve 1 fila:
--   → evento nuevo · proceder a actualizar kyc_profiles + audit_log

Garantías

• Exactly-once en kyc_profiles: el UPDATE solo se ejecuta si el INSERT en provider_events fue exitoso (no duplicado)
• At-least-once en webhook reception: SumSub reintenta hasta 2xx
• Audit log no-PII: incluso si event se rechaza, queda traza con signature_hash + status

8. Política GDPR

8.1 · Data minimization (Art. 5.1.c)

8.2 · No document custody

8.3 · Retention periods

8.4 · Right to erasure (Art. 17) where legally possible

SELECT gdpr_art17_purge_profile('GAB...XYZ', 'gdpr_art17_user_request');

-- Función SECURITY DEFINER · OWNER cuandeoro_kyc_auditor (inmutable)
-- Hace soft-delete, mantiene metadata mínima por AML retention 5 años
-- Después: aml_retention_hard_delete() job nocturno purga hard tras 5 años

8.5 · Right of access (Art. 15) / portability (Art. 20)

-- Función helper que exporta TODO lo que Cuandeoro tiene del usuario
CREATE FUNCTION gdpr_art15_export_profile(p_stellar_address VARCHAR)
RETURNS JSONB · SECURITY DEFINER
-- Devuelve JSONB con todo de kyc_profiles + audit_log entries de ese usuario
-- + nota: "Para datos completos KYC contactar SumSub directamente con applicant_id X"

8.6 · DPA con SumSub

• Firmar Data Processing Agreement (DPA) con SumSub antes de primer applicant productivo
• SumSub debe estar registrada como sub-processor en política de privacidad Cuandeoro
• Verificar SumSub ubicación servidores (UK / EU / Suiza) para evaluar transfers internacionales
• Si SumSub usa subprocesadores propios (AWS, GCP) → lista incluida en DPA

9. ⚠ Advertencia legal final