runbeam_sdk/
lib.rs

1//! Runbeam SDK
2//!
3//! A Rust library for integrating with the Runbeam Cloud API.
4//!
5//! This SDK provides:
6//! - JWT token validation with RS256 and JWKS caching
7//! - Laravel Sanctum API token support
8//! - Runbeam Cloud API client for gateway authorization
9//! - Secure token storage via encrypted filesystem storage (age encryption)
10//! - Type definitions for API requests/responses and error handling
11//!
12//! # Authentication Methods
13//!
14//! The SDK supports two authentication methods:
15//!
16//! ## JWT Tokens (Legacy)
17//!
18//! JWT tokens with RS256 signature validation. The SDK performs local validation
19//! using public keys fetched from JWKS endpoints. Use this method when you need
20//! local token validation and claim extraction.
21//!
22//! ## Laravel Sanctum API Tokens
23//!
24//! Laravel Sanctum API tokens (format: `{id}|{token}`) are passed directly to the
25//! server for validation. Use this method for simpler authentication flows where
26//! local token validation is not required.
27//!
28//! # Example (JWT Authentication)
29//!
30//! ```no_run
31//! use runbeam_sdk::{
32//!     RunbeamClient,
33//!     validate_jwt_token,
34//!     JwtValidationOptions,
35//!     save_machine_token,
36//!     MachineToken,
37//! };
38//!
39//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
40//! // Validate a user JWT token with trusted issuers
41//! let options = JwtValidationOptions::new()
42//!     .with_trusted_issuers(vec!["https://api.runbeam.io".to_string()]);
43//! let claims = validate_jwt_token("eyJhbGci...", &options).await?;
44//!
45//! // Create API client from JWT issuer
46//! let client = RunbeamClient::new(claims.api_base_url());
47//!
48//! // Authorize a gateway and get machine token
49//! let response = client.authorize_gateway(
50//!     "eyJhbGci...",
51//!     "gateway-123",
52//!     None,
53//!     None
54//! ).await?;
55//!
56//! // Save machine token securely (encrypted filesystem storage)
57//! let machine_token = MachineToken::new(
58//!     response.machine_token,
59//!     response.expires_at,
60//!     response.gateway.id,
61//!     response.gateway.code,
62//!     response.abilities,
63//! );
64//! save_machine_token("harmony", &machine_token).await?;
65//! # Ok(())
66//! # }
67//! ```
68//!
69//! # Example (Sanctum Authentication)
70//!
71//! ```no_run
72//! use runbeam_sdk::{
73//!     RunbeamClient,
74//!     save_machine_token,
75//!     MachineToken,
76//! };
77//!
78//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
79//! // Create API client with base URL
80//! let client = RunbeamClient::new("https://api.runbeam.io");
81//!
82//! // Authorize a gateway with Sanctum token (no validation needed)
83//! let response = client.authorize_gateway(
84//!     "1|abc123def456...",  // Sanctum API token
85//!     "gateway-123",
86//!     None,
87//!     None
88//! ).await?;
89//!
90//! // Save machine token securely (encrypted filesystem storage)
91//! let machine_token = MachineToken::new(
92//!     response.machine_token,
93//!     response.expires_at,
94//!     response.gateway.id,
95//!     response.gateway.code,
96//!     response.abilities,
97//! );
98//! save_machine_token("harmony", &machine_token).await?;
99//! # Ok(())
100//! # }
101//! ```
102
103pub mod runbeam_api;
104pub mod storage;
105pub mod validation;
106
107// Re-export commonly used types and functions
108pub use validation::{
109    validate_config_toml, validate_pipeline_toml, validate_toml, ValidationError,
110};
111
112pub use runbeam_api::{
113    client::RunbeamClient,
114    jwt::{extract_bearer_token, validate_jwt_token, JwtClaims, JwtValidationOptions},
115    resources::{
116        AcknowledgeChangesRequest, AcknowledgeChangesResponse, Authentication, Backend,
117        BaseUrlResponse, Change, ChangeAppliedResponse, ChangeFailedRequest, ChangeFailedResponse,
118        ChangeStatusResponse, Endpoint, Gateway, GatewayConfiguration, MeshTokenRequest,
119        MeshTokenResponse, Middleware, Network, PaginatedResponse, PaginationLinks, PaginationMeta,
120        Pipeline, Policy, PolicyRules, ResourceResponse, Service, Transform,
121    },
122    token_storage::{
123        // Backwards-compatible machine token functions
124        clear_machine_token,
125        // Generic token storage functions
126        clear_token,
127        load_machine_token,
128        load_token,
129        save_machine_token,
130        save_token,
131        save_token_with_key,
132        MachineToken,
133    },
134    types::{
135        ApiError, AuthorizeResponse, GatewayInfo, RunbeamError, StoreConfigRequest,
136        StoreConfigResponse, TeamInfo, UserInfo, UserToken,
137    },
138};
runbeam_sdk/lib.rs

runbeam_sdk/
lib.rs
