feat(authz): 重写权限模板分配与班级授权边界

拆分能力、分配范围和业务关系,固定管理员能力并收紧组织级写入口。
补齐内容、课表、设备会话和实时通道授权,兼容旧库分配及历史快照。
重写权限分配预览,按实际可操作范围展示维护入口,合并学生入口并独立学年升级页。
增加授权攻击矩阵及静态门禁,更新隔离回归与开发契约。

验证:授权矩阵 23 段通过,Node 24 下 Web 63/63,类型检查、lint 与文档严格构建通过。
This commit is contained in:
LoveChengke committed 2026-10-31 09:40:23 +08:00
1 parent 682818dd4a
commit 66be3a63b1
115 files changed
+4463 -2747

No files matched your search

@@ -1,3 +1,5 @@
import type { TokenPayload } from '../../lib/jwt.js';
import { assertAdmin } from '../../lib/authz/index.js';
import { getReleaseProgress, setReleaseProgress } from './release-progress.js';
import { Transform } from 'node:stream';
import crypto from 'node:crypto';
@@ -54,10 +56,14 @@ function releaseRoot(): string {
}
function releaseDir(version: string): string {
if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(version) || version.includes('..'))
throw ApiError.badRequest('版本号不是安全路径段');
return path.join(releaseRoot(), version);
}
function releaseFilePath(version: string, fileName: string): string {
if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(fileName) || fileName.includes('..'))
throw ApiError.badRequest('文件名不是安全路径段');
return path.join(releaseDir(version), fileName);
}
@@ -128,9 +134,11 @@ export async function resolveReleaseFile(
/** 登记一份已经在磁盘上的安装包:算 sha256 / 大小后落库(可重复登记,会覆盖) */
export async function registerRelease(
userId: string,
actor: TokenPayload,
input: RegisterClientReleaseInput,
): Promise<ClientReleaseDto> {
assertAdmin(actor);
const userId = actor.sub;
const version = input.version;
// 文件名默认走发布命名约定(与 GitHub Release、官网兜底直链一致)
const known = (await prisma.clientRelease.findUnique({ where: { version } })) as ReleaseRow | null;
@@ -171,11 +179,12 @@ export async function registerRelease(
/** 让服务端从 GitHub 拉一份安装包并登记(教室无外网时由服务端代下) */
export async function fetchReleaseFromGithub(
userId: string,
actor: TokenPayload,
input: FetchClientReleaseInput,
): Promise<ClientReleaseDto> {
if (['downloading', 'verifying'].includes(getReleaseProgress().stage))
throw ApiError.conflict('已有安装包正在下载');
assertAdmin(actor);
const version = input.version;
setReleaseProgress({ version, stage: 'downloading', downloadedBytes: 0, totalBytes: 0, error: '' });
const fileName = clientReleaseFileName(version);
@@ -221,13 +230,14 @@ export async function fetchReleaseFromGithub(
// 落盘后统一走登记:sha256 / 大小 / 落库都在同一处算
setReleaseProgress({ stage: 'verifying' });
const release = await registerRelease(userId, { version, fileName });
const release = await registerRelease(actor, { version, fileName });
setReleaseProgress({ stage: 'ready', downloadedBytes: release.size, totalBytes: release.size });
return release;
}
/** 删除一份缓存的安装包(元数据 + 磁盘文件) */
export async function deleteRelease(version: string): Promise<{ version: string }> {
export async function deleteRelease(actor: TokenPayload, version: string): Promise<{ version: string }> {
assertAdmin(actor);
const row = (await prisma.clientRelease.findUnique({ where: { version } })) as ReleaseRow | null;
if (!row) throw ApiError.notFound('服务端没有这个版本的安装包');
await prisma.clientRelease.delete({ where: { version } });
@@ -1,3 +1,4 @@
import { assertClassDevice, assertPermission, classIdsFor } from '../../lib/authz/index.js';
import { getReleaseProgress, setReleaseProgress } from './release-progress.js';
import { Router } from 'express';
import { sendCreated, sendOk, ApiError } from '../../lib/http.js';
@@ -7,9 +8,10 @@ import {
hasAuthPermission,
requireAnyPermission,
requirePermission,
requireStaffPermission,
requireAdmin,
requirePermissionOrClassDevice,
} from '../../middleware/auth.js';
import { validate, validatedBody, validatedParams } from '../../middleware/validate.js';
import { validateBadRequest as validate, validatedBody, validatedParams } from '../../middleware/validate.js';
import { defineModule } from '../module.types.js';
import * as clientReleases from './client-releases.service.js';
import * as updateService from './update.service.js';
@@ -39,7 +41,7 @@ router.get('/client/progress', requirePermission('client:update'), async (_req,
* 权限:任何已登录用户都能查(信息本身来自公开仓库)。`force=1` 绕过服务端缓存,
* 但**只有管理员生效** —— 否则任意登录用户都能靠刷这个参数把匿名限流打满。
*/
router.get('/check', requireStaffPermission('update:check'), async (req, res) => {
router.get('/check', requirePermissionOrClassDevice('update:check'), async (req, res) => {
const force = req.query.force === '1' && hasAuthPermission(req, 'update:force');
sendOk(res, await updateService.checkForUpdates({ force }), '更新检查完成');
});
@@ -68,13 +70,14 @@ router.get(
*/
router.post(
'/client/fetch',
requireAdmin(),
requirePermission('client:update'),
validate({ body: fetchClientReleaseSchema }),
async (req, res) => {
const user = getAuthUser(req);
const input = validatedBody<FetchClientReleaseInput>(req);
try {
sendCreated(res, await clientReleases.fetchReleaseFromGithub(user.sub, input), '安装包已下载并登记');
sendCreated(res, await clientReleases.fetchReleaseFromGithub(user, input), '安装包已下载并登记');
} catch (error) {
if (
!(error instanceof ApiError && error.status === 409) &&
@@ -97,23 +100,25 @@ router.post(
*/
router.post(
'/client/releases',
requireAdmin(),
requirePermission('client:update'),
validate({ body: registerClientReleaseSchema }),
async (req, res) => {
const user = getAuthUser(req);
const input = validatedBody<RegisterClientReleaseInput>(req);
sendCreated(res, await clientReleases.registerRelease(user.sub, input), '安装包已登记');
sendCreated(res, await clientReleases.registerRelease(user, input), '安装包已登记');
},
);
/** DELETE /api/update/client/releases/:version - 删除缓存(元数据 + 磁盘文件) */
router.delete(
'/client/releases/:version',
requireAdmin(),
requirePermission('client:update'),
validate({ params: clientReleaseVersionParamSchema }),
async (req, res) => {
const { version } = validatedParams<{ version: string }>(req);
sendOk(res, await clientReleases.deleteRelease(version), '安装包已删除');
sendOk(res, await clientReleases.deleteRelease(getAuthUser(req), version), '安装包已删除');
},
);
@@ -128,6 +133,13 @@ router.get(
'/client/download/:version',
validate({ params: clientReleaseVersionParamSchema }),
async (req, res) => {
const user = getAuthUser(req);
if (user.role === 'CLASS_DEVICE') assertClassDevice(user, user.classId ?? user.sub);
else {
await assertPermission(user, 'client:read');
if (user.role !== 'ADMIN' && !(await classIdsFor(user, 'client:read')).length)
throw ApiError.forbidden('无可访问班级');
}
const { version } = validatedParams<{ version: string }>(req);
const found = await clientReleases.resolveReleaseFile(version);
if (!found) throw ApiError.notFound('服务端没有缓存这个版本的安装包');
@@ -13,7 +13,7 @@ export const clientReleaseVersionSchema = z
.trim()
.min(1, '请输入版本号')
.max(40, '版本号最多 40 个字符')
.refine((value) => SAFE_SEGMENT.test(value), {
.refine((value) => SAFE_SEGMENT.test(value) && value !== '.' && value !== '..' && !value.includes('..'), {
message: '版本号只能包含字母、数字、点、下划线与短横线',
});
@@ -30,7 +30,9 @@ export const registerClientReleaseSchema = z.object({
.trim()
.min(1)
.max(120)
.refine((value) => SAFE_SEGMENT.test(value), { message: '文件名只能包含字母、数字、点、下划线与短横线' })
.refine((value) => SAFE_SEGMENT.test(value) && value !== '.' && value !== '..' && !value.includes('..'), {
message: '文件名只能包含字母、数字、点、下划线与短横线',
})
.optional(),
notes: z.string().trim().max(500).optional(),
});