private-landing: Instructions file for Claude Code

CLAUDE.md

This file provides context for AI assistants working with this codebase.

Project Overview

Private Landing is an educational authentication reference implementation for Cloudflare Workers. It demonstrates secure authentication patterns following NIST SP 800-63B/SP 800-132 guidelines and OWASP recommendations.

Stack: Hono, Turso (libSQL), Valkey (optional), TypeScript, Bun, Zod, Go

Architecture

This is a Bun workspace monorepo with an additional Go tool:

apps/cloudflare-workers/    # Hono app deployed to Cloudflare Workers
packages/core/              # Auth services, middleware, crypto utilities
packages/infrastructure/    # Database client, cache client, static file serving
packages/observability/     # Removable plugin: event capture, adaptive challenges, /ops API + WebSocket
packages/schemas/           # Zod validation schemas
packages/types/             # Shared TypeScript types and error classes
tools/cli/                  # plctl — Go TUI for the /ops API (not a Bun workspace)

Key Design Decisions

• JWT dual-token pattern: Short-lived access tokens (15 min) + long-lived refresh tokens (7 days)
• Session linkage: Tokens contain session IDs enabling server-side revocation
• PBKDF2-SHA384: 100,000 iterations with 128-bit salts per NIST SP 800-132
• Timing-safe comparison: Uses crypto.subtle.verify() for constant-time equality checks
• No composition rules: Password policy follows NIST guidance (length only, no complexity requirements)
• Content negotiation: Auth endpoints return JSON when Accept: application/json is sent, redirects otherwise
• Optional cache-backed sessions: CacheClient abstraction (ADR-003) enables Valkey/Redis for session storage via createCachedSessionService; SQL remains the default when no cache is configured
• Session dual-write: createMirroredSessionService decorator (ADR-007) wraps cache-backed sessions with best-effort SQL writes so operational queries against the session table stay accurate; cache remains authoritative for auth
• Password change with full revocation: POST /account/password verifies the current password, updates the hash, and revokes all sessions via endAllSessionsForUser (ADR-004)
• Semantic URL grouping: Routes organized into /health/* (public probes), /auth/* (authentication lifecycle), /account/* (account management), /ops/* (operational surface) with explicit per-route auth middleware (ADR-005)
• Rate limiting: Fixed-window counters via CacheClient (ADR-006); IP-based keying for public routes, user-based keying for authenticated routes; degrades to no-op when cache is disabled
• Observability plugin: packages/observability (ADR-008) provides structured event emission, adaptive proof-of-work challenges on login, agent credentials, and the /ops/* HTTP surface; removable by deleting the package and commenting two lines in app.ts
• WebSocket gateway: GET /ops/ws (ADR-009) provides persistent operational connections with authenticate-once upgrade, capability negotiation, heartbeat with credential re-validation, and origin blocking for browser-initiated connections
• Cloaking: /ops/* routes return 404 when AGENT_PROVISIONING_SECRET is absent, making the surface invisible in default deployments