> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Security & Data Compliance

> Data privacy standards (GDPR, NDPR, POPIA, LGPD), on-chain vs. off-chain PII separation, Right to Erasure, and security governance.

# Security & Data Compliance

LearnWay is engineered to meet global and regional data protection standards (GDPR, NDPR, POPIA, LGPD, and Apple/Google App Store privacy guidelines) while balancing the immutability of blockchain technology with user privacy rights.

***

## Data Privacy & Compliance Topology

```mermaid theme={null}
graph TD
    subgraph PrivacyFrameworks["🛡️ Regulatory Standards"]
        GDPR["GDPR (EU & Global)"]
        Regional["NDPR, POPIA & LGPD (Africa & LatAm)"]
        AppStore["Apple & Google App Store Privacy (5.1.1v)"]
        Web3Privacy["Web3 On-Chain vs. Off-Chain Standards"]
    end

    subgraph ArchitecturalControls["⚙️ Technical Safeguards"]
        Erasure["Right to Erasure (DELETE /api/v2/user/profile)"]
        DataMin["Zero PII On-Chain (Pseudonymous Only)"]
        KeyVault["Client-Side Key Vault (iOS Keychain / Android Keystore)"]
        RBAC["Role-Based Access Control (Admin / User Separation)"]
        Crypto["Cryptographic Auth (ECDSA, HMAC-SHA256, Bcrypt)"]
    end

    GDPR --> Erasure
    GDPR --> DataMin
    Regional --> DataMin
    AppStore --> Erasure
    AppStore --> KeyVault
    Web3Privacy --> DataMin
    Web3Privacy --> Crypto
    GDPR --> RBAC
```

***

## 1. Regulatory Frameworks & Compliance Controls

### A. GDPR (General Data Protection Regulation)

* **Right to Erasure ("Right to be Forgotten")**:
  * Implemented via self-serve `DELETE /api/v2/user/profile` and administrative `DELETE /api/v2/user/:userId`.
  * Cascades deletions across user records, battle participation logs, badge progress entries, and purges uploaded avatar files from the ImageKit CDN.
* **Right of Access & Data Portability**:
  * Users can export or inspect all profile data, learning history, quiz results, and wallet balances via `GET /api/v2/user/profile`, `GET /api/v2/user/me`, and the `transactions_apiv2/` ledger API.
* **Right to Rectification**:
  * Users maintain complete control over their display name, country code, preferred UI language, and wallet address linkages via `PATCH /api/v2/user/profile`.
* **Data Minimization**:
  * LearnWay collects strictly minimal personal data: email or social OAuth identifier, optional username, country code, and preferred language. Biometric data and government IDs are never requested or stored on backend servers.

***

### B. Regional Data Protection (NDPR, POPIA, LGPD)

* LearnWay operates across high-growth emerging markets supported by localized mobile money and airtime rails (NGN, KES, GHS, UGX, ZAR, BRL via Fonbnk):
  * **Nigeria Data Protection Regulation (NDPR)**: Explicit user consent obtained during account creation; strict purpose limitation for payment processing.
  * **South Africa POPIA**: Lawful processing of user activity metrics and notification preferences.
  * **Brazil LGPD**: Rigorous handling and cryptographic separation of payment order identifiers from general student learning data.

***

### C. Apple App Store & Google Play Privacy Guidelines

* **Mandatory In-App Account Deletion (Apple Guideline 5.1.1(v))**:
  * Apps that offer account registration must provide an accessible, instant in-app account deletion flow. LearnWay exposes this directly via mobile settings calling `DELETE /api/v2/user/profile`.
* **Client-Side Biometric & Key Isolation**:
  * Private keys, wallet recovery seeds, and biometric authentication data remain exclusively within native mobile device hardware (`iOS Keychain` / `Android Keystore`) and are never transmitted to backend servers.

***

### D. KYC & AML Compliance via DIDit (Decentralized Identity)

* **Zero PII Identity Absorption**:
  * LearnWay delegates all Know-Your-Customer (KYC), Anti-Money Laundering (AML), and proof-of-humanity verification directly to **DIDit**.
  * DIDit handles biometric scanning, official government document validation, and AML watchlist screening entirely within its regulated infrastructure.
