Crate stack_auth 

stack-auth

Website | Docs | Discord

Authentication strategies for CipherStash services.

All strategies implement the AuthStrategy trait, which provides a single get_token method that returns a valid ServiceToken. Token caching and refresh are handled automatically.

Strategies

Strategy	Use case	Credentials
AutoStrategy	Recommended default — detects credentials automatically	CS_CLIENT_ACCESS_KEY + CS_WORKSPACE_CRN, or ~/.cipherstash/auth.json
AccessKeyStrategy	Service-to-service / CI	Static access key + region
OAuthStrategy	Long-lived sessions with refresh	OAuth token (from device code flow or disk)
DeviceCodeStrategy	CLI login (RFC 8628)	User authorizes in browser
StaticTokenStrategy	Tests only (test-utils feature)	Pre-obtained token used as-is

Quick start

For most applications, AutoStrategy is the simplest way to get started:

use stack_auth::AutoStrategy;

let strategy = AutoStrategy::detect()?;
// That's it — get_token() handles the rest.

For service-to-service authentication with an access key:

use stack_auth::AccessKeyStrategy;
use cts_common::Region;

let region = Region::aws("ap-southeast-2")?;
let key = "CSAKkeyId.keySecret".parse()?;
let strategy = AccessKeyStrategy::new(region, key)?;

Security

Sensitive values (SecretToken) are automatically zeroized when dropped and are masked in Debug output to prevent accidental leaks in logs.

Token refresh

All strategies that cache tokens (AccessKeyStrategy, OAuthStrategy, AutoStrategy) share the same internal refresh engine. See the AuthStrategy trait docs for a full description of the concurrency model and flow diagram.

Structs

AccessKey

A CipherStash access key.

AccessKeyStrategy

An AuthStrategy that uses a static access key to authenticate.

AccessKeyStrategyBuilder

Builder for AccessKeyStrategy.

AutoStrategyBuilder

Builder for configuring credential resolution before calling detect().

DeviceCodeStrategy

Authenticates with CipherStash using the device code flow (RFC 8628).

DeviceCodeStrategyBuilder

Builder for DeviceCodeStrategy.

DeviceIdentity

Persistent identity for a CLI installation.

OAuthStrategy

An AuthStrategy that uses OAuth refresh tokens to maintain a valid access token.

OAuthStrategyBuilder

Builder for OAuthStrategy.

PendingDeviceCode

A device code flow that is waiting for the user to authorize.

SecretToken

A sensitive token string that is zeroized on drop and hidden from debug output.

ServiceToken

A CipherStash service token returned by an AuthStrategy.

Token

An access token returned by a successful authentication flow.

Enums

AuthError

Errors that can occur during an authentication flow.

AutoStrategy

An AuthStrategy that automatically detects available credentials and delegates to the appropriate inner strategy.

InvalidAccessKey

Error returned when parsing an invalid access key string.

Traits

AuthStrategy

A strategy for obtaining access tokens.