Skip to content

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

5.6 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 tools

import (
	"archive/zip"
	"fmt"
	"os"
	"path/filepath"
	"strings"
	"unicode/utf8"

	"github.com/siyuan-note/siyuan/kernel/util"

	"github.com/88250/gulu"
	"golang.org/x/text/encoding/simplifiedchinese"
)

// UnzipTool 提供工作区内 zip 文件解压能力。
// zipPath 和 destPath 均为工作区相对路径,通过 resolvePath 校验防逃逸;解压时对每个成员的最终
// 输出路径再做一次授权,防止成员覆盖敏感文件。
// 解压是写操作,自动触发 UI 确认和仓库快照(不在 safeActions 中)。
var UnzipTool = &Tool{
	Name:        "unzip",
	Description: "Extract a zip archive within the workspace. Provide the workspace-relative path to the zip file and the destination directory (also workspace-relative). The destination will be created if it does not exist.",
	InputSchema: ToolSchema{
		Type: "object",
		Properties: map[string]Property{
			"zipPath": {
				Type:        "string",
				Description: "Workspace-relative path to the .zip file to extract.",
			},
			"destPath": {
				Type:        "string",
				Description: "Workspace-relative destination directory to extract into.",
			},
		},
		Required: []string{"zipPath", "destPath"},
	},
	Handler: unzipHandler,
}

func init() {
	register(UnzipTool)
}

func unzipHandler(args map[string]any) (CallToolResult, error) {
	zipPath, _ := args["zipPath"].(string)
	destPath, _ := args["destPath"].(string)
	if zipPath == "" {
		return CallToolResult{Content: []ContentItem{{Type: "text", Text: "zipPath is required"}}, IsError: true}, nil
	}
	if destPath == "" {
		return CallToolResult{Content: []ContentItem{{Type: "text", Text: "destPath is required"}}, IsError: true}, nil
	}

	// 解析并校验路径在工作区内(防逃逸),复用 file 工具的 resolvePath。
	zipAbs, err := resolvePath(zipPath)
	if err != nil {
		return CallToolResult{Content: []ContentItem{{Type: "text", Text: "invalid zipPath: " + err.Error()}}, IsError: true}, nil
	}
	destAbs, err := resolvePath(destPath)
	if err != nil {
		return CallToolResult{Content: []ContentItem{{Type: "text", Text: "invalid destPath: " + err.Error()}}, IsError: true}, nil
	}

	// 检查 zip 文件存在。
	if !gulu.File.IsExist(zipAbs) {
		return CallToolResult{Content: []ContentItem{{Type: "text", Text: "zip file not found: " + zipPath}}, IsError: true}, nil
	}

	// 解压(与 /api/archive/unzip 一致:先校验全部条目的最终路径,再从同一个归档句柄解压)。
	// 不能直接使用 gulu.Zip.Unzip:它只做词法包含检查,无法对每个成员做授权,成员可以覆盖敏感文件。
	if err := extractGuardedArchive(zipAbs, destAbs); err != nil {
		return CallToolResult{Content: []ContentItem{{Type: "text", Text: "unzip failed: " + err.Error()}}, IsError: true}, nil
	}

	return CallToolResult{
		Content: []ContentItem{{Type: "text", Text: fmt.Sprintf("Extracted %s to %s", zipPath, destPath)}},
	}, nil
}

// extractGuardedArchive 校验归档全部条目后再从同一句柄解压:拒绝非本地路径名、路径穿越和符号链接条目,
// 并对每个最终输出路径做授权,防止成员覆盖受保护文件(例如成员 conf.json 解压到 conf 目录)。
func extractGuardedArchive(zipAbs, destAbs string) error {
	reader, err := zip.OpenReader(zipAbs)
	if err != nil {
		return err
	}
	defer reader.Close()

	// 成员名与其最终输出路径成对保存,两次遍历使用同一份判定输入
	type archiveMember struct {
		name string
		path string
	}
	members := make([]archiveMember, len(reader.File))
	for i, entry := range reader.File {
		name := entry.Name
		if !utf8.ValidString(name) {
			// 与 Gulu 一致地解码 GB18030 条目名,避免解码前后的名称不一致导致校验被绕过
			if name, err = simplifiedchinese.GB18030.NewDecoder().String(name); err != nil {
				return err
			}
		}
		name = strings.ReplaceAll(name, "\\", "/")
		if !filepath.IsLocal(filepath.FromSlash(name)) || entry.Mode()&os.ModeSymlink != 0 {
			return fmt.Errorf("invalid archive entry [%s]", name)
		}
		members[i] = archiveMember{name: name, path: filepath.Join(destAbs, filepath.FromSlash(name))}
		if err = authorizeArchiveEntry(destAbs, members[i].path, members[i].name); err != nil {
			return err
		}
	}
	for i, entry := range reader.File {
		// 解压前再次授权,不复用预检阶段的判定结果
		if err = authorizeArchiveEntry(destAbs, members[i].path, members[i].name); err != nil {
			return err
		}
		if err = util.ExtractArchiveEntry(entry, members[i].path); err != nil {
			return err
		}
	}
	return nil
}

// authorizeArchiveEntry 校验归档成员的最终输出路径:必须位于目标目录内(含符号链接解析后),
// 且通过最终路径授权(工作区包含、加密笔记本、symlink 逃逸、敏感文件黑名单)。
func authorizeArchiveEntry(destAbs, entryAbs, display string) error {
	if util.IsPluginDevelopmentRawWriteForbidden(entryAbs) {
		return fmt.Errorf("managed plugin development output cannot be overwritten: %s", display)
	}
	rel, err := filepath.Rel(destAbs, entryAbs)
	if err != nil || !filepath.IsLocal(rel) {
		return fmt.Errorf("archive entry escapes destination [%s]", display)
	}
	resolved := util.ResolveLongestExistingParent(entryAbs)
	resolvedDest := util.ResolveLongestExistingParent(destAbs)
	if rel, err = filepath.Rel(resolvedDest, resolved); err != nil || !filepath.IsLocal(rel) {
		return fmt.Errorf("archive entry resolves outside destination [%s]", display)
	}
	return authorizePath(entryAbs, display)
}