authkestra-core 0.1.0

Core traits and types for the authkestra authentication framework
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

# authkestra-core

Core traits and data structures for the [authkestra-rs](https://github.com/marcjazz/authkestra-rs) ecosystem.

This crate provides the foundational types and traits used across the `authkestra` framework, ensuring a consistent API for authentication providers, session stores, and identity management.

## Features

- `Identity` structure for unified user information across different providers.
- `OAuthToken` structure for standard OAuth2 token responses.
- `OAuthProvider` trait for implementing OAuth2-compatible authentication providers.
- `CredentialsProvider` trait for password-based or custom credential authentication.
- `UserMapper` trait for mapping provider identities to local application users.
- `pkce` module for Proof Key for Code Exchange support.
- Standard `AuthError` enum for consistent error handling.

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
authkestra-core = "0.1.0"
```

### Core Traits

#### OAuthProvider

The `OAuthProvider` trait defines the interface for OAuth2 providers. It includes methods for generating authorization URLs and exchanging codes for identities.

```rust
#[async_trait]
pub trait OAuthProvider: Send + Sync {
    fn get_authorization_url(
        &self,
        state: &str,
        scopes: &[&str],
        code_challenge: Option<&str>,
    ) -> String;

    async fn exchange_code_for_identity(
        &self,
        code: &str,
        code_verifier: Option<&str>,
    ) -> Result<(Identity, OAuthToken), AuthError>;
    
    // Optional methods for token management
    async fn refresh_token(&self, refresh_token: &str) -> Result<OAuthToken, AuthError>;
    async fn revoke_token(&self, token: &str) -> Result<(), AuthError>;
}
```

#### CredentialsProvider

The `CredentialsProvider` trait is used for non-OAuth authentication methods, such as email/password.

```rust
#[async_trait]
pub trait CredentialsProvider: Send + Sync {
    type Credentials;

    async fn authenticate(&self, creds: Self::Credentials) -> Result<Identity, AuthError>;
}
```

#### UserMapper

The `UserMapper` trait allows you to bridge the gap between a provider's `Identity` and your application's local user model.

```rust
#[async_trait]
pub trait UserMapper: Send + Sync {
    type LocalUser: Send + Sync;

    async fn map_user(&self, identity: &Identity) -> Result<Self::LocalUser, AuthError>;
}
```

## Part of authkestra-rs

This crate is part of the [authkestra-rs](https://github.com/marcjazz/authkestra-rs) workspace. `authkestra` is a modular, framework-agnostic authentication orchestration system for Rust.