Struct TokenStore 

pub struct TokenStore {
    pub apps: BTreeMap<String, App>,
    pub default_app: String,
    pub file_path: PathBuf,
}

Manages authentication tokens across multiple apps.

The in-memory shape mirrors the on-disk YAML at ~/.xurl. Library consumers construct via TokenStore::new (legacy default path), TokenStore::new_with_path (explicit path, no auto-import), or TokenStore::with_credentials (auto-backfill).

Example

use xurl::store::TokenStore;

let store = TokenStore::new_with_path("/tmp/my-xurl-store.yaml");
let active = store.get_default_app();
if let Some(app) = store.get_app(active) {
    println!("active app {active} has {} oauth2 users", app.oauth2_tokens.len());
}

Fields

apps: BTreeMap<String, App>

All registered apps, keyed by name.

default_app: String

Name of the default app selected when --app is not supplied.

file_path: PathBuf

Path to the YAML file backing this store.

Implementations

impl TokenStore

pub fn import_from_twurlrc(&mut self, file_path: &Path) -> Result<()>

Imports tokens from a .twurlrc file into the active app.

Errors

Returns an error if the file cannot be read, parsed, or the store cannot be saved.

impl TokenStore

pub fn save_bearer_token(&mut self, token: &str) -> Result<()>

Saves a bearer token into the resolved app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn save_bearer_token_for_app( &mut self, app_name: &str, token: &str, ) -> Result<()>

Saves a bearer token into the named app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn save_oauth2_token( &mut self, username: &str, access_token: &str, refresh_token: &str, expiration_time: u64, ) -> Result<()>

Saves an OAuth2 token into the resolved app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn save_oauth2_token_for_app( &mut self, app_name: &str, username: &str, access_token: &str, refresh_token: &str, expiration_time: u64, ) -> Result<()>

Saves an OAuth2 token into the named app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn save_oauth2_token_unnamed_for_app( &mut self, app_name: &str, access_token: &str, refresh_token: &str, expiration_time: u64, ) -> Result<()>

Saves an OAuth2 token into the named app’s unnamed (/me-failed salvage) slot.

Used by the refresh and exchange paths when post-token username discovery fails: the refreshed access token is still valid and is preserved here rather than discarded. Single-occupancy, last-write-wins per KTD1.

Errors

Returns an error if the store cannot be saved to disk.

pub fn save_oauth1_tokens( &mut self, access_token: &str, token_secret: &str, consumer_key: &str, consumer_secret: &str, ) -> Result<()>

Saves OAuth1 tokens into the resolved app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn save_oauth1_tokens_for_app( &mut self, app_name: &str, access_token: &str, token_secret: &str, consumer_key: &str, consumer_secret: &str, ) -> Result<()>

Saves OAuth1 tokens into the named app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn get_oauth2_token(&self, username: &str) -> Option<&Token>

Gets an OAuth2 token for a username from the resolved app.

pub fn get_oauth2_token_for_app( &self, app_name: &str, username: &str, ) -> Option<&Token>

Gets an OAuth2 token for a username from the named app.

pub fn get_first_oauth2_token(&self) -> Option<&Token>

Gets the first OAuth2 token from the resolved app.

pub fn get_first_oauth2_token_for_app(&self, app_name: &str) -> Option<&Token>

Gets the default user’s token, or the first OAuth2 token from the named app.

pub fn get_oauth2_token_unnamed_for_app(&self, app_name: &str) -> Option<&Token>

Gets the unnamed (/me-failed salvage) OAuth2 token from the named app.

Returns None when the slot is empty.

pub fn get_oauth1_tokens(&self) -> Option<&Token>

Gets OAuth1 tokens from the resolved app.

pub fn get_oauth1_tokens_for_app(&self, app_name: &str) -> Option<&Token>

Gets OAuth1 tokens from the named app.

pub fn get_bearer_token(&self) -> Option<&Token>

Gets the bearer token from the resolved app.

pub fn get_bearer_token_for_app(&self, app_name: &str) -> Option<&Token>

Gets the bearer token from the named app.

pub fn apps_with_credentials(&self) -> Vec<String>

Returns the names of every app in the store that holds at least one stored credential (OAuth2 token, OAuth1 tokens, or bearer token).

Iterates in BTreeMap key order so the result is deterministic. Used by the get_auth_header resolver to surface a “wrong-app” envelope when the active app is empty but the user has credentials stored under a different app.

pub fn clear_oauth2_token(&mut self, username: &str) -> Result<()>

Clears an OAuth2 token for a username from the resolved app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn clear_oauth2_token_for_app( &mut self, app_name: &str, username: &str, ) -> Result<()>

Clears an OAuth2 token for a username from the named app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn clear_oauth1_tokens(&mut self) -> Result<()>

Clears OAuth1 tokens from the resolved app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn clear_oauth1_tokens_for_app(&mut self, app_name: &str) -> Result<()>

Clears OAuth1 tokens from the named app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn clear_bearer_token(&mut self) -> Result<()>

Clears the bearer token from the resolved app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn clear_bearer_token_for_app(&mut self, app_name: &str) -> Result<()>

Clears the bearer token from the named app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn clear_all(&mut self) -> Result<()>

Clears all tokens from the resolved app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn clear_all_for_app(&mut self, app_name: &str) -> Result<()>

