Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions apps/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ pnpm docs:preview

English pages live at the documentation root. Every user-facing page has a matching Chinese page under `zh-CN`. `pnpm docs:check` verifies this route parity before building the site.

The check also validates the security-patched Markdown parser through VitePress's actual renderer. The local integration patch and its removal criteria are documented in [Dependency patches](../../patches/README.md).

The generated `.vitepress/dist` directory is local build output and must not be edited or committed. Publishing the site, configuring `d.i0c.cc`, or changing DNS remains a separate external operation.

## Vercel deployment
Expand Down
2 changes: 2 additions & 0 deletions apps/docs/README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ pnpm docs:preview

生成的 `.vitepress/dist` 属于本地构建产物,不应直接编辑或提交。发布站点、配置 `d.i0c.cc` 或修改 DNS 均属于独立的外部操作。

该检查还通过 VitePress 实际渲染器验证已修补的 Markdown 解析器。本地集成补丁及其移除条件见[依赖补丁说明](../../patches/README.md)。

## Vercel 部署

创建独立的 Vercel 项目,并把 Root Directory 设为 `apps/docs`。仓库内的 [vercel.json](vercel.json) 使用 Corepack 管理的 pnpm 从仓库根安装工作区、执行 `corepack pnpm build`,并发布 `.vitepress/dist`。文档站不需要在仓库根目录放置 Vercel 配置。
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"scripts": {
"assets:check": "corepack pnpm --dir ../.. assets:check",
"dev": "corepack pnpm assets:check && vitepress dev .",
"check": "corepack pnpm assets:check && node scripts/check-locales.mjs && vitepress build .",
"check": "corepack pnpm assets:check && node scripts/check-locales.mjs && node --test scripts/markdown-security.test.mjs && vitepress build .",
"build": "corepack pnpm assets:check && vitepress build .",
"preview": "vitepress preview ."
},
Expand Down
92 changes: 92 additions & 0 deletions apps/docs/scripts/markdown-security.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
import assert from "node:assert/strict"
import { createRequire } from "node:module"
import path from "node:path"
import test from "node:test"
import { fileURLToPath, pathToFileURL } from "node:url"
import { isMainThread, parentPort, Worker, workerData } from "node:worker_threads"

const docsRoot = fileURLToPath(new URL("../", import.meta.url))

if (!isMainThread) {
const require = createRequire(import.meta.url)
const requireFromVitePress = createRequire(require.resolve("vitepress"))
const packagePath = requireFromVitePress.resolve("markdown-it/package.json")
assert.equal(requireFromVitePress("markdown-it/package.json").version, "14.3.3")
const { default: MarkdownIt } = await import(
pathToFileURL(path.join(path.dirname(packagePath), "index.mjs")).href
)
const { createMarkdownRenderer } = await import("vitepress")
const md = await createMarkdownRenderer(docsRoot, {
typographer: true,
highlight: (code) => code,
})
assert.equal(md.constructor, MarkdownIt, "VitePress must use the patched parser")
parentPort.postMessage(md.render(workerData))
} else {
function render(markdown) {
return new Promise((resolve, reject) => {
const worker = new Worker(new URL(import.meta.url), {
workerData: markdown,
resourceLimits: { maxOldGenerationSizeMb: 256 },
})
const timer = setTimeout(() => {
void worker.terminate()
reject(new Error("VitePress rendering exceeded the 15 second limit"))
}, 15_000)
worker.once("message", (html) => {
clearTimeout(timer)
resolve(html)
})
worker.once("error", (error) => {
clearTimeout(timer)
reject(error)
})
worker.once("exit", (code) => {
clearTimeout(timer)
if (code !== 0) reject(new Error(`Markdown worker exited with ${code}`))
})
})
}

test("VitePress preserves its plugins with the external security-patched parser", async () => {
const html = await render([
"# Nami 文档",
"",
"::: tip",
"**English** and 中文 with [reference][guide].",
":::",
"",
"| Runtime | 状态 |",
"| --- | --- |",
"| Cloudflare | Ready |",
"",
"`inline code` and <span>HTML</span>.",
"",
"[guide]: https://example.com/guide",
].join("\n"))
assert.match(html, /header-anchor/)
assert.match(html, /Nami 文档/)
assert.match(html, /tip custom-block/)
assert.match(html, /<strong>English<\/strong>/)
assert.match(html, /<table tabindex="0">/)
assert.match(html, /href="https:\/\/example\.com\/guide"/)
assert.match(html, /<code>inline code<\/code>/)
assert.match(html, /<span>HTML<\/span>/)
})

// Adapted from markdown-it's MIT-licensed 14.3.3 pathological tests:
// https://github.com/markdown-it/markdown-it/blob/14.3.3/test/markdown-it/pathological.test.mjs
const pathologicalCases = [
["unclosed inline HTML", "<b></" + "<!--".repeat(30_000)],
["multiline reference title", '[a]: /u "' + "x\n".repeat(60_000) + '"'],
["linkified soft breaks", "ping a@b.co ok\n".repeat(10_000)],
["unregistered link schemes", "a://".repeat(30_000)],
["long quote run", '"'.repeat(60_000)],
["mismatched smart quotes", '"a '.repeat(30_000) + "b' ".repeat(30_000)],
]
for (const [name, markdown] of pathologicalCases) {
test(`VitePress bounds ${name}`, async () => {
assert.equal(typeof await render(markdown), "string")
})
}
}
4 changes: 2 additions & 2 deletions apps/webui/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
"@visx/tooltip": "^4.0.0",
"ajv": "^8.18.0",
"ajv-formats": "^3.0.1",
"next": "16.3.8",
"next": "16.4.1",
"next-auth": "^4.24.15",
"next-intl": "^4.9.2",
"qrcode.react": "^4.2.0",
Expand All @@ -55,7 +55,7 @@
"@types/react-dom": "^19",
"babel-plugin-react-compiler": "1.0.0",
"eslint": "^9",
"eslint-config-next": "16.3.8",
"eslint-config-next": "16.4.1",
"tailwindcss": "^4",
"tsx": "^4.21.0",
"typescript": "^5"
Expand Down
23 changes: 21 additions & 2 deletions patches/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,22 @@
# Dependency patches

