One sign-in for the terminal client, the desktop app and the daemon: the desktop app keeps its refresh token in the TUI's credentials.json under a shared lock, starts at that plane, and links a daemon nobody has linked when it connects¶
Decision 958 · accepted · 2026-10-27 · supersedes 710, 764
- One store. The desktop shell's
secretStoreiscredentials.jsonin the Troupe config directory, in the TUI's shape and under the TUI's key for a plane (signin.rsmirrorsTroupe.Remote.Discovery.base/1),0600on unix and an owner-only ACL on Windows, as the TUI writes it (TUI Decision 71). Both clients present the sameclient_id, the plane's, so a refresh token either took is honoured for the other. A sign-in made in either client is both clients', and signing out in either forgets it for both:troupe logoutalready tells the daemon to let go of the token, and Sign out does too (766). The OS credential store is read only to move a sign-in an earlier release kept there into the file, and is cleared once it is; 710's concern, which build reads which entry, is now about that migration alone, so 710 is superseded. - Why a file and not the keychain for both. Providers rotate the refresh token on
every use and refuse the old one; a copy seeded into a second store is retired at the
first refresh from the first, so sharing means one copy, read before every refresh and
written after. The TUI is an Elixir binary on three platforms with no keychain binding
worth carrying for one entry, and has kept the token in a user-only file since 71; the
desktop app can read the same file. The sign-in screen says where the token is kept
(
capabilities().secretsisconfig-file), as it said the keychain before. - One refresh at a time, across processes. Two programs refreshing one rotating token
at the same moment would have the second refused, and a provider that detects reuse may
revoke both. So
credentials.lockbeside the file is a machine-wide mutex, created exclusively and removed after: the TUI'sCredentials.with_lock/1aroundTokens.do_refresh, which reads the file's token inside it rather than the one it loaded at start, and the desktop app'sTokenStore.lock, optional on the interface and held inside the Web LockrefreshStoredalready takes, throughsignin_lockandsignin_unlock. A lock older than a minute was left by a dead process and is broken; past fifteen seconds' wait the refresh goes ahead regardless, a sign-in that cannot be renewed being the worse outcome. A TUI whose file entry is gone (the desktop app signed out) answerslogged_outrather than spend a token the other program gave up. - Starting at the plane. Before the first render, the desktop shell seeds the
planeUrlpreference from the file'scurrentplane where the app was told none (adoptSignedInPlane), so the sign-in screen restores from the stored token without a question. A plane the app was told before is kept, and local-only is untouched. - Signing in links the daemon.
handOverlinks a daemon nobody has linked, with the token, as this person at this plane, the way the TUI already did (764): signing in is the person asking, and a daemon left unlinked is one whose private sessions and artifacts no client can reach. A daemon linked to somebody else, or to this person at another plane, is still left alone; This computer remains for undoing a link and for a daemon that could not be reached at sign-in. That part of 764's desktop-app rule is superseded; the rest of 764 stands.troupe loginlinks the daemon at once as well (TUI Decision 168), so the installer's sign-in reaches the daemon before any client opens.
Governs: clients/gui/apps/desktop/src-tauri/src/signin.rs, clients/gui/apps/desktop/src-tauri/src/secrets.rs, clients/tui/lib/troupe/remote/credentials.ex, clients/tui/lib/troupe/remote/tokens.ex