authkestra-core 0.1.2

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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# authkestra-core

Core traits and data structures for the [authkestra](https://github.com/marcjazz/authkestra) 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.
- `AuthenticationStrategy` trait for implementing modular authentication strategies.
- `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.2"
```

### 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>;
}
```

### Authentication Strategies

The `strategy` module provides the `AuthenticationStrategy` trait, which allows for implementing modular authentication methods (e.g., Token, Session, Basic).

While `authkestra-flow` handles the high-level login flows (OAuth2, OIDC), `AuthkestraGuard` (from `authkestra-guard`) is used to protect your API routes by validating incoming requests against one or more strategies.

#### Relationship with `Authkestra`

`AuthkestraGuard` (from `authkestra-guard`) and `Authkestra` (from `authkestra-flow`) are designed to be used together but remain decoupled:

- **`Authkestra`**: Manages the **Login Flow** (e.g., redirecting to GitHub, handling the callback, creating a session).
- **`AuthkestraGuard`**: Manages **Access Control** (e.g., checking if a request has a valid session cookie or API key).

By keeping them separate, you can use `Authkestra` to log users in via OAuth2, and then use `AuthkestraGuard` to protect your API using both those sessions AND static API keys or JWTs.

#### 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

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