@studious-lms/server 1.7.0 → 1.9.0

package/src/services/folder.ts

@@ -1,316 +1,478 @@
 /**
- * Folder service – CRUD for class folders, file uploads, and folder hierarchy.
+ * Folder service — single source of truth for folders across every scope.
+ *
+ * A `Folder` can live inside one of four scopes (see `models/cloudStorage.ts`):
+ * class files, school storage, school documents, or a user's personal storage.
+ * Permissions and ownership are derived from the scope by walking up the tree
+ * to the root, so callers can either pass a `scope` (when there is no folder
+ * id yet, e.g. browsing the root) or just a `folderId` (everything else).
+ *
+ * The class files page and the global cloud-storage view both consume these
+ * endpoints — no duplicate routers.
  */
 import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
 import {
-  findClassWithTeacher,
+  CloudScope,
+  createSubFolder,
+  deleteFolderById,
   findFolderById,
-  findOrCreateRootFolder,
-  createFolder,
   findFolderWithContents,
-  findChildFolders,
-  findRootFolderWithContents,
-  findFolderByIdWithCount,
-  deleteFolderById,
-  updateFolderParent,
-  updateFolder,
-  findFolderByIdForTraversal,
-} from "../models/folder.js";
-import { createDirectUploadFiles } from "../lib/fileUpload.js";
+  findOrCreateScopeRoot,
+  listFolderBreadcrumbs,
+  renameFolder,
+  resolveFolderScope,
+} from "../models/cloudStorage.js";
+import {
+  createDirectUploadFiles,
+  type DirectFileData,
+  confirmDirectUpload,
+} from "../lib/fileUpload.js";
+import {
+  type AccessLevel,
+  getScopeDefault,
+  listSharedWithMe,
+  requireFolderAccess as requireFolderAccessResolved,
+} from "./permissions.js";
+
+interface AccessResult {
+  scope: CloudScope;
+  canWrite: boolean;
+  /**
+   * True when the viewer's access comes through an explicit grant rather than
+   * scope membership. Used by `browseFolder` to surface a "Shared with me"
+   * heading instead of the underlying scope's title — the grantee shouldn't
+   * see the folder labelled with the owner's scope.
+   */
+  viaGrant: boolean;
+}
 
-/** Create a folder in a class. Teacher-only. */
-export async function createFolderRecord(
+/**
+ * Scope-default-only check: used when there is no folder id yet (browsing or
+ * creating at the scope root). Does *not* consult explicit grants — those only
+ * apply to specific folders. Explicit-grant access to sub-folders surfaces via
+ * the "Shared with me" virtual scope, not by being a scope member.
+ */
+async function requireScopeAccess(
   userId: string,
-  input: {
-    classId: string;
-    name: string;
-    parentFolderId?: string | null;
-    color?: string;
+  scope: CloudScope,
+  level: AccessLevel
+): Promise<AccessResult> {
+  if (scope.kind === "CLASS") {
+    const classExists = await prisma.class.findFirst({
+      where: { id: scope.classId },
+      select: { id: true },
+    });
+    if (!classExists) {
+      throw new TRPCError({ code: "NOT_FOUND", message: "Class not found" });
+    }
   }
-) {
-  const classData = await findClassWithTeacher(input.classId, userId);
-  if (!classData) {
+  const granted = await getScopeDefault(userId, scope);
+  if (!granted) {
     throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Class not found or you are not a teacher",
+      code: "FORBIDDEN",
+      message:
+        scope.kind === "CLASS"
+          ? "You don't have access to this class"
+          : scope.kind === "SCHOOL_STORAGE"
+          ? "You aren't a member of this institution"
+          : "You can only access your own personal storage",
     });
   }
-
-  let parentFolderId = input.parentFolderId;
-  if (!parentFolderId) {
-    const root = await findOrCreateRootFolder(input.classId);
-    parentFolderId = root.id;
-  } else {
-    const parentFolder = await findFolderById(parentFolderId);
-    if (!parentFolder) {
-      throw new TRPCError({
-        code: "NOT_FOUND",
-        message: "Parent folder not found",
-      });
-    }
-  }
-
-  return createFolder({
-    name: input.name,
-    parentFolderId,
-    color: input.color,
-  });
-}
-
-/** Get folder with its contents (subfolders and files). */
-export async function getFolder(folderId: string) {
-  const folder = await findFolderWithContents(folderId);
-  if (!folder) {
+  if (level === "WRITE" && granted !== "WRITE") {
     throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Folder not found",
+      code: "FORBIDDEN",
+      message:
+        scope.kind === "CLASS"
+          ? "Only class teachers can modify class files"
+          : "Only teachers and admins can modify institution storage",
     });
   }
-  return folder;
-}
-
-export async function getChildFolders(classId: string) {
-  const root = await findOrCreateRootFolder(classId);
-  return findChildFolders(root.id);
+  // Scope-default-only path; access cannot be via a grant here.
+  return { scope, canWrite: granted === "WRITE", viaGrant: false };
 }
 
