From ee7d6adbf6ca728223d93ba48d67f9f5756a2380 Mon Sep 17 00:00:00 2001
From: ummaraali2 <syeda.umm@northeastern.edu>
Date: Fri, 12 Jun 2026 17:32:22 -0400
Subject: [PATCH 1/3] Add professional auth, display names, and brand assets.

OAuth sign-in (ORCID/Google/GitHub), email verification for local accounts,
display_name in profiles, logo + auth UI, and contributor testing docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 client-next/public/logo-mark.svg              |   5 +
 client-next/public/logo.svg                   |   7 +
 client-next/src/app/auth/complete/page.js     | 129 +++++
 .../src/app/auth/github/callback/page.js      |  63 +++
 .../src/app/auth/google/callback/page.js      |  67 +++
 client-next/src/app/forgot-password/page.js   |  88 ++--
 client-next/src/app/icon.svg                  |   5 +
 client-next/src/app/login/Auth.module.css     | 209 +++++++-
 client-next/src/app/login/page.js             |  86 ++--
 client-next/src/app/orcid/callback/page.js    |  46 +-
 client-next/src/app/register/page.js          | 163 +++---
 client-next/src/app/reset-password/page.js    |  98 ++--
 .../src/app/settings/Settings.module.css      |   9 +
 client-next/src/app/settings/page.js          |  22 +
 .../src/app/u/[username]/Profile.module.css   |   6 +
 .../src/app/u/[username]/ProfileClient.jsx    |  16 +-
 client-next/src/app/verify-email/page.js      | 118 +++++
 client-next/src/components/AuthLayout.jsx     |  84 ++++
 client-next/src/components/Comment.jsx        |   6 +-
 client-next/src/components/FeedCard.jsx       |   7 +-
 client-next/src/components/Layout.jsx         |   2 +
 client-next/src/components/Logo.jsx           |  56 +++
 client-next/src/components/Logo.module.css    |  34 ++
 client-next/src/components/Nav.jsx            |   5 +-
 client-next/src/components/PasswordInput.jsx  |  45 ++
 .../src/components/VerifyEmailBanner.jsx      |  36 ++
 .../components/VerifyEmailBanner.module.css   |  23 +
 client-next/src/lib/api.js                    |   1 +
 docs/DEVELOPER_NOTES.md                       |  33 +-
 docs/TESTING.md                               | 153 ++++++
 server/.env.example                           |   8 +
 .../migrations/021_oauth_and_verification.sql |  24 +
 server/db/migrations/022_display_name.sql     |   1 +
 server/index.js                               |   3 +
 server/lib/oauthUsers.js                      |  46 ++
 server/lib/session.js                         |  61 +++
 server/middleware/requireVerifiedEmail.js     |  37 ++
 server/routes/auth.js                         | 471 ++++++++++--------
 server/routes/discussions.js                  |  23 +-
 server/routes/explore.js                      |   2 +
 server/routes/github.js                       | 121 +++++
 server/routes/google.js                       | 148 ++++++
 server/routes/orcid.js                        | 305 ++++++------
 server/routes/search.js                       |   3 +-
 server/routes/users.js                        |  16 +-
 server/tests/auth-verify.test.js              | 133 +++++
 server/tests/auth.test.js                     |   1 +
 server/tests/helpers.js                       |  13 +
 server/tests/papers.test.js                   |   2 +
 server/tests/social.test.js                   |   4 +
 50 files changed, 2426 insertions(+), 618 deletions(-)
 create mode 100644 client-next/public/logo-mark.svg
 create mode 100644 client-next/public/logo.svg
 create mode 100644 client-next/src/app/auth/complete/page.js
 create mode 100644 client-next/src/app/auth/github/callback/page.js
 create mode 100644 client-next/src/app/auth/google/callback/page.js
 create mode 100644 client-next/src/app/icon.svg
 create mode 100644 client-next/src/app/verify-email/page.js
 create mode 100644 client-next/src/components/AuthLayout.jsx
 create mode 100644 client-next/src/components/Logo.jsx
 create mode 100644 client-next/src/components/Logo.module.css
 create mode 100644 client-next/src/components/PasswordInput.jsx
 create mode 100644 client-next/src/components/VerifyEmailBanner.jsx
 create mode 100644 client-next/src/components/VerifyEmailBanner.module.css
 create mode 100644 docs/TESTING.md
 create mode 100644 server/db/migrations/021_oauth_and_verification.sql
 create mode 100644 server/db/migrations/022_display_name.sql
 create mode 100644 server/lib/oauthUsers.js
 create mode 100644 server/lib/session.js
 create mode 100644 server/middleware/requireVerifiedEmail.js
 create mode 100644 server/routes/github.js
 create mode 100644 server/routes/google.js
 create mode 100644 server/tests/auth-verify.test.js
 create mode 100644 server/tests/helpers.js

