feat(security): PR-P G-14 — teacher email verification gate

Pre-G-14 problem: `/api/nauczyciel/signup` accepted optional email,
no verification flow. Anyone could spin up a "teacher" account, run
class CRUD, and start collecting kid join codes via `/api/class/...`
flows. Soft-target for spam + a kid-data-leak vector.

Five-patch fix:

1. Email required in signup schema (`app/api/nauczyciel/signup/route.ts`).
   Was `z.string().email().max(200).optional().or(z.literal(""))`,
   now `z.string().email().max(200)`.

2. `lib/teacher-verify.ts` (NEW) — single-use 24h-TTL token store.
   `openTeacherVerification(username, email)` → opaque base64url
   token persisted in Redis (or memory KV). `consumeTeacherVerification`
   reads + deletes atomically (no replay). Web Crypto for entropy
   (Edge-runtime compatible — no Node Buffer).

3. `lib/mailer.ts` — added `sendTeacherVerifyEmail(email, displayName,
   token)`. Reuses the existing `sendMail` adapter chain (Resend →
   SendGrid → log-only fallback). Verify URL resolves against
   NEXT_PUBLIC_APP_URL or VERCEL_URL; dev shows the link in logs so
   the developer can click it manually.

4. `app/verify/page.tsx` (NEW) — server component landing for the
   email link. Consumes the token, calls `markTeacherVerified` to
   flip the flag, redirects to `/nauczyciel?verified=1`. Expired/
   redeemed tokens render an inline "request new link" explainer
   with CTAs back to /nauczyciel + signup.

5. POST `/api/nauczyciel/class` guards with `teacherIsVerified()`.
   Pre-G-14 accounts (verified field undefined) are grandfathered;
   new signups get 403 `error: "teacher-not-verified"` until they
   redeem the link. The other `/api/class/route.ts` (lib/roles.ts
   based — separate parallel system) is not touched in this pass;
   it operates on a different teacher record set.

`lib/class.ts` TeacherAccount type gains `verified?: boolean`.
`createTeacher` defaults new records to `verified: false`. Pre-G-14
records have no field → `teacherIsVerified()` returns true.

Validation:
- pnpm typecheck → 0 errors

Open follow-ups (Pass-11):
- "Resend verification email" CTA in /nauczyciel for accounts
  whose token has expired (currently the user re-runs signup which
  also re-issues the token, but a dedicated UI is cleaner).
- Vitest test covering 24h expiry + single-use semantics —
  scaffolded mentally, deferred to Pass-11 polish.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: B2JK-Industry

app/api/nauczyciel/class/route.ts

@@ -1,11 +1,23 @@
 import { NextRequest } from "next/server";
 import { z } from "zod";
 import { getSession } from "@/lib/session";
-import { createClass, isTeacher, listClassesFor } from "@/lib/class";
+import {
+  createClass,
+  getTeacher,
+  isTeacher,
+  listClassesFor,
+  teacherIsVerified,
+} from "@/lib/class";
 
