feat: 遮蔽后台静态产物中的 Taro 指纹

Traefik 把 wechat.app.que01.top 上除 /api、/media 以外的路径直接转发到 Admin 静态
服务器且没有鉴权,因此 /admin/assets/*.js 可以被任意下载。后台产物里的模板 renderer
glob 路径(packages/template-*/taro/index.tsx)与按钮尺寸令牌(--taro-button-height)
同样暴露技术栈,此前只遮蔽了 Taro 双端产物。

- mask-taro.cjs 增加 admin 目标,覆盖 apps/admin/dist,接入根脚本 build:admin:preview;
- deploy:package 在后台构建后校验 apps/admin/dist,命中指纹即中止打包;
- 补充遮蔽目标测试与文档(ADR 0025、README、部署说明、交付清单)。

验证:后台产物遮蔽后 glob key 与运行时查找同步改名;未遮蔽/已遮蔽产物用生产静态
服务器跑同一套后台浏览器测试,失败内容逐字节一致(既有失败与本改动无关);H5 预览
11 项浏览器回归全部通过;admin 构建、lint、typecheck、deploy 与 API 测试通过。
This commit is contained in:
que01 committed 2026-10-13 23:18:43 +08:00
1 parent 9ad2776515
commit 4d1cd8f365
8 files changed
+63 -8

No files matched your search

