Skip to content

UPASSPORT_API.md

Latest commit

 

History

History
750 lines (583 loc) · 17.8 KB

UPASSPORT_API.md

File metadata and controls

750 lines (583 loc) · 17.8 KB

🛡️ UPassport API Documentation

🌟 Vue d'ensemble

UPassport est un système complet d'identité numérique et de gestion de fichiers intégré à Astroport.ONE. Il fournit une API sécurisée (port 54321) pour gérer les identités numériques, uploader des fichiers vers IPFS et interagir avec le réseau NOSTR.

📋 Table des Matières

  1. Installation & Configuration
  2. Fonctionnalités Principales
  3. Endpoints API
  4. Authentification NOSTR
  5. Gestion de Fichiers
  6. Intégration NOSTR
  7. Sécurité & Rate Limiting
  8. Exemples d'Utilisation
  9. Dépannage
  10. Architecture Technique

🚀 Installation & Configuration

Installation Automatique

UPassport est automatiquement installé lors de la configuration d'Astroport.ONE :

# Installation via Astroport.ONE
~/.zen/Astroport.ONE/install/install_upassport.sh

# Installation manuelle
git clone https://github.com/papiche/UPassport.git ~/.zen/UPassport
cd ~/.zen/UPassport
pip install -U -r requirements.txt
./setup_systemd.sh

Configuration

Créer le fichier .env dans le répertoire UPassport :

# Configuration .env
myDUNITER="https://g1.cgeek.fr"
myCESIUM="https://g1.data.e-is.pro"
OBSkey="null"

Gestion des Services

# Démarrer le service UPassport
sudo systemctl start upassport

# Activer le démarrage automatique
sudo systemctl enable upassport

# Vérifier le statut
sudo systemctl status upassport

# Voir les logs
sudo journalctl -u upassport -f

✨ Fonctionnalités Principales

🆔 Gestion d'Identité Numérique

  • Cartes NOSTR : Création et gestion d'identités NOSTR
  • Scan QR Code : Scan de QR codes pour vérification d'identité
  • Intégration Ğ1 : Liaison des identités avec la cryptomonnaie Ğ1
  • Géolocalisation : Association des identités avec coordonnées géographiques

📁 Gestion de Fichiers IPFS

  • Stockage Structuré : Organisation automatique des fichiers (Images, Music, Videos, Documents)
  • Sécurité Twin-Key : Fichiers liés aux identités NOSTR
  • Intégration IPFS : Stockage décentralisé avec génération de CID
  • Synchronisation Drive : Sync des fichiers entre IPFS et stockage local

🔐 Système d'Authentification

  • Authentification NIP-42 : Authentification sécurisée basée sur NOSTR
  • Rate Limiting : Protection contre les abus
  • Gestion IP de Confiance : Whitelist pour réseaux de confiance
  • Gestion de Session : Gestion sécurisée des sessions

🔌 Endpoints API

URL de Base

http://localhost:54321

Endpoints Principaux

1. Interface Principale

GET /

Description : creates System json with @Ustats.sh (accept UPlanet grid coord ie. /?lat=43&lon=1&deg=1)

2. Gestion GEO Message NOSTR

GET /nostr

Description : Interface de publication des "UPlanet GEO Message"

3. Interface SCAN

GET /scan

Description : MULITPASS 0.00 email registration + QR CODE Multi Scan : MULTIPASS, ZEN Card, uPASSPORT

4. Intégration Ğ1

GET /g1

Description : Interface Inscription MULTIPASS (option credentials Ğ1) ( Geo Localized )

API de Gestion de Fichiers

1. Upload de Fichier vers IPFS

POST /api/upload

Headers :

Content-Type: multipart/form-data

Paramètres :

  • file : Fichier à uploader (requis)
  • npub : Clé publique NOSTR pour authentification (requis)

Réponse :

{
  "success": true,
  "message": "File uploaded successfully",
  "file_path": "Images/photo.jpg",
  "file_type": "image",
  "target_directory": "Images",
  "new_cid": "QmHash...",
  "timestamp": "2024-01-01T12:00:00Z",
  "auth_verified": true
}

2. Upload depuis Drive IPFS

POST /api/upload_from_drive

Body :

{
  "ipfs_link": "QmHash/filename.ext",
  "npub": "npub1..."
}

Réponse :

{
  "success": true,
  "message": "File synchronized successfully from IPFS",
  "file_path": "Videos/video.mp4",
  "file_type": "video",
  "new_cid": "QmHash...",
  "timestamp": "2024-01-01T12:00:00Z",
  "auth_verified": true
}

3. Suppression de Fichier

POST /api/delete

Body :

{
  "file_path": "Images/photo.jpg",
  "npub": "npub1..."
}

Réponse :

