Staff Dashboard Setup Guide

Quick start guide for setting up and using the staff dashboard.

✅ Prerequisites Completed

• Clerk JWT template configured with staffDashboardAccess claim
• Convex schema deployed with staff tables
• Security infrastructure in place (4 layers)
• Basic UI routes created

🚀 Quick Start

1. Grant Staff Access to First Admin

Run this script to grant staff access to a @do.dev user:

pnpm tsx scripts/grant-staff-access.ts your-email@do.dev

Requirements:

• User must already be signed up in Clerk
• Email must end with @do.dev
• CLERK_SECRET_KEY must be set in .env.local

2. Sign Out and Sign Back In

After granting access, the user needs to:

1. Sign out completely
2. Sign back in
3. This refreshes the JWT token with the new staffDashboardAccess claim

3. Access the Staff Dashboard

Navigate to:

http://localhost:3017/staff

You should see the staff dashboard with:

• ✅ Warning banner
• ✅ Navigation sidebar
• ✅ Dashboard overview with placeholder cards
• ✅ Quick actions

🔒 Security Verification

Test Unauthorized Access

1. Test with no auth:

   • Navigate to /staff without being logged in
   • Should redirect to sign-in page

2. Test with wrong email domain:

   • Sign in with a non-@do.dev email
   • Navigate to /staff
   • Should show 404 (hiding dashboard existence)

3. Test without staff flag:

   • Sign in with @do.dev email but no staffDashboardAccess
   • Navigate to /staff
   • Should show 404

4. Test with full access:

   • Sign in with @do.dev email + staffDashboardAccess = true
   • Navigate to /staff
   • Should see staff dashboard ✅

📊 Current Features

✅ Implemented (Phase 1 & 2)

• Security Infrastructure

  • 4-layer defense in depth
  • Middleware protection
  • Layout server-side checks
  • Convex function auth helpers

• Basic UI

  • Dashboard overview page
  • User management page (placeholder)
  • Audit logs page (placeholder)
  • Navigation sidebar

• Database Schema

  • staffAuditLogs table
  • userProfiles table

⏳ Coming Soon (Phase 3 & 4)

• Dashboard Stats (Phase 3)

  • Real user counts from Clerk
  • Active user metrics
  • Staff member count
  • Recent activity feed

• User Management (Phase 3)

  • List all Clerk users
  • Search and filter
  • Grant/revoke staff access
  • View user details
  • Add staff notes

• Audit Logs (Phase 4)

  • View all staff actions
  • Filter by staff member, action, date
  • Export audit reports

🧪 Testing Checklist

• Can access /staff with authorized user
• Cannot access /staff without auth
• Cannot access /staff with wrong email domain
• Cannot access /staff without staff flag
• Navigation works between pages
• User info displays correctly in sidebar
• Warning banner appears on all pages

🔧 Troubleshooting

"404 Not Found" when accessing /staff

Possible causes:

1. User not authenticated → Sign in first
2. Email domain not @do.dev → Check your email
3. Staff access not granted → Run grant script
4. JWT claim not updated → Sign out and back in

Solution:

# Grant access
pnpm tsx scripts/grant-staff-access.ts your-email@do.dev

# Sign out completely, then sign back in

"Middleware errors"

Check that:

• Clerk credentials are in .env.local
• Convex is running (pnpm dev:convex)
• No typos in email domain check

"Can't find user"

Make sure the user has signed up at least once before granting staff access.

📝 Next Steps

1. Deploy Convex Schema:

   pnpm convex:deploy

2. Grant Staff Access:

   pnpm tsx scripts/grant-staff-access.ts admin@do.dev

3. Test Access:

   • Sign out and back in
   • Navigate to http://localhost:3017/staff
   • Verify you can see the dashboard

4. Ready for Phase 3:

   • Implement real dashboard stats
   • Build user management features
   • Connect to Convex queries

🎯 Development Phases

• ✅ Phase 1: Security foundation (COMPLETE)
• ✅ Phase 2: Route protection & basic UI (COMPLETE)
• ⏳ Phase 3: Real data integration (Next)
• ⏳ Phase 4: Advanced features
• ⏳ Phase 5: Security hardening & polish

🆘 Getting Help

Refer to the main plan document for detailed architecture:

docs/STAFF_DASHBOARD_PLAN.md

Check the source code comments for implementation details:

• lib/auth/staff-auth.ts - Authorization utilities
• convex/_helpers/staffAuth.ts - Convex auth helpers
• middleware.ts - Route protection
• app/staff/layout.tsx - Dashboard layout