Purrfect Sitter

A cat sitting application with dual authorization strategies. This is the support project for the How to Protect Your API with OpenFGA article.

An anonymous developer surrounded by cats

Architecture

Core Application

• Fastify-based API
• User authentication with Ory Kratos
• Core models: User, Cat, CatSitting, Review
• TypeBox for JSON Schema validation
• Drizzle ORM for database access
• OpenFGA for fine-grained authorization

NX Workspace Structure

apps/
  purrfect-sitter/       # Main Fastify application
  purrfect-sitter-e2e/   # End-to-end tests

libs/                    # Domain-specific libraries
  database/              # Database schema and repositories
  models/                # DTOs and validation schemas
  auth/                  # Authentication and authorization
  cats/                  # Cats domain business logic
  cat-sittings/          # Cat sittings domain business logic
  reviews/               # Reviews domain business logic

Authorization Strategies

This application implements two authorization strategies that can be toggled via environment variables:

1. Database Lookups (AUTH_STRATEGY=db)

   • Traditional database queries to check permissions
   • Uses JOINs and WHERE clauses for relationship checks
   • Direct SQL conditions for time-based rules

2. OpenFGA (AUTH_STRATEGY=openfga)

   • Relationship-based authorization using OpenFGA
   • Declarative authorization model (authorization-model.fga)
   • Uses relationship tuples for permissions
   • Supports complex relationship checks with contextual tuples

Both strategies implement the same authorization rules, allowing for performance comparisons.

Getting Started

Prerequisites

• Node.js 18+
• Docker and Docker Compose
• Nx CLI (npm install -g nx)

Environment Setup

1. Start the required services:

docker compose --profile dev up -d

This starts:

• PostgreSQL database
• OpenFGA authorization service
• Ory Kratos identity server

2. Set environment variables:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/purrfect-sitter
KRATOS_URL=http://localhost:4433
OPENFGA_URL=http://localhost:8080
OPENFGA_STORE_ID=<store_id>
AUTH_STRATEGY=db  # or 'openfga'

3. Run database migrations:

npx nx run database:generate
npx nx run database:migrate

4. Start the development server:

npx nx run purrfect-sitter:serve

API Endpoints

The API follows RESTful principles and provides the following endpoints:

Cats

• GET /api/cats - List all cats
• GET /api/cats/:id - Get cat details
• POST /api/cats - Create cat profile (authenticated)
• PUT /api/cats/:id - Update cat profile (owner or admin)
• DELETE /api/cats/:id - Delete cat profile (owner or admin)

Cat Sittings

• GET /api/cat-sittings - List cat sittings (filtered by permissions)
• GET /api/cat-sittings/:id - Get cat sitting details (owner, sitter, or admin)
• POST /api/cat-sittings - Create cat sitting request (authenticated)
• PUT /api/cat-sittings/:id - Update cat sitting (owner, sitter, or admin)
• PUT /api/cat-sittings/:id/status - Update cat sitting status (owner or sitter)
• DELETE /api/cat-sittings/:id - Delete cat sitting (owner or admin)

Reviews

• GET /api/reviews - List reviews (public)
• GET /api/reviews/:id - Get review details (author, subject, or admin)
• POST /api/reviews - Create review (cat owner after completed sitting)
• PUT /api/reviews/:id - Update review (author only)
• DELETE /api/reviews/:id - Delete review (admin only)

Testing

Unit Testing

• Run unit tests for a specific project:

  npx nx test <project-name>

• Run tests with coverage:

  npx nx test <project-name> --coverage

E2E Testing

This project includes comprehensive end-to-end tests that validate both authorization strategies.

Test Structure

E2E tests are located in the apps/purrfect-sitter-e2e/ directory:

• src/purrfect-sitter/ - Main test suites
  • cats/ - Tests for cat management APIs
  • cat-sittings/ - Tests for cat sitting APIs
  • reviews/ - Tests for review APIs
• src/support/ - Test utilities and setup

Test Environment Setup

E2E tests use a dedicated test environment with:

• Test-specific Kratos configuration
• Dedicated PostgreSQL database
• Separate OpenFGA store

Running E2E Tests

Run E2E tests using the Makefile commands:

# Run with database strategy
make e2e-test-db

# Run with OpenFGA strategy
make e2e-test-openfga

# Run with both strategies sequentially
make e2e-test-all

Or directly with Nx:

# Set strategy via environment variable
AUTH_STRATEGY=db npx nx e2e purrfect-sitter-e2e

Performance Analysis

Authorization Benchmarking

This project includes tools for benchmarking and analyzing the performance differences between database query-based authorization and OpenFGA-based authorization.

Benchmarking Scripts

Located in tools/scripts/:

• benchmark-auth-strategies.ts - Runs identical scenarios against both authorization strategies and captures telemetry data.

  • Creates users, cats, cat sittings, and reviews
  • Executes three scenarios:
    1. Simple case: View cat (public resource)
    2. Medium case: Cat sitting management (create, update, status changes)
    3. Complex case: Review management (nested authorization checks)
  • Automatically cleans up all created resources

• trace-analyzer.ts - Analyzes OpenTelemetry trace data from Zipkin:

  • Fetches traces from Zipkin API
  • Groups traces by scenario
  • Calculates performance metrics for each scenario:
    • Total execution time
    • Total transaction time (end-to-end HTTP request duration)
    • Operation count
    • Time ratio between strategies
    • Operation count ratio
  • Aggregates metrics across iterations for better analysis
  • Generates both detailed and aggregated CSV/JSON reports

Running Benchmark Tests

1. Ensure all services are running:

   make start-dev

2. Ensure the database is running and migrations are applied:

   npx nx run database:generate
   DATABASE_URL=postgresql://dbuser:secret@localhost:5432/purrfect-sitter npx nx run database:migrate

3. Ensure the OpenFGA model is created:

   npx nx run purrfect-sitter:create-auth-model

4. Start the Purrfect Sitter application:

   AUTH_STRATEGY=openfga npx nx run purrfect-sitter:serve:local

5. Run the benchmark script:

   node --experimental-strip-types tools/scripts/benchmark-auth-strategies.ts

   This script:

   • Creates test users (cat owner, cat sitter, admin)
   • Sets up necessary data (cats, cat sittings)
   • Executes multiple iterations of each scenario with headers for tracing
   • Sends HTTP requests with X-Benchmark-Scenario headers to identify scenarios in traces

6. Analyze the results:

   node --experimental-strip-types tools/scripts/trace-analyzer.ts

   This will:

   • Fetch OpenFGA traces from Zipkin
   • Calculate metrics for individual scenario iterations
   • Aggregate metrics by scenario type across iterations
   • Generate two report types:
     • auth-comparison-[timestamp].json/.csv - Aggregated metrics with averages
     • auth-comparison-detailed-[timestamp].json/.csv - Detailed per-iteration metrics

Visualization

• View traces in Zipkin UI (http://localhost:9411)
• Examine generated CSV/JSON reports for quantitative comparison:
  • Look at the totalScenarioTime field for end-to-end transaction times
  • Compare metrics between different scenario types
  • Analyze the aggregated reports for overall performance patterns
• Use the data to create charts showing performance differences between strategies
• Run benchmarks with both AUTH_STRATEGY=db and AUTH_STRATEGY=openfga to compare approaches