Authenticated-session lock plan #

Goal #

Prevent someone with physical access to an already-running runner window from immediately using a site that has authenticated itself through retained cookies. This is a local-session protection feature, not a replacement for OS account security or a site’s authentication controls.

Threat model and limits #

It addresses an unattended, unlocked application window on an otherwise trusted desktop. It does not protect against an attacker who can read the user’s home directory, modify the executable, inspect the running process, or use the account after the operating-system session is unlocked. Full-disk encryption and a locked OS session remain necessary.

A lock screen also cannot make an existing WebKit renderer forget page pixels or in-memory credentials. A full-window overlay is therefore insufficient for the threat model above; a security lock must destroy authenticated web views.

Implemented privacy lock #

The toolbar's Lock action is deliberately a convenience privacy lock, not that security lock. It places an opaque, input-blocking PIN overlay over every runner window while preserving the live WebKit views beneath it. A successful PIN entry removes every overlay and returns to the exact in-memory page state. It is useful when stepping away briefly, but it does not protect against an attacker who can inspect the running process or otherwise use the unlocked OS account.

Current decisions #

• Initial unlock credential: a local six-digit PIN. Future options remain an app passphrase, OS keyring, PAM, or biometric authentication.
• Initial lock trigger: closing the last runner window. Future triggers remain an explicit action, idle timeout, focus loss, suspend, and desktop session lock.
• The implementation must require the PIN before it creates any WebView when a persistent profile exists. Closing the window already destroys the visible authenticated page; this startup gate prevents retained cookies from immediately reopening it next time.
• No host allowlist for the first version. Record this as a deferred option.
• Add session privacy choices: retain cookies (default), clear runner data on close, and eventually a private no-storage session. The isolated-profile design is in profile-isolation-plan.md.

Credential design #

The first version should use a six-digit PIN. Store only a salted, slow password-derived verifier, never the PIN itself, and compare derived values in constant time. Rate-limit failed attempts. A six-digit PIN is appropriate only as a local screen gate; it is not strong protection for a copied cookie profile.

Future options are recorded for later: Freedesktop Secret Service/keyring storage, an app passphrase derived with Argon2id, PAM, and biometric/desktop authentication. The implementation should not use a reversible encrypted cookie database: encrypting cookies independently of WebKit complicates live access and key management. OS account protection plus the app lock is the simpler boundary.

Implementation slices #

1. Profile and cleanup: retain the current explicit cookie persistence; add a tested “clear all website data” command and document data locations.
2. Session privacy control: isolate this runner's WebKit profile before offering a session-wide navigation-bar checkbox for deferred cleanup. The checkbox must not change current page data. Later add private/no-storage mode and a confirmed, standalone “forget website data now” action.
3. Manual lock: add a toolbar lock action that tears down every WebView and displays a native lock window. For a first safe iteration, require the user to re-enter the PIN after each app restart rather than silently unlocking.
4. Secret setup: first-run six-digit PIN setup, salted slow verifier, and failed-attempt rate limiting. Keep keyring, passphrase, PAM, and biometric adapters as future options.
5. Automatic lock: defer idle timer, focus-loss timer, and desktop suspend/session-lock integration, but retain them as planned triggers.
6. Hardening and tests: test that no WebView survives lock, no URL loads before PIN entry, clearing requires site re-authentication, and rate limits work. Review desktop-specific session-lock integration manually.

Decisions needed #

• Later: should the six-digit PIN be replaced or supplemented by a passphrase, OS keyring, PAM, or fingerprint unlock?
• Later: should idle timeout, focus loss, suspend, and desktop session-lock triggers be enabled?
• Later: what timeout is acceptable for the sites involved?
• Later: should private/no-storage mode be available per site, per window, or only as a session-wide choice?
• Later: should navigation be restricted to named trusted hosts?