@studious-lms/server 1.7.0 → 1.9.0

package/dist/services/folder.js

@@ -1,248 +1,378 @@
 /**
- * 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.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4875a835-3cd4-5fcf-8e19-868d405dfe96")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="338c145a-d8eb-5931-9a42-2a9c7c9acc94")}catch(e){}}();
 import { TRPCError } from "@trpc/server";
-import { findClassWithTeacher, findFolderById, findOrCreateRootFolder, createFolder, findFolderWithContents, findChildFolders, findRootFolderWithContents, findFolderByIdWithCount, deleteFolderById, updateFolderParent, updateFolder, findFolderByIdForTraversal, } from "../models/folder.js";
-import { createDirectUploadFiles } from "../lib/fileUpload.js";
-/** Create a folder in a class. Teacher-only. */
-export async function createFolderRecord(userId, input) {
-    const classData = await findClassWithTeacher(input.classId, userId);
-    if (!classData) {
-        throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Class not found or you are not a teacher",
+import { prisma } from "../lib/prisma.js";
+import { createSubFolder, deleteFolderById, findFolderById, findFolderWithContents, findOrCreateScopeRoot, listFolderBreadcrumbs, renameFolder, resolveFolderScope, } from "../models/cloudStorage.js";
+import { createDirectUploadFiles, confirmDirectUpload, } from "../lib/fileUpload.js";
+import { getScopeDefault, listSharedWithMe, requireFolderAccess as requireFolderAccessResolved, } from "./permissions.js";
+/**
+ * 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, scope, level) {
+    if (scope.kind === "CLASS") {
+        const classExists = await prisma.class.findFirst({
+            where: { id: scope.classId },
+            select: { id: true },
         });
-    }
-    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",
-            });
+        if (!classExists) {
+            throw new TRPCError({ code: "NOT_FOUND", message: "Class not found" });
         }
     }
-    return createFolder({
-        name: input.name,
-        parentFolderId,
-        color: input.color,
-    });
-}
-/** Get folder with its contents (subfolders and files). */
-export async function getFolder(folderId) {
-    const folder = await findFolderWithContents(folderId);
-    if (!folder) {
+    const granted = await getScopeDefault(userId, scope);
+    if (!granted) {
         throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Folder not found",
+            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",
         });
     }
-    return folder;
-}
-export async function getChildFolders(classId) {
-    const root = await findOrCreateRootFolder(classId);
-    return findChildFolders(root.id);
-}
-export async function getFolderChildren(folderId, classId) {
-    return findChildFolders(folderId);
-}
-export async function getRootFolder(classId) {
-    const root = await findOrCreateRootFolder(classId);
-    const rootWithContents = await findRootFolderWithContents(classId);
-    if (!rootWithContents) {
+    if (level === "WRITE" && granted !== "WRITE") {
         throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Root 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 rootWithContents;
+    // Scope-default-only path; access cannot be via a grant here.
+    return { scope, canWrite: granted === "WRITE", viaGrant: false };
 }
-export async function uploadFilesToFolder(userId, classId, folderId, files) {
-    const classData = await findClassWithTeacher(classId, userId);
-    if (!classData) {
-        throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Class not found or you are not a teacher",
-        });
+/**
+ * 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, folderId, level, opts = {}) {
+    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" });
     }
-    const folder = await findFolderById(folderId);
-    if (!folder) {
-        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;
+        }
     }
-    const uploadedFiles = await createDirectUploadFiles(files, userId, folderId);
-    return {
-        success: true,
-        uploadedCount: uploadedFiles.length,
-    };
+    else if (level === "WRITE") {
+        canWrite = true;
+    }
+    return { scope: result.scope, canWrite, viaGrant: result.viaGrant };
 }
-export async function deleteFolderRecord(userId, classId, folderId) {
-    const classData = await findClassWithTeacher(classId, userId);
-    if (!classData) {
-        throw new TRPCError({
-            code: "FORBIDDEN",
-            message: "Class not found or you are not a teacher",
-        });
+function scopesEqual(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    switch (a.kind) {
+        case "CLASS":
+            return a.classId === b.classId;
+        case "SCHOOL_STORAGE":
+            return a.schoolId === b.schoolId;
+        case "PERSONAL":
+            return a.userId === b.userId;
     }
-    const folder = await findFolderByIdWithCount(folderId);
-    if (!folder) {
-        throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Folder not found",
-        });
+}
+/** Browse a folder. Pass `folderId` to drill into a specific folder, or a `scope` to land on its root. */
+export async function browseFolder(userId, input) {
+    let scope;
+    let folderId;
+    let canWrite;
+    let viaGrant;
+    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;
     }
-    // Verify folder belongs to class (traverse to root)
-    let currentId = folderId;
-    let belongsToClass = false;
-    while (currentId) {
-        const current = await findFolderByIdForTraversal(currentId);
-        if (!current)
-            break;
-        if (current.classId === classId) {
-            belongsToClass = true;
-            break;
-        }
-        currentId = current.parentFolderId;
+    else {
+        scope = input.scope;
+        const access = await requireScopeAccess(userId, scope, "READ");
+        canWrite = access.canWrite;
+        viaGrant = false;
     }
-    if (!belongsToClass) {
-        throw new TRPCError({
-            code: "FORBIDDEN",
-            message: "Folder does not belong to this class",
-        });
+    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" });
     }
-    await deleteFolderById(folderId);
     return {
-        success: true,
-        deletedFiles: folder._count.files,
-        deletedFolders: folder._count.childFolders + 1,
+        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", name: "Shared with me" }
+            : null,
     };
 }
-export async function moveFolder(userId, folderId, targetParentFolderId, classId) {
-    const classData = await findClassWithTeacher(classId, userId);
-    if (!classData) {
-        throw new TRPCError({
-            code: "FORBIDDEN",
-            message: "You must be a teacher of this class to move folders",
-        });
+/**
+ * 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) {
+    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",
+            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: [],
+        },
+        breadcrumbs: [{ id: "shared-with-me", name: "Shared with me" }],
+        canWrite: false,
+        scope: { kind: "PERSONAL", userId },
+        /** Same `displayRoot` shape as `browseFolder` so the client union is uniform. */
+        displayRoot: {
+            kind: "SHARED_WITH_ME",
+            name: "Shared with me",
+        },
+    };
+}
+export async function getRootFolder(userId, scope) {
+    const result = await browseFolder(userId, { scope });
+    return result.folder;
+}
+export async function getFolder(userId, folderId) {
+    const result = await browseFolder(userId, { folderId });
+    return result.folder;
+}
+export async function getFolderBreadcrumbs(userId, folderId) {
+    await requireFolderAccess(userId, folderId, "READ");
+    return listFolderBreadcrumbs(folderId);
+}
+export async function getFolderParents(userId, folderId) {
+    // 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, input) {
+    let parentId;
+    if (input.parentFolderId) {
+        parentId = input.parentFolderId;
+        await requireFolderAccess(userId, parentId, "WRITE");
     }
-    const folder = await findFolderById(folderId);
+    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,
+    });
+}
+export async function updateFolderRecord(userId, input) {
+    const folder = await findFolderById(input.folderId);
     if (!folder) {
-        throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Folder not found",
-        });
+        throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
     }
     if (!folder.parentFolderId) {
         throw new TRPCError({
             code: "BAD_REQUEST",
-            message: "Cannot move the root folder",
+            message: "Cannot rename a root folder",
         });
     }
