@studious-lms/server 1.27.0 → 1.28.0

package/src/index.ts

@@ -1,3 +1,7 @@
+// Must be the first import: Sentry only instruments libraries that are loaded
+// after `Sentry.init()` has run.
+import "./instrument.js";
+
 import express from 'express';
 import type { Request, Response } from 'express';
 import { createServer } from 'http';
@@ -11,11 +15,12 @@ import { findUserBySessionToken } from './models/auth.js';
 import { logger } from './utils/logger.js';
 import { setupSocketHandlers } from './socket/handlers.js';
 import { bucket } from './lib/googleCloudStorage.js';
-import { validateDirectUploadIntent } from './lib/fileUpload.js';
+import { validateDirectUploadSession } from './lib/fileUpload.js';
 import { prisma } from './lib/prisma.js';
 import { pusher } from './lib/pusher.js';
 import { connectRedis, disconnectRedis } from './lib/redis.js';
 import { createCorsOriginMatcher } from './lib/config/cors.js';
+import { isReportableTrpcError } from './utils/sentryTrpc.js';
 
 import { authLimiter, generalLimiter, helmetConfig, uploadLimiter } from './middleware/security.js';
 
@@ -25,7 +30,6 @@ import compression from 'compression';
 import { v4 as uuidv4 } from 'uuid';
 
 
-import "./instrument.js";
 import { openAIClient } from './utils/inference.js';
 import { aiStreamRouter } from './routes/aiStream.js';
 
@@ -551,7 +555,7 @@ function getUploadSessionId(req: Request) {
 }
 
 // File upload endpoint for secure file uploads (supports both POST and PUT)
-app.post('/api/upload/:filePath', async (req, res) => {
+app.post('/api/upload/:filePath', uploadLimiter, async (req, res) => {
   await handleFileUpload(req, res);
 });
 
@@ -575,7 +579,14 @@ async function handleFileUpload(req: Request, res: Response) {
     }
     
     res.header('Access-Control-Allow-Credentials', 'true');
-    
+
+    // Gate the write on the server-issued upload session for this exact path.
+    // Without this the proxy streams the body to any GCS key a caller names.
+    await validateDirectUploadSession({
+      filePath,
+      uploadSessionId: getUploadSessionId(req),
+    });
+
     const contentType = req.headers['content-type'] || 'application/octet-stream';
     const file = bucket.file(filePath);
 
@@ -647,6 +658,21 @@ app.use(
     createContext: async ({ req, res }: { req: Request; res: Response }) => {
       return createTRPCContext({ req, res });
     },
+    // tRPC replies with a JSON error envelope instead of throwing into Express,
+    // so `setupExpressErrorHandler` never sees procedure failures. Without this
+    // hook Sentry receives nothing for the entire API.
+    onError: ({ error, path, type, ctx }) => {
+      if (!isReportableTrpcError(error)) return;
+      Sentry.withScope((scope) => {
+        scope.setTags({
+          'trpc.path': path ?? 'unknown',
+          'trpc.type': type,
+          'trpc.code': error.code,
+        });
+        if (ctx?.user?.id) scope.setUser({ id: ctx.user.id });
+        Sentry.captureException(error.cause ?? error);
+      });
+    },
   })
 );
 

package/src/instrument.ts

@@ -1,15 +1,21 @@
 import * as Sentry from "@sentry/node";
 import { env } from "./lib/config/env.js";
+import { logger } from "./utils/logger.js";
 
 // Only initialize Sentry in non-test environments
 if (env.NODE_ENV !== 'test') {
+  if (!env.SENTRY_DSN) {
+    // Without a DSN the SDK silently drops everything, which looks identical
+    // to "no errors happened" — say so once at boot instead.
+    logger.warn('SENTRY_DSN is not set: error reporting is disabled');
+  }
+
   Sentry.init({
     dsn: env.SENTRY_DSN,
     environment: env.NODE_ENV || 'development',
     // Setting this option to true will send default PII data to Sentry.
     // For example, automatic IP address collection on events
     sendDefaultPii: false,
-    // @todo: disable in test environment
-    enabled: true, // Explicitly disable in test environment
+    enabled: Boolean(env.SENTRY_DSN),
   });
 }

