Module session 

CLI session file — §5.3.

The session file caches the PDS session tokens the CLI obtains at cairn login time. Each subsequent authed command asks the PDS for a fresh service auth JWT (via getServiceAuth) using the access token stored here; the CLI never mints service auth JWTs itself. §5.3 is explicit that this file is a moderator credential equivalent to the PDS app password; the on-disk invariants below are designed to catch any drift from that security posture.

On-disk invariants checked on every load:

• Mode exactly 0o600. Wider → reject.
• File owned by the current effective UID. Mismatch → reject.
• version field equals SESSION_VERSION. Mismatch → reject.

Writes are atomic: tempfile in the same directory (created with mode 0o600 via tempfile::NamedTempFile, which uses O_CREAT | O_EXCL with the target permissions set at open-time on Unix), fsync, rename(2) into place. Same-directory POSIX rename is atomic — cairn report’s auto-refresh-then-persist flow relies on this.

Structs

SessionFile

Cached PDS session + Cairn server identity. Everything needed to mint a service auth JWT at the PDS and send the result to Cairn, minus the moderator’s actual signing key (which lives at the PDS).

Enums

SessionError

Error taxonomy for session-file operations. Surfaces enough context to the CLI dispatcher to choose the right exit code (see criterion G) without leaking the session contents.

Constants

SESSION_FILE_ENV

Env-var override for the session file path. §5.3 names this as the scripted/CI escape hatch: pre-bake a session on a secure machine and point CI at it via secret management.

SESSION_VERSION

Current schema version written to disk. A load that finds a different value refuses to proceed rather than trying to migrate — a schema change warrants an explicit cairn login re-auth.

Functions

default_path

Resolve the session path: CAIRN_SESSION_FILE env var first, otherwise <config_dir>/cairn/session.json per XDG.

delete

Idempotent removal of the session file. Ok(()) regardless of whether the file existed — cairn logout treats “already gone” as success.