@studious-lms/server 1.8.0 → 1.11.0

package/prisma/migrations/20260510170000_add_folder_permissions/migration.sql

@@ -0,0 +1,93 @@
+-- Add folder-level ACL permissions (v1: folder-only).
+--
+-- This migration introduces the Permission table and its supporting enums.
+-- It is *purely additive* — no existing column or row is modified, so it can
+-- be applied safely on a live database without backfill.
+--
+-- File-level grants are deliberately deferred. When/if added later, they can
+-- be a non-breaking additive migration (new columns + back-relation).
+
+-- CreateEnum
+CREATE TYPE "PermissionPrincipalType" AS ENUM (
+    'USER',
+    'TAG',
+    'CLASS',
+    'CLASS_TEACHERS',
+    'CLASS_STUDENTS',
+    'DEPARTMENT',
+    'SCHOOL'
+);
+
+-- CreateEnum
+CREATE TYPE "PermissionLevel" AS ENUM ('READ', 'WRITE');
+
+-- CreateTable
+CREATE TABLE "Permission" (
+    "id" TEXT NOT NULL DEFAULT gen_random_uuid()::text,
+    "folderId" TEXT NOT NULL,
+    "principalType" "PermissionPrincipalType" NOT NULL,
+    "userId" TEXT,
+    "tagId" TEXT,
+    "classId" TEXT,
+    "departmentId" TEXT,
+    "schoolId" TEXT,
+    "level" "PermissionLevel" NOT NULL,
+    "grantedById" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "Permission_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "Permission_folderId_idx" ON "Permission"("folderId");
+
+-- CreateIndex
+CREATE INDEX "Permission_userId_idx" ON "Permission"("userId");
+
+-- CreateIndex
+CREATE INDEX "Permission_tagId_idx" ON "Permission"("tagId");
+
+-- CreateIndex
+CREATE INDEX "Permission_classId_idx" ON "Permission"("classId");
+
+-- CreateIndex
+CREATE INDEX "Permission_departmentId_idx" ON "Permission"("departmentId");
+
+-- CreateIndex
+CREATE INDEX "Permission_schoolId_idx" ON "Permission"("schoolId");
+
+-- CreateIndex
+-- One grant per (folder, principal). Re-granting upserts the level.
+-- Postgres treats nulls as distinct in unique indexes, but the service layer
+-- guarantees exactly one principal id is non-null per row, so this still
+-- uniquely identifies the row.
+CREATE UNIQUE INDEX "Permission_folderId_principalType_userId_tagId_classId_depa_key"
+    ON "Permission"("folderId", "principalType", "userId", "tagId", "classId", "departmentId", "schoolId");
+
+-- AddForeignKey
+ALTER TABLE "Permission" ADD CONSTRAINT "Permission_folderId_fkey"
+    FOREIGN KEY ("folderId") REFERENCES "Folder"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Permission" ADD CONSTRAINT "Permission_userId_fkey"
+    FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Permission" ADD CONSTRAINT "Permission_tagId_fkey"
+    FOREIGN KEY ("tagId") REFERENCES "Tag"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Permission" ADD CONSTRAINT "Permission_classId_fkey"
+    FOREIGN KEY ("classId") REFERENCES "Class"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Permission" ADD CONSTRAINT "Permission_departmentId_fkey"
+    FOREIGN KEY ("departmentId") REFERENCES "Department"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Permission" ADD CONSTRAINT "Permission_schoolId_fkey"
+    FOREIGN KEY ("schoolId") REFERENCES "School"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Permission" ADD CONSTRAINT "Permission_grantedById_fkey"
+    FOREIGN KEY ("grantedById") REFERENCES "User"("id") ON DELETE RESTRICT ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -127,6 +127,7 @@ model School {
   departments   Department[]
   tags          Tag[]
   storageRoot   Folder?            @relation("SchoolStorageRoot")
+  permissions   Permission[]       @relation("SchoolPermissions")
 }
 
 model Department {
@@ -144,6 +145,7 @@ model Department {
   tags              Tag[]
   rubricTemplates   MarkScheme[]
   boundaryTemplates GradingBoundary[]
+  permissions       Permission[]      @relation("DepartmentPermissions")
 
   @@unique([schoolId, name])
   @@index([schoolId])
@@ -171,6 +173,7 @@ model Tag {
   classes    Class[]           @relation("ClassTags")
   rubrics    MarkScheme[]      @relation("MarkSchemeTags")
   boundaries GradingBoundary[] @relation("GradingBoundaryTags")
+  permissions Permission[]     @relation("TagPermissions")
 
   @@unique([schoolId, name])
   @@index([schoolId])
@@ -213,6 +216,10 @@ model User {
   tags            Tag[]        @relation("UserTags")
   personalStorage Folder?      @relation("UserStorageRoot")
 
+  // Permission grants where this user is the principal vs. the granter.
+  userPermissions    Permission[] @relation("UserPermissions")
+  grantedPermissions Permission[] @relation("GrantedPermissions")
+
   // Chat relations
   conversationMemberships ConversationMember[]
   sentMessages            Message[]            @relation("SentMessages")
@@ -303,6 +310,7 @@ model Class {
   department        Department?       @relation(fields: [departmentId], references: [id], onDelete: SetNull)
   departmentId      String?
   tags              Tag[]             @relation("ClassTags")
+  permissions       Permission[]      @relation("ClassPermissions")
 
   @@index([schoolId])
   @@index([departmentId])
@@ -361,6 +369,8 @@ model Folder {
   schoolStorageId String? @unique
   personalOwner   User?   @relation("UserStorageRoot", fields: [personalOwnerId], references: [id], onDelete: Cascade)
   personalOwnerId String? @unique
+
+  permissions Permission[] @relation("FolderPermissions")
 }
 
 model File {
@@ -898,3 +908,67 @@ model RunJob {
   @@index([classId, status])
   @@index([status, createdAt])
 }
+
+/// What kind of principal an explicit Permission row grants access to.
+/// CLASS = everyone in the class (teachers + students). CLASS_TEACHERS /
+/// CLASS_STUDENTS narrow that to one role. Stored alongside a single FK
+/// (`classId`, `userId`, etc.) — see service-layer invariants.
+enum PermissionPrincipalType {
+  USER
+  TAG
+  CLASS
+  CLASS_TEACHERS
+  CLASS_STUDENTS
+  DEPARTMENT
+  SCHOOL
+}
+
+enum PermissionLevel {
+  READ
+  WRITE
+}
+
+/// Explicit ACL grant on a folder. Sits on top of (and is purely additive
+/// to) the scope-derived defaults computed from FolderScope. Files inherit
+/// from their parent folder — file-level overrides are deliberately deferred
+/// to a future, additive migration that adds a `fileId` column + discriminator.
+///
+/// Schema invariant enforced in the service layer (Prisma can't express it):
+///   - Exactly one of `userId` / `tagId` / `classId` / `departmentId` /
+///     `schoolId` is set, matching `principalType`. CLASS, CLASS_TEACHERS,
+///     CLASS_STUDENTS all share `classId`.
+model Permission {
+  id       String  @id @default(uuid())
+  folderId String
+  folder   Folder  @relation("FolderPermissions", fields: [folderId], references: [id], onDelete: Cascade)
+
+  principalType PermissionPrincipalType
+  userId        String?
+  tagId         String?
+  classId       String?
+  departmentId  String?
+  schoolId      String?
+
+  user       User?       @relation("UserPermissions", fields: [userId], references: [id], onDelete: Cascade)
+  tag        Tag?        @relation("TagPermissions", fields: [tagId], references: [id], onDelete: Cascade)
+  class      Class?      @relation("ClassPermissions", fields: [classId], references: [id], onDelete: Cascade)
+  department Department? @relation("DepartmentPermissions", fields: [departmentId], references: [id], onDelete: Cascade)
+  school     School?     @relation("SchoolPermissions", fields: [schoolId], references: [id], onDelete: Cascade)
+
+  level       PermissionLevel
+  grantedById String
+  grantedBy   User            @relation("GrantedPermissions", fields: [grantedById], references: [id])
+  createdAt   DateTime        @default(now())
+
+  /// One grant per (folder, principal). Re-granting upserts the level.
+  /// Postgres treats nulls as distinct in unique indexes, but the service layer
+  /// guarantees exactly one principal id is non-null, so this still uniquely
+  /// identifies the row.
+  @@unique([folderId, principalType, userId, tagId, classId, departmentId, schoolId])
+  @@index([folderId])
+  @@index([userId])
+  @@index([tagId])
+  @@index([classId])
+  @@index([departmentId])
+  @@index([schoolId])
+}

package/src/middleware/security.ts

@@ -20,7 +20,7 @@ const rateLimitHandler = (req: Request, res: Response) => {
 // General API rate limiter - applies to all routes
 export const generalLimiter = rateLimit({
   windowMs: 10 * 60 * 1000, // 10 minutes
-  max: 100, // Limit each IP to 100 requests per windowMs
+  max: 1000, // Limit each IP to 100 requests per windowMs
   message: 'Too many requests from this IP, please try again later.',
   standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
   legacyHeaders: false, // Disable the `X-RateLimit-*` headers

package/src/models/cloudStorage.ts

@@ -176,10 +176,130 @@ export function renameFolder(folderId: string, name: string, color?: string) {
   });
 }
 
-export async function listFolderBreadcrumbs(folderId: string) {
+/**
+ * Build the breadcrumb chain for a folder.
+ *
+ * Without `viewerId`: walks all the way up to the scope root (owner-style
+ * view).
+ *
+ * With `viewerId`: walks up but stops at the highest folder the viewer is
+ * actually granted on, OR at the scope root if the viewer is a scope member.
+ * This is the Drive-style "Shared with me" behavior — a grantee never sees
+ * ancestor folders they weren't shared on. The result for a grantee browsing
+ * `Owner/PrivateA/SharedB/C` (granted on B) reads `SharedB / C` — the ancestor
+ * `PrivateA` is correctly hidden.
+ */
+export async function listFolderBreadcrumbs(
+  folderId: string,
+  viewerId?: string
+) {
   const breadcrumbs: { id: string; name: string }[] = [];
   let currentId: string | null = folderId;
   let visits = 0;
+
+  let viewerGrantedFolderIds: Set<string> | null = null;
+  let viewerScopeMember = false;
+
+  if (viewerId) {
+    const grants = await prisma.permission.findMany({
+      where: {
+        OR: [
+          { principalType: "USER", userId: viewerId },
+          {
+            principalType: "TAG",
+            tag: { users: { some: { id: viewerId } } },
+          },
+          {
+            principalType: "CLASS",
+            class: {
+              OR: [
+                { teachers: { some: { id: viewerId } } },
+                { students: { some: { id: viewerId } } },
+              ],
+            },
+          },
+          {
+            principalType: "CLASS_TEACHERS",
+            class: { teachers: { some: { id: viewerId } } },
+          },
+          {
+            principalType: "CLASS_STUDENTS",
+            class: { students: { some: { id: viewerId } } },
+          },
+          {
+            principalType: "DEPARTMENT",
+            department: { members: { some: { id: viewerId } } },
+          },
+          {
+            principalType: "SCHOOL",
+            school: {
+              memberships: { some: { userId: viewerId, status: "ACTIVE" } },
+            },
+          },
+        ],
+      },
+      select: { folderId: true },
+    });
+    viewerGrantedFolderIds = new Set(
+      grants.map((g) => g.folderId).filter((x): x is string => Boolean(x))
+    );
+
+    // Determine if the viewer is a member of the *target* folder's scope —
+    // if so, breadcrumbs go all the way to the scope root as normal.
+    const scope = await resolveFolderScope(folderId);
+    if (scope) {
+      switch (scope.kind) {
+        case "CLASS": {
+          const c = await prisma.class.findFirst({
+            where: {
+              id: scope.classId,
+              OR: [
+                { teachers: { some: { id: viewerId } } },
+                { students: { some: { id: viewerId } } },
+              ],
+            },
+            select: { id: true },
+          });
+          viewerScopeMember = Boolean(c);
+          if (!viewerScopeMember && scope.classId) {
+            const klass = await prisma.class.findUnique({
+              where: { id: scope.classId },
+              select: { schoolId: true },
+            });
+            if (klass?.schoolId) {
+              const m = await prisma.schoolMembership.findFirst({
+                where: {
+                  schoolId: klass.schoolId,
+                  userId: viewerId,
+                  role: "ADMIN",
+                  status: "ACTIVE",
+                },
+                select: { id: true },
+              });
+              viewerScopeMember = Boolean(m);
+            }
+          }
+          break;
+        }
+        case "SCHOOL_STORAGE": {
+          const m = await prisma.schoolMembership.findFirst({
+            where: {
+              schoolId: scope.schoolId,
+              userId: viewerId,
+              status: "ACTIVE",
+            },
+            select: { id: true },
+          });
+          viewerScopeMember = Boolean(m);
+          break;
+        }
+        case "PERSONAL":
+          viewerScopeMember = scope.userId === viewerId;
+          break;
+      }
+    }
+  }
+
   while (currentId && visits < 64) {
     const folder = await prisma.folder.findUnique({
       where: { id: currentId },
@@ -187,6 +307,19 @@ export async function listFolderBreadcrumbs(folderId: string) {
     });
     if (!folder) break;
     breadcrumbs.unshift({ id: folder.id, name: folder.name });
+
+    // Viewer-aware truncation: when the viewer is *not* a scope member but
+    // is a grantee, stop at the highest granted ancestor (we walk up one
+    // more step into the granted folder, then stop there).
+    if (
+      viewerId &&
+      !viewerScopeMember &&
+      viewerGrantedFolderIds &&
+      viewerGrantedFolderIds.has(folder.id)
+    ) {
+      break;
+    }
+
     currentId = folder.parentFolderId;
     visits += 1;
   }

package/src/models/file.ts

@@ -8,9 +8,6 @@ const classFileAccessInclude = {
   teachers: true,
   school: {
     include: {
-      users: {
-        select: { id: true },
-      },
       memberships: {
         where: {
           role: "ADMIN" as const,
@@ -40,23 +37,7 @@ export function findFileById(fileId: string) {
           assignment: {
             include: {
               class: {
-                include: {
-                  teachers: true,
-                  school: {
-                    include: {
-                      users: {
-                        select: { id: true },
-                      },
-                      memberships: {
-                        where: {
-                          role: "ADMIN" as const,
-                          status: "ACTIVE" as const,
-                        },
-                        select: { userId: true },
-                      },
-                    },
-                  },
-                },
+                include: classFileAccessInclude,
               },
             },
           },
@@ -68,23 +49,7 @@ export function findFileById(fileId: string) {
           assignment: {
             include: {
               class: {
-                include: {
-                  teachers: true,
-                  school: {
-                    include: {
-                      users: {
-                        select: { id: true },
-                      },
-                      memberships: {
-                        where: {
-                          role: "ADMIN" as const,
-                          status: "ACTIVE" as const,
-                        },
-                        select: { userId: true },
-                      },
-                    },
-                  },
-                },
+                include: classFileAccessInclude,
               },
             },
           },

package/src/routers/_app.ts

@@ -25,6 +25,7 @@ import { searchRouter } from "./search.js";
 import { schoolRouter } from "./school.js";
 import { departmentRouter } from "./department.js";
 import { tagRouter } from "./tag.js";
+import { permissionsRouter } from "./permissions.js";
 
 export const appRouter = createTRPCRouter({
   class: classRouter,
@@ -51,6 +52,7 @@ export const appRouter = createTRPCRouter({
   school: schoolRouter,
   department: departmentRouter,
   tag: tagRouter,
+  permissions: permissionsRouter,
 });
 
 // Export type router type definition

package/src/routers/folder.ts

@@ -5,6 +5,7 @@ import {
 } from "../trpc.js";
 import {
   browseFolder,
+  browseSharedWithMe,
   confirmFolderUpload,
   createFolderRecord,
   deleteFolder,
@@ -16,6 +17,7 @@ import {
   moveFolder,
   updateFolderRecord,
 } from "../services/folder.js";
+import { listSharedWithMe } from "../services/permissions.js";
 
 const directFileSchema = z.object({
   name: z.string(),
@@ -40,16 +42,44 @@ const cloudScopeSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("PERSONAL"), userId: z.string() }),
 ]);
 
+/**
+ * Extended scope schema for `browse` only. SHARED_WITH_ME is a *virtual*
+ * scope — it has no root row in the `Folder` table and you can't create
+ * folders inside it directly. It just collects every top-most explicit grant
+ * the user holds for "Shared with me"-style display.
+ */
+const browseScopeSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("CLASS"), classId: z.string() }),
+  z.object({ kind: z.literal("SCHOOL_STORAGE"), schoolId: z.string() }),
+  z.object({ kind: z.literal("PERSONAL"), userId: z.string() }),
+  z.object({ kind: z.literal("SHARED_WITH_ME") }),
+]);
+
 export const folderRouter = createTRPCRouter({
   /** Browse a folder (or scope root) with breadcrumbs and access flag. */
   browse: protectedProcedure
     .input(
       z.union([
         z.object({ folderId: z.string() }),
-        z.object({ scope: cloudScopeSchema }),
+        z.object({ scope: browseScopeSchema }),
       ])
     )
-    .query(({ ctx, input }) => browseFolder(ctx.user!.id, input)),
+    .query(({ ctx, input }) => {
+      if ("scope" in input && input.scope.kind === "SHARED_WITH_ME") {
+        return browseSharedWithMe(ctx.user!.id);
+      }
+      return browseFolder(
+        ctx.user!.id,
+        "scope" in input
+          ? { scope: input.scope as Exclude<typeof input.scope, { kind: "SHARED_WITH_ME" }> }
+          : input
+      );
+    }),
+
+  /** Top-most folders/files explicitly shared with the caller (Drive-style). */
+  listSharedWithMe: protectedProcedure.query(({ ctx }) =>
+    listSharedWithMe(ctx.user!.id)
+  ),
 
   /** What scopes can this user pick from in the cloud-storage UI? */
   listScopes: protectedProcedure.query(({ ctx }) =>

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/routers/studentProgress.ts

@@ -8,6 +8,9 @@ import {
   chatAboutStudentProgress,
   dismissStudentRecommendation,
   getClassProgressRecommendations,
+  getStudentProgressFocus,
+  getStudentProgressForecast,
+  getStudentProgressInsights,
   getStudentProgressRecommendations,
 } from "../services/studentProgress.js";
 
@@ -27,6 +30,24 @@ export const studentProgressRouter = createTRPCRouter({
       ),
     ),
 
+  getInsights: protectedClassMemberProcedure
+    .input(progressInputSchema)
+    .query(({ ctx, input }) =>
+      getStudentProgressInsights(ctx.user!.id, input.classId, input.studentId),
+    ),
+
+  getForecast: protectedClassMemberProcedure
+    .input(progressInputSchema)
+    .query(({ ctx, input }) =>
+      getStudentProgressForecast(ctx.user!.id, input.classId, input.studentId),
+    ),
+
+  getStudentFocus: protectedClassMemberProcedure
+    .input(progressInputSchema)
+    .query(({ ctx, input }) =>
+      getStudentProgressFocus(ctx.user!.id, input.classId, input.studentId),
+    ),
+
   getClassRecommendations: protectedTeacherProcedure
     .input(z.object({ classId: z.string() }))
     .query(({ ctx, input }) =>

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,