Hugging Face's logo

Spaces:
yusufcalisir
/
Collaborative-Fraud-Intelligence-Simulator
Running

App Files Community
Collaborative-Fraud-Intelligence-Simulator / docs /developer_and_api_portal.md
yusufcalisir's picture
yusufcalisir
deploy: Hugging Face space upload
8af5729
preview code
|
Raw History Blame Contribute Delete
14.5 kB

📖 Developer & Interactive API Portal Specification

1. Overview & Architectural Role

The Collaborative Fraud Intelligence (CF-Intelligence) platform provides high-throughput gRPC and REST communication channels alongside an enterprise-grade WebSocket surface for real-time fraud scoring, fuzzy entity matching, compliance filing export, and infrastructure diagnostics.

To accelerate bank consortium onboarding, core banking connectivity, and SIEM integration, the platform features a dedicated Developer Portal (/developer), automated Multi-Language SDK Code Generator, a dark-themed Scalar API Gateway (/scalar), standard OpenAPI documentation gateways (/docs, /redoc), and a Live Interactive Request Runner Sandbox.

All endpoints enforce Zero Raw PII transmission. Identifiers are salted and hashed via HMAC-SHA256 before inference or cross-bank PSI operations.

2. API Surface & Gateway Index

Endpoint / Gateway Protocol Authentication Description
GET /scalar HTTP/1.1 Public / SSO Interactive dark-themed Scalar API Reference targeting /openapi.json with modern responsive layout
GET /openapi.json HTTP/1.1 Public OpenAPI 3.1.0 compliant JSON schema specification (140+ active operations)
GET /docs & GET /redoc HTTP/1.1 Public Interactive Swagger UI and ReDoc documentation gateways with mobile-responsive containment and CSP headers
WS /ws/telemetry WebSocket / WSS Bearer JWT Real-time bi-directional telemetry: live scored transactions, critical fraud alerts & heartbeats
WS /ws/training/{simulation_id} WebSocket / WSS Bearer JWT Redis pub/sub streaming of federated training round convergence events & per-bank AUC
POST /api/v1/predict/score HTTP/1.1 Bearer JWT / API Key Real-time payment fraud inference (<10ms) with PyTorch GAT & SHAP attribution (alias /api/v1/score-transaction)
POST /api/v1/predict HTTP/1.1 Bearer JWT / API Key Full 9-signal composite risk inference with dynamic policy rule evaluation
POST /api/v1/predict/feedback HTTP/1.1 Bearer JWT / API Key Ground-truth fraud label ingestion into feedback loop with DP noise injection
POST /api/v1/psi/match HTTP/1.1 mTLS + Bearer JWT Privacy-Preserving Diffie-Hellman Private Set Intersection (DH-PSI) cross-bank mule detection (alias /api/v1/entities/psi-match)
POST /api/v1/entities/psi HTTP/1.1 Bearer JWT Cross-bank entity set intersection with fuzzy MinHash LSH matching
POST /api/v1/entities/fuzzy-resolve HTTP/1.1 Bearer JWT Resolve fuzzy entity names against consortium identity graph via MinHash LSH
POST /api/v1/entities/hmac-tokenize HTTP/1.1 Bearer JWT Tokenize raw identifiers into tenant-salted HMAC tokens enforcing Zero Raw PII
GET|POST /api/v1/coordinator/negotiate HTTP/1.1 mTLS + Bearer JWT Dynamic hardware (GPU VRAM, bandwidth) & Non-IID Dirichlet hyperparameter negotiation
GET /api/v1/coordinator/clients HTTP/1.1 Bearer JWT Registered bank node runtime profiles, hardware status, and heartbeat timestamps
POST /api/v1/coordinator/handshake HTTP/1.1 mTLS + Bearer JWT Bank client registration and hardware capability exchange
POST /api/v1/cases/export/fincen-xml HTTP/1.1 Bearer JWT (4-Eyes) FinCEN BSA Electronic Filing SAR XML compilation with Four-Eyes dual supervisor signing
GET /api/v1/banks/scoring-volume HTTP/1.1 Bearer JWT / API Key 24-hour aggregated transaction scoring volume and metrics across consortium banks
GET /api/v1/training/{simulation_id}/rounds HTTP/1.1 Bearer JWT Training round convergence metrics: global AUC, round duration, per-bank AUC & loss
GET /api/v1/diagnostics/connectors HTTP/1.1 Bearer JWT / Admin Probe health across 7 enterprise infrastructure tiers (Kafka, Vault, KMS, Splunk, Redis, DB, ISO 20022)
POST /api/v1/diagnostics/test-connector HTTP/1.1 Bearer JWT / Admin On-demand live handshake ping test for specific enterprise adapter
POST /api/v1/scenarios/inject-attack HTTP/1.1 Bearer JWT Inject Adversarial Byzantine Attack & Evaluate Multi-Krum Shield
POST /api/v1/datasets/contract-audit HTTP/1.1 Bearer JWT Audit Ingested Transactions via Great Expectations Data Contract
POST /api/v1/datasets/consortium-enroll HTTP/1.1 Bearer JWT Enroll Validated Partition into Federated Learning Round

