runbeam-sdk 0.11.0

Rust SDK for integrating with the Runbeam Cloud API, providing JWT validation, API client, and generic secure token storage
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
128
129
130
131
132
133
134
135
136
137
138

//! Runbeam SDK
//!
//! A Rust library for integrating with the Runbeam Cloud API.
//!
//! This SDK provides:
//! - JWT token validation with RS256 and JWKS caching
//! - Laravel Sanctum API token support
//! - Runbeam Cloud API client for gateway authorization
//! - Secure token storage via encrypted filesystem storage (age encryption)
//! - Type definitions for API requests/responses and error handling
//!
//! # Authentication Methods
//!
//! The SDK supports two authentication methods:
//!
//! ## JWT Tokens (Legacy)
//!
//! JWT tokens with RS256 signature validation. The SDK performs local validation
//! using public keys fetched from JWKS endpoints. Use this method when you need
//! local token validation and claim extraction.
//!
//! ## Laravel Sanctum API Tokens
//!
//! Laravel Sanctum API tokens (format: `{id}|{token}`) are passed directly to the
//! server for validation. Use this method for simpler authentication flows where
//! local token validation is not required.
//!
//! # Example (JWT Authentication)
//!
//! ```no_run
//! use runbeam_sdk::{
//!     RunbeamClient,
//!     validate_jwt_token,
//!     JwtValidationOptions,
//!     save_machine_token,
//!     MachineToken,
//! };
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Validate a user JWT token with trusted issuers
//! let options = JwtValidationOptions::new()
//!     .with_trusted_issuers(vec!["https://api.runbeam.io".to_string()]);
//! let claims = validate_jwt_token("eyJhbGci...", &options).await?;
//!
//! // Create API client from JWT issuer
//! let client = RunbeamClient::new(claims.api_base_url());
//!
//! // Authorize a gateway and get machine token
//! let response = client.authorize_gateway(
//!     "eyJhbGci...",
//!     "gateway-123",
//!     None,
//!     None
//! ).await?;
//!
//! // Save machine token securely (encrypted filesystem storage)
//! let machine_token = MachineToken::new(
//!     response.machine_token,
//!     response.expires_at,
//!     response.gateway.id,
//!     response.abilities,
//! );
//! save_machine_token("harmony", &machine_token).await?;
//! # Ok(())
//! # }
//! ```
//!
//! # Example (Sanctum Authentication)
//!
//! ```no_run
//! use runbeam_sdk::{
//!     RunbeamClient,
//!     save_machine_token,
//!     MachineToken,
//! };
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Create API client with base URL
//! let client = RunbeamClient::new("https://api.runbeam.io");
//!
//! // Authorize a gateway with Sanctum token (no validation needed)
//! let response = client.authorize_gateway(
//!     "1|abc123def456...",  // Sanctum API token
//!     "gateway-123",
//!     None,
//!     None
//! ).await?;
//!
//! // Save machine token securely (encrypted filesystem storage)
//! let machine_token = MachineToken::new(
//!     response.machine_token,
//!     response.expires_at,
//!     response.gateway.id,
//!     response.abilities,
//! );
//! save_machine_token("harmony", &machine_token).await?;
//! # Ok(())
//! # }
//! ```

pub mod runbeam_api;
pub mod storage;
pub mod validation;

// Re-export commonly used types and functions
pub use validation::{
    validate_config_toml, validate_pipeline_toml, validate_toml, ValidationError,
};

pub use runbeam_api::{
    client::RunbeamClient,
    jwt::{extract_bearer_token, validate_jwt_token, JwtClaims, JwtValidationOptions},
    resources::{
        AcknowledgeChangesRequest, AcknowledgeChangesResponse, Authentication, Backend,
        BaseUrlResponse, Change, ChangeAppliedResponse, ChangeFailedRequest, ChangeFailedResponse,
        ChangeStatusResponse, Endpoint, Gateway, GatewayConfiguration, MeshTokenRequest,
        MeshTokenResponse, Middleware, Network, PaginatedResponse, PaginationLinks, PaginationMeta,
        Pipeline, Policy, PolicyRules, ResourceResponse, Service, Transform,
    },
    token_storage::{
        // Backwards-compatible machine token functions
        clear_machine_token,
        // Generic token storage functions
        clear_token,
        load_machine_token,
        load_token,
        save_machine_token,
        save_token,
        save_token_with_key,
        MachineToken,
    },
    types::{
        ApiError, AuthorizeResponse, GatewayInfo, LookupBy, ProviderConfig,
        ResolveResourceResponse, ResolutionMeta, ResolvedResource, ResourceReference,
        ResourceType, RunbeamError, StoreConfigRequest, StoreConfigResponse, TeamInfo, UserInfo,
        UserToken,
    },
};