From 647ec4ad770b6c8e8dde2ebcfa12affd4bf15f06 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:23:27 +0530
Subject: [PATCH 01/22] feat(tpo): add tpoRoleSignalService.js

---
 backend/services/tpoRoleSignalService.js | 161 +++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 backend/services/tpoRoleSignalService.js

diff --git a/backend/services/tpoRoleSignalService.js b/backend/services/tpoRoleSignalService.js
new file mode 100644
index 00000000..bce7e1bc
--- /dev/null
+++ b/backend/services/tpoRoleSignalService.js
@@ -0,0 +1,161 @@
+import { logger } from "../config/logger.js";
+
+/**
+ * Advisory classification for an institutional email.
+ *
+ * IMPORTANT: these rules are per-college configuration and are never an
+ * authorization decision. The result only helps the reviewer understand why
+ * a request was routed the way it was.
+ *
+ * Supported rule shapes:
+ *   { type: "domain", value: "staff.example.edu" }
+ *   { type: "local_prefix", values: ["faculty", "staff"] }
+ *   { type: "local_regex", value: "^(dr\\.|prof)" }
+ *
+ * Rules are intentionally constrained instead of accepting arbitrary regex
+ * strings for every purpose. The local_regex path is bounded and only applied
+ * to the local-part before the @.
+ */
+const MAX_RULES = 20;
+const MAX_REGEX_LENGTH = 120;
+
+function normalizeEmail(email) {
+  return String(email || "").trim().toLowerCase();
+}
+
+function splitEmail(email) {
+  const normalized = normalizeEmail(email);
+  const at = normalized.lastIndexOf("@");
+  if (at <= 0 || at === normalized.length - 1) {
+    return { email: normalized, local: "", domain: "" };
+  }
+  return {
+    email: normalized,
+    local: normalized.slice(0, at),
+    domain: normalized.slice(at + 1),
+  };
+}
+
+function matchesRule(local, domain, rule) {
+  if (!rule || typeof rule !== "object") return false;
+  const type = String(rule.type || "").toLowerCase().trim();
+
+  if (type === "domain") {
+    return domain === String(rule.value || "").toLowerCase().trim();
+  }
+
+  if (type === "local_prefix") {
+    const values = Array.isArray(rule.values) ? rule.values : [];
+    return values
+      .slice(0, MAX_RULES)
+      .some((value) => local.startsWith(String(value || "").toLowerCase().trim()));
+  }
+
+  if (type === "local_regex") {
+    const pattern = String(rule.value || "");
+    if (!pattern || pattern.length > MAX_REGEX_LENGTH) return false;
+    try {
+      return new RegExp(pattern, "i").test(local);
+    } catch (err) {
+      logger.warn({ err }, "[TpoRoleSignal] invalid local regex skipped");
+      return false;
+    }
+  }
+
+  return false;
+}
+
+function anyRuleMatches(local, domain, rules) {
+  return (Array.isArray(rules) ? rules : [])
+    .slice(0, MAX_RULES)
+    .some((rule) => matchesRule(local, domain, rule));
+}
+
+export function classifyInstitutionalEmailRole(email, college = {}) {
+  const { email: normalizedEmail, local, domain } = splitEmail(email);
+  if (!domain) return "unknown";
+
+  const staffMatch = anyRuleMatches(local, domain, college.staffEmailPatterns);
+  const studentMatch = anyRuleMatches(local, domain, college.studentEmailPatterns);
+
+  if (staffMatch && !studentMatch) return "staff_candidate";
+  if (studentMatch && !staffMatch) return "student_candidate";
+  if (staffMatch && studentMatch) return "ambiguous";
+  return "unknown";
+}
+
+export function buildTpoVerificationSignal(email, college) {
+  const classification = classifyInstitutionalEmailRole(email, college);
+
+  return {
+    type: "EMAIL_PATTERN",
+    result: classification,
+    capturedAt: new Date(),
+  };
+}
+
+export function isValidRolePatternRule(rule) {
+  if (!rule || typeof rule !== "object") return false;
+  const type = String(rule.type || "").toLowerCase().trim();
+
+  if (type === "domain") {
+    return (
+      typeof rule.value === "string" &&
+      /^[a-z0-9.-]+$/.test(rule.value.toLowerCase().trim()) &&
+      rule.value.length <= 253
+    );
+  }
+
+  if (type === "local_prefix") {
+    return (
+      Array.isArray(rule.values) &&
+      rule.values.length > 0 &&
+      rule.values.length <= MAX_RULES &&
+      rule.values.every(
+        (value) =>
+          typeof value === "string" &&
+          value.trim().length > 0 &&
+          value.trim().length <= 60
+      )
+    );
+  }
+
+  if (type === "local_regex") {
+    if (typeof rule.value !== "string" || rule.value.length === 0 || rule.value.length > MAX_REGEX_LENGTH) {
+      return false;
+    }
+    try {
+      // Compile during validation so malformed expressions never become
+      // active configuration.
+      new RegExp(rule.value, "i");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return false;
+}
+
+export function sanitizeRolePatternRules(rules) {
+  if (!Array.isArray(rules)) return [];
+  return rules
+    .slice(0, MAX_RULES)
+    .filter(isValidRolePatternRule)
+    .map((rule) => {
+      const type = String(rule.type).toLowerCase().trim();
+      if (type === "domain") {
+        return { type, value: rule.value.toLowerCase().trim() };
+      }
+      if (type === "local_prefix") {
+        return {
+          type,
+          values: rule.values
+            .map((value) => value.toLowerCase().trim())
+            .filter(Boolean)
+            .slice(0, MAX_RULES),
+        };
+      }
+      return { type, value: rule.value };
+    });
+}

From fedd0163558ca4063d6aa55c939f924fc931c123 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:23:29 +0530
Subject: [PATCH 02/22] feat(tpo): add TpoVerificationReview.js

---
 backend/models/TpoVerificationReview.js | 75 +++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 backend/models/TpoVerificationReview.js

diff --git a/backend/models/TpoVerificationReview.js b/backend/models/TpoVerificationReview.js
new file mode 100644
index 00000000..7eb52dd2
--- /dev/null
+++ b/backend/models/TpoVerificationReview.js
@@ -0,0 +1,75 @@
+import mongoose from "mongoose";
+
+/**
+ * One immutable review record per TPO role application decision.
+ * This is deliberately separate from User/College state so the audit trail
+ * survives later edits, role revocation, or college renames.
+ */
+const tpoVerificationReviewSchema = new mongoose.Schema(
+  {
+    userId: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: "User",
+      required: true,
+      index: true,
+    },
+    collegeId: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: "College",
+      required: true,
+      index: true,
+    },
+    requestedEmail: {
+      type: String,
+      required: true,
+      trim: true,
+      lowercase: true,
+      maxlength: 254,
+    },
+    emailRoleSignal: {
+      type: String,
+      enum: ["staff_candidate", "student_candidate", "ambiguous", "unknown"],
+      required: true,
+    },
+    evidence: {
+      type: [
+        {
+          kind: {
+            type: String,
+            enum: ["email", "invitation", "staff_id", "document", "manual_note"],
+            required: true,
+          },
+          label: { type: String, required: true, trim: true, maxlength: 120 },
+          reference: { type: String, default: null, trim: true, maxlength: 500 },
+          note: { type: String, default: null, trim: true, maxlength: 1000 },
+          addedAt: { type: Date, default: Date.now },
+        },
+      ],
+      default: [],
+    },
+    decision: {
+      type: String,
+      enum: ["approved", "rejected"],
+      required: true,
+    },
+    decisionReason: {
+      type: String,
+      default: null,
+      trim: true,
+      maxlength: 1000,
+    },
+    reviewedBy: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: "User",
+      required: true,
+      index: true,
+    },
+    reviewedAt: {
+      type: Date,
+      default: Date.now,
+    },
+  },
+  { timestamps: true }
+);
+
+export default mongoose.model("TpoVerificationReview", tpoVerificationReviewSchema);

From b90f7904b813246e76a8a35ab0d54cbaa646652a Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:23:34 +0530
Subject: [PATCH 03/22] feat(tpo): store college-specific role signal rules

---
 backend/models/College.js | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/backend/models/College.js b/backend/models/College.js
index 851fe022..d7b6957e 100644
--- a/backend/models/College.js
+++ b/backend/models/College.js
@@ -114,6 +114,32 @@ const collegeSchema = new mongoose.Schema(
       index: true,
     },
 