-export async function getFolderChildren(folderId: string, classId: string) {
-  return findChildFolders(folderId);
+/**
+ * Folder-level access check. Delegates to the central resolver which consults
+ * explicit grants in addition to the scope default. Returns the scope and a
+ * canWrite flag indicating whether the user has WRITE here (used by the UI to
+ * gate the "New folder" / "Upload" buttons during a READ-level browse).
+ *
+ * Pass `mutatesSelf: true` for actions that target the folder itself (rename,
+ * delete, move-this-folder). Drive-style: explicit grants don't authorize
+ * those — only scope-default WRITE does. Mutations of children should NOT
+ * pass this flag.
+ */
+export async function requireFolderAccess(
+  userId: string,
+  folderId: string,
+  level: AccessLevel,
+  opts: { mutatesSelf?: boolean } = {}
+): Promise<AccessResult> {
+  const result = await requireFolderAccessResolved(userId, folderId, level, opts);
+  if (!result.scope) {
+    // resolveFolderScope returns null only for missing folders; the resolver
+    // would have already thrown NOT_FOUND in that case.
+    throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
+  }
+  let canWrite = result.scopeDefault === "WRITE";
+  if (!canWrite && level !== "WRITE") {
+    // We came in with READ; check whether the user *also* has WRITE so the UI
+    // can show the right affordances. Cheaper to do this only when needed.
+    try {
+      await requireFolderAccessResolved(userId, folderId, "WRITE");
+      canWrite = true;
+    } catch {
+      canWrite = false;
+    }
+  } else if (level === "WRITE") {
+    canWrite = true;
+  }
+  return { scope: result.scope, canWrite, viaGrant: result.viaGrant };
 }
 
-export async function getRootFolder(classId: string) {
-  const root = await findOrCreateRootFolder(classId);
-  const rootWithContents = await findRootFolderWithContents(classId);
-  if (!rootWithContents) {
-    throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Root folder not found",
-    });
+function scopesEqual(a: CloudScope, b: CloudScope): boolean {
+  if (a.kind !== b.kind) return false;
+  switch (a.kind) {
+    case "CLASS":
+      return a.classId === (b as typeof a).classId;
+    case "SCHOOL_STORAGE":
+      return a.schoolId === (b as typeof a).schoolId;
+    case "PERSONAL":
+      return a.userId === (b as typeof a).userId;
   }
-  return rootWithContents;
 }
 
-export async function uploadFilesToFolder(
+/** Browse a folder. Pass `folderId` to drill into a specific folder, or a `scope` to land on its root. */
+export async function browseFolder(
   userId: string,
-  classId: string,
-  folderId: string,
-  files: { name: string; type: string; size: number }[]
+  input: { folderId: string } | { scope: CloudScope }
 ) {
-  const classData = await findClassWithTeacher(classId, userId);
-  if (!classData) {
-    throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Class not found or you are not a teacher",
-    });
+  let scope: CloudScope;
+  let folderId: string | undefined;
+  let canWrite: boolean;
+  let viaGrant: boolean;
+
+  if ("folderId" in input) {
+    folderId = input.folderId;
+    // `requireFolderAccess` consults explicit grants in addition to the scope
+    // default, so users can drill into folders shared with them via "Shared
+    // with me" without being scope members.
+    const access = await requireFolderAccess(userId, folderId, "READ");
+    scope = access.scope;
+    canWrite = access.canWrite;
+    viaGrant = access.viaGrant;
+  } else {
+    scope = input.scope;
+    const access = await requireScopeAccess(userId, scope, "READ");
+    canWrite = access.canWrite;
+    viaGrant = false;
   }
 
-  const folder = await findFolderById(folderId);
+  const targetId = folderId ?? (await findOrCreateScopeRoot(scope)).id;
+
+  const [folder, breadcrumbs] = await Promise.all([
+    findFolderWithContents(targetId),
+    listFolderBreadcrumbs(targetId, userId),
+  ]);
+
   if (!folder) {
-    throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Folder not found",
-    });
+    throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
   }
 
