Private Landing v1.6.0

🚀 Zero-Config Local Dev, WebSocket Gateway & Input Hardening

This release eliminates all onboarding friction — bun run dev now works with zero external accounts, API keys, or config files — and extends the observability plugin with a WebSocket gateway for live event streaming, HMAC-signed challenge nonces, and registration event coverage.

---

What's New

• ⚡ Zero-Config Local Development
  bun run dev starts a Bun server with auto-migrating local SQLite, generated JWT secrets, and static file serving — no Turso account, no .dev.vars, no setup. When .dev.vars is present, it automatically delegates to wrangler instead. bun run dev:local forces the local server regardless.

• 📡 WebSocket Gateway (GET /ops/ws)
  Persistent operational connections with authenticate-once upgrade, capability negotiation (query_events, query_sessions, subscribe_events, revoke_session), heartbeat with credential re-validation, and origin blocking for browser-initiated connections (ADR-009)

• 🖥️ plctl WebSocket Streaming
  Interactive TUI now supports live event streaming over WebSocket — watch security events in real time

• 🔐 HMAC-Signed Challenge Nonces
  Adaptive PoW nonces are now HMAC-signed with the JWT access secret and client IP, preventing nonce forgery and cross-IP replay

• 📊 Registration Event Emission
  registration.success and registration.failure events now captured via obsEmit middleware, matching the existing login event coverage

• 🔍 Test Files in Typecheck
  Per-package tsconfig.check.json configs include test files in bun run typecheck, catching type errors in mocks and test helpers that were previously invisible

---

Fixes

• AUTH_DB_TOKEN optional for local URLs — file: and :memory: database URLs no longer require an auth token at the type level or runtime
• serveStatic runtime guard — middleware skips gracefully when the Cloudflare ASSETS binding is absent (Bun dev server)
• plctl production safeguard — uses ENVIRONMENT binding instead of URL heuristics for production detection
• Test type errors resolved — incomplete mock interfaces, untyped .json() returns, partial ExecutionContext mocks, and missing endAllSessionsForUser on session service mocks fixed across core and observability packages

---

Changed

• Biome upgraded from 2.3.14 to 2.4.6

---

Documentation

• ADR-009: WebSocket gateway decision record — upgrade auth, capability model, heartbeat, origin policy
• WebSocket security audit: gateway-specific findings and remediations
• STRIDE threat model: WebSocket gateway attack surface added
• README, CONTRIBUTING, and CLAUDE.md updated for zero-config local dev experience
• README Why This Repo section condensed

---

Test Coverage

• 576 unit tests across 28 test suites
• New coverage: WebSocket handler, capability negotiation, heartbeat, signed nonces, registration events, local DB client paths

---

Packages (v1.6.0)

• @private-landing/core
• @private-landing/infrastructure
• @private-landing/observability
• @private-landing/schemas
• @private-landing/types
• @private-landing/cloudflare-workers

---

Intended Use

Private Landing is intended for:

• Education & learning around modern authentication systems
• Reference architecture for Cloudflare Workers
• Bootstrapping custom authentication implementations
• Security review and discussion

It is not a turnkey production authentication service.

---

Stability