3. Multi-Language SDK Code Generation

The in-app Developer Portal (/developer) dynamically compiles production-ready integration snippets for five core programming languages:

3.1 cURL CLI 

curl -X POST "https://cf-intelligence.vercel.app/api/v1/predict/score" \
  -H "Authorization: Bearer $CFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_live_994821",
    "account_id": "acc_eur_994821",
    "amount": 250000.0,
    "currency": "EUR",
    "merchant_id": "crypto_exchange_berlin",
    "country": "DE",
    "device_id": "device_fp_alpha_091"
  }'

3.2 Python (httpx / AsyncIO) 

import httpx
import asyncio

async def score_transaction(api_key: str, payload: dict) -> dict:
    url = "https://cf-intelligence.vercel.app/api/v1/predict/score"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.post(url, headers=headers, json=payload)
        resp.raise_for_status()
        return resp.json()

if __name__ == "__main__":
    payload = {
        "transaction_id": "txn_live_994821",
        "account_id": "acc_eur_994821",
        "amount": 250000.0,
        "currency": "EUR",
        "merchant_id": "crypto_exchange_berlin",
        "country": "DE",
        "device_id": "device_fp_alpha_091"
    }
    result = asyncio.run(score_transaction("cfi_live_key_alpha", payload))
    print(f"Decision: {result.get('decision')}, Risk Score: {result.get('risk_score')}, Latency: {result.get('latency_ms')}ms")

3.3 Node.js / TypeScript (axios) 

import axios from 'axios';

interface ScoreResponse {
  risk_score: number;
  risk_level: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
  decision: 'APPROVE' | 'REVIEW' | 'BLOCK' | 'BLOCK_AND_ESCALATE';
  model_version: string;
  latency_ms: number;
}

export async function checkFraudRisk(apiKey: string, transaction: Record<string, unknown>): Promise<ScoreResponse> {
  const { data } = await axios.post<ScoreResponse>(
    'https://cf-intelligence.vercel.app/api/v1/predict/score',
    transaction,
    {
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      timeout: 5000,
    }
  );
  return data;
}

3.4 Java (OkHttp) 

import okhttp3.*;
import java.io.IOException;

public class FraudClient {
    private static final OkHttpClient client = new OkHttpClient();
    private static final MediaType JSON = MediaType.get("application/json; charset=utf-8");

    public static String scoreTransaction(String apiKey, String jsonBody) throws IOException {
        RequestBody body = RequestBody.create(jsonBody, JSON);
        Request request = new Request.Builder()
            .url("https://cf-intelligence.vercel.app/api/v1/predict/score")
            .header("Authorization", "Bearer " + apiKey)
            .post(body)
            .build();

        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
            return response.body().string();
        }
    }
}

3.5 Go (net/http) 

package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
    "time"
)

func ScoreTransaction(apiKey string, jsonPayload []byte) ([]byte, error) {
    client := &http.Client{Timeout: 5 * time.Second}
    req, err := http.NewRequest("POST", "https://cf-intelligence.vercel.app/api/v1/predict/score", bytes.NewBuffer(jsonPayload))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    return io.ReadAll(resp.Body)
}

4. Real-Time WebSocket Telemetry Protocol

4.1 Connection & Heartbeat Handshake

  • Connection URI: ws://<host>:<port>/ws/telemetry or wss://<host>:<port>/ws/telemetry
  • Heartbeat Interval: Server transmits {"type": "PING", "timestamp": "..."} every 30 seconds.
  • Client Acknowledgement: Client responds with {"action": "PONG"} within 10 seconds to maintain channel liveness.

4.2 Subscription Frame 

{
  "action": "subscribe",
  "channels": ["transactions", "alerts", "heartbeat"]
}

4.3 High-Risk Alert Broadcast ($S \ge 700$) 

{
  "type": "FRAUD_ALERT",
  "transaction_id": "txn_live_994821",
  "bank_id": "bank_alpha",
  "amount": 250000.0,
  "currency": "EUR",
  "risk_score": 942,
  "decision": "BLOCK_AND_ESCALATE",
  "reason": "Velocity surge detected across 3 consortium nodes within 90 seconds",
  "timestamp": "2026-09-02T14:35:15Z"
}

4.4 Live Federated Training Round Streaming (WS /ws/training/{simulation_id})

Streams real-time convergence envelopes as each federated aggregation round completes via Redis pub/sub (training:{simulation_id}):

{
  "round": 4,
  "metrics": {
    "round": 4,
    "global_auc": 0.887,
    "loss": 0.283,
    "duration_sec": 3.42,
    "participating_banks": 3,
    "bank_metrics": {
      "bank_alpha": {"auc": 0.892, "loss": 0.274, "samples": 12500},
      "bank_beta": {"auc": 0.879, "loss": 0.291, "samples": 9800},
      "bank_gamma": {"auc": 0.890, "loss": 0.284, "samples": 11200}
    }
  },
  "timestamp": 1725580800.0
}