-  const uploadedFiles = await createDirectUploadFiles(files, userId, folderId);
   return {
-    success: true,
-    uploadedCount: uploadedFiles.length,
+    folder,
+    breadcrumbs,
+    canWrite,
+    scope,
+    /**
+     * When the viewer's access comes through an explicit grant (not scope
+     * membership), the UI should label the root as "Shared with me" rather
+     * than the underlying scope's title. The grantee may not even be a
+     * member of that scope — showing "My Files" or "Class Files" would be
+     * misleading. Null when the viewer is a regular scope member.
+     */
+    displayRoot: viaGrant
+      ? { kind: "SHARED_WITH_ME" as const, name: "Shared with me" }
+      : null,
+  };
+}
+
+/**
+ * Drive-style "Shared with me" — surfaces every top-most folder/file the user
+ * has an explicit grant on (filtering out anything already covered by their
+ * scope defaults). Shaped like a folder so the existing folder-browser UI can
+ * render it without special cases.
+ *
+ * The pseudo-folder has a synthetic id (`shared-with-me`) and the foreign-key
+ * columns set to null — the UI should never try to mutate it directly. The
+ * union shape matches `browseFolder`'s return type so the same client query
+ * can render either.
+ */
+export async function browseSharedWithMe(userId: string) {
+  const { folders } = await listSharedWithMe(userId);
+  return {
+    folder: {
+      id: "shared-with-me",
+      name: "Shared with me",
+      color: null,
+      classId: null,
+      schoolStorageId: null,
+      personalOwnerId: null,
+      scope: "GENERIC" as const,
+      parentFolderId: null,
+      parentFolder: null,
+      childFolders: folders.map((f) => ({
+        id: f.id,
+        name: f.name,
+        color: f.color,
+        _count: { files: 0, childFolders: 0 },
+      })),
+      // No file-level grants in v1 — files always live under a granted folder.
+      files: [] as {
+        id: string;
+        name: string;
+        type: string;
+        size: number | null;
+        path: string;
+        uploadedAt: Date | null;
+        user: { id: string; username: string } | null;
+      }[],
+    },
+    breadcrumbs: [{ id: "shared-with-me", name: "Shared with me" }],
+    canWrite: false,
+    scope: { kind: "PERSONAL" as const, userId } satisfies CloudScope,
+    /** Same `displayRoot` shape as `browseFolder` so the client union is uniform. */
+    displayRoot: {
+      kind: "SHARED_WITH_ME" as const,
+      name: "Shared with me",
+    },
   };
 }
 
-export async function deleteFolderRecord(
+export async function getRootFolder(userId: string, scope: CloudScope) {
+  const result = await browseFolder(userId, { scope });
+  return result.folder;
+}
+
+export async function getFolder(userId: string, folderId: string) {
+  const result = await browseFolder(userId, { folderId });
+  return result.folder;
+}
+
+export async function getFolderBreadcrumbs(userId: string, folderId: string) {
+  await requireFolderAccess(userId, folderId, "READ");
+  return listFolderBreadcrumbs(folderId);
+}
+
+export async function getFolderParents(userId: string, folderId: string) {
+  // Permission: user can read this folder.
+  await requireFolderAccess(userId, folderId, "READ");
+  const breadcrumbs = await listFolderBreadcrumbs(folderId);
+  // Existing API returned full folder records — re-fetch them.
+  return Promise.all(
+    breadcrumbs.map((b) => findFolderById(b.id))
+  );
+}
+
+export async function createFolderRecord(
   userId: string,
-  classId: string,
-  folderId: string
+  input: {
+    name: string;
+    parentFolderId?: string | null;
+    color?: string;
+    scope?: CloudScope;
+  }
 ) {
-  const classData = await findClassWithTeacher(classId, userId);
-  if (!classData) {
-    throw new TRPCError({
-      code: "FORBIDDEN",
-      message: "Class not found or you are not a teacher",
-    });
+  let parentId: string;
+  if (input.parentFolderId) {
+    parentId = input.parentFolderId;
+    await requireFolderAccess(userId, parentId, "WRITE");
+  } else {
+    if (!input.scope) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "scope is required when parentFolderId is omitted",
+      });
+    }
+    await requireScopeAccess(userId, input.scope, "WRITE");
+    parentId = (await findOrCreateScopeRoot(input.scope)).id;
   }
+  return createSubFolder({
+    name: input.name.trim(),
+    parentFolderId: parentId,
+    color: input.color,
+  });
+}
 