{
  "success": true,
  "message": "File deleted successfully (authenticated NOSTR)",
  "deleted_file": "Images/photo.jpg",
  "new_cid": "QmHash...",
  "timestamp": "2024-01-01T12:00:00Z",
  "auth_verified": true
}

4. Test d'Authentification NOSTR

POST /api/test-nostr

Body :

npub=npub1...

Réponse :

{
  "auth_verified": true,
  "npub": "npub1...",
  "message": "NOSTR authentication successful",
  "timestamp": "2024-01-01T12:00:00Z"
}

API Économie UPlanet ẐEN

1. Vérification de Solde Ğ1

GET /check_balance?g1pub={G1_PUBLIC_KEY}&html={0|1}

Paramètres :

  • g1pub : Clé publique Ğ1 (requis)
  • html : Si présent, retourne une page HTML au lieu de JSON (optionnel)

Réponse JSON :

{
  "g1pub": "XhPsqMeJX2LkPWcHEv3MY2AjEUqm...",
  "balance": "54.00",
  "zen": "530.00",
  "timestamp": "2025-10-09T15:40:47Z"
}

Formule de conversion : ẐEN = (Ğ1 - 1) × 10

2. Historique Capital Social (SOCIETY)

GET /check_society?html={0|1}

Description : Récupère l'historique des parts sociales distribuées depuis le portefeuille SOCIETY. La clé publique est automatiquement récupérée depuis l'environnement ($UPLANETNAME_SOCIETY).

Paramètres :

  • html : Si présent, retourne une page HTML stylisée (optionnel)

Réponse JSON :

{
  "g1pub": "MycKxkg9oVBvKeLdtmRwiPpNF48CDMfB7yJwKaoZJfG",
  "total_outgoing_g1": 55.0,
  "total_outgoing_zen": 530.0,
  "total_transfers": 2,
  "transfers": [
    {
      "date": "2025-09-24 00:38:31",
      "recipient": "support@qo-op.com",
      "amount_g1": 54.0,
      "amount_zen": 530.0,
      "part_type": "constellation",
      "ipfs_node": "12D3KooWL2FcDJ41U9...",
      "comment": "Constellation - UPLANET:g1LBF94v:SOCIETY:support@qo-op.com:constellation:12D3KooW..."
    }
  ],
  "timestamp": "2025-10-09T13:57:21"
}

Types de parts sociales :

  • constellation : Parts sociales constellation (540€/3ans avec IA) 🌟
  • satellite : Parts sociales satellite (50€/an sans IA) 🛰️
  • parts : Parts sociales legacy (ancien format) 📦
  • other : Autres types de transactions

Format des références blockchain :

UPLANET:${UPLANETG1PUB:0:8}:SOCIETY:${email}:${type}:${IPFSNODEID}

Traçabilité : Chaque transaction inclut l'identifiant IPFS du nœud (ipfs_node) pour identifier la machine à l'origine de la transaction.

Page HTML : Accessible via ?html=1, fournit une interface web stylisée avec :

  • Résumé du capital social total distribué
  • Tableau détaillé des parts sociales par sociétaire
  • Type de part avec icône
  • Lien vers le nœud IPFS d'origine
  • Historique complet des transactions

3. Chiffre d'Affaires (REVENUE)

GET /check_revenue?html={0|1}&year={YYYY}

Description : Récupère l'historique du Chiffre d'Affaires depuis les transactions ZENCOIN. Calcule les revenus totaux depuis le portefeuille UPLANETNAME (hub de distribution des services).

Paramètres :

  • html : Si présent, retourne une page HTML stylisée (optionnel)
  • year : Filtre par année (ex: "2024", "2025"). Par défaut: "all" (toutes les années)

Réponse JSON :

{
  "g1pub": "g1LBF94vApBWxJExucfEQyTRkAN1eFEnD5EFA2ZN8J1PpcdZ5",
  "filter_year": "all",
  "total_revenue_g1": 120.5,
  "total_revenue_zen": 1195.0,
  "total_transactions": 24,
  "yearly_summary": [
    {
      "year": "2025",
      "total_revenue_g1": 85.0,
      "total_revenue_zen": 840.0,
      "total_transactions": 17
    },
    {
      "year": "2024",
      "total_revenue_g1": 35.5,
      "total_revenue_zen": 355.0,
      "total_transactions": 7
    }
  ],
  "transactions": [
    {
      "date": "2025-10-09 14:20:15",
      "year": "2025",
      "customer_email": "frenault@linkeo.com",
      "amount_g1": 2.0,
      "amount_zen": 20.0,
      "transaction_type": "ZENCOIN",
      "comment": "Service ZENCOIN - UPLANET:g1LBF94v:ZENCOIN:frenault@linkeo.com"
    }
  ],
  "timestamp": "2025-10-09T16:30:42"
}