5. Enterprise Connector Diagnostics Architecture

The ConnectorDiagnosticsService evaluates live reachability, TLS handshakes, and round-trip ping latency across 7 enterprise banking infrastructure tiers:

  1. Apache Kafka: Topic metadata fetch and broker latency probe (kafka.internal:9092).
  2. HashiCorp Vault: Root PKI token check and transit mount inspection (https://vault.internal:8200).
  3. AWS KMS / HSM: Hardware security module envelope encryption key status (kms.eu-central-1.amazonaws.com).
  4. Splunk HEC SIEM: Raw event ingestion endpoint handshake (https://splunk.internal:8088/services/collector).
  5. Redis Sentinel / Cluster: Master/Replica ping and atomic lock verification (redis.internal:6379).
  6. PostgreSQL Relational DB: Connection pool health and multi-tenant schema isolation audit (postgresql.internal:5432).
  7. ISO 20022 Engine: High-throughput pacs.008 and camt.053 XML parser benchmark.

5.1 Diagnostics Overview Schema (GET /api/v1/diagnostics/connectors) 

{
  "total_connectors": 7,
  "healthy_connectors": 7,
  "avg_latency_ms": 2.4,
  "connectors": [
    {
      "connector_id": "kafka",
      "name": "Apache Kafka Event Broker",
      "status": "HEALTHY",
      "latency_ms": 3.4,
      "protocol": "PLAINTEXT/SASL_SSL",
      "endpoint": "kafka.internal:9092"
    },
    {
      "connector_id": "vault",
      "name": "HashiCorp Vault PKI Engine",
      "status": "HEALTHY",
      "latency_ms": 1.8,
      "protocol": "HTTPS",
      "endpoint": "https://vault.internal:8200"
    }
  ]
}

5.2 On-Demand Active Probe (POST /api/v1/diagnostics/test-connector) 

{
  "connector_id": "vault",
  "success": true,
  "status_code": 200,
  "round_trip_ms": 2.1,
  "handshake_summary": "TLS 1.3 handshake verified; Vault transit engine responsive.",
  "diagnostics_log": [
    "Resolving vault.internal:8200 DNS record",
    "TLS 1.3 mutual handshake established",
    "Transit secret engine mount status verified: OK"
  ]
}

6. In-App Developer Portal Architecture (/developer)

The Developer Portal UI (frontend/src/pages/ApiDocsPage.tsx) provides a rich client-side workspace:

  • Top Action Bar:
    • Export OpenAPI JSON: Generates and downloads a client-side OpenAPI 3.1.0 specification bundle (cfi-openapi-spec.json).
    • Scalar Gateway Link (/scalar): Opens the modern, dark-themed responsive reference powered by @scalar/api-reference.
    • ReDoc Link (/redoc): Accesses mobile-responsive ReDoc documentation with deep response schema exploration and dark tab styling.
    • Swagger UI Link (/docs): Accesses standard OpenAPI interactive Swagger gateway with responsive layout.
  • Interactive Request Runner Sandbox:
    • Enables developers to select any consortium endpoint, configure parameters or JSON payload, and execute live queries directly against the platform.
    • Measures execution latency (performance.now()), formats HTTP status badges (200 OK, 400 Bad Request), and renders JSON syntax-highlighted responses.

7. 🧪 Automated Test Suite Parity

The Developer Portal and API surface are thoroughly validated across both frontend and backend test suites:

7.1 Frontend Vitest Suite 

npm --prefix frontend test src/pages/__tests__/ApiDocsPage.test.tsx
# 3 passed (100% Pass)
  • Validates portal header, quick links, and endpoints directory rendering.
  • Verifies code generator language tabs switching (Python, Java, Node, cURL).
  • Tests live interactive request runner execution and response payload display.

7.2 Backend Pytest Suites 

python -m pytest \
  backend/tests/unit/test_developer_portal_api_parity.py \
  backend/tests/unit/test_connector_diagnostics.py \
  backend/tests/unit/test_openapi_contract_accuracy.py \
  backend/tests/contract/test_openapi_contract.py -v
# 22 passed in 10.26s (100% Pass)
Test Suite Test Count Scope
test_developer_portal_api_parity.py 5 /predict/score alias, /coordinator/negotiate POST, /psi/match direct, training rounds, /scalar gateway
test_connector_diagnostics.py 11 Health status across all 7 infrastructure tiers, on-demand active probe tests, error handling
test_openapi_contract_accuracy.py 2 OpenAPI 3.1 schema completeness (140+ endpoints), FinCEN BSA XML export contract
test_openapi_contract.py 4 Core OpenAPI structure, required endpoints presence, HTTP method status codes, component schemas