Clears all tokens from the named app.

Errors

Returns an error if the store cannot be saved to disk.

pub fn get_oauth2_usernames(&self) -> Vec<String>

Gets all OAuth2 usernames from the resolved app.

pub fn get_oauth2_usernames_for_app(&self, app_name: &str) -> Vec<String>

Gets all OAuth2 usernames from the named app.

pub fn has_oauth1_tokens(&self) -> bool

Checks if OAuth1 tokens exist in the resolved app.

pub fn has_bearer_token(&self) -> bool

Checks if a bearer token exists in the resolved app.

impl TokenStore

pub fn new() -> Self

Creates a new TokenStore, loading from ~/.xurl (auto-migrating legacy JSON).

pub fn with_credentials(client_id: &str, client_secret: &str) -> Self

Creates a TokenStore and backfills the given client credentials into any app that was migrated without them.

pub fn new_with_path(path: &str) -> Self

Creates a TokenStore from a specific file path (no auto-import).

pub fn new_with_credentials_and_path( client_id: &str, client_secret: &str, path: &str, ) -> Self

Creates a TokenStore from a specific file path with credential backfill.

pub fn new_with_home(home: &str) -> Self

Creates a TokenStore using a custom home directory (for testing).

pub fn load_from_path(path: &str) -> Self

Loads a TokenStore from a specific file path (alias for new_with_path).

pub fn add_app( &mut self, name: &str, client_id: &str, client_secret: &str, ) -> Result<()>

Registers a new application. If it’s the only app it becomes default.

Errors

Returns an error if the app name already exists or the store cannot be saved.

pub fn update_app( &mut self, name: &str, client_id: &str, client_secret: &str, ) -> Result<()>

Updates the credentials of an existing application.

Errors

Returns an error if the app is not found or the store cannot be saved.

pub fn remove_app(&mut self, name: &str) -> Result<()>

Removes a registered application and its tokens.

Errors

Returns an error if the app is not found or the store cannot be saved.

pub fn set_default_app(&mut self, name: &str) -> Result<()>

Sets the default application by name.

Errors

Returns an error if the app is not found or the store cannot be saved.

pub fn default_app_is_uninitialized(&self) -> bool

Returns true when the currently-resolved default app holds no credentials of any kind: no OAuth2 user tokens, no OAuth1 token, no bearer token, and no unnamed OAuth2 salvage token. The signal used by Self::promote_to_default_if_first_credentialed to detect the placeholder default that a fresh install starts with so the very first authenticated app can transparently take over.

pub fn promote_to_default_if_first_credentialed( &mut self, candidate_app: &str, ) -> Result<Option<String>>

Promotes candidate_app to the default app iff the current default is uninitialized (per Self::default_app_is_uninitialized) and candidate_app is registered and different from the current default. Returns the new default name when promotion happened, None otherwise.

Idempotent: callers can invoke unconditionally after any authentication save. No-op on already-credentialed defaults, on unknown candidates, on empty candidate names, and when the candidate already IS the default.

Drives the “first signed-in app becomes the default” UX so a fresh xr auth oauth2 --app NAME (or oauth1, or auth app --bearer-token --app NAME) does not leave the placeholder default ahead of NAME in the resolution chain. Users who want a different default later can still run xr auth default <name> explicitly; this helper only fires on the first authenticated save.

Errors

Returns an error if Self::set_default_app fails to persist.

pub fn list_apps(&self) -> Vec<String>

Returns sorted app names.

pub fn get_app(&self, name: &str) -> Option<&App>

Returns an app by name.

pub fn set_default_user(&mut self, app_name: &str, username: &str) -> Result<()>

Sets the default OAuth2 user for the named (or default) app.

Errors

Returns an error if the username is not found in the app or the store cannot be saved.

pub fn get_default_user(&self, app_name: &str) -> &str

Returns the default OAuth2 user for the named (or default) app.

pub fn set_app_redirect_uri(&mut self, name: &str, uri: &str) -> Result<()>

Sets the stored OAuth2 redirect URI for the named (or default) app.

An empty uri clears the stored value; the next serialize omits the field thanks to #[serde(skip_serializing_if = "String::is_empty")]. A non-empty uri is validated via crate::config::Config::validate_redirect_uri before persisting; on validation failure the store is not modified.

Errors

Returns an error if the URI fails validation or the store cannot be saved.

pub fn get_app_redirect_uri(&self, name: &str) -> Option<&str>

Returns the stored OAuth2 redirect URI for the named (or default) app.

Returns None when the app is absent or its stored URI is empty.

pub fn get_default_app(&self) -> &str

Returns the default app name.

pub fn get_active_app_name<'a>(&'a self, explicit: &'a str) -> &'a str

Returns the name of the active app (explicit or default).

pub fn resolve_app(&self, name: &str) -> &App

Returns the app for the given name, or the default app.

pub fn resolve_app_mut(&mut self, name: &str) -> &mut App

Returns the app for the given name (mutable), or the default app.

Panics

Panics if the internal app map is in an inconsistent state (should never happen as active_app_or_create always inserts a default).

Trait Implementations

impl Default for TokenStore

fn default() -> Self

Constructs a TokenStore from the default location, identical to calling TokenStore::new.