@studious-lms/server 1.26.0 → 1.28.0

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()] };
+}

package/src/services/adminTelemetry.ts

@@ -0,0 +1,194 @@
+import { Prisma } from '@prisma/client';
+import { prisma } from '../lib/prisma.js';
+
+export type DailyPoint = {
+  date: string;
+  signups: number;
+  logins: number;
+  assignments: number;
+  submissions: number;
+  messages: number;
+};
+
+type DayRow = { day: Date; total: bigint };
+
+function dayKey(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+async function dailyCounts(
+  table: Prisma.Sql,
+  column: Prisma.Sql,
+  since: Date,
+  extra: Prisma.Sql = Prisma.empty,
+): Promise<Map<string, number>> {
+  const rows = await prisma.$queryRaw<DayRow[]>`
+    SELECT date_trunc('day', ${column}) AS day, count(*) AS total
+    FROM ${table}
+    WHERE ${column} >= ${since} ${extra}
+    GROUP BY 1
+  `;
+  return new Map(rows.map((row) => [dayKey(row.day), Number(row.total)]));
+}
+
+async function dailyDistinctLogins(since: Date): Promise<Map<string, number>> {
+  const rows = await prisma.$queryRaw<DayRow[]>`
+    SELECT date_trunc('day', "createdAt") AS day,
+           count(DISTINCT "userId") AS total
+    FROM "Session"
+    WHERE "createdAt" >= ${since} AND "type" = 'AUTH' AND "userId" IS NOT NULL
+    GROUP BY 1
+  `;
+  return new Map(rows.map((row) => [dayKey(row.day), Number(row.total)]));
+}
+
+/**
+ * Per-day platform activity for the last `days` days, zero-filled so the admin
+ * chart always has one point per day even when nothing happened.
+ */
+export async function getActivitySeriesForAdmin(input: {
+  days: number;
+}): Promise<{ points: DailyPoint[] }> {
+  const days = Math.min(Math.max(input.days, 1), 90);
+  const since = new Date(Date.now() - (days - 1) * 24 * 60 * 60 * 1000);
+  since.setUTCHours(0, 0, 0, 0);
+
+  const [signups, logins, assignments, submissions, messages] =
+    await Promise.all([
+      dailyCounts(Prisma.sql`"UserProfile"`, Prisma.sql`"createdAt"`, since),
+      dailyDistinctLogins(since),
+      dailyCounts(Prisma.sql`"Assignment"`, Prisma.sql`"createdAt"`, since),
+      dailyCounts(Prisma.sql`"Submission"`, Prisma.sql`"createdAt"`, since),
+      dailyCounts(Prisma.sql`"Message"`, Prisma.sql`"createdAt"`, since),
+    ]);
+
+  const points: DailyPoint[] = [];
+  for (let offset = 0; offset < days; offset += 1) {
+    const date = new Date(since.getTime() + offset * 24 * 60 * 60 * 1000);
+    const key = dayKey(date);
+    points.push({
+      date: key,
+      signups: signups.get(key) ?? 0,
+      logins: logins.get(key) ?? 0,
+      assignments: assignments.get(key) ?? 0,
+      submissions: submissions.get(key) ?? 0,
+      messages: messages.get(key) ?? 0,
+    });
+  }
+
+  return { points };
+}
+
+/** Content inventory plus AI/job health, i.e. "what is actually on the platform". */
+export async function getContentTelemetryForAdmin() {
+  const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+  const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+
+  const [
+    assignments,
+    assignmentsLast7d,
+    submissions,
+    submissionsLast7d,
+    gradedSubmissions,
+    announcements,
+    announcementsLast7d,
+    discussions,
+    messages,
+    messagesLast7d,
+    worksheets,
+    events,
+    modules,
+    files,
+    fileSize,
+    aiCalls7d,
+    aiFailures7d,
+    aiTokens7d,
+    aiByModel7d,
+    runJobsByType7d,
+    failedJobsLast24h,
+  ] = await Promise.all([
+    prisma.assignment.count(),
+    prisma.assignment.count({ where: { createdAt: { gte: weekAgo } } }),
+    prisma.submission.count(),
+    prisma.submission.count({ where: { createdAt: { gte: weekAgo } } }),
+    prisma.submission.count({ where: { gradeReceived: { not: null } } }),
+    prisma.announcement.count(),
+    prisma.announcement.count({ where: { createdAt: { gte: weekAgo } } }),
+    prisma.discussion.count(),
+    prisma.message.count(),
+    prisma.message.count({ where: { createdAt: { gte: weekAgo } } }),
+    prisma.worksheet.count(),
+    prisma.event.count(),
+    prisma.module.count(),
+    prisma.file.count(),
+    prisma.file.aggregate({ _sum: { size: true } }),
+    prisma.aiUsageLog.count({ where: { createdAt: { gte: weekAgo } } }),
+    prisma.aiUsageLog.count({
+      where: { createdAt: { gte: weekAgo }, success: false },
+    }),
+    prisma.aiUsageLog.aggregate({
+      where: { createdAt: { gte: weekAgo } },
+      _sum: { totalTokens: true },
+    }),
+    prisma.aiUsageLog.groupBy({
+      by: ['model'],
+      where: { createdAt: { gte: weekAgo } },
+      _count: { _all: true },
+      _sum: { totalTokens: true },
+    }),
+    prisma.runJob.groupBy({
+      by: ['type', 'status'],
+      where: { createdAt: { gte: weekAgo } },
+      _count: { _all: true },
+    }),
+    prisma.runJob.count({
+      where: { status: 'FAILED', createdAt: { gte: dayAgo } },
+    }),
+  ]);
+
+  const jobsByType = new Map<string, { total: number; failed: number }>();
+  for (const row of runJobsByType7d) {
+    const entry = jobsByType.get(row.type) ?? { total: 0, failed: 0 };
+    entry.total += row._count._all;
+    if (row.status === 'FAILED') entry.failed += row._count._all;
+    jobsByType.set(row.type, entry);
+  }
+
+  return {
+    content: {
+      assignments,
+      assignmentsLast7d,
+      submissions,
+      submissionsLast7d,
+      gradedSubmissions,
+      announcements,
+      announcementsLast7d,
+      discussions,
+      messages,
+      messagesLast7d,
+      worksheets,
+      events,
+      modules,
+      files,
+      storageBytes: Number(fileSize._sum.size ?? 0),
+    },
+    ai: {
+      calls7d: aiCalls7d,
+      failures7d: aiFailures7d,
+      tokens7d: aiTokens7d._sum.totalTokens ?? 0,
+      byModel: aiByModel7d
+        .map((row) => ({
+          model: row.model,
+          calls: row._count._all,
+          tokens: row._sum.totalTokens ?? 0,
+        }))
+        .sort((a, b) => b.calls - a.calls),
+    },
+    jobs: {
+      failedLast24h: failedJobsLast24h,
+      byType: [...jobsByType.entries()]
+        .map(([type, counts]) => ({ type, ...counts }))
+        .sort((a, b) => b.total - a.total),
+    },
+  };
+}