MoosicBox Authentication

Basic authentication utilities for client registration and token management in the MoosicBox ecosystem.

Overview

The MoosicBox Auth package provides:

Client Registration: Register clients and manage access tokens
Magic Token Support: Create and validate magic tokens for authentication flows
Signature Token Fetching: Retrieve signature tokens for secure operations
Request Authorization: Basic request authorization middleware
Database Integration: Store and retrieve client credentials

Features

Core Authentication Functions

Client ID Generation: Generate unique client identifiers
Token Management: Store and retrieve client access tokens
Magic Token Workflow: Create and validate temporary authentication tokens
Signature Token Access: Fetch signature tokens for secure operations

Request Authorization

Non-Tunnel Authorization: Validate that requests are not from tunnel services
Header-Based Auth: Check user agent headers for authorization

Installation

Add this to your Cargo.toml:

[dependencies]
moosicbox_auth = "0.1.1"

Usage

Client Registration and Token Management

use moosicbox_auth::{get_client_id_and_access_token, AuthError};
use switchy_database::config::ConfigDatabase;

#[tokio::main]
async fn main() -> Result<(), AuthError> {
    let db = ConfigDatabase::new().await?;
    let host = "https://api.example.com";

    // Get or create client credentials
    let (client_id, access_token) = get_client_id_and_access_token(&db, host).await?;

    println!("Client ID: {}", client_id);
    println!("Access Token: {}", access_token);

    Ok(())
}

Magic Token Authentication

use moosicbox_auth::create_magic_token;
use switchy_database::config::ConfigDatabase;

async fn magic_token_example() -> Result<(), Box<dyn std::error::Error>> {
    let db = ConfigDatabase::new().await?;
    let tunnel_host = Some("https://tunnel.example.com".to_string());

    // Create a magic token for authentication flow
    let magic_token = create_magic_token(&db, tunnel_host).await?;

    println!("Magic token: {}", magic_token);

    Ok(())
}

Signature Token Retrieval

use moosicbox_auth::fetch_signature_token;

async fn get_signature_token() -> Result<(), Box<dyn std::error::Error>> {
    let host = "https://api.example.com";
    let client_id = "your-client-id";
    let access_token = "your-access-token";

    // Fetch signature token for secure operations
    match fetch_signature_token(host, client_id, access_token).await? {
        Some(signature_token) => {
            println!("Signature token: {}", signature_token);
        }
        None => {
            println!("No signature token available");
        }
    }

    Ok(())
}

Request Authorization Middleware

use moosicbox_auth::NonTunnelRequestAuthorized;
use actix_web::{web, HttpResponse, Result};

// Handler that requires non-tunnel authorization
async fn protected_handler(_auth: NonTunnelRequestAuthorized) -> Result<HttpResponse> {
    Ok(HttpResponse::Ok().json("Access granted"))
}

// The middleware automatically checks the User-Agent header
// and rejects requests from "MOOSICBOX_TUNNEL"

API Features

Database Operations

Store and retrieve client access tokens
Manage magic token lifecycle
Handle credential persistence

HTTP Integration

Actix Web request extractor for authorization
User-Agent based request filtering
Header validation and parsing

Error Handling

The package provides comprehensive error handling through the AuthError enum:

DatabaseFetch: Database operation errors
Parse: JSON parsing errors
Http: HTTP request errors
RegisterClient: Client registration failures
Unauthorized: Authorization failures

Environment Variables

TUNNEL_ACCESS_TOKEN: Required for client registration with tunnel services

Security Considerations

Magic tokens are UUIDs for temporary authentication
Client IDs are generated as UUIDs for uniqueness
Access tokens are managed securely in the database
Request filtering prevents tunnel service abuse

moosicbox_auth 0.1.4