+    // ── TPO email-role advisory rules ─────────────────────────────────────
+    // College-specific patterns are advisory evidence only. They never grant
+    // or deny a TPO role by themselves. This lets each institution describe
+    // its own mailbox conventions without hardcoding assumptions globally.
+    staffEmailPatterns: {
+      type: [
+        {
+          type: { type: String, enum: ["domain", "local_prefix", "local_regex"] },
+          value: { type: String, trim: true, maxlength: 253 },
+          values: { type: [String], default: undefined },
+        },
+      ],
+      default: [],
+    },
+
+    studentEmailPatterns: {
+      type: [
+        {
+          type: { type: String, enum: ["domain", "local_prefix", "local_regex"] },
+          value: { type: String, trim: true, maxlength: 253 },
+          values: { type: [String], default: undefined },
+        },
+      ],
+      default: [],
+    },
+
     // ── Institutional subscription (TPO-6 Commercialization) ─────────────
     // Billing belongs to the institution, not an individual TPO account.
     // This keeps access intact when the primary TPO changes.

From fb622ef4043aad24578eef22e80ebec6025ff310 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:23:40 +0530
Subject: [PATCH 04/22] feat(tpo): persist advisory verification state

---
 backend/models/User.js | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/backend/models/User.js b/backend/models/User.js
index 4f054150..6a3c017c 100644
--- a/backend/models/User.js
+++ b/backend/models/User.js
@@ -348,6 +348,41 @@ const userSchema = new mongoose.Schema(
       verifiedAt: { type: Date, default: null },
     },
 
+    // ── TPO verification application evidence ────────────────────────────
+    // Pending/approved TPO applications retain their latest advisory signals
+    // and evidence metadata here. This is not the authorization source of
+    // truth: verified TPO access still depends on tpoProfile.verified and the
+    // College approval flow.
+    tpoVerification: {
+      status: {
+        type: String,
+        enum: ["unset", "pending", "approved", "rejected"],
+        default: "unset",
+      },
+      emailRoleSignal: {
+        type: String,
+        enum: ["staff_candidate", "student_candidate", "ambiguous", "unknown"],
+        default: "unknown",
+      },
+      submittedEmail: { type: String, default: null, trim: true, lowercase: true },
+      submittedAt: { type: Date, default: null },
+      evidence: {
+        type: [
+          {
+            kind: {
+              type: String,
+              enum: ["email", "invitation", "staff_id", "document", "manual_note"],
+            },
+            label: { type: String, trim: true, maxlength: 120 },
+            reference: { type: String, default: null, trim: true, maxlength: 500 },
+            note: { type: String, default: null, trim: true, maxlength: 1000 },
+            addedAt: { type: Date, default: Date.now },
+          },
+        ],
+        default: [],
+      },
+    },
+
     // ── Student college verification (Phase 12C) ────────────────────────
     // Distinct from tpoProfile — this is any student proving their own
     // college affiliation, not a TPO representing one. collegeEmail is

From 1cf0c586655098f31b4f6c7c4e4df9740d8397f1 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:23:48 +0530
Subject: [PATCH 05/22] feat(tpo): capture advisory email role signal during
 registration

---
 backend/routes/tpo.js | 40 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/backend/routes/tpo.js b/backend/routes/tpo.js
index c5bc3f42..ae132928 100644
--- a/backend/routes/tpo.js
+++ b/backend/routes/tpo.js
@@ -37,6 +37,7 @@ import { computeReadinessScore } from "../utils/readiness.js";
 import multer from "multer";
 import { csvUpload } from "../middleware/csvUpload.js";
 import { getInstitutionSubscription } from "../services/institutionSubscriptionService.js";
+import { buildTpoVerificationSignal, classifyInstitutionalEmailRole } from "../services/tpoRoleSignalService.js";
 
 const TPO_CACHE_TTL_SECONDS = 2 * 60; // 2 minutes — matches profile cache TTL
 const TPO_CACHE_PREFIX = "tpo:";
