Skip to content

An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作

10.0 KB
Raw Blame
// SiYuan - https://github.com/siyuan-note/siyuan
// Copyright (c) 2020-present, b3log.org
// SPDX-License-Identifier: AGPL-3.0-or-later

package model

import (
	"crypto/sha256"
	"errors"
	"fmt"
	"io/fs"
	"os"
	"path"
	"path/filepath"
	"strings"
	"sync"
	"unicode"
	"unicode/utf8"

	"github.com/88250/lute/ast"
	"github.com/88250/lute/parse"
	"github.com/siyuan-note/filelock"
	"github.com/siyuan-note/siyuan/kernel/util"
)

var templateFileLock sync.Mutex

const maxTemplateSourceSize = 8 * 1024 * 1024

type TemplateFileRequest struct {
	Action   string `json:"action"`
	Path     string `json:"path"`
	Target   string `json:"target"`
	Content  string `json:"content"`
	Revision string `json:"revision"`
}

type TemplateFileEntry struct {
	Path      string `json:"path"`
	IsDir     bool   `json:"isDir"`
	IsPackage bool   `json:"isPackage,omitempty"`
}

// 访问已有模板只校验目录边界,不对文件名进行清理或改写。
func validateTemplateRelativePath(p string, allowRoot bool) error {
	if p == "" && allowRoot {
		return nil
	}
	if p == "" || !fs.ValidPath(p) || strings.ContainsAny(p, "\\:\x00") {
		return errors.New("invalid template path")
	}
	for part := range strings.SplitSeq(p, "/") {
		if strings.HasPrefix(part, ".") {
			return errors.New("hidden template paths are reserved")
		}
	}
	return nil
}

// 新名称保持跨平台可用,已有父目录沿用原名。
func validateNewTemplateName(p string) error {
	part := path.Base(p)
	device := strings.ToUpper(strings.SplitN(part, ".", 2)[0])
	if device == "CON" || device == "PRN" || device == "AUX" || device == "NUL" || (len(device) == 4 && (strings.HasPrefix(device, "COM") || strings.HasPrefix(device, "LPT")) && device[3] >= '1' && device[3] <= '9') {
		return errors.New("reserved template file name")
	}
	if strings.HasPrefix(part, ".") || strings.TrimSpace(part) != part || strings.HasSuffix(part, ".") || strings.ContainsAny(part, "\\:<>\"|?*") || strings.ContainsFunc(part, unicode.IsControl) {
		return errors.New("invalid template path component")
	}
	return nil
}

// 清单与目录共同标识模板包,保留目录身份以维持搜索和集市更新。
func isManagedTemplatePackage(root *os.Root, p string) bool {
	_, err := root.Lstat(path.Join(p, "template.json"))
	return err == nil
}

func openTemplateRoot() (*os.Root, error) {
	if err := os.MkdirAll(filepath.Join(util.DataDir, "templates"), 0755); err != nil {
		return nil, err
	}
	return os.OpenRoot(filepath.Join(util.DataDir, "templates"))
}

// 除根目录外不接受符号链接,避免管理操作影响另一个模板包。
func checkTemplateFilePath(root *os.Root, p string) error {
	if err := validateTemplateRelativePath(p, false); err != nil {
		return err
	}
	parts := strings.Split(p, "/")
	for i := range parts {
		info, err := root.Lstat(strings.Join(parts[:i+1], "/"))
		if errors.Is(err, os.ErrNotExist) && i == len(parts)-1 {
			return nil
		}
		if err != nil {
			return err
		}
		if info.Mode()&os.ModeSymlink != 0 || (!info.IsDir() && !info.Mode().IsRegular()) {
			return errors.New("template path is not a regular file or directory")
		}
	}
	return nil
}

func templateFileRevision(root *os.Root, p string) (string, error) {
	info, err := root.Stat(p)
	if err != nil {
		return "", err
	}
	h := sha256.New()
	if info.IsDir() {
		err = fs.WalkDir(root.FS(), p, func(name string, entry fs.DirEntry, walkErr error) error {
			if walkErr != nil {
				return walkErr
			}
			stat, statErr := entry.Info()
			if statErr != nil {
				return statErr
			}
			if stat.Mode()&os.ModeSymlink != 0 {
				return errors.New("template directory contains a symbolic link")
			}
			fmt.Fprintf(h, "%s\x00%d\x00%d\x00%d\n", name, stat.Size(), stat.ModTime().UnixNano(), stat.Mode())
			return nil
		})
	} else {
		if info.Size() > maxTemplateSourceSize {
			return "", errors.New("template source is too large")
		}
		var content []byte
		content, err = root.ReadFile(p)
		h.Write(content)
	}
	return fmt.Sprintf("%x", h.Sum(nil)), err
}

func readTemplateSource(root *os.Root, p string) (string, error) {
	info, err := root.Stat(p)
	if err != nil {
		return "", err
	}
	if !info.Mode().IsRegular() || info.Size() > maxTemplateSourceSize {
		return "", errors.New("invalid template source file")
	}
	content, err := root.ReadFile(p)
	if err != nil {
		return "", err
	}
	if !utf8.Valid(content) {
		return "", errors.New("template source is not UTF-8")
	}
	return string(content), nil
}

// 从源码的文档级属性读取导出来源,不执行模板动作,也不使用解析器生成的 ID。
func templateSourceDocumentID(content string) string {
	engine := util.NewLute()
	engine.SetKramdownBlockIAL(false)
	engine.SetIndentCodeBlock(true)
	tree := parse.Block("", []byte(content), engine.ParseOptions)
	if tree == nil || tree.Root.LastChild == nil || tree.Root.LastChild.Type != ast.NodeParagraph {
		return ""
	}
	// 导出器把文档属性写在末尾;单独解析属性,保留任意属性顺序并拒绝动态或无效 ID。
	attrs := parseTemplateDocumentAttributes(strings.TrimSpace(string(tree.Root.LastChild.Tokens)))
	id := parse.IAL2Map(attrs)["id"]
	if !ast.IsNodeIDPattern(id) {
		return ""
	}
	return id
}

