feat(auth): require admin approval for teacher accounts

New teacher registrations are created pending admin approval and are not
auto-logged-in. Login and every authenticated request are refused for
unapproved teachers (force-logging out any existing sessions), and all
teacher action routes are gated. Adds an admin API and an Approvals page
(list/approve/reject) guarded by an isAdmin flag or the SPANDAN_ADMIN_EMAILS
allowlist, plus a migration that sets existing teachers pending and promotes
the founder account.

Author: imrohitvk

backend/scripts/migrate_teacher_approval.js

@@ -0,0 +1,65 @@
+/**
+ * One-time migration for the teacher-approval feature.
+ *
+ * Approach for existing accounts: the founder account(s) are set approved + admin so they
+ * can sign in and reach the admin page; EVERY other existing teacher is set to 'pending' so
+ * they surface on the admin approval page for manual approve/reject (this also lets the admin
+ * flow be tested against real accounts, and the junk/attack accounts get rejected there).
+ *
+ * The field must be PERSISTED (not left to the Mongoose default) so that the admin page's
+ * `find({ teacherApprovalStatus: 'pending' })` query actually returns these old accounts.
+ *
+ * SAFE BY DEFAULT: dry-run (prints the plan, writes nothing). Pass --apply to write.
+ *
+ *   node backend/scripts/migrate_teacher_approval.js            # dry-run
+ *   node backend/scripts/migrate_teacher_approval.js --apply    # perform updates
+ *
+ * Uses MONGODB_URI (falls back to mongodb://127.0.0.1:27017/spandan). Run OFF the live
+ * session, and review the printed plan before using --apply.
+ */
+import mongoose from 'mongoose'
+import User from '../src/models/User.js'
+
+const APPLY = process.argv.includes('--apply')
+const URI = process.env.MONGODB_URI || 'mongodb://127.0.0.1:27017/spandan'
+
+// Founder account(s): set approved + admin so they can sign in and reach the admin page.
+// Override with FOUNDER_ADMIN_EMAILS (comma-separated). EVERY other existing teacher is set
+// to 'pending' so it appears on the admin approval page for manual approve/reject.
+const FOUNDER_ADMINS = (process.env.FOUNDER_ADMIN_EMAILS || 'imrohitvk@gmail.com')
+  .split(',').map(e => e.trim().toLowerCase()).filter(Boolean)
+
+const isFounder = (email = '') => FOUNDER_ADMINS.includes(email.toLowerCase())
+
+async function main() {
+  await mongoose.connect(URI)
+  console.log(`Connected: ${URI}  |  mode: ${APPLY ? 'APPLY (writing)' : 'DRY-RUN (no writes)'}`)
+
+  const teachers = await User.find({ role: 'teacher' }).select('name email teacherApprovalStatus isActive isAdmin')
+  const founders = [], pending = []
+  for (const t of teachers) {
+    if (isFounder(t.email)) founders.push(t)
+    else pending.push(t)
+  }
+
+  console.log(`\nTeachers: ${teachers.length}  ->  founder(approved+admin) ${founders.length}, set-pending ${pending.length}`)
+  console.log('\n-- FOUNDER -> approved + isAdmin=true (can sign in and administer) --')
+  founders.forEach(t => console.log(`   ${t.email}  (${t.name})`))
+  console.log('\n-- SET PENDING -> will appear on the admin page for approve/reject --')
+  pending.forEach(t => console.log(`   ${t.email}  (${t.name})`))
+
+  if (!APPLY) {
+    console.log('\nDRY-RUN complete. Re-run with --apply to write these changes.')
+    await mongoose.disconnect(); return
+  }
+
+  const founderIds = founders.map(t => t._id)
+  const pendingIds = pending.map(t => t._id)
+  // Approve+admin the founders FIRST so the admin is never locked out.
+  const r1 = founderIds.length ? await User.updateMany({ _id: { $in: founderIds } }, { $set: { teacherApprovalStatus: 'approved', isAdmin: true } }) : { modifiedCount: 0 }
+  const r2 = pendingIds.length ? await User.updateMany({ _id: { $in: pendingIds } }, { $set: { teacherApprovalStatus: 'pending' } }) : { modifiedCount: 0 }
+  console.log(`\nApplied: founders(approved+admin)=${r1.modifiedCount}, set-pending=${r2.modifiedCount}`)
+  await mongoose.disconnect()
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

backend/src/index.js

@@ -21,6 +21,7 @@ import transcriptionRoutes from './routes/transcription.js'
 import transcriptRoutes from './routes/transcripts.js'
 import responseRoutes from './routes/responses.js'
 import researchRoutes from './routes/research.js'
+import adminRoutes from './routes/admin.js'
 
 // Import models for reference
 import './models/index.js'
@@ -357,6 +358,7 @@ app.use('/api/transcription', transcriptionRoutes)
 app.use('/api/transcripts', transcriptRoutes)
 app.use('/api/responses', responseRoutes)
 app.use('/api/research', researchRoutes)
+app.use('/api/admin', adminRoutes)
 
 // Health check
 app.get('/api/health', (req, res) => {

backend/src/middleware/auth.js

@@ -54,6 +54,20 @@ export const authenticate = async (req, res, next) => {
       })
     }
 
+    // Force-logout unapproved teachers. A teacher whose account is pending or rejected may still
+    // hold a valid token — issued before approval was required, or before an admin revoked them.
+    // Returning 401 makes the client's global fetch interceptor drop the session and send them to
+    // the login screen (which then explains they are awaiting approval). Login separately blocks
+    // them, so they cannot get back in until approved. Approve/reject clears the auth cache, so
+    // this takes effect on their very next request rather than after the cache TTL.
+    if (user.role === 'teacher' && user.teacherApprovalStatus !== 'approved') {
+      return res.status(401).json({
+        error: 'Approval required',
+        code: 'TEACHER_NOT_APPROVED',
+        message: 'Your teacher account is awaiting admin approval. Please sign in once it is approved.'
+      })
+    }
+
     req.user = user
     next()
   } catch (error) {
@@ -93,6 +107,39 @@ export const authorize = (...roles) => {
   }
 }
 
