Struct StateParam

Source

pub struct StateParam { /* private fields */ }

Expand description

OAuth state parameter for CSRF protection and data preservation.

This type represents the state parameter used in OAuth authorization flows. It provides cryptographically secure nonce generation and optional data embedding.

§Thread Safety

StateParam is Send + Sync, making it safe to share across threads.

§Example

use shopify_sdk::auth::oauth::StateParam;

// Generate a simple state for CSRF protection
let state = StateParam::new();
println!("State: {}", state);
println!("Nonce: {}", state.nonce());

// Use as_ref for URL encoding
let encoded = urlencoding::encode(state.as_ref());

Implementations§

Source §

impl StateParam

Source

pub fn new() -> Self

Creates a new state parameter with a cryptographically secure random nonce.

The nonce is a 15-character alphanumeric string generated using a cryptographically secure random number generator, matching the Ruby SDK’s SecureRandom.alphanumeric(15) behavior.

§Example

use shopify_sdk::auth::oauth::StateParam;

let state = StateParam::new();
assert_eq!(state.nonce().len(), 15);
assert!(state.nonce().chars().all(|c| c.is_ascii_alphanumeric()));

Source

pub fn with_data<T: Serialize>(data: &T) -> Self

Creates a state parameter with embedded custom data.

The state is created as a base64-encoded JSON object containing both a secure random nonce and the provided data. This allows passing custom information through the OAuth flow (e.g., a return URL).

§Arguments

data - Any serializable data to embed in the state

§Example

use shopify_sdk::auth::oauth::StateParam;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct FlowContext {
    return_url: String,
    user_id: u64,
}

let context = FlowContext {
    return_url: "/dashboard".to_string(),
    user_id: 12345,
};

let state = StateParam::with_data(&context);
// State is base64-encoded, can be safely used in URLs
println!("State for OAuth: {}", state);

Source

pub fn from_raw(raw: impl Into<String>) -> Self

Creates a state parameter from a raw string.

This allows advanced users to provide their own state value. The string is used as-is without any processing or validation.

§Arguments

raw - The raw state string to use

§Example

use shopify_sdk::auth::oauth::StateParam;

let state = StateParam::from_raw("custom-state-value");
assert_eq!(state.as_ref(), "custom-state-value");

Source

pub fn nonce(&self) -> &str

Returns the raw state value.

For simple states (created with new() or from_raw()), this returns the nonce or raw value directly. For structured states (created with with_data()), this returns the full base64-encoded value.

To extract the actual nonce from a structured state, use extract_nonce().

§Example

use shopify_sdk::auth::oauth::StateParam;

// Simple state - nonce() returns the 15-char nonce
let simple = StateParam::new();
assert_eq!(simple.nonce().len(), 15);

// Structured state - nonce() returns the full encoded value
// Use extract_nonce() to get the actual nonce
let structured = StateParam::with_data(&"test");
let actual_nonce = structured.extract_nonce();
assert_eq!(actual_nonce.len(), 15);

Source

pub fn extract_data<T: DeserializeOwned>(&self) -> Option<T>

Extracts the embedded data from a structured state.

Attempts to base64-decode the state, parse it as JSON, and deserialize the data field to the specified type.

§Returns

Some(T) if the state was structured and the data could be deserialized
None if the state is not structured or deserialization fails

§Example

use shopify_sdk::auth::oauth::StateParam;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct UserData {
    name: String,
}

let data = UserData { name: "Alice".to_string() };
let state = StateParam::with_data(&data);

let extracted: Option<UserData> = state.extract_data();
assert_eq!(extracted, Some(data));

// Simple states don't have embedded data
let simple = StateParam::new();
let extracted: Option<UserData> = simple.extract_data();
assert!(extracted.is_none());

Source

pub fn extract_nonce(&self) -> String

Extracts the nonce from a potentially structured state.

For simple states, returns the full value (which is the nonce). For structured states, decodes and extracts the actual nonce.

§Returns

The 15-character nonce string, or the full value if parsing fails.

§Example

use shopify_sdk::auth::oauth::StateParam;

// Simple state
let simple = StateParam::new();
assert_eq!(simple.extract_nonce().len(), 15);

// Structured state
let structured = StateParam::with_data(&42);
assert_eq!(structured.extract_nonce().len(), 15);