@studious-lms/server 1.8.0 → 1.9.0

package/dist/services/permissions.js

@@ -0,0 +1,661 @@
+/**
+ * Permissions resolver — single source of truth for "can user U do X to target T?"
+ *
+ * Sits on top of the existing scope-derived defaults (class members, school
+ * members, personal owner) computed in `getScopeDefault`. Explicit `Permission`
+ * rows are *additive* — they only ever grant more access, never less. There is
+ * no concept of a "deny" rule by design; revocation = delete the row.
+ *
+ * Resolution order for `requireFolderAccess(user, folder, level)`:
+ *   1. Scope default (class member / school member / personal owner)
+ *   2. Direct grant on the folder, OR inherited grant on any ancestor
+ *      (walk up to scope root)
+ *   First match wins; otherwise FORBIDDEN.
+ *
+ * `requireFileAccess` resolves the file's parent folder and delegates. Files
+ * inherit from their folder in v1; per-file grants are deliberately deferred
+ * (forward-compatible additive migration when needed).
+ */
+
+!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]="2ac7304e-3502-58ed-af8e-db3b64af3009")}catch(e){}}();
+import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
+import { resolveFolderScope, } from "../models/cloudStorage.js";
+/**
+ * Build the audience set for a user. Cheap (5 queries, all id-only) but worth
+ * caching per request — most permission checks in a single tRPC call hit this.
+ */
+export async function expandUserPrincipals(userId) {
+    const [user, asTeacher, asStudent, departments, schoolMemberships] = await Promise.all([
+        prisma.user.findUnique({
+            where: { id: userId },
+            select: { tags: { select: { id: true } } },
+        }),
+        prisma.class.findMany({
+            where: { teachers: { some: { id: userId } } },
+            select: { id: true },
+        }),
+        prisma.class.findMany({
+            where: { students: { some: { id: userId } } },
+            select: { id: true },
+        }),
+        prisma.department.findMany({
+            where: { members: { some: { id: userId } } },
+            select: { id: true },
+        }),
+        prisma.schoolMembership.findMany({
+            where: { userId, status: "ACTIVE" },
+            select: { schoolId: true },
+        }),
+    ]);
+    const classTeacherIds = asTeacher.map((c) => c.id);
+    const classStudentIds = asStudent.map((c) => c.id);
+    return {
+        userId,
+        tagIds: user?.tags.map((t) => t.id) ?? [],
+        classTeacherIds,
+        classStudentIds,
+        classIds: Array.from(new Set([...classTeacherIds, ...classStudentIds])),
+        departmentIds: departments.map((d) => d.id),
+        schoolIds: schoolMemberships.map((m) => m.schoolId),
+    };
+}
+/**
+ * The principal-side `where` clause that matches any explicit grant whose
+ * principal applies to this user. CLASS / CLASS_TEACHERS / CLASS_STUDENTS all
+ * use `classId` but with different `principalType` values, so we have to fan
+ * those out into three OR branches.
+ */
+function principalsWhere(principals) {
+    const ors = [
+        { principalType: "USER", userId: principals.userId },
+    ];
+    if (principals.tagIds.length) {
+        ors.push({ principalType: "TAG", tagId: { in: principals.tagIds } });
+    }
+    if (principals.classIds.length) {
+        ors.push({
+            principalType: "CLASS",
+            classId: { in: principals.classIds },
+        });
+    }
+    if (principals.classTeacherIds.length) {
+        ors.push({
+            principalType: "CLASS_TEACHERS",
+            classId: { in: principals.classTeacherIds },
+        });
+    }
+    if (principals.classStudentIds.length) {
+        ors.push({
+            principalType: "CLASS_STUDENTS",
+            classId: { in: principals.classStudentIds },
+        });
+    }
+    if (principals.departmentIds.length) {
+        ors.push({
+            principalType: "DEPARTMENT",
+            departmentId: { in: principals.departmentIds },
+        });
+    }
+    if (principals.schoolIds.length) {
+        ors.push({
+            principalType: "SCHOOL",
+            schoolId: { in: principals.schoolIds },
+        });
+    }
+    return { OR: ors };
+}
+function levelSatisfies(granted, required) {
+    if (required === "READ")
+        return granted === "READ" || granted === "WRITE";
+    return granted === "WRITE";
+}
+/** Walk up to the scope root, collecting folder ids visited along the way (inclusive). */
+async function findAncestorIds(folderId) {
+    const ids = [];
+    let cursor = folderId;
+    let visits = 0;
+    while (cursor && visits < 64) {
+        ids.push(cursor);
+        const node = await prisma.folder.findUnique({
+            where: { id: cursor },
+            select: { parentFolderId: true },
+        });
+        if (!node)
+            break;
+        cursor = node.parentFolderId;
+        visits += 1;
+    }
+    return ids;
+}
+export { findAncestorIds };
+/**
+ * Compute the scope default for a user — i.e. the access level the existing
+ * scope-derived rules grant, *before* any explicit ACL is consulted.
+ *
+ * Mirrors the logic that used to live in `requireScopeAccess` in folder.ts.
+ * Returns "WRITE" / "READ" / null.
+ */
+export async function getScopeDefault(userId, scope) {
+    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)
+                return null;
+            if (classData.teachers.length > 0)
+                return "WRITE";
+            const isSchoolAdmin = classData.schoolId
+                ? Boolean(await prisma.schoolMembership.findFirst({
+                    where: {
+                        schoolId: classData.schoolId,
+                        userId,
+                        role: "ADMIN",
+                        status: "ACTIVE",
+                    },
+                    select: { id: true },
+                }))
+                : false;
+            if (isSchoolAdmin)
+                return "WRITE";
+            if (classData.students.length > 0)
+                return "READ";
+            return null;
+        }
+        case "SCHOOL_STORAGE": {
+            const membership = await prisma.schoolMembership.findFirst({
+                where: { schoolId: scope.schoolId, userId, status: "ACTIVE" },
+                select: { role: true },
+            });
+            if (!membership)
+                return null;
+            if (membership.role === "ADMIN" || membership.role === "TEACHER")
+                return "WRITE";
+            return "READ";
+        }
+        case "PERSONAL": {
+            return scope.userId === userId ? "WRITE" : null;
+        }
+    }
+}
+/**
+ * Does any of the given folder ids carry a grant matching this user at >=
+ * `level`? Returns the matching folder id (highest-priority for caller use)
+ * or null.
+ */
+async function findGrantOnFolders(folderIds, principals, level) {
+    if (!folderIds.length)
+        return null;
+    const grant = await prisma.permission.findFirst({
+        where: {
+            folderId: { in: folderIds },
+            ...principalsWhere(principals),
+            ...(level === "WRITE" ? { level: "WRITE" } : {}),
+        },
+        select: { folderId: true },
+    });
+    return grant?.folderId ?? null;
+}
+/**
+ * Permission gate for folder-scoped operations. Throws TRPCError on denial,
+ * returns the scope (and which path granted access) on success.
+ *
+ * `opts.mutatesSelf` (Drive-style guard): when true, the action targets the
+ * folder *itself* — rename, delete, move-this-folder. Explicit grants do NOT
+ * authorize these; only scope-default WRITE does. This means a teacher sharing
+ * "Math Resources" with the parents tag can let parents read/edit children of
+ * the folder, but parents cannot rename or delete the share root. Mutations
+ * targeting *children* of the folder (uploads, sub-folders, child renames)
+ * pass `mutatesSelf: false` and flow through the normal grant + ancestor +
+ * scope-default path.
+ */
+export async function requireFolderAccess(userId, folderId, level, opts = {}) {
+    const scope = await resolveFolderScope(folderId);
+    if (!scope) {
+        throw new TRPCError({ code: "NOT_FOUND", message: "Folder not found" });
+    }
+    const scopeDefault = await getScopeDefault(userId, scope);
+    if (scopeDefault && levelSatisfies(scopeDefault, level)) {
+        return { scope, scopeDefault, viaGrant: false };
+    }
+    // Mutations of the share root itself are reserved for scope-default WRITE.
+    // Explicit grants don't authorize delete/rename/move-self even at WRITE
+    // level. We've already failed the scope-default branch above, so deny.
+    if (opts.mutatesSelf && level === "WRITE") {
+        throw new TRPCError({
+            code: "FORBIDDEN",
+            message: "Only the folder's owner can rename, move, or delete it. " +
+                "You can edit its contents.",
+        });
+    }
+    const principals = await expandUserPrincipals(userId);
+    const ancestors = await findAncestorIds(folderId);
+    const grantFolderId = await findGrantOnFolders(ancestors, principals, level);
+    if (grantFolderId) {
+        return { scope, scopeDefault, viaGrant: true };
+    }
+    throw new TRPCError({
+        code: "FORBIDDEN",
+        message: level === "WRITE"
+            ? "You don't have write access here"
+            : "You don't have access to this folder",
+    });
+}
+/**
+ * Per-class role check used by file-context handlers (assignment, submission,
+ * annotation, announcement, class-draft attachments). Single query.
+ */
+async function userClassRole(userId, classId) {
+    const cls = await prisma.class.findFirst({
+        where: { id: classId },
+        select: {
+            schoolId: true,
+            teachers: { where: { id: userId }, select: { id: true } },
+            students: { where: { id: userId }, select: { id: true } },
+        },
+    });
+    if (!cls)
+        return null;
+    if (cls.teachers.length)
+        return "TEACHER";
+    if (cls.schoolId) {
+        const admin = await prisma.schoolMembership.findFirst({
+            where: {
+                schoolId: cls.schoolId,
+                userId,
+                role: "ADMIN",
+                status: "ACTIVE",
+            },
+            select: { id: true },
+        });
+        if (admin)
+            return "ADMIN";
+    }
+    if (cls.students.length)
+        return "STUDENT";
+    return null;
+}
+const fileGrant = (level) => ({
+    scope: null,
+    scopeDefault: level,
+    viaGrant: false,
+});
+/**
+ * Permission gate for file-scoped operations. Dispatches on whichever context
+ * relation the file carries, so every kind of file (cloud-storage, chat
+ * attachment, assignment / submission / annotation / announcement / class-draft
+ * attachment, school logo) gets authorized through one entry point.
+ *
+ * Resolution order — first match wins:
+ *   1. **Owner** — `file.userId === user`. Always WRITE.
+ *   2. **Folder-bound** — delegate to `requireFolderAccess` (handles scope
+ *      defaults + explicit grants + ancestor inheritance).
+ *   3. **Conversation/message attachment** — any conversation member READs;
+ *      only the sender (= owner, handled in step 1) WRITEs.
+ *   4. **Assignment attachment** — class teacher/admin RW, class student R.
+ *   5. **Submission file** — submission's student RW (until grading workflow
+ *      locks it down), class teacher/admin R.
+ *   6. **Annotation file** — class teacher/admin RW, submission's student R.
+ *   7. **Announcement attachment** — class teacher/admin RW, class student R.
+ *   8. **Class-draft attachment** — class teacher/admin RW (drafts have no
+ *      students yet in practice).
+ *   9. **School logo** — any active school member R, school admin W.
+ *  10. **Otherwise** (incl. SDP supporting docs) — owner-only fallback already
+ *      covered by step 1; deny.
+ */
+export async function requireFileAccess(userId, fileId, level) {
+    const file = await prisma.file.findUnique({
+        where: { id: fileId },
+        select: {
+            id: true,
+            userId: true,
+            folderId: true,
+            conversationId: true,
+            assignmentId: true,
+            classDraftId: true,
+            announcementId: true,
+            schoolDevelopementProgramId: true,
+            assignment: { select: { classId: true } },
+            submission: {
+                select: { studentId: true, assignment: { select: { classId: true } } },
+            },
+            annotations: {
+                select: { studentId: true, assignment: { select: { classId: true } } },
+            },
+            announcement: { select: { classId: true } },
+            schools: { select: { id: true } },
+        },
+    });
+    if (!file) {
+        throw new TRPCError({ code: "NOT_FOUND", message: "File not found" });
+    }
+    if (file.userId === userId) {
+        return { scope: null, scopeDefault: "WRITE", viaGrant: false };
+    }
+    if (file.folderId) {
+        return requireFolderAccess(userId, file.folderId, level);
+    }
+    if (file.conversationId) {
+        const member = await prisma.conversationMember.findFirst({
+            where: { conversationId: file.conversationId, userId },
+            select: { id: true },
+        });
+        if (member) {
+            // Non-owners can only read; only the sender (owner, already handled
+            // above) can mutate the attachment record.
+            if (level === "READ")
+                return fileGrant("READ");
+        }
+    }
+    if (file.assignment?.classId) {
+        const role = await userClassRole(userId, file.assignment.classId);
+        if (role === "TEACHER" || role === "ADMIN")
+            return fileGrant("WRITE");
+        if (role === "STUDENT" && level === "READ")
+            return fileGrant("READ");
+    }
+    if (file.submission?.assignment?.classId) {
+        if (file.submission.studentId === userId)
+            return fileGrant("WRITE");
+        const role = await userClassRole(userId, file.submission.assignment.classId);
+        if ((role === "TEACHER" || role === "ADMIN") && level === "READ") {
+            return fileGrant("READ");
+        }
+    }
+    if (file.annotations?.assignment?.classId) {
+        const role = await userClassRole(userId, file.annotations.assignment.classId);
+        if (role === "TEACHER" || role === "ADMIN")
+            return fileGrant("WRITE");
+        if (file.annotations.studentId === userId && level === "READ") {
+            return fileGrant("READ");
+        }
+    }
+    if (file.announcement?.classId) {
+        const role = await userClassRole(userId, file.announcement.classId);
+        if (role === "TEACHER" || role === "ADMIN")
+            return fileGrant("WRITE");
+        if (role === "STUDENT" && level === "READ")
+            return fileGrant("READ");
+    }
+    if (file.classDraftId) {
+        const role = await userClassRole(userId, file.classDraftId);
+        if (role === "TEACHER" || role === "ADMIN")
+            return fileGrant("WRITE");
+    }
+    if (file.schools.length) {
+        // Files referenced as `School.logo` — readable by any active member of
+        // any school using this file, writable only by an admin of one of them.
+        const schoolIds = file.schools.map((s) => s.id);
+        if (level === "WRITE") {
+            const adminMembership = await prisma.schoolMembership.findFirst({
+                where: {
+                    schoolId: { in: schoolIds },
+                    userId,
+                    role: "ADMIN",
+                    status: "ACTIVE",
+                },
+                select: { id: true },
+            });
+            if (adminMembership)
+                return fileGrant("WRITE");
+        }
+        else {
+            const membership = await prisma.schoolMembership.findFirst({
+                where: {
+                    schoolId: { in: schoolIds },
+                    userId,
+                    status: "ACTIVE",
+                },
+                select: { id: true },
+            });
+            if (membership)
+                return fileGrant("READ");
+        }
+    }
+    throw new TRPCError({
+        code: "FORBIDDEN",
+        message: level === "WRITE"
+            ? "You don't have write access to this file"
+            : "You don't have access to this file",
+    });
+}
+/**
+ * Top-most-grant computation: surface every folder the user has an explicit
+ * grant on whose nearest permissioned ancestor the user does *not* also hold a
+ * grant on, AND whose scope default does not already grant access. That second
+ * filter avoids "Shared with me" duplicating things you already see in your
+ * normal class/school/personal scopes.
+ *
+ * Files are not surfaced here — file-level grants are deferred to a future
+ * feature; in v1 files inherit from their folder.
+ */
+export async function listSharedWithMe(userId) {
+    const principals = await expandUserPrincipals(userId);
+    const grants = await prisma.permission.findMany({
+        where: principalsWhere(principals),
+        select: { id: true, folderId: true },
+    });
+    const grantedFolderIds = new Set(grants.map((g) => g.folderId).filter((x) => Boolean(x)));
+    const topFolders = [];
+    for (const folderId of grantedFolderIds) {
+        const ancestors = await findAncestorIds(folderId);
+        // Skip self; we want to know if any *strict* ancestor is also granted.
+        const strictAncestors = ancestors.slice(1);
+        const coveredByAncestor = strictAncestors.some((id) => grantedFolderIds.has(id));
+        if (coveredByAncestor)
+            continue;
+        const scope = await resolveFolderScope(folderId);
+        if (scope) {
+            const scopeDefault = await getScopeDefault(userId, scope);
+            if (scopeDefault)
+                continue;
+        }
+        const folder = await prisma.folder.findUnique({
+            where: { id: folderId },
+            select: { id: true, name: true, color: true },
+        });
+        if (folder)
+            topFolders.push(folder);
+    }
+    return { folders: topFolders, files: [] };
+}
+/** Resolve which school an explicit grant target belongs to (for cross-school checks). */
+async function resolveTargetSchoolId(folderId) {
+    const scope = await resolveFolderScope(folderId);
+    return scopeSchoolId(scope);
+}
+async function scopeSchoolId(scope) {
+    if (!scope)
+        return null;
+    switch (scope.kind) {
+        case "CLASS": {
+            const c = await prisma.class.findUnique({
+                where: { id: scope.classId },
+                select: { schoolId: true },
+            });
+            return c?.schoolId ?? null;
+        }
+        case "SCHOOL_STORAGE":
+            return scope.schoolId;
+        case "PERSONAL":
+            return null;
+    }
+}
+/** The school a principal lives in (for cross-school leak prevention). */
+async function principalSchoolId(principal) {
+    switch (principal.kind) {
+        case "USER": {
+            const u = await prisma.user.findUnique({
+                where: { id: principal.userId },
+                select: { schoolId: true },
+            });
+            return u?.schoolId ?? null;
+        }
+        case "TAG": {
+            const t = await prisma.tag.findUnique({
+                where: { id: principal.tagId },
+                select: { schoolId: true },
+            });
+            return t?.schoolId ?? null;
+        }
+        case "CLASS":
+        case "CLASS_TEACHERS":
+        case "CLASS_STUDENTS": {
+            const c = await prisma.class.findUnique({
+                where: { id: principal.classId },
+                select: { schoolId: true },
+            });
+            return c?.schoolId ?? null;
+        }
+        case "DEPARTMENT": {
+            const d = await prisma.department.findUnique({
+                where: { id: principal.departmentId },
+                select: { schoolId: true },
+            });
+            return d?.schoolId ?? null;
+        }
+        case "SCHOOL":
+            return principal.schoolId;
+    }
+}
+function principalToColumns(principal) {
+    const base = {
+        userId: null,
+        tagId: null,
+        classId: null,
+        departmentId: null,
+        schoolId: null,
+    };
+    switch (principal.kind) {
+        case "USER":
+            return { ...base, principalType: "USER", userId: principal.userId };
+        case "TAG":
+            return { ...base, principalType: "TAG", tagId: principal.tagId };
+        case "CLASS":
+            return { ...base, principalType: "CLASS", classId: principal.classId };
+        case "CLASS_TEACHERS":
+            return {
+                ...base,
+                principalType: "CLASS_TEACHERS",
+                classId: principal.classId,
+            };
+        case "CLASS_STUDENTS":
+            return {
+                ...base,
+                principalType: "CLASS_STUDENTS",
+                classId: principal.classId,
+            };
+        case "DEPARTMENT":
+            return {
+                ...base,
+                principalType: "DEPARTMENT",
+                departmentId: principal.departmentId,
+            };
+        case "SCHOOL":
+            return { ...base, principalType: "SCHOOL", schoolId: principal.schoolId };
+    }
+}
+/**
+ * Create a new explicit grant on a folder. Validates:
+ *   - Granter has WRITE on the folder.
+ *   - The principal is in the same school as the folder's scope (no
+ *     cross-school leaks). Personal-scope folders cannot be granted to
+ *     non-USER principals — there's no "school" to check membership against.
+ */
+export async function grantPermission(grantedById, input) {
+    await requireFolderAccess(grantedById, input.folderId, "WRITE");
+    const [targetSchoolId, principalSchool] = await Promise.all([
+        resolveTargetSchoolId(input.folderId),
+        principalSchoolId(input.principal),
+    ]);
+    if (input.principal.kind !== "USER") {
+        if (!targetSchoolId) {
+            throw new TRPCError({
+                code: "BAD_REQUEST",
+                message: "Personal-scope items can only be shared with specific users, not groups",
+            });
+        }
+        if (principalSchool !== targetSchoolId) {
+            throw new TRPCError({
+                code: "BAD_REQUEST",
+                message: "Cannot share with a principal from a different school",
+            });
+        }
+    }
+    else if (targetSchoolId && principalSchool && principalSchool !== targetSchoolId) {
+        throw new TRPCError({
+            code: "BAD_REQUEST",
+            message: "Cannot share with a user from a different school",
+        });
+    }
+    // Re-granting the same (folder, principal) pair updates the existing row's
+    // level instead of throwing P2002 against the @@unique. Prisma's composite-
+    // unique-key types refuse nullable columns, so we go through findFirst +
+    // update/create rather than a single upsert.
+    const principalCols = principalToColumns(input.principal);
+    const existing = await prisma.permission.findFirst({
+        where: {
+            folderId: input.folderId,
+            principalType: principalCols.principalType,
+            userId: principalCols.userId,
+            tagId: principalCols.tagId,
+            classId: principalCols.classId,
+            departmentId: principalCols.departmentId,
+            schoolId: principalCols.schoolId,
+        },
+        select: { id: true },
+    });
+    if (existing) {
+        return prisma.permission.update({
+            where: { id: existing.id },
+            data: { level: input.level, grantedById },
+        });
+    }
+    return prisma.permission.create({
+        data: {
+            folderId: input.folderId,
+            ...principalCols,
+            level: input.level,
+            grantedById,
+        },
+    });
+}
+/** Revoke a grant. Allowed for the granter or anyone with WRITE on the folder. */
+export async function revokePermission(userId, permissionId) {
+    const grant = await prisma.permission.findUnique({
+        where: { id: permissionId },
+        select: { id: true, grantedById: true, folderId: true },
+    });
+    if (!grant) {
+        throw new TRPCError({ code: "NOT_FOUND", message: "Permission not found" });
+    }
+    if (grant.grantedById !== userId) {
+        await requireFolderAccess(userId, grant.folderId, "WRITE");
+    }
+    await prisma.permission.delete({ where: { id: permissionId } });
+    return { success: true };
+}
+/** List all explicit grants on a folder. Caller must have WRITE on it. */
+export async function listPermissions(userId, folderId) {
+    await requireFolderAccess(userId, folderId, "WRITE");
+    return prisma.permission.findMany({
+        where: { folderId },
+        include: {
+            user: { select: { id: true, username: true, email: true } },
+            tag: { select: { id: true, name: true, color: true } },
+            class: { select: { id: true, name: true, section: true } },
+            department: { select: { id: true, name: true, color: true } },
+            school: { select: { id: true, name: true } },
+        },
+        orderBy: { createdAt: "desc" },
+    });
+}
+//# sourceMappingURL=permissions.js.map
+//# debugId=2ac7304e-3502-58ed-af8e-db3b64af3009