beep-authz 0.2.0

Authorization library for Beep services
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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

# 🔒 beep-authz

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

[![Crates.io](https://img.shields.io/crates/v/beep-authz.svg)](https://crates.io/crates/beep-authz)
[![Documentation](https://docs.rs/beep-authz/badge.svg)](https://docs.rs/beep-authz)
[![Rust](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/beep-industries/crates/blob/main/LICENSE)

*Powerful, flexible authorization with Google Zanzibar-inspired permission checks*

[📖 Documentation](https://docs.rs/beep-authz) | [🚀 Getting Started](#quick-start) | [💡 Examples](#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`:

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

### Basic Usage

```rust
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:

```bash
# 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](https://github.com/authzed/spicedb) - Open-source authorization system
- [AuthZed](https://authzed.com/) - Managed SpiceDB service

## 📚 Learn More

- [SpiceDB Documentation](https://authzed.com/docs)
- [Zanzibar Paper](https://research.google/pubs/pub48190/) - Google's authorization system
- [Permission System Design](https://authzed.com/blog/what-is-rebac)

## 🧪 Testing

Run the test suite:

```bash
cargo test
```

## 📄 License

Licensed under Apache License 2.0. See [LICENSE](../../LICENSE) for details.