atproto-oauth-aip

Crates.ioatproto-oauth-aip
lib.rsatproto-oauth-aip
version0.11.2
created_at2025-06-18 21:26:18.325727+00
updated_at2025-08-20 18:54:47.468483+00
descriptionATProtocol AIP OAuth tools
homepagehttps://tangled.sh/@smokesignal.events/atproto-identity-rs
repositoryhttps://tangled.sh/@smokesignal.events/atproto-identity-rs
max_upload_size
id1717621
size105,843
Nick Gerakines (ngerakines)

documentation

https://docs.rs/atproto-oauth-aip

README

atproto-oauth-aip

OAuth AIP (Identity Provider) implementation for AT Protocol.

Overview

Complete OAuth 2.0 authorization code flow with PAR, PKCE, token exchange, and AT Protocol session management for identity providers.

Features

  • OAuth 2.0 authorization code flow: Complete implementation with PKCE support for secure authentication
  • Pushed Authorization Requests (PAR): Enhanced security through server-side request storage
  • Token exchange: Secure OAuth token issuance and refresh capabilities
  • AT Protocol session management: Convert OAuth tokens to AT Protocol sessions with DID resolution
  • Resource validation: OAuth protected resource and authorization server configuration validation
  • Structured error handling: Comprehensive error types following AT Protocol conventions

CLI Tools

This crate does not provide standalone CLI tools. It serves as a library for OAuth AIP implementations.

Usage

Basic OAuth Flow

use atproto_oauth_aip::{OAuthClient, oauth_init, oauth_complete, session_exchange};
use atproto_oauth::storage::MemoryStorage;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize OAuth client
    let client = OAuthClient::new(
        "https://your-app.com/client-id".to_string(),
        Some("your-client-secret".to_string()),
        "https://your-app.com/callback".to_string(),
    );
    
    // Initialize storage (use persistent storage in production)
    let storage = MemoryStorage::new();
    
    // Start OAuth flow
    let (authorization_url, state) = oauth_init(
        &client,
        "user@example.com",  // User identifier
        &storage,
    ).await?;
    
    // Redirect user to authorization_url
    println!("Please visit: {}", authorization_url);
    
    // After user authorizes and is redirected back with code and state...
    let authorization_code = "received-auth-code";
    let returned_state = "returned-state";
    
    // Complete OAuth flow
    let access_token = oauth_complete(
        &client,
        authorization_code,
        returned_state,
        &storage,
    ).await?;
    
    // Exchange for AT Protocol session
    let session = session_exchange(
        &client,
        &access_token,
        &storage,
    ).await?;
    
    println!("Authenticated as: {} ({})", session.handle, session.did);
    println!("PDS Endpoint: {}", session.pds_endpoint);
    
    Ok(())
}

Fetching OAuth Metadata

use atproto_oauth_aip::resources::{oauth_protected_resource, oauth_authorization_server};

// Get OAuth protected resource configuration
let protected_resource = oauth_protected_resource("https://bsky.social").await?;

// Get OAuth authorization server metadata
let auth_server = oauth_authorization_server(&protected_resource).await?;

API Documentation

Core Types

  • OAuthClient: OAuth client credentials and configuration
  • ATProtocolSession: Authenticated session containing DID, handle, and PDS endpoint

Main Functions

  • oauth_init(): Initiates OAuth flow using PAR
  • oauth_complete(): Exchanges authorization code for access token
  • session_exchange(): Converts OAuth access token to AT Protocol session

Resource Functions

  • oauth_protected_resource(): Fetch OAuth protected resource metadata
  • oauth_authorization_server(): Fetch OAuth authorization server metadata

Error Handling

The crate uses typed errors following the AT Protocol error format:

use atproto_oauth_aip::OAuthWorkflowError;

match result {
    Err(OAuthWorkflowError::InvalidAuthorizationRequest(e)) => {
        // Handle PAR errors
    }
    Err(OAuthWorkflowError::TokenExchangeFailed(e)) => {
        // Handle token exchange errors
    }
    // ... other error types
}

Storage Requirements

This crate requires an implementation of the OAuthStorage trait from atproto-oauth. For production use, implement persistent storage rather than using MemoryStorage.

Security Considerations

  • Always use HTTPS URLs for OAuth endpoints
  • Implement proper state validation to prevent CSRF attacks
  • Store client secrets securely
  • Use persistent storage with appropriate security measures
  • Validate DPoP keys when required by the authorization server

Dependencies

This crate depends on:

  • atproto-oauth: Core OAuth implementation
  • atproto-identity: AT Protocol identity resolution
  • atproto-record: Record handling
  • reqwest: HTTP client
  • serde: Serialization
  • tokio: Async runtime

License

MIT License

Commit count: 0

cargo fmt