* **Cryptographic Attestations**:
  * LearnWay's backend and databases **never store or process raw identity documents, passport scans, or facial biometric templates**.
  * LearnWay only receives a cryptographically signed verification attestation (e.g. `verificationStatus: VERIFIED`, `kycLevel: 1`, `attestationHash`).
* **Compliance Liability Isolation**:
  * By outsourcing identity verification to DIDit, all regulatory data protection, document retention, and cross-border privacy compliance concerns surrounding sensitive KYC identity documents are fully absorbed by DIDit.

***

## 2. Web3 On-Chain Data Privacy & Immutability Reconciliation

A core architectural challenge in decentralized applications is reconciling GDPR's **Right to Erasure** with the **immutable nature of blockchain ledgers**.

```mermaid theme={null}
graph LR
    subgraph OffChain["📦 Off-Chain Database (PostgreSQL & CDN)"]
        PII["Personal Identifiers<br/>• Email Address<br/>• Username & Country<br/>• Profile Photos (ImageKit)<br/>• Session Tokens"]
        DeleteOp["DELETE /api/v2/user/profile<br/>(Permanent Cascading Purge)"]
    end

    subgraph OnChain["⛓️ On-Chain Ledger (Lisk L2)"]
        PublicLedger["Pseudonymous State Only<br/>• Hex Wallet Address (0x...)<br/>• Numeric XP & Gem State<br/>• Badge Token IDs (ERC-721)<br/>• Certificate Hashes (ERC-1155)"]
    end

    DeleteOp -->|Erases Linkage & Data| PII
    PII -.->|Points to Pseudonymous Address| PublicLedger
```

### Architectural Safeguards:

1. **Zero Personally Identifiable Information (PII) On-Chain**:
   * No names, emails, phone numbers, passwords, PINs, or private keys are ever submitted to the Lisk L2 blockchain.
2. **Pseudonymous Identifiers**:
   * On-chain smart contracts (`LearnWayManager`, `XPContract`, `GemContract`, `BadgesNFT`, `LearnWayCertificate`) only store pseudonymous cryptographic addresses (`0x...`), token IDs, numeric XP/Gem values, and decentralized IPFS metadata hashes.
3. **Irreversible Anonymization Upon Deletion**:
   * When a user triggers account deletion, all off-chain PII linking their real identity to their public wallet address is permanently deleted from PostgreSQL and caches. Past on-chain transactions remain mathematically pseudonymous with zero linkage to real-world identity.

***

## 3. Cryptographic Governance & Security Controls

| Security Domain           | Architectural Mechanism           | Implementation Details                                                                                                                                                                                    |
| :------------------------ | :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Key Management**        | SLIP-39 2-of-3 MPC Secret Sharing | Master private keys are split into 3 mnemonic shares (1 local on device, 2 encrypted via Argon2id + AES-GCM on server). Threshold of 2 required to sign; zero plaintext stored on servers.                |
| **Authentication**        | JWT Access & Refresh Tokens       | Short-lived access tokens (15m) paired with rotating refresh tokens (7d) stored securely in encrypted HTTP-only or mobile keychain storage.                                                               |
| **Sensitive Actions**     | 4-to-6-Digit Wallet PIN           | High-value actions (token transfers, sponsorship requests) require security PIN verification with sliding-window brute-force rate limits.                                                                 |
| **Webhook Security**      | HMAC-SHA256 Signatures            | Inbound webhooks from third-party payment rails (Fonbnk, RevenueCat) validate cryptographic HMAC signatures before processing state transitions.                                                          |
| **Paymaster Sponsorship** | ECDSA Cryptographic Receipts      | `PaymasterSignerService` generates time-boxed (5-minute validity) ECDSA signatures validating allowed token contracts (USDT/fUSD) and methods (`transfer`/`approve`).                                     |
| **Smart Contract RBAC**   | `LearnWayAdmin.sol`               | OpenZeppelin `AccessControlDefaultAdminRules` with strict role segmentation (`DEFAULT_ADMIN_ROLE`, `MANAGER_ROLE`, `MINTER_ROLE`, `BURNER_ROLE`, `EMERGENCY_ROLE`) and instant pausable circuit breakers. |
| **API Defense**           | Rate Limiting & Proxy Trust       | Throttling guards on public routes, sliding-window limits (max 10 requests / 60s for Paymaster), and `trust proxy` configuration for reverse-proxy deployment.                                            |