@studious-lms/server 1.8.0 → 1.11.0

package/tests/unit/services/permissions.test.ts

@@ -0,0 +1,463 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { TRPCError } from "@trpc/server";
+
+const { prismaMocks, resolveFolderScope } = vi.hoisted(() => ({
+  prismaMocks: {
+    user: { findUnique: vi.fn() },
+    class: { findMany: vi.fn(), findFirst: vi.fn(), findUnique: vi.fn() },
+    department: { findMany: vi.fn(), findUnique: vi.fn() },
+    schoolMembership: { findMany: vi.fn(), findFirst: vi.fn() },
+    folder: { findUnique: vi.fn() },
+    file: { findUnique: vi.fn() },
+    tag: { findUnique: vi.fn() },
+    permission: {
+      findFirst: vi.fn(),
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+    },
+  },
+  resolveFolderScope: vi.fn(),
+}));
+
+vi.mock("../../../src/lib/prisma.js", () => ({
+  prisma: prismaMocks,
+}));
+
+vi.mock("../../../src/models/cloudStorage.js", () => ({
+  resolveFolderScope,
+}));
+
+import {
+  expandUserPrincipals,
+  getScopeDefault,
+  grantPermission,
+  listSharedWithMe,
+  requireFileAccess,
+  requireFolderAccess,
+} from "../../../src/services/permissions.js";
+
+function setNoMemberships() {
+  prismaMocks.user.findUnique.mockResolvedValue({ tags: [] });
+  prismaMocks.class.findMany.mockResolvedValue([]);
+  prismaMocks.department.findMany.mockResolvedValue([]);
+  prismaMocks.schoolMembership.findMany.mockResolvedValue([]);
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  prismaMocks.permission.findFirst.mockResolvedValue(null);
+  prismaMocks.permission.findMany.mockResolvedValue([]);
+});
+
+describe("expandUserPrincipals", () => {
+  test("collects tags, classes (split by role), departments, and active school memberships", async () => {
+    prismaMocks.user.findUnique.mockResolvedValue({
+      tags: [{ id: "tag-a" }, { id: "tag-b" }],
+    });
+    prismaMocks.class.findMany
+      .mockResolvedValueOnce([{ id: "class-teach" }])
+      .mockResolvedValueOnce([
+        { id: "class-stud-1" },
+        { id: "class-stud-2" },
+      ]);
+    prismaMocks.department.findMany.mockResolvedValue([{ id: "dep-1" }]);
+    prismaMocks.schoolMembership.findMany.mockResolvedValue([
+      { schoolId: "school-1" },
+    ]);
+
+    const principals = await expandUserPrincipals("user-1");
+
+    expect(principals.tagIds).toEqual(["tag-a", "tag-b"]);
+    expect(principals.classTeacherIds).toEqual(["class-teach"]);
+    expect(principals.classStudentIds).toEqual(["class-stud-1", "class-stud-2"]);
+    expect(principals.classIds.sort()).toEqual(
+      ["class-teach", "class-stud-1", "class-stud-2"].sort()
+    );
+    expect(principals.departmentIds).toEqual(["dep-1"]);
+    expect(principals.schoolIds).toEqual(["school-1"]);
+  });
+
+  test("returns empty arrays when the user has no memberships", async () => {
+    setNoMemberships();
+    const principals = await expandUserPrincipals("user-1");
+    expect(principals.tagIds).toEqual([]);
+    expect(principals.classIds).toEqual([]);
+    expect(principals.departmentIds).toEqual([]);
+    expect(principals.schoolIds).toEqual([]);
+  });
+});
+
+describe("getScopeDefault", () => {
+  test("class teacher gets WRITE, student gets READ, outsider gets null", async () => {
+    prismaMocks.class.findFirst
+      .mockResolvedValueOnce({
+        id: "class-1",
+        schoolId: null,
+        teachers: [{ id: "user-1" }],
+        students: [],
+      })
+      .mockResolvedValueOnce({
+        id: "class-1",
+        schoolId: null,
+        teachers: [],
+        students: [{ id: "user-2" }],
+      })
+      .mockResolvedValueOnce({
+        id: "class-1",
+        schoolId: null,
+        teachers: [],
+        students: [],
+      });
+
+    expect(
+      await getScopeDefault("user-1", { kind: "CLASS", classId: "class-1" })
+    ).toBe("WRITE");
+    expect(
+      await getScopeDefault("user-2", { kind: "CLASS", classId: "class-1" })
+    ).toBe("READ");
+    expect(
+      await getScopeDefault("user-3", { kind: "CLASS", classId: "class-1" })
+    ).toBeNull();
+  });
+
+  test("school admin gets WRITE on class even without being teacher/student", async () => {
+    prismaMocks.class.findFirst.mockResolvedValueOnce({
+      id: "class-1",
+      schoolId: "school-1",
+      teachers: [],
+      students: [],
+    });
+    prismaMocks.schoolMembership.findFirst.mockResolvedValueOnce({
+      id: "membership-1",
+    });
+
+    expect(
+      await getScopeDefault("admin-1", { kind: "CLASS", classId: "class-1" })
+    ).toBe("WRITE");
+  });
+
+  test("school storage: ADMIN/TEACHER write, STUDENT reads, non-member denied", async () => {
+    prismaMocks.schoolMembership.findFirst
+      .mockResolvedValueOnce({ role: "TEACHER" })
+      .mockResolvedValueOnce({ role: "STUDENT" })
+      .mockResolvedValueOnce(null);
+
+    expect(
+      await getScopeDefault("u", {
+        kind: "SCHOOL_STORAGE",
+        schoolId: "school-1",
+      })
+    ).toBe("WRITE");
+    expect(
+      await getScopeDefault("u", {
+        kind: "SCHOOL_STORAGE",
+        schoolId: "school-1",
+      })
+    ).toBe("READ");
+    expect(
+      await getScopeDefault("u", {
+        kind: "SCHOOL_STORAGE",
+        schoolId: "school-1",
+      })
+    ).toBeNull();
+  });
+
+  test("personal scope only the owner has WRITE", async () => {
+    expect(
+      await getScopeDefault("user-1", { kind: "PERSONAL", userId: "user-1" })
+    ).toBe("WRITE");
+    expect(
+      await getScopeDefault("user-2", { kind: "PERSONAL", userId: "user-1" })
+    ).toBeNull();
+  });
+});
+
+describe("requireFolderAccess", () => {
+  beforeEach(() => {
+    setNoMemberships();
+  });
+
+  test("scope default grants access without consulting permissions", async () => {
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "user-1",
+    });
+
+    const result = await requireFolderAccess("user-1", "folder-1", "READ");
+    expect(result.scopeDefault).toBe("WRITE");
+    expect(result.viaGrant).toBe(false);
+    expect(prismaMocks.permission.findFirst).not.toHaveBeenCalled();
+  });
+
+  test("ancestor inheritance: grant on parent folder lets a non-member access a child", async () => {
+    // user is in NO scope (PERSONAL of someone else => null default)
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "owner-x",
+    });
+    // child folder has parent
+    prismaMocks.folder.findUnique
+      .mockResolvedValueOnce({ parentFolderId: "folder-parent" })
+      .mockResolvedValueOnce({ parentFolderId: null });
+    prismaMocks.permission.findFirst.mockResolvedValueOnce({
+      folderId: "folder-parent",
+    });
+
+    const result = await requireFolderAccess("user-1", "folder-child", "READ");
+    expect(result.viaGrant).toBe(true);
+    expect(result.scopeDefault).toBeNull();
+  });
+
+  test("direct grant on the folder itself grants access", async () => {
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "owner-x",
+    });
+    prismaMocks.folder.findUnique.mockResolvedValueOnce({
+      parentFolderId: null,
+    });
+    prismaMocks.permission.findFirst.mockResolvedValueOnce({
+      folderId: "folder-1",
+    });
+
+    const result = await requireFolderAccess("user-1", "folder-1", "READ");
+    expect(result.viaGrant).toBe(true);
+  });
+
+  test("denies when neither scope default nor any ancestor grant matches", async () => {
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "owner-x",
+    });
+    prismaMocks.folder.findUnique.mockResolvedValueOnce({
+      parentFolderId: null,
+    });
+    prismaMocks.permission.findFirst.mockResolvedValueOnce(null);
+
+    await expect(
+      requireFolderAccess("user-1", "folder-1", "READ")
+    ).rejects.toThrow(TRPCError);
+  });
+
+  test("WRITE denied when only a READ grant exists", async () => {
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "owner-x",
+    });
+    prismaMocks.folder.findUnique.mockResolvedValueOnce({
+      parentFolderId: null,
+    });
+    // resolver query is filtered with `level: "WRITE"` so a READ grant
+    // simply doesn't match — returns null.
+    prismaMocks.permission.findFirst.mockResolvedValueOnce(null);
+
+    await expect(
+      requireFolderAccess("user-1", "folder-1", "WRITE")
+    ).rejects.toThrow(TRPCError);
+  });
+
+  test("Drive-style: mutatesSelf WRITE is denied via grant, allowed via scope default", async () => {
+    // Case A: grantee has WRITE via explicit grant, but the action targets
+    // the share root itself — must be rejected with the Drive-style message.
+    resolveFolderScope.mockResolvedValueOnce({
+      kind: "PERSONAL",
+      userId: "owner-x", // user-1 is NOT the owner -> no scope default
+    });
+
+    await expect(
+      requireFolderAccess("user-1", "folder-1", "WRITE", { mutatesSelf: true })
+    ).rejects.toThrow(/owner/i);
+    // We never even got to the grant lookup because mutatesSelf short-circuits.
+    expect(prismaMocks.permission.findFirst).not.toHaveBeenCalled();
+
+    // Case B: the actual scope owner can mutatesSelf without issue.
+    resolveFolderScope.mockResolvedValueOnce({
+      kind: "PERSONAL",
+      userId: "user-1",
+    });
+    const result = await requireFolderAccess(
+      "user-1",
+      "folder-1",
+      "WRITE",
+      { mutatesSelf: true }
+    );
+    expect(result.scopeDefault).toBe("WRITE");
+    expect(result.viaGrant).toBe(false);
+  });
+});
+
+describe("requireFileAccess", () => {
+  beforeEach(() => {
+    setNoMemberships();
+  });
+
+  test("delegates to folder access when the file lives in a folder", async () => {
+    prismaMocks.file.findUnique.mockResolvedValueOnce({
+      id: "file-1",
+      userId: null,
+      folderId: "folder-x",
+    });
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "user-1",
+    });
+
+    const result = await requireFileAccess("user-1", "file-1", "READ");
+    expect(result.scopeDefault).toBe("WRITE");
+  });
+
+  test("unfiled files fall back to owner-only access", async () => {
+    prismaMocks.file.findUnique.mockResolvedValueOnce({
+      id: "file-1",
+      userId: "user-1",
+      folderId: null,
+    });
+
+    const result = await requireFileAccess("user-1", "file-1", "READ");
+    expect(result.scopeDefault).toBe("WRITE");
+    expect(result.viaGrant).toBe(false);
+  });
+
+  test("unfiled files with another owner deny access", async () => {
+    prismaMocks.file.findUnique.mockResolvedValueOnce({
+      id: "file-1",
+      userId: "owner-x",
+      folderId: null,
+    });
+
+    await expect(
+      requireFileAccess("user-1", "file-1", "READ")
+    ).rejects.toThrow(TRPCError);
+  });
+});
+
+describe("listSharedWithMe (topmost-grant computation)", () => {
+  beforeEach(() => {
+    setNoMemberships();
+  });
+
+  test("filters out grants whose ancestor is also granted (collapse to the topmost)", async () => {
+    prismaMocks.permission.findMany.mockResolvedValueOnce([
+      { id: "g-parent", folderId: "parent" },
+      { id: "g-child", folderId: "child" },
+    ]);
+
+    // Ancestor walks: child -> parent; parent -> root (no parent).
+    prismaMocks.folder.findUnique
+      // Walk for "parent" (ancestors)
+      .mockResolvedValueOnce({ parentFolderId: null })
+      // Folder details fetch for "parent"
+      .mockResolvedValueOnce({
+        id: "parent",
+        name: "Parent",
+        color: null,
+      })
+      // Walk for "child" (ancestors) — first hit child, then parent
+      .mockResolvedValueOnce({ parentFolderId: "parent" })
+      .mockResolvedValueOnce({ parentFolderId: null });
+
+    resolveFolderScope.mockResolvedValue(null);
+
+    const result = await listSharedWithMe("user-1");
+    expect(result.folders.map((f) => f.id)).toEqual(["parent"]);
+    expect(result.files).toEqual([]);
+  });
+
+  test("filters out grants already covered by the user's scope default", async () => {
+    prismaMocks.permission.findMany.mockResolvedValueOnce([
+      { id: "g-1", folderId: "folder-1" },
+    ]);
+    prismaMocks.folder.findUnique.mockResolvedValueOnce({
+      parentFolderId: null,
+    });
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "user-1",
+    });
+    // user-1 IS the owner -> scope default WRITE -> filtered out
+
+    const result = await listSharedWithMe("user-1");
+    expect(result.folders).toEqual([]);
+  });
+});
+
+describe("grantPermission cross-school leak prevention", () => {
+  beforeEach(() => {
+    setNoMemberships();
+  });
+
+  test("rejects a TAG principal whose school differs from the target's scope school", async () => {
+    // Granter has WRITE via scope default (class teacher in school-A).
+    resolveFolderScope.mockResolvedValue({
+      kind: "CLASS",
+      classId: "class-A",
+    });
+    prismaMocks.class.findFirst.mockResolvedValueOnce({
+      id: "class-A",
+      schoolId: "school-A",
+      teachers: [{ id: "granter-1" }],
+      students: [],
+    });
+    // resolveTargetSchoolId(folder) -> walks scope -> school-A
+    prismaMocks.class.findUnique
+      .mockResolvedValueOnce({ schoolId: "school-A" })
+      // principalSchoolId(TAG: tag-X) -> school-B
+      .mockResolvedValue(null);
+    prismaMocks.tag.findUnique.mockResolvedValueOnce({ schoolId: "school-B" });
+
+    await expect(
+      grantPermission("granter-1", {
+        folderId: "folder-1",
+        principal: { kind: "TAG", tagId: "tag-X" },
+        level: "READ",
+      })
+    ).rejects.toThrow(/different school/);
+  });
+
+  test("rejects sharing a personal-scope folder with a non-USER principal", async () => {
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "granter-1",
+    });
+    // resolveTargetSchoolId(folder) -> personal scope -> null
+    prismaMocks.tag.findUnique.mockResolvedValueOnce({ schoolId: "school-A" });
+
+    await expect(
+      grantPermission("granter-1", {
+        folderId: "folder-1",
+        principal: { kind: "TAG", tagId: "tag-X" },
+        level: "READ",
+      })
+    ).rejects.toThrow(/specific users/i);
+  });
+
+  test("re-granting the same (folder, principal) updates the existing row instead of erroring", async () => {
+    // Granter has WRITE via personal-scope ownership.
+    resolveFolderScope.mockResolvedValue({
+      kind: "PERSONAL",
+      userId: "granter-1",
+    });
+    // Existing READ grant for user-X on this folder.
+    prismaMocks.permission.findFirst.mockResolvedValueOnce({ id: "perm-1" });
+    prismaMocks.permission.update.mockResolvedValueOnce({
+      id: "perm-1",
+      level: "WRITE",
+    });
+
+    const result = await grantPermission("granter-1", {
+      folderId: "folder-1",
+      principal: { kind: "USER", userId: "user-X" },
+      level: "WRITE",
+    });
+
+    expect(prismaMocks.permission.update).toHaveBeenCalledWith({
+      where: { id: "perm-1" },
+      data: { level: "WRITE", grantedById: "granter-1" },
+    });
+    expect(prismaMocks.permission.create).not.toHaveBeenCalled();
+    expect(result.level).toBe("WRITE");
+  });
+});

