SSI Authentication Service

Un servizio di autenticazione basato su Self-Sovereign Identity (SSI) che utilizza Credo-TS e Hyperledger Indy per gestire credenziali digitali verificabili e emettere JWT per l'autenticazione.

📋 Panoramica del Progetto

Questo progetto implementa un servizio di autenticazione che:

• Gestisce agenti SSI tramite Credo-TS
• Emette credenziali verificabili su Hyperledger Indy
• Genera JWT per l'accesso a servizi protetti
• Gestisce connessioni DIDComm tra agenti
• Fornisce API REST per interagire con le funzionalità SSI

🏗️ Struttura del Progetto

SSIAuthService/
├── src/
│   ├── config.js                 # Configurazione dell'applicazione
│   ├── server.js                 # Entry point e configurazione Express
│   ├── credo/
│   │   └── agent.js              # Inizializzazione agente Credo-TS
│   ├── routes/
│   │   ├── authRoutes.js         # Endpoint di autenticazione
│   │   └── ssiRoutes.js          # Endpoint SSI
│   ├── services/
│   │   ├── jwtService.js         # Gestione token JWT
│   │   └── ssiService.js         # Logica SSI
│   └── store/
│       └── memoryStore.js        # Store in memoria (temporaneo)
├── .env                          # Variabili di ambiente (non committare)
├── .env.example                  # Template variabili di ambiente
├── package.json                  # Dipendenze e script
└── README.md                     # Questo file

🔧 Requisiti

• Node.js >= 18
• npm o yarn

📦 Installazione

1. Clona il repository

   git clone <repository-url>
   cd SSIAuthService

2. Installa le dipendenze

   npm install

3. Configura le variabili di ambiente

   cp .env.example .env

   Modifica il file .env con i tuoi valori specifici (vedi sezione Configuration)

⚙️ Configurazione

Variabili di Ambiente (.env)

# Express
PORT=3000                           # Porta su cui il server ascolterà

# JWT
JWT_SECRET=<your-jwt-secret>        # Secret per firmare i JWT
JWT_ISSUER=<your-did>               # DID dell'agente (issuer dei JWT)
JWT_AUDIENCE=your-service           # Audience per i JWT
JWT_EXPIRES_IN=15m                  # Scadenza dei token JWT

# CredoTS Agent
AGENT_LABEL=MyIssuerAgent           # Etichetta dell'agente
AGENT_ENDPOINT=https://<domain>     # URL pubblico dell'agente
AGENT_INBOUND_PORT=3001             # Porta per messaggi DIDComm in ingresso

# Wallet Askar
WALLET_ID=solidserver               # ID del wallet
WALLET_KEY=<your-wallet-key>        # Chiave del wallet (32 caratteri)
WALLET_DID=<your-did>               # DID associato al wallet
DID_KEY=<your-did-key>              # Chiave privata del DID (32 caratteri)

# Ledger Indy
LEDGER_URL=https://test.bcovrin.vonx.io/genesis  # URL del ledger Indy

# Credenziali
CREDENTIAL_DEFINITION_ID=<cred-def-id>  # ID della definizione di credenziale

Descrizione delle Variabili Principali

• JWT_SECRET: Generare con openssl rand -hex 32
• WALLET_KEY: Chiave di 32 caratteri (lettere e numeri)
• DID_KEY: Chiave privata associata al DID, formato hex
• CREDENTIAL_DEFINITION_ID: Ottenuto registrando una credenziale su Indy

🚀 Avvio dell'Applicazione

Modalità Sviluppo

Con hot reload tramite nodemon:

npm run dev

Modalità Produzione

npm start

Il server ascolterà sulla porta specificata in PORT (default: 3000).

📡 API Endpoints

Autenticazione (/api/auth)

Creare una connessione

POST /api/auth/connection
Response:
{
  "outOfBandUrl": "https://...",
  "outOfBandId": "uuid",
  "qrCode": "data:image/png;base64,..."
}

Verificare connessione

GET /api/auth/connection/:outOfBandId
Response:
{
  "status": "connected",
  "connectionId": "uuid"
}

SSI (/api/ssi)

Emettere una credenziale

POST /api/ssi/offer
Body:
{
  "connectionId": "uuid",
  "attributes": {
    "name": "John Doe",
    "degree": "Bachelor",
    "date": "2024-01-01"
  }
}
Response:
{
  "credentialOfferStatus": "sent",
  "recordId": "uuid"
}

Richiedere una proof

POST /api/ssi/proof-request
Body:
{
  "connectionId": "uuid",
  "attributes": ["name", "degree"]
}
Response:
{
  "proofRequestStatus": "sent",
  "recordId": "uuid"
}

🔑 Tecnologie Utilizzate

Core SSI

• Credo-TS - Framework SSI per TypeScript/JavaScript
• Hyperledger Indy - Ledger distribuito per DIDs e credenziali
• Hyperledger Askar - Wallet crittografico

API e Autenticazione

• Express.js - Framework web
• JWT - Token authentication
• QRCode - Generazione QR code per connessioni

Utilities

• dotenv - Gestione variabili di ambiente
• uuid - Generazione ID univoci
• nodemon - Auto-reload durante lo sviluppo

🛠️ Struttura del Codice

agent.js

Gestisce l'inizializzazione dell'agente Credo-TS e le operazioni SSI principali:

• Configurazione del wallet Askar
• Connessione al ledger Indy
• Importazione del DID
• Emissione di credenziali e proof

authRoutes.js

Endpoint per la gestione dell'autenticazione e delle connessioni DIDComm

ssiRoutes.js

Endpoint per operazioni SSI (emissione credenziali, richiesta proof)

jwtService.js

Servizio per la generazione e validazione di JWT

ssiService.js

Logica di business per le operazioni SSI

📝 Workflow Tipico

1. Creazione Connessione: Client richiede una connessione tramite /api/auth/connection
2. Scansione QR: Client scansiona il QR code con l'app SSI
3. Stabilimento Connessione: L'agente riceve la connessione e la conferma
4. Emissione Credenziale: Server emette una credenziale al client
5. Autenticazione: Client invia i dati della credenziale verificata per ottenere JWT

🔐 Sicurezza

• ✅ Valida tutte le credenziali tramite il ledger Indy
• ✅ Firma i JWT con chiavi crittografiche
• ✅ Utilizza wallets Askar per la gestione delle chiavi private
• ✅ Supporta connessioni DIDComm crittografate

📚 Risorse Utili

• Credo-TS Documentation
• Hyperledger Indy
• Self-Sovereign Identity
• DIDComm Specification

🐛 Troubleshooting

Errore: "Credo Agent not initialized"

Assicurati che initCredoAgent() sia chiamato durante l'avvio del server.

Errore: "Missing LEDGER_URL in env"

Verifica che tutte le variabili di ambiente siano configurate in .env.

Errore di connessione al ledger Indy

Verifica che:

• LEDGER_URL sia corretto e raggiungibile
• La connessione Internet sia attiva
• Il ledger Indy sia online

📄 Licenza

[Specifica la tua licenza qui]

👥 Contributi

Le pull request sono benvenute. Per modifiche importanti, apri prima una issue per discutere i cambiamenti proposti.