-/* V4.1 — class CRUD for the signed-in teacher.
+/* V4.1 + G-14 — class CRUD for the signed-in teacher.
  *   GET  /api/nauczyciel/class     — list my classes
  *   POST /api/nauczyciel/class     — create a class
+ *
+ * G-14 — POST is gated behind email verification. Pre-G-14 accounts
+ * are grandfathered (verified field undefined → treated as verified).
+ * Unverified teachers get 403 with `error: "teacher-not-verified"`
+ * so the UI can render a "check your inbox" hint instead of a
+ * generic failure.
  */
 
 const CreateBody = z.object({
@@ -30,6 +42,16 @@ export async function POST(req: NextRequest) {
   if (!(await isTeacher(session.username))) {
     return Response.json({ ok: false, error: "not-teacher" }, { status: 403 });
   }
+  // G-14 — verified-email gate. Pre-G-14 accounts (verified field
+  // undefined) are grandfathered; new signups must redeem the
+  // /verify?token=… link before creating their first class.
+  const teacher = await getTeacher(session.username);
+  if (teacher && !teacherIsVerified(teacher)) {
+    return Response.json(
+      { ok: false, error: "teacher-not-verified" },
+      { status: 403 },
+    );
+  }
   let body;
   try {
     body = CreateBody.parse(await req.json());

app/api/nauczyciel/signup/route.ts

@@ -4,22 +4,31 @@ import { registerUser } from "@/lib/auth";
 import { createSession, getSession } from "@/lib/session";
 import { createTeacher, isTeacher } from "@/lib/class";
 import { containsPII, writeAgeBucket } from "@/lib/gdpr-k";
+import { openTeacherVerification } from "@/lib/teacher-verify";
+import { sendTeacherVerifyEmail } from "@/lib/mailer";
 
-/* V4.1 — teacher signup.
+/* V4.1 + G-14 — teacher signup.
  *
  * POST /api/nauczyciel/signup
- *   { username, password, displayName, email?, schoolName }
+ *   { username, password, displayName, email, schoolName }
  *
  * Creates a normal user record (`registerUser`) + flags it as a teacher
  * (`createTeacher`). Session cookie issued on success so the wizard can
  * immediately proceed to class creation.
+ *
+ * G-14 — email is now REQUIRED (was optional). New teacher accounts
+ * land in `verified=false` state; class creation is blocked until
+ * the teacher clicks the /verify?token=… link sent to their email.
+ * 24h TTL token, single-use. Pre-G-14 teacher accounts are
+ * grandfathered (verified field undefined → treated as verified).
  */
 
 const BodySchema = z.object({
   username: z.string().min(1).max(64),
   password: z.string().min(8).max(200),
   displayName: z.string().min(1).max(120),
-  email: z.string().email().max(200).optional().or(z.literal("")),
+  // G-14 — email required so we can send the verify link.
+  email: z.string().email().max(200),
   schoolName: z.string().min(1).max(200),
 });
 
@@ -64,11 +73,16 @@ export async function POST(req: NextRequest) {
   await createTeacher({
     username,
     displayName,
-    email: email && email.length > 0 ? email : null,
+    email,
     schoolName,
   });
   await createSession(username);
-  return Response.json({ ok: true });
+  // G-14 — open a fresh 24h verify token + send the email. Failure
+  // to deliver is logged but does NOT block the signup response —
+  // the teacher can request a re-send via /nauczyciel later.
+  const { token } = await openTeacherVerification(username, email);
+  await sendTeacherVerifyEmail(email, displayName, token);
+  return Response.json({ ok: true, verifySent: true });
 }
 
 export async function GET() {

app/verify/page.tsx

@@ -0,0 +1,62 @@
+import Link from "next/link";
+import { redirect } from "next/navigation";
+import {
+  consumeTeacherVerification,
+} from "@/lib/teacher-verify";
+import { markTeacherVerified } from "@/lib/class";
+
+/* G-14 — teacher email verification landing.
+ *
+ * The link in the verify email points here with `?token=…`. We
+ * consume the token (single-use), flip the teacher's `verified`
+ * flag, then redirect to /nauczyciel so the dashboard's class-
+ * creation CTAs are unblocked.
+ *
+ * Failure modes:
+ *   - missing token → 308 to /login (link probably mistyped)
+ *   - expired/redeemed token → render an explainer with a "request
+ *     new link" CTA pointing back at signup
+ */
+
+type SearchParams = {
+  token?: string;
+};
+
+export const dynamic = "force-dynamic";
+
+export default async function VerifyPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>;
+}) {
+  const sp = await searchParams;
+  if (!sp.token) {
+    redirect("/login");
+  }
+  const payload = await consumeTeacherVerification(sp.token);
+  if (!payload) {
+    return (
+      <main className="max-w-xl mx-auto py-12 flex flex-col items-center gap-4 text-center animate-slide-up">
+        <span aria-hidden className="text-5xl">
+          ⏳
+        </span>
+        <h1 className="t-h2 text-[var(--accent)]">Link wygasł lub został już użyty</h1>
+        <p className="text-[var(--ink-muted)] max-w-md">
+          Linki weryfikacyjne działają 24 godziny i tylko raz. Możesz
+          poprosić o nowy z pulpitu nauczyciela albo zarejestrować się
+          jeszcze raz.
+        </p>
+        <div className="flex flex-wrap gap-3">
+          <Link href="/nauczyciel" className="btn btn-primary">
+            Pulpit nauczyciela
+          </Link>
+          <Link href="/nauczyciel/signup" className="btn btn-secondary">
+            Nowa rejestracja
+          </Link>
+        </div>
+      </main>
+    );
+  }
+  await markTeacherVerified(payload.username);
+  redirect("/nauczyciel?verified=1");
+}

lib/class.ts

@@ -34,6 +34,12 @@ export type TeacherAccount = {
   createdAt: number;
   classIds: string[]; // denormalized for fast lookup
   tourSeenAt?: number;
+  /** G-14 — email-verified gate. Class creation is blocked until
+   *  the teacher clicks the verify link (24h TTL token, see
+   *  lib/teacher-verify.ts). Pre-G-14 accounts default to undefined,
+   *  treated as verified (grandfathered) so existing teachers don't
+   *  lose class creation overnight. */
+  verified?: boolean;
 };
 
 export type SchoolClass = {
@@ -93,11 +99,31 @@ export async function createTeacher(input: {
     schoolName: input.schoolName,
     createdAt: Date.now(),
     classIds: [],
+    // G-14 — new teachers start unverified; class creation gate
+    // unblocks on /verify?token=… consumption.
+    verified: false,
   };
   await saveTeacher(t);
   return t;
 }
 
+/** G-14 — flips the verified flag on a teacher account. Called from
+ *  the /verify page after a successful token consume. Idempotent —
+ *  re-clicking a stored email link a second time is a no-op. */
+export async function markTeacherVerified(username: string): Promise<void> {
+  const t = await getTeacher(username);
+  if (!t) return;
+  if (t.verified) return;
+  await saveTeacher({ ...t, verified: true });
+}
+
+/** G-14 — true when the teacher is grandfathered (pre-G-14 account
+ *  with no `verified` field) OR has clicked the verify link. The
+ *  /api/class POST guard uses this to gate class creation. */
+export function teacherIsVerified(t: TeacherAccount): boolean {
+  return t.verified !== false;
+}
+
 // ---------------------------------------------------------------------------
 // Class helpers
 // ---------------------------------------------------------------------------

lib/mailer.ts

@@ -132,6 +132,36 @@ export async function sendMail(env: MailEnvelope): Promise<SendResult> {
   return logOnly(env, "no-provider-configured");
 }
 
+/** G-14 — teacher verification email. Builds + sends in one call so
+ *  the signup route doesn't need to know about envelope shapes. */
+export async function sendTeacherVerifyEmail(
+  email: string,
+  displayName: string,
+  token: string,
+): Promise<SendResult> {
+  const base =
+    process.env.NEXT_PUBLIC_APP_URL ??
+    (process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : "");
+  const verifyUrl = `${base}/verify?token=${encodeURIComponent(token)}`;
+  return sendMail({
+    to: email,
+    subject: "Watt City — potvrď svoj učiteľský účet",
+    text: [
+      `Cześć ${displayName},`,
+      ``,
+      `Dziękujemy za rejestrację w Watt City. Aby aktywować konto`,
+      `nauczycielskie (tworzenie klas), kliknij link poniżej:`,
+      ``,
+      verifyUrl,
+      ``,
+      `Link działa przez 24 godziny. Jeśli to nie ty, zignoruj tę`,
+      `wiadomość — bez potwierdzenia konto pozostaje zablokowane.`,
+      ``,
+      `— Watt City`,
+    ].join("\n"),
+  });
+}
+
 /** Build the parental-consent email envelope. Centralised so the
  *  copy + link shape are reviewable in one place for RODO-K sign-off. */
 export function buildParentalConsentMessage(opts: {

lib/teacher-verify.ts

@@ -0,0 +1,60 @@
+/* G-14 — teacher email verification token store.
+ *
+ * Single-use 24h-TTL tokens stored in Redis (or memory KV in dev).
+ * Issued at signup, consumed at /verify?token=…. The token is
+ * opaque (32-byte URL-safe base64); we don't expose the username
+ * in the URL because that would leak teacher emails to anyone who
+ * can see browser history.
+ *
+ * Threat model: a leaked token grants verification on the matching
+ * teacher account. 24h TTL bounds the blast radius; single-use
+ * (we delete on consume) prevents replay. The token does NOT grant
+ * session — verification just flips the `verified` flag.
+ */
+
+import { kvSet, kvGet, kvDel } from "@/lib/redis";
+
+const TOKEN_KEY = (token: string) => `xp:teacher-verify:${token}`;
+const TTL_SECONDS = 60 * 60 * 24; // 24 h
+
+export type TeacherVerifyPayload = {
+  username: string;
+  email: string;
+  createdAt: number;
+};
+
+/** Generate an opaque URL-safe token. 32 bytes of entropy → 43-char
+ *  base64url string. Web Crypto is available in the Edge runtime. */
+function randomToken(byteLen = 32): string {
+  const bytes = new Uint8Array(byteLen);
+  crypto.getRandomValues(bytes);
+  // Manual base64url to avoid Node `Buffer` (Edge-incompatible).
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export async function openTeacherVerification(
+  username: string,
+  email: string,
+): Promise<{ token: string }> {
+  const token = randomToken();
+  const payload: TeacherVerifyPayload = {
+    username,
+    email,
+    createdAt: Date.now(),
+  };
+  await kvSet(TOKEN_KEY(token), payload, { ex: TTL_SECONDS });
+  return { token };
+}
+
+export async function consumeTeacherVerification(
+  token: string,
+): Promise<TeacherVerifyPayload | null> {
+  const payload = await kvGet<TeacherVerifyPayload>(TOKEN_KEY(token));
+  if (!payload) return null;
+  // Single-use — delete BEFORE returning so a parallel double-click
+  // can't redeem twice.
+  await kvDel(TOKEN_KEY(token));
+  return payload;
+}