@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/storage/storage.go

@@ -0,0 +1,268 @@
+package storage
+
+import (
+	"context"
+	"io"
+	"time"
+)
+
+// ===============================================================
+// Provider 接口
+// ===============================================================
+
+// Provider 云存储 Provider 接口
+//
+// 所有存储操作的统一抽象。S3 兼容协议覆盖 AWS S3 / Cloudflare R2 / MinIO。
+type Provider interface {
+	// GeneratePresignedUploadURL 生成预签名上传 URL
+	GeneratePresignedUploadURL(ctx context.Context, params PresignUploadParams) (*PresignUploadResult, error)
+	// GeneratePresignedDownloadURL 生成预签名下载 URL
+	GeneratePresignedDownloadURL(ctx context.Context, params PresignDownloadParams) (*PresignDownloadResult, error)
+	// Upload 服务端直接上传（小文件代理）
+	Upload(ctx context.Context, params UploadParams) (*UploadResult, error)
+	// Delete 删除对象
+	Delete(ctx context.Context, params DeleteParams) error
+	// HeadObject 获取对象元数据
+	HeadObject(ctx context.Context, params HeadObjectParams) (*ObjectMetadata, error)
+	// InitiateMultipartUpload 发起分片上传
+	InitiateMultipartUpload(ctx context.Context, params InitiateMultipartParams) (*InitiateMultipartResult, error)
+	// GeneratePartPresignedURL 生成分片预签名上传 URL
+	GeneratePartPresignedURL(ctx context.Context, params PresignPartParams) (*PresignPartResult, error)
+	// CompleteMultipartUpload 完成分片上传
+	CompleteMultipartUpload(ctx context.Context, params CompleteMultipartParams) (*CompleteMultipartResult, error)
+	// AbortMultipartUpload 取消分片上传
+	AbortMultipartUpload(ctx context.Context, params AbortMultipartParams) error
+	// Download 服务端直接下载对象内容（用于 Worker 等持有凭证的场景）
+	Download(ctx context.Context, params DownloadParams) (*DownloadResult, error)
+}
+
+// ImmutableObjectProvider 为内容寻址对象提供原子 create-only 写入能力。
+//
+// created=false 表示对象已存在，调用方必须验证已有对象后复用，禁止覆盖或删除。
+type ImmutableObjectProvider interface {
+	UploadIfAbsent(ctx context.Context, params UploadParams) (result *UploadResult, created bool, err error)
+}
+
+// ===============================================================
+// 预签名上传
+// ===============================================================
+
+// PresignUploadParams 预签名上传请求参数
+type PresignUploadParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+	// 文件 MIME 类型
+	ContentType string
+	// 最大文件大小（字节）
+	MaxFileSize int64
+	// 预签名 URL 有效期
+	ExpiresIn time.Duration
+	// 自定义元数据
+	Metadata map[string]string
+}
+
+// PresignUploadResult 预签名上传返回结果
+type PresignUploadResult struct {
+	// 预签名上传 URL
+	URL string
+	// 上传时需要附带的请求头
+	Headers map[string]string
+	// URL 过期时间
+	ExpiresAt time.Time
+}
+
+// ===============================================================
+// 预签名下载
+// ===============================================================
+
+// PresignDownloadParams 预签名下载请求参数
+type PresignDownloadParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+	// 预签名 URL 有效期
+	ExpiresIn time.Duration
+	// 下载文件名（触发浏览器下载时使用）
+	DownloadFilename string
+}
+
+// PresignDownloadResult 预签名下载返回结果
+type PresignDownloadResult struct {
+	// 预签名下载 URL
+	URL string
+	// URL 过期时间
+	ExpiresAt time.Time
+}
+
+// ===============================================================
+// 服务端上传
+// ===============================================================
+
+// UploadParams 服务端上传请求参数
+type UploadParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+	// 文件内容读取流
+	Body io.Reader
+	// 文件 MIME 类型
+	ContentType string
+	// 文件大小（字节）
+	Size int64
+	// 自定义元数据
+	Metadata map[string]string
+}
+
+// UploadResult 服务端上传返回结果
+type UploadResult struct {
+	// 对象 ETag
+	ETag string
+	// 对象访问地址
+	Location string
+}
+
+// ===============================================================
+// 删除
+// ===============================================================
+
+// DeleteParams 删除对象请求参数
+type DeleteParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+}
+
+// ===============================================================
+// 元数据查询
+// ===============================================================
+
+// HeadObjectParams 获取对象元数据请求参数
+type HeadObjectParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+}
+
+// ObjectMetadata 对象元数据
+type ObjectMetadata struct {
+	// 文件 MIME 类型
+	ContentType string
+	// 文件大小（字节）
+	ContentLength int64
+	// 对象 ETag
+	ETag string
+	// 最后修改时间
+	LastModified time.Time
+	// 自定义元数据
+	Metadata map[string]string
+}
+
+// ===============================================================
+// 分片上传
+// ===============================================================
+
+// InitiateMultipartParams 发起分片上传请求参数
+type InitiateMultipartParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+	// 文件 MIME 类型
+	ContentType string
+	// 自定义元数据
+	Metadata map[string]string
+}
+
+// InitiateMultipartResult 发起分片上传返回结果
+type InitiateMultipartResult struct {
+	// 分片上传 ID
+	UploadID string
+}
+
+// PresignPartParams 生成分片预签名上传 URL 请求参数
+type PresignPartParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+	// 分片上传 ID
+	UploadID string
+	// 分片编号（从 1 开始）
+	PartNumber int32
+	// 预签名 URL 有效期
+	ExpiresIn time.Duration
+}
+
+// PresignPartResult 分片预签名上传 URL 返回结果
+type PresignPartResult struct {
+	// 预签名上传 URL
+	URL string
+	// URL 过期时间
+	ExpiresAt time.Time
+}
+
+// CompletedPart 已完成的分片信息
+type CompletedPart struct {
+	// 分片编号
+	PartNumber int32
+	// 分片 ETag
+	ETag string
+}
+
+// CompleteMultipartParams 完成分片上传请求参数
+type CompleteMultipartParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+	// 分片上传 ID
+	UploadID string
+	// 已上传的分片列表
+	Parts []CompletedPart
+}
+
+// CompleteMultipartResult 完成分片上传返回结果
+type CompleteMultipartResult struct {
+	// 合并后对象的 ETag
+	ETag string
+	// 对象访问地址
+	Location string
+}
+
+// AbortMultipartParams 取消分片上传请求参数
+type AbortMultipartParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+	// 分片上传 ID
+	UploadID string
+}
+
+// ===============================================================
+// 服务端下载
+// ===============================================================
+
+// DownloadParams 服务端下载请求参数
+type DownloadParams struct {
+	// 存储桶名称
+	Bucket string
+	// 对象键
+	Key string
+}
+
+// DownloadResult 服务端下载返回结果
+type DownloadResult struct {
+	// 文件内容
+	Body io.ReadCloser
+	// 文件 MIME 类型
+	ContentType string
+	// 文件大小（字节）
+	ContentLength int64
+}