@@ -103,8 +104,16 @@ router.post("/register", async (req, res) => {
 
     const email = req.userDoc.email || "";
     const domain = email.split("@")[1];
+    if (!domain) {
+      return res.status(400).json({
+        error: "Your account does not have a valid institutional email address.",
+      });
+    }
 
-    if (!domain || isConsumerEmailDomain(domain)) {
+    // Advisory only: never grants or denies TPO access. The resolved college
+    // rules are applied after the College document is known below.
+
+    if (isConsumerEmailDomain(domain)) {
       return res.status(400).json({
         error: "Please sign up with your institutional email (e.g. yourname@college.ac.in), not a personal email.",
       });
@@ -131,6 +140,14 @@ router.post("/register", async (req, res) => {
       });
     }
 
+    const emailRoleSignal = buildTpoVerificationSignal(email, collegeDoc || existingCollege || {});
+    const emailRoleClassification = emailRoleSignal.result;
+
+    // A matching student signal is deliberately not an automatic rejection:
+    // people can legitimately hold multiple institutional responsibilities
+    // and local mailbox conventions are advisory. It simply makes the
+    // evidence trail explicit for the reviewer.
+
     const now = new Date();
     // Hybrid verification (Phase B): known college domains — including one
     // already verified via an earlier TPO from the same college — skip the
@@ -200,6 +217,22 @@ router.post("/register", async (req, res) => {
       verifiedAt: autoVerified ? now : null,
     };
 
+    req.userDoc.tpoVerification = {
+      status: autoVerified ? "approved" : "pending",
+      emailRoleSignal: emailRoleClassification,
+      submittedEmail: email,
+      submittedAt: now,
+      evidence: [
+        {
+          kind: "email",
+          label: "Institutional sign-in email",
+          reference: null,
+          note: "Email ownership is established by the authenticated sign-in provider; role classification remains advisory.",
+          addedAt: now,
+        },
+      ],
+    };
+
     // TPO-1 hardening: partial-failure handling. The College-side write
     // above already committed by this point — if the User-side write
     // fails now, we'd otherwise strand the domain in a half-claimed state
@@ -272,6 +305,11 @@ router.post("/register", async (req, res) => {
       verified: autoVerified,
       status: autoVerified ? "verified" : "pending",
       isPrimary,
+      emailRoleSignal: emailRoleClassification,
+      verification: {
+        status: autoVerified ? "approved" : "pending",
+        additionalEvidenceRecommended: !autoVerified || emailRoleClassification !== "staff_candidate",
+      },
       message: autoVerified
         ? "Your college is verified. You're all set — head to your dashboard."
         : "Your college registration request has been submitted for verification.",

From 950bf71a7be168dcac8dc26b1396610a675f064c Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:24:38 +0530
Subject: [PATCH 06/22] feat(tpo): add verification review trail to admin
 decisions

---
 backend/controllers/adminController.js | 166 +++++++++++++------------
 1 file changed, 89 insertions(+), 77 deletions(-)

diff --git a/backend/controllers/adminController.js b/backend/controllers/adminController.js
index f8eff3da..0f83a276 100644
--- a/backend/controllers/adminController.js
+++ b/backend/controllers/adminController.js
@@ -35,6 +35,7 @@ import { recordAdminAction } from "../services/adminAuditLog.js";
 import { invalidateCachedUserByFirebaseUid } from "../utils/userAuthCache.js";
 import { logger } from "../config/logger.js";
 import { claimPrimaryIfNone, clearPrimaryIfCurrent } from "../services/tpoTeamService.js";
+import TpoVerificationReview from "../models/TpoVerificationReview.js";
 
 const RECRUITER_QUEUE_FIELDS = "email displayName recruiterProfile createdAt";
 
@@ -79,15 +80,27 @@ export async function getPendingQueue(req, res) {
         companyDomain: u.recruiterProfile?.companyDomain,
         requestedAt: u.createdAt,
       })),
-      tpos: tpoColleges.map((c) => ({
-        collegeId: c._id,
-        collegeName: c.name,
-        domain: c.domains?.[0],
-        requestedBy: c.submittedBy
-          ? { email: c.submittedBy.email, displayName: c.submittedBy.displayName }
-          : null,
-        requestedAt: c.createdAt,
-      })),
+      tpos: await Promise.all(
+        tpoColleges.map(async (c) => {
+          const applicant = c.submittedBy
+            ? await User.findById(c.submittedBy).select("email displayName tpoVerification").lean()
+            : null;
+          const signal = applicant?.tpoVerification?.emailRoleSignal || "unknown";
+          return {
+            collegeId: c._id,
+            collegeName: c.name,
+            domains: c.domains,
+            requestedBy: applicant
+              ? { email: applicant.email, displayName: applicant.displayName }
+              : null,
+            requestedAt: applicant?.tpoVerification?.submittedAt || c.createdAt,
+            emailRoleSignal: signal,
+            verificationStatus: applicant?.tpoVerification?.status || "pending",
+            additionalEvidenceRecommended: signal !== "staff_candidate",
+            evidence: applicant?.tpoVerification?.evidence || [],
+          };
+        })
+      ),
       studentCollegeRequests: studentColleges.map((c) => ({
         collegeId: c._id,
         collegeName: c.name,
@@ -215,68 +228,57 @@ async function setCollegeStatus(collegeId, status) {
 export async function approveTpo(req, res) {
   try {
     const college = await setCollegeStatus(req.params.collegeId, "verified");
+    if (!college) return res.status(404).json({ error: "College request not found." });
 
-    if (!college) {
-      return res.status(404).json({ error: "College request not found." });
-    }
-
-    // ── First verified TPO becomes primary (Phase 3, item 5/6) ──────────
-    // This approval can verify several pending TPOs for the same domain in
-    // one bulk updateMany (anyone who registered while the college was
-    // still pending) — "first" among them is deterministic by earliest
-    // tpoProfile.requestedAt, read BEFORE the updateMany flips their
-    // verified flag (after which this same unverified-only query would
-    // match none of them). If the college already has a primary (e.g. an
-    // earlier auto-verified registration already claimed it — see
-    // routes/tpo.js's POST /register), claimPrimaryIfNone's CAS is a
-    // guaranteed no-op, so this is safe to call unconditionally rather
-    // than branching on college.primaryTpo here.
     const pendingCandidates = await User.find({
       role: "tpo",
       "tpoProfile.collegeDomain": { $in: college.domains },
       "tpoProfile.verified": false,
     })
-      .sort({ "tpoProfile.requestedAt": 1 })
-      .select("_id firebaseUid")
+      .sort({ "tpoProfile.requestedAt": 1, _id: 1 })
+      .select("_id firebaseUid email tpoVerification")
       .lean();
 
     await User.updateMany(
       { role: "tpo", "tpoProfile.collegeDomain": { $in: college.domains }, "tpoProfile.verified": false },
-      { $set: { "tpoProfile.verified": true, "tpoProfile.verifiedAt": college.verifiedAt } }
+      {
+        $set: {
+          "tpoProfile.verified": true,
+          "tpoProfile.verifiedAt": college.verifiedAt,
+          "tpoVerification.status": "approved",
+        },
+      }
     );
 
-    // TPO-1 closure fix: this bulk verification bypasses per-document
-    // save hooks (updateMany), so — unlike every other place in this file
-    // that flips a user's verified/authorization state (see
-    // approveStudentCollege below, rejectTpo, rejectRecruiter) — it never
-    // invalidated the short-lived auth cache (utils/userAuthCache.js) for
-    // the accounts it just verified. Each one would keep failing
-    // requireVerified with a stale "pending" userDoc until that cache
-    // entry's TTL expired on its own, rather than being usable
-    // immediately after approval.
     pendingCandidates.forEach((u) => invalidateCachedUserByFirebaseUid(u.firebaseUid));
 
-    // TPO-1 hardening: isolated in its own try/catch. By this point the
-    // college is verified and every pending TPO has already been bulk-
-    // verified — the core "approve this TPO application" operation has
-    // already succeeded. A transient failure in this CAS write must not
-    // make the whole approval report a 500 back to the admin (who would
-    // then have no way to know the approval itself actually went
-    // through). Falling back to "no primary claimed this round" is a
-    // safe, already-supported state (rule 4: zero primary TPOs
-    // temporarily) — recoverable via the team endpoints' admin override,
-    // or automatically on this same college's next approval/registration.
     if (pendingCandidates.length > 0) {
       try {
         await claimPrimaryIfNone(college._id, pendingCandidates[0]._id);
       } catch (err) {
-        logger.error(
-          { err, collegeId: college._id },
-          "[Admin] approveTpo: primary claim failed after successful bulk-verification — continuing"
-        );
+        logger.error({ err, collegeId: college._id }, "[Admin] approveTpo primary claim failed");
       }
     }
 
+    const reviewerId = req.actingAdminDoc?._id || req.userDoc?._id;
+    if (reviewerId) {
+      await Promise.all(
+        pendingCandidates.map((u) =>
+          TpoVerificationReview.create({
+            userId: u._id,
+            collegeId: college._id,
+            requestedEmail: u.tpoVerification?.submittedEmail || u.email || "",
+            emailRoleSignal: u.tpoVerification?.emailRoleSignal || "unknown",
+            evidence: u.tpoVerification?.evidence || [],
+            decision: "approved",
+            decisionReason: "Approved through the administrative TPO verification queue.",
+            reviewedBy: reviewerId,
+            reviewedAt: college.verifiedAt || new Date(),
+          })
+        )
+      );
+    }
+
     recordAdminAction({
       adminDoc: req.actingAdminDoc || req.userDoc,
       action: "tpo.approve",
@@ -289,33 +291,46 @@ export async function approveTpo(req, res) {
         userId: college.submittedBy,
         type: "tpo_verified",
         title: "TPO access approved",
-        message: `${college.name} is verified. Your placement dashboard is ready.`,
+        message: college.name + " is verified. Your placement dashboard is ready.",
         link: "/tpo/dashboard",
       }).catch(() => {});
     }
 
-    return res.json({ success: true });
+    return res.json({ success: true, reviewed: pendingCandidates.length });
   } catch (err) {
     logger.error({ err }, "[Admin] approve TPO error");
     return res.status(500).json({ error: "Failed to approve TPO." });
   }
 }
 
+
 // ── POST /api/admin/tpo/:collegeId/reject ───────────────────────────────────
 export async function rejectTpo(req, res) {
   try {
     const college = await College.findById(req.params.collegeId);
-
-    if (!college) {
-      return res.status(404).json({ error: "College request not found." });
-    }
+    if (!college) return res.status(404).json({ error: "College request not found." });
 
     const requesterId = college.submittedBy;
     const collegeName = college.name;
+    const requester = requesterId
+      ? await User.findById(requesterId).select("email firebaseUid role tpoVerification")
+      : null;
+
+    const reviewerId = req.actingAdminDoc?._id || req.userDoc?._id;
+    if (reviewerId && requester) {
+      await TpoVerificationReview.create({
+        userId: requester._id,
+        collegeId: college._id,
+        requestedEmail: requester.tpoVerification?.submittedEmail || requester.email || "",
+        emailRoleSignal: requester.tpoVerification?.emailRoleSignal || "unknown",
+        evidence: requester.tpoVerification?.evidence || [],
+        decision: "rejected",
+        decisionReason: "TPO request rejected through the administrative verification queue.",
+        reviewedBy: reviewerId,
+        reviewedAt: new Date(),
+      });
+    }
 
-    // Unlike student-submitted colleges (rejectStudentCollege below), a
-    // rejected TPO signup has no other purpose for the record, so the
-    // College doc itself is deleted here — unchanged from prior behavior.
     await College.deleteOne({ _id: college._id });
 
     recordAdminAction({
@@ -325,29 +340,25 @@ export async function rejectTpo(req, res) {
       targetId: college._id,
     });
 
-    if (requesterId) {
-      const user = await User.findById(requesterId);
-      if (user && user.role === "tpo") {
-        // Revoke the "tpo" authorization, matching rejectRecruiter's
-        // revokeRole above — see that comment for why.
-        user.revokeRole("tpo");
-        user.role = "student";
-        user.tpoProfile = {
-          collegeDomain: null,
-          collegeName: null,
-          verified: false,
-          requestedAt: null,
-          verifiedAt: null,
-        };
-        await user.save();
-        invalidateCachedUserByFirebaseUid(user.firebaseUid);
-      }
+    if (requester) {
+      requester.revokeRole("tpo");
+      requester.role = "student";
+      requester.tpoProfile = {
+        collegeDomain: null,
+        collegeName: null,
+        verified: false,
+        requestedAt: null,
+        verifiedAt: null,
+      };
+      requester.tpoVerification.status = "rejected";
+      await requester.save();
+      invalidateCachedUserByFirebaseUid(requester.firebaseUid);
 
       createNotification({
         userId: requesterId,
         type: "tpo_rejected",
         title: "TPO access request declined",
-        message: `We couldn't verify your request for ${collegeName}. Reach out if this was a mistake.`,
+        message: "We couldn't verify your request for " + collegeName + ". Reach out if this was a mistake.",
         link: "/tpo/signup",
       }).catch(() => {});
     }
@@ -359,6 +370,7 @@ export async function rejectTpo(req, res) {
   }
 }
 
+
 // ── POST /api/admin/student-colleges/:collegeId/approve ────────────────────
 // Approves a college that was requested via a student's college-email
 // verification (backend/routes/collegeVerification.js), as opposed to a TPO

From c846e30385e3f9f3c9b42af3ac4c160258f5cca2 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:24:45 +0530
Subject: [PATCH 07/22] test(tpo): cover tpoRoleSignalService.test.js

---
 backend/services/tpoRoleSignalService.test.js | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 backend/services/tpoRoleSignalService.test.js

diff --git a/backend/services/tpoRoleSignalService.test.js b/backend/services/tpoRoleSignalService.test.js
new file mode 100644
index 00000000..3d8760b0
--- /dev/null
+++ b/backend/services/tpoRoleSignalService.test.js
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import {
+  classifyInstitutionalEmailRole,
+  isValidRolePatternRule,
+  sanitizeRolePatternRules,
+} from "./tpoRoleSignalService.js";
+
+describe("tpoRoleSignalService", () => {
+  const college = {
+    staffEmailPatterns: [
+      { type: "domain", value: "staff.example.edu" },
+      { type: "local_prefix", values: ["staff.", "faculty."] },
+      { type: "local_regex", value: "^(dr\\.|prof)" },
+    ],
+    studentEmailPatterns: [
+      { type: "domain", value: "students.example.edu" },
+      { type: "local_prefix", values: ["student.", "22"] },
+    ],
+  };
+
+  it("classifies a configured staff domain", () => {
+    expect(classifyInstitutionalEmailRole("person@staff.example.edu", college)).toBe("staff_candidate");
+  });
+
+  it("classifies a configured student domain", () => {
+    expect(classifyInstitutionalEmailRole("person@students.example.edu", college)).toBe("student_candidate");
+  });
+
+  it("classifies a staff local prefix", () => {
+    expect(classifyInstitutionalEmailRole("faculty.person@example.edu", college)).toBe("staff_candidate");
+  });
+
+  it("returns ambiguous when both rule groups match", () => {
+    expect(classifyInstitutionalEmailRole("student.person@staff.example.edu", college)).toBe("ambiguous");
+  });
+
+  it("returns unknown for an unmatched address", () => {
+    expect(classifyInstitutionalEmailRole("person@example.edu", college)).toBe("unknown");
+  });
+
+  it("rejects unsupported and malformed rules", () => {
+    expect(isValidRolePatternRule({ type: "wat", value: "x" })).toBe(false);
+    expect(isValidRolePatternRule({ type: "domain", value: "bad domain" })).toBe(false);
+    expect(isValidRolePatternRule({ type: "local_regex", value: "[" })).toBe(false);
+  });
+
+  it("sanitizes and bounds rules", () => {
+    const rules = sanitizeRolePatternRules([
+      { type: "DOMAIN", value: "STAFF.EXAMPLE.EDU" },
+      { type: "LOCAL_PREFIX", values: ["Faculty.", ""] },
+      { type: "wat", value: "ignored" },
+    ]);
+    expect(rules).toEqual([
+      { type: "domain", value: "staff.example.edu" },
+      { type: "local_prefix", values: ["faculty."] },
+    ]);
+  });
+});

From fb714792b5563826488bfcc0ca0c83150763b599 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:24:48 +0530
Subject: [PATCH 08/22] test(tpo): cover TpoVerificationReview.test.js

---
 backend/models/TpoVerificationReview.test.js | 29 ++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 backend/models/TpoVerificationReview.test.js

diff --git a/backend/models/TpoVerificationReview.test.js b/backend/models/TpoVerificationReview.test.js
new file mode 100644
index 00000000..37be1b83
--- /dev/null
+++ b/backend/models/TpoVerificationReview.test.js
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import TpoVerificationReview from "./TpoVerificationReview.js";
+
+describe("TpoVerificationReview", () => {
+  it("requires the reviewer decision fields", () => {
+    const doc = new TpoVerificationReview({});
+    const error = doc.validateSync();
+    expect(error?.errors?.userId).toBeTruthy();
+    expect(error?.errors?.collegeId).toBeTruthy();
+    expect(error?.errors?.requestedEmail).toBeTruthy();
+    expect(error?.errors?.emailRoleSignal).toBeTruthy();
+    expect(error?.errors?.decision).toBeTruthy();
+    expect(error?.errors?.reviewedBy).toBeTruthy();
+  });
+
+  it("accepts the four advisory email classifications", () => {
+    for (const signal of ["staff_candidate", "student_candidate", "ambiguous", "unknown"]) {
+      const doc = new TpoVerificationReview({
+        userId: "507f1f77bcf86cd799439011",
+        collegeId: "507f1f77bcf86cd799439012",
+        requestedEmail: "person@example.edu",
+        emailRoleSignal: signal,
+        decision: "approved",
+        reviewedBy: "507f1f77bcf86cd799439013",
+      });
+      expect(doc.validateSync()).toBeUndefined();
+    }
+  });
+});

From b4c7006b2423c14273d5b7849c4d9f63481199f7 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:24:53 +0530
Subject: [PATCH 09/22] feat(tpo): surface verification evidence in admin queue

---
 .../admin/VerificationQueueSection.jsx           | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/src/components/admin/VerificationQueueSection.jsx b/src/components/admin/VerificationQueueSection.jsx
index 56054d2d..21a3424b 100644
--- a/src/components/admin/VerificationQueueSection.jsx
+++ b/src/components/admin/VerificationQueueSection.jsx
@@ -9,7 +9,7 @@ import ConfirmDialog from "../ui/ConfirmDialog";
 // way for the admin to undo it from here. It gets a confirmation step;
 // Approve stays one-click since a fast, low-friction "yes" is exactly
 // what a review queue should optimize for.
-function QueueRow({ title, subtitle, meta, onApprove, onReject, busy }) {
+function QueueRow({ title, subtitle, meta, signal, evidenceHint, evidence, onApprove, onReject, busy }) {
   const [confirmingReject, setConfirmingReject] = useState(false);
 
   return (
@@ -18,6 +18,17 @@ function QueueRow({ title, subtitle, meta, onApprove, onReject, busy }) {
         <p className="text-[var(--foreground)] font-semibold text-sm truncate">{title}</p>
         <p className="text-[var(--muted-foreground)] text-xs truncate">{subtitle}</p>
         {meta && <p className="text-[var(--muted-foreground)] text-[11px] mt-0.5">{meta}</p>}
+        {signal && (
+          <p className="text-[var(--muted-foreground)] text-[11px] mt-1">
+            Email signal: <span className="font-medium text-[var(--foreground)]">{signal.replaceAll("_", " ")}</span>
+            {evidenceHint ? " · additional evidence recommended" : ""}
+          </p>
+        )}
+        {Array.isArray(evidence) && evidence.length > 0 && (
+          <p className="text-[var(--muted-foreground)] text-[11px] mt-0.5">
+            Evidence: {evidence.map((item) => item.label).join(", ")}
+          </p>
+        )}
       </div>
       <div className="flex items-center gap-2 shrink-0">
         <Button
@@ -80,6 +91,9 @@ function VerificationQueueSection({ heading, loading, emptyLabel, items, busyIds
                 title={row.title}
                 subtitle={row.subtitle}
                 meta={row.meta}
+                signal={row.signal}
+                evidenceHint={row.evidenceHint}
+                evidence={row.evidence}
                 busy={busyIds[row.id]}
                 onApprove={() => onApprove(row.id)}
                 onReject={() => onReject(row.id)}

From dacc5b3b0514ba979a7b35c7ceeaa67fb6009992 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:25:05 +0530
Subject: [PATCH 10/22] feat(tpo): show role signal in verification queue

---
 src/pages/admin/AdminOverviewPage.jsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/pages/admin/AdminOverviewPage.jsx b/src/pages/admin/AdminOverviewPage.jsx
index 7f5a65f8..566bca71 100644
--- a/src/pages/admin/AdminOverviewPage.jsx
+++ b/src/pages/admin/AdminOverviewPage.jsx
@@ -87,7 +87,10 @@ export default function AdminOverviewPage() {
                 id: t.collegeId,
                 title: t.collegeName,
                 subtitle: t.requestedBy?.displayName || t.requestedBy?.email || "Unknown requester",
-                meta: `${t.domain} · requested ${formatDate(t.requestedAt)}`,
+                meta: `${(t.domains || []).join(", ")} · requested ${formatDate(t.requestedAt)}`,
+                signal: t.emailRoleSignal,
+                evidenceHint: t.additionalEvidenceRecommended,
+                evidence: t.evidence,
               })}
               onApprove={(id) => actOnTpo(id, "approve")}
               onReject={(id) => actOnTpo(id, "reject")}

From 2fb15e0c048192bb8264b0d0ad2eea6484d8e7ea Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:25:10 +0530
Subject: [PATCH 11/22] docs(tpo): document advisory role signal

---
 docs/api-contracts.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/api-contracts.md b/docs/api-contracts.md
index 37a1639d..5b37bff1 100644
--- a/docs/api-contracts.md
+++ b/docs/api-contracts.md
@@ -80,7 +80,7 @@ Mounted at `/api/tpo`. All routes return `{ enabled: false, message }` while `B2
 
 | Method | Path | Purpose |
 |---|---|---|
-| POST | `/api/tpo/register` | Convert the caller's account to a TPO account (requires an institutional email domain — rejects gmail/yahoo/outlook). |
+| POST | `/api/tpo/register` | Convert the caller's account to a TPO account (requires an institutional email domain — rejects gmail/yahoo/outlook). Captures a per-college advisory email-role signal; this signal never grants the TPO role. |
 | GET | `/api/tpo/me` | Current TPO's profile + college info. |
 | GET | `/api/tpo/college-directory` | Verified TPO directory for the authenticated student's own verified college. The server resolves the institution from the student session; no client-supplied collegeId is accepted. |
 | GET | `/api/tpo/students` | All students matched by the TPO's college email domain. |

From 23b5854d1ac8dae422a8bbac70114f33ce8b51a7 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:25:19 +0530
Subject: [PATCH 12/22] fix(tpo): resolve college before advisory role
 classification

---
 backend/routes/tpo.js | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/backend/routes/tpo.js b/backend/routes/tpo.js
index ae132928..e0af79f2 100644
--- a/backend/routes/tpo.js
+++ b/backend/routes/tpo.js
@@ -140,8 +140,10 @@ router.post("/register", async (req, res) => {
       });
     }
 
-    const emailRoleSignal = buildTpoVerificationSignal(email, collegeDoc || existingCollege || {});
-    const emailRoleClassification = emailRoleSignal.result;
+    // Role classification is advisory and must use the resolved college rules.
+    // For a new college, there are no configured staff/student patterns yet,
+    // so the classification correctly remains unknown until an admin configures them.
+    let emailRoleClassification = "unknown";
 
     // A matching student signal is deliberately not an automatic rejection:
     // people can legitimately hold multiple institutional responsibilities
@@ -149,6 +151,11 @@ router.post("/register", async (req, res) => {
     // evidence trail explicit for the reviewer.
 
     const now = new Date();
+    if (collegeDoc || existingCollege) {
+      const signal = buildTpoVerificationSignal(email, collegeDoc || existingCollege);
+      emailRoleClassification = signal.result;
+    }
+
     // Hybrid verification (Phase B): known college domains — including one
     // already verified via an earlier TPO from the same college — skip the
     // queue. Everything else is created pending and shows up in

From 5e6767ccd8cbcd4dbd6b415802a2c53b9d423bc3 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:25:32 +0530
Subject: [PATCH 13/22] fix(tpo): classify email after college resolution

---
 backend/routes/tpo.js | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/backend/routes/tpo.js b/backend/routes/tpo.js
index e0af79f2..9e78fcca 100644
--- a/backend/routes/tpo.js
+++ b/backend/routes/tpo.js
@@ -203,6 +203,14 @@ router.post("/register", async (req, res) => {
       await existingCollege.save();
     }
 
+    const signal = buildTpoVerificationSignal(email, collegeDoc || existingCollege || {});
+    emailRoleClassification = signal.result;
+
+    // A matching student signal is deliberately not an automatic rejection:
+    // people can legitimately hold multiple institutional responsibilities
+    // and local mailbox conventions are advisory. It simply makes the
+    // evidence trail explicit for the reviewer.
+
     // Mark user as TPO. Previously this dropped collegeDomain/collegeName
     // entirely — tpoProfile only ever got verificationStatus (not even a
     // real schema field) + verified + requestedAt, so every TPO's own

From cf18d9b6f68ba09143637f3fbb42415698c8c7b8 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:25:52 +0530
Subject: [PATCH 14/22] refactor(tpo): clean verification flow before final
 test

---
 backend/routes/tpo.js | 102 +-----------------------------------------
 1 file changed, 2 insertions(+), 100 deletions(-)

diff --git a/backend/routes/tpo.js b/backend/routes/tpo.js
index 9e78fcca..9ff3ec7c 100644
--- a/backend/routes/tpo.js
+++ b/backend/routes/tpo.js
@@ -110,106 +110,8 @@ router.post("/register", async (req, res) => {
       });
     }
 
-    // Advisory only: never grants or denies TPO access. The resolved college
-    // rules are applied after the College document is known below.
-
-    if (isConsumerEmailDomain(domain)) {
-      return res.status(400).json({
-        error: "Please sign up with your institutional email (e.g. yourname@college.ac.in), not a personal email.",
-      });
-    }
-
-    // A second TPO from a domain that's already verified doesn't need
-    // another manual review — the college itself has already been vetted.
-    // A domain still pending review from an earlier TPO or student stays
-    // blocked from a second claim, to avoid two conflicting requests in
-    // the queue — UNLESS the existing record is an auto-detected
-    // placeholder (submittedByRole: "auto", created the moment some
-    // student first signed up from this domain — see
-    // services/collegeAutoProvision.js). Nobody actually submitted that
-    // one; it's not a real claim to conflict with, so a TPO registering
-    // for the same domain should be able to claim/upgrade it rather than
-    // being blocked by a guess nobody reviewed.
-    const existingCollege = await College.findByDomain(domain);
-    const existingIsAutoPlaceholder = existingCollege?.submittedByRole === "auto";
-
-    if (existingCollege && existingCollege.status !== "verified" && !existingIsAutoPlaceholder) {
-      return res.status(409).json({
-        error: "This college is already registered and pending verification.",
-        status: existingCollege.status,
-      });
-    }
-
-    // Role classification is advisory and must use the resolved college rules.
-    // For a new college, there are no configured staff/student patterns yet,
-    // so the classification correctly remains unknown until an admin configures them.
-    let emailRoleClassification = "unknown";
-
-    // A matching student signal is deliberately not an automatic rejection:
-    // people can legitimately hold multiple institutional responsibilities
-    // and local mailbox conventions are advisory. It simply makes the
-    // evidence trail explicit for the reviewer.
-
-    const now = new Date();
-    if (collegeDoc || existingCollege) {
-      const signal = buildTpoVerificationSignal(email, collegeDoc || existingCollege);
-      emailRoleClassification = signal.result;
-    }
-
-    // Hybrid verification (Phase B): known college domains — including one
-    // already verified via an earlier TPO from the same college — skip the
-    // queue. Everything else is created pending and shows up in
-    // GET /api/admin/pending for manual approval.
-    const autoVerified =
-      (existingCollege?.status === "verified" && !existingIsAutoPlaceholder) ||
-      (await isDomainAutoVerified(domain, "college"));
-
-    // Tracks the resolved College doc across all three branches below
-    // (brand new / upgraded placeholder / already-verified existing) so
-    // the primary-TPO claim after it can run against a real _id in every
-    // case, not just the "created a new one" branch. Also tracks enough
-    // to roll a College-side change back if the User-side save fails
-    // right after — see the try/catch around req.userDoc.save() below.
-    let collegeDoc = existingCollege;
-    let createdNewCollege = false;
-    let placeholderSnapshot = null;
-    if (!existingCollege) {
-      collegeDoc = await College.create({
-        domains: [domain],
-        name: collegeName,
-        status: autoVerified ? "verified" : "pending",
-        verifiedAt: autoVerified ? now : null,
-        submittedBy: req.userDoc._id,
-        submittedByRole: "tpo",
-      });
-      createdNewCollege = true;
-    } else if (existingIsAutoPlaceholder) {
-      // Upgrade the auto-detected placeholder into a real TPO submission
-      // — replace the guessed name with the TPO's actual college name and
-      // record who's now vouching for it, rather than leaving a second,
-      // duplicate College doc for the same domain.
-      placeholderSnapshot = {
-        name: existingCollege.name,
-        status: existingCollege.status,
-        verifiedAt: existingCollege.verifiedAt,
-        submittedBy: existingCollege.submittedBy,
-        submittedByRole: existingCollege.submittedByRole,
-      };
-      existingCollege.name = collegeName;
-      existingCollege.status = autoVerified ? "verified" : "pending";
-      existingCollege.verifiedAt = autoVerified ? now : null;
-      existingCollege.submittedBy = req.userDoc._id;
-      existingCollege.submittedByRole = "tpo";
-      await existingCollege.save();
-    }
-
-    const signal = buildTpoVerificationSignal(email, collegeDoc || existingCollege || {});
-    emailRoleClassification = signal.result;
-
-    // A matching student signal is deliberately not an automatic rejection:
-    // people can legitimately hold multiple institutional responsibilities
-    // and local mailbox conventions are advisory. It simply makes the
-    // evidence trail explicit for the reviewer.
+    // Advisory role classification is performed after the College document
+    // is resolved, so each institution controls its own mailbox conventions.
 
     // Mark user as TPO. Previously this dropped collegeDomain/collegeName
     // entirely — tpoProfile only ever got verificationStatus (not even a

From 24fc5e648d89f4653ccf2c184a1bec805f26d238 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 13:26:03 +0530
Subject: [PATCH 15/22] fix(tpo): restore registration flow after verification
 integration

---
 backend/routes/tpo.js | 122 +++++++++++++++++++++---------------------
 1 file changed, 61 insertions(+), 61 deletions(-)

diff --git a/backend/routes/tpo.js b/backend/routes/tpo.js
index 9ff3ec7c..7e2615f0 100644
--- a/backend/routes/tpo.js
+++ b/backend/routes/tpo.js
@@ -94,46 +94,76 @@ router.post("/register", async (req, res) => {
     if (!collegeName) return res.status(400).json({ error: "collegeName is required." });
 
     if (looksLikeEmailAddress(collegeName)) {
-      // The "unnecessary box" bug class: a College record whose name is
-      // literally someone's email address, pasted into the wrong field.
-      // Reject it here instead of silently storing it.
       return res.status(400).json({
         error: "That looks like an email address — please enter your college's name instead.",
       });
     }
 
     const email = req.userDoc.email || "";
-    const domain = email.split("@")[1];
-    if (!domain) {
+    const domain = email.split("@")[1]?.toLowerCase().trim();
+    if (!domain || isConsumerEmailDomain(domain)) {
       return res.status(400).json({
-        error: "Your account does not have a valid institutional email address.",
+        error: "Please sign in with your institutional email (e.g. yourname@college.ac.in), not a personal email.",
       });
     }
 
-    // Advisory role classification is performed after the College document
-    // is resolved, so each institution controls its own mailbox conventions.
-
-    // Mark user as TPO. Previously this dropped collegeDomain/collegeName
-    // entirely — tpoProfile only ever got verificationStatus (not even a
-    // real schema field) + verified + requestedAt, so every TPO's own
-    // college identity was silently lost. Fixed here.
-    //
-    // grantRole is additive — a Student registering as TPO keeps their
-    // "student" authorization (and every student-track field: totalXP,
-    // solvedSlugs, streaks, etc. all stay untouched on this same
-    // document); only the ACTIVE role below switches to "tpo". See
-    // models/User.js's role/roles comment for why student data isn't
-    // moved or cleared here.
+    const existingCollege = await College.findByDomain(domain);
+    const existingIsAutoPlaceholder = existingCollege?.submittedByRole === "auto";
+
+    if (existingCollege && existingCollege.status !== "verified" && !existingIsAutoPlaceholder) {
+      return res.status(409).json({
+        error: "This college is already registered and pending verification.",
+        status: existingCollege.status,
+      });
+    }
+
+    const autoVerified =
+      (existingCollege?.status === "verified" && !existingIsAutoPlaceholder) ||
+      (await isDomainAutoVerified(domain, "college"));
+
+    const now = new Date();
+    let collegeDoc = existingCollege;
+    let createdNewCollege = false;
+    let placeholderSnapshot = null;
+
+    if (!existingCollege) {
+      collegeDoc = await College.create({
+        domains: [domain],
+        name: collegeName.trim(),
+        status: autoVerified ? "verified" : "pending",
+        verifiedAt: autoVerified ? now : null,
+        submittedBy: req.userDoc._id,
+        submittedByRole: "tpo",
+      });
+      createdNewCollege = true;
+    } else if (existingIsAutoPlaceholder) {
+      placeholderSnapshot = {
+        name: existingCollege.name,
+        status: existingCollege.status,
+        verifiedAt: existingCollege.verifiedAt,
+        submittedBy: existingCollege.submittedBy,
+        submittedByRole: existingCollege.submittedByRole,
+      };
+      existingCollege.name = collegeName.trim();
+      existingCollege.status = autoVerified ? "verified" : "pending";
+      existingCollege.verifiedAt = autoVerified ? now : null;
+      existingCollege.submittedBy = req.userDoc._id;
+      existingCollege.submittedByRole = "tpo";
+      await existingCollege.save();
+    }
+
+    const signal = buildTpoVerificationSignal(email, collegeDoc);
+    const emailRoleClassification = signal.result;
+
     req.userDoc.grantRole("tpo");
     req.userDoc.role = "tpo";
     req.userDoc.tpoProfile = {
       collegeDomain: domain,
-      collegeName,
+      collegeName: collegeName.trim(),
       verified: autoVerified,
       requestedAt: now,
       verifiedAt: autoVerified ? now : null,
     };
-
     req.userDoc.tpoVerification = {
       status: autoVerified ? "approved" : "pending",
       emailRoleSignal: emailRoleClassification,
@@ -143,26 +173,12 @@ router.post("/register", async (req, res) => {
         {
           kind: "email",
           label: "Institutional sign-in email",
-          reference: null,
           note: "Email ownership is established by the authenticated sign-in provider; role classification remains advisory.",
           addedAt: now,
         },
       ],
     };
 
-    // TPO-1 hardening: partial-failure handling. The College-side write
-    // above already committed by this point — if the User-side write
-    // fails now, we'd otherwise strand the domain in a half-claimed state
-    // with no valid owner (the pending-college 409 guard near the top of
-    // this handler would then permanently block every future
-    // registration attempt for this domain, since College.findByDomain
-    // would keep finding this orphaned record). Roll the College-side
-    // change back so the domain returns to its pre-request state and can
-    // be retried cleanly. Best-effort (a rollback failure is logged, not
-    // thrown over) — there is no fully atomic alternative available in
-    // this codebase (no transactions are used anywhere else either; see
-    // tpoTeamService.js's CAS-based approach for why single-document
-    // atomic operations are preferred where the invariant allows it).
     try {
       await req.userDoc.save();
     } catch (err) {
@@ -170,40 +186,23 @@ router.post("/register", async (req, res) => {
         await College.deleteOne({ _id: collegeDoc._id }).catch((rollbackErr) =>
           (req.log || logger).error(
             { err: rollbackErr, collegeId: collegeDoc._id },
-            "[TPO] register: failed to roll back newly-created College after User save failure"
+            "[TPO] register: failed to roll back newly-created College"
           )
         );
       } else if (placeholderSnapshot) {
-        await College.updateOne({ _id: collegeDoc._id }, { $set: placeholderSnapshot }).catch((rollbackErr) =>
+        await College.updateOne(
+          { _id: collegeDoc._id },
+          { $set: placeholderSnapshot }
+        ).catch((rollbackErr) =>
           (req.log || logger).error(
             { err: rollbackErr, collegeId: collegeDoc._id },
-            "[TPO] register: failed to roll back placeholder-upgrade College change after User save failure"
+            "[TPO] register: failed to roll back placeholder College"
           )
         );
       }
       throw err;
     }
 
-    // ── First verified TPO becomes primary (Phase 3, item 5) ────────────
-    // Only ever attempted here for the auto-verified path — a pending TPO
-    // isn't verified yet and can't hold primary authority (item 3/18).
-    // Pending TPOs get their shot at this when an admin later verifies
-    // their college — see adminController.js's approveTpo, which runs the
-    // same claim against whichever pending TPO registered earliest. Uses
-    // the atomic CAS in tpoTeamService.js rather than a plain "is there a
-    // primary yet?" read-then-write, so two people registering for a
-    // brand-new domain at nearly the same moment can't both become primary.
-    //
-    // TPO-1 hardening: this is deliberately isolated in its own try/catch.
-    // By this point the User doc is already saved and verified — the core
-    // "did registration succeed" outcome is already settled. A failure
-    // here (e.g. a transient DB error on the CAS write) must not make an
-    // otherwise-successful registration report as a 500 to the person
-    // registering. Falling back to isPrimary: false is always a *safe*
-    // default per the invariant (rule 4: a college can legitimately have
-    // zero primary TPOs temporarily) — it just means this particular
-    // attempt didn't claim it, recoverable later via the team endpoints
-    // or the next verified registration.
     let isPrimary = false;
     if (autoVerified && collegeDoc) {
       try {
@@ -211,7 +210,7 @@ router.post("/register", async (req, res) => {
       } catch (err) {
         (req.log || logger).error(
           { err, collegeId: collegeDoc._id, userId: req.userDoc._id },
-          "[TPO] register: primary claim failed after successful registration — continuing without primary"
+          "[TPO] register: primary claim failed after successful registration"
         );
       }
     }
@@ -225,7 +224,8 @@ router.post("/register", async (req, res) => {
       emailRoleSignal: emailRoleClassification,
       verification: {
         status: autoVerified ? "approved" : "pending",
-        additionalEvidenceRecommended: !autoVerified || emailRoleClassification !== "staff_candidate",
+        additionalEvidenceRecommended:
+          emailRoleClassification !== "staff_candidate",
       },
       message: autoVerified
         ? "Your college is verified. You're all set — head to your dashboard."

From fdaea0ab7654d31d634860df556ac21e36dbf1a8 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 15:51:41 +0530
Subject: [PATCH 16/22] fix(tpo): preserve valid local role pattern rules

---
 backend/services/tpoRoleSignalService.js | 55 ++++++++++++++++--------
 1 file changed, 36 insertions(+), 19 deletions(-)

diff --git a/backend/services/tpoRoleSignalService.js b/backend/services/tpoRoleSignalService.js
index bce7e1bc..77becf24 100644
--- a/backend/services/tpoRoleSignalService.js
+++ b/backend/services/tpoRoleSignalService.js
@@ -139,23 +139,40 @@ export function isValidRolePatternRule(rule) {
 
 export function sanitizeRolePatternRules(rules) {
   if (!Array.isArray(rules)) return [];
-  return rules
-    .slice(0, MAX_RULES)
-    .filter(isValidRolePatternRule)
-    .map((rule) => {
-      const type = String(rule.type).toLowerCase().trim();
-      if (type === "domain") {
-        return { type, value: rule.value.toLowerCase().trim() };
-      }
-      if (type === "local_prefix") {
-        return {
-          type,
-          values: rule.values
-            .map((value) => value.toLowerCase().trim())
-            .filter(Boolean)
-            .slice(0, MAX_RULES),
-        };
-      }
-      return { type, value: rule.value };
-    });
+
+  const sanitized = [];
+
+  for (const rule of rules.slice(0, MAX_RULES)) {
+    if (!isValidRolePatternRule(rule)) continue;
+
+    const type = String(rule.type || "").toLowerCase().trim();
+
+    if (type === "domain") {
+      sanitized.push({
+        type,
+        value: rule.value.toLowerCase().trim(),
+      });
+      continue;
+    }
+
+    if (type === "local_prefix") {
+      sanitized.push({
+        type,
+        values: rule.values
+          .map((value) => value.toLowerCase().trim())
+          .filter(Boolean)
+          .slice(0, MAX_RULES),
+      });
+      continue;
+    }
+
+    if (type === "local_regex") {
+      sanitized.push({
+        type,
+        value: rule.value,
+      });
+    }
+  }
+
+  return sanitized;
 }

From 5d4838e3fec79cef848f81d7a4fe447f105e3080 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 15:51:53 +0530
Subject: [PATCH 17/22] fix(tpo): keep existing admin queue behavior and
 isolate audit failures

---
 backend/controllers/adminController.js | 120 +++++++++++++++----------
 1 file changed, 71 insertions(+), 49 deletions(-)

diff --git a/backend/controllers/adminController.js b/backend/controllers/adminController.js
index 0f83a276..28eb4b88 100644
--- a/backend/controllers/adminController.js
+++ b/backend/controllers/adminController.js
@@ -54,7 +54,7 @@ export async function getPendingQueue(req, res) {
       // same collection and split below by submittedByRole so the queue
       // can render/label them separately.
       College.find({ status: "pending" })
-        .populate("submittedBy", "email displayName")
+        .populate("submittedBy", "email displayName tpoVerification")
         .sort({ createdAt: 1 })
         .lean(),
     ]);
@@ -80,27 +80,28 @@ export async function getPendingQueue(req, res) {
         companyDomain: u.recruiterProfile?.companyDomain,
         requestedAt: u.createdAt,
       })),
-      tpos: await Promise.all(
-        tpoColleges.map(async (c) => {
-          const applicant = c.submittedBy
-            ? await User.findById(c.submittedBy).select("email displayName tpoVerification").lean()
-            : null;
-          const signal = applicant?.tpoVerification?.emailRoleSignal || "unknown";
-          return {
-            collegeId: c._id,
-            collegeName: c.name,
-            domains: c.domains,
-            requestedBy: applicant
-              ? { email: applicant.email, displayName: applicant.displayName }
-              : null,
-            requestedAt: applicant?.tpoVerification?.submittedAt || c.createdAt,
-            emailRoleSignal: signal,
-            verificationStatus: applicant?.tpoVerification?.status || "pending",
-            additionalEvidenceRecommended: signal !== "staff_candidate",
-            evidence: applicant?.tpoVerification?.evidence || [],
-          };
-        })
-      ),
+      tpos: tpoColleges.map((c) => {
+        const applicant = c.submittedBy && typeof c.submittedBy === "object"
+          ? c.submittedBy
+          : null;
+        const signal = applicant?.tpoVerification?.emailRoleSignal || "unknown";
+        return {
+          collegeId: c._id,
+          collegeName: c.name,
+          // Keep the legacy first-domain field for existing admin clients while
+          // exposing the complete configured domain list.
+          domain: c.domains?.[0],
+          domains: c.domains,
+          requestedBy: applicant
+            ? { email: applicant.email, displayName: applicant.displayName }
+            : null,
+          requestedAt: applicant?.tpoVerification?.submittedAt || c.createdAt,
+          emailRoleSignal: signal,
+          verificationStatus: applicant?.tpoVerification?.status || "pending",
+          additionalEvidenceRecommended: signal !== "staff_candidate",
+          evidence: applicant?.tpoVerification?.evidence || [],
+        };
+      }),
       studentCollegeRequests: studentColleges.map((c) => ({
         collegeId: c._id,
         collegeName: c.name,
@@ -262,21 +263,28 @@ export async function approveTpo(req, res) {
 
     const reviewerId = req.actingAdminDoc?._id || req.userDoc?._id;
     if (reviewerId) {
-      await Promise.all(
-        pendingCandidates.map((u) =>
-          TpoVerificationReview.create({
-            userId: u._id,
-            collegeId: college._id,
-            requestedEmail: u.tpoVerification?.submittedEmail || u.email || "",
-            emailRoleSignal: u.tpoVerification?.emailRoleSignal || "unknown",
-            evidence: u.tpoVerification?.evidence || [],
-            decision: "approved",
-            decisionReason: "Approved through the administrative TPO verification queue.",
-            reviewedBy: reviewerId,
-            reviewedAt: college.verifiedAt || new Date(),
-          })
-        )
-      );
+      try {
+        await Promise.all(
+          pendingCandidates.map((u) =>
+            TpoVerificationReview.create({
+              userId: u._id,
+              collegeId: college._id,
+              requestedEmail: u.tpoVerification?.submittedEmail || u.email || "",
+              emailRoleSignal: u.tpoVerification?.emailRoleSignal || "unknown",
+              evidence: u.tpoVerification?.evidence || [],
+              decision: "approved",
+              decisionReason: "Approved through the administrative TPO verification queue.",
+              reviewedBy: reviewerId,
+              reviewedAt: college.verifiedAt || new Date(),
+            })
+          )
+        );
+      } catch (err) {
+        logger.error(
+          { err, collegeId: college._id },
+          "[Admin] approveTpo: failed to persist verification review audit"
+        );
+      }
     }
 
     recordAdminAction({
@@ -318,17 +326,24 @@ export async function rejectTpo(req, res) {
 
     const reviewerId = req.actingAdminDoc?._id || req.userDoc?._id;
     if (reviewerId && requester) {
-      await TpoVerificationReview.create({
-        userId: requester._id,
-        collegeId: college._id,
-        requestedEmail: requester.tpoVerification?.submittedEmail || requester.email || "",
-        emailRoleSignal: requester.tpoVerification?.emailRoleSignal || "unknown",
-        evidence: requester.tpoVerification?.evidence || [],
-        decision: "rejected",
-        decisionReason: "TPO request rejected through the administrative verification queue.",
-        reviewedBy: reviewerId,
-        reviewedAt: new Date(),
-      });
+      try {
+        await TpoVerificationReview.create({
+          userId: requester._id,
+          collegeId: college._id,
+          requestedEmail: requester.tpoVerification?.submittedEmail || requester.email || "",
+          emailRoleSignal: requester.tpoVerification?.emailRoleSignal || "unknown",
+          evidence: requester.tpoVerification?.evidence || [],
+          decision: "rejected",
+          decisionReason: "TPO request rejected through the administrative verification queue.",
+          reviewedBy: reviewerId,
+          reviewedAt: new Date(),
+        });
+      } catch (err) {
+        logger.error(
+          { err, collegeId: college._id },
+          "[Admin] rejectTpo: failed to persist verification review audit"
+        );
+      }
     }
 
     await College.deleteOne({ _id: college._id });
@@ -350,7 +365,14 @@ export async function rejectTpo(req, res) {
         requestedAt: null,
         verifiedAt: null,
       };
-      requester.tpoVerification.status = "rejected";
+      requester.tpoVerification = {
+        ...(requester.tpoVerification || {}),
+        status: "rejected",
+        emailRoleSignal: requester.tpoVerification?.emailRoleSignal || "unknown",
+        submittedEmail: requester.tpoVerification?.submittedEmail || requester.email || null,
+        submittedAt: requester.tpoVerification?.submittedAt || null,
+        evidence: requester.tpoVerification?.evidence || [],
+      };
       await requester.save();
       invalidateCachedUserByFirebaseUid(requester.firebaseUid);
 

From 88d01eb6649e9f0985d1b5a3f7b23653ba728125 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 15:51:59 +0530
Subject: [PATCH 18/22] chore(tpo): preserve core admin decisions when audit
 write is unavailable


From f59af2fe01cf450a848f2943d164bec48fff271f Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 15:56:44 +0530
Subject: [PATCH 19/22] fix: preserve TPO admin response and rejection
 semantics

---
 backend/controllers/adminController.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/backend/controllers/adminController.js b/backend/controllers/adminController.js
index 28eb4b88..8b3b8e18 100644
--- a/backend/controllers/adminController.js
+++ b/backend/controllers/adminController.js
@@ -304,7 +304,7 @@ export async function approveTpo(req, res) {
       }).catch(() => {});
     }
 
-    return res.json({ success: true, reviewed: pendingCandidates.length });
+    return res.json({ success: true });
   } catch (err) {
     logger.error({ err }, "[Admin] approve TPO error");
     return res.status(500).json({ error: "Failed to approve TPO." });
@@ -321,7 +321,7 @@ export async function rejectTpo(req, res) {
     const requesterId = college.submittedBy;
     const collegeName = college.name;
     const requester = requesterId
-      ? await User.findById(requesterId).select("email firebaseUid role tpoVerification")
+      ? await User.findById(requesterId)
       : null;
 
     const reviewerId = req.actingAdminDoc?._id || req.userDoc?._id;
@@ -355,7 +355,7 @@ export async function rejectTpo(req, res) {
       targetId: college._id,
     });
 
-    if (requester) {
+    if (requester && requester.role === "tpo") {
       requester.revokeRole("tpo");
       requester.role = "student";
       requester.tpoProfile = {

From ee7a9642b975f9a2b1dce1bfedcffb2f3fd47c92 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 15:56:49 +0530
Subject: [PATCH 20/22] fix: sanitize empty local-prefix entries

---
 backend/services/tpoRoleSignalService.js | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/backend/services/tpoRoleSignalService.js b/backend/services/tpoRoleSignalService.js
index 77becf24..1587dcbc 100644
--- a/backend/services/tpoRoleSignalService.js
+++ b/backend/services/tpoRoleSignalService.js
@@ -156,13 +156,18 @@ export function sanitizeRolePatternRules(rules) {
     }
 
     if (type === "local_prefix") {
-      sanitized.push({
-        type,
-        values: rule.values
-          .map((value) => value.toLowerCase().trim())
-          .filter(Boolean)
-          .slice(0, MAX_RULES),
-      });
+      // Empty prefix entries are harmless configuration noise and should be
+      // removed during sanitization rather than invalidating the entire rule.
+      // Validation stays strict for callers that validate an unsanitized rule.
+      const values = rule.values
+        .filter((value) => typeof value === "string")
+        .map((value) => value.toLowerCase().trim())
+        .filter(Boolean)
+        .slice(0, MAX_RULES);
+
+      if (values.length === 0) continue;
+
+      sanitized.push({ type, values });
       continue;
     }
 

From 1604b3f196e8a53ac264f7f5358bb804ba9fe972 Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 15:56:56 +0530
Subject: [PATCH 21/22] test: cover TPO review audit and rejection safety

---
 backend/controllers/adminController.test.js | 34 +++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/backend/controllers/adminController.test.js b/backend/controllers/adminController.test.js
index 347e9e20..ec5a3b85 100644
--- a/backend/controllers/adminController.test.js
+++ b/backend/controllers/adminController.test.js
@@ -1,5 +1,8 @@
 import { describe, expect, it, vi, beforeEach } from "vitest";
 
+vi.mock("../models/TpoVerificationReview.js", () => ({
+    default: { create: vi.fn().mockResolvedValue({}) },
+}));
 vi.mock("../models/College.js", () => ({
     default: {
         find: vi.fn(),
@@ -50,6 +53,7 @@ vi.mock("../config/logger.js", () => ({
     logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
 }));
 
+import TpoVerificationReview from "../models/TpoVerificationReview.js";
 import College from "../models/College.js";
 import User from "../models/User.js";
 import ImpersonationLog from "../models/ImpersonationLog.js";
@@ -274,6 +278,14 @@ describe("adminController", () => {
             expect(createNotification).toHaveBeenCalledWith(
                 expect.objectContaining({ userId: "admin-user-1", type: "tpo_verified" })
             );
+            expect(TpoVerificationReview.create).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    userId: "req1",
+                    collegeId: "c1",
+                    decision: "approved",
+                    reviewedBy: "admin1",
+                })
+            );
             expect(res.json).toHaveBeenCalledWith({ success: true });
         });
 
@@ -414,6 +426,28 @@ describe("adminController", () => {
             expect(recordAdminAction).toHaveBeenCalledWith(
                 expect.objectContaining({ adminDoc: admin, action: "tpo.reject", targetType: "College", targetId: "c1" })
             );
+            expect(TpoVerificationReview.create).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    userId: "req1",
+                    collegeId: "c1",
+                    decision: "rejected",
+                    reviewedBy: "admin1",
+                })
+            );
+            expect(res.json).toHaveBeenCalledWith({ success: true });
+        });
+
+        it("does not demote a requester who is no longer a TPO", async () => {
+            const college = { _id: "c1", name: "MIT", submittedBy: "req1" };
+            const requester = makeUser({ _id: "req1", role: "student", roles: ["student"], firebaseUid: "fb-req1" });
+            College.findById.mockResolvedValueOnce(college);
+            User.findById.mockResolvedValueOnce(requester);
+
+            await rejectTpo({ params: { collegeId: "c1" }, userDoc: makeAdmin(), actingAdminDoc: null }, res);
+
+            expect(College.deleteOne).toHaveBeenCalledWith({ _id: "c1" });
+            expect(requester.save).not.toHaveBeenCalled();
+            expect(invalidateCachedUserByFirebaseUid).not.toHaveBeenCalled();
             expect(res.json).toHaveBeenCalledWith({ success: true });
         });
     });

From a44e493b3ed435ebb98168b57c720cf35f614b8b Mon Sep 17 00:00:00 2001
From: Shiva Shankara Vara Prasad <ssvp006@gmail.com>
Date: Sat, 26 Sep 2026 15:58:07 +0530
Subject: [PATCH 22/22] fix: normalize prefixes before validation

---
 backend/services/tpoRoleSignalService.js | 39 +++++++++++++-----------
 1 file changed, 22 insertions(+), 17 deletions(-)

diff --git a/backend/services/tpoRoleSignalService.js b/backend/services/tpoRoleSignalService.js
index 1587dcbc..40e2cf76 100644
--- a/backend/services/tpoRoleSignalService.js
+++ b/backend/services/tpoRoleSignalService.js
@@ -143,10 +143,31 @@ export function sanitizeRolePatternRules(rules) {
   const sanitized = [];
 
   for (const rule of rules.slice(0, MAX_RULES)) {
-    if (!isValidRolePatternRule(rule)) continue;
+    if (!rule || typeof rule !== "object") continue;
 
     const type = String(rule.type || "").toLowerCase().trim();
 
+    if (type === "local_prefix") {
+      // Sanitization intentionally removes empty entries before validation.
+      // An otherwise valid rule such as ["faculty.", ""] must remain usable;
+      // the empty string is configuration noise, not a reason to discard the
+      // whole rule.
+      const values = Array.isArray(rule.values)
+        ? rule.values
+            .filter((value) => typeof value === "string")
+            .map((value) => value.toLowerCase().trim())
+            .filter(Boolean)
+            .slice(0, MAX_RULES)
+        : [];
+
+      if (!isValidRolePatternRule({ type, values })) continue;
+
+      sanitized.push({ type, values });
+      continue;
+    }
+
+    if (!isValidRolePatternRule(rule)) continue;
+
     if (type === "domain") {
       sanitized.push({
         type,
@@ -155,22 +176,6 @@ export function sanitizeRolePatternRules(rules) {
       continue;
     }
 
-    if (type === "local_prefix") {
-      // Empty prefix entries are harmless configuration noise and should be
-      // removed during sanitization rather than invalidating the entire rule.
-      // Validation stays strict for callers that validate an unsanitized rule.
-      const values = rule.values
-        .filter((value) => typeof value === "string")
-        .map((value) => value.toLowerCase().trim())
-        .filter(Boolean)
-        .slice(0, MAX_RULES);
-
-      if (values.length === 0) continue;
-
-      sanitized.push({ type, values });
-      continue;
-    }
-
     if (type === "local_regex") {
       sanitized.push({
         type,