Files
persionalBrand/apps/api/src/modules/admin/admin-template-package.service.ts
T

486 lines
19 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import {
BadRequestException,
ConflictException,
Injectable,
PayloadTooLargeException,
} from "@nestjs/common";
import { validateTemplatePackageManifest } from "@personal-brand/config";
import type { FastifyRequest } from "fastify";
import { createHash } from "node:crypto";
import { execFile } from "node:child_process";
import { promises as fs } from "node:fs";
import path from "node:path";
import { promisify } from "node:util";
import { PrismaService } from "../../prisma.service.js";
const execFileAsync = promisify(execFile);
const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
const MAX_EXTRACTED_BYTES = 200 * 1024 * 1024;
const MAX_FILES = 5_000;
const PACKAGE_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
type Manifest = {
packageKey: string;
version: string;
displayName: string;
visualTemplateKey?: string;
};
type ChecksumFile = {
formatVersion: string;
packageKey: string;
version: string;
contentChecksum: string;
files: Array<{ path: string; bytes: number; sha256: string }>;
};
type JsonRecord = Record<string, unknown>;
function record(value: unknown): JsonRecord {
return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonRecord) : {};
}
function array(value: unknown): unknown[] {
return Array.isArray(value) ? value : [];
}
function sha256(value: Buffer | string): string {
return createHash("sha256").update(value).digest("hex");
}
function canonical(value: unknown): unknown {
if (Array.isArray(value)) return value.map(canonical);
if (!value || typeof value !== "object") return value;
return Object.fromEntries(
Object.entries(value)
.sort(([left], [right]) => left.localeCompare(right))
.map(([key, item]) => [key, canonical(item)]),
);
}
function jsonObject(value: unknown, label: string): Record<string, unknown> {
if (!value || typeof value !== "object" || Array.isArray(value))
throw new BadRequestException(`${label} 必须是 JSON 对象`);
return value as Record<string, unknown>;
}
function safeEntryName(input: string): string {
if (!input || input.includes("\\") || input.startsWith("/") || /^[A-Za-z]:/.test(input))
throw new BadRequestException("模板包包含不安全的文件路径");
const withoutTrailingSlash = input.endsWith("/") ? input.slice(0, -1) : input;
const normalized = path.posix.normalize(withoutTrailingSlash);
if (!withoutTrailingSlash || normalized !== withoutTrailingSlash || normalized === ".")
throw new BadRequestException("模板包包含不安全的文件路径");
if (normalized.split("/").some((segment) => segment === ".." || segment === "."))
throw new BadRequestException("模板包包含不安全的文件路径");
return normalized;
}
async function listArchiveEntries(archivePath: string): Promise<string[]> {
let list: string;
let verbose: string;
try {
({ stdout: list } = await execFileAsync("tar", ["-tzf", archivePath], {
maxBuffer: 4 * 1024 * 1024,
}));
({ stdout: verbose } = await execFileAsync("tar", ["-tvzf", archivePath], {
maxBuffer: 4 * 1024 * 1024,
}));
} catch {
throw new BadRequestException("模板包不是有效的 gzip tar archive");
}
const entries = list
.split("\n")
.map((item) => item.trimEnd())
.filter(Boolean)
.map(safeEntryName);
if (!entries.length || entries.length > MAX_FILES)
throw new BadRequestException("模板包文件数量超出限制");
const typeLines = verbose
.split("\n")
.map((item) => item.trimEnd())
.filter(Boolean);
if (
typeLines.length !== entries.length ||
typeLines.some((line) => !["-", "d"].includes(line[0] ?? ""))
)
throw new BadRequestException("模板包只允许包含普通文件和目录,不允许链接或特殊文件");
if (new Set(entries).size !== entries.length) throw new BadRequestException("模板包包含重复路径");
return entries;
}
async function walkFiles(
directory: string,
relative = "",
): Promise<Array<{ path: string; bytes: number }>> {
const result: Array<{ path: string; bytes: number }> = [];
for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
const current = relative ? `${relative}/${entry.name}` : entry.name;
const absolute = path.join(directory, entry.name);
if (entry.isSymbolicLink()) throw new BadRequestException("模板包解压后包含符号链接");
if (entry.isDirectory()) result.push(...(await walkFiles(absolute, current)));
else if (entry.isFile()) result.push({ path: current, bytes: (await fs.stat(absolute)).size });
else throw new BadRequestException("模板包包含不支持的文件类型");
}
return result;
}
@Injectable()
export class AdminTemplatePackageService {
constructor(private readonly prisma: PrismaService) {}
async list(page = 1, pageSize = 20) {
const [total, versions] = await this.prisma.$transaction([
this.prisma.templatePackageVersion.count(),
this.prisma.templatePackageVersion.findMany({
orderBy: { importedAt: "desc" },
skip: (page - 1) * pageSize,
take: pageSize,
select: {
id: true,
packageKey: true,
version: true,
displayName: true,
visualTemplateKey: true,
status: true,
contentChecksum: true,
archiveChecksum: true,
validationReport: true,
manifestSnapshot: true,
importedAt: true,
updatedAt: true,
templatePackage: { select: { id: true } },
importedBy: { select: { id: true, username: true, displayName: true } },
},
}),
]);
return {
items: versions.map(({ templatePackage, manifestSnapshot, ...version }) => ({
...version,
templatePackageId: templatePackage.id,
manifestSummary: {
runtimeContract:
typeof record(manifestSnapshot).runtimeContract === "string"
? (record(manifestSnapshot).runtimeContract as string)
: "",
supportedIndustryTemplates: array(
record(manifestSnapshot).supportedIndustryTemplates,
).filter((item): item is string => typeof item === "string"),
requiredCapabilities: array(record(manifestSnapshot).requiredCapabilities).filter(
(item): item is string => typeof item === "string",
),
},
})),
page,
pageSize,
total,
};
}
async importArchive(request: FastifyRequest, actorId: string) {
const part = await request.file({ limits: { files: 1, fileSize: MAX_ARCHIVE_BYTES } });
if (!part) throw new BadRequestException("请上传模板 archive 文件");
if (part.fieldname !== "archive") throw new BadRequestException("上传字段必须是 archive");
const chunks: Buffer[] = [];
let bytes = 0;
let storedArtifactPath: string | null = null;
try {
for await (const chunk of part.file) {
const buffer = Buffer.from(chunk as Uint8Array);
bytes += buffer.length;
if (bytes > MAX_ARCHIVE_BYTES) throw new PayloadTooLargeException("模板包超过 50 MB 限制");
chunks.push(buffer);
}
} catch (error) {
if (error instanceof PayloadTooLargeException) throw error;
throw new BadRequestException("读取模板 archive 失败");
}
if (part.file.truncated) throw new PayloadTooLargeException("模板包超过 50 MB 限制");
const archive = Buffer.concat(chunks);
const archiveChecksum = sha256(archive);
const temporaryRoot = await fs.mkdtemp(path.join(process.cwd(), ".template-import-"));
const archivePath = path.join(temporaryRoot, "package.tar.gz");
const extractedRoot = path.join(temporaryRoot, "extracted");
try {
await fs.writeFile(archivePath, archive, { mode: 0o600 });
const entries = await listArchiveEntries(archivePath);
const roots = new Set(entries.map((entry) => entry.split("/")[0]));
if (roots.size !== 1) throw new BadRequestException("模板包必须只有一个根目录");
const rootName = [...roots][0];
if (
!rootName ||
entries.some((entry) => entry !== rootName && !entry.startsWith(`${rootName}/`))
)
throw new BadRequestException("模板包根目录结构无效");
await fs.mkdir(extractedRoot, { recursive: true });
try {
await execFileAsync(
"tar",
[
"-xzf",
archivePath,
"--directory",
extractedRoot,
"--no-same-owner",
"--no-same-permissions",
],
{ maxBuffer: 4 * 1024 * 1024 },
);
} catch {
throw new BadRequestException("模板包解压失败");
}
const packageRoot = path.join(extractedRoot, rootName);
const files = await walkFiles(packageRoot);
if (files.length > MAX_FILES) throw new BadRequestException("模板包文件数量超出限制");
if (files.reduce((total, file) => total + file.bytes, 0) > MAX_EXTRACTED_BYTES)
throw new PayloadTooLargeException("模板包解压后超过 200 MB 限制");
const manifest = (await this.readJson(
path.join(packageRoot, "template.json"),
"template.json",
)) as Manifest;
const packageJson = jsonObject(
await this.readJson(path.join(packageRoot, "package.json"), "package.json"),
"package.json",
) as { name?: unknown; version?: unknown };
const checksums = jsonObject(
await this.readJson(path.join(packageRoot, "checksums.json"), "checksums.json"),
"checksums.json",
) as unknown as ChecksumFile;
this.validateManifest(manifest, packageJson, checksums);
await this.validateChecksums(packageRoot, files, checksums);
const packageKey = manifest.packageKey;
const existingPackage = await this.prisma.templatePackage.findUnique({
where: { packageKey },
});
const existingVersion = existingPackage
? await this.prisma.templatePackageVersion.findUnique({
where: {
templatePackageId_version: {
templatePackageId: existingPackage.id,
version: manifest.version,
},
},
})
: null;
if (existingVersion) {
if (existingVersion.contentChecksum === checksums.contentChecksum)
return {
imported: false,
idempotent: true,
version: this.publicVersion(existingVersion),
};
throw new ConflictException(`${packageKey}@${manifest.version} 已存在不同内容的版本`);
}
const artifactRoot = path.resolve(
process.env.TEMPLATE_ARTIFACT_ROOT ??
path.join(process.cwd(), "storage", "template-artifacts"),
);
const artifactPath = path.join(
artifactRoot,
packageKey,
manifest.version,
`${archiveChecksum}.tar.gz`,
);
await fs.mkdir(path.dirname(artifactPath), { recursive: true });
await fs.copyFile(archivePath, artifactPath);
storedArtifactPath = artifactPath;
const version = await this.prisma.$transaction(async (tx) => {
const packageRecord =
existingPackage ?? (await tx.templatePackage.create({ data: { packageKey } }));
const created = await tx.templatePackageVersion.create({
data: {
templatePackageId: packageRecord.id,
packageKey,
version: manifest.version,
displayName: manifest.displayName,
visualTemplateKey: manifest.visualTemplateKey ?? null,
manifestSnapshot: manifest,
validationReport: {
formatVersion: "1",
errors: [],
fileCount: files.length,
extractedBytes: files.reduce((total, file) => total + file.bytes, 0),
},
contentChecksum: checksums.contentChecksum,
archiveChecksum,
artifactPath,
importedById: actorId,
},
});
await tx.templatePackageAuditLog.create({
data: {
templatePackageVersionId: created.id,
actorId,
action: "imported",
toStatus: "imported",
metadata: {
contentChecksum: checksums.contentChecksum,
archiveChecksum,
},
},
});
return created;
});
return { imported: true, idempotent: false, version: this.publicVersion(version) };
} catch (error) {
if (storedArtifactPath) await fs.rm(storedArtifactPath, { force: true });
throw error;
} finally {
await fs.rm(temporaryRoot, { recursive: true, force: true });
}
}
async publish(id: string, actorId: string, requestId?: string) {
return this.transition(id, actorId, "published", requestId);
}
async retire(id: string, actorId: string, requestId?: string) {
return this.transition(id, actorId, "retired", requestId);
}
async audit(id: string) {
const version = await this.prisma.templatePackageVersion.findUnique({ where: { id } });
if (!version) throw new BadRequestException("模板版本不存在");
return this.prisma.templatePackageAuditLog.findMany({
where: { templatePackageVersionId: id },
orderBy: { createdAt: "asc" },
include: { actor: { select: { id: true, username: true, displayName: true } } },
});
}
private async transition(
id: string,
actorId: string,
target: "published" | "retired",
requestId?: string,
) {
const version = await this.prisma.templatePackageVersion.findUnique({ where: { id } });
if (!version) throw new BadRequestException("模板版本不存在");
if (version.status === target) return { changed: false, version: this.publicVersion(version) };
const valid =
target === "published" ? version.status === "imported" : version.status === "published";
if (!valid) throw new ConflictException(`模板版本当前状态为 ${version.status},不能执行此操作`);
const updated = await this.prisma.$transaction(async (tx) => {
const changed = await tx.templatePackageVersion.updateMany({
where: { id, status: version.status },
data: { status: target },
});
if (changed.count !== 1) {
const current = await tx.templatePackageVersion.findUnique({ where: { id } });
if (current?.status === target) return { next: current, changed: false };
throw new ConflictException("模板版本状态已被其他操作修改,请刷新后重试");
}
const next = await tx.templatePackageVersion.findUniqueOrThrow({ where: { id } });
await tx.templatePackageAuditLog.create({
data: {
templatePackageVersionId: id,
actorId,
action: target,
fromStatus: version.status,
toStatus: target,
...(requestId ? { requestId } : {}),
},
});
return { next, changed: true };
});
return { changed: updated.changed, version: this.publicVersion(updated.next) };
}
private async readJson(filePath: string, label: string): Promise<unknown> {
try {
return JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
} catch {
throw new BadRequestException(`${label} 不是有效的 JSON 文件`);
}
}
private validateManifest(
manifest: Manifest,
packageJson: { name?: unknown; version?: unknown },
checksums: ChecksumFile,
) {
if (!manifest || typeof manifest !== "object")
throw new BadRequestException("template.json 无效");
if (!PACKAGE_KEY_PATTERN.test(manifest.packageKey))
throw new BadRequestException("模板 packageKey 无效");
if (typeof manifest.version !== "string" || !manifest.version.trim())
throw new BadRequestException("模板 version 无效");
if (typeof manifest.displayName !== "string" || !manifest.displayName.trim())
throw new BadRequestException("模板 displayName 无效");
if (packageJson.name !== `@personal-brand/template-${manifest.packageKey}`)
throw new BadRequestException("package.json name 与 template.json packageKey 不一致");
if (packageJson.version !== manifest.version)
throw new BadRequestException("package.json version 与 template.json version 不一致");
let errors: string[];
try {
errors = validateTemplatePackageManifest(manifest as never);
} catch {
throw new BadRequestException("template.json 不符合模板契约");
}
if (errors.length)
throw new BadRequestException(`template.json 不符合模板契约:${errors.join(";")}`);
if (
checksums.formatVersion !== "1" ||
checksums.packageKey !== manifest.packageKey ||
checksums.version !== manifest.version
)
throw new BadRequestException("checksums.json 元数据不一致");
}
private async validateChecksums(
packageRoot: string,
files: Array<{ path: string; bytes: number }>,
checksums: ChecksumFile,
) {
if (!Array.isArray(checksums.files) || checksums.files.length !== files.length - 1)
throw new BadRequestException("checksums.json 文件清单不完整");
const comparePath = (left: { path: string }, right: { path: string }) =>
left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
const actualFiles = files.filter((file) => file.path !== "checksums.json").sort(comparePath);
const checksumFiles = [...checksums.files].sort(comparePath);
if (checksumFiles.some((item, index) => item.path !== actualFiles[index]?.path))
throw new BadRequestException("checksums.json 文件清单与 archive 不一致");
for (const item of checksumFiles) {
safeEntryName(item.path);
if (
!Number.isSafeInteger(item.bytes) ||
item.bytes < 0 ||
!/^[a-f0-9]{64}$/.test(item.sha256)
)
throw new BadRequestException("checksums.json 文件摘要格式无效");
const content = fs.readFile(path.join(packageRoot, item.path));
if (item.bytes !== actualFiles.find((file) => file.path === item.path)?.bytes)
throw new BadRequestException("模板文件大小校验失败");
if (sha256(await content) !== item.sha256)
throw new BadRequestException("模板文件摘要校验失败");
}
const expected = sha256(JSON.stringify(canonical(checksumFiles)));
if (checksums.contentChecksum !== expected || !/^[a-f0-9]{64}$/.test(checksums.contentChecksum))
throw new BadRequestException("模板内容摘要校验失败");
}
private publicVersion(version: {
id: string;
packageKey: string;
version: string;
displayName: string;
visualTemplateKey: string | null;
status: string;
contentChecksum: string;
archiveChecksum: string;
importedAt: Date;
}) {
return {
id: version.id,
packageKey: version.packageKey,
version: version.version,
displayName: version.displayName,
visualTemplateKey: version.visualTemplateKey,
status: version.status,
contentChecksum: version.contentChecksum,
archiveChecksum: version.archiveChecksum,
importedAt: version.importedAt,
};
}
}