@studious-lms/server 1.27.0 → 1.28.0

package/src/services/adminInstitution.ts

@@ -1,6 +1,7 @@
 import type { Prisma } from '@prisma/client';
 import { TRPCError } from '@trpc/server';
 import { prisma } from '../lib/prisma.js';
+import { classifyEmail } from './adminSpam.js';
 
 export async function listSchoolsForAdmin(input: {
   page: number;
@@ -159,7 +160,10 @@ export async function listSchoolDevelopmentProgramsForAdmin(input: {
   ]);
 
   return {
-    items,
+    items: items.map((item) => ({
+      ...item,
+      signals: classifyEmail(item.contactEmail),
+    })),
     total,
     page: input.page,
     pageSize: input.pageSize,
@@ -183,7 +187,10 @@ export async function listEarlyAccessRequestsForAdmin(input: {
   ]);
 
   return {
-    items,
+    items: items.map((item) => ({
+      ...item,
+      signals: classifyEmail(item.email),
+    })),
     total,
     page: input.page,
     pageSize: input.pageSize,

package/src/services/adminMetrics.ts

@@ -1,13 +1,31 @@
 import { prisma } from '../lib/prisma.js';
+import { suspectedUserWhere } from './adminSpam.js';
+
+async function countActiveUsersSince(since: Date) {
+  const rows = await prisma.session.groupBy({
+    by: ['userId'],
+    where: { type: 'AUTH', createdAt: { gte: since }, userId: { not: null } },
+  });
+  return rows.length;
+}
 
 export async function getOverviewMetricsForAdmin() {
   const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+  const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+  const suspected = suspectedUserWhere();
 
   const [
     schools,
     users,
     verifiedUsers,
+    suspectedUsers,
+    signupsLast24h,
+    signupsLast7d,
+    activeUsersLast24h,
+    activeUsersLast7d,
     classes,
+    activeClassesLast7d,
+    submissionsLast24h,
     departments,
     runJobsByStatus,
     failedRunJobsLast24h,
@@ -17,7 +35,16 @@ export async function getOverviewMetricsForAdmin() {
     prisma.school.count(),
     prisma.user.count(),
     prisma.user.count({ where: { verified: true } }),
+    prisma.user.count({ where: suspected }),
+    prisma.userProfile.count({ where: { createdAt: { gte: dayAgo } } }),
+    prisma.userProfile.count({ where: { createdAt: { gte: weekAgo } } }),
+    countActiveUsersSince(dayAgo),
+    countActiveUsersSince(weekAgo),
     prisma.class.count(),
+    prisma.class.count({
+      where: { assignments: { some: { createdAt: { gte: weekAgo } } } },
+    }),
+    prisma.submission.count({ where: { submittedAt: { gte: dayAgo } } }),
     prisma.department.count(),
     prisma.runJob.groupBy({ by: ['status'], _count: { _all: true } }),
     prisma.runJob.count({
@@ -31,6 +58,14 @@ export async function getOverviewMetricsForAdmin() {
     schools,
     users,
     verifiedUsers,
+    suspectedUsers,
+    cleanUsers: users - suspectedUsers,
+    signupsLast24h,
+    signupsLast7d,
+    activeUsersLast24h,
+    activeUsersLast7d,
+    activeClassesLast7d,
+    submissionsLast24h,
     classes,
     departments,
     runJobs: {

package/src/services/adminSpam.ts

@@ -0,0 +1,224 @@
+import type { Prisma } from '@prisma/client';
+import { prisma } from '../lib/prisma.js';
+
+export type SpamReason =
+  | 'BLOCKED_DOMAIN'
+  | 'BOT_PATTERN'
+  | 'DISPOSABLE_DOMAIN'
+  | 'NEVER_VERIFIED_INACTIVE';
+
+export type SpamSignals = {
+  suspected: boolean;
+  reasons: SpamReason[];
+};
+
+const DEFAULT_BLOCKED_DOMAINS = ['riverside.edu'];
+
+const DEFAULT_BOT_PATTERNS = ['devin', 'automation-bot', 'qa-bot'];
+
+const DEFAULT_DISPOSABLE_DOMAINS = [
+  'mailinator.com',
+  'guerrillamail.com',
+  'yopmail.com',
+  'tempmail.com',
+  'temp-mail.org',
+  '10minutemail.com',
+  'trashmail.com',
+  'sharklasers.com',
+  'dispostable.com',
+];
+
+function fromEnv(name: string, fallback: string[]): string[] {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = raw
+    .split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter(Boolean);
+  return parsed.length > 0 ? parsed : fallback;
+}
+
+export function spamRules() {
+  return {
+    blockedDomains: fromEnv('ADMIN_SPAM_DOMAINS', DEFAULT_BLOCKED_DOMAINS),
+    botPatterns: fromEnv('ADMIN_SPAM_BOT_PATTERNS', DEFAULT_BOT_PATTERNS),
+    disposableDomains: fromEnv(
+      'ADMIN_SPAM_DISPOSABLE_DOMAINS',
+      DEFAULT_DISPOSABLE_DOMAINS,
+    ),
+  };
+}
+
+function domainOf(email: string): string {
+  const at = email.lastIndexOf('@');
+  return at === -1 ? '' : email.slice(at + 1).trim().toLowerCase();
+}
+
+function matchesDomain(domain: string, listed: string): boolean {
+  return domain === listed || domain.endsWith(`.${listed}`);
+}
+
+export type ClassifiableUser = {
+  username: string;
+  email: string;
+  verified: boolean;
+  _count?: { teacherIn: number; studentIn: number; submissions?: number };
+};
+
+export function classifyEmail(
+  email: string | null | undefined,
+  username?: string | null,
+): SpamSignals {
+  const rules = spamRules();
+  const normalisedEmail = (email ?? '').toLowerCase();
+  const normalisedUsername = (username ?? '').toLowerCase();
+  const domain = domainOf(normalisedEmail);
+  const reasons: SpamReason[] = [];
+
+  if (rules.blockedDomains.some((listed) => matchesDomain(domain, listed))) {
+    reasons.push('BLOCKED_DOMAIN');
+  }
+  if (rules.disposableDomains.some((listed) => matchesDomain(domain, listed))) {
+    reasons.push('DISPOSABLE_DOMAIN');
+  }
+  if (
+    rules.botPatterns.some(
+      (pattern) =>
+        normalisedEmail.includes(pattern) ||
+        (normalisedUsername.length > 0 && normalisedUsername.includes(pattern)),
+    )
+  ) {
+    reasons.push('BOT_PATTERN');
+  }
+
+  return { suspected: reasons.length > 0, reasons };
+}
+
+export function classifyUser(user: ClassifiableUser): SpamSignals {
+  const reasons = [...classifyEmail(user.email, user.username).reasons];
+  const counts = user._count;
+  if (
+    !user.verified &&
+    counts &&
+    counts.teacherIn === 0 &&
+    counts.studentIn === 0 &&
+    (counts.submissions ?? 0) === 0
+  ) {
+    reasons.push('NEVER_VERIFIED_INACTIVE');
+  }
+
+  return { suspected: reasons.length > 0, reasons };
+}
+
+/**
+ * Prisma filter matching the rule-based part of {@link classifyUser}. The
+ * `NEVER_VERIFIED_INACTIVE` reason is intentionally excluded: brand new real
+ * signups look identical to it, so it only annotates rows and never drives
+ * list filtering or counts.
+ */
+export function suspectedUserWhere(): Prisma.UserWhereInput {
+  const rules = spamRules();
+  const domains = [...rules.blockedDomains, ...rules.disposableDomains];
+
+  return {
+    OR: [
+      ...domains.map((domain) => ({
+        email: { endsWith: `@${domain}`, mode: 'insensitive' as const },
+      })),
+      ...domains.map((domain) => ({
+        email: { endsWith: `.${domain}`, mode: 'insensitive' as const },
+      })),
+      ...rules.botPatterns.flatMap((pattern) => [
+        { username: { contains: pattern, mode: 'insensitive' as const } },
+        { email: { contains: pattern, mode: 'insensitive' as const } },
+      ]),
+    ],
+  };
+}
+
+export function notSuspectedUserWhere(): Prisma.UserWhereInput {
+  return { NOT: suspectedUserWhere() };
+}
+
+export async function countSuspectedUsers(): Promise<number> {
+  return prisma.user.count({ where: suspectedUserWhere() });
+}
+
+type DomainRow = { domain: string | null; total: bigint; verified: bigint };
+
+export async function listUserEmailDomainsForAdmin(input: {
+  limit: number;
+  suspectedOnly: boolean;
+}) {
+  const rows = await prisma.$queryRaw<DomainRow[]>`
+    SELECT lower(split_part(email, '@', 2)) AS domain,
+           count(*) AS total,
+           count(*) FILTER (WHERE verified) AS verified
+    FROM "User"
+    GROUP BY 1
+    ORDER BY count(*) DESC, 1 ASC
+    LIMIT ${Math.min(input.limit, 200)}
+  `;
+
+  const rules = spamRules();
+  const items = rows.map((row) => {
+    const domain = row.domain ?? '';
+    const suspected =
+      rules.blockedDomains.some((listed) => matchesDomain(domain, listed)) ||
+      rules.disposableDomains.some((listed) => matchesDomain(domain, listed));
+    return {
+      domain: domain || '(none)',
+      total: Number(row.total),
+      verified: Number(row.verified),
+      suspected,
+    };
+  });
+
+  return {
+    items: input.suspectedOnly ? items.filter((item) => item.suspected) : items,
+  };
+}
+
+export async function getSpamOverviewForAdmin() {
+  const rules = spamRules();
+  const suspectedWhere = suspectedUserWhere();
+
+  const [
+    totalUsers,
+    suspectedUsers,
+    suspectedVerified,
+    domains,
+    recent,
+  ] = await Promise.all([
+    prisma.user.count(),
+    prisma.user.count({ where: suspectedWhere }),
+    prisma.user.count({ where: { AND: [suspectedWhere, { verified: true }] } }),
+    listUserEmailDomainsForAdmin({ limit: 200, suspectedOnly: true }),
+    prisma.user.findMany({
+      where: suspectedWhere,
+      orderBy: { username: 'asc' },
+      take: 50,
+      select: {
+        id: true,
+        username: true,
+        email: true,
+        verified: true,
+        profile: { select: { createdAt: true } },
+        _count: { select: { teacherIn: true, studentIn: true, submissions: true } },
+      },
+    }),
+  ]);
+
+  return {
+    rules,
+    totalUsers,
+    suspectedUsers,
+    suspectedVerified,
+    cleanUsers: totalUsers - suspectedUsers,
+    domains: domains.items,
+    recent: recent.map((user) => ({
+      ...user,
+      signals: classifyUser(user),
+    })),
+  };
+}

package/src/services/adminSql.ts

@@ -0,0 +1,214 @@
+import { TRPCError } from '@trpc/server';
+import { prisma } from '../lib/prisma.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Read-only SQL console backing `admin.runSql`.
+ *
+ * Three independent guards, because a single one is not enough:
+ * 1. the statement is parsed/validated here (single read statement only),
+ * 2. it runs inside a `READ ONLY` transaction so the database rejects writes,
+ * 3. a statement timeout and row cap bound the blast radius of a bad query.
+ */
+
+const READ_STARTERS = ['select', 'with', 'explain', 'show', 'table', 'values'];
+
+/** Statement keywords that must never appear, including inside CTEs. */
+const FORBIDDEN_KEYWORDS = [
+  'insert',
+  'update',
+  'delete',
+  'merge',
+  'upsert',
+  'drop',
+  'alter',
+  'create',
+  'truncate',
+  'grant',
+  'revoke',
+  'comment',
+  'copy',
+  'vacuum',
+  'analyze',
+  'reindex',
+  'cluster',
+  'refresh',
+  'lock',
+  'listen',
+  'notify',
+  'call',
+  'do',
+  'set',
+  'reset',
+  'begin',
+  'commit',
+  'rollback',
+  'savepoint',
+  'prepare',
+  'execute',
+  'deallocate',
+  'discard',
+  'import',
+  'security',
+  'pg_read_file',
+  'pg_read_binary_file',
+  'pg_ls_dir',
+  'dblink',
+  'pg_sleep',
+];
+
+export const SQL_MAX_ROWS = 500;
+export const SQL_TIMEOUT_MS = 10_000;
+
+function stripCommentsAndStrings(sql: string): string {
+  return sql
+    .replace(/--[^\n]*/g, ' ')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/'(?:[^']|'')*'/g, "''")
+    .replace(/"(?:[^"]|"")*"/g, '""');
+}
+
+function badRequest(message: string): TRPCError {
+  return new TRPCError({ code: 'BAD_REQUEST', message });
+}
+
+/**
+ * Validates that `sql` is a single read-only statement and returns it without
+ * its trailing semicolon. Throws a `BAD_REQUEST` otherwise.
+ */
+export function assertReadOnlySql(sql: string): string {
+  const statement = sql.trim().replace(/;\s*$/, '').trim();
+  if (!statement) throw badRequest('Query is empty.');
+
+  const sanitized = stripCommentsAndStrings(statement).toLowerCase();
+
+  if (sanitized.includes(';')) {
+    throw badRequest('Only a single statement may be executed.');
+  }
+
+  const firstWord = sanitized.trim().split(/\s+/)[0]?.replace(/^\(+/, '') ?? '';
+  if (!READ_STARTERS.includes(firstWord)) {
+    throw badRequest(
+      `Only ${READ_STARTERS.map((word) => word.toUpperCase()).join('/')} queries are allowed.`,
+    );
+  }
+
+  const forbidden = FORBIDDEN_KEYWORDS.find((keyword) =>
+    new RegExp(`\\b${keyword}\\b`).test(sanitized),
+  );
+  if (forbidden) {
+    throw badRequest(`Keyword "${forbidden.toUpperCase()}" is not allowed in the SQL console.`);
+  }
+
+  return statement;
+}
+
+/** Wraps row-returning statements so the row cap is enforced by the database. */
+export function buildBoundedQuery(statement: string, limit: number): string {
+  const firstWord = stripCommentsAndStrings(statement).trim().toLowerCase().split(/\s+/)[0] ?? '';
+  if (firstWord === 'explain' || firstWord === 'show') return statement;
+  return `SELECT * FROM (${statement}) AS admin_sql_console LIMIT ${limit}`;
+}
+
+/** JSON-safe values: Prisma returns bigints, dates, buffers and Decimals raw. */
+export function serializeValue(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'bigint') return value.toString();
+  if (value instanceof Date) return value.toISOString();
+  if (Buffer.isBuffer(value)) return `\\x${value.toString('hex')}`;
+  if (Array.isArray(value)) return value.map(serializeValue);
+  if (typeof value === 'object') {
+    const source = value as Record<string, unknown>;
+    if (typeof source.toFixed === 'function') return String(value);
+    return Object.fromEntries(
+      Object.entries(source).map(([key, entry]) => [key, serializeValue(entry)]),
+    );
+  }
+  return value;
+}
+
+export type AdminSqlResult = {
+  columns: string[];
+  rows: Record<string, unknown>[];
+  rowCount: number;
+  truncated: boolean;
+  durationMs: number;
+};
+
+export async function runAdminSql(input: {
+  sql: string;
+  limit?: number;
+  userId?: string;
+}): Promise<AdminSqlResult> {
+  const limit = Math.min(Math.max(input.limit ?? SQL_MAX_ROWS, 1), SQL_MAX_ROWS);
+  const statement = assertReadOnlySql(input.sql);
+  const query = buildBoundedQuery(statement, limit + 1);
+
+  logger.warn('Admin SQL console query', { userId: input.userId, sql: statement, limit });
+
+  const started = Date.now();
+  let rows: Record<string, unknown>[];
+  try {
+    rows = await prisma.$transaction(async (tx) => {
+      await tx.$executeRawUnsafe('SET TRANSACTION READ ONLY');
+      await tx.$executeRawUnsafe(`SET LOCAL statement_timeout = ${SQL_TIMEOUT_MS}`);
+      return (await tx.$queryRawUnsafe(query)) as Record<string, unknown>[];
+    });
+  } catch (error) {
+    throw new TRPCError({
+      code: 'BAD_REQUEST',
+      message: error instanceof Error ? error.message : 'Query failed',
+      cause: error,
+    });
+  }
+
+  const durationMs = Date.now() - started;
+  const truncated = rows.length > limit;
+  const capped = truncated ? rows.slice(0, limit) : rows;
+
+  return {
+    columns: capped.length > 0 ? Object.keys(capped[0]) : [],
+    rows: capped.map(
+      (row) =>
+        Object.fromEntries(
+          Object.entries(row).map(([key, value]) => [key, serializeValue(value)]),
+        ) as Record<string, unknown>,
+    ),
+    rowCount: capped.length,
+    truncated,
+    durationMs,
+  };
+}
+
+export type AdminSqlTable = {
+  table: string;
+  columns: { name: string; type: string; nullable: boolean }[];
+};
+
+/** Schema browser for the console sidebar. */
+export async function listSqlSchemaForAdmin(): Promise<{ tables: AdminSqlTable[] }> {
+  const rows = (await prisma.$queryRawUnsafe(`
+    SELECT table_name, column_name, data_type, is_nullable
+    FROM information_schema.columns
+    WHERE table_schema = 'public'
+    ORDER BY table_name, ordinal_position
+  `)) as {
+    table_name: string;
+    column_name: string;
+    data_type: string;
+    is_nullable: string;
+  }[];
+
+  const tables = new Map<string, AdminSqlTable>();
+  for (const row of rows) {
+    const table = tables.get(row.table_name) ?? { table: row.table_name, columns: [] };
+    table.columns.push({
+      name: row.column_name,
+      type: row.data_type,
+      nullable: row.is_nullable === 'YES',
+    });
+    tables.set(row.table_name, table);
+  }
+
+  return { tables: [...tables.values()] };
+}