@akairos/pipeline 0.19.1 → 0.20.0

package/README.md

@@ -234,7 +234,7 @@ Studio 模板与 pipeline 配置分开保存：`data/templates/*.json` 保存模
 
 固定素材的 `templateAssetKey` 是模板内的替换标识，图片来源仍是 `images[].src`。支持可访问的 HTTP/HTTPS URL、本地文件及 `/uploads/...` 引用。使用 `/uploads/...` 时应连同 `uploads/` 目录原文件名一起同步；绝对路径应改为服务器可用路径，或把素材上传到 COS/CDN 后使用稳定 HTTPS URL。编辑器预览远程图片还需要图片服务允许跨域读取。
 
-**版本基线（2026-10-15）：** Pipeline `0.19.1` 固定 Typeset Studio `0.2.6` 和 myno `0.3.1`；插件仍需显式配置。模板与素材不打进 npm 包，服务器通过运行时配置包提供。源码适配器路径仅用于本地联调，Worker 使用 npm 入口。
+**版本基线（2026-10-15）：** Pipeline `0.19.2` 固定 Typeset Studio `0.2.7` 和 myno `0.3.1`；插件仍需显式配置。模板与素材不打进 npm 包，服务器通过运行时配置包提供。源码适配器路径仅用于本地联调，Worker 使用 npm 入口。
 
 ### 生成 Worker 运行时配置包
 

package/article-style.ts

@@ -0,0 +1,2 @@
+export { createArticleStyleSnapshot, validateArticleStyleSnapshot } from "./src/article-style";
+export type { ArticleStyleManifest, ArticleStyleSnapshot } from "./src/article-style";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akairos/pipeline",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -12,6 +12,7 @@
   },
   "files": [
     "src/",
+    "article-style.ts",
     "ARTICLE-THEMES.md",
     "THIRD-PARTY-NOTICES.md"
   ],
