Merge branch 'the-spice-must-flow' into 'main'

Add SpiceDB Integration with Service-based Routing

See merge request gitlab-org/software-supply-chain-security/authorization/authzd!9

2 files changed, 277 insertions, 0 deletions

diff --git a/share/man/cedar/README.md b/share/man/cedar/README.md
new file mode 100644
index 00000000..ec665d69
--- /dev/null
+++ b/share/man/cedar/README.md
@@ -0,0 +1,125 @@
+# Cedar Authorization Guide
+
+Cedar provides policy-based authorization using Amazon's Cedar policy
+language. This service handles request authorization through Envoy's
+`ext_authz` filter.
+
+## Architecture
+
+```
++---------------------------------------------------------------------+
+|                     Client Request                                  |
++---------------------------------------------------------------------+
+                          │
+                          V
++---------------------------------------------------------------------+
+│                     Envoy Proxy (:20000)                            |
+│                                                                     |
+│  * JWT Filter extracts x-jwt-claim-sub header                       |
+│  * ext_authz sends CheckRequest to authzd                           |
++---------------------------------------------------------------------+
+                          | ext_authz
+                          V
+              +---------------------+
+              |   authzd (:50052)   |
+              |                     |
+              | +-----------------+ |
+              | | Cedar Policies  | |
+              | | * Static Assets | |
+              | | * JWT Claims    | |
+              | | * Path Rules    | |
+              | +-----------------+ |
+              +---------------------+
+```
+
+## Authorization Flow
+
+```
+     Client                    Envoy                     authzd
+        |                       |                        |
+        | HTTP Request + JWT    |                        |
+        |---------------------->|                        |
+        |                       | Extract JWT claims     |
+        |                       | Add x-jwt-claim-sub    |
+        |                       |                        |
+        |                       | ext_authz CheckRequest |
+        |                       |----------------------->|
+        |                       |                        |
+        |                       |                        | Evaluate
+        |                       |                        | Cedar
+        |                       |                        | policies
+        |                       |      Allow/Deny        |
+        |                       |<-----------------------|
+        |                       |                        |
+        | Forward request       |                        |
+        | or 403 Forbidden      |                        |
+        |<----------------------|                        |
+```
+
+## Cedar Policies
+
+### Policy Structure
+
+Policies are stored in `etc/authzd/*.cedar` files using Cedar's policy language:
+
+```cedar
+permit (
+  principal == User::"1",
+  action == Action::"GET",
+  resource == Resource::"/sparkle/"
+)
+when
+{
+  context has host &&
+  context.host == "sparkle.staging.runway.gitlab.net" &&
+  principal has username
+};
+```
+
+## JWT Integration
+
+### JWT Header Extraction
+
+Envoy's JWT filter extracts claims and adds them as headers:
+
+- `x-jwt-claim-sub` - User ID (subject)
+
+## Policy Development
+
+### Adding New Policies
+
+1. Create or edit `.cedar` files in `etc/authzd/`
+2. Use Cedar policy syntax for rules
+3. Test with `make test`
+4. Validate with `make lint`
+
+### Policy Validation
+
+```bash
+# Check policy syntax
+cedar check-parse --policies etc/authzd/policy1.cedar
+
+# Format policies
+cedar format --policies etc/authzd/policy1.cedar --check
+```
+
+### Testing Policies
+
+```bash
+# Run Cedar authorization tests
+cargo test authorization::cedar_authorizer_test
+
+# Test specific scenarios
+cargo test test_sparkle_homepage
+```
+
+## Make Targets
+
+- `make test` - Run all tests including Cedar policy tests
+- `make lint` - Validate Cedar policy syntax and formatting
+
+## References
+
+- [Cedar Policy Language](https://docs.cedarpolicy.com/)
+- [Cedar Language Guide](https://docs.cedarpolicy.com/policies/syntax.html)
+- [Envoy JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter)
diff --git a/share/man/spicedb/README.md b/share/man/spicedb/README.md
new file mode 100644
index 00000000..f5e2e968
--- /dev/null
+++ b/share/man/spicedb/README.md
@@ -0,0 +1,152 @@
+# 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)