Autenticazione Clerk

Clerk è la piattaforma di autenticazione e gestione degli utenti che gestisce tutte le operazioni di identità in CodeCourier. Dalla registrazione alla gestione delle sessioni fino alla pulizia dell’account guidata da webhook, Clerk fornisce una soluzione di autenticazione completa che si integra perfettamente con il frontend Next.js e il backend Convex. Questa pagina illustra come CodeCourier usa Clerk, le istruzioni di configurazione e le opzioni di personalizzazione.

Cosa offre Clerk

Clerk è una piattaforma di autenticazione pensata per gli sviluppatori che offre:

• Più metodi di accesso -- Email e password, provider OAuth (Google, GitHub e altri), magic link e altro ancora.
• Componenti UI predefiniti -- Moduli di accesso e registrazione pronti all’uso che gestiscono l’intero flusso di autenticazione.
• Emissione di JWT -- JWT firmati che si integrano con servizi backend come Convex per la verifica dell’identità lato server.
• Gestione degli utenti -- Profili utente, metadati e impostazioni dell’account tramite una dashboard ospitata.
• Eventi webhook -- Notifiche per gli eventi del ciclo di vita dell’utente come la creazione e la cancellazione dell’account.
• Gestione delle sessioni -- Aggiornamento automatico delle sessioni, supporto multi-dispositivo e gestione sicura dei cookie.

Come CodeCourier usa Clerk

Flusso di autenticazione

CodeCourier usa l’SDK @clerk/nextjs (versione 6+) per integrare Clerk con l’app router di Next.js. L’integrazione include:

• Pagine di accesso e registrazione -- Situate in /sign-in e /sign-up, usano i componenti predefiniti di Clerk stilizzati per corrispondere al design system di CodeCourier.
• Protezione delle route -- Il proxy di Next.js (proxy.ts) intercetta le richieste e reindirizza gli utenti non autenticati alla pagina di accesso per le route protette.
• Integrazione Convex -- Il componente ConvexProviderWithClerk avvolge l’applicazione e passa automaticamente i token di sessione Clerk al client Convex per l’autenticazione lato server.

Sincronizzazione dei record utente

Quando un utente accede per la prima volta, CodeCourier crea un record corrispondente nella tabella Convex users. Questo record memorizza:

• clerkId -- L’ID utente di Clerk, usato per le ricerche tramite l’indice by_clerk_id.
• email -- L’indirizzo email principale dell’utente.
• name -- Il nome visualizzato dell’utente (facoltativo).
• imageUrl -- L’URL dell’avatar dell’utente dal suo profilo Clerk o dal provider OAuth.
• role -- Un ruolo facoltativo a livello di applicazione (da non confondere con i ruoli di appartenenza al progetto).

Gestione delle sessioni

Clerk gestisce automaticamente il ciclo di vita delle sessioni. Le sessioni vengono mantenute tramite cookie HTTP-only sicuri con aggiornamento automatico. L’SDK @clerk/nextjs fornisce un middleware (implementato come proxy.ts in Next.js 16) che convalida la sessione a ogni richiesta e rende l’identità dell’utente disponibile ai componenti server e alle route API.

Cancellazione dell’account

Quando un utente cancella il proprio account Clerk, l’endpoint /clerk/webhook riceve un evento user.deleted. Questo attiva la pulizia dei dati dell’utente in Convex. Il webhook usa la verifica della firma Svix per la sicurezza (vedi la pagina Webhooks per i dettagli sulla verifica).

Installazione e configurazione

Variabili d’ambiente

Per l’integrazione con Clerk sono richieste tre variabili d’ambiente:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY -- La chiave pubblica dalla tua dashboard Clerk. Usata dall’SDK frontend per le operazioni lato client.
• CLERK_SECRET_KEY -- La chiave segreta dalla tua dashboard Clerk. Usata dall’SDK lato server per la convalida delle sessioni e le chiamate API.
• CLERK_WEBHOOK_SECRET -- Il segreto di firma Svix per la verifica dei webhook. Ottenuto dalla sezione webhook della tua dashboard Clerk.

Configurazione della dashboard Clerk

1. Crea un’applicazione Clerk su clerk.com.
2. Configura i metodi di accesso che vuoi supportare (email/password, OAuth Google, OAuth GitHub, ecc.).
3. Copia la chiave pubblica e la chiave segreta nelle tue variabili d’ambiente.
4. Configura un endpoint webhook che punti all’URL di deployment del tuo Convex seguito da /clerk/webhook.
5. Sottoscrivi l’evento user.deleted (e qualsiasi altro evento che vuoi gestire).
6. Copia il segreto di firma del webhook nella tua variabile d’ambiente CLERK_WEBHOOK_SECRET.

Gestione degli utenti

Profili utente

Le informazioni del profilo utente sono gestite principalmente tramite Clerk. La pagina del profilo utente ospitata da Clerk consente agli utenti di:

• Aggiornare il nome visualizzato e l’avatar
• Modificare l’indirizzo email
• Gestire gli account OAuth collegati
• Aggiornare la password
• Abilitare o disabilitare l’autenticazione a due fattori

CodeCourier legge le informazioni del profilo da Clerk tramite il JWT di sessione e le mostra nell’intestazione della dashboard, nel componente avatar utente e negli elenchi dei membri del progetto.

Preferenze utente

Le preferenze specifiche dell’applicazione (come l’ultimo progetto attivo) vengono memorizzate nella tabella Convex userSettings, separatamente dal profilo Clerk. Questa separazione mantiene Clerk focalizzato sull’identità mentre Convex gestisce lo stato dell’applicazione.

OAuth e autenticazione social

Clerk supporta numerosi provider OAuth pronti all’uso. Per aggiungere un’opzione di accesso social:

1. Vai su User & Authentication > Social Connections nella dashboard Clerk.
2. Abilita il provider desiderato (Google, GitHub, ecc.).
3. Configura le credenziali dell’app OAuth (client ID e secret) per i deployment di produzione.

Non sono necessarie modifiche al codice in CodeCourier -- i componenti di accesso Clerk mostrano automaticamente i pulsanti per tutti i provider abilitati.

Personalizzazione

Integrazione del tema

CodeCourier personalizza i componenti di accesso e registrazione di Clerk usando il pacchetto @clerk/themes. La configurazione dell’aspetto è definita in lib/clerk-appearance.ts e garantisce che i componenti Clerk corrispondano al design system di CodeCourier, incluso il supporto per la modalità scura e una tipografia coerente.

Auth Guard

Il componente AuthGuard fornisce la protezione delle route lato client. Controlla lo stato della sessione Clerk e reindirizza gli utenti non autenticati alla pagina di accesso. Questo funziona insieme al proxy lato server per una difesa in profondità.

GDPR e privacy dei dati

CodeCourier implementa un sistema di gestione del consenso accanto all’autenticazione Clerk. Le tabelle consents e consentHistory tracciano il consenso dell’utente per il trattamento dei dati essenziali, di analytics, marketing e funzionali. Gli utenti possono inviare richieste sui dati (esportazione, cancellazione, restrizione, opposizione, rettifica) tramite il sistema dataRequests.

Quando un utente richiede la cancellazione del proprio account tramite CodeCourier, il sistema elabora la richiesta internamente e può attivare la cancellazione dell’account Clerk se necessario. Al contrario, se un utente cancella direttamente il proprio account Clerk, il webhook garantisce che CodeCourier venga notificato e possa effettuare la pulizia di conseguenza.