package/dist/resources/templates/go-backend/internal/core/storage/validation.go

@@ -0,0 +1,225 @@
+package storage
+
+import (
+	"fmt"
+	"net/http"
+	"path/filepath"
+	"slices"
+	"strings"
+	"unicode"
+)
+
+// ===============================================================
+// 校验配置
+// ===============================================================
+
+// ValidationConfig 文件校验配置
+type ValidationConfig struct {
+	// 允许的 MIME 类型列表（空 = 使用默认白名单）
+	AllowedMimeTypes []string
+	// 最大文件大小（字节）
+	MaxFileSize int64
+}
+
+// 默认允许的 MIME 类型白名单
+var defaultAllowedMimeTypes = []string{
+	// 图片
+	"image/jpeg",
+	"image/png",
+	"image/gif",
+	"image/webp",
+	"image/svg+xml",
+	"image/bmp",
+	"image/tiff",
+	// 文档
+	"application/pdf",
+	"application/msword",
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+	"application/vnd.ms-excel",
+	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+	"application/vnd.ms-powerpoint",
+	"application/vnd.openxmlformats-officedocument.presentationml.presentation",
+	// 文本
+	"text/plain",
+	"text/csv",
+	"text/html",
+	"text/markdown",
+	"application/json",
+	"application/xml",
+	// 音频
+	"audio/mpeg",
+	"audio/wav",
+	"audio/ogg",
+	"audio/webm",
+	"audio/aac",
+	// 视频
+	"video/mp4",
+	"video/webm",
+	"video/ogg",
+	"video/quicktime",
+	// 压缩包
+	"application/zip",
+	"application/gzip",
+	"application/x-tar",
+	"application/x-7z-compressed",
+	"application/x-rar-compressed",
+}
+
+// MIME 类型到常见扩展名的映射
+var mimeToExtensions = map[string][]string{
+	"image/jpeg":         {".jpg", ".jpeg"},
+	"image/png":          {".png"},
+	"image/gif":          {".gif"},
+	"image/webp":         {".webp"},
+	"image/svg+xml":      {".svg"},
+	"image/bmp":          {".bmp"},
+	"image/tiff":         {".tif", ".tiff"},
+	"application/pdf":    {".pdf"},
+	"application/msword": {".doc"},
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.document": {".docx"},
+	"application/vnd.ms-excel": {".xls"},
+	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":         {".xlsx"},
+	"application/vnd.ms-powerpoint":                                             {".ppt"},
+	"application/vnd.openxmlformats-officedocument.presentationml.presentation": {".pptx"},
+	"text/plain":                   {".txt", ".log"},
+	"text/csv":                     {".csv"},
+	"text/html":                    {".html", ".htm"},
+	"text/markdown":                {".md", ".markdown"},
+	"application/json":             {".json"},
+	"application/xml":              {".xml"},
+	"audio/mpeg":                   {".mp3"},
+	"audio/wav":                    {".wav"},
+	"audio/ogg":                    {".ogg"},
+	"audio/webm":                   {".weba"},
+	"audio/aac":                    {".aac"},
+	"video/mp4":                    {".mp4"},
+	"video/webm":                   {".webm"},
+	"video/ogg":                    {".ogv"},
+	"video/quicktime":              {".mov"},
+	"application/zip":              {".zip"},
+	"application/gzip":             {".gz"},
+	"application/x-tar":            {".tar"},
+	"application/x-7z-compressed":  {".7z"},
+	"application/x-rar-compressed": {".rar"},
+}
+
+// ===============================================================
+// 校验函数
+// ===============================================================
+
+// ValidateFileMetadata 校验文件元数据（扩展名、大小、MIME 类型）
+func ValidateFileMetadata(filename, contentType string, size int64, cfg ValidationConfig) error {
+	// 校验文件大小
+	if cfg.MaxFileSize > 0 && size > cfg.MaxFileSize {
+		return fmt.Errorf("file size %d exceeds maximum allowed size %d", size, cfg.MaxFileSize)
+	}
+
+	// 确定 MIME 白名单
+	allowedTypes := cfg.AllowedMimeTypes
+	if len(allowedTypes) == 0 {
+		allowedTypes = defaultAllowedMimeTypes
+	}
+
+	// 校验 MIME 类型是否在白名单内
+	if !isAllowedMimeType(contentType, allowedTypes) {
+		return fmt.Errorf("content type %q is not allowed", contentType)
+	}
+
+	// 校验文件扩展名与 MIME 类型是否匹配
+	if filename != "" {
+		ext := strings.ToLower(filepath.Ext(filename))
+		if ext != "" {
+			expectedExts, ok := mimeToExtensions[contentType]
+			if ok && !slices.Contains(expectedExts, ext) {
+				return fmt.Errorf("file extension %q does not match content type %q", ext, contentType)
+			}
+		}
+	}
+
+	return nil
+}
+
+// ValidateFileContent 校验文件内容（magic bytes 嗅探）
+//
+// 将 magic bytes 检测结果与声明的 Content-Type 进行比对，防止伪造 MIME 类型。
+func ValidateFileContent(header []byte, declaredContentType string) error {
+	if len(header) == 0 {
+		return fmt.Errorf("file header is empty")
+	}
+
+	detected := http.DetectContentType(header)
+
+	// application/octet-stream 表示无法识别，跳过校验
+	if detected == "application/octet-stream" {
+		return nil
+	}
+
+	// 提取主类型进行宽松匹配（例如 text/plain 可能检测为 text/html）
+	detectedMain := strings.Split(detected, "/")[0]
+	declaredMain := strings.Split(declaredContentType, "/")[0]
+
+	if detectedMain != declaredMain {
+		return fmt.Errorf("detected content type %q does not match declared type %q", detected, declaredContentType)
+	}
+
+	return nil
+}
+
+// SanitizeFilename 清理文件名，移除路径分隔符和危险字符
+func SanitizeFilename(filename string) string {
+	// 移除路径分隔符，只保留文件名部分
+	filename = filepath.Base(filename)
+
+	// 移除 null 字节和不可打印字符
+	cleaned := strings.Map(func(r rune) rune {
+		if r == 0 {
+			return -1
+		}
+		if !unicode.IsPrint(r) {
+			return -1
+		}
+		return r
+	}, filename)
+
+	// 替换不安全字符，只保留字母、数字、点、连字符、下划线
+	var result strings.Builder
+	for _, r := range cleaned {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) || r == '.' || r == '-' || r == '_' {
+			result.WriteRune(r)
+		} else {
+			result.WriteRune('_')
+		}
+	}
+
+	sanitized := result.String()
+
+	// 避免空文件名
+	if sanitized == "" || sanitized == "." {
+		sanitized = "unnamed"
+	}
+
+	return sanitized
+}
+
+// ===============================================================
+// 内部辅助
+// ===============================================================
+
+// isAllowedMimeType 检查 MIME 类型是否在白名单中
+func isAllowedMimeType(contentType string, allowed []string) bool {
+	for _, a := range allowed {
+		pattern := strings.TrimSpace(a)
+		if pattern == "" {
+			continue
+		}
+		if pattern == contentType {
+			return true
+		}
+		if strings.HasSuffix(pattern, "/*") &&
+			strings.HasPrefix(contentType, strings.TrimSuffix(pattern, "*")) &&
+			slices.Contains(defaultAllowedMimeTypes, contentType) {
+			return true
+		}
+	}
+	return false
+}