vhscom/private-landing🔐 Impara l'autenticazione costruendola correttamente. Un'implementazione di riferimento estensibile e conforme agli standard per Cloudflare Workers con Hono, Turso, PBKDF2 e sessioni a doppio token JWT.
Impara l'autenticazione costruendola correttamente.
Demo Live · Modello delle Minacce · Flussi di Autenticazione · ADR
Nota sulla demo: L'endpoint di login è protetto da sfide PoW adattive — tentativi falliti ripetuti aumentano la difficoltà della proof-of-work. Il rate limiting basato su cache è implementato e testato ma attualmente non attivo sulla demo live; attiva
createCacheClientinapp.tsper abilitarlo.
Un'implementazione di autenticazione di riferimento realizzata da zero per Cloudflare Workers — hashing delle password con PBKDF2, sessioni dual-token JWT, confronto a tempo costante, scadenza scorrevole e un plugin di osservabilità rimovibile — tutto collegato con Hono, Turso (con caching opzionale su Valkey/Redis) e TypeScript rigoroso.
Ogni scelta progettuale si basa su uno standard: NIST SP 800-63B per le credenziali, NIST SP 800-132 per la derivazione delle chiavi, OWASP ASVS per la verifica e RFC 8725 per le buone pratiche JWT.
Stai sviluppando un prodotto? Usa Better Auth — copre OAuth, passkey, MFA, rate limiting e altro ancora, già pronto all'uso con un ecosistema di plugin attivo. Questo repository esiste per insegnarti come funziona l'autenticazione, non per sostituire una libreria di produzione.
| Livello | Cosa fa |
|---|---|
| Archiviazione password | PBKDF2-SHA384 con salt a 128 bit, digest di integrità, tracciamento versione (password-service.ts) |
| Gestione sessioni | Sessioni lato server con tracciamento dispositivo, scadenza scorrevole, enforcement massimo 3 per utente; sessioni opzionali con cache Valkey/Redis (session-service.ts, cached-session-service.ts) |
| Cambio password | Riverifica della password corrente, rehash completo PBKDF2, revoca atomica di tutte le sessioni (account-service.ts, ADR-004) |
| Pattern dual-token JWT | Token di accesso da 15 min + token di refresh da 7 giorni, collegati alla sessione per la revoca (token-service.ts) |
| Middleware autenticazione | Flusso di refresh automatico, pinning esplicito HS256, validazione claim typ (require-auth.ts) |
| Cookie sicuri | HttpOnly, Secure, SameSite=Strict, Path=/ (cookie.ts) |
| Intestazioni di sicurezza | HSTS, CSP, CORP/COEP/COOP, Permissions-Policy, rimozione impronta digitale (security.ts) |
| Validazione input | Schemi Zod con criterio password conforme a NIST (solo lunghezza, nessuna regola di complessità) |
| Rate limiting | Throttling a finestra fissa contro attacchi brute-force e credential stuffing: IP-chiave sulle route pubbliche di autenticazione (es. login), utente-chiave sulle azioni protette; nessun blocco definitivo (allineato a NIST) (ADR-006) |
| Plugin osservabilità | Eventi di sicurezza strutturati, sfide PoW adattive, API /ops autenticata tramite agente — si inserisce tramite middleware, rimovibile eliminando un pacchetto (ADR-008) |
| Strumenti CLI | Interfaccia TUI in Go (plctl) per interrogare eventi, gestire sessioni e fornire credenziali agente tramite la superficie /ops (tools/cli/) |
| Test vettori d'attacco | Manomissione JWT, confusione algoritmo, confusione tipo, casi limite Unicode, controlli di divulgazione informazioni |
Questo progetto omette intenzionalmente funzionalità al di fuori del suo scopo didattico. Se stai estendendo questo codice verso la produzione (o valutando cosa richiede un sistema di autenticazione in produzione), le tabelle seguenti organizzano le lacune per priorità.
Per la maggior parte dei progetti reali, usa Better Auth invece di costruire tutto da te.
| Funzionalità | Perché è importante | Standard / Riferimento |
|---|---|---|
| Controllo password violate | Impedisce l'uso di password note in dump pubblici | NIST SP 800-63B §5.1.1.2, API HIBP |
| Funzionalità | Perché è importante | Standard / Riferimento |
|---|---|---|
| Protezione CSRF (se SameSite rilassato) | SameSite=Strict previene attualmente CSRF; se cambiato in Lax per UX, è necessario un token esplicito | OWASP CSRF Cheat Sheet |
| Rotazione token di refresh | Rileva furto di token — se un token di refresh ruotato viene riutilizzato, revoca l'intera famiglia di sessioni | RFC 6819 §5.2.2.3 |
Claim aud nei JWT | Impedisce che un token di un servizio venga accettato da un altro che condivide lo stesso segreto | RFC 7519 §4.1.3, RFC 8725 §3.9 |
| Nonce CSP per script inline | L'attuale CSP usa 'unsafe-inline'; i nonce eliminano i vettori XSS da script inline | MDN CSP script-src |
| Funzionalità | Perché è importante | Standard / Riferimento |
|---|---|---|
| Autenticazione multi-fattore TOTP | Aggiunge un secondo fattore per account di alto valore | RFC 6238, NIST SP 800-63B §5.1.4 |
| WebAuthn / passkey | Autenticazione resistente al phishing con autenticatori di piattaforma | WebAuthn Level 2 |
| OAuth / login social | Riduce l'attrito, evita l'affaticamento delle password | RFC 6749 |
| Magic link / OTP | Opzione senza password per flussi a basso rischio | NIST SP 800-63B §5.1.3 |
| Analisi sessioni | Tracciamento dispositivo, visibilità sessioni concorrenti, rilevamento anomalie | OWASP Session Management Cheat Sheet |
| Rotazione chiave di firma | Consente rotazione periodica del segreto senza invalidare tutte le sessioni | RFC 7517 (JWK) |
| Funzionalità | Perché è importante | Standard / Riferimento |
|---|---|---|
| DPoP / binding token | Lega i token alla connessione TLS del client, impedendo il replay in caso di esfiltrazione | RFC 9449 (DPoP) |
| Multi-tenancy | Isola pool di utenti, segreti e policy per tenant | Specifico dell'applicazione |
| Geo-fencing / reputazione IP | Blocca login da regioni inaspettate o IP noti come malevoli | OWASP ASVS v5.0 §6.3.5 |
| Autenticazione adattiva | Aumenta i requisiti di autenticazione in base a segnali di rischio (dispositivo, posizione, comportamento) | NIST SP 800-63B §6 |
| Aggiornamento iterazioni PBKDF2 o Argon2id | OWASP raccomanda 210.000 iterazioni PBKDF2-SHA512 (Cloudflare limita a 100k); Argon2id è memory-hard | OWASP Password Storage Cheat Sheet |
Tutte queste sono ottime ragioni per affidarsi a Better Auth.
.
├── apps/
│ └── cloudflare-workers/ # Esempio Worker + route Hono
├── packages/
│ ├── core/ # Servizi di autenticazione, middleware, utilità crittografiche
│ ├── infrastructure/ # Client DB + utilità
│ ├── observability/ # Emissione eventi, sfide adattive, API ops (plugin rimovibile)
│ ├── schemas/ # Schemi Zod
│ └── types/ # Tipi TypeScript condivisi
├── tools/
│ └── cli/ # plctl — interfaccia TUI Go per la superficie /ops
└── docs/
├── adr/ # Documenti di Decisione Architetturale
└── audits/ # Audit di sicurezza
git clone https://github.com/vhscom/private-landing.git
cd private-landing
bun install
bun run dev
Tutto qui — nessun account, nessuna chiave API, nessun file .env. Il server di sviluppo parte con un database SQLite locale e segreti generati. Apri http://localhost:8788 per registrare un account ed esplorare i flussi di autenticazione.
Hai un account Turso? Inserisci un file
.dev.varsinapps/cloudflare-workers/(vedi.dev.vars.example) ebun run devutilizzerà automaticamente wrangler con il tuo database remoto. Usabun run dev:localper forzare il server locale indipendentemente.
Vedi CONTRIBUTING.md per istruzioni su test e distribuzione.
Questo repository include un file CLAUDE.md che fornisce contesto per assistenti IA. Quando utilizzi Claude Code, Cursor o strumenti di sviluppo basati su IA simili:
CLAUDE.md per il contesto del progettodocs/adr/ spiegano le scelte progettualidocs/audits/ documentano la postura di sicurezzaIl codebase è progettato per essere leggibile dall'IA, con confini di modulo chiari, tipi completi e nomi descrittivi.