Manuale Utente - DID Login

1. Introduzione

DID Login è un sistema di autenticazione basato su identità decentralizzata (DID) che permette di accedere utilizzando il tuo wallet Ethereum (MetaMask), senza bisogno di password, email o provider di identità centralizzati.

Cosa puoi fare

• Autenticarti con un click usando MetaMask (zero gas, zero transazioni on-chain)
• Ottenere un identificatore decentralizzato (DID) legato al tuo wallet
• Gestire il tuo profilo utente
• Richiedere e verificare Verifiable Credentials (credenziali verificabili W3C)

2. Concetti Chiave

2.1 Decentralized Identifier (DID)

Un DID è un identificatore unico e permanentemente assegnato al tuo wallet Ethereum. Il formato utilizzato è did:ethr:0x... secondo lo standard W3C. Nessun ente centrale lo controlla: è tuo e lo rimane finché possiedi le chiavi del wallet.

2.2 Sign-In with Ethereum (SIWE)

Il protocollo di autenticazione segue lo standard EIP-4361: Sign-In with Ethereum. Il server genera un messaggio (nonce), tu lo firmi con MetaMask (operazione gratuita, off-chain), e il server verifica la firma crittografica per confermare la tua identità.

2.3 Verifiable Credentials (VC)

Le Verifiable Credentials sono attestati digitali firmati crittograficamente secondo lo standard W3C. Possono rappresentare verifiche email, livelli KYC, membership, o qualsiasi altra attestazione. Chiunque può verificarne l'autenticità senza contattare l'emittente.

2.4 JWT (JSON Web Token)

Dopo il login, il server emette un JWT che viene salvato nella sessione del browser. Questo token viene usato per autenticare tutte le richieste API successive.

3. Prerequisiti

3.1 MetaMask

Devi avere l'estensione MetaMask installata nel tuo browser:

• Chrome / Edge / Brave: installa da metamask.io
• Firefox: installa dal componente aggiuntivo MetaMask
• Mobile: app MetaMask disponibile per iOS e Android

3.2 Wallet configurato

Assicurati di avere:

• Un wallet MetaMask con almeno un account attivo
• Accesso al browser dove è installato MetaMask

4. Connessione e Login

4.1 Prima connessione

1. Accedi a https://wallet.smartcomm.telemaco.it
2. Clicca il pulsante "Connect MetaMask"
3. MetaMask chiederà di selezionare un account e autorizzare la connessione
4. Approva la richiesta di connessione

4.2 Firma del messaggio (SIWE)

Dopo la connessione, il sistema avvia automaticamente il login:

1. Connecting — Il server genera un nonce unico e un messaggio SIWE
2. Signing — MetaMask ti chiede di firmare il messaggio (operazione gratuita)
3. Verifying — Il server verifica la firma e emette un JWT

4.3 Sessione attiva

Dopo il login, la sessione rimane attiva finché il browser è aperto (il JWT è salvato in sessionStorage). Chiudendo il browser o cliccando "Logout", la sessione viene terminata.

4.4 Cambio account o rete

• Se cambi account in MetaMask, il sistema rileva il cambio e richiede automaticamente una nuova firma
• Se cambi rete blockchain, la pagina si ricarica per aggiornare il contesto

4.5 Logout

Clicca il pulsante "Logout" in alto a destra nella dashboard. Il token JWT viene eliminato e verrai riportato alla pagina di login.

5. Profilo Utente

La sezione Profile mostra e permette di modificare le tue informazioni.

5.1 Campi del profilo

5.2 Modificare il profilo

1. Clicca "Edit Profile"
2. Compila i campi desiderati
3. Clicca "Save" per salvare o "Cancel" per annullare

6. DID - Identità Decentralizzata

La sezione DID mostra il tuo identificatore decentralizzato e il relativo DID Document.

6.1 Il tuo DID

Il DID viene generato automaticamente dal tuo indirizzo Ethereum con il formato:
did:ethr:0x1234567890abcdef1234567890abcdef12345678

6.2 DID Document

Il DID Document è un documento JSON che descrive il metodo di verifica associato al tuo DID. Contiene:

• id — Il DID stesso
• verificationMethod — Metodo crittografico (secp256k1 recovery)
• authentication — Riferimento al metodo di autenticazione
• assertionMethod — Riferimento al metodo per firmare attestati

Clicca "Show DID Document" per visualizzare il JSON completo.

7. Verifiable Credentials

La sezione Credentials permette di gestire le tue credenziali verificabili (VC).

7.1 Tipi di credenziali disponibili

7.2 Richiedere una credenziale

1. Nella sezione "Request New Credential", seleziona il tipo di credenziale
2. Inserisci i claims in formato JSON (es. {"email": "user@example.com"})
3. Clicca "Issue Credential"
4. La credenziale viene emessa firmata dal DID dell'issuer e salvata nel sistema

7.3 Verificare una credenziale

Clicca "Verify" su una credenziale per verificarne l'autenticità. Il sistema controlla la firma crittografica del JWT e mostra:

• Valid — La credenziale è autentica e firmata correttamente
• Issuer — Il DID dell'emittente
• Type — I tipi della credenziale
• Subject — Il DID del soggetto (tu)

7.4 Visualizzare il JWT

Clicca "Show JWT" per visualizzare il token JWT della Verifiable Credential. Questo token può essere condiviso con terze parti per dimostrare il possesso della credenziale.

8. Sicurezza

8.1 Autenticazione

• L'autenticazione usa firme crittografiche ECDSA (secp256k1)
• Il nonce è unico e scade dopo 5 minuti
• Il JWT ha una scadenza configurata (default: 24 ore)
• Il JWT è salvato in sessionStorage (non persiste alla chiusura del browser)

8.2 Firme off-chain

• Nessuna transazione on-chain viene effettuata
• Nessun gas viene speso
• Le firme vengono verificate localmente dal server

8.3 Privacy

• I dati del profilo sono salvati localmente sul server (file JSON)
• Le credenziali sono firmate e verificabili crittograficamente
• L'identità è legata esclusivamente al tuo wallet Ethereum

8.4 Best practices

• Non condividere il tuo JWT con terze parti
• Esegui sempre il logout quando hai finito
• Proteggi la tua seed phrase di MetaMask
• Verifica sempre il dominio prima di firmare un messaggio

9. Riferimento API

Tutti gli endpoint sono prefissati con /api.

9.1 Autenticazione

9.2 Profilo (richiede JWT)

9.3 DID

9.4 Credenziali

9.5 Esempio: flusso di login completo

// 1. Richiedi nonce
POST /api/auth/nonce
{ "address": "0x..." }
→ { "message": "wallet.smartcomm.telemaco.it wants you to sign in..." }

// 2. Firma il messaggio con MetaMask (personal_sign)

// 3. Verifica la firma
POST /api/auth/verify
{ "message": "...", "signature": "0x..." }
→ { "success": true, "token": "eyJ...", "did": "did:ethr:0x..." }

// 4. Usa il token per le richieste autenticate
GET /api/profile
Authorization: Bearer eyJ...

10. Domande Frequenti (FAQ)

11. Glossario