HOUSECARL :: Authorization System

╔═ SYSTEM CAPABILITIES ═╗

Multi-Tenant Isolation Complete data and authorization boundary isolation per tenant with PostgreSQL schema separation

Policy-Based AuthZ JSON-based policy engine with fine-grained permissions, resource-level control, and inheritance

JWT Authentication Stateless JWT tokens with secure signing, configurable expiry, and refresh capabilities

gRPC + REST APIs High-performance gRPC backend with HTTP/REST gateway for maximum flexibility

Email Verification Resend integration with customizable templates, welcome flows, and OAuth support

OAuth SSO Google OAuth integration with extensible provider framework (GitHub, Azure AD ready)

Audit Logging Comprehensive audit trail with centralized logging service and queryable history

Billing Integration Stripe-based subscription management with usage tracking and tiered plans

╔═ TECHNICAL ARCHITECTURE ═╗

Primary Language:

Rust (1.75+) - Memory safety, zero-cost abstractions

Web Framework:

Axum (async, Tower middleware, type-safe)

RPC Protocol:

Tonic gRPC (HTTP/2, protobuf serialization)

Database:

PostgreSQL 17 (ACID, schema-per-tenant isolation)

Build System:

Bazel (hermetic builds, remote caching, monorepo)

Observability:

Jaeger (traces), Prometheus (metrics), Grafana (viz)

Containers:

OCI images, Debian 12.6-slim, Kubernetes-native

TLS/SSL:

rustls (no OpenSSL dependency, pure Rust)

╔═ TECHNOLOGY STACK ═╗

axum 0.7

tonic 0.12

sqlx 0.8

tokio (async runtime)

tower (middleware)

serde (serialization)

jsonwebtoken (JWT)

argon2 (password hash)

ureq 3.0 (HTTP client)

askama (templates)

tracing (observability)

uuid (identifiers)

╔═ API USAGE EXAMPLE ═╗

# Authenticate and get JWT token
$ curl -X POST https://api.housecarl.dev/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"***","tenant":"system"}'

# Response: {"token":"eyJhbGc...", "user_id":"...", "tenant_id":"..."}

# Check authorization
$ curl -X POST https://api.housecarl.dev/authz/can-i \
  -H "Authorization: Bearer eyJhbGc..." \
  -d '{"action":"read","resource":"tenant:acme-corp"}'

# Response: {"allowed":true,"reason":"policy:admin-access"}

# Create user with housectl CLI
$ housectl user create-user \
  --username engineer \
  --email engineer@example.com \
  --password "secure-password-here"

┌─ HOUSECARL AUTHORIZATION SYSTEM ─┐