@studious-lms/server 1.8.0 → 1.9.0

package/src/routers/permissions.ts

@@ -0,0 +1,71 @@
+/**
+ * Permissions router. Backs the "Share" dialog and the "Shared with me" view.
+ *
+ * Permission semantics live in `services/permissions.ts`; this router is just
+ * a thin Zod-validated tRPC surface over those helpers.
+ *
+ * v1 grants only on folders. Files inherit from their parent folder. Adding
+ * file-level grants later is a non-breaking, additive change.
+ */
+import { z } from "zod";
+import { createTRPCRouter, protectedProcedure } from "../trpc.js";
+import {
+  grantPermission,
+  listPermissions,
+  listSharedWithMe,
+  revokePermission,
+  type PermissionPrincipalInput,
+} from "../services/permissions.js";
+
+const principalSchema: z.ZodType<PermissionPrincipalInput> = z.discriminatedUnion(
+  "kind",
+  [
+    z.object({ kind: z.literal("USER"), userId: z.string() }),
+    z.object({ kind: z.literal("TAG"), tagId: z.string() }),
+    z.object({ kind: z.literal("CLASS"), classId: z.string() }),
+    z.object({ kind: z.literal("CLASS_TEACHERS"), classId: z.string() }),
+    z.object({ kind: z.literal("CLASS_STUDENTS"), classId: z.string() }),
+    z.object({ kind: z.literal("DEPARTMENT"), departmentId: z.string() }),
+    z.object({ kind: z.literal("SCHOOL"), schoolId: z.string() }),
+  ]
+);
+
+const levelSchema = z.enum(["READ", "WRITE"]);
+
+export const permissionsRouter = createTRPCRouter({
+  /** List all explicit grants on a folder. Caller must have WRITE. */
+  list: protectedProcedure
+    .input(z.object({ folderId: z.string() }))
+    .query(({ ctx, input }) =>
+      listPermissions(ctx.user!.id, input.folderId)
+    ),
+
+  /** Create a new explicit grant on a folder. */
+  grant: protectedProcedure
+    .input(
+      z.object({
+        folderId: z.string(),
+        principal: principalSchema,
+        level: levelSchema,
+      })
+    )
+    .mutation(({ ctx, input }) =>
+      grantPermission(ctx.user!.id, {
+        folderId: input.folderId,
+        principal: input.principal,
+        level: input.level,
+      })
+    ),
+
+  /** Remove an explicit grant. Allowed for the granter or anyone with WRITE on the folder. */
+  revoke: protectedProcedure
+    .input(z.object({ permissionId: z.string() }))
+    .mutation(({ ctx, input }) =>
+      revokePermission(ctx.user!.id, input.permissionId)
+    ),
+
+  /** Drive-style "Shared with me" — top-most folders explicitly granted to the caller. */
+  listSharedWithMe: protectedProcedure.query(({ ctx }) =>
+    listSharedWithMe(ctx.user!.id)
+  ),
+});

package/src/services/class.ts

