# SpiceDB Integration Guide

SpiceDB provides relation-based authorization using the Google Zanzibar model.
This service handles complex permission hierarchies through relationship graphs.

## Architecture

```
+---------------------------------------------------------------------+
|                      Client Request                                 |
+---------------------------------------------------------------------+
                          |
                          V
+---------------------------------------------------------------------+
|                     Envoy Proxy (:20000)                            |
|                                                                     |
|  Routes /authzed.api.v1.* directly to SpiceDB                       |
|---------------------------------------------------------------------+
                          | SpiceDB APIs
                          V
              +---------------------+
              |  SpiceDB (:50051)   |
              |                     |
              | +-----------------+ |
              | |   Relations     | |
              | | * user:mokhax   | |
              | | * project:1     | |
              | | * maintainer    | |
              | | * developer     | |
              | +-----------------+ |
              +---------------------+
```

## Authorization Flow

```
     Client                    Envoy                   SpiceDB
        |                       |                        |
        | gRPC PermissionCheck  |                        |
        |---------------------->|                        |
        |                       | Route by gRPC service  |
        |                       |----------------------->|
        |                       |                        |
        |                       |                        | Query
        |                       |                        | relations
        |                       |                        | graph
        |                       |   Permission result    |
        |                       |<-----------------------|
        |                       |                        |
        | Permission response   |                        |
        |<----------------------|                        |
```

## Quick Start

### 1. Start All Services

```bash
# Start authzd, envoy, and spicedb
make run
```

### 2. Setup SpiceDB Schema & Data

```bash
# Initialize schema and test data
make run-spicedb-setup

# Test permissions
make run-spicedb-permission-check
```

### 3. Test SpiceDB Permissions

```bash
# Check permissions via zed CLI
zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 read user:mokhax
```

## SpiceDB Configuration

### Schema Development

1. Update schema in `etc/authzd/spice.schema`
2. Apply with `zed schema write`
3. Add relationships with `zed relationship create`

### Schema Example

```zed
definition user {}
definition project {
  relation developer: user
  relation maintainer: user
  permission read = developer + maintainer
  permission write = maintainer
}
```

### Creating Relationships

```bash
# Add user to project as maintainer
zed relationship create project:1 maintainer user:mokhax

# Add user to project as developer
zed relationship create project:1 developer user:tanuki
```

## zed CLI Commands

### Schema Management

```bash
# Write schema to SpiceDB
zed --endpoint "localhost:20000" --token "secret" --insecure schema write etc/authzd/spice.schema

# Read current schema
zed --endpoint "localhost:20000" --token "secret" --insecure schema read
```

### Relationship Management

```bash
# Create relationships
zed --endpoint "localhost:20000" --token "secret" --insecure relationship create project:1 maintainer user:mokhax

# Delete relationships
zed --endpoint "localhost:20000" --token "secret" --insecure relationship delete project:1 developer user:tanuki
```

### Permission Checks

```bash
# Check specific permissions
zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 write user:mokhax

# Bulk permission checks
zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 read user:tanuki
```

## Make Targets

- `make run-spicedb-setup` - Initialize schema and test data
- `make run-spicedb-permission-check` - Test permission queries

## References

- [SpiceDB Documentation](https://authzed.com/docs)
- [Google Zanzibar Paper](https://authzed.com/blog/what-is-google-zanzibar)
- [Cedar Policy Language](https://docs.cedarpolicy.com/)
- [Envoy External Authorization](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter)