Session-Based Authentication & Passkeys

[jamaljsr]

Objective

This project aims to implement session-based authentication with password and passkey support in lnc-web, significantly improving user experience while maintaining strong security. Users will no longer need to re-enter passwords on every page reload or browser restart within the same session, with automatic 24-hour sessions that can extend up to 7 days based on activity. The system provides device binding and origin constraints to prevent cross-device credential reuse, while remaining fully backward compatible with existing applications.

Key Benefits:

• Enhanced UX: Eliminates repetitive password prompts within active sessions
• Security: Device-bound sessions with automatic cleanup and configurable timeouts
• Backward Compatible: Zero breaking changes for existing apps
• Opt-in: Developers choose when to enable session features
• Modern Auth: Adds passkey support alongside traditional passwords

Proof of Concept

The fully functional implementation can be found in the poc-sessions-passkeys branch for reference of how each PR fits into the larger picture.

Planned PRs

• PR 1 — Prep - Normalize Indents
  Normalizes indentation to 2 spaces across the project. This is a pure whitespace change to avoid noise in future PRs.
  [SBA-01] chore: normalize indentation to 2 spaces #130

• PR 2 — Config & Cleanup
  Upgrades TypeScript, introduces a dedicated typecheck config, and cleans up lint/build config files.
  [SBA-02] update typescript and add typecheck script #131

• PR 3 — WasmManager Extraction
  Extracts WebAssembly management logic from the main LNC class into a dedicated WasmManager.
  [SBA-03] extract WASM functions from LNC into WasmManager class #132

• PR 4 — Demo App Baseline
  Introduces the passkeys-demo as a copy of connect-demo. No new features yet, just ensuring it builds.
  [SBA-04] initialize passkeys demo app #134

• PR 5 — Core Types & Repositories
  Adds core auth types, a shared encryption service abstraction, and the Password Repository implementation.
  [SBA-05] Introduce new password encryption abstractions #137

• PR 6 — Unified Credential Store
  Implements UnifiedCredentialStore and the strategy-based auth architecture (PasswordStrategy + coordination layer), and integrates them into LNC via an internal orchestrator.
  [SBA-06] Create initial UnifiedCredentialStore with password auth #138

• PR 7 — Passkey Implementation
  Adds Passkey encryption service, repository, and strategy, integrated into the existing strategy/coordination architecture.
  [SBA-08] Add Passkeys support with demo update #143

• PR 8 — Demo Passkey UI
  Updates the demo app to support Passkey pairing and login using the new auth APIs and strategy-based store.
  [SBA-08] Add Passkeys support with demo update #143

• PR 9 — Basic Session Support
  Minimal SessionManager (no complex crypto yet) and SessionStrategy, plus basic session wiring in the unified store. Updates the demo to support session-based auto-login.
  [SBA-09] Add basic Sessions support with demo update #145

• PR 10 — Origin Key Security
  Adds IndexedDB origin key management and origin-bound key wrapping to SessionManager, moving session credentials out of cleartext storage.
  [SBA-10] Add Origin Key wrapping for session credentials #149

• PR 11 — Device Binding
  Adds device fingerprinting and binding to SessionManager, completing the double-wrap (device + origin) design for stored session credentials.
  [SBA-11] Add Device Key wrapping for session credentials #150

• PR 12 — Session Refresh
  Adds activity monitoring and automatic session refresh on top of the secure, device-bound session storage.
  [SBA-12] Add Session Refresh Manager #155

• PR 13 - Scoped Logging Refactor
  Create prefixed loggers to reduce repeating the class names in the log messages (comment)
  [SBA-13] Refactor classes to use scoped loggers #159

• PR 14 — Backward Compat Refactoring
  After reviewing all of the new classes and the architecture, I've thought of an idea to eliminate some of the code smells introduced to maintain backwards compatibility. Instead of keeping the LNC class as the main entry point, we create a new enhanced class that users can migrate to in order to get Passkeys and Sessions support. This new class will not need to adhere to the existing interfaces and can be implemented clean as-if it were a new project. The old LNC class can remain for legacy users. The docs should be updated to only reference the new class.
  [SBA-14] Refactor Entrypoint for Cleaner Architecture #160

• PR 15 — README & Docs Update
  Updates public-facing documentation to describe the new unified auth model, configuration options for passwords, passkeys, and sessions, and recommended integration patterns.
  [SBA-15] Update docs for LightningNodeConnect entrypoint #162

PRs follow a linear stack where each builds on the previous, maintaining API compatibility and passing tests. Only 1-2 PRs are open at a time. After implementation, each PR is marked complete and the next begins. This approach ensures thorough review while allowing early testing of functional features like password authentication.