package/src/lib/fileUpload.ts

@@ -76,6 +76,55 @@ export async function validateDirectUploadIntent(input: {
   return fileRecord;
 }
 
+/**
+ * Capability check for the `/api/upload/:filePath` proxy. The browser uploads
+ * with no auth header (only the server-issued `uploadSessionId` in the URL),
+ * so the session id + path pair *is* the capability: it maps to exactly one
+ * pending, unexpired file record that the server created for the requesting
+ * owner. Without this, the proxy would write the request body to any GCS
+ * object path a caller names.
+ */
+export async function validateDirectUploadSession(input: {
+  filePath: string;
+  uploadSessionId: string | undefined;
+}) {
+  if (!input.uploadSessionId) {
+    throw new TRPCError({
+      code: 'FORBIDDEN',
+      message: 'Missing upload session',
+    });
+  }
+
+  const fileRecord = await prisma.file.findFirst({
+    where: {
+      path: input.filePath,
+      uploadSessionId: input.uploadSessionId,
+      uploadExpiresAt: { gt: new Date() },
+      isOrphaned: false,
+    },
+    select: {
+      id: true,
+      uploadStatus: true,
+    },
+  });
+
+  if (!fileRecord) {
+    throw new TRPCError({
+      code: 'FORBIDDEN',
+      message: 'Invalid or expired upload intent',
+    });
+  }
+
+  if (!['PENDING', 'UPLOADING'].includes(fileRecord.uploadStatus)) {
+    throw new TRPCError({
+      code: 'BAD_REQUEST',
+      message: 'Upload is no longer accepting data',
+    });
+  }
+
+  return fileRecord;
+}
+
 // DEPRECATED: These functions are no longer used - files are uploaded directly to GCS
 // Use createDirectUploadFile() and createDirectUploadFiles() instead
 

package/src/pipelines/generateVisualization.ts

@@ -0,0 +1,107 @@
+/**
+ * Newton visualisation generator: turns a teacher's description into a
+ * self-contained interactive HTML document (sliders, canvas/SVG, labels)
+ * that the frontend renders inside a sandboxed iframe.
+ */
+import { z } from "zod";
+import { inference, type AiUsageAttribution } from "../utils/inference.js";
+
+export const VISUALIZATION_MODEL = "gpt-5-mini";
+export const MAX_VISUALIZATION_HTML_LENGTH = 200_000;
+
+export const generatedVisualizationSchema = z.object({
+  title: z
+    .string()
+    .describe("Short student-facing title, at most 80 characters."),
+  html: z
+    .string()
+    .describe(
+      "A complete, self-contained HTML document starting with <!DOCTYPE html>.",
+    ),
+});
+
+export type GeneratedVisualization = z.infer<typeof generatedVisualizationSchema>;
+
+export const VISUALIZATION_SYSTEM_PROMPT = `You are Newton, the teaching assistant inside the Studious LMS.
+A teacher wants an interactive visualisation to attach to a lesson for students.
+
+Return ONE complete, self-contained HTML document:
+- All CSS in a <style> tag and all JavaScript in inline <script> tags. No external scripts, stylesheets, fonts, images or network requests (no fetch, XMLHttpRequest, WebSocket, import()). It runs in a sandboxed iframe with no network access.
+- No localStorage, sessionStorage, cookies, alert, prompt or confirm.
+- Use <canvas> or inline <svg> for the visual. Give students real controls (sliders, toggles, buttons, draggable points) that update the visual live, and show the key values numerically next to each control.
+- Label axes, units and important quantities. Include a one-sentence instruction at the top telling students what to explore.
+- Responsive: fill the viewport width, work from 320px to 1200px wide, no horizontal scroll. Use a clean neutral look with system-ui font and support prefers-color-scheme: dark.
+- The science/maths must be correct. Prefer accurate formulas over approximations, and clamp inputs to physically sensible ranges.
+- Keep it focused on what the teacher asked for; no quizzes, scoring or chat.`;
+
+interface GenerateOptions {
+  attribution?: AiUsageAttribution;
+  className?: string | null;
+  subject?: string | null;
+}
+
+function classContext(options: GenerateOptions) {
+  const parts = [
+    options.subject ? `Subject: ${options.subject}` : null,
+    options.className ? `Class: ${options.className}` : null,
+  ].filter(Boolean);
+  return parts.length ? `${parts.join("\n")}\n\n` : "";
+}
+
+function assertValidHtml(result: GeneratedVisualization | null | undefined) {
+  if (!result?.html || !/<html[\s>]/i.test(result.html)) {
+    throw new Error("Newton did not return an HTML document");
+  }
+  if (result.html.length > MAX_VISUALIZATION_HTML_LENGTH) {
+    throw new Error("Generated visualisation is too large");
+  }
+  return {
+    title: result.title.trim().slice(0, 120) || "Visualisation",
+    html: result.html,
+  };
+}
+
+export async function generateVisualization(
+  prompt: string,
+  options: GenerateOptions = {},
+): Promise<GeneratedVisualization> {
+  const result = await inference<GeneratedVisualization>(
+    [
+      { role: "system", content: VISUALIZATION_SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: `${classContext(options)}Teacher request:\n${prompt}`,
+      },
+    ],
+    generatedVisualizationSchema,
+    {
+      reason: "visualization.generate",
+      model: VISUALIZATION_MODEL,
+      attribution: options.attribution,
+    },
+  );
+  return assertValidHtml(result);
+}
+
+export async function reviseVisualization(
+  current: { title: string; html: string },
+  instruction: string,
+  options: GenerateOptions = {},
+): Promise<GeneratedVisualization> {
+  const result = await inference<GeneratedVisualization>(
+    [
+      { role: "system", content: VISUALIZATION_SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: `${classContext(options)}Current visualisation "${current.title}":\n\n${current.html}\n\nRevise it as the teacher asks, keeping everything else working. Return the full updated document.\n\nTeacher request:\n${instruction}`,
+      },
+    ],
+    generatedVisualizationSchema,
+    {
+      reason: "visualization.revise",
+      model: VISUALIZATION_MODEL,
+      attribution: options.attribution,
+    },
+  );
+  return assertValidHtml(result);
+}

package/src/routers/_app.ts

@@ -36,6 +36,7 @@ import { marketplaceRouter } from "./marketplace.js";
 import { moduleItemRouter } from "./moduleItem.js";
 import { academicCalendarRouter } from "./academicCalendar.js";
 import { parentRouter } from "./parent.js";
+import { visualizationRouter } from "./visualization.js";
 
 export const appRouter = createTRPCRouter({
   class: classRouter,
@@ -73,6 +74,7 @@ export const appRouter = createTRPCRouter({
   moduleItem: moduleItemRouter,
   academicCalendar: academicCalendarRouter,
   parent: parentRouter,
+  visualization: visualizationRouter,
 });
 
 // Export type router type definition

package/src/routers/admin.ts

@@ -15,6 +15,23 @@ import {
 } from '../services/adminInstitution.js';
 import { getOverviewMetricsForAdmin } from '../services/adminMetrics.js';
 import { getUserForAdmin, searchUsersForAdmin } from '../services/adminUser.js';
+import {
+  getSpamOverviewForAdmin,
+  listUserEmailDomainsForAdmin,
+} from '../services/adminSpam.js';
+import {
+  getClassForAdmin,
+  listClassesForAdmin,
+} from '../services/adminClass.js';
+import {
+  getActivitySeriesForAdmin,
+  getContentTelemetryForAdmin,
+} from '../services/adminTelemetry.js';
+import {
+  SQL_MAX_ROWS,
+  listSqlSchemaForAdmin,
+  runAdminSql,
+} from '../services/adminSql.js';
 
 export const adminRouter = createTRPCRouter({
   getOverviewMetrics: adminProcedure.query(() => getOverviewMetricsForAdmin()),
@@ -88,6 +105,12 @@ export const adminRouter = createTRPCRouter({
         page: z.number().int().min(0).default(0),
         pageSize: z.number().int().min(1).max(100).default(25),
         query: z.string().optional(),
+        emailDomain: z.string().optional(),
+        schoolId: z.string().uuid().optional(),
+        verified: z.boolean().optional(),
+        spam: z.enum(['all', 'suspected', 'clean']).default('all'),
+        activity: z.enum(['all', 'active', 'inactive']).default('all'),
+        sort: z.enum(['username', 'recent', 'activity']).default('username'),
       }),
     )
     .query(({ input }) => searchUsersForAdmin(input)),
@@ -95,4 +118,53 @@ export const adminRouter = createTRPCRouter({
   getUser: adminProcedure
     .input(z.object({ id: z.string().uuid() }))
     .query(({ input }) => getUserForAdmin(input.id)),
+
+  listClasses: adminProcedure
+    .input(
+      z.object({
+        page: z.number().int().min(0).default(0),
+        pageSize: z.number().int().min(1).max(100).default(25),
+        query: z.string().optional(),
+        schoolId: z.string().uuid().optional(),
+        membership: z.enum(['all', 'populated', 'empty']).default('all'),
+        sort: z.enum(['name', 'students', 'assignments']).default('name'),
+      }),
+    )
+    .query(({ input }) => listClassesForAdmin(input)),
+
+  getClass: adminProcedure
+    .input(z.object({ id: z.string().uuid() }))
+    .query(({ input }) => getClassForAdmin(input.id)),
+
+  getContentTelemetry: adminProcedure.query(() =>
+    getContentTelemetryForAdmin(),
+  ),
+
+  getActivitySeries: adminProcedure
+    .input(z.object({ days: z.number().int().min(1).max(90).default(14) }))
+    .query(({ input }) => getActivitySeriesForAdmin(input)),
+
+  listSqlSchema: adminProcedure.query(() => listSqlSchemaForAdmin()),
+
+  runSql: adminProcedure
+    .input(
+      z.object({
+        sql: z.string().min(1).max(10_000),
+        limit: z.number().int().min(1).max(SQL_MAX_ROWS).default(SQL_MAX_ROWS),
+      }),
+    )
+    .mutation(({ input, ctx }) =>
+      runAdminSql({ sql: input.sql, limit: input.limit, userId: ctx.user?.id }),
+    ),
+
+  getSpamOverview: adminProcedure.query(() => getSpamOverviewForAdmin()),
+
+  listUserEmailDomains: adminProcedure
+    .input(
+      z.object({
+        limit: z.number().int().min(1).max(200).default(50),
+        suspectedOnly: z.boolean().default(false),
+      }),
+    )
+    .query(({ input }) => listUserEmailDomainsForAdmin(input)),
 });

package/src/routers/class.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { TRPCError } from "@trpc/server";
 import {
   createTRPCRouter,
   protectedProcedure,
@@ -95,7 +96,19 @@ export const classRouter = createTRPCRouter({
 
   delete: protectedTeacherProcedure
     .input(z.object({ classId: z.string(), id: z.string() }))
-    .mutation(({ input }) => deleteClass(input.id)),
+    .mutation(({ input }) => {
+      // `protectedTeacherProcedure` authorizes the caller against `classId`.
+      // Deleting `input.id` unchecked let a teacher of one class delete any
+      // other class by id; require the two to match so the authorized class
+      // is the one deleted.
+      if (input.id !== input.classId) {
+        throw new TRPCError({
+          code: "FORBIDDEN",
+          message: "Class id does not match the authorized class.",
+        });
+      }
+      return deleteClass(input.classId);
+    }),
   addStudent: protectedTeacherProcedure
     .input(z.object({ classId: z.string(), studentId: z.string() }))
     .mutation(({ input }) => addStudent(input.classId, input.studentId)),

package/src/routers/visualization.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import {
+  createTRPCRouter,
+  protectedClassMemberProcedure,
+  protectedTeacherProcedure,
+} from "../trpc.js";
+import {
+  createVisualization,
+  deleteVisualization,
+  getVisualization,
+  listVisualizations,
+  reviseVisualizationRecord,
+  updateVisualization,
+} from "../services/visualization.js";
+
+export const visualizationRouter = createTRPCRouter({
+  list: protectedClassMemberProcedure
+    .input(z.object({ classId: z.string() }))
+    .query(({ ctx, input }) => listVisualizations(ctx.user!.id, input.classId)),
+
+  get: protectedClassMemberProcedure
+    .input(z.object({ classId: z.string(), id: z.string() }))
+    .query(({ ctx, input }) => getVisualization(ctx.user!.id, input.classId, input.id)),
+
+  generate: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        prompt: z.string().trim().min(3).max(4000),
+        title: z.string().trim().max(120).optional(),
+      }),
+    )
+    .mutation(({ ctx, input }) => createVisualization(ctx.user!.id, input)),
+
+  revise: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        id: z.string(),
+        instruction: z.string().trim().min(3).max(4000),
+      }),
+    )
+    .mutation(({ ctx, input }) => reviseVisualizationRecord(ctx.user!.id, input)),
+
+  update: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        id: z.string(),
+        title: z.string().trim().min(1).max(120).optional(),
+        html: z.string().min(1).optional(),
+        published: z.boolean().optional(),
+      }),
+    )
+    .mutation(({ input }) => updateVisualization(input)),
+
+  delete: protectedTeacherProcedure
+    .input(z.object({ classId: z.string(), id: z.string() }))
+    .mutation(({ input }) => deleteVisualization(input)),
+});

