Module auth_session 

Single atomic entry point for installing a fresh sign-in onto disk.

Replaces the historical pattern where each caller (CLI run_login, desktop sign_in, desktop handle_deeplink) wrote credentials in three independent steps:

1. auth::write_credentials — token + user_id + device_id + bump
2. credstore::write_encryption_key — generated lazily, sometimes after the version bump fired
3. credstore::write_device_privkey — generated lazily as well

The lazy generation race meant the desktop FS watcher could fire on the version bump from step 1 and adopt credentials before steps 2-3 had produced the AES + X25519 material. install_credentials collapses all three writes into a single transaction with exactly one credential_version bump at the end.

AES + X25519 are generated up-front (eager) and reused if the user already has them on this machine.

Structs

InstallOutcome

Outcome of install_credentials — useful for callers that want to surface “this is the first sign-in on this machine” or report which credstore backend was used.

InstallParams

Inputs for an atomic credential install. Everything the relay returned for a fresh device-code or pair handshake.

Enums

RequireKeyError

Error returned when the E2EE key is not available for a user.

Functions

install_credentials

Install credentials atomically: writes the AES user key + X25519 device key first, then updates ~/.cinch/config.json with token / user_id / device_id / hostname / machine_id and bumps credential_version exactly once at the end.

require_encryption_key

E2EE precondition. Returns the user’s AES-256 key or a clear error. Callers map Missing to the ENCRYPTION_REQUIRED exit code.