🔒 beep-authz

A Rust authorization library with SpiceDB integration for fine-grained permissions.

Powerful, flexible authorization with Google Zanzibar-inspired permission checks

📖 Documentation | 🚀 Getting Started | 💡 Examples

✨ Features

🔐 SpiceDB Integration

• Native support for SpiceDB/AuthZed
• Fine-grained permission checks
• Relationship-based access control (ReBAC)

⚡ High Performance

• Async/await support with Tokio
• Connection pooling
• gRPC-based communication

🎯 Type-Safe Permissions

• Strongly-typed permission system
• Object-based resource modeling
• Compile-time safety

🛡️ Enterprise Ready

• Production-tested
• Comprehensive error handling
• Token-based authentication

🚀 Quick Start

Installation

Add beep-authz to your Cargo.toml:

[dependencies]
beep-authz = "0.1.0"
tokio = { version = "1.48", features = ["full"] }

Basic Usage

use authz::{SpiceDbRepository, SpiceDbConfig, SpiceDbObject, Permissions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 🔧 Configure SpiceDB connection
    let config = SpiceDbConfig {
        endpoint: "localhost:50051".to_string(),
        token: Some("your-preshared-key".to_string()),
    };

    // 🔌 Connect to SpiceDB
    let authz = SpiceDbRepository::new(config).await?;

    // 🔍 Check if user can view a channel
    let result = authz.check_permissions(
        SpiceDbObject::Channel("channel-123".to_string()),
        Permissions::ViewChannels,
        SpiceDbObject::User("user-456".to_string()),
    ).await;

    if result.has_permissions() {
        println!("✅ User has permission to view channel");
    } else {
        println!("❌ Access denied");
    }

    Ok(())
}

📋 Supported Permissions

The library includes built-in permissions for common scenarios:

• Administrator - Full access to all resources
• ManageServer - Update server settings
• ManageRoles - Create and manage roles
• CreateInvitation - Generate invite links
• ManageChannels - Full channel management
• ManageWebhooks - Webhook CRUD operations
• ViewChannels - Read channel contents
• SendMessages - Post messages
• ManageNicknames - Update user nicknames
• ChangeNickname - Update own nickname
• ManageMessages - Moderate messages
• AttachFiles - Upload files

🏗️ Architecture

┌─────────────────────────────────────────┐
│           SpiceDbRepository             │
│  ┌───────────────────────────────────┐  │
│  │   check_permissions()             │  │
│  │   check_permissions_raw()         │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
                    │
                    │ gRPC
                    ▼
┌─────────────────────────────────────────┐
│             SpiceDB Server              │
│  ┌───────────────────────────────────┐  │
│  │  Permission Engine                │  │
│  │  • Check relationships            │  │
│  │  • Evaluate permissions           │  │
│  │  • Return authorization result    │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

🔧 Configuration

Configure SpiceDB connection via environment variables or command-line arguments:

# Environment variables
export SPICEDB_ENDPOINT="grpc.authzed.com:443"
export SPICEDB_TOKEN="your-preshared-key"

# Or use command-line arguments
cargo run -- --spicedb-endpoint localhost:50051 --spicedb-token your-key

🌐 SpiceDB Setup

This library works with:

• SpiceDB - Open-source authorization system
• AuthZed - Managed SpiceDB service

📚 Learn More

• SpiceDB Documentation
• Zanzibar Paper - Google's authorization system
• Permission System Design

🧪 Testing

Run the test suite:

cargo test

📄 License

Licensed under Apache License 2.0. See LICENSE for details.