@@ -28,7 +29,7 @@
   },
   "dependencies": {
     "@akairos/milkdown-article-plugins": "^0.1.6",
-    "@akairos/typeset-studio": "0.2.6",
+    "@akairos/typeset-studio": "0.2.7",
     "@chenglou/pretext": "0.0.8",
     "image-size": "^2.0.2",
     "pngjs": "^7.0.0",

package/src/article-style.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from "bun:test";
+import { createArticleStyleSnapshot, validateArticleStyleSnapshot } from "../article-style";
+
+const manifest = {
+  schemaVersion: 1, engineVersion: 1, id: "style-1", name: "正文样式", version: "1.0.0",
+  editorVars: { "--brand": "#AABBCC" },
+  exportTheme: { bodyFontSize: "18.00px", bodyLineHeight: "1.80", primaryColor: "#AABBCC", h2Color: "#112233" },
+  syntaxPresets: { h2: "pillar" },
+};
+
+test("正文样式规范化、内容 hash 与修订身份独立且可严格回读", () => {
+  const snapshot = createArticleStyleSnapshot(manifest, manifest.id, 1);
+  expect(snapshot.manifest.exportTheme.bodyFontSize).toBe("18px");
+  expect(snapshot.manifest.exportTheme.bodyLineHeight).toBe("1.8");
+  expect(snapshot.manifest.editorVars["--brand"]).toBe("#aabbcc");
+  expect(snapshot.manifest.css).toBe("");
+  expect(validateArticleStyleSnapshot(JSON.parse(JSON.stringify(snapshot)))).toEqual(snapshot);
+  expect(createArticleStyleSnapshot(snapshot.manifest, manifest.id, 2).hash).toBe(snapshot.hash);
+  const reordered = Object.fromEntries(Object.entries(manifest).reverse());
+  expect(createArticleStyleSnapshot(reordered, manifest.id, 1).hash).toBe(snapshot.hash);
+});
+
+test("正文快照拒绝未知版本、身份分裂、篡改及未支持字段", () => {
+  const snapshot = createArticleStyleSnapshot(manifest, manifest.id, 1);
+  for (const patch of [{ schemaVersion: 2 }, { revision: 0 }, { id: "other" }, { hash: "0".repeat(64) }, { path: "/private/style.json" }]) {
+    expect(() => validateArticleStyleSnapshot({ ...snapshot, ...patch })).toThrow();
+  }
+  for (const patch of [
+    { engineVersion: 2 }, { css: "p { color: red }" }, { structure: {} }, { assets: [] }, { fonts: [] },
+    { editorVars: { "--font": "serif" } }, { editorVars: { "--brand": "url(https://example.test/a)" } },
+    { exportTheme: { bodyFontSize: "25px" } }, { exportTheme: { bodyLineHeight: "1.1" } },
+    { exportTheme: { fontFamily: "serif" } }, { syntaxPresets: { h2: "unknown" } },
+  ]) expect(() => createArticleStyleSnapshot({ ...manifest, ...patch }, manifest.id, 1)).toThrow();
+});

package/src/article-style.ts

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { ArticleThemeSchema, validateArticleThemeCss } from "./article-theme";
+
+const color = z.string().regex(/^#[a-f\d]{6}$/i).transform(value => value.toLowerCase());
+const fontSize = z.string().regex(/^\d+(?:\.\d+)?px$/)
+  .refine(value => Number.parseFloat(value) >= 12 && Number.parseFloat(value) <= 24)
+  .transform(value => `${Number.parseFloat(value)}px`);
+const lineHeight = z.string().regex(/^\d+(?:\.\d+)?$/)
+  .refine(value => Number(value) >= 1.2 && Number(value) <= 2.4)
+  .transform(value => String(Number(value)));
+
+// 复用主题身份，仅开放本轮已验证的纯 JSON 正文样式。
+const ArticleStyleManifestSchema = ArticleThemeSchema.pick({
+  schemaVersion: true, engineVersion: true, id: true, name: true, version: true, description: true,
+}).extend({
+  editorVars: z.object({ "--brand": color.optional() }).strict().default({}),
+  exportTheme: z.object({
+    bodyFontSize: fontSize.optional(), bodyLineHeight: lineHeight.optional(),
+    primaryColor: color.optional(), h2Color: color.optional(),
+  }).strict().default({}),
+  syntaxPresets: z.object({ h2: z.enum(["pillar", "bottom-line", "plain"]).optional() }).strict().default({}),
+  css: z.literal("").default(""),
+}).strict();
+
+export type ArticleStyleManifest = z.infer<typeof ArticleStyleManifestSchema>;
+const SnapshotHeaderSchema = z.object({
+  schemaVersion: z.literal(1),
+  id: ArticleThemeSchema.shape.id,
+  revision: z.number().int().positive(),
+}).strict();
+
+export interface ArticleStyleSnapshot {
+  schemaVersion: 1;
+  id: string;
+  revision: number;
+  manifest: ArticleStyleManifest;
+  hash: string;
+}
+
+/** 内容 hash 只基于规范化 manifest；资产修订身份由外层快照保存。 */
+export function createArticleStyleSnapshot(value: unknown, id: string, revision: number): ArticleStyleSnapshot {
+  const header = SnapshotHeaderSchema.parse({ schemaVersion: 1, id, revision });
+  const manifest = ArticleStyleManifestSchema.parse(value);
+  if (manifest.id !== header.id) throw new Error("Article style id must match manifest.id");
+  validateArticleThemeCss(ArticleThemeSchema.parse(manifest), manifest.css);
+  const hash = createHash("sha256").update(JSON.stringify(manifest)).digest("hex");
+  return { ...header, manifest, hash };
+}
+
+/** 严格验证快照格式及内容 hash，未知版本和被篡改内容均拒绝。 */
+export function validateArticleStyleSnapshot(value: unknown): ArticleStyleSnapshot {
+  const input = SnapshotHeaderSchema.extend({ manifest: z.unknown(), hash: z.string().regex(/^[a-f\d]{64}$/) }).strict().parse(value);
+  const snapshot = createArticleStyleSnapshot(input.manifest, input.id, input.revision);
+  if (input.hash !== snapshot.hash) throw new Error("Article style hash mismatch");
+  return snapshot;
+}

package/src/article-theme.ts

@@ -41,6 +41,16 @@ export interface ArticleThemePackage {
   files: Map<string, Uint8Array>;
 }
 
+/** 本地主题与云端快照共用 CSS 边界，禁止隐藏外部资源。 */
+export function validateArticleThemeCss(manifest: ArticleThemeManifest, css: string): void {
+  const unsafeCss = (value: string) => /\\|@import\b|url\s*\(|expression\s*\(/i.test(value.replace(/\/\*[\s\S]*?\*\//g, ""));
+  if (Object.keys(manifest.editorVars).some(key => !/^--[a-zA-Z0-9_-]+$/.test(key))) throw new Error("模板变量名无效");
+  for (const value of [...Object.values(manifest.editorVars), ...Object.values(manifest.exportTheme)]) {
+    if (value.length > 8192 || unsafeCss(value)) throw new Error("模板变量不能包含外部资源或 CSS 转义");
+  }
+  if (css.length > 256_000 || unsafeCss(css)) throw new Error("模板 CSS 不支持外部资源、CSS 转义或可执行表达式");
+}
+
 /** 限制所有资源在包内，拒绝符号链接、目录越界及过大文件。 */
 export async function readArticleTheme(inputPath: string): Promise<ArticleThemePackage> {
   const entry = resolve(inputPath);
@@ -76,14 +86,8 @@ export async function readArticleTheme(inputPath: string): Promise<ArticleThemeP
   if (manifest.structure.headerImage) paths.push(manifest.structure.headerImage);
   for (const name of new Set(paths)) await read(name);
   const css = manifest.css ?? new TextDecoder().decode(files.get(manifest.stylesheet));
-  // 模板无需 CSS 转义；拒绝用转义或注释隐藏的网络/文件资源。
-  const unsafeCss = (value: string) => /\\|@import\b|url\s*\(|expression\s*\(/i.test(value.replace(/\/\*[\s\S]*?\*\//g, ""));
-  if (Object.keys(manifest.editorVars).some(key => !/^--[a-zA-Z0-9_-]+$/.test(key))) throw new Error("模板变量名无效");
-  for (const value of [...Object.values(manifest.editorVars), ...Object.values(manifest.exportTheme)]) {
-    if (value.length > 8192 || unsafeCss(value)) throw new Error("模板变量不能包含外部资源或 CSS 转义");
-  }
+  validateArticleThemeCss(manifest, css);
   if (manifest.structure.headerImage && !/\.(png|jpe?g|gif|webp)$/i.test(manifest.structure.headerImage)) throw new Error("模板页首素材仅支持 PNG、JPEG、GIF、WebP");
-  if (css.length > 256_000 || unsafeCss(css)) throw new Error("模板 CSS 不支持外部资源、CSS 转义或可执行表达式");
   const digest = createHash("sha256").update(JSON.stringify(manifest)).update(css);
   for (const name of [...new Set([...manifest.assets, ...(manifest.structure.headerImage ? [manifest.structure.headerImage] : [])])].sort()) {
     digest.update(name).update(files.get(name)!);