## VitePress 1.6.4

`vitepress@1.6.4.patch` makes the VitePress Markdown renderer use the separately
resolved `markdown-it@14.3.3` package instead of its bundled 14.1.0 parser. The
workspace package extension supplies this exact dependency. VitePress plugins and
renderer options are still applied by its original renderer factory.

The bundled parser is invisible to lockfile audits. The external 14.3.3 release
contains the upstream fixes for GHSA-38c4-r59v-3vqw, GHSA-6v5v-wf23-fmfq,
GHSA-253c-mchw-3w2r, GHSA-r7fv-28h4-cvq7, GHSA-vfgh-jcmw-g37q, and
GHSA-gfr2-rv44-r23c. This is a local integration patch, not a VitePress release.

`pnpm docs:check` verifies the actual VitePress renderer uses that external parser,
checks bilingual headings, links, tables, containers and inline HTML, runs bounded
adversarial-input regressions, and builds all documentation. Remove this patch only
after an upstream VitePress release supplies a fixed parser and these checks pass.

## braces 3.0.3

`braces@3.0.3.patch` is a local mitigation for
Expand All @@ -17,5 +34,7 @@ boundary inputs, escaped/quoted delimiters, direct ASTs, ranges, and resource-bo
malicious inputs. The regression script can additionally compare against a pristine
3.0.3 package passed as its second directory argument.

The advisory remains visible in raw audits. Remove this local patch only after a
verified upstream fix is available and the same regression tests pass.
The advisory was withdrawn on 2026-10-23 as not practically exploitable, so the
2026-10-24 raw audit no longer reports it. This is an advisory-feed change, not an
upstream code fix. Retain the local hardening and its regression tests until a
separately reviewed upstream change makes it unnecessary.
12 changes: 12 additions & 0 deletions patches/vitepress@1.6.4.patch
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
diff --git a/dist/node/chunk-D3CUZ4fa.js b/dist/node/chunk-D3CUZ4fa.js
--- a/dist/node/chunk-D3CUZ4fa.js
+++ b/dist/node/chunk-D3CUZ4fa.js
@@ -1,2 +1,3 @@
import { webcrypto, createHash } from 'node:crypto';
+import PatchedMarkdownIt from 'markdown-it';
import { createRequire } from 'node:module';
@@ -35722,3 +35723,3 @@
_disposeHighlighter = dispose;
- md = MarkdownIt({ html: true, linkify: true, highlight: highlight$1, ...options });
+ md = PatchedMarkdownIt({ html: true, linkify: true, highlight: highlight$1, ...options });
md.linkify.set({ fuzzyLink: false });
Loading
Loading