+2 -1
View File
@@ -37,10 +37,11 @@ TEMPLATE_KEY=linjing-editorial pnpm --filter @personal-brand/taro build:weapp
## 构建产物遮蔽
生产构建会调用构建后处理脚本 `config/mask-taro.cjs`,按 `config/mask.config.json` 替换产物里的 Taro 标识符(文件名与内容使用同一张表),遮蔽后仍命中 `forbidden` 词表时构建失败。`build:h5`、`build:weapp`、`build:preview` 都已接入;`dev:h5`、`dev:preview` 保持原始命名便于调试。改架构名只改 `config/mask.config.json`;复核某次产物是否干净用:
生产构建会调用构建后处理脚本 `config/mask-taro.cjs`,按 `config/mask.config.json` 替换产物里的 Taro 标识符(文件名与内容使用同一张表),遮蔽后仍命中 `forbidden` 词表时构建失败。`build:h5`、`build:weapp`、`build:preview` 都已接入,后台静态产物由根脚本 `pnpm build:admin:preview` 用 `admin` 目标覆盖;`dev:h5`、`dev:preview` 保持原始命名便于调试。改架构名只改 `config/mask.config.json`;复核某次产物是否干净用:
```sh
TEMPLATE_KEY=acheng-campus-food node config/mask-taro.cjs weapp --check
node config/mask-taro.cjs admin --check
```
由于产物名称与源码名称不同,产物契约测试用 `test/mask-names.mjs` 的 `unmask()` 还原后再断言,浏览器测试的选择器写成 `:is(<源码名>, <遮蔽名>)`。机制与取舍见 [docs/adr/0025-build-output-stack-masking.md](../../docs/adr/0025-build-output-stack-masking.md)。
+4 -1
View File
@@ -8,6 +8,7 @@
* node config/mask-taro.cjs weapp 处理后 dist/<template>/weapp
* node config/mask-taro.cjs h5 处理后 dist/<template>/h5
* node config/mask-taro.cjs h5 --preview 处理后 dist/template-preview/h5
* node config/mask-taro.cjs admin 处理后后台静态产物 apps/admin/dist
* node config/mask-taro.cjs weapp --check 只检查是否仍有指纹,不修改
*/
const fs = require("node:fs");
@@ -75,6 +76,8 @@ function maskFileName(name, replacements) {
function resolveTargets(envType, preview) {
if (preview) return [path.join(taroRoot, "dist/template-preview/h5")];
// 后台静态产物同样对外可达,其中的模板 renderer 路径与按钮尺寸变量也会带出指纹。
if (envType === "admin") return [path.resolve(taroRoot, "../admin/dist")];
const templateKey = process.env.TEMPLATE_KEY;
if (!templateKey) throw new Error("TEMPLATE_KEY is required for non-preview masking");
return [path.join(taroRoot, "dist", templateKey, envType)];
@@ -192,6 +195,6 @@ function main() {
if (failed) process.exit(1);
}
module.exports = { maskText, maskFileName, maskDirectory, findLeaks, loadConfig };
module.exports = { maskText, maskFileName, maskDirectory, findLeaks, loadConfig, resolveTargets };
if (require.main === module) main();
+28 -1
View File
@@ -7,7 +7,13 @@ import { createRequire } from "node:module";
import { maskConfig, masked, unmask } from "./mask-names.mjs";
const require = createRequire(import.meta.url);
const { maskText, maskFileName, maskDirectory, findLeaks } = require("../config/mask-taro.cjs");
const {
maskText,
maskFileName,
maskDirectory,
findLeaks,
resolveTargets,
} = require("../config/mask-taro.cjs");
const replacements = maskConfig.replacements;
/** 长度超过 40 的 base64/哈希片段,遮蔽时必须原样保留。 */
@@ -31,6 +37,27 @@ test("遮蔽表在测试与构建之间保持一致", () => {
);
});
test("遮蔽目标覆盖双端产物、预览与后台静态产物", () => {
const taroRoot = path.resolve(import.meta.dirname, "..");
const previous = process.env.TEMPLATE_KEY;
try {
process.env.TEMPLATE_KEY = "example-template";
assert.deepEqual(resolveTargets("weapp", false), [
path.join(taroRoot, "dist/example-template/weapp"),
]);
assert.deepEqual(resolveTargets("h5", false), [
path.join(taroRoot, "dist/example-template/h5"),
]);
assert.deepEqual(resolveTargets("h5", true), [path.join(taroRoot, "dist/template-preview/h5")]);
assert.deepEqual(resolveTargets("admin", false), [path.resolve(taroRoot, "../admin/dist")]);
delete process.env.TEMPLATE_KEY;
assert.throws(() => resolveTargets("weapp", false), /TEMPLATE_KEY/);
} finally {
if (previous === undefined) delete process.env.TEMPLATE_KEY;
else process.env.TEMPLATE_KEY = previous;
}
});
test("文本遮蔽改标识符但不损坏不透明数据段", () => {
const content = `var tmpl="taro_tmpl";var key="${opaqueRun}";const modifyTaroEvent=1;`;
const result = maskText(content, replacements);
+6 -2
View File
@@ -4,16 +4,19 @@
模板预览(H5)与微信小程序产物都是外部可获取的材料:预览页面可以打开 DevTools 查看 DOM 与资源,小程序包也能从微信侧下载后反编译。Taro 的指纹在产物中大量出现且没有官方开关:`taro_tmpl`、`base.wxml`、`utils.wxs`、`comp.*`、`taro.js`、`taro-*-core` 自定义元素、`taroWindowProvider`、`taro_tabbar_page`、`--taro-button-height`、`project.config.json` 的 `projectname` 等。竞争对手据此可以判断预览与小程序都由 Taro 生成。
后台静态站点同样对外可达:Traefik 把 `wechat.app.que01.top` 上除 `/api`、`/media` 以外的全部路径直接转发到 Admin 静态服务器,没有鉴权中间件,因此 `https://…/admin/assets/*.js` 可以直接下载。后台产物里带有模板 renderer 的 glob 路径(`packages/template-*/taro/index.tsx`)和按钮尺寸令牌(`--taro-button-height`),同样会暴露技术栈。
Taro 4.3 没有隐藏这些名称的配置项。名称分别硬编码在 `@tarojs/plugin-platform-weapp`、`@tarojs/vite-runner`、`@tarojs/runtime` 内部;官方 hook(`modifyBuildAssets`、`modifyMiniConfigs`、`modifyRunnerOpts`)只能改写构建产物与配置,覆盖不到运行时内部硬编码的标识符。
## Decision
- 在 `apps/taro` 的生产构建脚本末尾增加构建后处理:`apps/taro/config/mask-taro.cjs` 读取 `apps/taro/config/mask.config.json`,对 `dist/<templateKey>/weapp`、`dist/<templateKey>/h5`、`dist/template-preview/h5` 做确定性改名。
- 在 `apps/taro` 的生产构建脚本末尾增加构建后处理:`apps/taro/config/mask-taro.cjs` 读取 `apps/taro/config/mask.config.json`,对 `dist/<templateKey>/weapp`、`dist/<templateKey>/h5`、`dist/template-preview/h5` 做确定性改名;后台静态产物 `apps/admin/dist` 通过 `admin` 目标覆盖,接入根脚本 `build:admin:preview`。
- 同一张替换表同时作用于文件名和文本内容,因此 `taro.js` 与其引用会一起变成 `appkit.js`,`taro_tmpl` 与页面里的引用也保持同步,不需要维护两份映射。
- 只遮蔽 Taro 相关标识符;vite、rollup、rolldown 等通用打包工具的名称属于行业通用信息,不做处理。
- 长度 ≥ 40 的不透明串(内嵌 base64、摘要)保持原样,避免误改数据。
- 遮蔽后仍存在 `forbidden` 词表命中时构建失败(退出码 1),因此产物不会静默泄露。
- `project.config.json` 的 `projectname`、`description` 由配置中性化。
- `pnpm deploy:package` 在 `build:admin:preview` 之后对 `apps/admin/dist` 做一次指纹校验,命中即中止打包(`scripts/deploy/package-release.mjs`)。
- 源码与开发构建不改名:`dev:h5`、`dev:preview` 输出保留 Taro 原始命名,便于本地调试;只有 `build:h5`、`build:weapp`、`build:preview` 产物会遮蔽。
## Alternatives
@@ -28,10 +31,11 @@ Taro 4.3 没有隐藏这些名称的配置项。名称分别硬编码在 `@taroj
- 产物中的名称与源码名称不一致,因此产物契约测试必须先 `unmask()` 再断言,浏览器测试的选择器使用 `:is(<源码名>, <遮蔽名>)` 同时接受两种命名。
- 新增会出现在产物里的 Taro 标识符时,需要同时更新 `mask.config.json` 的 `replacements` 与 `forbidden`,否则构建会因为 `forbidden` 命中而失败(这是期望行为)。
- 必须通过 `pnpm --filter @personal-brand/taro build:*` 构建。直接执行 `taro build` 不经过遮蔽。
- 后台静态产物必须通过 `pnpm build:admin:preview`(或 `pnpm deploy:package`)构建;单独运行 `pnpm --filter @personal-brand/admin build` 不会遮蔽。
- 改架构名只改 `mask.config.json`,不需要改构建脚本、测试或文档中的映射。
## Migration Plan
1. 默认 `enabled: true`;出现遮蔽引起的问题时可临时置为 `false` 让构建脚本跳过处理,产物回到未遮蔽状态。
2. 新增模板或升级 Taro 后先跑一次 `build:weapp` 与 `build:preview`,确认构建脚本的指纹检查通过。
3. 需要复核某次产物是否干净时执行 `TEMPLATE_KEY=<key> node config/mask-taro.cjs weapp --check`;它只检查、不修改。
3. 需要复核某次产物是否干净时执行 `TEMPLATE_KEY=<key> node config/mask-taro.cjs weapp --check`(后台产物用 `node apps/taro/config/mask-taro.cjs admin --check`);它只检查、不修改。
+1 -1
View File
@@ -66,7 +66,7 @@ pnpm preview:templates
VITE_APP_BASE_PATH=/ ADMIN_PORT=3000 pnpm --filter @personal-brand/admin dev
```
预览与小程序产物在构建时遮蔽 Taro 标识符(见 [ADR 0025](adr/0025-build-output-stack-masking.md)),因此生产预览与小程序包只通过包内构建脚本产出:`pnpm build:admin:preview`、`pnpm --filter @personal-brand/taro build:weapp`。直接运行 `taro build` 不会执行遮蔽,产物会带出技术栈指纹;遮蔽后仍检测到指纹时构建会失败。
预览与小程序产物在构建时遮蔽 Taro 标识符(见 [ADR 0025](adr/0025-build-output-stack-masking.md)),因此生产预览与小程序包只通过包内构建脚本产出:`pnpm build:admin:preview`、`pnpm --filter @personal-brand/taro build:weapp`。直接运行 `taro build` 不会执行遮蔽,产物会带出技术栈指纹;遮蔽后仍检测到指纹时构建会失败,`pnpm deploy:package` 还会在打包前校验 `apps/admin/dist`,命中指纹即中止发布。
本地 Admin 默认连接 `http://localhost:3002` 上的统一预览服务。`VITE_TEMPLATE_PREVIEW_URL` 只用于部署时覆盖预览应用地址,不再按模板配置 URL map。
+1 -1
View File
@@ -39,7 +39,7 @@
`TEMPLATE_KEY=<template-key> API_BASE_URL=<production-api> WEAPP_APP_ID=<appid> pnpm --filter @personal-brand/taro build:weapp`;
- 小程序和 H5 必须分别构建并归档到 `apps/taro/dist/<templateKey>/weapp` 与 `apps/taro/dist/<templateKey>/h5`;产物契约测试通过;
- 产物检查必须覆盖:`project.config.json` 的 AppID、请求内嵌的 `API_BASE_URL`、`/media/` 相对地址补全结果、`common.wxss` 中的按钮规则;
- 产物不得出现 Taro 指纹:`build:weapp`、`build:h5`、`build:preview` 必须走包内脚本(构建后处理失败会中断构建),必要时用 `node config/mask-taro.cjs <weapp|h5> --check` 复核;改名规则只改 `apps/taro/config/mask.config.json`;
- 产物不得出现 Taro 指纹:`build:weapp`、`build:h5`、`build:preview`、后台静态产物必须走包内脚本(`pnpm build:admin:preview` 或 `pnpm deploy:package`,构建后处理与打包门禁失败都会中断),必要时用 `node config/mask-taro.cjs <weapp|h5|admin> --check` 复核;改名规则只改 `apps/taro/config/mask.config.json`;
- 涉及 `Button`、`Input`、`Textarea`、`Picker` 等原生控件时,源码和产物都要核对;禁止只依据 H5 预览判定小程序样式;
- 按页面角色检查视觉点,不按模板名称写专用清单,并记录截图或说明未改动原因:
- 首页:媒体加载、横向间距、标签换行、整卡点击;
+1 -1
View File
@@ -34,7 +34,7 @@
"deploy:images": "node scripts/deploy/export-images.mjs",
"test:deploy-verify": "node --test scripts/deploy/verify-release.test.mjs",
"test:deploy": "node --test scripts/deploy/*.test.mjs deploy/*.test.mjs",
"build:admin:preview": "PREVIEW_ALL_TEMPLATES=true API_BASE_URL=/api PREVIEW_PUBLIC_PATH=/template-preview/ pnpm --filter @personal-brand/taro build:preview && node scripts/package-template-preview.cjs && VITE_APP_BASE_PATH=/admin/ VITE_API_BASE_URL=/api pnpm --filter @personal-brand/admin build",
"build:admin:preview": "PREVIEW_ALL_TEMPLATES=true API_BASE_URL=/api PREVIEW_PUBLIC_PATH=/template-preview/ pnpm --filter @personal-brand/taro build:preview && node scripts/package-template-preview.cjs && VITE_APP_BASE_PATH=/admin/ VITE_API_BASE_URL=/api pnpm --filter @personal-brand/admin build && node apps/taro/config/mask-taro.cjs admin",
"build:taro:food": "pnpm --filter @personal-brand/taro build:h5 && pnpm --filter @personal-brand/taro build:weapp",
"build:taro:linjing": "TEMPLATE_KEY=linjing-editorial pnpm --filter @personal-brand/taro build:h5 && TEMPLATE_KEY=linjing-editorial pnpm --filter @personal-brand/taro build:weapp",
"template:doctor": "node scripts/template-doctor.mjs",
+20
View File
@@ -3,8 +3,12 @@ import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { spawnSync } from "node:child_process";
import { createRequire } from "node:module";
import { checkPackage } from "./check-package.mjs";
const require = createRequire(import.meta.url);
const { findLeaks, loadConfig } = require("../../apps/taro/config/mask-taro.cjs");
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
const timestamp = new Date().toISOString().replace(/\D/g, "").slice(0, 14);
const git = spawnSync("git", ["rev-parse", "--short=12", "HEAD"], { cwd: root, encoding: "utf8" });
@@ -19,6 +23,21 @@ function run(command, args) {
if (result.status !== 0) process.exit(result.status ?? 1);
}
/** 发布产物对外可下载,出现框架指纹即视为发布配置错误。 */
function assertNoStackFingerprint(directory) {
const config = loadConfig();
if (!config.enabled) return;
const leaks = findLeaks(path.join(root, directory), config);
if (!leaks.length) return;
throw new Error(
`${directory} 仍含技术栈指纹,请通过包内构建脚本产出:\n` +
leaks
.slice(0, 10)
.map((leak) => " - " + leak)
.join("\n"),
);
}
async function listFiles(directory, prefix = "") {
const files = [];
for (const entry of await readdir(directory, { withFileTypes: true })) {
@@ -142,6 +161,7 @@ async function main() {
}
run("pnpm", ["build:admin:preview"]);
assertNoStackFingerprint("apps/admin/dist");
run("pnpm", ["--filter", "@personal-brand/config", "build"]);
run("pnpm", ["--filter", "@personal-brand/types", "build"]);
run("pnpm", ["--filter", "@personal-brand/validation", "build"]);