@studious-lms/server 1.7.0 → 1.9.0

package/src/services/tag.ts

@@ -0,0 +1,229 @@
+/**
+ * Tag service — institution-scoped tag CRUD and assignment to taggable
+ * targets (users, classes, rubrics, boundaries).
+ */
+import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
+import {
+  attachTagToTarget,
+  createTag,
+  deleteTag,
+  detachTagFromTarget,
+  getTag,
+  listTagsAttachedTo,
+  listTagsForSchool,
+  type TagTarget,
+  updateTag,
+} from "../models/tag.js";
+import {
+  findActiveSchoolAdminMembership,
+  findSchoolMembership,
+} from "../models/school.js";
+
+async function requireAdmin(schoolId: string, userId: string) {
+  const membership = await findActiveSchoolAdminMembership(schoolId, userId);
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only school admins can manage tags",
+    });
+  }
+}
+
+async function requireMember(schoolId: string, userId: string) {
+  const membership = await findSchoolMembership(schoolId, userId);
+  if (!membership || membership.status !== "ACTIVE") {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "You aren't a member of this institution",
+    });
+  }
+  return membership;
+}
+
+export async function listTags(
+  userId: string,
+  input: { schoolId: string; departmentId?: string | null }
+) {
+  await requireMember(input.schoolId, userId);
+  return listTagsForSchool(input.schoolId, {
+    departmentId: input.departmentId,
+  });
+}
+
+export async function createTagRecord(
+  userId: string,
+  input: {
+    schoolId: string;
+    departmentId?: string | null;
+    name: string;
+    color?: string;
+  }
+) {
+  await requireAdmin(input.schoolId, userId);
+  if (input.departmentId) {
+    const dept = await prisma.department.findUnique({
+      where: { id: input.departmentId },
+      select: { schoolId: true },
+    });
+    if (!dept || dept.schoolId !== input.schoolId) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Department does not belong to this institution",
+      });
+    }
+  }
+  return createTag(input);
+}
+
+export async function updateTagRecord(
+  userId: string,
+  input: {
+    tagId: string;
+    name?: string;
+    color?: string;
+    departmentId?: string | null;
+  }
+) {
+  const tag = await getTag(input.tagId);
+  if (!tag) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Tag not found" });
+  }
+  await requireAdmin(tag.schoolId, userId);
+  if (input.departmentId) {
+    const dept = await prisma.department.findUnique({
+      where: { id: input.departmentId },
+      select: { schoolId: true },
+    });
+    if (!dept || dept.schoolId !== tag.schoolId) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Department does not belong to this institution",
+      });
+    }
+  }
+  return updateTag(input.tagId, {
+    name: input.name,
+    color: input.color,
+    departmentId: input.departmentId,
+  });
+}
+
+export async function deleteTagRecord(userId: string, tagId: string) {
+  const tag = await getTag(tagId);
+  if (!tag) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Tag not found" });
+  }
+  await requireAdmin(tag.schoolId, userId);
+  await deleteTag(tagId);
+  return { success: true };
+}
+
+async function ensureTargetInScope(
+  schoolId: string,
+  target: TagTarget,
+  targetId: string
+) {
+  switch (target) {
+    case "USER": {
+      const inSchool = await prisma.schoolMembership.findFirst({
+        where: { schoolId, userId: targetId, status: "ACTIVE" },
+        select: { id: true },
+      });
+      if (!inSchool) {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: "User is not in this institution",
+        });
+      }
+      return;
+    }
+    case "CLASS": {
+      const inSchool = await prisma.class.findFirst({
+        where: { id: targetId, schoolId },
+        select: { id: true },
+      });
+      if (!inSchool) {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: "Class is not in this institution",
+        });
+      }
+      return;
+    }
+    case "RUBRIC": {
+      const inSchool = await prisma.markScheme.findFirst({
+        where: {
+          id: targetId,
+          OR: [
+            { class: { schoolId } },
+            { department: { schoolId } },
+          ],
+        },
+        select: { id: true },
+      });
+      if (!inSchool) {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: "Rubric is not in this institution",
+        });
+      }
+      return;
+    }
+    case "BOUNDARY": {
+      const inSchool = await prisma.gradingBoundary.findFirst({
+        where: {
+          id: targetId,
+          OR: [
+            { class: { schoolId } },
+            { department: { schoolId } },
+          ],
+        },
+        select: { id: true },
+      });
+      if (!inSchool) {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: "Boundary is not in this institution",
+        });
+      }
+      return;
+    }
+  }
+}
+
+export async function attachTag(
+  userId: string,
+  input: { tagId: string; target: TagTarget; targetId: string }
+) {
+  const tag = await getTag(input.tagId);
+  if (!tag) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Tag not found" });
+  }
+  await requireMember(tag.schoolId, userId);
+  await ensureTargetInScope(tag.schoolId, input.target, input.targetId);
+  return attachTagToTarget(input);
+}
+
+export async function detachTag(
+  userId: string,
+  input: { tagId: string; target: TagTarget; targetId: string }
+) {
+  const tag = await getTag(input.tagId);
+  if (!tag) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Tag not found" });
+  }
+  await requireMember(tag.schoolId, userId);
+  return detachTagFromTarget(input);
+}
+
+export async function getAttachedTags(
+  userId: string,
+  input: { target: TagTarget; targetId: string }
+) {
+  const tags = await listTagsAttachedTo(input.target, input.targetId);
+  if (tags[0]) {
+    await requireMember(tags[0].schoolId, userId);
+  }
+  return tags;
+}

package/src/utils/aiUser.ts

@@ -26,7 +26,6 @@ export async function ensureAIUserExists(): Promise<void> {
         email: 'ai@studious-lms.com',
         password: 'ai-system-user', // Not used for login
         verified: true,
-        role: 'NONE', // Special role for AI
         profile: {
           create: {
             displayName: 'AI Assistant',

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