-    if (targetParentFolderId) {
-        const targetParent = await findFolderByIdForTraversal(targetParentFolderId);
-        if (!targetParent) {
-            throw new TRPCError({
-                code: "NOT_FOUND",
-                message: "Target parent folder not found",
-            });
-        }
-        if (targetParentFolderId === folderId) {
-            throw new TRPCError({
-                code: "BAD_REQUEST",
-                message: "Cannot move a folder into itself",
-            });
-        }
-        let currentParent = 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);
+    // 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);
 }
-export async function updateFolderRecord(folderId, name, color, classId) {
+export async function deleteFolder(userId, folderId) {
     const folder = await findFolderById(folderId);
     if (!folder) {
-        throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Folder not found",
-        });
+        throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
     }
-    if (!name.trim()) {
+    if (!folder.parentFolderId) {
         throw new TRPCError({
             code: "BAD_REQUEST",
-            message: "Folder name cannot be empty",
+            message: "Cannot delete a root folder",
         });
     }
-    return updateFolder(folderId, {
-        name: name.trim(),
-        ...(color && { color }),
-    });
+    // Delete targets the folder itself — same Drive-style guard as rename.
+    await requireFolderAccess(userId, folderId, "WRITE", { mutatesSelf: true });
+    await deleteFolderById(folderId);
+    return { success: true };
 }
