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