cesium_oauth/lib.rs
1//! # cesium
2//!
3//! The `cesium-oauth` crate provides a simple interface for authenticating with fediverse
4//! servers using the OAuth API.
5//!
6//! For more info, see <https://docs.joinmastodon.org/spec/oauth/>
7//!
8//! In the examples below we use the <https://mastodon.art> instance. This is purely an
9//! example, almost any fediverse instance (mastodon, calckey, pixelfed, etc) should work.
10//!
11//! ## Apps
12//!
13//! In order to authenticate with a fediverse server, you first need to register an
14//! application. To do so, you can call [apps::register_new_app()]. However, you
15//! probably shouldn't register a new app for every authentication attempt. This crate
16//! provides a simple file-based implementation for caching your apps, see
17//! [apps::FileCachedAppProvider]. It will automatically register a new app if it
18//! needs one for a specific server.
19//!
20//! Basic usage:
21//! ```no_run
22//! # use cesium_oauth::apps::{AppInfo, AppProvider, FileCachedAppProvider};
23//! # async fn run() -> Result<(), cesium_oauth::Error> {
24//! let app_info = AppInfo::new("Test App", "https://example.org");
25//! let mut provider = FileCachedAppProvider::new("apps.toml", app_info)?;
26//! let registered_app = provider.get_app_for("mastodon.art").await?;
27//! # Ok(())
28//! # }
29//! ```
30//!
31//! ## Authentication
32//!
33//! Once you have an app, authentication is really simple. Let your user navigate to the
34//! url `https://[INSTANCE DOMAIN]/oauth/authorize?response_type=code&client_id=[CLIENT ID]&redirect_uri=[REDIRECT_URI]&scope=read:accounts`
35//! Replace the placeholders with the appropriate values. The client ID can be found in [apps::RegisteredApp].
36//! An example authorization URL might look like this:
37//!
38//! <https://mastodon.art/oauth/authorize?response_type=code&client_id=EMNn7o4PkKPB5aggs5aHysiY2CY24CUS3AA8sqvwy9Y&redirect_uri=https://example.org&scope=read:accounts>
39//!
40//! Once the user logs in, this will redirect them to the provided `redirect_uri` with a `code`
41//! field as a GET parameter. You will need this code for the next step:
42//! ```no_run
43//! # use cesium_oauth::apps::{AppInfo, AppProvider, FileCachedAppProvider, RegisteredApp};
44//! # use cesium_oauth::auth;
45//! # async fn get_app(app_info: &AppInfo) -> Result<RegisteredApp, cesium_oauth::Error> {
46//! # let mut provider = FileCachedAppProvider::new("apps.toml", app_info.clone())?;
47//! # provider.get_app_for("mastodon.art").await
48//! # }
49//! # async fn run() -> Result<(), cesium_oauth::Error> {
50//! # let app_info = AppInfo::new("Test App", "https://example.org");
51//! # let app = get_app(&app_info).await?;
52//! let token = auth::get_auth_token("mastodon.art", "[CODE]", &app, &app_info).await?;
53//! let account = auth::verify_credentials("mastodon.art", &token.access_token).await?;
54//! # Ok(())
55//! # }
56//! ```
57//! If this does not result in an error, the authentication was successful.
58//! The [auth::Account] struct it returns contains some basic information about the user.
59//!
60
61pub use error::Error;
62
63pub mod apps;
64pub mod auth;
65mod error;