package/tests/unit/services/studentProgress.test.ts

@@ -31,6 +31,9 @@ import {
   chatAboutStudentProgress,
   dismissStudentRecommendation,
   getClassProgressRecommendations,
+  getStudentProgressFocus,
+  getStudentProgressForecast,
+  getStudentProgressInsights,
   getStudentProgressRecommendations,
 } from "../../../src/services/studentProgress.js";
 
@@ -221,7 +224,10 @@ describe("studentProgress service", () => {
       ],
     });
 
-    const result = await getClassProgressRecommendations("teacher-1", "class-1");
+    const result = await getClassProgressRecommendations(
+      "teacher-1",
+      "class-1",
+    );
 
     expect(result.class).toMatchObject({
       id: "class-1",
@@ -297,7 +303,9 @@ describe("studentProgress service", () => {
     });
 
     expect(result.isFallback).toBe(true);
-    expect(result.message).toContain("Student One's current overall grade is 60%.");
+    expect(result.message).toContain(
+      "Student One's current overall grade is 60%.",
+    );
     expect(result.message).toContain("1 assignment appears overdue.");
     expect(result.message).toContain("1 graded assignment is below 70%.");
     expect(logger.error).toHaveBeenCalled();
@@ -340,6 +348,164 @@ describe("studentProgress service", () => {
     expect(result.recommendations).toHaveLength(0);
   });
 
+  test("generates structured student insights from progress context", async () => {
+    isTeacherInClass.mockResolvedValue(true);
+    inference.mockResolvedValue({
+      summary:
+        "Student One is at 72% with a steady trajectory. Fractions Test is a strength, while Missing Quiz needs attention.",
+      strengths: [
+        { label: "Fraction fluency", evidence: "Fractions Test scored 84%." },
+        { label: "Quiz recovery", evidence: "Retake Review improved to 78%." },
+      ],
+      growth: [
+        { label: "Missing work", evidence: "Missing Quiz is overdue." },
+        { label: "Test precision", evidence: "Unit Test scored 62%." },
+      ],
+      talkingPoints: [
+        "What helped you on Fractions Test?",
+        "What blocked Missing Quiz?",
+        "Which review format would help this week?",
+      ],
+    });
+    prismaMocks.class.findUnique.mockResolvedValue({
+      id: "class-1",
+      name: "Algebra",
+      subject: "Math",
+    });
+    prismaMocks.user.findFirst.mockResolvedValue({
+      id: "student-1",
+      username: "student1",
+      profile: { displayName: "Student One" },
+    });
+    prismaMocks.submission.findMany.mockResolvedValue([
+      createSubmission({
+        id: "graded-submission",
+        gradeReceived: 84,
+        submitted: true,
+        returned: true,
+        submittedAt: daysFromNow(-4),
+        assignment: {
+          id: "graded-assignment",
+          title: "Fractions Test",
+          dueDate: daysFromNow(-5),
+          type: "TEST",
+        },
+      }),
+    ]);
+
+    const result = await getStudentProgressInsights(
+      "teacher-1",
+      "class-1",
+      "student-1",
+    );
+
+    expect(result.strengths[0]?.label).toBe("Fraction fluency");
+    expect(inference).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        expect.objectContaining({ role: "system" }),
+        expect.objectContaining({
+          role: "user",
+          content: expect.stringContaining("Fractions Test"),
+        }),
+      ]),
+      expect.any(Object),
+      expect.objectContaining({
+        reason: "student_progress_insights",
+        metadata: {
+          viewerId: "teacher-1",
+          classId: "class-1",
+          studentId: "student-1",
+        },
+      }),
+    );
+  });
+
+  test("generates a structured student forecast", async () => {
+    isTeacherInClass.mockResolvedValue(false);
+    inference.mockResolvedValue({
+      forecastLow: 62,
+      forecastHigh: 74,
+      risk: "watch",
+      reason:
+        "Recent low score and one missing assignment create moderate risk.",
+    });
+    prismaMocks.class.findUnique.mockResolvedValue({
+      id: "class-1",
+      name: "Algebra",
+      subject: "Math",
+    });
+    prismaMocks.user.findFirst.mockResolvedValue({
+      id: "student-1",
+      username: "student1",
+      profile: { displayName: "Student One" },
+    });
+    prismaMocks.submission.findMany.mockResolvedValue([
+      createSubmission({
+        gradeReceived: 62,
+        submitted: true,
+        returned: true,
+        submittedAt: daysFromNow(-2),
+        assignment: { title: "Unit Test", dueDate: daysFromNow(-3) },
+      }),
+    ]);
+
+    const result = await getStudentProgressForecast(
+      "student-1",
+      "class-1",
+      "student-1",
+    );
+
+    expect(result).toMatchObject({
+      forecastLow: 62,
+      forecastHigh: 74,
+      risk: "watch",
+    });
+    expect(inference).toHaveBeenCalledWith(
+      expect.any(Array),
+      expect.any(Object),
+      expect.objectContaining({ reason: "student_progress_forecast" }),
+    );
+  });
+
+  test("generates student-facing weekly focus items", async () => {
+    isTeacherInClass.mockResolvedValue(false);
+    inference.mockResolvedValue({
+      focusItems: [
+        "Finish Missing Quiz make-up.",
+        "Review Unit Test mistakes.",
+        "Ask for help on fractions.",
+      ],
+    });
+    prismaMocks.class.findUnique.mockResolvedValue({
+      id: "class-1",
+      name: "Algebra",
+      subject: "Math",
+    });
+    prismaMocks.user.findFirst.mockResolvedValue({
+      id: "student-1",
+      username: "student1",
+      profile: { displayName: "Student One" },
+    });
+    prismaMocks.submission.findMany.mockResolvedValue([
+      createSubmission({
+        assignment: { title: "Missing Quiz", dueDate: daysFromNow(-2) },
+      }),
+    ]);
+
+    const result = await getStudentProgressFocus(
+      "student-1",
+      "class-1",
+      "student-1",
+    );
+
+    expect(result.focusItems).toHaveLength(3);
+    expect(inference).toHaveBeenCalledWith(
+      expect.any(Array),
+      expect.any(Object),
+      expect.objectContaining({ reason: "student_progress_focus" }),
+    );
+  });
+
   test("allows teachers to dismiss a recommendation", async () => {
     isTeacherInClass.mockResolvedValue(true);
     prismaMocks.submission.findFirst.mockResolvedValue({ id: "submission-1" });