docnest 0.1.5 → 0.1.7

package/README.md

@@ -89,6 +89,8 @@ startServer(3000)
 如果宿主项目需要生成静态站点，可使用 `docnest/attachments` 提供的
 `collectDocumentAttachmentPaths` 和 `copyDocumentAttachments`。它们只复制
 Markdown 或 HTML 中明确引用的本地附件，不按文件扩展名设置业务白名单；外链、文档链接、隐藏路径、路径穿越和代码块中的伪引用会被忽略，缺失的附件默认会让构建失败。
+常见凭据文件（如 `.env`、私钥和证书容器）属于公共安全阻断项，即使被误写进文档链接也不会进入静态产物。
+静态生成 HTML 时，可再调用 `rewriteDocumentAttachmentUrls`，将正文中的附件链接统一改写到 `/doc-asset/` 端点。
 
 ## 开发
 

package/dist/attachments.d.ts

@@ -5,7 +5,13 @@ export type DocumentAttachmentOptions = {
      */
     failOnMissing?: boolean;
 };
+export type DocumentAttachmentUrlOptions = {
+    assetPaths?: readonly string[];
+    assetPrefix?: string;
+};
 /** Collect every existing, explicitly referenced local document attachment. */
 export declare function collectDocumentAttachmentPaths(docsRoot: string, options?: DocumentAttachmentOptions): string[];
 /** Copy collected attachments while preserving their paths relative to docsRoot. */
 export declare function copyDocumentAttachments(sourceRoot: string, destinationRoot: string, options?: DocumentAttachmentOptions): string[];
+/** Rewrite rendered local attachment links to the static document asset endpoint. */
+export declare function rewriteDocumentAttachmentUrls(html: string, documentPath: string, options?: DocumentAttachmentUrlOptions): string;

package/dist/attachments.js

@@ -5,9 +5,27 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectDocumentAttachmentPaths = collectDocumentAttachmentPaths;
 exports.copyDocumentAttachments = copyDocumentAttachments;
+exports.rewriteDocumentAttachmentUrls = rewriteDocumentAttachmentUrls;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const MARKDOWN_SOURCE_EXTENSIONS = new Set(['.md', '.markdown']);
+const SENSITIVE_ATTACHMENT_EXTENSIONS = new Set([
+    '.env',
+    '.pem',
+    '.key',
+    '.p12',
+    '.pfx',
+    '.jks',
+    '.keystore',
+    '.secret',
+    '.secrets',
+]);
+const SENSITIVE_ATTACHMENT_NAMES = new Set([
+    'id_rsa',
+    'id_dsa',
+    'id_ecdsa',
+    'id_ed25519',
+]);
 const MARKDOWN_LINK_PATTERN = /!?\[[^\]]*\]\(\s*(?:<([^>\n]+)>|([^\s)]+))(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/g;
 const MARKDOWN_REFERENCE_PATTERN = /^\s{0,3}\[[^\]]+\]:\s*(?:<([^>\n]+)>|(\S+))/gm;
 const HTML_ASSET_PATTERN = /\b(?:src|href)=["']([^"']+)["']/gi;
@@ -33,6 +51,12 @@ function isLocalRelativeTarget(target) {
 function stripTargetSuffix(target) {
     return target.split(/[?#]/, 1)[0];
 }
+function isSensitiveAttachment(target) {
+    const baseName = node_path_1.default.basename(target).toLowerCase();
+    return SENSITIVE_ATTACHMENT_EXTENSIONS.has(node_path_1.default.extname(baseName))
+        || SENSITIVE_ATTACHMENT_NAMES.has(baseName)
+        || baseName.startsWith('.env.');
+}
 function extractTargets(markdown) {
     const source = markdown.replace(FENCED_CODE_PATTERN, '');
     const targets = [];
@@ -65,6 +89,8 @@ function resolveAttachmentPath(docsRoot, realDocsRoot, markdownPath, rawTarget,
     const extension = node_path_1.default.extname(decodedTarget).toLowerCase();
     if (MARKDOWN_SOURCE_EXTENSIONS.has(extension))
         return null;
+    if (isSensitiveAttachment(decodedTarget))
+        return null;
     const resolved = node_path_1.default.resolve(docsRoot, node_path_1.default.dirname(markdownPath), decodedTarget);
     const relative = node_path_1.default.relative(docsRoot, resolved);
     if (!relative || node_path_1.default.isAbsolute(relative) || relative === '..' || relative.startsWith(`..${node_path_1.default.sep}`)) {
@@ -121,3 +147,36 @@ function copyDocumentAttachments(sourceRoot, destinationRoot, options = {}) {
     }
     return attachmentPaths;
 }
+function encodeAssetPath(assetPath) {
+    return assetPath.split('/').map((segment) => encodeURIComponent(segment)).join('/');
+}
+/** Rewrite rendered local attachment links to the static document asset endpoint. */
+function rewriteDocumentAttachmentUrls(html, documentPath, options = {}) {
+    const assetPrefix = (options.assetPrefix || '/doc-asset').replace(/\/+$/, '');
+    const assetPaths = options.assetPaths ? new Set(options.assetPaths) : null;
+    const documentDir = node_path_1.default.posix.dirname(documentPath.replace(/\\/g, '/'));
+    const attributePattern = /(<(?:a|audio|embed|iframe|img|object|source|video)\b[^>]*\s(?:href|src)=["'])([^"']+)(["'])/gi;
+    return html.replace(attributePattern, (match, prefix, rawTarget, suffix) => {
+        if (!rawTarget || /^(?:[a-z][a-z0-9+.-]*:|\/\/|#|\/|data:)/i.test(rawTarget))
+            return match;
+        const targetWithoutSuffix = stripTargetSuffix(rawTarget);
+        let decodedTarget;
+        try {
+            decodedTarget = decodeURIComponent(targetWithoutSuffix);
+        }
+        catch {
+            return match;
+        }
+        if (!decodedTarget || MARKDOWN_SOURCE_EXTENSIONS.has(node_path_1.default.extname(decodedTarget).toLowerCase())) {
+            return match;
+        }
+        const resolved = node_path_1.default.posix.normalize(node_path_1.default.posix.join(documentDir, decodedTarget));
+        if (!resolved || resolved === '..' || resolved.startsWith('../') || resolved.startsWith('.'))
+            return match;
+        if (assetPaths && !assetPaths.has(resolved))
+            return match;
+        const suffixStart = targetWithoutSuffix.length;
+        const queryAndHash = rawTarget.slice(suffixStart);
+        return `${prefix}${assetPrefix}/${encodeAssetPath(resolved)}${queryAndHash}${suffix}`;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docnest",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "可复用的本地 Markdown 文档中心",
   "repository": {
     "type": "git",