pubky 0.11.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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

use url::Url;

use pubky_common::crypto::random_bytes;

use crate::actors::DEFAULT_HTTP_RELAY_INBOX;
#[allow(deprecated, reason = "Internal use of deprecated public API")]
use crate::actors::auth::cookie::flow::PubkyCookieAuthFlow;
use crate::actors::auth::deep_links::{
    DeepLink, DeepLinkScheme, SigninDeepLink, SigninParams, SignupDeepLink, SignupParams,
    XCallbackParams,
};
use crate::actors::auth::kind::AuthFlowKind;
use crate::actors::auth::relay::auth_relay_listener::AuthRelayListener;
use crate::errors::Result;
use crate::{Capabilities, PubkyHttpClient};

/// Builder for the **legacy (cookie)** [`PubkyCookieAuthFlow`].
///
/// The signer returns a [`pubky_common::auth::AuthToken`] which the SDK
/// exchanges for a session cookie. For long-lived, mirror-friendly
/// sessions, prefer [`crate::PubkyGrantAuthFlow`].
#[derive(Debug, Clone)]
pub struct CookieAuthFlowBuilder {
    caps: Capabilities,
    base_relay: Url,
    client: Option<PubkyHttpClient>,
    auth_kind: AuthFlowKind,
    client_secret: [u8; 32],
    x_callback: XCallbackParams,
}

impl CookieAuthFlowBuilder {
    pub(crate) fn new(caps: Capabilities, auth_kind: AuthFlowKind) -> Self {
        Self {
            caps,
            base_relay: Url::parse(DEFAULT_HTTP_RELAY_INBOX)
                .expect("Should be able to parse the default HTTP relay"),
            client: None,
            auth_kind,
            client_secret: random_bytes::<32>(),
            x_callback: XCallbackParams::default(),
        }
    }

    /// Set a custom relay base URL. Trailing slash optional.
    #[must_use]
    pub fn relay(mut self, url: Url) -> Self {
        self.base_relay = url;
        self
    }

    /// Provide a custom `PubkyHttpClient` (e.g., with custom TLS, roots, or test wiring).
    #[must_use]
    pub fn client(mut self, client: PubkyHttpClient) -> Self {
        self.client = Some(client);
        self
    }

    /// Override the random `client_secret`. By default, a fresh 32-byte secret is generated.
    #[must_use]
    pub fn client_secret(mut self, client_secret: [u8; 32]) -> Self {
        self.client_secret = client_secret;
        self
    }

    /// Attach optional x-callback-url metadata to the authorization deep link.
    #[must_use]
    pub fn x_callback(mut self, x_callback: XCallbackParams) -> Self {
        self.x_callback = x_callback;
        self
    }

    /// Finalize: derive channel, compute the `pubkyauth://` deep link, spawn
    /// the background poller, and return the flow handle.
    ///
    /// # Errors
    /// - Propagates failures from constructing the default [`PubkyHttpClient`]
    ///   or starting the [`AuthRelayListener`].
    #[allow(deprecated, reason = "Internal use of deprecated public API")]
    pub fn start(self) -> Result<PubkyCookieAuthFlow> {
        let Self {
            caps,
            base_relay,
            client,
            auth_kind,
            client_secret,
            x_callback,
        } = self;

        let client = match client {
            Some(c) => c,
            None => PubkyHttpClient::new()?,
        };

        let auth_url = match auth_kind {
            AuthFlowKind::SignIn => DeepLink::Signin(SigninDeepLink::new(
                DeepLinkScheme::PubkyAuth,
                SigninParams {
                    capabilities: caps,
                    relay: base_relay.clone(),
                    secret: client_secret,
                },
            )),
            AuthFlowKind::SignUp {
                homeserver_public_key,
                signup_token,
            } => DeepLink::Signup(SignupDeepLink::new(
                DeepLinkScheme::PubkyAuth,
                SignupParams {
                    capabilities: caps,
                    relay: base_relay.clone(),
                    secret: client_secret,
                    homeserver: *homeserver_public_key,
                    signup_token,
                },
            )),
        }
        .with_x_callback(x_callback);

        let relay_listener = AuthRelayListener::builder(client_secret)
            .relay_base_url(base_relay)
            .client(client.clone())
            .start()?;

        Ok(PubkyCookieAuthFlow::new(relay_listener, client, auth_url))
    }
}