pubky 0.12.0

Pubky SDK
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! Account-level grant management.
//!
//! [`GrantManager`] is authenticated by a [`PubkySession`], but is not tied to
//! grant-backed sessions. The homeserver decides whether the session has the
//! root capability required to list and revoke grants.

use pubky_common::auth::{grant_session_responses::GrantInfo, jws::GrantId};
use pubky_common::crypto::PublicKey;
use reqwest::Method;
use std::sync::Arc;

use crate::actors::session::credential::SessionCredential;
use crate::client::user_endpoint_url;
use crate::errors::{RequestError, Result};
use crate::util::check_http_status;
use crate::{PubkyHttpClient, PubkySession};

/// Account-level grant management for a signed-in user.
///
/// Use this to list and revoke grants (app permissions) for your account.
/// Requires a session with the **root capability**; non-root sessions get
/// `403 Forbidden` from the homeserver.
///
/// # Example
///
/// ```no_run
/// use pubky::GrantManager;
///
/// # async fn example(session: pubky::PubkySession) -> pubky::Result<()> {
/// let manager = GrantManager::new(&session);
///
/// // List all active grants
/// let grants = manager.list().await?;
/// for grant in &grants {
///     println!("grant {} from client {}", grant.grant_id, grant.client_id);
/// }
///
/// // Revoke a specific grant
/// if let Some(grant) = grants.first() {
///     manager.revoke(&grant.grant_id).await?;
/// }
/// # Ok(()) }
/// ```
#[derive(Debug, Clone)]
pub struct GrantManager {
    client: PubkyHttpClient,
    user: PublicKey,
    credential: Arc<dyn SessionCredential>,
}

impl GrantManager {
    /// Construct a grant manager authenticated by `session`.
    #[must_use]
    pub fn new(session: &PubkySession) -> Self {
        Self {
            client: session.client().clone(),
            user: session.info().public_key().clone(),
            credential: Arc::clone(session.credential()),
        }
    }

    /// List all active grants for this user.
    ///
    /// Calls `GET /auth/grant/sessions`. Requires a root-capability session;
    /// non-root sessions get `403 Forbidden` from the homeserver.
    ///
    /// # Errors
    /// - Propagates HTTP errors from the homeserver (`401`/`403` for invalid
    ///   auth or missing root capability).
    pub async fn list(&self) -> Result<Vec<GrantInfo>> {
        let url = user_endpoint_url(&self.user, "/auth/grant/sessions")?;
        let rb = self.client.cross_request(Method::GET, url).await?;
        let resp = self
            .credential
            .attach(rb, &self.client)
            .await?
            .send()
            .await?;
        let resp = check_http_status(resp).await?;
        let grants: Vec<GrantInfo> = resp.json().await.map_err(|e| RequestError::DecodeJson {
            message: format!("decoding /auth/grant/sessions response: {e}"),
        })?;
        Ok(grants)
    }

    /// Revoke a specific grant by id, killing all of its sessions.
    ///
    /// Calls `DELETE /auth/grant/session/{gid}`. Requires a root-capability
    /// session.
    ///
    /// # Errors
    /// - Propagates HTTP errors from the homeserver (`401`/`403` for invalid
    ///   auth or missing root capability).
    pub async fn revoke(&self, grant_id: &GrantId) -> Result<()> {
        let path = format!("/auth/grant/session/{}", grant_id.as_str());
        let url = user_endpoint_url(&self.user, &path)?;
        let rb = self.client.cross_request(Method::DELETE, url).await?;
        let resp = self
            .credential
            .attach(rb, &self.client)
            .await?
            .send()
            .await?;
        check_http_status(resp).await?;
        Ok(())
    }
}