v1.6.0 is fully backward compatible. The zero-config dev server is a new entry point that does not affect production deployments or wrangler-based development. The WebSocket gateway requires AGENT_PROVISIONING_SECRET to activate (same cloaking as the rest of /ops/*). HMAC-signed nonces are transparent to clients — the challenge/response protocol is unchanged. All existing tests continue to pass.

Private Landing v1.5.0

🔭 Observability Plugin & Operational Surface

This release introduces a removable observability plugin with structured security event capture, adaptive proof-of-work challenges, an agent-authenticated /ops API for incident response, and a Go TUI for exercising it — all without modifying the core authentication services.

---

What's New

• 📡 Structured Event Capture
  Security-relevant actions (login, logout, password change, rate-limit rejection, challenge escalation, agent auth failure) are persisted to a security_event table with actor attribution and fire-and-forget semantics — event emission never blocks authentication (ADR-008)

• ⚡ Adaptive Proof-of-Work Challenges
  The login endpoint escalates SHA-256 PoW difficulty after repeated failures from the same IP (3+ failures → difficulty 3, 6+ → difficulty 5). Complements rate limiting by raising per-request cost without CAPTCHA infrastructure. Fails open on DB error.

• 🤖 Agent Identity & /ops API
  Non-human agents authenticate with 256-bit API keys (SHA-256 hashed, not PBKDF2 — high-entropy keys don't need stretching). Trust levels (read/write) enforce least privilege. Provisioning is gated by a separate infrastructure secret. All /ops/* routes cloak behind 404 when the provisioning secret is absent.

• 🖥️ plctl CLI
  Go TUI (Bubble Tea) for interactive session, event, and agent management via the /ops API. Zero runtime dependency on the Node/Bun toolchain.

• 🪞 Mirrored Session Service
  createMirroredSessionService decorator ensures SQL visibility for /ops/sessions when cache is the authoritative session store — best-effort SQL mirror never blocks auth (ADR-007)

• 🔌 Fully Removable
  Delete packages/observability and comment the two [obs-plugin] lines in app.ts to restore the core auth system. CI verifies the core build and tests pass with the plugin removed.

---

Fixes

• 🔒 timingSafeEqual length leak closed (OBS-4) — both inputs padded to max length before HMAC comparison, eliminating a timing side-channel that leaked the byte-length of the compared secret
• 🔒 CLI path traversal (OBS-1) — agent name now escaped with url.PathEscape before URL concatenation
• 🔒 CLI query injection (OBS-2) — string concatenation replaced with net/url.Values for query parameters
• 🔒 SELECT * removed (OBS-3) — /ops/events uses an explicit column list to avoid auto-exposing future sensitive columns
• plctl enter key on empty events — no longer panics when pressing enter with no event selected

---

Documentation

• ADR-007: session dual-write decision record
• ADR-008: adaptive challenges, operational surface, agent identity, CLI tooling
• Security audit (Feb 28, 2026): OBS-1 through OBS-4 findings and remediations
• STRIDE threat model: observability plugin attack surface added (entries 19–27); repudiation gap (#9) marked mitigated; brute-force residual risk (#13) updated for adaptive challenges
• 90-day event pruning command documented in ADR-008
• Stale app.ts line references corrected in threat model and flow diagrams

---

Test Coverage

• 426 unit tests, 63 integration tests (489 total)
• Observability plugin: middleware, router, adaptive flow, config, schema, event processing, agent key auth
• Mirrored session service: dual-write, consistency, limit enforcement
• plctl: API client, input handling

---

Packages (v1.5.0)

• @private-landing/core
• @private-landing/infrastructure
• @private-landing/observability (new)
• @private-landing/schemas
• @private-landing/types
• @private-landing/cloudflare-workers

---

Intended Use

Private Landing is intended for:

• Education & learning around modern authentication systems
• Reference architecture for Cloudflare Workers
• Bootstrapping custom authentication implementations
• Security review and discussion

It is not a turnkey production authentication service.

---

Stability

v1.5.0 is fully backward compatible. The observability plugin ships enabled but is removable — commenting the two [obs-plugin] lines in app.ts disables it. The timingSafeEqual fix is a correctness improvement with no API surface change. All existing tests continue to pass with or without the plugin.

Private Landing v1.4.0

🛡️ Rate Limiting & Security Hardening

This release adds fixed-window rate limiting across all auth routes, closes an atomicity gap that could cause permanent key lockout, removes an unnecessary 'unsafe-eval' from the CSP, and ships a security audit covering both the rate limiting middleware and the v1.3.0 wizard UI.

---

What's New

• 🚦 Fixed-Window Rate Limiting
  createRateLimiter middleware backed by the CacheClient abstraction throttles brute-force and credential-stuffing attacks before any business logic runs (ADR-006):
  • IP-keyed on public routes: 5 req / 300 s on login and register, 20 req / 300 s on the /auth/* group
  • User ID-keyed on protected routes: 5 logouts / 300 s, 3 password changes / 3600 s
  • Returns 429 Too Many Requests with a Retry-After header on limit breach
  • Fails open on cache errors — a cache outage never blocks legitimate requests
  • Degrades to no-op when no cache is configured; enabling requires an explicit code change

---

Fixes

• 🔒 INCR+EXPIRE atomicity gap closed — if expire threw after a successful incr, the counter key persisted with no TTL, causing permanent rate-limit lockout for that identifier. The fix wraps expire in a nested try/catch and calls cache.del(key) on failure. Both failure paths are covered by unit tests.

• 🔒 'unsafe-eval' removed from CSP — script-src included 'unsafe-eval' with no code requiring it

• 🔒 Session limit enforced post-INSERT — the max-3-sessions-per-user check now runs after the new session is inserted, closing a brief window where a 4th concurrent session could exist

---

Documentation

• ADR-006: rate limiting design, algorithm choice, configuration, and future considerations
• Security audit: full review of rate limiting middleware plus stop-gap audit of the v1.3.0 wizard UI — 2 findings resolved, 1 false positive documented
• Auth flow diagrams: rate limiting rejection steps added to login and register flows
• STRIDE threat model updated: brute-force gap now marked as mitigated

---

Test Coverage

• 326 unit tests, 63 integration tests (389 total)
• New unit tests cover INCR+EXPIRE partial-failure paths: expire failure triggers del cleanup; both failing still fails open
• security-headers.test.ts updated to assert 'unsafe-eval' is absent from CSP

---

Packages (v1.4.0)

• @private-landing/core
• @private-landing/infrastructure
• @private-landing/schemas
• @private-landing/types
• @private-landing/cloudflare-workers

---

Intended Use

Private Landing is intended for:

• Education & learning around modern authentication systems
• Reference architecture for Cloudflare Workers
• Bootstrapping custom authentication implementations
• Security review and discussion

It is not a turnkey production authentication service.

---

Stability

v1.4.0 is fully backward compatible. The rate limiter is off by default (createCacheClient = null) — no behaviour changes without an explicit code change. The CSP tightening and session fix are purely additive hardening with no API surface changes.

Private Landing v1.3.0

🛤️ URL Reorganization & Wizard UI

This release restructures all routes into semantic groups, replaces implicit auth with explicit per-route middleware, and ships an interactive authentication wizard.

---

What's New

• 🗂️ Semantic Route Groups
  All routes reorganized from flat /api/* into /health, /auth/*, /account/* with explicit per-route requireAuth middleware — no more declaration-order coupling (ADR-005)

• 🧙 Tabbed Wizard UI
  Interactive four-step demo: Register, Login, Password, Logout with live API console showing requests and responses

• 🔍 Auth Status Badge
  Click-to-check authentication state against /account/me, with automatic check on page load

• 📴 No-JS Progressive Enhancement
  Native form submissions with fragment-based status banners via CSS :target — the demo works without JavaScript

---

Changes

• Health endpoint public — GET /health no longer requires authentication, following infrastructure conventions
• Simplified health — removed /health/live and /health/ready; single /health endpoint is sufficient for Workers
• /account/me — replaces /api/ping, returns { userId } for the authenticated user
• Console UX — stays visible during fetch with "waiting..." indicator; status code displayed inline with command

---

Accessibility

• <main> landmark for screen reader navigation
• <meta name="theme-color"> for dark and light modes
• prefers-reduced-motion support with suppressed noImportantStyles lint rule

---

Documentation

• ADR-005: URL reorganization decision record
• Updated route paths across ADR-001, ADR-004, flow diagrams, and CLAUDE.md

---

Test Coverage

• 315 unit tests, 63 integration tests (378 total)
• Integration tests updated for new route paths and fragment-based redirects

---

Packages (v1.3.0)

• @private-landing/core
• @private-landing/infrastructure
• @private-landing/schemas
• @private-landing/types
• @private-landing/cloudflare-workers

---

Intended Use

Private Landing is intended for:

• Education & learning around modern authentication systems
• Reference architecture for Cloudflare Workers
• Bootstrapping custom authentication implementations
• Security review and discussion

It is not a turnkey production authentication service.

---

Stability

Private Landing v1.3.0 is a breaking URL change with no migration period — the wizard UI ships with idiomatic URLs from the start. No external consumers existed on the previous /api/* paths.

Private Landing v1.2.0

🔑 Password Change Endpoint

This release adds a secure password change endpoint with full session revocation, closing a critical production gap.

---

What's New

• 🔄 Password Change Endpoint
  POST /api/account/password with current password re-verification, PBKDF2 rehash with fresh salt, and atomic revocation of all sessions (ADR-004)

• 🚪 Bulk Session Revocation
  endAllSessionsForUser on SessionService interface — works on both SQL and cache-backed implementations

• 📋 Password Change Schema
  passwordChangeSchema with cross-field refinement rejecting no-op changes (current === new)

---

Security Properties

• Timing-safe rejection — non-existent users trigger full PBKDF2 against a dummy hash to equalize
  response time
• Generic error messages — "Password change failed" for both wrong password and missing account
• Full session revocation — all sessions expired atomically, including the current one
• Current password required — session-only access cannot escalate to credential takeover (OWASP
  ASVS v5.0 §6.2.3, NIST SP 800-63B §5.1.1.2)

---

Documentation

• ADR-004: password change endpoint decision record with OWASP ASVS v5.0 and NIST SP 800-63B references
• Security audit report for password change implementation
• Updated auth flow diagrams with password change sequence
• Updated threat model with password change threats and OWASP ASVS v5.0 references
• CLAUDE.md: added password change to key design decisions, added cache enablement shortcut

---

Test Coverage

• 315 unit tests, 63 integration tests (378 total, up from 361)
• Integration tests cover: success path, session revocation, re-login with new password, wrong current password, same-password rejection, auth requirement, content negotiation

---

Packages (v1.2.0)

• @private-landing/core
• @private-landing/infrastructure
• @private-landing/schemas
• @private-landing/types
• @private-landing/cloudflare-workers

---

Intended Use

Private Landing is intended for:

• Education & learning around modern authentication systems
• Reference architecture for Cloudflare Workers
• Bootstrapping custom authentication implementations
• Security review and discussion

It is not a turnkey production authentication service.

---

Stability

Private Landing v1.2.0 adds password change as a new capability. No existing behavior has changed.
SQL-backed sessions remain the default.

Private Landing v1.1.0

🔐 Cache-Backed Sessions & Hardening

This release adds an optional cache layer for session storage, hardens authentication edge cases, and improves test reliability.

---

What's New

• ⚡ Cache-Backed Session Service
  Optional Valkey/Redis session storage via createCachedSessionService (ADR-003), with SQL remaining the default

• 🗄️ Worker Cache Bindings
  Wrangler configuration updated with cache service bindings

• 🤖 Robots Guidance
  Added robots.txt to guide crawlers on usage

---

Bug Fixes

• Password verification — use constant-time combine for digest comparison
• Schema hardening — enforce email max length and password max post-normalization
• Auth error handling — return 500 for non-auth errors instead of leaking context
• Hono JWT types — expose error types for downstream consumers
• Session expiry sync — fix expiresAt drift on sliding window renewal
• Memory cache client — correct del count logic
• Default SQL sessions — restore fallback when no cache is configured

---

Test Reliability

• Per-suite user isolation — integration suites no longer share user_id=1, eliminating session contention and removing --retry 3
• Valkey client tests — added unit tests for cache client abstraction

---

Documentation

• ADR-003: cache layer decision record (accepted), deployment/rollback plan, TCP availability clarification
• Cache layer security audit report
• Updated cross-references, contributing guide, and CLAUDE.md for cache onboarding
• Added RFC 9116 security.txt
• Added CHANGELOG.md following Keep a Changelog format

---

Packages (v1.1.0)

• @private-landing/core
• @private-landing/infrastructure
• @private-landing/schemas
• @private-landing/types
• @private-landing/cloudflare-workers

---

Intended Use

Private Landing is intended for:

• Education & learning around modern authentication systems
• Reference architecture for Cloudflare Workers
• Bootstrapping custom authentication implementations
• Security review and discussion

It is not a turnkey production authentication service.

---

Stability

Private Landing v1.1.0 extends the stable reference baseline with an optional cache layer.
SQL-backed sessions remain the default; no existing behavior has changed.

Private Landing v1.0.0

🔐 Authentication Reference Implementation for Cloudflare Workers

This release establishes Private Landing v1.0.0 as a stable authentication reference implementation for Cloudflare Workers. It demonstrates modern, security-focused authentication patterns and serves as a learning and starting point for real-world systems.

Private Landing prioritizes clarity, correctness, and documentation over completeness. The README intentionally guides readers through the remaining steps required to harden and adapt the system for production use.

---

What’s Included

• 🔐 Authentication Primitives
  NIST-aligned password handling using PBKDF2-SHA384

• 📱 Session Management Model
  Device-aware sessions, IP tracking, sliding expiration, and revocation patterns

• 🗄️ SQLite Reference Schema
  Example production-style schemas, migrations, and management tooling (Turso-compatible)

• 🚀 Edge-First Architecture
  Built for Cloudflare Workers using Hono, optimized for edge execution

• 💻 Developer Experience
  Full TypeScript coverage, automated formatting, and extensive documentation

• ⚡ Security Baselines
  CSRF protection patterns, secure cookie handling, and rate-limiting hooks

• 📦 Monorepo Structure
  Clear package boundaries with workspace dependencies

---

License & Compliance

• 100% Apache-2.0 licensed
• No GPL / AGPL dependencies
• Enterprise-safe dependency tree

---

Technical Highlights

Authentication Model

• JWT-based access tokens linked to persistent sessions
• Access tokens (15 minutes) + refresh tokens (7 days)
• HTTP-only secure cookies with CSRF protection
• Session lifecycle modeling with device and IP awareness

Security Practices

• NIST SP 800-63B–aligned password storage
• PBKDF2-SHA384 with 100,000 iterations
• Type-safe validation with runtime guarantees

Database Design

• SQLite schema optimized for Turso
• Automated migrations and backups
• Sliding session expiration examples

---

Packages (v1.0.0)

• @private-landing/core
• @private-landing/infrastructure
• @private-landing/schemas
• @private-landing/types
• @private-landing/cloudflare-workers

---

Intended Use

Private Landing is intended for:

• Education & learning around modern authentication systems
• Reference architecture for Cloudflare Workers
• Bootstrapping custom authentication implementations
• Security review and discussion

It is not a turnkey production authentication service.

---

Stability

Private Landing v1.0.x reflects a stable reference baseline.
Changes will prioritize clarity, correctness, and documentation over feature expansion.

Private Landing v1.0.0-alpha.3

This alpha release focuses on converting the template into a monorepo, separating web application from authentication system logic. It also improves on security with stricter validation of user inputs and more detailed error responses.

Core Features

Authentication System

• Add strict input validation
• Enforce login types

API Foundation

• Abstract auth database
• Expressive validation errors

Developer Experience

• Convert to monorepo
• Add dry-run deployment
• Enhance DB management
• Configurable table names

Technical Details

• Bun workspaces
• Discriminated unions
• Isolate auth database
• Errors codes

Getting Started

See the README for:

• Installation steps
• Repository structure
• Package exports
• Database setup
• Environment configuration
• Development workflow
• Contributing guidelines

Note

Increases security and portability. See ADR-001 for updated implementation details.

Private Landing v1.0.0-alpha.2

Edge-optimized authentication with complete session lifecycle.

Core Features

Authentication System

• Complete session termination with database cleanup
• Cross-domain cookie handling with security defaults
• Security header optimizations:
  • Content Security Policy (CSP)
  • Cross-Origin protections
  • Frame and resource controls

API Foundation

• Test suite with Vitest and Cloudflare Workers
• Database seeding for development
• Optimized edge performance
• Type-safe implementations

Developer Experience

• Test coverage for auth flows
• Database setup scripts
• Local environment tooling
• Streamlined project structure

Technical Details

• Database-backed session invalidation
• Domain-aware cookie configuration
• Cross-origin security defaults
• Auth flow test coverage

Getting Started

See the README for:

• Installation steps
• Database setup
• Environment configuration
• Development workflow

Note

Completes authentication lifecycle with secure logout. See ADR-001 for implementation details.

Private Landing v1.0.0-alpha.1

Initial alpha release establishing a foundation for building authenticated APIs using Cloudflare Workers, Hono, and Turso. This release implements core authentication features following NIST guidelines and security best practices.

Core Features

Authentication System

• NIST-compliant password storage using PBKDF2-SHA384
• Hybrid JWT + session-based authentication
• Secure session tracking with nanoid-generated IDs
• Automatic token refresh handling
• HTTP-only secure cookies with SameSite protection

API Foundation

• Edge-optimized with Cloudflare Workers
• Hono-based REST API framework
• Turso SQLite database integration
• TypeScript throughout

Developer Experience

• Database management scripts
• Local development environment
• Comprehensive documentation
• Type-safe implementations

Technical Details

• Access tokens: 15-minute lifetime
• Refresh tokens: 7-day lifetime
• Session management with device tracking
• Database-backed session validation
• Configurable security parameters

Getting Started

See the README for:

• Prerequisites and installation
• Database setup instructions
• Environment configuration
• Development workflow

Note

This alpha release focuses on establishing a secure authentication foundation. Some planned security enhancements (rate limiting, token rotation, advanced session management) will be rolled out in upcoming releases.

Feedback and contributions are welcome, especially regarding the authentication implementation and security features.