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

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

High Priority — Production Confidence

Medium Priority — As Product Scales

Advanced — Enterprise / High-Security

All of these are excellent reasons to reach for Better Auth instead.

Repository Structure

.
├── apps/
│   └── cloudflare-workers/    # Example Worker + Hono routes
├── packages/
│   ├── core/                  # Auth services, middleware, crypto utilities
│   ├── infrastructure/        # DB client + utilities
│   ├── observability/         # Event emission, adaptive challenges, ops API (removable plugin)
│   ├── schemas/               # Zod schemas
│   └── types/                 # Shared TypeScript types
├── tools/
│   └── cli/                   # plctl — Go TUI for the /ops surface
└── docs/
    ├── adr/                   # Architecture Decision Records
    └── audits/                # Security audits

Getting Started

git clone https://github.com/vhscom/private-landing.git
cd private-landing
bun install
bun run dev

That's it — no accounts, no API keys, no .env files. The dev server starts with a local SQLite database and generated secrets. Open http://localhost:8788 to register an account and explore the auth flows.

Have a Turso account? Drop a .dev.vars file in apps/cloudflare-workers/ (see .dev.vars.example) and bun run dev will automatically use wrangler with your remote database instead. Use bun run dev:local to force the local server regardless.

See CONTRIBUTING.md for testing and deployment instructions.

Using with AI

This repository includes a CLAUDE.md file that provides context for AI assistants. When using Claude Code, Cursor, or similar AI-powered development tools:

1. The AI will automatically read CLAUDE.md for project context
2. Architecture Decision Records in docs/adr/ explain design choices
3. Security audits in docs/audits/ document the security posture
4. Tests demonstrate expected behavior and edge cases

The codebase is designed to be AI-readable with clear module boundaries, comprehensive types, and descriptive naming.

License

Apache-2.0