package/src/services/adminClass.ts

@@ -0,0 +1,222 @@
+import type { Prisma } from '@prisma/client';
+import { TRPCError } from '@trpc/server';
+import { prisma } from '../lib/prisma.js';
+import { classifyUser } from './adminSpam.js';
+
+export type AdminClassMembership = 'all' | 'populated' | 'empty';
+export type AdminClassSort = 'name' | 'students' | 'assignments';
+
+export async function listClassesForAdmin(input: {
+  page: number;
+  pageSize: number;
+  query?: string;
+  schoolId?: string;
+  membership?: AdminClassMembership;
+  sort?: AdminClassSort;
+}) {
+  const skip = input.page * input.pageSize;
+  const filters: Prisma.ClassWhereInput[] = [];
+
+  const q = input.query?.trim();
+  if (q) {
+    filters.push({
+      OR: [
+        { name: { contains: q, mode: 'insensitive' } },
+        { subject: { contains: q, mode: 'insensitive' } },
+        { section: { contains: q, mode: 'insensitive' } },
+      ],
+    });
+  }
+
+  if (input.schoolId) filters.push({ schoolId: input.schoolId });
+  if (input.membership === 'populated') filters.push({ students: { some: {} } });
+  if (input.membership === 'empty') filters.push({ students: { none: {} } });
+
+  const where: Prisma.ClassWhereInput = filters.length ? { AND: filters } : {};
+
+  const orderBy: Prisma.ClassOrderByWithRelationInput[] =
+    input.sort === 'students'
+      ? [{ students: { _count: 'desc' } }, { name: 'asc' }]
+      : input.sort === 'assignments'
+        ? [{ assignments: { _count: 'desc' } }, { name: 'asc' }]
+        : [{ name: 'asc' }];
+
+  const [items, total] = await Promise.all([
+    prisma.class.findMany({
+      where,
+      orderBy,
+      skip,
+      take: input.pageSize,
+      select: {
+        id: true,
+        name: true,
+        subject: true,
+        section: true,
+        school: { select: { id: true, name: true } },
+        department: { select: { id: true, name: true } },
+        teachers: { select: { id: true, username: true }, take: 3 },
+        assignments: {
+          orderBy: { createdAt: 'desc' },
+          take: 1,
+          select: { createdAt: true },
+        },
+        _count: {
+          select: {
+            students: true,
+            teachers: true,
+            assignments: true,
+            announcements: true,
+            discussions: true,
+            worksheets: true,
+            events: true,
+            modules: true,
+          },
+        },
+      },
+    }),
+    prisma.class.count({ where }),
+  ]);
+
+  return {
+    items: items.map(({ assignments, ...rest }) => ({
+      ...rest,
+      lastAssignmentAt: assignments[0]?.createdAt ?? null,
+    })),
+    total,
+    page: input.page,
+    pageSize: input.pageSize,
+    pageCount: Math.max(1, Math.ceil(total / input.pageSize)),
+  };
+}
+
+const MEMBER_SELECT = {
+  id: true,
+  username: true,
+  email: true,
+  verified: true,
+  _count: { select: { teacherIn: true, studentIn: true, submissions: true } },
+} satisfies Prisma.UserSelect;
+
+export async function getClassForAdmin(id: string) {
+  const cls = await prisma.class.findUnique({
+    where: { id },
+    select: {
+      id: true,
+      name: true,
+      subject: true,
+      section: true,
+      color: true,
+      school: { select: { id: true, name: true } },
+      department: { select: { id: true, name: true } },
+      teachers: { orderBy: { username: 'asc' }, select: MEMBER_SELECT },
+      students: {
+        orderBy: { username: 'asc' },
+        take: 200,
+        select: MEMBER_SELECT,
+      },
+      assignments: {
+        orderBy: { createdAt: 'desc' },
+        take: 20,
+        select: {
+          id: true,
+          title: true,
+          type: true,
+          graded: true,
+          dueDate: true,
+          createdAt: true,
+          teacher: { select: { id: true, username: true } },
+          _count: { select: { submissions: true } },
+        },
+      },
+      announcements: {
+        orderBy: { createdAt: 'desc' },
+        take: 10,
+        select: {
+          id: true,
+          createdAt: true,
+          remarks: true,
+          teacher: { select: { id: true, username: true } },
+        },
+      },
+      _count: {
+        select: {
+          students: true,
+          teachers: true,
+          assignments: true,
+          announcements: true,
+          discussions: true,
+          worksheets: true,
+          events: true,
+          modules: true,
+          sections: true,
+        },
+      },
+    },
+  });
+
+  if (!cls) {
+    throw new TRPCError({ code: 'NOT_FOUND', message: 'Class not found' });
+  }
+
+  // Per-student submission counts scoped to this class, so a roster row shows
+  // engagement here rather than platform-wide totals.
+  const submissionsByStudent = await prisma.submission.groupBy({
+    by: ['studentId'],
+    where: { assignment: { classId: id } },
+    _count: { _all: true },
+  });
+  const submissionCount = new Map(
+    submissionsByStudent.map((row) => [row.studentId, row._count._all]),
+  );
+
+  const withSignals = (user: (typeof cls.students)[number]) => ({
+    ...user,
+    signals: classifyUser(user),
+    submissionsInClass: submissionCount.get(user.id) ?? 0,
+  });
+
+  return {
+    ...cls,
+    teachers: cls.teachers.map(withSignals),
+    students: cls.students.map(withSignals),
+    announcements: cls.announcements.map((announcement) => ({
+      ...announcement,
+      remarks:
+        announcement.remarks.length > 160
+          ? `${announcement.remarks.slice(0, 160)}…`
+          : announcement.remarks,
+    })),
+    suspectedMembers: [...cls.teachers, ...cls.students].filter(
+      (user) => classifyUser(user).suspected,
+    ).length,
+  };
+}
+
+/** Classes a single user teaches or studies in, for the user detail page. */
+export async function listClassesForUserForAdmin(userId: string) {
+  const select = {
+    id: true,
+    name: true,
+    subject: true,
+    section: true,
+    school: { select: { id: true, name: true } },
+    _count: { select: { students: true, assignments: true } },
+  } satisfies Prisma.ClassSelect;
+
+  const [teaching, enrolled] = await Promise.all([
+    prisma.class.findMany({
+      where: { teachers: { some: { id: userId } } },
+      orderBy: { name: 'asc' },
+      take: 100,
+      select,
+    }),
+    prisma.class.findMany({
+      where: { students: { some: { id: userId } } },
+      orderBy: { name: 'asc' },
+      take: 100,
+      select,
+    }),
+  ]);
+
+  return { teaching, enrolled };
+}