Demo note: The login endpoint is protected by adaptive PoW challenges — repeated failures return increasing proof-of-work difficulty. Cache-backed rate limiting is implemented and tested but not currently enabled on the live demo; flip createCacheClient in app.ts to activate it.

---

A from-scratch authentication reference implementation for Cloudflare Workers — PBKDF2 password hashing, JWT dual-token sessions, constant-time comparison, sliding expiration, and a removable observability plugin — all wired together with Hono, Turso (with optional Valkey/Redis caching), and strict TypeScript.

Every design choice traces back to a standard: NIST SP 800-63B for credentials, NIST SP 800-132 for key derivation, OWASP ASVS for verification, and RFC 8725 for JWT best practices.

Shipping a product? Use Better Auth instead — it covers OAuth, passkeys, MFA, rate limiting, and more out of the box with an active plugin ecosystem. This repo exists to teach you how auth works, not to replace a production library.

Why this repo

• Read the code, not just the docs — every security property (timing-safe rejection, session-linked revocation, algorithm pinning) is implemented and tested, not just described
• NIST + OWASP + RFC references throughout — learn the why behind each decision
• 630+ tests including attack-vector suites (token tampering, algorithm confusion, unicode edge cases)
• Observability plugin — structured audit logging, adaptive PoW challenges, agent-authenticated ops API, and WebSocket event streaming — bolts on via Hono middleware without modifying core auth
• Built for the edge — runs on Cloudflare Workers with Web Crypto API, no Node.js dependencies
• Apache-2.0 — fork it, teach with it, learn from it

What You'll Find Inside

Layer	What it does
Password storage	PBKDF2-SHA384 with 128-bit salts, integrity digest, version tracking (password-service.ts)
Session management	Server-side sessions with device tracking, sliding expiration, max-3-per-user enforcement; optional cache-backed sessions via Valkey/Redis (session-service.ts, cached-session-service.ts)
Password change	Current-password re-verification, full PBKDF2 rehash, atomic revocation of all sessions (account-service.ts, ADR-004)
JWT dual-token pattern	15-min access + 7-day refresh tokens, session-linked for revocation (token-service.ts)
Auth middleware	Automatic refresh flow, explicit HS256 pinning, typ claim validation (require-auth.ts)
Secure cookies	HttpOnly, Secure, SameSite=Strict, Path=/ (cookie.ts)
Security headers	HSTS, CSP, CORP/COEP/COOP, Permissions-Policy, fingerprint removal (security.ts)
Input validation	Zod schemas with NIST-compliant password policy (length only, no complexity rules)
Rate limiting	Fixed-window throttling against brute-force and credential-stuffing attacks: IP-keyed on public auth routes (e.g. login), user-keyed on protected actions; no hard lockouts (NIST-aligned) (ADR-006)
Observability plugin	Structured security events, adaptive PoW challenges, agent-authenticated /ops API — plugs in via middleware, removable by deleting one package (ADR-008)
CLI tooling	Go TUI (plctl) for querying events, managing sessions, and provisioning agent credentials via the /ops surface (tools/cli/)
Attack-vector tests	JWT tampering, algorithm confusion, type confusion, unicode edge cases, info-disclosure checks

Production Next Steps

This project intentionally omits features that are outside its educational scope. If you're extending this code toward production (or evaluating what a production auth system requires), the tables below organize the gaps by priority tier.

For most real-world projects, use Better Auth instead of building these yourself.

Critical — Add Before Real Users

Feature	Why It Matters	Standard / Reference
Breached-password checking	Prevents use of passwords known to be in public breach dumps	NIST SP 800-63B §5.1.1.2, HIBP API

High Priority — Production Confidence