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)?;

Extensibility

stack-auth exposes two layers that can be plugged independently:

            ┌──────────────────────────────────────────────────┐
            │  AuthStrategy ─ acquisition layer                │
            │  get_token() -> ServiceToken                     │
            │  AccessKeyStrategy / OAuthStrategy / AutoStrategy│
            │  ── or ──                                        │
            │  AuthStrategyFn (closure → AuthStrategy)         │
            └────────────────────────┬─────────────────────────┘
                                     │ uses
            ┌────────────────────────▼─────────────────────────┐
            │  TokenStore ─ persistence layer                  │
            │  load() / save() of Token                        │
            │  InMemoryTokenStore / NoStore                    │
            │  ── or ──                                        │
            │  TokenStoreFn (closures → TokenStore)            │
            └──────────────────────────────────────────────────┘

Use TokenStoreFn when you want stack-auth’s own strategies to handle HTTP/refresh, but you need to plug in custom persistence (a cookie, a KV blob, Redis). Wire it via the strategy’s builder.

Use AuthStrategyFn when you want to bring your own token acquisition end-to-end — typically because the strategy lives across an FFI boundary (e.g. a JS getToken() reached via protect-ffi). The closure runs every time a token is needed.

Module paths mirror this split: stack_auth::auth groups the acquisition layer, stack_auth::store groups the persistence layer. All items are also re-exported at the crate root.

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.

Modules

auth

Token acquisition — strategies that produce a ServiceToken.

store

Token persistence — pluggable backends for the service-token cache.

Structs

AccessKey

A CipherStash access key.

AccessKeyStrategy

An AuthStrategy that uses a static access key to authenticate.

AccessKeyStrategyBuilder

Builder for AccessKeyStrategy.

AuthStrategyFn

AuthStrategy backed by a user-supplied async closure that returns a ServiceToken.

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.

InMemoryTokenStore

In-process token store. Useful for tests and as a shared cache across multiple strategy instances in the same process (e.g. a worker pool).

NoStore

Zero-sized default for AutoRefresh<R, S = NoStore> — load returns None, save is a no-op. Carries no per-instance cost.

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.

TokenStoreFn

TokenStore backed by user-supplied load and save async closures.

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.

DeviceClientError

Errors that can occur during device client provisioning.

InvalidAccessKey

Error returned when parsing an invalid access key string.

Traits

AuthStrategy

A strategy for obtaining access tokens.

TokenStore

Pluggable persistent cache for service tokens.

Functions

bind_client_device

Provision a device client after login.