48 lines
2.3 KiB
Markdown
48 lines
2.3 KiB
Markdown
# 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.
|