KArtSell.Aegis/docs/JWT_TEST_GUIDE.md

JWT Authentication Testing Guide

Local Testing (Release Mode)

Prerequisites

• .NET 10 SDK
• PostgreSQL SSH tunnel
• curl or Postman

Step 1: Start SSH Tunnel

ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7

Keep this terminal open.

Step 2: Start Backend (Release Mode)

cd D:\JobRoomz\KArtSell.Aegis

# Set test JWT key (32 bytes = 256 bits)
$env:JWT_KEY = "test-key-32-bytes-min-for-hs256!!"

# Set PostgreSQL connection
$env:KARTSELL_POSTGRES = "Host=127.0.0.1;Port=5432;Database=kartselldb;Username=kartsell;Password=kartsell4321@!"

# Run Release mode
dotnet run -c Release --project src/KArtSell.Host

# Expected output:
# Now listening on: http://0.0.0.0:5002

Wait for "Application started" message.

Step 3: Start Frontend Dev Server

cd D:\JobRoomz\KArtSell.Aegis\frontend
pnpm dev

# Expected output:
# VITE v... ready in ... ms
# ➜  Local:   http://localhost:5174/

Step 4: Test Login Flow

Option A: Browser (Recommended)

1. Open http://localhost:5174
2. Should redirect to /login (no auth token)
3. Enter credentials:
   • Username: testuser
   • Password: testpass
4. Click "Sign In"
5. Should receive JWT token and redirect to /home
6. Check browser DevTools > Application > localStorage
   • kartsell_auth_token: Contains JWT token
   • kartsell_expires_at: Unix timestamp (current time + 1 hour)

Option B: curl (API Testing)

1. Login Request

curl -X POST http://localhost:5002/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass","role":"Admin"}'

Expected Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

2. Extract Token

# Copy accessToken value
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

3. Use Token in Protected Endpoint

curl http://localhost:5002/api/identities \
  -H "Authorization: Bearer $TOKEN"

Expected: Success (200 OK) or relevant business response

4. Test Expired/Invalid Token

# Invalid token
curl http://localhost:5002/api/identities \
  -H "Authorization: Bearer invalid.token.here"

# Expected: 401 Unauthorized

Test Scenarios

Scenario 1: Successful Login

✅ User provides correct credentials ✅ Backend returns JWT token ✅ Frontend stores token in localStorage ✅ Subsequent requests include Authorization header ✅ User can access protected resources

Scenario 2: Invalid Credentials

❌ User provides wrong password ✅ Backend returns 401 Unauthorized ✅ Frontend shows error message ✅ No token stored ✅ User remains on login page

Scenario 3: Token Expiration

✅ Token is valid initially ⏳ Wait for token expiration (or manually adjust kartsell_expires_at) ✅ Frontend detects expiration ✅ Protected endpoint returns 401 ✅ Frontend automatically logs out ✅ User redirected to login

Scenario 4: API Interceptor

✅ User logs in and receives token ✅ Make request via fetch API ✅ setupAuthInterceptor adds Authorization header ✅ Backend receives and validates token ✅ Request succeeds with 200 OK

Scenario 5: Multiple Tabs/Windows

✅ Login in Tab 1 ✅ Token stored in localStorage ✅ Open Tab 2 to same app ✅ Tab 2 automatically has token (from localStorage) ✅ Both tabs can make authenticated requests

Debugging

Check Backend JWT Configuration

# Add this to Program.cs temporarily for debugging
Console.WriteLine($"JWT Key: {config["Jwt:Key"]}");
Console.WriteLine($"JWT Issuer: {config["Jwt:Issuer"]}");
Console.WriteLine($"JWT Audience: {config["Jwt:Audience"]}");

Check Frontend Token

// Open browser console
localStorage.getItem('kartsell_auth_token')
localStorage.getItem('kartsell_expires_at')
new Date(parseInt(localStorage.getItem('kartsell_expires_at')))

Enable Debug Logging

Backend:

{
  "Serilog": {
    "MinimumLevel": "Debug"
  }
}

Frontend:

// In useAuthApi.ts
console.log('Auth state:', authState.value)
console.log('Token valid:', getToken())

Network Inspector

1. Open browser DevTools > Network tab
2. Click "Sign In"
3. Look for POST /api/auth/login
4. Check response has accessToken
5. Make subsequent API request
6. Check request headers include Authorization: Bearer ...

Common Issues & Solutions

Issue: 401 Unauthorized on Protected Endpoints

Possible Causes:

1. Token not included in Authorization header

   • Check setupAuthInterceptor in main.ts
   • Verify localStorage token exists

2. Token expired

   • Check kartsell_expires_at in localStorage
   • Set Jwt:ExpirationMinutes to larger value for testing

3. JWT key mismatch

   • Backend JWT key must match production key
   • Ensure JWT_KEY environment variable is set

4. Token signature invalid

   • Check JWT signature on jwt.io
   • Verify HMAC SHA256 algorithm

Solution:

# 1. Check token value
localStorage.getItem('kartsell_auth_token')

# 2. Decode token (jwt.io)
# Copy token to https://jwt.io

# 3. Verify claims
# Should have: NameIdentifier, Name, Role, auth_mode

# 4. Check expiration
new Date(parseInt(localStorage.getItem('kartsell_expires_at')))

Issue: Redirect Loop

Possible Causes:

1. Token always invalid
2. setupAuthInterceptor not working
3. Router guard issue

Solution:

# Check LocalStorage
localStorage.clear()

# Restart frontend
# Re-login

# Check Network tab for actual requests

Issue: CORS Errors

Backend and Frontend on Different Ports

• Backend: http://localhost:5002
• Frontend: http://localhost:5174

Solution: Add CORS middleware to backend:

// In Program.cs
app.UseCors(builder => builder
    .AllowAnyOrigin()
    .AllowAnyMethod()
    .AllowAnyHeader());

Performance Testing

Load Test JWT Validation

# Generate 100 requests with valid token
$token = "eyJ..." # from login response

1..100 | ForEach-Object {
    curl http://localhost:5002/api/identities `
      -H "Authorization: Bearer $token" `
      -w "%{http_code}\n"
}

Expected: All 200 or 401 (consistent)

Token Generation Performance

time (for i in {1..10}; do
  curl -X POST http://localhost:5002/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{"username":"test","password":"test"}' \
    > /dev/null
done)

Expected: < 500ms per request

Cleanup

After testing:

# Kill backend
Ctrl+C in backend terminal

# Kill frontend
Ctrl+C in frontend terminal

# Clear test data
localStorage.clear()

# Close SSH tunnel
Ctrl+C in SSH terminal

Next Steps

If all tests pass:

1. ✅ JWT authentication working in Release mode
2. → Proceed to Phase 2: Production Deployment Preparation
3. → Implement database credential validation
4. → Configure production JWT key