Testing

Overview

This guide documents how to test the Kong gateway integration with auth-server and rxdb-server.

Prerequisites

• Docker and Docker Compose installed
• .env file in project root (can be empty for local dev)
• JWT keys in .jwt-dev-keys/ directory (auto-generated if missing)

Quick Start

# From docker directory
cd docker
docker compose -f docker-compose.local.yml up -d --build
docker compose -f docker-compose.local.yml logs -f

Or use the helper script from project root:

./scripts/local-env.sh start
./scripts/local-env.sh logs -f
./scripts/local-env.sh stop

Service Access Points

Test Endpoints

Health Checks

# Kong health
curl http://localhost:7001/status

# Auth server via Kong
curl http://localhost:7080/auth/send-code \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'

# Well-known OAuth endpoint
curl http://localhost:7080/.well-known/oauth-authorization-server | jq

# Direct auth server health
curl http://localhost:7004/health

# Direct RxDB server health
curl http://localhost:7002/health

# MCP server health
curl http://localhost:7101/health

OAuth 2.0 + PKCE Flow Test

Step 1: Generate PKCE Code Verifier and Challenge

# Generate random code verifier (43-128 characters, base64url-encoded)
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d "=+/" | cut -c1-43)
echo "Code Verifier: $CODE_VERIFIER"

# Generate code challenge (SHA256 hash of verifier, base64url-encoded)
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | base64 | tr -d "=+/" | tr "/+" "_-")
echo "Code Challenge: $CODE_CHALLENGE"

Step 2: Request Verification Code

# Send verification code to email
curl http://localhost:7080/auth/send-code \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "domainId": "test-domain"
  }'

In development, the verification code is logged to the auth-server container logs:

docker compose -f docker-compose.local.yml logs auth-server | grep "code:"

Step 3: Authorize and Get Authorization Code

# Open in browser to see the UI (optional)
open "http://localhost:7080/auth/authorize?client_id=claude-code&redirect_uri=http://localhost:3000/callback&response_type=code&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256&state=random123"

# Or use curl to programmatically submit (after getting verification code)
VERIFICATION_CODE="123456"  # Replace with code from logs
curl http://localhost:7080/auth/authorize \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=claude-code" \
  -d "redirect_uri=http://localhost:3000/callback" \
  -d "response_type=code" \
  -d "code_challenge=$CODE_CHALLENGE" \
  -d "code_challenge_method=S256" \
  -d "state=random123" \
  -d "email=test@example.com" \
  -d "code=$VERIFICATION_CODE" \
  -d "domain_id=test-domain" \
  -i

This will redirect to the redirect_uri with the authorization code. Extract the code from the Location header.

Step 4: Exchange Authorization Code for Tokens

AUTHORIZATION_CODE="code_xxxxxxxxx"  # Replace with code from redirect

curl http://localhost:7080/auth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$AUTHORIZATION_CODE" \
  -d "client_id=claude-code" \
  -d "redirect_uri=http://localhost:3000/callback" \
  -d "code_verifier=$CODE_VERIFIER" \
  | jq

Expected response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_xxxxxxxxx",
  "scope": "read write"
}

Step 5: Use Access Token

ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."  # From previous step

# Get current user info
curl http://localhost:7080/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq

Step 6: Refresh Token

REFRESH_TOKEN="rt_xxxxxxxxx"  # From token response

curl http://localhost:7080/auth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=claude-code" \
  | jq

Kong Admin API Tests

# List all services
curl http://localhost:7001/services | jq

# List all routes
curl http://localhost:7001/routes | jq

# Get specific service
curl http://localhost:7001/services/auth-service | jq

# Check Kong configuration
curl http://localhost:7001/config | jq

RxDB Server Tests (via Kong)

# After getting an access token from OAuth flow

# Test sync endpoint
curl http://localhost:7080/sync/example-collection \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checkpoint": null,
    "limit": 100
  }' | jq

# Test API endpoint
curl http://localhost:7080/api/example-collection \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq

Supported OAuth Clients

The auth server supports the following OAuth clients:

Troubleshooting

Service Won't Start

# Check service logs
docker compose -f docker-compose.local.yml logs <service-name>

# Check service health
docker compose -f docker-compose.local.yml ps

# Rebuild from scratch
docker compose -f docker-compose.local.yml down -v
docker compose -f docker-compose.local.yml build --no-cache
docker compose -f docker-compose.local.yml up -d

Kong Configuration Errors

# Validate Kong configuration
docker compose -f docker-compose.local.yml run --rm kong kong config parse /kong/kong.yml

# Check Kong error logs
docker compose -f docker-compose.local.yml logs kong

Auth Issues

# Check JWT keys are mounted correctly
docker compose -f docker-compose.local.yml exec auth-server ls -la /app/jwt-keys

# View auth server logs with verification codes
docker compose -f docker-compose.local.yml logs -f auth-server

Network Issues

# Inspect the network
docker network inspect flowstate-network-local

# Check if services can reach each other
docker compose -f docker-compose.local.yml exec kong ping -c 2 auth-server
docker compose -f docker-compose.local.yml exec kong ping -c 2 rxdb-server

Integration Test Checklist

Before merging the Kong gateway changes, verify:

• [ ] All services start without errors
• [ ] Kong health check passes
• [ ] Auth server health check passes (direct and via Kong)
• [ ] RxDB server health check passes (direct and via Kong)
• [ ] Well-known OAuth endpoint returns correct metadata
• [ ] PKCE authorization flow completes successfully
• [ ] Access token works for protected endpoints
• [ ] Refresh token can obtain new access tokens
• [ ] Kong Admin API is accessible
• [ ] All service routes are properly configured in Kong
• [ ] CORS headers are present on responses
• [ ] Services can communicate via Docker network
• [ ] JWT keys are properly mounted and accessible

Performance Testing

Load Testing with Apache Bench

# Test auth endpoint
ab -n 1000 -c 10 -p post-data.json -T application/json \
  http://localhost:7080/auth/send-code

# Where post-data.json contains:
# {"email":"test@example.com"}

Monitor Resource Usage

# Watch container stats
docker stats

# Check Kong metrics
curl http://localhost:7001/metrics

Security Considerations

Development vs Production

This configuration is for local development only. Production deployments must:

1. Use proper SSL/TLS certificates (not self-signed)
2. Configure Kong with rate limiting and authentication plugins
3. Use production-grade secrets management (not .env files)
4. Enable Kong's security features (request validation, bot detection)
5. Configure proper CORS policies (not *)
6. Use secure Redis passwords
7. Enable Kong audit logging

Environment Variables

Never commit these to version control:

• GITHUB_TOKEN
• RXDB_PREMIUM
• JWT private keys
• Database credentials
• API keys

Next Steps

After validating the integration locally:

1. Run full test suites: yarn test
2. Build all packages: yarn build
3. Test in staging environment
4. Update production deployment documentation
5. Create migration plan for existing users
6. Update client applications to use new OAuth flow

Additional Resources

• Kong Gateway Documentation
• OAuth 2.0 RFC 6749
• PKCE RFC 7636
• RxDB Replication Protocol