diff --git a/client-next/public/logo-mark.svg b/client-next/public/logo-mark.svg
new file mode 100644
index 0000000..cfbeb7c
--- /dev/null
+++ b/client-next/public/logo-mark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <path d="M9 8c0-1.5 1.2-2.5 2.8-2.5 1.4 0 2.5.8 2.8 2" stroke="#1C1917" stroke-width="2.2" stroke-linecap="round"/>
+  <path d="M8 12c2.5-1 5.5-1 8 0 2.5 1 4.5 3 6 5.5" stroke="#8B4F4F" stroke-width="2.2" stroke-linecap="round"/>
+  <path d="M22 18.5h6M25 15.5v6" stroke="#8B4F4F" stroke-width="2" stroke-linecap="round"/>
+</svg>
diff --git a/client-next/public/logo.svg b/client-next/public/logo.svg
new file mode 100644
index 0000000..0d67caf
--- /dev/null
+++ b/client-next/public/logo.svg
@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 32" fill="none">
+  <path d="M9 8c0-1.5 1.2-2.5 2.8-2.5 1.4 0 2.5.8 2.8 2" stroke="#1C1917" stroke-width="2.2" stroke-linecap="round"/>
+  <path d="M8 12c2.5-1 5.5-1 8 0 2.5 1 4.5 3 6 5.5" stroke="#8B4F4F" stroke-width="2.2" stroke-linecap="round"/>
+  <path d="M22 18.5h6M25 15.5v6" stroke="#8B4F4F" stroke-width="2" stroke-linecap="round"/>
+  <text x="38" y="22" font-family="Georgia, 'IBM Plex Serif', serif" font-size="18" font-weight="600" fill="#1C1917">Post</text>
+  <text x="78" y="22" font-family="system-ui, 'Source Sans 3', sans-serif" font-size="18" font-weight="600" fill="#8B4F4F">Scholar</text>
+</svg>
diff --git a/client-next/src/app/auth/complete/page.js b/client-next/src/app/auth/complete/page.js
new file mode 100644
index 0000000..94fe25a
--- /dev/null
+++ b/client-next/src/app/auth/complete/page.js
@@ -0,0 +1,129 @@
+'use client'
+
+import { Suspense, useEffect, useState } from 'react'
+import { useSearchParams, useRouter } from 'next/navigation'
+import Link from 'next/link'
+import { getApiUrl } from '@/lib/config'
+import { useAuth } from '@/context/AuthContext'
+import Logo from '@/components/Logo'
+import { AuthBrandPanel } from '@/components/AuthLayout'
+import styles from '../../login/Auth.module.css'
+
+const USERNAME_REGEX = /^[a-z0-9_]{3,30}$/
+
+function AuthCompleteInner() {
+  const searchParams = useSearchParams()
+  const router = useRouter()
+  const { refreshUser } = useAuth()
+  const [username, setUsername] = useState('')
+  const [displayName, setDisplayName] = useState('')
+  const [error, setError] = useState(null)
+  const [loading, setLoading] = useState(false)
+
+  const token = searchParams.get('token')
+  const prefilledName = searchParams.get('name')
+
+  useEffect(() => {
+    if (prefilledName) setDisplayName(prefilledName)
+  }, [prefilledName])
+
+  if (!token) {
+    return (
+      <div className={styles.page}>
+        <div className={styles.formPanel} style={{ width: '100%' }}>
+          <div className={styles.card}>
+            <p className={styles.error}>Missing completion token. Please sign in with ORCID again.</p>
+            <p className={styles.switchLink}><Link href="/login">Back to sign in</Link></p>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  async function handleSubmit(e) {
+    e.preventDefault()
+    setError(null)
+
+    if (!USERNAME_REGEX.test(username)) {
+      setError('Username must be 3–30 characters: lowercase letters, numbers, underscores')
+      return
+    }
+
+    setLoading(true)
+    try {
+      const res = await fetch(`${getApiUrl()}/auth/complete`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify({
+          token,
+          username,
+          display_name: displayName || undefined,
+        }),
+      })
+      const data = await res.json()
+      if (!res.ok) throw new Error(data.error || 'Could not complete signup')
+      await refreshUser()
+      router.push('/')
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className={styles.page}>
+      <AuthBrandPanel />
+      <div className={styles.formPanel}>
+        <div className={styles.card}>
+          <div className={styles.header}>
+            <Logo variant="full" href="/" className={styles.mobileLogo} />
+            <h1 className={styles.title}>Complete your profile</h1>
+            <p className={styles.subtitle}>Choose a username for your ORCID account</p>
+          </div>
+
+          <form className={styles.form} onSubmit={handleSubmit}>
+            <div className={styles.field}>
+              <label className={styles.label} htmlFor="display_name">Display name</label>
+              <p className={styles.hint}>Optional — how your name appears on comments</p>
+              <input
+                className={styles.input}
+                id="display_name"
+                value={displayName}
+                onChange={e => setDisplayName(e.target.value)}
+                maxLength={50}
+              />
+            </div>
+
+            <div className={styles.field}>
+              <label className={styles.label} htmlFor="username">Username</label>
+              <p className={styles.hint}>Used in your profile URL and @mentions</p>
+              <input
+                className={styles.input}
+                id="username"
+                value={username}
+                onChange={e => setUsername(e.target.value.toLowerCase())}
+                required
+              />
+            </div>
+
+            {error && <p className={styles.error}>{error}</p>}
+
+            <button className={styles.submitBtn} type="submit" disabled={loading}>
+              {loading ? 'Creating account…' : 'Continue'}
+            </button>
+          </form>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default function AuthCompletePage() {
+  return (
+    <Suspense fallback={<div className={styles.page} />}>
+      <AuthCompleteInner />
+    </Suspense>
+  )
+}
diff --git a/client-next/src/app/auth/github/callback/page.js b/client-next/src/app/auth/github/callback/page.js
new file mode 100644
index 0000000..3613304
--- /dev/null
+++ b/client-next/src/app/auth/github/callback/page.js
@@ -0,0 +1,63 @@
+'use client'
+
+import { Suspense, useEffect, useState } from 'react'
+import { useSearchParams, useRouter } from 'next/navigation'
+import { getApiUrl } from '@/lib/config'
+import { useAuth } from '@/context/AuthContext'
+import styles from '../../../login/Auth.module.css'
+
+function GitHubCallbackInner() {
+  const searchParams = useSearchParams()
+  const router = useRouter()
+  const { refreshUser } = useAuth()
+  const [message, setMessage] = useState('Signing in with GitHub…')
+
+  useEffect(() => {
+    const code = searchParams.get('code')
+    const state = searchParams.get('state')
+    if (!code || !state) {
+      setMessage('Invalid callback — missing code or state.')
+      return
+    }
+
+    async function exchange() {
+      try {
+        const res = await fetch(`${getApiUrl()}/auth/github/callback`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          credentials: 'include',
+          body: JSON.stringify({ code, state }),
+        })
+        const data = await res.json()
+        if (!res.ok) {
+          setMessage(data.error || 'Sign-in failed')
+          return
+        }
+        await refreshUser()
+        router.push('/')
+      } catch {
+        setMessage('Failed to reach server')
+      }
+    }
+
+    exchange()
+  }, [searchParams, router, refreshUser])
+
+  return (
+    <div className={styles.page}>
+      <div className={styles.formPanel} style={{ width: '100%' }}>
+        <div className={styles.card}>
+          <p className={styles.subtitle}>{message}</p>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default function GitHubCallbackPage() {
+  return (
+    <Suspense fallback={<div className={styles.page} />}>
+      <GitHubCallbackInner />
+    </Suspense>
+  )
+}
diff --git a/client-next/src/app/auth/google/callback/page.js b/client-next/src/app/auth/google/callback/page.js
new file mode 100644
index 0000000..8ad9d13
--- /dev/null
+++ b/client-next/src/app/auth/google/callback/page.js
@@ -0,0 +1,67 @@
+'use client'
+
+import { Suspense, useEffect, useState } from 'react'
+import { useSearchParams, useRouter } from 'next/navigation'
+import { getApiUrl } from '@/lib/config'
+import { useAuth } from '@/context/AuthContext'
+import styles from '../../../login/Auth.module.css'
+
+function OAuthCallback({ provider, endpoint }) {
+  const searchParams = useSearchParams()
+  const router = useRouter()
+  const { refreshUser } = useAuth()
+  const [message, setMessage] = useState(`Signing in with ${provider}…`)
+
+  useEffect(() => {
+    const code = searchParams.get('code')
+    const state = searchParams.get('state')
+    if (!code || !state) {
+      setMessage('Invalid callback — missing code or state.')
+      return
+    }
+
+    async function exchange() {
+      try {
+        const res = await fetch(`${getApiUrl()}${endpoint}`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          credentials: 'include',
+          body: JSON.stringify({ code, state }),
+        })
+        const data = await res.json()
+        if (!res.ok) {
+          setMessage(data.error || 'Sign-in failed')
+          return
+        }
+        await refreshUser()
+        router.push('/')
+      } catch {
+        setMessage('Failed to reach server')
+      }
+    }
+
+    exchange()
+  }, [searchParams, router, refreshUser, endpoint])
+
+  return (
+    <div className={styles.page}>
+      <div className={styles.formPanel} style={{ width: '100%' }}>
+        <div className={styles.card}>
+          <p className={styles.subtitle}>{message}</p>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function GoogleCallbackInner() {
+  return <OAuthCallback provider="Google" endpoint="/auth/google/callback" />
+}
+
+export default function GoogleCallbackPage() {
+  return (
+    <Suspense fallback={<div className={styles.page} />}>
+      <GoogleCallbackInner />
+    </Suspense>
+  )
+}
diff --git a/client-next/src/app/forgot-password/page.js b/client-next/src/app/forgot-password/page.js
index 8560b2a..be4daf6 100644
--- a/client-next/src/app/forgot-password/page.js
+++ b/client-next/src/app/forgot-password/page.js
@@ -3,13 +3,10 @@
 import { useState } from 'react'
 import Link from 'next/link'
 import { getApiUrl } from '@/lib/config'
-import styles from './Auth.module.css'
+import Logo from '@/components/Logo'
+import { AuthBrandPanel } from '@/components/AuthLayout'
+import styles from '../login/Auth.module.css'
 
-/**
- * Forgot password page — /forgot-password
- * Submits email to POST /auth/forgot-password.
- * Always shows success message to prevent user enumeration.
- */
 export default function ForgotPassword() {
   const [email, setEmail] = useState('')
   const [submitted, setSubmitted] = useState(false)
@@ -24,7 +21,7 @@ export default function ForgotPassword() {
       const res = await fetch(`${getApiUrl()}/auth/forgot-password`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ email })
+        body: JSON.stringify({ email }),
       })
       const data = await res.json()
       if (!res.ok) {
@@ -41,50 +38,45 @@ export default function ForgotPassword() {
 
   return (
     <div className={styles.page}>
-      <div className={styles.card}>
-        <div className={styles.header}>
-          <Link href="/" className={styles.wordmark}>PostScholar</Link>
-          <h1 className={styles.title}>Reset password</h1>
-          <p className={styles.subtitle}>
-            Enter your email and we'll send a reset link.
-          </p>
-        </div>
-
-        {submitted ? (
-          <div className={styles.successBox}>
-            If that email exists, a reset link has been sent. Check your inbox.
+      <AuthBrandPanel />
+      <div className={styles.formPanel}>
+        <div className={styles.card}>
+          <div className={styles.header}>
+            <Logo variant="full" href="/" className={styles.mobileLogo} />
+            <h1 className={styles.title}>Reset password</h1>
+            <p className={styles.subtitle}>Enter your email and we&apos;ll send a reset link.</p>
           </div>
-        ) : (
-          <form className={styles.form} onSubmit={handleSubmit}>
-            <div className={styles.field}>
-              <label className={styles.label} htmlFor="email">Email</label>
-              <input
-                className={styles.input}
-                id="email"
-                type="email"
-                required
-                value={email}
-                onChange={e => setEmail(e.target.value)}
-                autoComplete="email"
-              />
-            </div>
 
-            {error && <p className={styles.error}>{error}</p>}
-
-            <button
-              className={styles.submitBtn}
-              type="submit"
-              disabled={loading}
-            >
-              {loading ? 'Sending...' : 'Send reset link'}
-            </button>
-          </form>
-        )}
+          {submitted ? (
+            <div className={styles.successBox}>
+              If that email exists, a reset link has been sent. Check your inbox.
+            </div>
+          ) : (
+            <form className={styles.form} onSubmit={handleSubmit}>
+              <div className={styles.field}>
+                <label className={styles.label} htmlFor="email">Email</label>
+                <input
+                  className={styles.input}
+                  id="email"
+                  type="email"
+                  required
+                  value={email}
+                  onChange={e => setEmail(e.target.value)}
+                  autoComplete="email"
+                />
+              </div>
+              {error && <p className={styles.error}>{error}</p>}
+              <button className={styles.submitBtn} type="submit" disabled={loading}>
+                {loading ? 'Sending…' : 'Send reset link'}
+              </button>
+            </form>
+          )}
 
-        <p className={styles.switchLink}>
-          <Link href="/login">Back to sign in</Link>
-        </p>
+          <p className={styles.switchLink}>
+            <Link href="/login">Back to sign in</Link>
+          </p>
+        </div>
       </div>
     </div>
   )
-}
\ No newline at end of file
+}
diff --git a/client-next/src/app/icon.svg b/client-next/src/app/icon.svg
new file mode 100644
index 0000000..cfbeb7c
--- /dev/null
+++ b/client-next/src/app/icon.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <path d="M9 8c0-1.5 1.2-2.5 2.8-2.5 1.4 0 2.5.8 2.8 2" stroke="#1C1917" stroke-width="2.2" stroke-linecap="round"/>
+  <path d="M8 12c2.5-1 5.5-1 8 0 2.5 1 4.5 3 6 5.5" stroke="#8B4F4F" stroke-width="2.2" stroke-linecap="round"/>
+  <path d="M22 18.5h6M25 15.5v6" stroke="#8B4F4F" stroke-width="2" stroke-linecap="round"/>
+</svg>
diff --git a/client-next/src/app/login/Auth.module.css b/client-next/src/app/login/Auth.module.css
index c880492..2593cfb 100644
--- a/client-next/src/app/login/Auth.module.css
+++ b/client-next/src/app/login/Auth.module.css
@@ -1,24 +1,72 @@
-/* Auth pages — Login and Register share this stylesheet */
+/* Auth pages — shared layout for login, register, forgot, reset */
 
 .page {
   min-height: 100vh;
   display: flex;
+  background: var(--bg-base);
+}
+
+.brandPanel {
+  display: none;
+  flex: 1;
+  padding: var(--space-10);
+  background: var(--bg-surface);
+  border-right: 1px solid var(--border);
+  flex-direction: column;
+  justify-content: center;
+  gap: var(--space-6);
+  max-width: 480px;
+}
+
+.brandLogo {
+  margin-bottom: var(--space-2);
+}
+
+.brandTitle {
+  font-family: var(--font-serif);
+  font-size: var(--text-2xl);
+  font-weight: 600;
+  color: var(--text-primary);
+  line-height: var(--leading-snug);
+  margin: 0;
+}
+
+.brandList {
+  margin: 0;
+  padding-left: var(--space-5);
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+  line-height: var(--leading-relaxed);
+}
+
+.brandFooter {
+  margin: 0;
+  font-size: var(--text-sm);
+  color: var(--text-muted);
+}
+
+.brandFooter a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+.formPanel {
+  flex: 1;
+  display: flex;
   align-items: center;
   justify-content: center;
-  background: var(--bg-base);
   padding: var(--space-6);
 }
 
 .card {
   width: 100%;
-  max-width: 360px;
+  max-width: 400px;
   background: var(--bg-surface);
   border: 1px solid var(--border);
   border-radius: var(--radius-lg);
   padding: var(--space-8);
 }
 
-/* Header */
 .header {
   margin-bottom: var(--space-6);
   display: flex;
@@ -26,33 +74,81 @@
   gap: var(--space-2);
 }
 
-.wordmark {
-  font-family: var(--font-serif);
-  font-size: var(--text-base);
-  font-weight: 600;
-  color: var(--accent);
-  text-decoration: none;
-  letter-spacing: -0.01em;
-}
-
-.wordmark:hover {
-  text-decoration: none;
-  color: var(--accent-hover);
+.mobileLogo {
+  display: block;
+  margin-bottom: var(--space-2);
 }
 
 .title {
   font-size: var(--text-2xl);
   font-weight: 700;
   color: var(--text-primary);
-  margin: var(--space-2) 0 var(--space-3);
+  margin: 0;
 }
 
 .subtitle {
   font-size: var(--text-sm);
   color: var(--text-muted);
+  margin: 0;
+}
+
+.social {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  margin-bottom: var(--space-5);
+}
+
+.socialBtn {
+  width: 100%;
+  padding: var(--space-2) var(--space-4);
+  font-size: var(--text-sm);
+  font-weight: 500;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border);
+  background: var(--bg-base);
+  color: var(--text-primary);
+  cursor: pointer;
+  transition: border-color 0.15s ease, background 0.15s ease;
+}
+
+.socialBtn:hover:not(:disabled) {
+  border-color: var(--border-strong);
+  background: var(--bg-surface);
+}
+
+.socialBtn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.orcidBtn {
+  border-color: #a6ce39;
+  color: #3d5c0a;
+}
+
+.googleBtn,
+.githubBtn {
+  /* outline style — inherits .socialBtn */
+}
+
+.divider {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  color: var(--text-muted);
+  font-size: var(--text-xs);
+  margin-top: var(--space-2);
+}
+
+.divider::before,
+.divider::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: var(--border);
 }
 
-/* Form */
 .form {
   display: flex;
   flex-direction: column;
@@ -83,6 +179,15 @@
   margin: 0;
 }
 
+.readOnly {
+  padding: var(--space-2) var(--space-3);
+  font-size: var(--text-sm);
+  color: var(--text-muted);
+  background: var(--bg-base);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+}
+
 .forgotLink {
   font-size: var(--text-xs);
   color: var(--text-muted);
@@ -115,6 +220,54 @@
   color: var(--text-muted);
 }
 
+.inputError {
+  border-color: #c0392b;
+}
+
+.passwordWrap {
+  position: relative;
+}
+
+.passwordWrap .input {
+  padding-right: var(--space-10);
+}
+
+.passwordToggle {
+  position: absolute;
+  right: var(--space-2);
+  top: 50%;
+  transform: translateY(-50%);
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: var(--space-1);
+  display: flex;
+  align-items: center;
+}
+
+.passwordToggle:hover {
+  color: var(--text-secondary);
+}
+
+.checkboxRow {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-2);
+  font-size: var(--text-sm);
+  color: var(--text-secondary);
+  line-height: var(--leading-normal);
+}
+
+.checkboxRow input {
+  margin-top: 3px;
+}
+
+.checkboxRow a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
 .error {
   font-size: var(--text-sm);
   color: #c0392b;
@@ -131,8 +284,8 @@
   font-size: var(--text-sm);
   font-weight: 500;
   color: var(--bg-base);
-  background: var(--accent);
-  border: 1px solid var(--accent);
+  background: var(--brand);
+  border: 1px solid var(--brand);
   border-radius: var(--radius-sm);
   cursor: pointer;
   transition: background 0.15s ease;
@@ -140,8 +293,8 @@
 }
 
 .submitBtn:hover:not(:disabled) {
-  background: var(--accent-hover);
-  border-color: var(--accent-hover);
+  background: var(--brand-hover, #7a4545);
+  border-color: var(--brand-hover, #7a4545);
 }
 
 .submitBtn:disabled {
@@ -149,7 +302,6 @@
   cursor: not-allowed;
 }
 
-/* Bottom link */
 .switchLink {
   margin-top: var(--space-6);
   text-align: center;
@@ -165,6 +317,7 @@
 .switchLink a:hover {
   text-decoration: underline;
 }
+
 .successBox {
   padding: var(--space-4);
   background: rgba(90, 138, 106, 0.1);
@@ -174,3 +327,13 @@
   color: var(--text-secondary);
   line-height: var(--leading-normal);
 }
+
+@media (min-width: 900px) {
+  .brandPanel {
+    display: flex;
+  }
+
+  .mobileLogo {
+    display: none;
+  }
+}
diff --git a/client-next/src/app/login/page.js b/client-next/src/app/login/page.js
index 1612b43..4fccfe4 100644
--- a/client-next/src/app/login/page.js
+++ b/client-next/src/app/login/page.js
@@ -4,17 +4,17 @@ import { useState } from 'react'
 import { useRouter } from 'next/navigation'
 import Link from 'next/link'
 import { useAuth } from '@/context/AuthContext'
+import Logo from '@/components/Logo'
+import { AuthBrandPanel, SocialAuthButtons } from '@/components/AuthLayout'
+import PasswordInput from '@/components/PasswordInput'
 import styles from './Auth.module.css'
 
-/**
- * Login page
- * Centered card layout, inline field-level errors, link to register.
- */
 export default function Login() {
   const { login } = useAuth()
   const router = useRouter()
   const [error, setError] = useState(null)
   const [loading, setLoading] = useState(false)
+  const [password, setPassword] = useState('')
 
   async function handleSubmit(e) {
     e.preventDefault()
@@ -22,7 +22,7 @@ export default function Login() {
     setLoading(true)
     const form = e.target
     try {
-      await login(form.email.value, form.password.value)
+      await login(form.email.value, password)
       router.push('/')
     } catch (err) {
       setError(err.message)
@@ -33,61 +33,57 @@ export default function Login() {
 
   return (
     <div className={styles.page}>
-      <div className={styles.card}>
-        <div className={styles.header}>
-          <Link href="/" className={styles.wordmark}>PostScholar</Link>
-          <h1 className={styles.title}>Sign in</h1>
-          <p className={styles.subtitle}>
-            Continue to your account
-          </p>
-        </div>
-
-        <form className={styles.form} onSubmit={handleSubmit}>
-          <div className={styles.field}>
-            <label className={styles.label} htmlFor="email">Email</label>
-            <input
-              className={styles.input}
-              id="email"
-              name="email"
-              type="email"
-              autoComplete="email"
-              required
-            />
+      <AuthBrandPanel />
+      <div className={styles.formPanel}>
+        <div className={styles.card}>
+          <div className={styles.header}>
+            <Logo variant="full" href="/" className={styles.mobileLogo} />
+            <h1 className={styles.title}>Sign in</h1>
+            <p className={styles.subtitle}>Continue to your account</p>
           </div>
 
-          <div className={styles.field}>
+          <SocialAuthButtons />
+
+          <form className={styles.form} onSubmit={handleSubmit}>
+            <div className={styles.field}>
+              <label className={styles.label} htmlFor="email">Email</label>
+              <input
+                className={styles.input}
+                id="email"
+                name="email"
+                type="email"
+                autoComplete="email"
+                required
+              />
+            </div>
+
             <div className={styles.labelRow}>
               <label className={styles.label} htmlFor="password">Password</label>
               <Link href="/forgot-password" className={styles.forgotLink}>
                 Forgot password?
               </Link>
             </div>
-            <input
-              className={styles.input}
+            <PasswordInput
               id="password"
               name="password"
-              type="password"
+              label=""
               autoComplete="current-password"
-              required
+              value={password}
+              onChange={e => setPassword(e.target.value)}
             />
-          </div>
 
-          {error && <p className={styles.error}>{error}</p>}
+            {error && <p className={styles.error}>{error}</p>}
 
-          <button
-            className={styles.submitBtn}
-            type="submit"
-            disabled={loading}
-          >
-            {loading ? 'Signing in...' : 'Sign in'}
-          </button>
-        </form>
+            <button className={styles.submitBtn} type="submit" disabled={loading}>
+              {loading ? 'Signing in…' : 'Sign in'}
+            </button>
+          </form>
 
-        <p className={styles.switchLink}>
-          No account?{' '}
-          <Link href="/register">Create one</Link>
-        </p>
+          <p className={styles.switchLink}>
+            No account? <Link href="/register">Create one</Link>
+          </p>
+        </div>
       </div>
     </div>
   )
-}
\ No newline at end of file
+}
diff --git a/client-next/src/app/orcid/callback/page.js b/client-next/src/app/orcid/callback/page.js
index ac77f08..3a7efcb 100644
--- a/client-next/src/app/orcid/callback/page.js
+++ b/client-next/src/app/orcid/callback/page.js
@@ -3,21 +3,14 @@
 import { Suspense, useEffect, useState } from 'react'
 import { useSearchParams, useRouter } from 'next/navigation'
 import { getApiUrl } from '@/lib/config'
+import { useAuth } from '@/context/AuthContext'
 import styles from './OrcidCallback.module.css'
 
-/**
- * OrcidCallback — /orcid/callback
- *
- * ORCID redirects here after OAuth with ?code=xxx&state=xxx
- * We send these to POST /auth/orcid/callback which verifies
- * the author and stores the verification record.
- *
- * After success or failure, we redirect back to the discussion.
- */
 function OrcidCallbackInner() {
   const searchParams = useSearchParams()
   const router = useRouter()
-  const [status, setStatus] = useState('loading') // loading | success | error | no_match
+  const { refreshUser } = useAuth()
+  const [status, setStatus] = useState('loading')
   const [message, setMessage] = useState('')
 
   useEffect(() => {
@@ -36,13 +29,30 @@ function OrcidCallbackInner() {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           credentials: 'include',
-          body: JSON.stringify({ code, state })
+          body: JSON.stringify({ code, state }),
         })
         const data = await res.json()
 
         if (!res.ok) {
           setStatus('error')
-          setMessage(data.error || 'Verification failed')
+          setMessage(data.error || 'ORCID sign-in failed')
+          return
+        }
+
+        if (data.needs_completion) {
+          const params = new URLSearchParams({
+            token: data.completion_token,
+          })
+          if (data.display_name) params.set('name', data.display_name)
+          router.replace(`/auth/complete?${params.toString()}`)
+          return
+        }
+
+        if (data.mode === 'login') {
+          await refreshUser()
+          setStatus('success')
+          setMessage('Signed in with ORCID.')
+          setTimeout(() => router.push('/'), 1500)
           return
         }
 
@@ -70,7 +80,7 @@ function OrcidCallbackInner() {
     }
 
     exchange()
-  }, [searchParams, router])
+  }, [searchParams, router, refreshUser])
 
   return (
     <div className={styles.page}>
@@ -78,21 +88,21 @@ function OrcidCallbackInner() {
         {status === 'loading' && (
           <>
             <div className={styles.spinner} />
-            <p className={styles.message}>Verifying your ORCID...</p>
+            <p className={styles.message}>Connecting your ORCID account…</p>
           </>
         )}
         {status === 'success' && (
           <>
             <div className={styles.icon}>✓</div>
             <p className={`${styles.message} ${styles.success}`}>{message}</p>
-            <p className={styles.hint}>Redirecting...</p>
+            <p className={styles.hint}>Redirecting…</p>
           </>
         )}
         {(status === 'error' || status === 'no_match') && (
           <>
             <div className={`${styles.icon} ${styles.failIcon}`}>✗</div>
             <p className={`${styles.message} ${styles.fail}`}>{message}</p>
-            <p className={styles.hint}>Redirecting...</p>
+            <p className={styles.hint}>Redirecting…</p>
           </>
         )}
       </div>
@@ -102,8 +112,8 @@ function OrcidCallbackInner() {
 
 export default function OrcidCallback() {
   return (
-    <Suspense fallback={<div style={{ padding: '2rem', textAlign: 'center' }}>Loading...</div>}>
+    <Suspense fallback={<div style={{ padding: '2rem', textAlign: 'center' }}>Loading…</div>}>
       <OrcidCallbackInner />
     </Suspense>
   )
-}
\ No newline at end of file
+}
diff --git a/client-next/src/app/register/page.js b/client-next/src/app/register/page.js
index 4670269..feddda1 100644
--- a/client-next/src/app/register/page.js
+++ b/client-next/src/app/register/page.js
@@ -5,39 +5,60 @@ import { useRouter } from 'next/navigation'
 import Link from 'next/link'
 import { useAuth } from '@/context/AuthContext'
 import { getApiUrl } from '@/lib/config'
-import styles from './Auth.module.css'
+import Logo from '@/components/Logo'
+import { AuthBrandPanel, SocialAuthButtons } from '@/components/AuthLayout'
+import PasswordInput from '@/components/PasswordInput'
+import styles from '../login/Auth.module.css'
+
+const USERNAME_REGEX = /^[a-z0-9_]{3,30}$/
 
-/**
- * Register page
- * Same card layout as Login, three fields, inline errors.
- */
 export default function Register() {
   const { refreshUser } = useAuth()
   const router = useRouter()
   const [error, setError] = useState(null)
   const [loading, setLoading] = useState(false)
+  const [username, setUsername] = useState('')
+  const [password, setPassword] = useState('')
+  const [termsAccepted, setTermsAccepted] = useState(false)
+  const [fieldErrors, setFieldErrors] = useState({})
+
+  function validate() {
+    const errors = {}
+    if (!USERNAME_REGEX.test(username)) {
+      errors.username = '3–30 chars: lowercase letters, numbers, underscores'
+    }
+    if (password.length < 8) {
+      errors.password = 'At least 8 characters'
+    }
+    if (!termsAccepted) {
+      errors.terms = 'You must agree to the Terms and Privacy Policy'
+    }
+    setFieldErrors(errors)
+    return Object.keys(errors).length === 0
+  }
 
   async function handleSubmit(e) {
     e.preventDefault()
     setError(null)
+    if (!validate()) return
+
     setLoading(true)
     const form = e.target
     try {
-      // Register then immediately log in
       const res = await fetch(`${getApiUrl()}/auth/register`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         credentials: 'include',
         body: JSON.stringify({
           email: form.email.value,
-          username: form.username.value,
-          password: form.password.value
-        })
+          username,
+          password,
+        }),
       })
       const data = await res.json()
       if (!res.ok) throw new Error(data.error || 'Registration failed')
       await refreshUser()
-      router.push('/')
+      router.push('/verify-email?sent=1')
     } catch (err) {
       setError(err.message)
     } finally {
@@ -47,70 +68,84 @@ export default function Register() {
 
   return (
     <div className={styles.page}>
-      <div className={styles.card}>
-        <div className={styles.header}>
-          <Link href="/" className={styles.wordmark}>PostScholar</Link>
-          <h1 className={styles.title}>Create account</h1>
-          <p className={styles.subtitle}>
-            Join the discussion
-          </p>
-        </div>
-
-        <form className={styles.form} onSubmit={handleSubmit}>
-          <div className={styles.field}>
-            <label className={styles.label} htmlFor="email">Email</label>
-            <input
-              className={styles.input}
-              id="email"
-              name="email"
-              type="email"
-              autoComplete="email"
-              required
-            />
+      <AuthBrandPanel />
+      <div className={styles.formPanel}>
+        <div className={styles.card}>
+          <div className={styles.header}>
+            <Logo variant="full" href="/" className={styles.mobileLogo} />
+            <h1 className={styles.title}>Create account</h1>
+            <p className={styles.subtitle}>Join paper discussions</p>
           </div>
 
-          <div className={styles.field}>
-            <label className={styles.label} htmlFor="username">Username</label>
-            <p className={styles.hint}>Lowercase letters, numbers, underscores. 3–30 characters.</p>
-            <input
-              className={styles.input}
-              id="username"
-              name="username"
-              type="text"
-              autoComplete="username"
-              required
-            />
-          </div>
+          <SocialAuthButtons />
+
+          <form className={styles.form} onSubmit={handleSubmit}>
+            <div className={styles.field}>
+              <label className={styles.label} htmlFor="email">Email</label>
+              <input
+                className={styles.input}
+                id="email"
+                name="email"
+                type="email"
+                autoComplete="email"
+                required
+              />
+            </div>
+
+            <div className={styles.field}>
+              <label className={styles.label} htmlFor="username">Username</label>
+              <p className={styles.hint}>Lowercase letters, numbers, underscores. 3–30 characters.</p>
+              <input
+                className={`${styles.input} ${fieldErrors.username ? styles.inputError : ''}`}
+                id="username"
+                name="username"
+                type="text"
+                autoComplete="username"
+                value={username}
+                onChange={e => setUsername(e.target.value.toLowerCase())}
+                required
+              />
+              {fieldErrors.username && <p className={styles.error}>{fieldErrors.username}</p>}
+            </div>
 
-          <div className={styles.field}>
-            <label className={styles.label} htmlFor="password">Password</label>
-            <p className={styles.hint}>At least 8 characters.</p>
-            <input
-              className={styles.input}
+            <PasswordInput
               id="password"
               name="password"
-              type="password"
+              label="Password"
+              hint="At least 8 characters."
               autoComplete="new-password"
-              required
+              value={password}
+              onChange={e => setPassword(e.target.value)}
             />
-          </div>
+            {fieldErrors.password && <p className={styles.error}>{fieldErrors.password}</p>}
+
+            <label className={styles.checkboxRow}>
+              <input
+                type="checkbox"
+                checked={termsAccepted}
+                onChange={e => setTermsAccepted(e.target.checked)}
+              />
+              <span>
+                I agree to the{' '}
+                <Link href="/terms" target="_blank">Terms of Service</Link>
+                {' '}and{' '}
+                <Link href="/privacy" target="_blank">Privacy Policy</Link>
+              </span>
+            </label>
+            {fieldErrors.terms && <p className={styles.error}>{fieldErrors.terms}</p>}
 
-          {error && <p className={styles.error}>{error}</p>}
+            {error && <p className={styles.error}>{error}</p>}
 
-          <button
-            className={styles.submitBtn}
-            type="submit"
-            disabled={loading}
-          >
-            {loading ? 'Creating account...' : 'Create account'}
-          </button>
-        </form>
+            <button className={styles.submitBtn} type="submit" disabled={loading}>
+              {loading ? 'Creating account…' : 'Create account'}
+            </button>
+          </form>
 
-        <p className={styles.switchLink}>
-          Already have an account?{' '}
-          <Link href="/login">Sign in</Link>
-        </p>
+          <p className={styles.switchLink}>
+            Already have an account? <Link href="/login">Sign in</Link>
+          </p>
+        </div>
       </div>
     </div>
   )
-}
\ No newline at end of file
+}
diff --git a/client-next/src/app/reset-password/page.js b/client-next/src/app/reset-password/page.js
index eea64de..a8dcb4c 100644
--- a/client-next/src/app/reset-password/page.js
+++ b/client-next/src/app/reset-password/page.js
@@ -4,13 +4,11 @@ import { Suspense, useState } from 'react'
 import { useSearchParams, useRouter } from 'next/navigation'
 import Link from 'next/link'
 import { getApiUrl } from '@/lib/config'
-import styles from './Auth.module.css'
+import Logo from '@/components/Logo'
+import { AuthBrandPanel } from '@/components/AuthLayout'
+import PasswordInput from '@/components/PasswordInput'
+import styles from '../login/Auth.module.css'
 
-/**
- * Reset password page — /reset-password?token=xxx
- * Reads the token from the URL query string.
- * Submits to POST /auth/reset-password.
- */
 function ResetPasswordInner() {
   const searchParams = useSearchParams()
   const token = searchParams.get('token')
@@ -40,7 +38,7 @@ function ResetPasswordInner() {
       const res = await fetch(`${getApiUrl()}/auth/reset-password`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token, password })
+        body: JSON.stringify({ token, password }),
       })
       const data = await res.json()
       if (!res.ok) {
@@ -59,9 +57,11 @@ function ResetPasswordInner() {
   if (!token) {
     return (
       <div className={styles.page}>
-        <div className={styles.card}>
-          <p className={styles.error}>Invalid reset link. Please request a new one.</p>
-          <p className={styles.switchLink}><Link href="/forgot-password">Request reset link</Link></p>
+        <div className={styles.formPanel} style={{ width: '100%' }}>
+          <div className={styles.card}>
+            <p className={styles.error}>Invalid reset link. Please request a new one.</p>
+            <p className={styles.switchLink}><Link href="/forgot-password">Request reset link</Link></p>
+          </div>
         </div>
       </div>
     )
@@ -69,59 +69,47 @@ function ResetPasswordInner() {
 
   return (
     <div className={styles.page}>
-      <div className={styles.card}>
-        <div className={styles.header}>
-          <Link href="/" className={styles.wordmark}>PostScholar</Link>
-          <h1 className={styles.title}>Set new password</h1>
-        </div>
-
-        {done ? (
-          <div className={styles.successBox}>
-            Password updated. Redirecting to sign in...
+      <AuthBrandPanel />
+      <div className={styles.formPanel}>
+        <div className={styles.card}>
+          <div className={styles.header}>
+            <Logo variant="full" href="/" className={styles.mobileLogo} />
+            <h1 className={styles.title}>Set new password</h1>
           </div>
-        ) : (
-          <form className={styles.form} onSubmit={handleSubmit}>
-            <div className={styles.field}>
-              <label className={styles.label} htmlFor="password">New password</label>
-              <input
-                className={styles.input}
+
+          {done ? (
+            <div className={styles.successBox}>
+              Password updated. Redirecting to sign in…
+            </div>
+          ) : (
+            <form className={styles.form} onSubmit={handleSubmit}>
+              <PasswordInput
                 id="password"
-                type="password"
-                required
+                name="password"
+                label="New password"
+                autoComplete="new-password"
                 value={password}
                 onChange={e => setPassword(e.target.value)}
-                autoComplete="new-password"
               />
-            </div>
-
-            <div className={styles.field}>
-              <label className={styles.label} htmlFor="confirm">Confirm password</label>
-              <input
-                className={styles.input}
+              <PasswordInput
                 id="confirm"
-                type="password"
-                required
+                name="confirm"
+                label="Confirm password"
+                autoComplete="new-password"
                 value={confirm}
                 onChange={e => setConfirm(e.target.value)}
-                autoComplete="new-password"
               />
-            </div>
+              {error && <p className={styles.error}>{error}</p>}
+              <button className={styles.submitBtn} type="submit" disabled={loading}>
+                {loading ? 'Updating…' : 'Update password'}
+              </button>
+            </form>
+          )}
 
-            {error && <p className={styles.error}>{error}</p>}
-
-            <button
-              className={styles.submitBtn}
-              type="submit"
-              disabled={loading}
-            >
-              {loading ? 'Updating...' : 'Update password'}
-            </button>
-          </form>
-        )}
-
-        <p className={styles.switchLink}>
-          <Link href="/login">Back to sign in</Link>
-        </p>
+          <p className={styles.switchLink}>
+            <Link href="/login">Back to sign in</Link>
+          </p>
+        </div>
       </div>
     </div>
   )
@@ -129,8 +117,8 @@ function ResetPasswordInner() {
 
 export default function ResetPassword() {
   return (
-    <Suspense fallback={<div style={{ padding: '2rem', textAlign: 'center' }}>Loading...</div>}>
+    <Suspense fallback={<div className={styles.page} />}>
       <ResetPasswordInner />
     </Suspense>
   )
-}
\ No newline at end of file
+}
diff --git a/client-next/src/app/settings/Settings.module.css b/client-next/src/app/settings/Settings.module.css
index 9e3d92b..9633bba 100644
--- a/client-next/src/app/settings/Settings.module.css
+++ b/client-next/src/app/settings/Settings.module.css
@@ -155,6 +155,15 @@
   cursor: not-allowed;
 }
 
+.readOnly {
+  padding: var(--space-2) var(--space-3);
+  font-size: var(--text-sm);
+  color: var(--text-muted);
+  background: var(--bg-base);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+}
+
 .topicsLink {
   font-size: var(--text-sm);
   font-weight: 500;
diff --git a/client-next/src/app/settings/page.js b/client-next/src/app/settings/page.js
index c00bc22..2b59ef0 100644
--- a/client-next/src/app/settings/page.js
+++ b/client-next/src/app/settings/page.js
@@ -12,6 +12,7 @@ export default function SettingsPage() {
   const { user, isLoading, refreshUser } = useAuth()
   const router = useRouter()
   const [bio, setBio] = useState('')
+  const [displayName, setDisplayName] = useState('')
   const [affiliation, setAffiliation] = useState('')
   const [location, setLocation] = useState('')
   const [websiteUrl, setWebsiteUrl] = useState('')
@@ -35,6 +36,7 @@ export default function SettingsPage() {
     getMyProfile()
       .then(data => {
         setBio(data.bio || '')
+        setDisplayName(data.display_name || '')
         setAffiliation(data.affiliation || '')
         setLocation(data.location || '')
         setWebsiteUrl(data.website_url || '')
@@ -53,6 +55,7 @@ export default function SettingsPage() {
     try {
       await updateProfile({
         bio,
+        display_name: displayName,
         affiliation,
         location,
         website_url: websiteUrl,
@@ -81,6 +84,25 @@ export default function SettingsPage() {
         <section className={styles.section}>
           <h2 className={styles.sectionHeading}>Profile</h2>
 
+          <div className={styles.field}>
+            <label className={styles.label}>Display name</label>
+            <input
+              type="text"
+              className={styles.input}
+              value={displayName}
+              onChange={e => setDisplayName(e.target.value)}
+              placeholder="How your name appears on comments"
+              maxLength={50}
+            />
+            <span className={styles.hint}>Optional — @username stays your handle for URLs and mentions</span>
+          </div>
+
+          <div className={styles.field}>
+            <label className={styles.label}>Username</label>
+            <div className={styles.readOnly}>@{user.username}</div>
+            <span className={styles.hint}>Used in your profile URL and @mentions</span>
+          </div>
+
           <div className={styles.field}>
             <label className={styles.label}>Bio</label>
             <textarea
diff --git a/client-next/src/app/u/[username]/Profile.module.css b/client-next/src/app/u/[username]/Profile.module.css
index 013ec73..455d6d0 100644
--- a/client-next/src/app/u/[username]/Profile.module.css
+++ b/client-next/src/app/u/[username]/Profile.module.css
@@ -50,6 +50,12 @@
   letter-spacing: -0.02em;
 }
 
+.handle {
+  font-size: var(--text-sm);
+  color: var(--text-muted);
+  margin: var(--space-1) 0 0;
+}
+
 .affiliation {
   font-size: var(--text-sm);
   color: var(--text-secondary);
diff --git a/client-next/src/app/u/[username]/ProfileClient.jsx b/client-next/src/app/u/[username]/ProfileClient.jsx
index dc3fa33..511fce8 100644
--- a/client-next/src/app/u/[username]/ProfileClient.jsx
+++ b/client-next/src/app/u/[username]/ProfileClient.jsx
@@ -7,8 +7,9 @@ import { useAuth } from '@/context/AuthContext'
 import { followUser, unfollowUser, getFollowStatus, getFollowCounts } from '@/lib/api'
 import styles from './Profile.module.css'
 
-function getInitials(username) {
-  return username.slice(0, 2).toUpperCase()
+function getInitials(profile) {
+  const source = profile.display_name || profile.username || ''
+  return source.slice(0, 2).toUpperCase()
 }
 
 function timeAgo(dateStr) {
@@ -83,10 +84,17 @@ export default function ProfileClient({ profile }) {
       <Link href="/explore" className="backLink">← Discussions</Link>
 
       <div className={styles.header}>
-        <div className={styles.avatar}>{getInitials(profile.username)}</div>
+        <div className={styles.avatar}>{getInitials(profile)}</div>
         <div className={styles.info}>
           <div className={styles.nameRow}>
-            <h1 className={styles.username}>{profile.username}</h1>
+            <div>
+              <h1 className={styles.username}>
+                {profile.display_name || profile.username}
+              </h1>
+              {profile.display_name && (
+                <p className={styles.handle}>@{profile.username}</p>
+              )}
+            </div>
             {!isOwnProfile && user && (
               <button
                 className={`${styles.followBtn} ${following ? styles.following : ''}`}
diff --git a/client-next/src/app/verify-email/page.js b/client-next/src/app/verify-email/page.js
new file mode 100644
index 0000000..936f94e
--- /dev/null
+++ b/client-next/src/app/verify-email/page.js
@@ -0,0 +1,118 @@
+'use client'
+
+import { Suspense, useEffect, useState } from 'react'
+import { useSearchParams, useRouter } from 'next/navigation'
+import Link from 'next/link'
+import { useAuth } from '@/context/AuthContext'
+import { getApiUrl } from '@/lib/config'
+import Logo from '@/components/Logo'
+import styles from '../login/Auth.module.css'
+
+function VerifyEmailInner() {
+  const searchParams = useSearchParams()
+  const router = useRouter()
+  const { user, refreshUser } = useAuth()
+  const [status, setStatus] = useState('pending')
+  const [message, setMessage] = useState('')
+  const [resending, setResending] = useState(false)
+
+  const token = searchParams.get('token')
+  const justSent = searchParams.get('sent') === '1'
+
+  useEffect(() => {
+    if (!token) return
+
+    async function verify() {
+      try {
+        const res = await fetch(`${getApiUrl()}/auth/verify-email?token=${encodeURIComponent(token)}`)
+        const data = await res.json()
+        if (!res.ok) {
+          setStatus('error')
+          setMessage(data.error || 'Verification failed')
+          return
+        }
+        setStatus('success')
+        setMessage('Your email is verified. You can now post comments and start discussions.')
+        await refreshUser()
+        setTimeout(() => router.push('/'), 3000)
+      } catch {
+        setStatus('error')
+        setMessage('Failed to reach server')
+      }
+    }
+
+    verify()
+  }, [token, router, refreshUser])
+
+  async function handleResend() {
+    setResending(true)
+    try {
+      const res = await fetch(`${getApiUrl()}/auth/resend-verification`, {
+        method: 'POST',
+        credentials: 'include',
+      })
+      const data = await res.json()
+      if (!res.ok) throw new Error(data.error || 'Failed to resend')
+      setMessage('Verification email sent. Check your inbox.')
+    } catch (err) {
+      setMessage(err.message)
+    } finally {
+      setResending(false)
+    }
+  }
+
+  if (token) {
+    return (
+      <div className={styles.page}>
+        <div className={styles.formPanel} style={{ width: '100%' }}>
+          <div className={styles.card}>
+            <Logo variant="full" href="/" className={styles.mobileLogo} />
+            <h1 className={styles.title}>Verify email</h1>
+            {status === 'pending' && <p className={styles.subtitle}>Verifying…</p>}
+            {status === 'success' && <p className={styles.successBox}>{message}</p>}
+            {status === 'error' && <p className={styles.error}>{message}</p>}
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className={styles.page}>
+      <div className={styles.formPanel} style={{ width: '100%' }}>
+        <div className={styles.card}>
+          <Logo variant="full" href="/" className={styles.mobileLogo} />
+          <h1 className={styles.title}>Check your inbox</h1>
+          <p className={styles.subtitle}>
+            {justSent
+              ? 'We sent a verification link to your email. Click it to unlock posting.'
+              : 'Verify your email to post comments and start discussions.'}
+          </p>
+          {user?.email && (
+            <p className={styles.hint}>Sent to {user.email}</p>
+          )}
+          {message && <p className={styles.successBox}>{message}</p>}
+          <button
+            className={styles.submitBtn}
+            onClick={handleResend}
+            disabled={resending}
+            type="button"
+          >
+            {resending ? 'Sending…' : 'Resend verification email'}
+          </button>
+          <p className={styles.switchLink}>
+            <Link href="/">Continue browsing</Link>
+          </p>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default function VerifyEmailPage() {
+  return (
+    <Suspense fallback={<div className={styles.page} />}>
+      <VerifyEmailInner />
+    </Suspense>
+  )
+}
diff --git a/client-next/src/components/AuthLayout.jsx b/client-next/src/components/AuthLayout.jsx
new file mode 100644
index 0000000..0192708
--- /dev/null
+++ b/client-next/src/components/AuthLayout.jsx
@@ -0,0 +1,84 @@
+'use client'
+
+import { useState } from 'react'
+import Link from 'next/link'
+import { getApiUrl } from '@/lib/config'
+import Logo from '@/components/Logo'
+import styles from '@/app/login/Auth.module.css'
+
+async function startOAuth(path) {
+  const res = await fetch(`${getApiUrl()}${path}`, { credentials: 'include' })
+  const data = await res.json()
+  if (!res.ok) throw new Error(data.error || 'OAuth unavailable')
+  window.location.href = data.url
+}
+
+export default function SocialAuthButtons() {
+  const [loading, setLoading] = useState(null)
+  const [error, setError] = useState(null)
+
+  async function handleOAuth(provider, path) {
+    setLoading(provider)
+    setError(null)
+    try {
+      await startOAuth(path)
+    } catch (err) {
+      setError(err.message)
+      setLoading(null)
+    }
+  }
+
+  return (
+    <div className={styles.social}>
+      <button
+        type="button"
+        className={`${styles.socialBtn} ${styles.orcidBtn}`}
+        onClick={() => handleOAuth('orcid', '/auth/orcid/login/url')}
+        disabled={!!loading}
+      >
+        {loading === 'orcid' ? 'Redirecting…' : 'Continue with ORCID'}
+      </button>
+      <button
+        type="button"
+        className={`${styles.socialBtn} ${styles.googleBtn}`}
+        onClick={() => handleOAuth('google', '/auth/google/url')}
+        disabled={!!loading}
+      >
+        {loading === 'google' ? 'Redirecting…' : 'Continue with Google'}
+      </button>
+      <button
+        type="button"
+        className={`${styles.socialBtn} ${styles.githubBtn}`}
+        onClick={() => handleOAuth('github', '/auth/github/url')}
+        disabled={!!loading}
+      >
+        {loading === 'github' ? 'Redirecting…' : 'Continue with GitHub'}
+      </button>
+      {error && <p className={styles.error}>{error}</p>}
+      <div className={styles.divider}>
+        <span>or continue with email</span>
+      </div>
+    </div>
+  )
+}
+
+export function AuthBrandPanel() {
+  return (
+    <div className={styles.brandPanel}>
+      <Logo variant="full" href="/" className={styles.brandLogo} />
+      <h2 className={styles.brandTitle}>
+        Post-publication discussion for published research
+      </h2>
+      <ul className={styles.brandList}>
+        <li>DOI-backed discussion threads</li>
+        <li>ORCID author verification badges</li>
+        <li>Quiet, scholarly conversation</li>
+      </ul>
+      <p className={styles.brandFooter}>
+        <Link href="/terms">Terms</Link>
+        {' · '}
+        <Link href="/privacy">Privacy</Link>
+      </p>
+    </div>
+  )
+}
diff --git a/client-next/src/components/Comment.jsx b/client-next/src/components/Comment.jsx
index 616157c..f56d708 100644
--- a/client-next/src/components/Comment.jsx
+++ b/client-next/src/components/Comment.jsx
@@ -17,6 +17,10 @@ import CommentBody from './CommentBody'
 import styles from './Comment.module.css'
 import 'katex/dist/katex.min.css'
 
+function authorLabel(comment) {
+  return comment.display_name || comment.username
+}
+
 /**
  * Comment
  *
@@ -199,7 +203,7 @@ export default function Comment({
         {/* Header */}
         <div className={styles.header}>
           <Link href={`/u/${comment.username}`} className={styles.username}>
-            {comment.username}
+            {authorLabel(comment)}
           </Link>
           <AuthorBadge isVerifiedAuthor={comment.is_verified_author} />
           <span className={styles.time}>{timeAgo(comment.created_at)}</span>
diff --git a/client-next/src/components/FeedCard.jsx b/client-next/src/components/FeedCard.jsx
index 90810f3..2d935ec 100644
--- a/client-next/src/components/FeedCard.jsx
+++ b/client-next/src/components/FeedCard.jsx
@@ -48,9 +48,12 @@ export default function FeedCard({ discussion: rawDiscussion }) {
     comment_count,
     latest_activity,
     topics = [],
-    username
+    username,
+    display_name,
   } = discussion
 
+  const starterLabel = display_name || username
+
   const { user } = useAuth()
   const [bookmarked, setBookmarked] = useState(false)
   const [bookmarkLoading, setBookmarkLoading] = useState(false)
@@ -113,7 +116,7 @@ export default function FeedCard({ discussion: rawDiscussion }) {
             <span className={styles.metaItem}>
               <span className={styles.metaLabel}>Started by</span>
               <Link href={`/u/${username}`} className={styles.author}>
-                {username}
+                {starterLabel}
               </Link>
             </span>
           )}
diff --git a/client-next/src/components/Layout.jsx b/client-next/src/components/Layout.jsx
index c700c03..2d4b8a2 100644
--- a/client-next/src/components/Layout.jsx
+++ b/client-next/src/components/Layout.jsx
@@ -3,6 +3,7 @@
 import { Suspense } from 'react'
 import Nav from './Nav'
 import Footer from './Footer'
+import VerifyEmailBanner from './VerifyEmailBanner'
 import styles from './Layout.module.css'
 
 /**
@@ -20,6 +21,7 @@ export default function Layout({ children, sidebar = null, bare = false, wide =
       <Suspense fallback={null}>
         <Nav />
       </Suspense>
+      <VerifyEmailBanner />
       <div className={styles.body}>
         {sidebar ? (
           <div className={styles.withSidebar}>
diff --git a/client-next/src/components/Logo.jsx b/client-next/src/components/Logo.jsx
new file mode 100644
index 0000000..7d4ae4f
--- /dev/null
+++ b/client-next/src/components/Logo.jsx
@@ -0,0 +1,56 @@
+import Link from 'next/link'
+import styles from './Logo.module.css'
+
+function LogoMark({ className }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 32 32"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+    >
+      <path
+        d="M9 8c0-1.5 1.2-2.5 2.8-2.5 1.4 0 2.5.8 2.8 2"
+        stroke="currentColor"
+        strokeWidth="2.2"
+        strokeLinecap="round"
+      />
+      <path
+        d="M8 12c2.5-1 5.5-1 8 0 2.5 1 4.5 3 6 5.5"
+        stroke="var(--brand)"
+        strokeWidth="2.2"
+        strokeLinecap="round"
+      />
+      <path
+        d="M22 18.5h6M25 15.5v6"
+        stroke="var(--brand)"
+        strokeWidth="2"
+        strokeLinecap="round"
+      />
+    </svg>
+  )
+}
+
+export default function Logo({ variant = 'full', href = '/', className = '' }) {
+  const content = (
+    <span className={`${styles.logo} ${className}`}>
+      <LogoMark className={styles.mark} />
+      {variant === 'full' && (
+        <span className={styles.wordmark}>
+          Post<span className={styles.accent}>Scholar</span>
+        </span>
+      )}
+    </span>
+  )
+
+  if (href) {
+    return (
+      <Link href={href} className={styles.link} aria-label="PostScholar home">
+        {content}
+      </Link>
+    )
+  }
+
+  return content
+}
diff --git a/client-next/src/components/Logo.module.css b/client-next/src/components/Logo.module.css
new file mode 100644
index 0000000..16bdf70
--- /dev/null
+++ b/client-next/src/components/Logo.module.css
@@ -0,0 +1,34 @@
+.link {
+  text-decoration: none;
+  display: inline-flex;
+}
+
+.link:hover {
+  text-decoration: none;
+}
+
+.logo {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.mark {
+  width: 28px;
+  height: 28px;
+  flex-shrink: 0;
+  color: var(--text-primary);
+}
+
+.wordmark {
+  font-family: var(--font-serif);
+  font-size: var(--text-lg);
+  font-weight: 600;
+  color: var(--text-primary);
+  letter-spacing: -0.02em;
+  line-height: 1;
+}
+
+.accent {
+  color: var(--brand);
+}
diff --git a/client-next/src/components/Nav.jsx b/client-next/src/components/Nav.jsx
index 82f4340..30065db 100644
--- a/client-next/src/components/Nav.jsx
+++ b/client-next/src/components/Nav.jsx
@@ -5,6 +5,7 @@ import Link from 'next/link'
 import { useRouter, usePathname } from 'next/navigation'
 import { useAuth } from '@/context/AuthContext'
 import { useTheme } from '@/context/ThemeContext'
+import Logo from './Logo'
 import { Search, Moon, Sun, Menu, X, Bell, User, Settings, LogOut, Shield } from 'lucide-react'
 import { getUnreadMentionCount } from '@/lib/api'
 import styles from './Nav.module.css'
@@ -130,9 +131,7 @@ export default function Nav() {
   return (
     <nav className={styles.nav}>
       <div className={styles.inner}>
-        <Link href="/" className={styles.wordmark}>
-          Post<span className={styles.wordmarkAccent}>Scholar</span>
-        </Link>
+        <Logo variant="full" href="/" />
 
         <form onSubmit={handleSearch} className={styles.search}>
           <input
diff --git a/client-next/src/components/PasswordInput.jsx b/client-next/src/components/PasswordInput.jsx
new file mode 100644
index 0000000..91f611e
--- /dev/null
+++ b/client-next/src/components/PasswordInput.jsx
@@ -0,0 +1,45 @@
+'use client'
+
+import { useState } from 'react'
+import { Eye, EyeOff } from 'lucide-react'
+import styles from '@/app/login/Auth.module.css'
+
+export default function PasswordInput({
+  id,
+  name,
+  label,
+  autoComplete,
+  value,
+  onChange,
+  hint,
+  required = true,
+}) {
+  const [visible, setVisible] = useState(false)
+
+  return (
+    <div className={styles.field}>
+      {label ? <label className={styles.label} htmlFor={id}>{label}</label> : null}
+      {hint && <p className={styles.hint}>{hint}</p>}
+      <div className={styles.passwordWrap}>
+        <input
+          className={styles.input}
+          id={id}
+          name={name}
+          type={visible ? 'text' : 'password'}
+          autoComplete={autoComplete}
+          value={value}
+          onChange={onChange}
+          required={required}
+        />
+        <button
+          type="button"
+          className={styles.passwordToggle}
+          onClick={() => setVisible(v => !v)}
+          aria-label={visible ? 'Hide password' : 'Show password'}
+        >
+          {visible ? <EyeOff size={16} /> : <Eye size={16} />}
+        </button>
+      </div>
+    </div>
+  )
+}
diff --git a/client-next/src/components/VerifyEmailBanner.jsx b/client-next/src/components/VerifyEmailBanner.jsx
new file mode 100644
index 0000000..78cb07e
--- /dev/null
+++ b/client-next/src/components/VerifyEmailBanner.jsx
@@ -0,0 +1,36 @@
+'use client'
+
+import Link from 'next/link'
+import { useAuth } from '@/context/AuthContext'
+import { getApiUrl } from '@/lib/config'
+import styles from './VerifyEmailBanner.module.css'
+
+export default function VerifyEmailBanner() {
+  const { user } = useAuth()
+
+  if (!user || user.email_verified !== false) return null
+
+  async function handleResend() {
+    try {
+      await fetch(`${getApiUrl()}/auth/resend-verification`, {
+        method: 'POST',
+        credentials: 'include',
+      })
+    } catch {
+      // silent
+    }
+  }
+
+  return (
+    <div className={styles.banner} role="status">
+      <p>
+        Verify your email to post comments and start discussions.{' '}
+        <Link href="/verify-email">Check your inbox</Link>
+        {' · '}
+        <button type="button" className={styles.resend} onClick={handleResend}>
+          Resend email
+        </button>
+      </p>
+    </div>
+  )
+}
diff --git a/client-next/src/components/VerifyEmailBanner.module.css b/client-next/src/components/VerifyEmailBanner.module.css
new file mode 100644
index 0000000..bec72bf
--- /dev/null
+++ b/client-next/src/components/VerifyEmailBanner.module.css
@@ -0,0 +1,23 @@
+.banner {
+  background: rgba(139, 79, 79, 0.08);
+  border-bottom: 1px solid rgba(139, 79, 79, 0.2);
+  padding: var(--space-2) var(--space-4);
+  text-align: center;
+  font-size: var(--text-sm);
+  color: var(--text-secondary);
+}
+
+.banner a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+.resend {
+  background: none;
+  border: none;
+  padding: 0;
+  font: inherit;
+  color: var(--accent);
+  cursor: pointer;
+  text-decoration: underline;
+}
diff --git a/client-next/src/lib/api.js b/client-next/src/lib/api.js
index c280355..8bfaf6b 100644
--- a/client-next/src/lib/api.js
+++ b/client-next/src/lib/api.js
@@ -327,6 +327,7 @@ export function normalizeDiscussion(discussion) {
   return {
     ...discussion,
     username: discussion.username || discussion.started_by || null,
+    display_name: discussion.display_name || discussion.started_by_display_name || null,
     latest_activity:
       discussion.latest_activity ||
       discussion.bookmarked_at ||
diff --git a/docs/DEVELOPER_NOTES.md b/docs/DEVELOPER_NOTES.md
index 8921427..2f3904d 100644
--- a/docs/DEVELOPER_NOTES.md
+++ b/docs/DEVELOPER_NOTES.md
@@ -12,6 +12,7 @@ Technical architecture, design decisions, and implementation details for PostSch
 6. [Third-Party Integrations](#third-party-integrations)
 7. [Performance Considerations](#performance-considerations)
 8. [Known Limitations](#known-limitations)
+9. [Testing](./TESTING.md) — PR checklist and test commands
 
 ## Architecture Overview
 
@@ -144,13 +145,41 @@ Strategic indexes for common queries:
 ### JWT Authentication
 
 **Flow**:
-1. User logs in with email/password
-2. Server verifies credentials via bcrypt
+1. User signs in via email/password, ORCID, Google, or GitHub
+2. Server verifies credentials (bcrypt for local accounts; OAuth token exchange for social)
 3. Server generates JWT with user ID and username
 4. JWT stored in httpOnly cookie (not accessible to JavaScript)
 5. Subsequent requests include cookie automatically
 6. Server verifies JWT on protected routes via `authenticateToken` middleware
 
+### Email verification (local accounts)
+
+Email/password signups receive a verification link via Resend. Users can browse while unverified, but `requireVerifiedEmail` middleware blocks:
+- `POST /discussions` (start discussion)
+- `POST /discussions/:id/comments`
+
+OAuth users (Google, GitHub) and ORCID-linked users skip email verification.
+
+**Endpoints**:
+- `GET /auth/verify-email?token=` — marks account verified
+- `POST /auth/resend-verification` — authenticated resend (rate-limited)
+
+### Social sign-in
+
+| Provider | Routes | Notes |
+|----------|--------|-------|
+| Google | `GET /auth/google/url`, `POST /auth/google/callback` | Redirect URI: `{CLIENT_URL}/auth/google/callback` |
+| GitHub | `GET /auth/github/url`, `POST /auth/github/callback` | Scopes: `read:user`, `user:email` |
+| ORCID login | `GET /auth/orcid/login/url`, `POST /auth/orcid/callback` | New users → `POST /auth/complete` for username |
+| ORCID verify | `GET /auth/orcid/url?discussion_id=` | Author badge flow (unchanged) |
+
+**Env vars**: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, plus existing ORCID and Resend vars.
+
+### Display name
+
+- `username` — permanent handle for URLs and @mentions (read-only in settings)
+- `display_name` — optional human-readable name shown on profile and comments
+
 **Why httpOnly cookies?**
 - Prevents XSS attacks from stealing tokens
 - Browser handles cookie storage/sending automatically
diff --git a/docs/TESTING.md b/docs/TESTING.md
new file mode 100644
index 0000000..402e950
--- /dev/null
+++ b/docs/TESTING.md
@@ -0,0 +1,153 @@
+# Testing Guide
+
+What to run before opening a PR. PostScholar’s automated tests live on the **server** (Jest + Supertest). The Next.js client has lint only — no unit test suite yet.
+
+## Quick PR checklist
+
+From the repo root, with a local Postgres DB running and migrations applied:
+
+```bash
+npm run migrate          # apply any new migrations
+npm test                 # server integration tests
+npm run lint             # server + client ESLint
+npm run format:check     # optional — Prettier
+```
+
+If you changed auth, profiles, or OAuth, also run through the [manual smoke tests](#manual-smoke-tests-auth--profiles) below.
+
+---
+
+## Prerequisites
+
+### Database
+
+Tests hit a real Postgres database via `DATABASE_URL` in `server/.env`.
+
+```bash
+# From repo root
+npm run migrate
+```
+
+Or from `server/`:
+
+```bash
+cd server && npm run migrate
+```
+
+New migrations must be applied before tests that depend on new columns (e.g. `021_oauth_and_verification.sql`, `022_display_name.sql`).
+
+### Environment
+
+`server/.env` needs at least:
+
+- `DATABASE_URL`
+- `JWT_SECRET`
+- `CLIENT_URL` (e.g. `http://localhost:3001`)
+
+Tests set `NODE_ENV=test`. Verification emails are **not** sent in test mode. Resend is not required for `npm test`.
+
+---
+
+## Commands
+
+| Command | Where | What it does |
+|---------|--------|----------------|
+| `npm test` | repo root | Runs all server tests |
+| `npm test` | `server/` | Same |
+| `npm run lint` | repo root | ESLint on server + client |
+| `npm run lint` | `server/` or `client-next/` | Lint one package |
+| `npm run format:check` | repo root | Prettier check |
+| `cd client-next && npm run build` | client | Catches Next.js build errors |
+
+### Run a single test file
+
+```bash
+cd server
+npm test -- tests/auth.test.js
+npm test -- tests/auth-verify.test.js
+npm test -- tests/social.test.js
+npm test -- tests/papers.test.js
+```
+
+---
+
+## Test suites
+
+| File | Covers |
+|------|--------|
+| `auth.test.js` | Register, login, `/auth/me`, cookies |
+| `auth-verify.test.js` | Email verification gate, ORCID `/auth/complete`, OAuth URL 503 when unconfigured |
+| `social.test.js` | Follows, mentions, appreciation notifications, reports/moderation |
+| `papers.test.js` | Manual paper + discussion + comment flow |
+
+### Skipped / network tests
+
+`papers.test.js` includes CrossRef lookup tests that are **skipped locally** unless `CI` is set:
+
+```bash
+CI=1 npm test -- tests/papers.test.js
+```
+
+Only run that when you have network access and want to exercise live CrossRef — not required for most PRs.
+
+---
+
+## What tests do *not* cover
+
+- Google / GitHub OAuth token exchange (needs real OAuth apps + network)
+- Resend email delivery (skipped in `NODE_ENV=test`)
+- Browser UI / auth layout (manual or future E2E)
+- Full Next.js component tests
+
+---
+
+## Manual smoke tests (auth & profiles)
+
+After `npm run dev` (or with staging deployed), spot-check:
+
+1. **Register** — email account → redirect to `/verify-email`; banner shows when browsing
+2. **Verify** — click link in email (or use resend) → can post comments
+3. **Login** — email/password; forgot/reset password still works
+4. **Display name** — Settings → save → profile + comments show name; `@username` unchanged
+5. **ORCID login** — “Continue with ORCID” → new user → `/auth/complete` for username
+6. **ORCID verify** — on a discussion, author verify still works (separate from login)
+7. **Google / GitHub** — only after OAuth env vars and redirect URIs are configured
+
+---
+
+## Production deploy order
+
+When shipping auth/schema changes:
+
+1. **Push** code (server + client)
+2. **Deploy** server (Railway) and client (Vercel)
+3. **Migrate production DB** — `cd server && npm run migrate:railway`
+4. **Add OAuth env vars** on Railway (`GOOGLE_*`, `GITHUB_*`) and create OAuth apps with redirect URIs:
+   - `https://postscholar.org/auth/google/callback`
+   - `https://postscholar.org/auth/github/callback`
+   - `http://localhost:3001/auth/google/callback` (local dev)
+   - `http://localhost:3001/auth/github/callback` (local dev)
+
+Migrations should run **as soon as the new server code is live** — the API expects columns from `021` and `022`. OAuth env vars can be added after deploy; social buttons return a clear error until then.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `column "email_verified" does not exist` | Run `npm run migrate` |
+| Tests fail with 403 on POST `/discussions` | Test users need `email_verified = true` — see `server/tests/helpers.js` |
+| `ENOTFOUND api.resend.com` in test output | Harmless if `NODE_ENV=test`; verification send is skipped |
+| Port / DB connection errors | Check `DATABASE_URL` and that Postgres is running |
+
+---
+
+## Adding tests
+
+- Put new server tests in `server/tests/`
+- Use `supertest` against `require('../index')` — see existing files
+- For register flows, call `verifyTestUserByEmail()` from `helpers.js` if the test needs to post comments or start discussions
+- Prefer deterministic data (`Date.now()` / random suffix in emails and usernames) to avoid collisions
+
+See also [DEVELOPER_NOTES.md](./DEVELOPER_NOTES.md) for architecture and auth design.
diff --git a/server/.env.example b/server/.env.example
index ccfa137..6edd0df 100644
--- a/server/.env.example
+++ b/server/.env.example
@@ -15,6 +15,14 @@ NODE_ENV=development
 ORCID_CLIENT_ID=
 ORCID_CLIENT_SECRET=
 
+# Google OAuth (https://console.cloud.google.com/apis/credentials)
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+# GitHub OAuth (https://github.com/settings/developers)
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
 # Email (Resend — https://resend.com)
 RESEND_API_KEY=
 EMAIL_FROM=PostScholar <noreply@postscholar.org>
diff --git a/server/db/migrations/021_oauth_and_verification.sql b/server/db/migrations/021_oauth_and_verification.sql
new file mode 100644
index 0000000..3937bc6
--- /dev/null
+++ b/server/db/migrations/021_oauth_and_verification.sql
@@ -0,0 +1,24 @@
+-- OAuth providers and email verification for local signups
+
+ALTER TABLE users ALTER COLUMN password_hash DROP NOT NULL;
+ALTER TABLE users ALTER COLUMN email DROP NOT NULL;
+
+ALTER TABLE users ADD COLUMN IF NOT EXISTS google_id TEXT;
+ALTER TABLE users ADD COLUMN IF NOT EXISTS github_id TEXT;
+ALTER TABLE users ADD COLUMN IF NOT EXISTS email_verified BOOLEAN NOT NULL DEFAULT false;
+
+CREATE UNIQUE INDEX IF NOT EXISTS users_google_id_unique ON users(google_id) WHERE google_id IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS users_github_id_unique ON users(github_id) WHERE github_id IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS users_orcid_id_unique ON users(orcid_id) WHERE orcid_id IS NOT NULL;
+
+-- Grandfather existing accounts
+UPDATE users SET email_verified = true WHERE email_verified = false;
+
+CREATE TABLE IF NOT EXISTS email_verification_tokens (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token_hash TEXT NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  used_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
diff --git a/server/db/migrations/022_display_name.sql b/server/db/migrations/022_display_name.sql
new file mode 100644
index 0000000..00efce8
--- /dev/null
+++ b/server/db/migrations/022_display_name.sql
@@ -0,0 +1 @@
+ALTER TABLE users ADD COLUMN IF NOT EXISTS display_name TEXT;
diff --git a/server/index.js b/server/index.js
index 73b0320..2bb564b 100644
--- a/server/index.js
+++ b/server/index.js
@@ -57,10 +57,13 @@ app.use('/auth/login', authLimiter)
 app.use('/auth/register', authLimiter)
 app.use('/auth/forgot-password', authLimiter)
 app.use('/auth/reset-password', authLimiter)
+app.use('/auth/resend-verification', authLimiter)
 app.use('/', generalLimiter)
 
 app.use('/papers', require('./routes/papers'))
 app.use('/auth', require('./routes/auth'))
+app.use('/auth/google', require('./routes/google'))
+app.use('/auth/github', require('./routes/github'))
 app.use('/discussions', require('./routes/discussions'))
 app.use('/auth/orcid', require('./routes/orcid'))
 app.use('/users', require('./routes/users'))
diff --git a/server/lib/oauthUsers.js b/server/lib/oauthUsers.js
new file mode 100644
index 0000000..df89eef
--- /dev/null
+++ b/server/lib/oauthUsers.js
@@ -0,0 +1,46 @@
+const pool = require('../db')
+
+const USERNAME_REGEX = /^[a-z0-9_]{3,30}$/
+
+function sanitizeUsernameBase(value) {
+  let base = (value || 'user')
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '')
+  if (base.length < 3) base = `user_${base || 'x'}`
+  return base.slice(0, 26)
+}
+
+async function findAvailableUsername(base) {
+  const root = sanitizeUsernameBase(base)
+  for (let i = 0; i < 100; i++) {
+    const suffix = i === 0 ? '' : `_${i}`
+    const candidate = `${root}${suffix}`.slice(0, 30)
+    if (!USERNAME_REGEX.test(candidate)) continue
+    const existing = await pool.query(
+      'SELECT id FROM users WHERE username = $1',
+      [candidate]
+    )
+    if (existing.rows.length === 0) return candidate
+  }
+  return `user_${Date.now().toString(36).slice(-8)}`
+}
+
+function formatUserResponse(user) {
+  return {
+    id: user.id,
+    username: user.username,
+    email: user.email,
+    display_name: user.display_name || null,
+    role: user.role || 'user',
+    email_verified: user.email_verified,
+  }
+}
+
+module.exports = {
+  USERNAME_REGEX,
+  sanitizeUsernameBase,
+  findAvailableUsername,
+  formatUserResponse,
+}
diff --git a/server/lib/session.js b/server/lib/session.js
new file mode 100644
index 0000000..af9139b
--- /dev/null
+++ b/server/lib/session.js
@@ -0,0 +1,61 @@
+const jwt = require('jsonwebtoken')
+
+const JWT_EXPIRY = '7d'
+
+function signToken(payload) {
+  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: JWT_EXPIRY })
+}
+
+function tokenCookieOptions(maxAge) {
+  const isProd = process.env.NODE_ENV === 'production'
+  return {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: isProd,
+    path: '/',
+    maxAge,
+  }
+}
+
+function setTokenCookie(res, token) {
+  res.cookie('token', token, tokenCookieOptions(7 * 24 * 60 * 60 * 1000))
+}
+
+function clearTokenCookie(res) {
+  res.cookie('token', '', tokenCookieOptions(0))
+}
+
+function signOAuthState(payload, expiresIn = '10m') {
+  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn })
+}
+
+function verifyOAuthState(token) {
+  try {
+    return jwt.verify(token, process.env.JWT_SECRET)
+  } catch {
+    return null
+  }
+}
+
+function signCompletionToken(payload) {
+  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '30m' })
+}
+
+function verifyCompletionToken(token) {
+  try {
+    return jwt.verify(token, process.env.JWT_SECRET)
+  } catch {
+    return null
+  }
+}
+
+module.exports = {
+  signToken,
+  setTokenCookie,
+  clearTokenCookie,
+  signOAuthState,
+  verifyOAuthState,
+  signCompletionToken,
+  verifyCompletionToken,
+  JWT_EXPIRY,
+}
diff --git a/server/middleware/requireVerifiedEmail.js b/server/middleware/requireVerifiedEmail.js
new file mode 100644
index 0000000..ad0de07
--- /dev/null
+++ b/server/middleware/requireVerifiedEmail.js
@@ -0,0 +1,37 @@
+const pool = require('../db')
+
+/**
+ * Blocks posting for local email/password users until email is verified.
+ * OAuth and ORCID-linked users may post without email verification.
+ */
+async function requireVerifiedEmail(req, res, next) {
+  try {
+    const result = await pool.query(
+      `SELECT email_verified, google_id, github_id, orcid_id
+       FROM users WHERE id = $1`,
+      [req.user.userId]
+    )
+    const user = result.rows[0]
+    if (!user) {
+      return res.status(401).json({ error: 'Unauthorized' })
+    }
+
+    if (user.google_id || user.github_id || user.orcid_id) {
+      return next()
+    }
+
+    if (!user.email_verified) {
+      return res.status(403).json({
+        error: 'Please verify your email before posting',
+        code: 'EMAIL_UNVERIFIED',
+      })
+    }
+
+    return next()
+  } catch (err) {
+    console.error('requireVerifiedEmail error:', err)
+    return res.status(500).json({ error: 'Internal server error' })
+  }
+}
+
+module.exports = requireVerifiedEmail
diff --git a/server/routes/auth.js b/server/routes/auth.js
index 7438676..2dce760 100644
--- a/server/routes/auth.js
+++ b/server/routes/auth.js
@@ -1,203 +1,188 @@
 const express = require('express')
 const bcrypt = require('bcrypt')
-const jwt = require('jsonwebtoken')
 const crypto = require('crypto')
 const db = require('../db')
+const {
+  signToken,
+  setTokenCookie,
+  clearTokenCookie,
+  verifyCompletionToken,
+} = require('../lib/session')
+const {
+  USERNAME_REGEX,
+  findAvailableUsername,
+  formatUserResponse,
+} = require('../lib/oauthUsers')
 
 const router = express.Router()
+const authenticateToken = require('../middleware/authenticateToken')
 
-// bcrypt cost factor — 12 is slow enough to resist brute force,
-// fast enough to not noticeably delay login
 const BCRYPT_COST = 12
-
-// JWT expiry — 7 days, stored in an httpOnly cookie
-const JWT_EXPIRY = '7d'
-
-// Password reset token expiry — 1 hour
 const RESET_TOKEN_EXPIRY_MS = 60 * 60 * 1000
-
-// Username: 3-30 chars, lowercase letters, numbers, underscores only
-const USERNAME_REGEX = /^[a-z0-9_]{3,30}$/
-
-// Basic email format check — not exhaustive, just sanity validation
+const VERIFY_TOKEN_EXPIRY_MS = 24 * 60 * 60 * 1000
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+const DUMMY_HASH = '$2b$12$invalidhashfortimingprotectiononly000000000000000000000'
 
-/**
- * signToken(payload)
- * Signs a JWT with the app secret and 7-day expiry.
- * Payload contains { userId, username }.
- */
-function signToken(payload) {
-  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: JWT_EXPIRY })
-}
-
-/**
- * Cookie options for the JWT session.
- * Frontend proxies /api → backend (Vercel/Railway and local dev), so the
- * browser always talks same-origin and lax cookies work — including mobile Safari.
- */
-function tokenCookieOptions(maxAge) {
-  const isProd = process.env.NODE_ENV === 'production'
-  return {
-    httpOnly: true,
-    sameSite: 'lax',
-    secure: isProd,
-    path: '/',
-    maxAge,
-  }
-}
-
-function setTokenCookie(res, token) {
-  res.cookie('token', token, tokenCookieOptions(7 * 24 * 60 * 60 * 1000))
-}
-
-function clearTokenCookie(res) {
-  res.cookie('token', '', tokenCookieOptions(0))
-}
-
-/**
- * hashToken(rawToken)
- * SHA-256 hashes a raw token before storing in the DB.
- * We store only the hash so that a DB leak doesn't expose valid reset tokens,
- * similar to how we store password hashes instead of plaintext passwords.
- */
 function hashToken(rawToken) {
   return crypto.createHash('sha256').update(rawToken).digest('hex')
 }
 
-/**
- * sendResetEmail(email, resetUrl)
- * Sends a password reset email via Resend.
- * Uses onboarding@resend.dev as the sender until a custom domain is verified.
- */
-async function sendResetEmail(email, resetUrl) {
-  // console.log('Resend key loaded:', !!process.env.RESEND_API_KEY)
+async function sendEmail({ to, subject, html }) {
   const res = await fetch('https://api.resend.com/emails', {
     method: 'POST',
     headers: {
-      'Authorization': `Bearer ${process.env.RESEND_API_KEY}`,
-      'Content-Type': 'application/json'
+      Authorization: `Bearer ${process.env.RESEND_API_KEY}`,
+      'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       from: process.env.EMAIL_FROM || 'PostScholar <onboarding@resend.dev>',
-      to: email,
-      subject: 'Reset your PostScholar password',
-      html: `
-        <p>You requested a password reset for your PostScholar account.</p>
-        <p>Click the link below to reset your password. This link expires in 1 hour.</p>
-        <p><a href="${resetUrl}">${resetUrl}</a></p>
-        <p>If you did not request this, you can ignore this email.</p>
-      `
-    })
+      to,
+      subject,
+      html,
+    }),
   })
-
   if (!res.ok) {
     const err = await res.json()
     throw new Error(`Resend error: ${JSON.stringify(err)}`)
   }
 }
 
-// ---------------------------------------------------------------------------
-// POST /auth/register
-// ---------------------------------------------------------------------------
-// Creates a new user account, hashes the password with bcrypt, signs a JWT,
-// and sets it as an httpOnly cookie. Returns only the username on success.
-// ---------------------------------------------------------------------------
-router.post('/register', async (req, res) => {
-  const { email, username, password } = req.body
+async function sendResetEmail(email, resetUrl) {
+  await sendEmail({
+    to: email,
+    subject: 'Reset your PostScholar password',
+    html: `
+      <p>You requested a password reset for your PostScholar account.</p>
+      <p>Click the link below to reset your password. This link expires in 1 hour.</p>
+      <p><a href="${resetUrl}">${resetUrl}</a></p>
+      <p>If you did not request this, you can ignore this email.</p>
+    `,
+  })
+}
 
-  if (!email || !EMAIL_REGEX.test(email)) {
-    return res.status(400).json({ error: 'Invalid email' })
-  }
-  if (!username || !USERNAME_REGEX.test(username)) {
-    return res.status(400).json({ error: 'Username must be 3–30 characters, lowercase letters, numbers, and underscores only' })
-  }
-  if (!password || password.length < 8) {
-    return res.status(400).json({ error: 'Password must be at least 8 characters' })
-  }
+async function sendVerificationEmail(email, verifyUrl) {
+  if (process.env.NODE_ENV === 'test') return
+  await sendEmail({
+    to: email,
+    subject: 'Verify your PostScholar email',
+    html: `
+      <p>Welcome to PostScholar. Please verify your email address to post comments and start discussions.</p>
+      <p><a href="${verifyUrl}">${verifyUrl}</a></p>
+      <p>This link expires in 24 hours. You can browse discussions while you wait.</p>
+    `,
+  })
+}
+
+async function issueVerificationToken(userId) {
+  const rawToken = crypto.randomBytes(32).toString('hex')
+  const tokenHash = hashToken(rawToken)
+  const expiresAt = new Date(Date.now() + VERIFY_TOKEN_EXPIRY_MS)
 
-  // Check for duplicate email or username in one query
-  const existing = await db.query(
-    'SELECT id FROM users WHERE email = $1 OR username = $2',
-    [email, username]
+  await db.query(
+    'UPDATE email_verification_tokens SET used_at = NOW() WHERE user_id = $1 AND used_at IS NULL',
+    [userId]
   )
-  if (existing.rows.length > 0) {
-    return res.status(409).json({ error: 'Email or username already taken' })
-  }
+  await db.query(
+    'INSERT INTO email_verification_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)',
+    [userId, tokenHash, expiresAt]
+  )
+
+  return rawToken
+}
 
-  const password_hash = await bcrypt.hash(password, BCRYPT_COST)
+router.post('/register', async (req, res) => {
+  try {
+    const { email, username, password } = req.body
 
-  const result = await db.query(
-    'INSERT INTO users (email, username, password_hash) VALUES ($1, $2, $3) RETURNING id, username, email, role',
-    [email, username, password_hash]
-  )
-  const user = result.rows[0]
+    if (!email || !EMAIL_REGEX.test(email)) {
+      return res.status(400).json({ error: 'Invalid email' })
+    }
+    if (!username || !USERNAME_REGEX.test(username)) {
+      return res.status(400).json({
+        error: 'Username must be 3–30 characters, lowercase letters, numbers, and underscores only',
+      })
+    }
+    if (!password || password.length < 8) {
+      return res.status(400).json({ error: 'Password must be at least 8 characters' })
+    }
 
-  const token = signToken({ userId: user.id, username: user.username })
-  setTokenCookie(res, token)
+    const existing = await db.query(
+      'SELECT id FROM users WHERE email = $1 OR username = $2',
+      [email, username]
+    )
+    if (existing.rows.length > 0) {
+      return res.status(409).json({ error: 'Email or username already taken' })
+    }
 
-  res.status(201).json({
-    id: user.id,
-    username: user.username,
-    email: user.email,
-    role: user.role || 'user',
-  })
-})
+    const password_hash = await bcrypt.hash(password, BCRYPT_COST)
+    const result = await db.query(
+      `INSERT INTO users (email, username, password_hash, email_verified)
+       VALUES ($1, $2, $3, false)
+       RETURNING id, username, email, display_name, role, email_verified`,
+      [email, username, password_hash]
+    )
+    const user = result.rows[0]
 
-// ---------------------------------------------------------------------------
-// POST /auth/login
-// ---------------------------------------------------------------------------
-// Validates email + password, sets a new JWT cookie on success.
-//
-// Timing attack protection: if the user is not found, we still run bcrypt
-// compare against a dummy hash. This ensures the response time is the same
-// whether the email exists or not, preventing user enumeration via timing.
-// ---------------------------------------------------------------------------
-const DUMMY_HASH = '$2b$12$invalidhashfortimingprotectiononly000000000000000000000'
+    const token = signToken({ userId: user.id, username: user.username })
+    setTokenCookie(res, token)
 
-router.post('/login', async (req, res) => {
-  const { email, password } = req.body
+    try {
+      const rawToken = await issueVerificationToken(user.id)
+      const verifyUrl = `${process.env.CLIENT_URL}/verify-email?token=${rawToken}`
+      await sendVerificationEmail(user.email, verifyUrl)
+    } catch (err) {
+      console.error('Verification email failed:', err)
+    }
 
-  if (!email || !password) {
-    return res.status(400).json({ error: 'Email and password are required' })
+    res.status(201).json(formatUserResponse(user))
+  } catch (err) {
+    console.error('POST /auth/register error:', err)
+    res.status(500).json({ error: 'Internal server error' })
   }
+})
 
-  const result = await db.query(
-    'SELECT id, username, email, password_hash, role FROM users WHERE email = $1',
-    [email]
-  )
-  const user = result.rows[0]
+router.post('/login', async (req, res) => {
+  try {
+    const { email, password } = req.body
 
-  // Always run bcrypt.compare even if user not found (timing protection)
-  const hashToCompare = user ? user.password_hash : DUMMY_HASH
-  const match = await bcrypt.compare(password, hashToCompare)
+    if (!email || !password) {
+      return res.status(400).json({ error: 'Email and password are required' })
+    }
 
-  if (!user || !match) {
-    return res.status(401).json({ error: 'Invalid email or password' })
-  }
+    const result = await db.query(
+      `SELECT id, username, email, password_hash, display_name, role, email_verified,
+              google_id, github_id, orcid_id
+       FROM users WHERE email = $1`,
+      [email]
+    )
+    const user = result.rows[0]
 
-  const token = signToken({ userId: user.id, username: user.username })
-  setTokenCookie(res, token)
+    if (user && !user.password_hash && (user.google_id || user.github_id || user.orcid_id)) {
+      return res.status(400).json({
+        error: 'This account uses social sign-in. Please continue with ORCID, Google, or GitHub.',
+      })
+    }
 
-  res.status(200).json({
-    id: user.id,
-    username: user.username,
-    email: user.email,
-    role: user.role || 'user',
-  })
-})
+    const hashToCompare = user?.password_hash || DUMMY_HASH
+    const match = await bcrypt.compare(password, hashToCompare)
 
-const authenticateToken = require('../middleware/authenticateToken')
+    if (!user || !match) {
+      return res.status(401).json({ error: 'Invalid email or password' })
+    }
+
+    const token = signToken({ userId: user.id, username: user.username })
+    setTokenCookie(res, token)
+    res.status(200).json(formatUserResponse(user))
+  } catch (err) {
+    console.error('POST /auth/login error:', err)
+    res.status(500).json({ error: 'Internal server error' })
+  }
+})
 
-// ---------------------------------------------------------------------------
-// GET /auth/me
-// ---------------------------------------------------------------------------
-// Protected. Returns the currently authenticated user's profile.
-// Used by the frontend AuthContext on page load to restore session state.
-// ---------------------------------------------------------------------------
 router.get('/me', authenticateToken, async (req, res) => {
   const result = await db.query(
-    'SELECT id, username, email, role, created_at FROM users WHERE id = $1',
+    `SELECT id, username, email, display_name, role, created_at, email_verified
+     FROM users WHERE id = $1`,
     [req.user.userId]
   )
   if (!result.rows[0]) return res.status(404).json({ error: 'User not found' })
@@ -209,20 +194,140 @@ router.post('/logout', (req, res) => {
   res.json({ ok: true })
 })
 
-// ---------------------------------------------------------------------------
-// POST /auth/forgot-password
-// ---------------------------------------------------------------------------
-// Accepts an email address and sends a password reset link if the account
-// exists. Always returns 200 regardless of whether the email was found —
-// this prevents user enumeration (attacker can't tell if an email is registered
-// by observing the response).
-//
-// Flow:
-//   1. Look up user by email
-//   2. Generate a cryptographically random 32-byte token
-//   3. Hash it with SHA-256 and store in password_reset_tokens
-//   4. Send the raw token in a reset link via Resend
-// ---------------------------------------------------------------------------
+router.get('/verify-email', async (req, res) => {
+  try {
+    const { token } = req.query
+    if (!token || typeof token !== 'string') {
+      return res.status(400).json({ error: 'Token is required' })
+    }
+
+    const tokenHash = hashToken(token)
+    const tokenResult = await db.query(
+      `SELECT id, user_id, expires_at, used_at
+       FROM email_verification_tokens WHERE token_hash = $1`,
+      [tokenHash]
+    )
+    const verifyToken = tokenResult.rows[0]
+
+    if (!verifyToken) {
+      return res.status(400).json({ error: 'Invalid or expired verification token' })
+    }
+    if (verifyToken.used_at) {
+      return res.status(400).json({ error: 'Verification token has already been used' })
+    }
+    if (new Date() > new Date(verifyToken.expires_at)) {
+      return res.status(400).json({ error: 'Verification token has expired' })
+    }
+
+    const client = await db.connect()
+    try {
+      await client.query('BEGIN')
+      await client.query(
+        'UPDATE users SET email_verified = true WHERE id = $1',
+        [verifyToken.user_id]
+      )
+      await client.query(
+        'UPDATE email_verification_tokens SET used_at = NOW() WHERE id = $1',
+        [verifyToken.id]
+      )
+      await client.query('COMMIT')
+    } catch (err) {
+      await client.query('ROLLBACK')
+      throw err
+    } finally {
+      client.release()
+    }
+
+    res.json({ message: 'Email verified successfully' })
+  } catch (err) {
+    console.error('GET /auth/verify-email error:', err)
+    res.status(500).json({ error: 'Internal server error' })
+  }
+})
+
+router.post('/resend-verification', authenticateToken, async (req, res) => {
+  try {
+    const result = await db.query(
+      'SELECT id, email, email_verified FROM users WHERE id = $1',
+      [req.user.userId]
+    )
+    const user = result.rows[0]
+    if (!user) return res.status(404).json({ error: 'User not found' })
+    if (user.email_verified) {
+      return res.json({ message: 'Email already verified' })
+    }
+
+    const rawToken = await issueVerificationToken(user.id)
+    const verifyUrl = `${process.env.CLIENT_URL}/verify-email?token=${rawToken}`
+    await sendVerificationEmail(user.email, verifyUrl)
+
+    res.json({ message: 'Verification email sent' })
+  } catch (err) {
+    console.error('POST /auth/resend-verification error:', err)
+    res.status(500).json({ error: 'Internal server error' })
+  }
+})
+
+router.post('/complete', async (req, res) => {
+  try {
+    const { token, username, display_name } = req.body
+
+    if (!token || !username) {
+      return res.status(400).json({ error: 'Token and username are required' })
+    }
+    if (!USERNAME_REGEX.test(username)) {
+      return res.status(400).json({
+        error: 'Username must be 3–30 characters, lowercase letters, numbers, and underscores only',
+      })
+    }
+    if (display_name && display_name.trim().length > 50) {
+      return res.status(400).json({ error: 'Display name must be 50 characters or fewer' })
+    }
+
+    const payload = verifyCompletionToken(token)
+    if (!payload || payload.mode !== 'orcid_complete' || !payload.orcid_id) {
+      return res.status(400).json({ error: 'Invalid or expired completion token' })
+    }
+
+    const existingOrcid = await db.query(
+      'SELECT id FROM users WHERE orcid_id = $1',
+      [payload.orcid_id]
+    )
+    if (existingOrcid.rows.length > 0) {
+      return res.status(409).json({ error: 'ORCID account already registered' })
+    }
+
+    const existingUsername = await db.query(
+      'SELECT id FROM users WHERE username = $1',
+      [username]
+    )
+    if (existingUsername.rows.length > 0) {
+      return res.status(409).json({ error: 'Username already taken' })
+    }
+
+    const result = await db.query(
+      `INSERT INTO users (username, email, orcid_id, display_name, email_verified)
+       VALUES ($1, $2, $3, $4, true)
+       RETURNING id, username, email, display_name, role, email_verified`,
+      [
+        username,
+        payload.email || null,
+        payload.orcid_id,
+        display_name?.trim() || payload.display_name || null,
+      ]
+    )
+    const user = result.rows[0]
+
+    const sessionToken = signToken({ userId: user.id, username: user.username })
+    setTokenCookie(res, sessionToken)
+
+    res.status(201).json(formatUserResponse(user))
+  } catch (err) {
+    console.error('POST /auth/complete error:', err)
+    res.status(500).json({ error: 'Internal server error' })
+  }
+})
+
 router.post('/forgot-password', async (req, res) => {
   try {
     const { email } = req.body
@@ -232,35 +337,33 @@ router.post('/forgot-password', async (req, res) => {
     }
 
     const result = await db.query(
-      'SELECT id, email FROM users WHERE email = $1',
+      'SELECT id, email, password_hash FROM users WHERE email = $1',
       [email]
     )
     const user = result.rows[0]
 
-    // Always return success to prevent user enumeration
     if (!user) {
       return res.json({ message: 'If that email exists, a reset link has been sent' })
     }
 
-    // Generate a secure random token — 32 bytes = 64 hex chars
+    if (!user.password_hash) {
+      return res.json({ message: 'If that email exists, a reset link has been sent' })
+    }
+
     const rawToken = crypto.randomBytes(32).toString('hex')
     const tokenHash = hashToken(rawToken)
     const expiresAt = new Date(Date.now() + RESET_TOKEN_EXPIRY_MS)
 
-    // Invalidate any existing unused tokens for this user before creating a new one
     await db.query(
       'UPDATE password_reset_tokens SET used_at = NOW() WHERE user_id = $1 AND used_at IS NULL',
       [user.id]
     )
-
     await db.query(
       'INSERT INTO password_reset_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)',
       [user.id, tokenHash, expiresAt]
     )
 
-    // Build the reset URL — frontend will extract the token from the query string
     const resetUrl = `${process.env.CLIENT_URL}/reset-password?token=${rawToken}`
-
     await sendResetEmail(user.email, resetUrl)
 
     return res.json({ message: 'If that email exists, a reset link has been sent' })
@@ -270,16 +373,6 @@ router.post('/forgot-password', async (req, res) => {
   }
 })
 
-// ---------------------------------------------------------------------------
-// POST /auth/reset-password
-// ---------------------------------------------------------------------------
-// Accepts a raw reset token and a new password. Validates the token, updates
-// the password, and marks the token as used — all in a transaction.
-//
-// Body params:
-//   token       (string) — raw token from the reset link query string
-//   password    (string) — new password, min 8 chars
-// ---------------------------------------------------------------------------
 router.post('/reset-password', async (req, res) => {
   try {
     const { token, password } = req.body
@@ -291,16 +384,12 @@ router.post('/reset-password', async (req, res) => {
       return res.status(400).json({ error: 'Password must be at least 8 characters' })
     }
 
-    // Hash the incoming token to compare against stored hash
     const tokenHash = hashToken(token)
-
     const tokenResult = await db.query(
       `SELECT id, user_id, expires_at, used_at
-       FROM password_reset_tokens
-       WHERE token_hash = $1`,
+       FROM password_reset_tokens WHERE token_hash = $1`,
       [tokenHash]
     )
-
     const resetToken = tokenResult.rows[0]
 
     if (!resetToken) {
@@ -314,22 +403,17 @@ router.post('/reset-password', async (req, res) => {
     }
 
     const password_hash = await bcrypt.hash(password, BCRYPT_COST)
-
-    // Update password and mark token as used in a transaction
     const client = await db.connect()
     try {
       await client.query('BEGIN')
-
       await client.query(
         'UPDATE users SET password_hash = $1 WHERE id = $2',
         [password_hash, resetToken.user_id]
       )
-
       await client.query(
         'UPDATE password_reset_tokens SET used_at = NOW() WHERE id = $1',
         [resetToken.id]
       )
-
       await client.query('COMMIT')
     } catch (err) {
       await client.query('ROLLBACK')
@@ -346,4 +430,3 @@ router.post('/reset-password', async (req, res) => {
 })
 
 module.exports = router
-
diff --git a/server/routes/discussions.js b/server/routes/discussions.js
index 7d5949b..2b9bd8f 100644
--- a/server/routes/discussions.js
+++ b/server/routes/discussions.js
@@ -2,6 +2,7 @@ const express = require('express')
 const router = express.Router()
 const pool = require('../db')
 const authenticateToken = require('../middleware/authenticateToken')
+const requireVerifiedEmail = require('../middleware/requireVerifiedEmail')
 const optionalAuth = require('../middleware/optionalAuth')
 const sanitizeHtml = require('sanitize-html')
 
@@ -165,7 +166,7 @@ router.get('/:id/comments', optionalAuth, async (req, res) => {
     // Fetch one extra row to detect if a next page exists
     // Join users to get username for display
     const topLevelResult = await pool.query(
-      `SELECT c.*, u.username FROM comments c
+      `SELECT c.*, u.username, u.display_name FROM comments c
        JOIN users u ON u.id = c.user_id
        WHERE c.discussion_id = $1
          AND c.parent_comment_id IS NULL
@@ -187,11 +188,11 @@ router.get('/:id/comments', optionalAuth, async (req, res) => {
       // Fetch all descendants of this page's top-level comments recursively
       const descendantsResult = await pool.query(
         `WITH RECURSIVE descendants AS (
-           SELECT c.*, u.username FROM comments c
+           SELECT c.*, u.username, u.display_name FROM comments c
            JOIN users u ON u.id = c.user_id
            WHERE c.parent_comment_id = ANY($1::uuid[])
            UNION ALL
-           SELECT c.*, u.username FROM comments c
+           SELECT c.*, u.username, u.display_name FROM comments c
            JOIN users u ON u.id = c.user_id
            INNER JOIN descendants d ON c.parent_comment_id = d.id
          )
@@ -292,7 +293,7 @@ router.get('/:id/comments/search', optionalAuth, async (req, res) => {
 //
 // Depth is computed server-side as parent.depth + 1.
 // ---------------------------------------------------------------------------
-router.post('/:id/comments', authenticateToken, async (req, res) => {
+router.post('/:id/comments', authenticateToken, requireVerifiedEmail, async (req, res) => {
   try {
     const { id: discussion_id } = req.params
     const { body, parent_comment_id } = req.body
@@ -349,7 +350,8 @@ router.post('/:id/comments', authenticateToken, async (req, res) => {
     const result = await pool.query(
       `INSERT INTO comments (discussion_id, user_id, parent_comment_id, body, depth)
        VALUES ($1, $2, $3, $4, $5)
-       RETURNING *, (SELECT username FROM users WHERE id = $2) AS username`,
+       RETURNING *, (SELECT username FROM users WHERE id = $2) AS username,
+       (SELECT display_name FROM users WHERE id = $2) AS display_name`,
       [discussion_id, req.user.userId, parent_comment_id || null, sanitizedBody, depth]
     )
 
@@ -599,7 +601,8 @@ router.get('/:id/paper', optionalAuth, async (req, res) => {
               d.id AS discussion_id,
               d.created_at AS discussion_created_at,
               d.custom_tags,
-              u.username AS started_by
+              u.username AS started_by,
+              u.display_name AS started_by_display_name
        FROM papers p
        JOIN discussions d ON d.paper_id = p.id
        LEFT JOIN users u ON u.id = d.created_by
@@ -622,7 +625,8 @@ router.get('/:id/paper', optionalAuth, async (req, res) => {
       discussion_id: row.discussion_id,
       discussion_created_at: row.discussion_created_at,
       custom_tags: row.custom_tags,
-      started_by: row.started_by
+      started_by: row.started_by,
+      started_by_display_name: row.started_by_display_name,
     })
   } catch (err) {
     console.error('GET /discussions/:id/paper error:', err)
@@ -644,7 +648,7 @@ router.get('/:id/paper', optionalAuth, async (req, res) => {
 //   topics      (UUID[], optional) — topic IDs from the taxonomy
 //   custom_tags (string[], optional) — free-text tags
 // ---------------------------------------------------------------------------
-router.post('/', authenticateToken, async (req, res) => {
+router.post('/', authenticateToken, requireVerifiedEmail, async (req, res) => {
   try {
     const { paper_id, topics = [], custom_tags = [] } = req.body
 
@@ -776,6 +780,7 @@ router.get('/following', authenticateToken, async (req, res) => {
       SELECT d.id, d.created_at, d.created_by, d.custom_tags,
              p.title, p.authors_json, p.journal, p.year, p.doi,
              u.username,
+             u.display_name,
              COUNT(c.id)::int AS comment_count,
              COALESCE(MAX(c.created_at), d.created_at) AS latest_activity,
              COALESCE(
@@ -806,7 +811,7 @@ router.get('/following', authenticateToken, async (req, res) => {
 
     query += `
       GROUP BY d.id, d.custom_tags, d.created_by, d.created_at,
-               p.title, p.authors_json, p.journal, p.year, p.doi, u.username
+               p.title, p.authors_json, p.journal, p.year, p.doi, u.username, u.display_name
       ORDER BY d.created_at DESC
       LIMIT $${paramCount}
     `
diff --git a/server/routes/explore.js b/server/routes/explore.js
index 4d9ea10..68afbee 100644
--- a/server/routes/explore.js
+++ b/server/routes/explore.js
@@ -57,6 +57,7 @@ router.get('/explore/active', async (req, res) => {
          p.journal,
          p.year,
          u.username,
+         u.display_name,
          (
            SELECT COUNT(*)
            FROM comments c
@@ -234,6 +235,7 @@ router.get('/explore', optionalAuth, async (req, res) => {
          p.journal,
          p.year,
          u.username,
+         u.display_name,
          (
            SELECT COUNT(*)
            FROM comments c
diff --git a/server/routes/github.js b/server/routes/github.js
new file mode 100644
index 0000000..e938003
--- /dev/null
+++ b/server/routes/github.js
@@ -0,0 +1,121 @@
+const express = require('express')
+const {
+  signToken,
+  setTokenCookie,
+  signOAuthState,
+  verifyOAuthState,
+} = require('../lib/session')
+const { formatUserResponse } = require('../lib/oauthUsers')
+const { findOrCreateOAuthUser } = require('./google')
+
+const router = express.Router()
+
+const GITHUB_AUTH_URL = 'https://github.com/login/oauth/authorize'
+const GITHUB_TOKEN_URL = 'https://github.com/login/oauth/access_token'
+
+router.get('/url', (req, res) => {
+  if (!process.env.GITHUB_CLIENT_ID) {
+    return res.status(503).json({ error: 'GitHub sign-in is not configured' })
+  }
+
+  const state = signOAuthState({ provider: 'github', mode: 'login' })
+  const params = new URLSearchParams({
+    client_id: process.env.GITHUB_CLIENT_ID,
+    redirect_uri: `${process.env.CLIENT_URL}/auth/github/callback`,
+    scope: 'read:user user:email',
+    state,
+  })
+
+  res.json({ url: `${GITHUB_AUTH_URL}?${params.toString()}` })
+})
+
+router.post('/callback', async (req, res) => {
+  try {
+    const { code, state } = req.body
+    if (!code || !state) {
+      return res.status(400).json({ error: 'code and state are required' })
+    }
+
+    const statePayload = verifyOAuthState(state)
+    if (!statePayload || statePayload.provider !== 'github') {
+      return res.status(400).json({ error: 'Invalid or expired state' })
+    }
+
+    const tokenRes = await fetch(GITHUB_TOKEN_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body: new URLSearchParams({
+        code,
+        client_id: process.env.GITHUB_CLIENT_ID,
+        client_secret: process.env.GITHUB_CLIENT_SECRET,
+        redirect_uri: `${process.env.CLIENT_URL}/auth/github/callback`,
+      }),
+    })
+
+    if (!tokenRes.ok) {
+      return res.status(502).json({ error: 'Failed to exchange GitHub code' })
+    }
+
+    const tokenData = await tokenRes.json()
+    const accessToken = tokenData.access_token
+    if (!accessToken) {
+      return res.status(502).json({ error: 'Failed to obtain GitHub access token' })
+    }
+
+    const [profileRes, emailsRes] = await Promise.all([
+      fetch('https://api.github.com/user', {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: 'application/vnd.github+json',
+          'User-Agent': 'PostScholar',
+        },
+      }),
+      fetch('https://api.github.com/user/emails', {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: 'application/vnd.github+json',
+          'User-Agent': 'PostScholar',
+        },
+      }),
+    ])
+
+    if (!profileRes.ok) {
+      return res.status(502).json({ error: 'Failed to fetch GitHub profile' })
+    }
+
+    const profile = await profileRes.json()
+    let email = profile.email
+    let emailVerified = false
+
+    if (emailsRes.ok) {
+      const emails = await emailsRes.json()
+      const primary = emails.find(e => e.primary && e.verified)
+        || emails.find(e => e.verified)
+      if (primary) {
+        email = primary.email
+        emailVerified = primary.verified
+      }
+    }
+
+    const user = await findOrCreateOAuthUser({
+      provider: 'github',
+      providerId: String(profile.id),
+      email,
+      emailVerified,
+      displayName: profile.name || profile.login,
+      usernameBase: profile.login || email?.split('@')[0] || 'user',
+    })
+
+    const sessionToken = signToken({ userId: user.id, username: user.username })
+    setTokenCookie(res, sessionToken)
+    res.json(formatUserResponse(user))
+  } catch (err) {
+    console.error('POST /auth/github/callback error:', err)
+    res.status(500).json({ error: 'Internal server error' })
+  }
+})
+
+module.exports = router
diff --git a/server/routes/google.js b/server/routes/google.js
new file mode 100644
index 0000000..fd4c6f5
--- /dev/null
+++ b/server/routes/google.js
@@ -0,0 +1,148 @@
+const express = require('express')
+const db = require('../db')
+const {
+  signToken,
+  setTokenCookie,
+  signOAuthState,
+  verifyOAuthState,
+} = require('../lib/session')
+const { findAvailableUsername, formatUserResponse } = require('../lib/oauthUsers')
+
+const router = express.Router()
+
+const GOOGLE_AUTH_URL = 'https://accounts.google.com/o/oauth2/v2/auth'
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token'
+const GOOGLE_USERINFO_URL = 'https://www.googleapis.com/oauth2/v2/userinfo'
+
+router.get('/url', (req, res) => {
+  if (!process.env.GOOGLE_CLIENT_ID) {
+    return res.status(503).json({ error: 'Google sign-in is not configured' })
+  }
+
+  const state = signOAuthState({ provider: 'google', mode: 'login' })
+  const params = new URLSearchParams({
+    client_id: process.env.GOOGLE_CLIENT_ID,
+    redirect_uri: `${process.env.CLIENT_URL}/auth/google/callback`,
+    response_type: 'code',
+    scope: 'openid email profile',
+    state,
+    access_type: 'online',
+    prompt: 'select_account',
+  })
+
+  res.json({ url: `${GOOGLE_AUTH_URL}?${params.toString()}` })
+})
+
+router.post('/callback', async (req, res) => {
+  try {
+    const { code, state } = req.body
+    if (!code || !state) {
+      return res.status(400).json({ error: 'code and state are required' })
+    }
+
+    const statePayload = verifyOAuthState(state)
+    if (!statePayload || statePayload.provider !== 'google') {
+      return res.status(400).json({ error: 'Invalid or expired state' })
+    }
+
+    const tokenRes = await fetch(GOOGLE_TOKEN_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        code,
+        client_id: process.env.GOOGLE_CLIENT_ID,
+        client_secret: process.env.GOOGLE_CLIENT_SECRET,
+        redirect_uri: `${process.env.CLIENT_URL}/auth/google/callback`,
+        grant_type: 'authorization_code',
+      }),
+    })
+
+    if (!tokenRes.ok) {
+      return res.status(502).json({ error: 'Failed to exchange Google code' })
+    }
+
+    const tokenData = await tokenRes.json()
+    const userRes = await fetch(GOOGLE_USERINFO_URL, {
+      headers: { Authorization: `Bearer ${tokenData.access_token}` },
+    })
+
+    if (!userRes.ok) {
+      return res.status(502).json({ error: 'Failed to fetch Google profile' })
+    }
+
+    const profile = await userRes.json()
+    if (!profile.id) {
+      return res.status(502).json({ error: 'Invalid Google profile' })
+    }
+
+    const user = await findOrCreateOAuthUser({
+      provider: 'google',
+      providerId: profile.id,
+      email: profile.email,
+      emailVerified: profile.verified_email !== false,
+      displayName: profile.name,
+      usernameBase: profile.email?.split('@')[0] || profile.given_name || 'user',
+    })
+
+    const sessionToken = signToken({ userId: user.id, username: user.username })
+    setTokenCookie(res, sessionToken)
+    res.json(formatUserResponse(user))
+  } catch (err) {
+    console.error('POST /auth/google/callback error:', err)
+    res.status(500).json({ error: 'Internal server error' })
+  }
+})
+
+async function findOrCreateOAuthUser({
+  provider,
+  providerId,
+  email,
+  emailVerified,
+  displayName,
+  usernameBase,
+}) {
+  const idColumn = provider === 'google' ? 'google_id' : 'github_id'
+
+  const byProvider = await db.query(
+    `SELECT id, username, email, display_name, role, email_verified
+     FROM users WHERE ${idColumn} = $1`,
+    [providerId]
+  )
+  if (byProvider.rows[0]) return byProvider.rows[0]
+
+  if (email) {
+    const byEmail = await db.query(
+      `SELECT id, username, email, display_name, role, email_verified, google_id, github_id
+       FROM users WHERE email = $1`,
+      [email]
+    )
+    if (byEmail.rows[0]) {
+      const existing = byEmail.rows[0]
+      await db.query(
+        `UPDATE users
+         SET ${idColumn} = $1,
+             email_verified = CASE WHEN $2 THEN true ELSE email_verified END,
+             display_name = COALESCE(display_name, $3)
+         WHERE id = $4`,
+        [providerId, emailVerified, displayName || null, existing.id]
+      )
+      const updated = await db.query(
+        `SELECT id, username, email, display_name, role, email_verified FROM users WHERE id = $1`,
+        [existing.id]
+      )
+      return updated.rows[0]
+    }
+  }
+
+  const username = await findAvailableUsername(usernameBase)
+  const result = await db.query(
+    `INSERT INTO users (username, email, ${idColumn}, display_name, email_verified)
+     VALUES ($1, $2, $3, $4, $5)
+     RETURNING id, username, email, display_name, role, email_verified`,
+    [username, email || null, providerId, displayName || null, emailVerified]
+  )
+  return result.rows[0]
+}
+
+module.exports = router
+module.exports.findOrCreateOAuthUser = findOrCreateOAuthUser
diff --git a/server/routes/orcid.js b/server/routes/orcid.js
index 5a3033f..d8b8346 100644
--- a/server/routes/orcid.js
+++ b/server/routes/orcid.js
@@ -3,29 +3,23 @@ const router = express.Router()
 const jwt = require('jsonwebtoken')
 const pool = require('../db')
 const authenticateToken = require('../middleware/authenticateToken')
+const {
+  signToken,
+  setTokenCookie,
+  signOAuthState,
+  verifyOAuthState,
+  signCompletionToken,
+} = require('../lib/session')
+const { formatUserResponse } = require('../lib/oauthUsers')
 
-// ORCID OAuth endpoints
 const ORCID_AUTH_URL = 'https://orcid.org/oauth/authorize'
 const ORCID_TOKEN_URL = 'https://orcid.org/oauth/token'
-
-// Short-lived JWT expiry for OAuth state parameter
 const STATE_EXPIRY = '10m'
 
-/**
- * signState(payload)
- * Signs a short-lived JWT to use as the OAuth state parameter.
- * The state carries the discussion_id and userId through the OAuth redirect
- * so we know which discussion to verify for and which user is verifying.
- * Using a signed JWT prevents CSRF — an attacker cannot forge a valid state.
- */
 function signState(payload) {
   return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: STATE_EXPIRY })
 }
 
-/**
- * verifyState(token)
- * Verifies and decodes the state JWT. Returns null if invalid or expired.
- */
 function verifyState(token) {
   try {
     return jwt.verify(token, process.env.JWT_SECRET)
@@ -34,50 +28,67 @@ function verifyState(token) {
   }
 }
 
-/**
- * normalizeOrcidName(given, family)
- * Normalizes a name from ORCID into lowercase trimmed parts for comparison.
- * ORCID returns given (first) and family (last) name separately.
- */
 function normalizeOrcidName(given, family) {
   return {
     given: (given || '').toLowerCase().trim(),
-    family: (family || '').toLowerCase().trim()
+    family: (family || '').toLowerCase().trim(),
   }
 }
 
-/**
- * matchesAuthor(orcidName, authors)
- * Checks if the ORCID name matches any author in the paper's authors_json.
- * Matching is done on family name exact match + given name starts-with check.
- * The starts-with check handles cases where CrossRef stores "John" but ORCID
- * has "John Michael" or vice versa.
- */
 function matchesAuthor(orcidName, authors) {
   for (const author of authors) {
     const authorFamily = (author.family || '').toLowerCase().trim()
     const authorGiven = (author.given || '').toLowerCase().trim()
-
     const familyMatch = authorFamily === orcidName.family
     const givenMatch =
       authorGiven.startsWith(orcidName.given) ||
       orcidName.given.startsWith(authorGiven)
-
     if (familyMatch && givenMatch) return true
   }
   return false
 }
 
-// ---------------------------------------------------------------------------
-// GET /auth/orcid/url
-// ---------------------------------------------------------------------------
-// Protected. Returns the ORCID OAuth authorization URL for the client to
-// redirect to. Accepts ?discussion_id= as a query parameter.
-//
-// The state parameter is a signed JWT containing { userId, discussion_id }.
-// This survives the redirect and lets us verify who is authenticating and
-// for which discussion, without storing anything server-side.
-// ---------------------------------------------------------------------------
+function buildOrcidAuthUrl(state) {
+  const params = new URLSearchParams({
+    client_id: process.env.ORCID_CLIENT_ID,
+    response_type: 'code',
+    scope: '/authenticate',
+    redirect_uri: `${process.env.CLIENT_URL}/orcid/callback`,
+    state,
+  })
+  return `${ORCID_AUTH_URL}?${params.toString()}`
+}
+
+async function exchangeOrcidCode(code) {
+  const tokenRes = await fetch(ORCID_TOKEN_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: new URLSearchParams({
+      client_id: process.env.ORCID_CLIENT_ID,
+      client_secret: process.env.ORCID_CLIENT_SECRET,
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: `${process.env.CLIENT_URL}/orcid/callback`,
+    }),
+  })
+
+  if (!tokenRes.ok) return null
+  return tokenRes.json()
+}
+
+// GET /auth/orcid/url?mode=login
+router.get('/login/url', (req, res) => {
+  if (!process.env.ORCID_CLIENT_ID) {
+    return res.status(503).json({ error: 'ORCID sign-in is not configured' })
+  }
+  const state = signOAuthState({ mode: 'login', provider: 'orcid' })
+  return res.json({ url: buildOrcidAuthUrl(state) })
+})
+
+// GET /auth/orcid/url?discussion_id=... (author verify — requires auth)
 router.get('/url', authenticateToken, async (req, res) => {
   const { discussion_id } = req.query
 
@@ -85,7 +96,6 @@ router.get('/url', authenticateToken, async (req, res) => {
     return res.status(400).json({ error: 'discussion_id is required' })
   }
 
-  // Confirm the discussion exists
   const discussionCheck = await pool.query(
     'SELECT id FROM discussions WHERE id = $1',
     [discussion_id]
@@ -94,7 +104,6 @@ router.get('/url', authenticateToken, async (req, res) => {
     return res.status(404).json({ error: 'Discussion not found' })
   }
 
-  // Check if already verified for this discussion
   const existing = await pool.query(
     'SELECT id FROM author_verifications WHERE user_id = $1 AND discussion_id = $2',
     [req.user.userId, discussion_id]
@@ -103,43 +112,12 @@ router.get('/url', authenticateToken, async (req, res) => {
     return res.status(409).json({ error: 'Already verified as author for this discussion' })
   }
 
-  // Build the state JWT
-  const state = signState({ userId: req.user.userId, discussion_id })
-
-  // Build the ORCID OAuth URL
-  const params = new URLSearchParams({
-    client_id: process.env.ORCID_CLIENT_ID,
-    response_type: 'code',
-    scope: '/authenticate',
-    redirect_uri: `${process.env.CLIENT_URL}/orcid/callback`,
-    state
-  })
-
-  return res.json({ url: `${ORCID_AUTH_URL}?${params.toString()}` })
+  const state = signState({ mode: 'verify', userId: req.user.userId, discussion_id })
+  return res.json({ url: buildOrcidAuthUrl(state) })
 })
 
-// ---------------------------------------------------------------------------
-// POST /auth/orcid/callback
-// ---------------------------------------------------------------------------
-// Protected. Called by the frontend after ORCID redirects back with a code.
-// Exchanges the code for an access token, retrieves the user's ORCID name,
-// checks if it matches any author on the paper, and stores the verification.
-//
-// Body params:
-//   code          (string) — the OAuth authorization code from ORCID
-//   state         (string) — the signed state JWT from the initial redirect
-//
-// Flow:
-//   1. Verify the state JWT → extract userId and discussion_id
-//   2. Confirm the authenticated user matches the userId in state (CSRF check)
-//   3. Exchange code for ORCID access token
-//   4. Extract ORCID iD and name from token response
-//   5. Fetch the paper's authors_json via the discussion
-//   6. Check if ORCID name matches any author
-//   7. If match → insert into author_verifications
-//   8. Return { verified: true/false }
-// ---------------------------------------------------------------------------
-router.post('/callback', authenticateToken, async (req, res) => {
+// POST /auth/orcid/callback — handles login and verify modes
+router.post('/callback', async (req, res) => {
   try {
     const { code, state } = req.body
 
@@ -147,97 +125,132 @@ router.post('/callback', authenticateToken, async (req, res) => {
       return res.status(400).json({ error: 'code and state are required' })
     }
 
-    // Verify the state JWT
-    const statePayload = verifyState(state)
+    const statePayload = verifyOAuthState(state) || verifyState(state)
     if (!statePayload) {
       return res.status(400).json({ error: 'Invalid or expired state' })
     }
 
-    // CSRF check — the user in the cookie must match the user in the state
-    if (statePayload.userId !== req.user.userId) {
-      return res.status(403).json({ error: 'State mismatch' })
-    }
-
-    const { discussion_id } = statePayload
-
-    // Check if already verified
-    const existing = await pool.query(
-      'SELECT id FROM author_verifications WHERE user_id = $1 AND discussion_id = $2',
-      [req.user.userId, discussion_id]
-    )
-    if (existing.rows.length > 0) {
-      return res.status(409).json({ error: 'Already verified as author for this discussion' })
-    }
-
-    // Exchange the authorization code for an access token
-    const tokenRes = await fetch(ORCID_TOKEN_URL, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/x-www-form-urlencoded',
-        'Accept': 'application/json'
-      },
-      body: new URLSearchParams({
-        client_id: process.env.ORCID_CLIENT_ID,
-        client_secret: process.env.ORCID_CLIENT_SECRET,
-        grant_type: 'authorization_code',
-        code,
-        redirect_uri: `${process.env.CLIENT_URL}/orcid/callback`
-      })
-    })
-
-    if (!tokenRes.ok) {
+    const tokenData = await exchangeOrcidCode(code)
+    if (!tokenData) {
       return res.status(502).json({ error: 'Failed to exchange ORCID code' })
     }
 
-    const tokenData = await tokenRes.json()
-
-    // The token response contains the ORCID iD and name directly —
-    // no need for a separate API call for basic verification
     const orcidId = tokenData.orcid
     const orcidGiven = tokenData.name?.given_names?.value || ''
     const orcidFamily = tokenData.name?.family_name?.value || ''
+    const displayName = [orcidGiven, orcidFamily].filter(Boolean).join(' ').trim() || null
 
     if (!orcidId) {
       return res.status(502).json({ error: 'Could not retrieve ORCID iD' })
     }
 
-    // Fetch the paper's authors via the discussion
-    const paperResult = await pool.query(
-      `SELECT p.authors_json FROM papers p
-       JOIN discussions d ON d.paper_id = p.id
-       WHERE d.id = $1`,
-      [discussion_id]
-    )
-
-    if (paperResult.rows.length === 0) {
-      return res.status(404).json({ error: 'Discussion or paper not found' })
-    }
-
-    const authors = paperResult.rows[0].authors_json
-
-    // Compare ORCID name against paper authors
-    const orcidName = normalizeOrcidName(orcidGiven, orcidFamily)
-    const isAuthor = matchesAuthor(orcidName, authors)
-
-    if (!isAuthor) {
-      return res.json({
-        verified: false,
-        reason: 'Your ORCID name does not match any author on this paper'
-      })
+    if (statePayload.mode === 'login') {
+      return handleOrcidLogin(req, res, { orcidId, displayName })
     }
 
-    // Store the verification
-    await pool.query(
-      `INSERT INTO author_verifications (user_id, discussion_id, orcid_id)
-       VALUES ($1, $2, $3)`,
-      [req.user.userId, discussion_id, orcidId]
-    )
-
-    return res.json({ verified: true, orcid_id: orcidId })
+    return handleOrcidVerify(req, res, {
+      statePayload,
+      orcidId,
+      orcidGiven,
+      orcidFamily,
+    })
   } catch (err) {
     console.error('POST /auth/orcid/callback error:', err)
     res.status(500).json({ error: 'Internal server error' })
   }
 })
 
+async function handleOrcidLogin(req, res, { orcidId, displayName }) {
+  const existing = await pool.query(
+    `SELECT id, username, email, display_name, role, email_verified
+     FROM users WHERE orcid_id = $1`,
+    [orcidId]
+  )
+
+  if (existing.rows[0]) {
+    const user = existing.rows[0]
+    const sessionToken = signToken({ userId: user.id, username: user.username })
+    setTokenCookie(res, sessionToken)
+    return res.json({ ...formatUserResponse(user), mode: 'login' })
+  }
+
+  const completionToken = signCompletionToken({
+    mode: 'orcid_complete',
+    orcid_id: orcidId,
+    display_name: displayName,
+    email: null,
+  })
+
+  return res.json({
+    needs_completion: true,
+    completion_token: completionToken,
+    display_name: displayName,
+    mode: 'login',
+  })
+}
+
+async function handleOrcidVerify(req, res, { statePayload, orcidId, orcidGiven, orcidFamily }) {
+  const token = req.cookies?.token
+  if (!token) {
+    return res.status(401).json({ error: 'Authentication required for author verification' })
+  }
+
+  let decoded
+  try {
+    decoded = jwt.verify(token, process.env.JWT_SECRET)
+  } catch {
+    return res.status(401).json({ error: 'Invalid session' })
+  }
+
+  if (statePayload.userId !== decoded.userId) {
+    return res.status(403).json({ error: 'State mismatch' })
+  }
+
+  const { discussion_id } = statePayload
+
+  const existing = await pool.query(
+    'SELECT id FROM author_verifications WHERE user_id = $1 AND discussion_id = $2',
+    [decoded.userId, discussion_id]
+  )
+  if (existing.rows.length > 0) {
+    return res.status(409).json({ error: 'Already verified as author for this discussion' })
+  }
+
+  const paperResult = await pool.query(
+    `SELECT p.authors_json FROM papers p
+     JOIN discussions d ON d.paper_id = p.id
+     WHERE d.id = $1`,
+    [discussion_id]
+  )
+
+  if (paperResult.rows.length === 0) {
+    return res.status(404).json({ error: 'Discussion or paper not found' })
+  }
+
+  const authors = paperResult.rows[0].authors_json
+  const orcidName = normalizeOrcidName(orcidGiven, orcidFamily)
+  const isAuthor = matchesAuthor(orcidName, authors)
+
+  if (!isAuthor) {
+    return res.json({
+      verified: false,
+      reason: 'Your ORCID name does not match any author on this paper',
+      mode: 'verify',
+    })
+  }
+
+  await pool.query(
+    'UPDATE users SET orcid_id = COALESCE(orcid_id, $1) WHERE id = $2',
+    [orcidId, decoded.userId]
+  )
+
+  await pool.query(
+    `INSERT INTO author_verifications (user_id, discussion_id, orcid_id)
+     VALUES ($1, $2, $3)`,
+    [decoded.userId, discussion_id, orcidId]
+  )
+
+  return res.json({ verified: true, orcid_id: orcidId, mode: 'verify' })
+}
+
 module.exports = router
diff --git a/server/routes/search.js b/server/routes/search.js
index f90f701..0acca22 100644
--- a/server/routes/search.js
+++ b/server/routes/search.js
@@ -21,12 +21,13 @@ router.get('/', optionalAuth, async (req, res) => {
         `SELECT
            id,
            username,
+           display_name,
            bio,
            affiliation,
            created_at,
            (SELECT COUNT(*) FROM discussions WHERE created_by = users.id) as discussion_count
          FROM users
-         WHERE ($1 = '' OR username ILIKE $2 OR bio ILIKE $2 OR affiliation ILIKE $2)
+         WHERE ($1 = '' OR username ILIKE $2 OR display_name ILIKE $2 OR bio ILIKE $2 OR affiliation ILIKE $2)
          ORDER BY discussion_count DESC
          LIMIT 20`,
         [q, `%${q}%`]
diff --git a/server/routes/users.js b/server/routes/users.js
index 1c5c627..6599865 100644
--- a/server/routes/users.js
+++ b/server/routes/users.js
@@ -74,7 +74,7 @@ router.get('/suggested', optionalAuth, async (req, res) => {
 router.get('/me', authenticateToken, async (req, res) => {
   try {
     const result = await pool.query(
-      `SELECT id, username, bio, avatar_url, profile_visibility, affiliation,
+      `SELECT id, username, display_name, bio, avatar_url, profile_visibility, affiliation,
               location, website_url, twitter_handle, google_scholar_url,
               orcid_id, created_at
        FROM users WHERE id = $1`,
@@ -97,7 +97,7 @@ router.get('/:username', optionalAuth, async (req, res) => {
     const { username } = req.params
 
     const userResult = await pool.query(
-      `SELECT id, username, bio, avatar_url, profile_visibility, affiliation,
+      `SELECT id, username, display_name, bio, avatar_url, profile_visibility, affiliation,
               location, website_url, twitter_handle, google_scholar_url,
               orcid_id, created_at
        FROM users WHERE username = $1`,
@@ -116,6 +116,7 @@ router.get('/:username', optionalAuth, async (req, res) => {
 
     const profile = {
       username: user.username,
+      display_name: user.display_name,
       avatar_url: user.avatar_url,
       bio: visibility.bio || isOwnProfile ? user.bio : null,
       joined_date: visibility.joined_date || isOwnProfile ? user.created_at : null,
@@ -174,6 +175,7 @@ router.patch('/me', authenticateToken, async (req, res) => {
   try {
     const {
       bio,
+      display_name,
       profile_visibility,
       affiliation,
       location,
@@ -191,6 +193,14 @@ router.patch('/me', authenticateToken, async (req, res) => {
       updates.push(`bio = $${paramCount++}`)
       values.push(bio.trim())
     }
+    if (display_name !== undefined) {
+      const trimmed = display_name.trim()
+      if (trimmed.length > 50) {
+        return res.status(400).json({ error: 'Display name must be 50 characters or fewer' })
+      }
+      updates.push(`display_name = $${paramCount++}`)
+      values.push(trimmed || null)
+    }
     if (profile_visibility !== undefined) {
       updates.push(`profile_visibility = $${paramCount++}`)
       values.push(JSON.stringify(profile_visibility))
@@ -227,7 +237,7 @@ router.patch('/me', authenticateToken, async (req, res) => {
       UPDATE users
       SET ${updates.join(', ')}
       WHERE id = $${paramCount}
-      RETURNING id, username, bio, avatar_url, profile_visibility, affiliation,
+      RETURNING id, username, display_name, bio, avatar_url, profile_visibility, affiliation,
                 location, website_url, twitter_handle, google_scholar_url,
                 orcid_id, created_at
     `
diff --git a/server/tests/auth-verify.test.js b/server/tests/auth-verify.test.js
new file mode 100644
index 0000000..c612787
--- /dev/null
+++ b/server/tests/auth-verify.test.js
@@ -0,0 +1,133 @@
+const request = require('supertest')
+const crypto = require('crypto')
+const app = require('../index')
+const pool = require('../db')
+const { signCompletionToken } = require('../lib/session')
+
+const ts = Date.now()
+const testEmail = `verify_${ts}@example.com`
+const testUsername = `verify_${ts}`
+const testPassword = 'password123'
+
+let cookie = ''
+let userId = ''
+let paperId = ''
+let discussionId = ''
+
+function hashToken(raw) {
+  return crypto.createHash('sha256').update(raw).digest('hex')
+}
+
+afterAll(async () => {
+  try {
+    if (discussionId) {
+      await pool.query('DELETE FROM discussions WHERE id = $1', [discussionId])
+    }
+    if (paperId) {
+      await pool.query('DELETE FROM papers WHERE id = $1', [paperId])
+    }
+    await pool.query('DELETE FROM users WHERE email = $1', [testEmail])
+  } catch (_err) {
+    // cleanup best-effort
+  }
+})
+
+describe('Email verification flow', () => {
+  it('registers with email_verified false', async () => {
+    const res = await request(app)
+      .post('/auth/register')
+      .send({ email: testEmail, username: testUsername, password: testPassword })
+
+    expect(res.status).toBe(201)
+    expect(res.body.email_verified).toBe(false)
+    cookie = res.headers['set-cookie'][0]
+
+    const me = await request(app).get('/auth/me').set('Cookie', cookie)
+    userId = me.body.id
+    expect(me.body.email_verified).toBe(false)
+  })
+
+  it('blocks unverified user from posting comments', async () => {
+    const paper = await pool.query(
+      `INSERT INTO papers (doi, title, authors_json, journal, year, source)
+       VALUES ($1, $2, $3, $4, $5, $6) RETURNING id`,
+      [`10.9999/verify.${ts}`, 'Verify Test Paper', '[]', 'Test Journal', 2024, 'manual']
+    )
+    paperId = paper.rows[0].id
+
+    const discussion = await pool.query(
+      `INSERT INTO discussions (paper_id, created_by) VALUES ($1, $2) RETURNING id`,
+      [paperId, userId]
+    )
+    discussionId = discussion.rows[0].id
+
+    const res = await request(app)
+      .post(`/discussions/${discussionId}/comments`)
+      .set('Cookie', cookie)
+      .send({ body: 'Should be blocked' })
+
+    expect(res.status).toBe(403)
+    expect(res.body.code).toBe('EMAIL_UNVERIFIED')
+  })
+
+  it('allows posting after email verification', async () => {
+    const rawToken = crypto.randomBytes(32).toString('hex')
+    await pool.query(
+      `INSERT INTO email_verification_tokens (user_id, token_hash, expires_at)
+       VALUES ($1, $2, NOW() + INTERVAL '1 hour')`,
+      [userId, hashToken(rawToken)]
+    )
+
+    const verify = await request(app).get(`/auth/verify-email?token=${rawToken}`)
+    expect(verify.status).toBe(200)
+
+    const res = await request(app)
+      .post(`/discussions/${discussionId}/comments`)
+      .set('Cookie', cookie)
+      .send({ body: 'Verified comment' })
+
+    expect(res.status).toBe(201)
+    expect(res.body.comment.body).toBe('Verified comment')
+  })
+})
+
+describe('ORCID account completion', () => {
+  it('creates user from completion token', async () => {
+    const orcidId = `0000-0002-${ts.toString().slice(-4)}-${(ts % 10000).toString().padStart(4, '0')}`
+    const token = signCompletionToken({
+      mode: 'orcid_complete',
+      orcid_id: orcidId,
+      display_name: 'Test Researcher',
+      email: null,
+    })
+
+    const username = `orcid_${ts}`
+    const res = await request(app)
+      .post('/auth/complete')
+      .send({ token, username, display_name: 'Test Researcher' })
+
+    expect(res.status).toBe(201)
+    expect(res.body.username).toBe(username)
+    expect(res.body.display_name).toBe('Test Researcher')
+
+    await pool.query('DELETE FROM users WHERE username = $1', [username])
+  })
+})
+
+describe('OAuth URL endpoints', () => {
+  it('returns 503 when Google is not configured', async () => {
+    const prev = process.env.GOOGLE_CLIENT_ID
+    delete process.env.GOOGLE_CLIENT_ID
+    const res = await request(app).get('/auth/google/url')
+    expect(res.status).toBe(503)
+    process.env.GOOGLE_CLIENT_ID = prev
+  })
+
+  it('returns 503 when GitHub is not configured', async () => {
+    const prev = process.env.GITHUB_CLIENT_ID
+    delete process.env.GITHUB_CLIENT_ID
+    const res = await request(app).get('/auth/github/url')
+    expect(res.status).toBe(503)
+    process.env.GITHUB_CLIENT_ID = prev
+  })
+})
diff --git a/server/tests/auth.test.js b/server/tests/auth.test.js
index 2d5682c..0f0b591 100644
--- a/server/tests/auth.test.js
+++ b/server/tests/auth.test.js
@@ -24,6 +24,7 @@ describe('POST /auth/register', () => {
 
     expect(res.status).toBe(201)
     expect(res.body.username).toBe(testUsername)
+    expect(res.body.email_verified).toBe(false)
     expect(res.headers['set-cookie']).toBeDefined()
     cookie = res.headers['set-cookie'][0]
   })
diff --git a/server/tests/helpers.js b/server/tests/helpers.js
new file mode 100644
index 0000000..9b5d8b8
--- /dev/null
+++ b/server/tests/helpers.js
@@ -0,0 +1,13 @@
+const pool = require('../db')
+
+async function verifyTestUserByEmail(email) {
+  const result = await pool.query(
+    'UPDATE users SET email_verified = true WHERE email = $1 RETURNING id',
+    [email]
+  )
+  if (result.rowCount === 0) {
+    throw new Error(`verifyTestUserByEmail: no user for ${email}`)
+  }
+}
+
+module.exports = { verifyTestUserByEmail }
diff --git a/server/tests/papers.test.js b/server/tests/papers.test.js
index 07ffc5d..d57afdf 100644
--- a/server/tests/papers.test.js
+++ b/server/tests/papers.test.js
@@ -1,6 +1,7 @@
 const request = require('supertest')
 const app = require('../index')
 const pool = require('../db')
+const { verifyTestUserByEmail } = require('./helpers')
 
 const ts = Date.now().toString(36)
 const testEmail = `papertest_${ts}@example.com`
@@ -15,6 +16,7 @@ beforeAll(async () => {
     .post('/auth/register')
     .send({ email: testEmail, username: testUsername, password: 'password123' })
   cookie = res.headers['set-cookie'][0]
+  await verifyTestUserByEmail(testEmail)
 })
 
 afterAll(async () => {
diff --git a/server/tests/social.test.js b/server/tests/social.test.js
index 67cc3a3..88d0d68 100644
--- a/server/tests/social.test.js
+++ b/server/tests/social.test.js
@@ -1,6 +1,7 @@
 const request = require('supertest')
 const app = require('../index')
 const pool = require('../db')
+const { verifyTestUserByEmail } = require('./helpers')
 
 const ts = Date.now().toString(36)
 const userA = { email: `social_a_${ts}@example.com`, username: `sa_${ts}` }
@@ -23,6 +24,9 @@ beforeAll(async () => {
     .send({ ...userB, password })
   cookieB = regB.headers['set-cookie'][0]
 
+  await verifyTestUserByEmail(userA.email)
+  await verifyTestUserByEmail(userB.email)
+
   await pool.query(
     "UPDATE users SET role = 'moderator' WHERE username = $1",
     [userA.username]

From b36cf7b87a8535786aeafc1e4e8e03cb177bee36 Mon Sep 17 00:00:00 2001
From: ummaraali2 <syeda.umm@northeastern.edu>
Date: Fri, 12 Jun 2026 18:00:09 -0400
Subject: [PATCH 2/3] Fix AuthLayout export for Vercel build. Export
 SocialAuthButtons as a named export to match login/register imports.

---
 client-next/src/components/AuthLayout.jsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/client-next/src/components/AuthLayout.jsx b/client-next/src/components/AuthLayout.jsx
index 0192708..93c46c2 100644
--- a/client-next/src/components/AuthLayout.jsx
+++ b/client-next/src/components/AuthLayout.jsx
@@ -13,7 +13,7 @@ async function startOAuth(path) {
   window.location.href = data.url
 }
 
-export default function SocialAuthButtons() {
+export function SocialAuthButtons() {
   const [loading, setLoading] = useState(null)
   const [error, setError] = useState(null)
 

From ba0f23529ebd69ad5b85814dc75f1f61a7ba266d Mon Sep 17 00:00:00 2001
From: ummaraali2 <syeda.umm@northeastern.edu>
Date: Fri, 12 Jun 2026 18:08:56 -0400
Subject: [PATCH 3/3] Remove unused findAvailableUsername import in auth
 routes. Fixes server ESLint failure in CI.

---
 server/routes/auth.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/server/routes/auth.js b/server/routes/auth.js
index 2dce760..1479ede 100644
--- a/server/routes/auth.js
+++ b/server/routes/auth.js
@@ -10,7 +10,6 @@ const {
 } = require('../lib/session')
 const {
   USERNAME_REGEX,
-  findAvailableUsername,
   formatUserResponse,
 } = require('../lib/oauthUsers')