Filtrage par année :

  • GET /check_revenue : Toutes les années (avec résumé annuel)
  • GET /check_revenue?year=2025 : Uniquement l'année 2025
  • GET /check_revenue?year=2024 : Uniquement l'année 2024

Format des références blockchain :

UPLANET:${UPLANETG1PUB:0:8}:ZENCOIN:${email}

Calcul du CA : Le Chiffre d'Affaires est calculé depuis les transactions INCOMING (entrantes) vers UPLANETG1PUB qui :

  1. Proviennent de UPLANETNAME_G1 (réserve)
  2. Contiennent "ZENCOIN" dans la référence (ventes de services)

Page HTML : Accessible via ?html=1, fournit une interface web stylisée avec :

  • Résumé du CA total (ẐEN, Ğ1, nombre de transactions)
  • Tableau récapitulatif annuel (mode "all")
  • Boutons pour filtrer par année
  • Historique détaillé des ventes ZENCOIN avec identification client

Architecture économique :

UPLANETNAME_G1 (Réserve) 
    ↓ ÉMISSION (CA enregistré)
UPLANETNAME (UPLANETG1PUB) ← Hub de distribution
    ↓ DISTRIBUTION
MULTIPASS / ZEN Card (Services utilisateurs)

🔐 Authentification NOSTR

Principe NIP-42

UPassport utilise l'authentification NOSTR (NIP-42) pour sécuriser les opérations privilégiées :

  1. Événement d'Authentification : L'utilisateur signe un événement kind: 22242
  2. Vérification Serveur : UPassport vérifie l'événement sur le relay NOSTR local
  3. Autorisation : Si l'événement est valide et récent (< 24h), l'opération est autorisée

Workflow d'Authentification

sequenceDiagram
    participant Client as Application
    participant API as UPassport API
    participant Relay as NOSTR Relay
    participant IPFS as IPFS Storage
    
    Client->>API: POST /api/upload (avec npub)
    API->>Relay: Vérifie événement NIP-42 (kind 22242)
    Relay->>API: Retourne événements récents
    API->>API: Valide signature et timestamp
    API->>IPFS: Upload fichier si authentifié
    API->>Client: Réponse avec statut
Loading

Exemple d'Authentification (JavaScript)

// Génération de clés NOSTR
const privateKey = NostrTools.generatePrivateKey();
const publicKey = NostrTools.getPublicKey(privateKey);

// Création de l'événement d'authentification
const authEvent = {
    kind: 22242,
    created_at: Math.floor(Date.now() / 1000),
    tags: [
        ['relay', 'ws://127.0.0.1:7777'],
        ['challenge', 'astroport-auth-' + Date.now()]
    ],
    content: 'Authentification pour UPassport API'
};

// Signature de l'événement
const signedEvent = NostrTools.finishEvent(authEvent, privateKey);

// Publication sur le relay
const relay = NostrTools.relayInit('ws://127.0.0.1:7777');
await relay.connect();
await relay.publish(signedEvent);

📁 Gestion de Fichiers

Structure de Stockage

uDRIVE organise automatiquement les fichiers dans une structure hiérarchique :

~/.zen/UPassport/
├── Images/          # Images (jpg, png, gif, etc.)
├── Music/           # Fichiers audio (mp3, wav, etc.)
├── Videos/          # Fichiers vidéo (mp4, avi, etc.)
├── Documents/       # Documents (pdf, txt, doc, etc.)
├── _index.html      # Interface web de navigation
└── manifest.json    # Métadonnées du drive

Types de Fichiers Supportés

Type Extensions Description
Images jpg, jpeg, png, gif, bmp, svg Images et graphiques
Music mp3, wav, ogg, flac, m4a Fichiers audio
Videos mp4, avi, mov, mkv, webm Fichiers vidéo
Documents pdf, txt, doc, docx, odt Documents texte

Sécurité Twin-Key

Chaque fichier est lié à l'identité NOSTR de l'utilisateur :

  • Vérification de Propriété : Seul le propriétaire peut modifier ses fichiers
  • Drive Personnel : Chaque utilisateur a son propre drive IPFS
  • Synchronisation : Possibilité de sync depuis d'autres drives publics

🌐 Intégration NOSTR

Événements NOSTR

Gestion d'événements NOSTR :

  • Kind 0 : Mise à jour de profil
  • Kind 1 : Messages texte
  • Kind 3 : Contacts et suivi
  • Kind 22242 : Authentification (NIP-42)

🛡️ Sécurité & Rate Limiting

Protection contre les Abus

UPassport implémente plusieurs niveaux de protection :

1. Rate Limiting

# Limite : 100 requêtes par minute par IP
RATE_LIMIT = {
    "requests_per_minute": 100,
    "burst_limit": 10
}