// 同目录临时文件写入完成后替换,写入失败时保留原模板。
func writeTemplateSource(root *os.Root, p, content string, create bool) error {
	if !utf8.ValidString(content) {
		return errors.New("invalid template source")
	}
	if create {
		file, err := root.OpenFile(p, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644)
		if err != nil {
			return err
		}
		_, err = file.WriteString(content)
		if err == nil {
			err = file.Sync()
		}
		closeErr := file.Close()
		if err != nil {
			root.Remove(p)
			return err
		}
		return closeErr
	}
	tmp := path.Join(path.Dir(p), ".template-"+ast.NewNodeID())
	file, err := root.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644)
	if err != nil {
		return err
	}
	defer root.Remove(tmp)
	_, err = file.WriteString(content)
	if err == nil {
		err = file.Sync()
	}
	closeErr := file.Close()
	if err != nil {
		return err
	}
	if closeErr != nil {
		return closeErr
	}
	return root.Rename(tmp, p)
}

func ManageTemplateFiles(request TemplateFileRequest) (ret any, err error) {
	templateFileLock.Lock()
	defer templateFileLock.Unlock()
	root, err := openTemplateRoot()
	if err != nil {
		return nil, err
	}
	defer root.Close()
	if request.Action == "list" {
		entries := []TemplateFileEntry{}
		err = fs.WalkDir(root.FS(), ".", func(p string, entry fs.DirEntry, walkErr error) error {
			if walkErr != nil {
				return walkErr
			}
			if p == "." {
				return nil
			}
			if strings.HasPrefix(entry.Name(), ".") || entry.Type()&os.ModeSymlink != 0 {
				if entry.IsDir() {
					return fs.SkipDir
				}
				return nil
			}
			if entry.IsDir() || strings.EqualFold(path.Ext(p), ".md") {
				entries = append(entries, TemplateFileEntry{Path: p, IsDir: entry.IsDir(), IsPackage: entry.IsDir() && isManagedTemplatePackage(root, p)})
			}
			return nil
		})
		return entries, err
	}
	if err = checkTemplateFilePath(root, request.Path); err != nil {
		return nil, err
	}
	abs := filepath.Join(root.Name(), filepath.FromSlash(request.Path))
	filelock.Lock(abs)
	defer filelock.Unlock(abs)
	info, statErr := root.Stat(request.Path)
	if request.Action == "mkdir" {
		if err = validateNewTemplateName(request.Path); err != nil {
			return nil, err
		}
		return nil, root.Mkdir(request.Path, 0755)
	}
	if statErr != nil && !(request.Action == "write" && request.Revision == "" && errors.Is(statErr, os.ErrNotExist)) {
		return nil, statErr
	}
	if info == nil || !info.IsDir() {
		if !strings.EqualFold(path.Ext(request.Path), ".md") {
			return nil, errors.New("template source must use the .md extension")
		}
	}
	if request.Action == "read" {
		if info.IsDir() {
			revision, readErr := templateFileRevision(root, request.Path)
			return map[string]string{"content": "", "revision": revision}, readErr
		}
		content, readErr := readTemplateSource(root, request.Path)
		if readErr != nil {
			return nil, readErr
		}
		ret := map[string]string{"content": content, "revision": fmt.Sprintf("%x", sha256.Sum256([]byte(content))), "path": filepath.Join(util.DataDir, "templates", filepath.FromSlash(request.Path))}
		if id := templateSourceDocumentID(content); id != "" {
			ret["sourceDocID"] = id
		}
		return ret, nil
	}
	if info != nil {
		revision, revisionErr := templateFileRevision(root, request.Path)
		if revisionErr != nil {
			return nil, revisionErr
		}
		if request.Revision == "" || request.Revision != revision {
			return nil, errors.New("template changed; reload it before saving, moving or deleting")
		}
	}
	switch request.Action {
	case "write":
		if info == nil {
			if err = validateNewTemplateName(request.Path); err != nil {
				return nil, err
			}
		}
		if len(request.Content) > maxTemplateSourceSize {
			return nil, errors.New("template source is too large")
		}
		if info != nil && info.IsDir() {
			return nil, errors.New("cannot write a template directory")
		}
		err = writeTemplateSource(root, request.Path, request.Content, info == nil)
		return map[string]string{"revision": fmt.Sprintf("%x", sha256.Sum256([]byte(request.Content)))}, err
	case "move":
		if info.IsDir() && isManagedTemplatePackage(root, request.Path) {
			return nil, errors.New("template packages cannot be renamed or moved")
		}
		if err = checkTemplateFilePath(root, request.Target); err != nil {
			return nil, err
		}
		if err = validateNewTemplateName(request.Target); err != nil {
			return nil, err
		}
		if !info.IsDir() && !strings.EqualFold(path.Ext(request.Target), ".md") {
			return nil, errors.New("template source must use the .md extension")
		}
		if _, err = root.Stat(request.Target); !errors.Is(err, os.ErrNotExist) {
			return nil, errors.New("template destination already exists or is inaccessible")
		}
		return nil, root.Rename(request.Path, request.Target)
	case "remove":
		// 路径边界和版本校验完成后,直接删除选中项目及其内容。
		if info.IsDir() {
			return nil, root.RemoveAll(request.Path)
		}
		return nil, root.Remove(request.Path)
	default:
		return nil, errors.New("unsupported template operation")
	}
}