-  const folder = await findFolderByIdWithCount(folderId);
+export async function updateFolderRecord(
+  userId: string,
+  input: { folderId: string; name?: string; color?: string }
+) {
+  const folder = await findFolderById(input.folderId);
   if (!folder) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
+  }
+  if (!folder.parentFolderId) {
     throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Folder not found",
+      code: "BAD_REQUEST",
+      message: "Cannot rename a root folder",
     });
   }
+  // Rename targets the folder itself — Drive-style guard reserves this for
+  // scope-default WRITE (explicit grants don't authorize renaming the share).
+  await requireFolderAccess(userId, input.folderId, "WRITE", {
+    mutatesSelf: true,
+  });
+  return renameFolder(
+    input.folderId,
+    input.name?.trim() ?? folder.name,
+    input.color
+  );
+}
 
-  // Verify folder belongs to class (traverse to root)
-  let currentId: string | null = folderId;
-  let belongsToClass = false;
-  while (currentId) {
-    const current = await findFolderByIdForTraversal(currentId);
-    if (!current) break;
-    if (current.classId === classId) {
-      belongsToClass = true;
-      break;
-    }
-    currentId = current.parentFolderId;
+export async function deleteFolder(userId: string, folderId: string) {
+  const folder = await findFolderById(folderId);
+  if (!folder) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
   }
-  if (!belongsToClass) {
+  if (!folder.parentFolderId) {
     throw new TRPCError({
-      code: "FORBIDDEN",
-      message: "Folder does not belong to this class",
+      code: "BAD_REQUEST",
+      message: "Cannot delete a root folder",
     });
   }
-
+  // Delete targets the folder itself — same Drive-style guard as rename.
+  await requireFolderAccess(userId, folderId, "WRITE", { mutatesSelf: true });
   await deleteFolderById(folderId);
-  return {
-    success: true,
-    deletedFiles: folder._count.files,
-    deletedFolders: folder._count.childFolders + 1,
-  };
+  return { success: true };
 }
 
 export async function moveFolder(
   userId: string,
-  folderId: string,
-  targetParentFolderId: string,
-  classId: string
+  input: { folderId: string; targetParentFolderId: string }
 ) {
-  const classData = await findClassWithTeacher(classId, userId);
-  if (!classData) {
+  if (input.folderId === input.targetParentFolderId) {
     throw new TRPCError({
-      code: "FORBIDDEN",
-      message: "You must be a teacher of this class to move folders",
+      code: "BAD_REQUEST",
+      message: "Cannot move a folder into itself",
     });
   }
-
-  const folder = await findFolderById(folderId);
-  if (!folder) {
-    throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Folder not found",
-    });
+  const [sourceScope, targetScope] = await Promise.all([
+    resolveFolderScope(input.folderId),
+    resolveFolderScope(input.targetParentFolderId),
+  ]);
+  if (!sourceScope || !targetScope) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
   }
-
-  if (!folder.parentFolderId) {
+  if (!scopesEqual(sourceScope, targetScope)) {
     throw new TRPCError({
       code: "BAD_REQUEST",
-      message: "Cannot move the root folder",
+      message: "Cannot move folders between scopes",
     });
   }
+  // Moving the folder targets it (and the new parent's contents). Source-side
+  // is mutates-self; target-side is regular WRITE on the new parent.
+  await requireFolderAccess(userId, input.folderId, "WRITE", {
+    mutatesSelf: true,
+  });
+  await requireFolderAccess(userId, input.targetParentFolderId, "WRITE");
 
-  if (targetParentFolderId) {
-    const targetParent = await findFolderByIdForTraversal(targetParentFolderId);
-    if (!targetParent) {
-      throw new TRPCError({
-        code: "NOT_FOUND",
-        message: "Target parent folder not found",
-      });
-    }
-
-    if (targetParentFolderId === folderId) {
+  // Don't let a folder land under one of its own descendants.
+  let cursor: string | null = input.targetParentFolderId;
+  while (cursor) {
+    if (cursor === input.folderId) {
       throw new TRPCError({
         code: "BAD_REQUEST",
-        message: "Cannot move a folder into itself",
+        message: "Cannot move a folder into its own descendant",
       });
     }
-
-    let currentParent: typeof targetParent | null = targetParent;
-    while (currentParent?.parentFolderId) {
-      if (currentParent.parentFolderId === folderId) {
-        throw new TRPCError({
-          code: "BAD_REQUEST",
-          message: "Cannot move a folder into its descendant",
-        });
-      }
-      currentParent = await findFolderByIdForTraversal(currentParent.parentFolderId);
-      if (!currentParent) break;
-    }
-  }
-
-  return updateFolderParent(folderId, targetParentFolderId);
-}
-
-export async function updateFolderRecord(
-  folderId: string,
-  name: string,
-  color: string | undefined,
-  classId: string
-) {
-  const folder = await findFolderById(folderId);
-  if (!folder) {
-    throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Folder not found",
-    });
-  }
-
-  if (!name.trim()) {
-    throw new TRPCError({
-      code: "BAD_REQUEST",
-      message: "Folder name cannot be empty",
+    const node = await prisma.folder.findUnique({
+      where: { id: cursor },
+      select: { parentFolderId: true },
     });
+    cursor = node?.parentFolderId ?? null;
   }
 
-  return updateFolder(folderId, {
-    name: name.trim(),
-    ...(color && { color }),
+  await prisma.folder.update({
+    where: { id: input.folderId },
+    data: { parentFolderId: input.targetParentFolderId },
   });
-}
-
-export async function getFolderParents(folderId: string) {
-  const parents: Awaited<ReturnType<typeof findFolderByIdForTraversal>>[] = [];
-  let currentId: string | null = folderId;
-
-  while (currentId) {
-    const folder = await findFolderByIdForTraversal(currentId);
-    if (!folder) break;
-    parents.push(folder);
-    currentId = folder.parentFolderId;
-  }
-
-  return parents;
+  return { success: true };
 }
 
 export async function getFolderUploadUrls(
   userId: string,
-  classId: string,
-  folderId: string,
-  files: { name: string; type: string; size: number }[]
+  input: { folderId: string; files: DirectFileData[] }
 ) {
-  const classData = await findClassWithTeacher(classId, userId);
-  if (!classData) {
-    throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Class not found or you are not a teacher",
-    });
-  }
+  await requireFolderAccess(userId, input.folderId, "WRITE");
+  return createDirectUploadFiles(input.files, userId, input.folderId);
+}
 
-  const folder = await findFolderById(folderId);
-  if (!folder) {
-    throw new TRPCError({
-      code: "NOT_FOUND",
-      message: "Folder not found",
-    });
-  }
+export async function confirmFolderUpload(
+  _userId: string,
+  input: { fileId: string; uploadSuccess: boolean; errorMessage?: string }
+) {
+  // Permission was already checked at upload-url issuance — the file record
+  // exists with PENDING status, and the user holds the session id needed to
+  // PUT bytes. Confirming flips status, so we just trust the call.
+  await confirmDirectUpload(
+    input.fileId,
+    input.uploadSuccess,
+    input.errorMessage
+  );
+  return { success: true };
+}
 
-  let currentFolder: typeof folder | null = folder;
-  let belongsToClass = false;
-  while (currentFolder) {
-    if (currentFolder.classId === classId) {
-      belongsToClass = true;
-      break;
-    }
-    if (currentFolder.parentFolderId) {
-      currentFolder = await findFolderByIdForTraversal(currentFolder.parentFolderId);
-    } else {
-      break;
-    }
-  }
+/** What scopes can this user pick from in cloud-storage UIs? */
+export async function listUserScopes(userId: string) {
+  const memberships = await prisma.schoolMembership.findMany({
+    where: { userId, status: "ACTIVE" },
+    select: {
+      role: true,
+      school: {
+        select: { id: true, name: true, logoId: true },
+      },
+    },
+    orderBy: { createdAt: "asc" },
+  });
 
-  if (!belongsToClass) {
-    throw new TRPCError({
-      code: "FORBIDDEN",
-      message: "Folder does not belong to this class",
-    });
-  }
+  const classes = await prisma.class.findMany({
+    where: {
+      OR: [
+        { teachers: { some: { id: userId } } },
+        { students: { some: { id: userId } } },
+      ],
+    },
+    select: {
+      id: true,
+      name: true,
+      subject: true,
+      section: true,
+      color: true,
+      schoolId: true,
+    },
+    orderBy: { name: "asc" },
+  });
+
+  // Light counts for the "Shared with me" bucket so the UI can hide the entry
+  // when there's nothing to show. Cheap to compute — just counts top-most
+  // grants, not folder/file metadata.
+  const sharedWithMe = await listSharedWithMe(userId);
 
-  return createDirectUploadFiles(files, userId, folderId);
+  return {
+    personal: { kind: "PERSONAL" as const, userId },
+    schools: memberships.map((m) => ({
+      id: m.school.id,
+      name: m.school.name,
+      logoId: m.school.logoId,
+      role: m.role,
+    })),
+    classes,
+    sharedWithMe: {
+      kind: "SHARED_WITH_ME" as const,
+      folderCount: sharedWithMe.folders.length,
+      fileCount: sharedWithMe.files.length,
+    },
+  };
 }