📚 Zap Platform Documentation

Complete documentation for the Zap platform, including development guides, testing procedures, and infrastructure details

Testing Auth & Migration
Authentication testing and database migration • Topic Documentation

Testing Authentication and Dual-Write Migration

What Can Be Tested Now

✅ Ready to Test:

  • Database Tables - Verify migrations applied correctly
  • Authentication API - Login, logout, auth check endpoints
  • Dual-Write Migration - Recording metadata written to both SQLite and PostgreSQL
  • ⏳ Not Yet Ready:

    • Login page UI (needs to be created)
    • /connect page (needs to be created)
    • Full authorization flow in UI
    • ---

      Step 1: Create Test User

      cd /var/www/zap
      php scripts/create-test-user.php

      This creates:

    • Email: test@example.com
    • Password: test123
    • Permissions: Can host, can manage recordings
    • ---

      Step 2: Test Authentication API

      Test Login (should succeed)

      curl -X POST https://orcus.getzap.co/api/auth-login.php \
        -H "Content-Type: application/json" \
        -d '{"email":"test@example.com","password":"test123"}' \
        -c cookies.txt

      Expected response:

      {
        "success": true,
        "user": {
          "id": "...",
          "email": "test@example.com",
          "display_name": "Test User",
          "can_host": true,
          "can_manage_recordings": true
        }
      }

      Test Login (should fail - wrong password)

      curl -X POST https://orcus.getzap.co/api/auth-login.php \
        -H "Content-Type: application/json" \
        -d '{"email":"test@example.com","password":"wrong"}' \
        -c cookies.txt

      Expected response:

      {
        "error": "Invalid email or password"
      }
      Status: 401

      Test Auth Check (while logged in)

      curl -X GET https://orcus.getzap.co/api/auth-check.php \
        -b cookies.txt

      Expected response:

      {
        "authenticated": true,
        "user": {
          "id": "...",
          "email": "test@example.com",
          "display_name": "Test User",
          "can_host": true,
          "can_manage_recordings": true
        }
      }

      Test Auth Check (while logged out)

      curl -X GET https://orcus.getzap.co/api/auth-check.php

      Expected response:

      {
        "authenticated": false
      }
      Status: 401

      Test Logout

      curl -X POST https://orcus.getzap.co/api/auth-logout.php \
        -b cookies.txt

      Expected response:

      {
        "success": true
      }

      After logout, auth-check.php should return {"authenticated": false}.

      ---

      Step 3: Test Dual-Write Migration

      The dual-write happens automatically when a recording is uploaded via TUS. To test:

    • Make a recording using the existing /host or /guest page
    • Check SQLite database:
    •    sqlite3 /var/www/zap/database/recordings.db "SELECT upload_id, session_id, filename, file_type FROM recordings ORDER BY upload_time DESC LIMIT 5;"
         ``

    • Check PostgreSQL database:
    • `bash sudo -u postgres psql -d zap -c "SELECT upload_id, session_id, filename, file_type FROM recordings ORDER BY upload_time DESC LIMIT 5;" `

    • Compare results - Both should have the same records
    • Check logs for dual-write confirmation:
    • `bash tail -n 50 /var/www/zap/logs/tus-hooks.log | grep -i postgresql `

      You should see lines like:

      [2025-11-15T...] PostgreSQL: Stored metadata for upload abc123...
      
      ---

      Step 4: Verify Database Tables

      Check PostgreSQL tables exist:

      bash sudo -u postgres psql -d zap -c "\dt"
      
      Should show:
      
    • recordings
    • users
    • user_permissions
    • chat_rooms (from previous migration)
    • chat_room_members
    • chat_messages
    • etc.
    • Check table structures:

      bash

      Recordings table

      sudo -u postgres psql -d zap -c "\d recordings"

      Users table

      sudo -u postgres psql -d zap -c "\d users"

      User permissions table

      sudo -u postgres psql -d zap -c "\d user_permissions"
      
      ---

      Step 5: Test Session Persistence

    • Login via browser:
    • - Open browser dev tools → Network tab - Go to:
      https://orcus.getzap.co/api/auth-login.php (will show 405, need POST) - Or use a simple HTML form (see below)

    • Create a simple test page (temporary):
    • html Test Login
      `

    • Access: https://orcus.getzap.co/test-login.html
    • Submit form - should see user data
    • Check browser cookies - should see PHPSESSID cookie
    • Refresh page - session should persist
    • ---

      Troubleshooting

      Authentication fails:

    • Check PHP error logs: tail -f /var/www/zap/logs/apache-error.log
    • Verify user exists: sudo -u postgres psql -d zap -c "SELECT email, can_host FROM users u LEFT JOIN user_permissions up ON u.id = up.user_id;"
    • Check password hash: Verify password_verify() works with stored hash
    • Dual-write not working:

    • Check tus-hooks.log: tail -f /var/www/zap/logs/tus-hooks.log
    • Verify PostgreSQL connection in Connection.php
    • Check for exceptions in logs
    • Session not persisting:

    • Check PHP session config: php -i | grep session
    • Verify session directory is writable: ls -la /var/lib/php/sessions/
    • Check Apache/PHP-FPM session configuration
    ---

    Next Steps After Testing

    Once authentication is verified:

  • Create proper login page (/login.php)
  • Create /connect page with role selection
  • Add authorization checks to /connect` page
  • Migrate existing SQLite data to PostgreSQL (script needed)
  • Switch reads from SQLite to PostgreSQL
  • Remove SQLite code