Implement shared authentication leases

docs/authentication-leases.md

@@ -0,0 +1,47 @@
+# Authentication leases
+
+`crates/storage` owns the authentication and inactivity policy shared by every
+interactive frontend. `AuthenticationSession` owns an uncached `SecretStore`,
+and `authenticate` accepts only non-secret `KeyInfo`. A frontend therefore
+never receives or retains a GPG passphrase itself.
+
+An authenticated session returns an `AuthenticationHandle`. Every clone is
+bound to the same generation. Manual lock, cancellation, or expiry revokes the
+generation, clears its cached unlock material, locks the backing secret store,
+and makes all old handles reject later secret access. A new authentication
+creates a distinct generation, so an old editor or view cannot become valid
+again accidentally.
+
+The lease caches only a zeroizing `SecretBytes` passphrase for each protected
+key actually requested during the active generation. The underlying
+`SecretStore` cache is disabled for the session, avoiding duplicate cache
+lifetimes. Relock drops this map before returning. Git credentials remain in
+the OS-backed store and are retrieved only through a currently valid handle.
+
+## Activity and expiry
+
+The shared TOML setting is:
+
+```toml
+[security]
+inactivity_timeout_seconds = 120
+```
+
+The default is 120 seconds; valid values range from 1 second through 24 hours.
+Frontends call `touch_user_activity` only for real keyboard, pointer, touch, or
+other intentional user input. Reading a secret, polling `remaining_time` or
+`expire`, refreshing repository state, performing Git work, and repainting do
+not move the deadline. This keeps presentation adapters from inventing their
+own activity heuristics or timeout arithmetic.
+
+All access checks and relock transitions share one operation lock. At the exact
+deadline, either an operation finishes before relock or expiry wins and the
+operation observes a revoked handle; there is no check-then-use window into the
+secret store. Frontend timers may call `expire` to eagerly clean up at the
+deadline, while every handle operation also checks expiry before accessing a
+secret. The monotonic clock boundary is injectable so these cases remain fully
+deterministic in tests.
+
+OS authentication cancellation is reported distinctly. Explicit `cancel`
+also revokes an active generation, which lets an abandoned authentication UI
+clean up through the same storage-owned path as manual lock.

docs/configuration.md

@@ -29,6 +29,10 @@ editor = ["code", "--wait"]
 # Optional; upstream pass defaults to 45 seconds. Values are limited to 1..300.
 clipboard_timeout_seconds = 45
 
+# Optional; interactive frontends default to a two-minute inactivity lease.
+[security]
+inactivity_timeout_seconds = 120
+
 [[git.remotes]]
 name = "origin"
 url = "https://git.example.test/alice/password-store.git"
@@ -58,6 +62,12 @@ It defaults to 45 seconds for upstream `pass` compatibility and must be between
 selection and every platform can restore or clear the value reliably without a
 background helper process.
 
+`security.inactivity_timeout_seconds` controls the shared authentication lease
+used by interactive frontends. It defaults to 120 seconds and accepts values
+from 1 second through 24 hours. The storage crate owns deadline calculation and
+relock; frontends report only genuine input events as user activity. Repaints,
+timers, background refresh, and Git work never extend the lease.
+
 Passwords, passphrases, tokens, credentials, private keys, and other secret
 values are forbidden in TOML. Unknown fields are rejected. Parse errors never
 echo the source line or value, so an accidentally supplied secret is not