2. Gestion des IP de Confiance

# Whitelist pour réseaux de confiance
TRUSTED_IPS = [
    "127.0.0.1",
    "192.168.1.0/24",
    "10.0.0.0/8"
]

3. Validation des Fichiers

# Vérification des types de fichiers
ALLOWED_EXTENSIONS = {
    "images": [".jpg", ".jpeg", ".png", ".gif"],
    "music": [".mp3", ".wav", ".ogg"],
    "videos": [".mp4", ".avi", ".mov"],
    "documents": [".pdf", ".txt", ".doc"]
}

Chiffrement et Sécurité

  • Chiffrement en Transit : HTTPS/TLS pour toutes les communications
  • Chiffrement au Repos : Fichiers chiffrés sur IPFS
  • Authentification Forte : NOSTR NIP-42 pour toutes les opérations
  • Isolation des Données : Chaque utilisateur a son propre espace

💡 Exemples d'Utilisation

1. Upload de Fichier avec Authentification

# Test d'authentification
curl -X POST http://localhost:54321/api/test-nostr \
  -F "npub=npub1..."

# Upload de fichier
curl -F "file=@photo.jpg" \
     -F "npub=npub1..." \
     http://localhost:54321/api/upload

2. Synchronisation depuis IPFS

# Sync d'un fichier depuis IPFS
curl -X POST http://localhost:54321/api/upload_from_drive \
  -H "Content-Type: application/json" \
  -d '{
    "ipfs_link": "QmHash/photo.jpg",
    "npub": "npub1..."
  }'

3. Suppression de Fichier

# Suppression de fichier
curl -X POST http://localhost:54321/api/delete \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "Images/photo.jpg",
    "npub": "npub1..."
  }'

4. Interface Web

# Accès à l'interface web
open http://localhost:54321

# Interface Geo Messaging NOSTR
open http://localhost:54321/nostr

# Interface MULTIPASS Ğ1
open http://localhost:54321/g1

🔧 Dépannage

Problèmes Courants

1. Service UPassport ne démarre pas

# Vérifier les logs
journalctl -fu upassport

# Vérifier la configuration
cat ~/.zen/UPassport/.env

# Redémarrer le service
sudo systemctl restart upassport

2. Erreur d'authentification NOSTR

# Vérifier le relay NOSTR
curl -I http://localhost:7777

# Tester l'authentification
curl -X POST http://localhost:54321/api/test-nostr \
  -F "npub=npub1..."

3. Problème d'upload IPFS

# Vérifier IPFS
ipfs swarm peers

# Vérifier l'espace disque
df -h ~/.ipfs

Logs et Debugging

# Logs UPassport
tail -f ~/.zen/tmp/54321.log

# Logs système
sudo journalctl -u upassport -f

🏗️ Architecture Technique

Composants Principaux

UPassport/
├── 54321.py              # Serveur principal FastAPI
├── upassport.sh          # Scripts de gestion /SCAN
├── templates/            # Templates HTML
├── static/              # Fichiers statiques
├── tools/               # Outils utilitaires
└── requirements.txt     # Dépendances Python

Dépendances Python

fastapi==0.104.1
uvicorn==0.24.0
aiofiles==23.2.1
pydantic==2.5.0
python-multipart==0.0.6
python-dotenv==1.0.0
cryptography==41.0.8
base58==2.1.1
aiohttp==3.9.1
Jinja2==3.1.2

Configuration Système

[Unit]
Description=UPassport API Service
After=network.target

[Service]
Type=simple
User=fred
WorkingDirectory=/home/fred/.zen/UPassport
ExecStart=/home/fred/.astro/bin/python 54321.py
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target

🔗 Intégration avec Astroport.ONE

Ports et Services

Port Service Description
54321 UPassport API API d'identité numérique
7777 NOSTR Relay Relay pour authentification
8080 IPFS Gateway Accès aux fichiers IPFS

Flux d'Intégration

graph TD
    A[Astroport.ONE] --> B[UPassport API]
    B --> C[NOSTR Relay]
    B --> D[IPFS Storage]
    B --> E[Ğ1 Blockchain]
    
    F[Interface Web] --> B
    G[Application Mobile] --> B
    H[Scripts BASH] --> B
Loading

📊 Métriques et Monitoring

Indicateurs de Performance

  • Temps de Réponse : < 500ms pour les requêtes simples
  • Throughput : 1000+ requêtes/minute
  • Disponibilité : 99.9% uptime
  • Stockage : Gestion automatique de l'espace

Monitoring

# Vérifier le statut du service
sudo systemctl status upassport

# Vérifier les métriques
curl http://localhost:54321/health

🔗 Liens et Ressources

Documentation

Ressources Externes

Support

UPassport : Votre identité numérique décentralisée et sécurisée 🛡️✨