+// Defense-in-depth gate for teacher-only actions. The primary control is that an
+// unapproved teacher is never issued a JWT (blocked at /register/verify and /login),
+// so this normally never fires; it covers the edge cases where a token already exists
+// (approval revoked mid-session, or a student self-promoted to teacher via PUT /role).
+// Place AFTER authenticate + authorize('teacher') on every teacher write/session route.
+export const requireApprovedTeacher = (req, res, next) => {
+  if (req.user && req.user.role === 'teacher' && req.user.teacherApprovalStatus !== 'approved') {
+    return res.status(403).json({
+      error: 'Approval pending',
+      code: 'TEACHER_NOT_APPROVED',
+      message: 'Your teacher account is awaiting admin approval.'
+    })
+  }
+  next()
+}
+
+// Admins are identified by the persisted isAdmin flag OR a bootstrap allowlist from the
+// SPANDAN_ADMIN_EMAILS env var (comma-separated), so the first admin can act before any
+// isAdmin flag is set in the DB. Never trust a client-supplied admin claim.
+const ADMIN_EMAILS = (process.env.SPANDAN_ADMIN_EMAILS || '')
+  .split(',').map(e => e.trim().toLowerCase()).filter(Boolean)
+
+export const authorizeAdmin = (req, res, next) => {
+  if (!req.user) {
+    return res.status(401).json({ error: 'Not authenticated', message: 'Please sign in.' })
+  }
+  const isAdmin = req.user.isAdmin === true || ADMIN_EMAILS.includes((req.user.email || '').toLowerCase())
+  if (!isAdmin) {
+    return res.status(403).json({ error: 'Access denied', message: 'Admin access required.' })
+  }
+  next()
+}
+
 export const generateToken = (userId) => {
   return jwt.sign(
     { userId },

backend/src/models/User.js

@@ -33,6 +33,34 @@ const userSchema = new mongoose.Schema({
     enum: ['teacher', 'student'],
     required: [true, 'Role is required']
   },
+  // Teacher accounts must be approved by an admin before they can sign in or use any
+  // teacher functionality. Students are 'approved' by default (the field is only
+  // consulted when role === 'teacher'). New teacher registrations start 'pending'.
+  teacherApprovalStatus: {
+    type: String,
+    enum: ['pending', 'approved', 'rejected'],
+    default: 'pending'
+  },
+  // Grants access to the admin approval page and endpoints. Set only via the migration
+  // script or another admin; never client-settable.
+  isAdmin: {
+    type: Boolean,
+    default: false
+  },
+  approvedBy: {
+    type: mongoose.Schema.Types.ObjectId,
+    ref: 'User',
+    default: null
+  },
+  approvedAt: {
+    type: Date,
+    default: null
+  },
+  rejectionReason: {
+    type: String,
+    default: '',
+    maxlength: [500, 'Rejection reason cannot exceed 500 characters']
+  },
   profileImage: {
     type: String,
     default: ''

backend/src/routes/admin.js

@@ -0,0 +1,69 @@
+import express from 'express'
+import User from '../models/User.js'
+import { authenticate, authorizeAdmin, clearUserCache } from '../middleware/auth.js'
+
+const router = express.Router()
+
+// Every admin route requires a signed-in admin (isAdmin flag OR SPANDAN_ADMIN_EMAILS allowlist).
+router.use(authenticate, authorizeAdmin)
+
+const STATUSES = ['pending', 'approved', 'rejected']
+const SAFE_FIELDS = 'name email teacherApprovalStatus isActive createdAt approvedAt approvedBy rejectionReason'
+
+// List teacher accounts by approval status (default: pending). Used by the admin page.
+router.get('/teacher-requests', async (req, res) => {
+  try {
+    const status = req.query.status
+    const filter = { role: 'teacher' }
+    if (STATUSES.includes(status)) filter.teacherApprovalStatus = status
+    else if (status && status !== 'all') return res.status(400).json({ error: 'Invalid status filter' })
+
+    const requests = await User.find(filter).select(SAFE_FIELDS).sort({ createdAt: -1 }).lean()
+    const counts = {}
+    for (const s of STATUSES) counts[s] = await User.countDocuments({ role: 'teacher', teacherApprovalStatus: s })
+    res.json({ requests, counts })
+  } catch (error) {
+    res.status(500).json({ error: error.message })
+  }
+})
+
+// Approve a pending teacher: they can now sign in and use teacher features.
+router.post('/teacher-requests/:id/approve', async (req, res) => {
+  try {
+    const user = await User.findById(req.params.id)
+    if (!user || user.role !== 'teacher') return res.status(404).json({ error: 'Teacher account not found' })
+
+    user.teacherApprovalStatus = 'approved'
+    user.approvedBy = req.user._id
+    user.approvedAt = new Date()
+    user.rejectionReason = ''
+    user.isActive = true
+    await user.save()
+    clearUserCache() // reflect immediately, not after the auth-cache TTL
+
+    res.json({ message: 'Teacher approved', user: user.toJSON() })
+  } catch (error) {
+    res.status(500).json({ error: error.message })
+  }
+})
+
+// Reject a teacher request (optionally with a reason). They stay unable to sign in.
+router.post('/teacher-requests/:id/reject', async (req, res) => {
+  try {
+    const user = await User.findById(req.params.id)
+    if (!user || user.role !== 'teacher') return res.status(404).json({ error: 'Teacher account not found' })
+
+    user.teacherApprovalStatus = 'rejected'
+    user.rejectionReason = (req.body?.reason || '').toString().slice(0, 500)
+    user.approvedBy = req.user._id
+    user.approvedAt = new Date()
+    await user.save()
+    clearUserCache()
+
+    res.json({ message: 'Teacher request rejected', user: user.toJSON() })
+  } catch (error) {
+    res.status(500).json({ error: error.message })
+  }
+})
+
+export default router

backend/src/routes/auth.js

@@ -40,6 +40,17 @@ router.post('/register/verify', validate(verifyRegistrationSchema), async (req,
     const { name, email, password, role, otp } = req.validatedBody
     await verifyRegistrationOtp(email, otp) // throws on invalid/expired/too-many-attempts
     const user = await register(name, email, password, role) // creates the (now email-verified) account
+
+    // Teacher accounts are NOT auto-logged-in: they require admin approval first. We issue
+    // no token and return a pendingApproval flag so the client sends the registrant back to
+    // the login screen with an "admin approval pending" message. Students log in immediately.
+    if (user.role === 'teacher') {
+      return res.status(202).json({
+        pendingApproval: true,
+        message: 'Registration successful. Your teacher account is pending admin approval. You will be able to sign in once an administrator approves it.'
+      })
+    }
+
     const token = generateToken(user._id)
     res.status(201).json({
       message: 'Registration successful',
@@ -60,6 +71,16 @@ router.post('/login', validate(loginSchema), async (req, res) => {
   try {
     const { email, password } = req.validatedBody
     const user = await login(email, password)
+
+    // A teacher who is not yet approved (or was rejected) is refused a token and bounced back
+    // to the login screen with a clear message, rather than landing in the teacher dashboard.
+    if (user.role === 'teacher' && user.teacherApprovalStatus !== 'approved') {
+      const message = user.teacherApprovalStatus === 'rejected'
+        ? 'Your teacher account request was not approved. Please contact the administrator.'
+        : 'Your teacher account is awaiting admin approval. Please try signing in again once it is approved.'
+      return res.status(403).json({ error: message, code: 'TEACHER_NOT_APPROVED', status: user.teacherApprovalStatus })
+    }
+
     const token = generateToken(user._id)
 
     res.json({

backend/src/routes/questions.js

@@ -1,5 +1,5 @@
 import express from 'express'
-import { authenticate, authorize } from '../middleware/auth.js'
+import { authenticate, authorize, requireApprovedTeacher } from '../middleware/auth.js'
 import { generateQuestions, AI_PROVIDERS } from '../services/questionService.js'
 import { getGenerationQueue } from '../services/generationQueue.js'
 import { stripObject } from '../utils/sanitize.js'
@@ -27,7 +27,7 @@ router.get('/providers', (req, res) => {
 
 // POST /api/questions/generate - Generate questions from transcript
 // Authorization: teacher only
-router.post('/generate', authorize('teacher'), async (req, res) => {
+router.post('/generate', authorize('teacher'), requireApprovedTeacher, async (req, res) => {
   try {
     const { transcript, config } = req.body
     const { 
@@ -79,7 +79,7 @@ router.post('/generate', authorize('teacher'), async (req, res) => {
 
 // GET /api/questions/jobs/:jobId - poll an async generation job (Phase 2D)
 // Authorization: teacher only, and only the teacher who requested it.
-router.get('/jobs/:jobId', authorize('teacher'), async (req, res) => {
+router.get('/jobs/:jobId', authorize('teacher'), requireApprovedTeacher, async (req, res) => {
   try {
     const queue = getGenerationQueue()
     if (!queue) {
@@ -108,7 +108,7 @@ router.get('/jobs/:jobId', authorize('teacher'), async (req, res) => {
 
 // Create a question (for manual creation)
 // Authorization: teacher only
-router.post('/', authorize('teacher'), async (req, res) => {
+router.post('/', authorize('teacher'), requireApprovedTeacher, async (req, res) => {
   try {
     const Question = (await import('../models/Question.js')).default
     const { 

backend/src/routes/rooms.js

@@ -1,14 +1,14 @@
 import express from 'express'
 import { createRoom, getRoomById, getRoomByCode, getRoomsByTeacher, getRoomsByStudent, getActiveRoomsByStudent, updateRoom, deleteRoom } from '../services/roomService.js'
 import { authenticate } from '../middleware/auth.js'
-import { authorize } from '../middleware/auth.js'
+import { authorize, requireApprovedTeacher } from '../middleware/auth.js'
 import { validate, createRoomSchema } from '../middleware/validation.js'
 import { rebuildSnapshot } from '../services/resultsSnapshot.js'
 
 const router = express.Router()
 
 // Create new room
-router.post('/', authenticate, authorize('teacher'), validate(createRoomSchema), async (req, res) => {
+router.post('/', authenticate, authorize('teacher'), requireApprovedTeacher, validate(createRoomSchema), async (req, res) => {
   try {
     const { name, settings } = req.validatedBody
     const room = await createRoom(name, req.user._id, settings)
@@ -127,7 +127,7 @@ router.get('/student/active', authenticate, authorize('student'), async (req, re
 })
 
 // Update room
-router.put('/:id', authenticate, authorize('teacher'), async (req, res) => {
+router.put('/:id', authenticate, authorize('teacher'), requireApprovedTeacher, async (req, res) => {
   try {
     const room = await getRoomById(req.params.id)
 
@@ -163,7 +163,7 @@ router.put('/:id', authenticate, authorize('teacher'), async (req, res) => {
 })
 
 // Delete room
-router.delete('/:id', authenticate, authorize('teacher'), async (req, res) => {
+router.delete('/:id', authenticate, authorize('teacher'), requireApprovedTeacher, async (req, res) => {
   try {
     const room = await getRoomById(req.params.id)
 

backend/src/routes/transcription.js

@@ -1,5 +1,5 @@
 import express from 'express'
-import { authenticate, authorize } from '../middleware/auth.js'
+import { authenticate, authorize, requireApprovedTeacher } from '../middleware/auth.js'
 
 const router = express.Router()
 
@@ -23,7 +23,7 @@ router.get('/status', authenticate, async (req, res) => {
 })
 
 // Transcribe an audio chunk — forwarded to the faster-whisper service
-router.post('/transcribe', authenticate, authorize('teacher'), async (req, res) => {
+router.post('/transcribe', authenticate, authorize('teacher'), requireApprovedTeacher, async (req, res) => {
   if (!req.body || !req.body.audio) {
     return res.status(400).json({ error: 'No audio provided' })
   }