@@ -74,7 +74,7 @@ export async function getAllClasses(userId: string) {
       schoolId: cls.schoolId ?? null,
       school: cls.school ?? null,
       department: cls.department ?? null,
-    })),
+    })).filter((cls) => cls.members.some((member) => member.id === userId)),
     studentInClass: studentClasses.map((cls) => ({
       id: cls.id,
       name: cls.name,

package/src/services/file.ts

@@ -1,11 +1,23 @@
 /**
- * File service – signed URLs, move, rename, delete. Handles permission checks
- * for assignment, submission, announcement, folder, and user-owned files.
+ * File service – signed URLs, move, rename, delete.
  *
- * The class files page calls the legacy class-scoped helpers; the unified
- * cloud-storage page calls the `*Scoped` / `*Generic` helpers below, which
- * derive permissions from the parent folder's CloudScope so the same endpoint
- * can serve class, school, and personal storage.
+ * Two access concepts coexist here, and they should not be conflated:
+ *
+ *   1. **Contextual access** — assignment, submission, announcement, and chat
+ *      attachments. A teacher viewing a student's submission has access by
+ *      virtue of teaching the class, not because anyone explicitly "shared"
+ *      the file with them. These checks live inline in `getFileSignedUrl`
+ *      below and predate the explicit-share system.
+ *
+ *   2. **Explicit-share access** — folder-scoped files in cloud storage.
+ *      Permission flows through the central resolver in `permissions.ts`,
+ *      which consults explicit `Permission` rows in addition to the
+ *      scope-derived defaults. The cloud-storage helpers (`*Scoped` /
+ *      `*Generic`) below all use this path.
+ *
+ * If you're tempted to refactor the contextual checks into the resolver,
+ * don't — they intentionally key off the file's domain context, not its
+ * filesystem location.
  */
 import { TRPCError } from "@trpc/server";
 import { getSignedUrl, deleteFile } from "../lib/googleCloudStorage.js";
@@ -23,17 +35,34 @@ import { findConversationMembership } from "../models/message.js";
 import { prisma } from "../lib/prisma.js";
 import { resolveFolderScope } from "../models/cloudStorage.js";
 import { requireFolderAccess } from "./folder.js";
+import { requireFileAccess } from "./permissions.js";
 
 function isSchoolAdminForClass(classData: any, userId: string) {
   return Boolean(
     classData?.school?.memberships?.some(
       (membership: { userId: string }) => membership.userId === userId
-    ) ||
-      classData?.school?.users?.some((admin: { id: string }) => admin.id === userId)
+    )
   );
 }
 
-/** Generate a signed URL for file download. Validates user has access. */
+/**
+ * Generate a signed URL for file download.
+ *
+ * Access resolution, in order — first match wins:
+ *   1. Owner of the file.
+ *   2. Member of the conversation the file is attached to (chat upload).
+ *   3. Contextual access via the file's class context: assignment / announcement
+ *      / submission / annotations attached to a class the user teaches, learns
+ *      in, or is a school admin for.
+ *   4. The central permissions resolver, which covers folder-scoped files —
+ *      explicit Permission grants (USER / TAG / CLASS / DEPARTMENT / SCHOOL
+ *      principals) plus scope defaults (school members read SCHOOL_STORAGE,
+ *      class members read class folders, owners read personal folders).
+ *
+ * The resolver is invoked unconditionally as the last step, so files shared
+ * via the new Permission system reach this code path even when they have no
+ * matching domain context.
+ */
 export async function getFileSignedUrl(userId: string, fileId: string) {
   const file = await findFileById(fileId);
   if (!file) {
@@ -45,58 +74,58 @@ export async function getFileSignedUrl(userId: string, fileId: string) {
 
   let hasAccess = false;
 
-  if (file.assignment?.class) {
-    const isTeacher = file.assignment.class.teachers.some(
-      (t) => t.id === userId
-    );
-    const isStudent = file.assignment.class.students.some(
-      (s) => s.id === userId
-    );
-    const isSchoolAdmin = isSchoolAdminForClass(file.assignment.class, userId);
-    logger.info(
-      `Assignment file access check - userId: ${userId}, isTeacher: ${isTeacher}, isStudent: ${isStudent}, isSchoolAdmin: ${isSchoolAdmin}`
-    );
-    hasAccess = isTeacher || isStudent || isSchoolAdmin;
+  if (file.userId === userId) {
+    hasAccess = true;
   }
 
-  if ((file as any).announcement?.class) {
-    const ann = (file as any).announcement;
-    const isTeacher = ann.class.teachers.some((t: any) => t.id === userId);
-    const isStudent = ann.class.students.some((s: any) => s.id === userId);
-    const isSchoolAdmin = isSchoolAdminForClass(ann.class, userId);
-    hasAccess = hasAccess || isTeacher || isStudent || isSchoolAdmin;
+  if (!hasAccess && file.conversationId) {
+    const membership = await findConversationMembership(file.conversationId, userId);
+    hasAccess = Boolean(membership);
   }
 
-  if (file.submission?.assignment?.classId) {
+  if (!hasAccess && file.assignment?.class) {
+    const cls = file.assignment.class;
     hasAccess =
-      hasAccess ||
-      file.submission.studentId === userId ||
-      file.submission.assignment.class.teachers.some((t) => t.id === userId) ||
-      isSchoolAdminForClass(file.submission.assignment.class, userId);
+      cls.teachers.some((t) => t.id === userId) ||
+      cls.students.some((s) => s.id === userId) ||
+      isSchoolAdminForClass(cls, userId);
   }
 
-  if (file.annotations?.assignment?.classId) {
+  if (!hasAccess && (file as any).announcement?.class) {
+    const cls = (file as any).announcement.class;
     hasAccess =
-      hasAccess ||
-      file.annotations.studentId === userId ||
-      file.annotations.assignment.class.teachers.some((t) => t.id === userId) ||
-      isSchoolAdminForClass(file.annotations.assignment.class, userId);
+      cls.teachers.some((t: { id: string }) => t.id === userId) ||
+      cls.students.some((s: { id: string }) => s.id === userId) ||
+      isSchoolAdminForClass(cls, userId);
   }
 
-  if (file.userId === userId) {
-    hasAccess = true;
+  if (!hasAccess && file.submission?.assignment?.classId) {
+    const cls = file.submission.assignment.class;
+    hasAccess =
+      file.submission.studentId === userId ||
+      cls.teachers.some((t) => t.id === userId) ||
+      isSchoolAdminForClass(cls, userId);
   }
 
-  if (file.conversationId) {
-    const membership = await findConversationMembership(file.conversationId, userId);
-    hasAccess = hasAccess || Boolean(membership);
+  if (!hasAccess && file.annotations?.assignment?.classId) {
+    const cls = file.annotations.assignment.class;
+    hasAccess =
+      file.annotations.studentId === userId ||
+      cls.teachers.some((t) => t.id === userId) ||
+      isSchoolAdminForClass(cls, userId);
   }
 
-  if (file.folder?.class) {
-    const isTeacher = file.folder.class.teachers.some((t) => t.id === userId);
-    const isStudent = file.folder.class.students.some((s) => s.id === userId);
-    const isSchoolAdmin = isSchoolAdminForClass(file.folder.class, userId);
-    hasAccess = hasAccess || isTeacher || isStudent || isSchoolAdmin;
+  // Final fallback: the explicit-share + scope-default resolver. Covers
+  // folder-scoped files shared via Permission grants (incl. SCHOOL/CLASS/TAG
+  // principals) and any institution member reading SCHOOL_STORAGE files.
+  // Safe to call for unfiled files — the resolver returns owner-only there.
+  if (!hasAccess) {
+    try {
+      await requireFileAccess(userId, fileId, "READ");
+      hasAccess = true;
+    } catch {
+      // resolver denied — fall through to FORBIDDEN below.
+    }
   }
 
   if (!hasAccess) {

package/src/services/folder.ts

@@ -28,106 +28,107 @@ import {
   type DirectFileData,
   confirmDirectUpload,
 } from "../lib/fileUpload.js";
-
-type AccessLevel = "READ" | "WRITE";
+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;
 }
 
+/**
+ * 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,
   scope: CloudScope,
   level: AccessLevel
 ): Promise<AccessResult> {
-  switch (scope.kind) {
-    case "CLASS": {
-      const classData = await prisma.class.findFirst({
-        where: { id: scope.classId },
-        select: {
-          id: true,
-          schoolId: true,
-          teachers: { where: { id: userId }, select: { id: true } },
-          students: { where: { id: userId }, select: { id: true } },
-        },
-      });
-      if (!classData) {
-        throw new TRPCError({ code: "NOT_FOUND", message: "Class not found" });
-      }
-      const isTeacher = classData.teachers.length > 0;
-      const isStudent = classData.students.length > 0;
-      const isSchoolAdmin = classData.schoolId
-        ? Boolean(
-            await prisma.schoolMembership.findFirst({
-              where: {
-                schoolId: classData.schoolId,
-                userId,
-                role: "ADMIN",
-                status: "ACTIVE",
-              },
-              select: { id: true },
-            })
-          )
-        : false;
-      if (!isTeacher && !isStudent && !isSchoolAdmin) {
-        throw new TRPCError({
-          code: "FORBIDDEN",
-          message: "You don't have access to this class",
-        });
-      }
-      const canWrite = isTeacher || isSchoolAdmin;
-      if (level === "WRITE" && !canWrite) {
-        throw new TRPCError({
-          code: "FORBIDDEN",
-          message: "Only class teachers can modify class files",
-        });
-      }
-      return { scope, canWrite };
-    }
-    case "SCHOOL_STORAGE": {
-      const membership = await prisma.schoolMembership.findFirst({
-        where: { schoolId: scope.schoolId, userId, status: "ACTIVE" },
-        select: { role: true },
-      });
-      if (!membership) {
-        throw new TRPCError({
-          code: "FORBIDDEN",
-          message: "You aren't a member of this institution",
-        });
-      }
-      const canWrite =
-        membership.role === "ADMIN" || membership.role === "TEACHER";
-      if (level === "WRITE" && !canWrite) {
-        throw new TRPCError({
-          code: "FORBIDDEN",
-          message: "Only teachers and admins can modify institution storage",
-        });
-      }
-      return { scope, canWrite };
-    }
-    case "PERSONAL": {
-      if (scope.userId !== userId) {
-        throw new TRPCError({
-          code: "FORBIDDEN",
-          message: "You can only access your own personal storage",
-        });
-      }
-      return { scope, canWrite: true };
+  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 granted = await getScopeDefault(userId, scope);
+  if (!granted) {
+    throw new TRPCError({
+      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",
+    });
+  }
+  if (level === "WRITE" && granted !== "WRITE") {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message:
+        scope.kind === "CLASS"
+          ? "Only class teachers can modify class files"
+          : "Only teachers and admins can modify institution storage",
+    });
+  }
+  // Scope-default-only path; access cannot be via a grant here.
+  return { scope, canWrite: granted === "WRITE", viaGrant: false };
 }
 
+/**
+ * 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
-) {
-  const scope = await resolveFolderScope(folderId);
-  if (!scope) {
+  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" });
   }
-  return requireScopeAccess(userId, scope, level);
+  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 };
 }
 
 function scopesEqual(a: CloudScope, b: CloudScope): boolean {
@@ -149,24 +150,30 @@ export async function browseFolder(
 ) {
   let scope: CloudScope;
   let folderId: string | undefined;
+  let canWrite: boolean;
+  let viaGrant: boolean;
 
   if ("folderId" in input) {
     folderId = input.folderId;
-    const resolved = await resolveFolderScope(input.folderId);
-    if (!resolved) {
-      throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
-    }
-    scope = resolved;
+    // `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 access = await requireScopeAccess(userId, scope, "READ");
   const targetId = folderId ?? (await findOrCreateScopeRoot(scope)).id;
 
   const [folder, breadcrumbs] = await Promise.all([
     findFolderWithContents(targetId),
-    listFolderBreadcrumbs(targetId),
+    listFolderBreadcrumbs(targetId, userId),
   ]);
 
   if (!folder) {
@@ -176,8 +183,70 @@ export async function browseFolder(
   return {
     folder,
     breadcrumbs,
-    canWrite: access.canWrite,
+    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",
+    },
   };
 }
 
@@ -250,7 +319,11 @@ export async function updateFolderRecord(
       message: "Cannot rename a root folder",
     });
   }
-  await requireFolderAccess(userId, input.folderId, "WRITE");
+  // 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,
@@ -269,7 +342,8 @@ export async function deleteFolder(userId: string, folderId: string) {
       message: "Cannot delete a root folder",
     });
   }
-  await requireFolderAccess(userId, folderId, "WRITE");
+  // Delete targets the folder itself — same Drive-style guard as rename.
+  await requireFolderAccess(userId, folderId, "WRITE", { mutatesSelf: true });
   await deleteFolderById(folderId);
   return { success: true };
 }
@@ -297,7 +371,12 @@ export async function moveFolder(
       message: "Cannot move folders between scopes",
     });
   }
-  await requireScopeAccess(userId, sourceScope, "WRITE");
+  // 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: string | null = input.targetParentFolderId;
@@ -376,6 +455,11 @@ export async function listUserScopes(userId: string) {
     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" as const, userId },
     schools: memberships.map((m) => ({
@@ -385,5 +469,10 @@ export async function listUserScopes(userId: string) {
       role: m.role,
     })),
     classes,
+    sharedWithMe: {
+      kind: "SHARED_WITH_ME" as const,
+      folderCount: sharedWithMe.folders.length,
+      fileCount: sharedWithMe.files.length,
+    },
   };
 }