package spool import ( "archive/zip" "bufio" "bytes" "crypto/sha256" "encoding/hex" "encoding/json" "errors" "hash" "io" "os" "path/filepath" "strings" "unicode/utf8" "knowledge-governance/internal/governance" ) type Expectation struct { RelativeRef string SHA256 string SizeBytes int64 Format string } type Artifact struct { file *os.File expectedSHA string expectedSize int64 streamHash hash.Hash streamed int64 } var supportedFormats = map[string]struct{}{ "pdf": {}, "docx": {}, "doc": {}, "xlsx": {}, "xls": {}, "md": {}, "txt": {}, "csv": {}, "json": {}, "png": {}, "jpg": {}, "jpeg": {}, "gif": {}, "bmp": {}, "webp": {}, } func InspectVerified(root, relativeRef, format string, maxBytes int64) (Expectation, error) { if !filepath.IsAbs(root) || relativeRef == "" || filepath.IsAbs(relativeRef) || maxBytes <= 0 { return Expectation{}, errors.New("invalid spool reference") } cleanRef := filepath.Clean(relativeRef) if cleanRef == "." || cleanRef != relativeRef || cleanRef == ".." || strings.HasPrefix(cleanRef, ".."+string(filepath.Separator)) { return Expectation{}, errors.New("invalid spool reference") } if _, ok := supportedFormats[format]; !ok { return Expectation{}, errors.New("unsupported spool artifact format") } file, err := openRegularNoSymlink(root, cleanRef) if err != nil { return Expectation{}, errors.New("open spool artifact") } defer file.Close() info, err := file.Stat() if err != nil || !info.Mode().IsRegular() || info.Size() <= 0 || info.Size() > maxBytes { return Expectation{}, errors.New("spool artifact size or type mismatch") } digest := sha256.New() bytesRead, err := io.Copy(digest, file) if err != nil || bytesRead != info.Size() { return Expectation{}, errors.New("inspect spool artifact content") } if _, err := file.Seek(0, io.SeekStart); err != nil { return Expectation{}, errors.New("rewind spool artifact") } if err := validateFormat(file, format, info.Size()); err != nil { return Expectation{}, errors.New("spool artifact format mismatch") } return Expectation{ RelativeRef: cleanRef, SHA256: hex.EncodeToString(digest.Sum(nil)), SizeBytes: info.Size(), Format: format, }, nil } func OpenVerified(root string, expected Expectation, maxBytes int64) (*Artifact, error) { if !filepath.IsAbs(root) || expected.RelativeRef == "" || filepath.IsAbs(expected.RelativeRef) { return nil, errors.New("invalid spool reference") } cleanRef := filepath.Clean(expected.RelativeRef) if cleanRef == "." || cleanRef != expected.RelativeRef || cleanRef == ".." || strings.HasPrefix(cleanRef, ".."+string(filepath.Separator)) { return nil, errors.New("invalid spool reference") } if !governance.ValidSHA256(expected.SHA256) || expected.SizeBytes <= 0 || maxBytes <= 0 || expected.SizeBytes > maxBytes { return nil, errors.New("invalid spool expectation") } if _, ok := supportedFormats[expected.Format]; !ok { return nil, errors.New("unsupported spool artifact format") } file, err := openRegularNoSymlink(root, cleanRef) if err != nil { return nil, errors.New("open spool artifact") } info, err := file.Stat() if err != nil { file.Close() return nil, errors.New("inspect spool artifact") } if !info.Mode().IsRegular() || info.Size() != expected.SizeBytes { file.Close() return nil, errors.New("spool artifact size or type mismatch") } beforeHash := sha256.New() bytesRead, err := io.Copy(beforeHash, file) if err != nil || bytesRead != expected.SizeBytes || hex.EncodeToString(beforeHash.Sum(nil)) != expected.SHA256 { file.Close() return nil, errors.New("spool artifact content mismatch") } if _, err := file.Seek(0, io.SeekStart); err != nil { file.Close() return nil, errors.New("rewind spool artifact") } if err := validateFormat(file, expected.Format, expected.SizeBytes); err != nil { file.Close() return nil, errors.New("spool artifact format mismatch") } if _, err := file.Seek(0, io.SeekStart); err != nil { file.Close() return nil, errors.New("rewind spool artifact after validation") } return &Artifact{ file: file, expectedSHA: expected.SHA256, expectedSize: expected.SizeBytes, streamHash: sha256.New(), }, nil } func validateFormat(file *os.File, format string, size int64) error { switch format { case "pdf": header := make([]byte, len("%PDF-")) if _, err := io.ReadFull(file, header); err != nil || !bytes.Equal(header, []byte("%PDF-")) { return errors.New("invalid PDF magic") } case "docx", "xlsx": archive, err := zip.NewReader(file, size) if err != nil { return errors.New("invalid Office ZIP") } required := map[string]string{ "docx": "word/document.xml", "xlsx": "xl/workbook.xml", }[format] foundContentTypes := false foundRequired := false for _, entry := range archive.File { switch entry.Name { case "[Content_Types].xml": foundContentTypes = true case required: foundRequired = true } } if !foundContentTypes || !foundRequired { return errors.New("missing Office package entry") } case "doc", "xls": header := make([]byte, 8) oleMagic := []byte{0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1} if _, err := io.ReadFull(file, header); err != nil || !bytes.Equal(header, oleMagic) { return errors.New("invalid legacy Office magic") } case "png", "jpg", "jpeg", "gif", "bmp", "webp": header := make([]byte, 12) n, err := file.Read(header) if err != nil || n < 12 { return errors.New("invalid image header") } valid := false switch format { case "png": valid = bytes.Equal(header[:8], []byte{0x89, 'P', 'N', 'G', 0x0d, 0x0a, 0x1a, 0x0a}) case "jpg", "jpeg": valid = header[0] == 0xff && header[1] == 0xd8 && header[2] == 0xff case "gif": valid = bytes.Equal(header[:6], []byte("GIF87a")) || bytes.Equal(header[:6], []byte("GIF89a")) case "bmp": valid = header[0] == 'B' && header[1] == 'M' case "webp": valid = bytes.Equal(header[:4], []byte("RIFF")) && bytes.Equal(header[8:12], []byte("WEBP")) } if !valid { return errors.New("invalid image magic") } if _, err := file.Seek(0, io.SeekStart); err != nil { return errors.New("rewind image artifact") } case "json": decoder := json.NewDecoder(file) var value any if err := decoder.Decode(&value); err != nil { return errors.New("invalid JSON") } if err := decoder.Decode(&struct{}{}); err != io.EOF { return errors.New("multiple JSON values") } case "md", "txt", "csv": prefixSize := size if prefixSize > 4096 { prefixSize = 4096 } prefix := make([]byte, prefixSize) if _, err := io.ReadFull(file, prefix); err != nil { return errors.New("read text prefix") } lowerPrefix := strings.ToLower(strings.TrimSpace(strings.TrimPrefix(string(prefix), "\ufeff"))) if strings.HasPrefix(lowerPrefix, " 0 { artifact.streamed += int64(count) _, _ = artifact.streamHash.Write(buffer[:count]) } return count, err } func (artifact *Artifact) VerifyComplete() error { if artifact.streamed != artifact.expectedSize || hex.EncodeToString(artifact.streamHash.Sum(nil)) != artifact.expectedSHA { return errors.New("spool artifact changed during streaming") } return nil } func (artifact *Artifact) Close() error { return artifact.file.Close() }