-export async function getFolderParents(folderId) {
-    const parents = [];
-    let currentId = folderId;
-    while (currentId) {
-        const folder = await findFolderByIdForTraversal(currentId);
-        if (!folder)
-            break;
-        parents.push(folder);
-        currentId = folder.parentFolderId;
-    }
-    return parents;
-}
-export async function getFolderUploadUrls(userId, classId, folderId, files) {
-    const classData = await findClassWithTeacher(classId, userId);
-    if (!classData) {
+export async function moveFolder(userId, input) {
+    if (input.folderId === input.targetParentFolderId) {
         throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Class not found or you are not a teacher",
+            code: "BAD_REQUEST",
+            message: "Cannot move a folder into itself",
         });
     }
-    const folder = await findFolderById(folderId);
-    if (!folder) {
+    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 (!scopesEqual(sourceScope, targetScope)) {
         throw new TRPCError({
-            code: "NOT_FOUND",
-            message: "Folder not found",
+            code: "BAD_REQUEST",
+            message: "Cannot move folders between scopes",
         });
     }
-    let currentFolder = folder;
-    let belongsToClass = false;
-    while (currentFolder) {
-        if (currentFolder.classId === classId) {
-            belongsToClass = true;
-            break;
-        }
-        if (currentFolder.parentFolderId) {
-            currentFolder = await findFolderByIdForTraversal(currentFolder.parentFolderId);
-        }
-        else {
-            break;
+    // 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");
+    // Don't let a folder land under one of its own descendants.
+    let cursor = input.targetParentFolderId;
+    while (cursor) {
+        if (cursor === input.folderId) {
+            throw new TRPCError({
+                code: "BAD_REQUEST",
+                message: "Cannot move a folder into its own descendant",
+            });
         }
-    }
-    if (!belongsToClass) {
-        throw new TRPCError({
-            code: "FORBIDDEN",
-            message: "Folder does not belong to this class",
+        const node = await prisma.folder.findUnique({
+            where: { id: cursor },
+            select: { parentFolderId: true },
         });
+        cursor = node?.parentFolderId ?? null;
     }
-    return createDirectUploadFiles(files, userId, folderId);
+    await prisma.folder.update({
+        where: { id: input.folderId },
+        data: { parentFolderId: input.targetParentFolderId },
+    });
+    return { success: true };
+}
+export async function getFolderUploadUrls(userId, input) {
+    await requireFolderAccess(userId, input.folderId, "WRITE");
+    return createDirectUploadFiles(input.files, userId, input.folderId);
+}
+export async function confirmFolderUpload(_userId, input) {
+    // 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 };
+}
+/** What scopes can this user pick from in cloud-storage UIs? */
+export async function listUserScopes(userId) {
+    const memberships = await prisma.schoolMembership.findMany({
+        where: { userId, status: "ACTIVE" },
+        select: {
+            role: true,
+            school: {
+                select: { id: true, name: true, logoId: true },
+            },
+        },
+        orderBy: { createdAt: "asc" },
+    });
+    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 {
+        personal: { kind: "PERSONAL", 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",
+            folderCount: sharedWithMe.folders.length,
+            fileCount: sharedWithMe.files.length,
+        },
+    };
 }
 //# sourceMappingURL=folder.js.map
-//# debugId=4875a835-3cd4-5fcf-8e19-868d405dfe96
+//# debugId=338c145a-d8eb-5931-9a42-2a9c7c9acc94