LOW: OCI image annotation validation missing, leading to poor error messages

[e-gineer]

Bug Description

The OCI installer does not validate that required image annotations exist or are non-empty. When annotations are missing, empty strings are used as filenames, leading to confusing "file not found" errors instead of clear "malformed image" errors.

Severity: LOW

Location

• pkg/ociinstaller/db_downloader.go:42 (GetImageData)
• pkg/ociinstaller/fdw_downloader.go:42, 51, 58 (GetImageData)
• pkg/ociinstaller/asset_downloader.go:34 (GetImageData)

Current Code

// DB downloader
res.ArchiveDir = foundLayers[0].Annotations["org.opencontainers.image.title"]

// FDW downloader
res.BinaryFile = foundLayers[0].Annotations["org.opencontainers.image.title"]
res.ControlFile = foundLayers[0].Annotations["org.opencontainers.image.title"]
res.SqlFile = foundLayers[0].Annotations["org.opencontainers.image.title"]

No validation that annotations exist or contain non-empty values.

Problem

If an OCI image is malformed and missing required annotations:

1. Empty string "" is assigned as filename
2. Later installation code tries to open file with empty name
3. Error message: "file not found: /path/to/"
4. User sees confusing error, doesn't realize image is malformed

Impact

• Severity: LOW (poor UX, not a functional bug)
• User Impact: Confusing error messages when using malformed/corrupted images
• Frequency: Rare (official images have proper annotations)
• Affected Operations: All OCI installations with malformed images

Example Error Flow

Current behavior:

Error: could not install database
Caused by: file not found: /tmp/steampipe-db/

User thinks: "Why is it looking for a file with no name?"

With validation:

Error: invalid OCI image
Caused by: missing required annotation 'org.opencontainers.image.title' 
           in layer application/vnd.turbot.steampipe.db.darwin-arm64.layer.v1+tar

User thinks: "The image is malformed, I need to re-pull or contact support"

Recommended Fix

Add annotation validation in each GetImageData method:

func (p *dbDownloader) GetImageData(layers []ocispec.Descriptor) (*dbImage, error) {
    res := &dbImage{}

    // Get the binary jar file
    mediaType, err := p.MediaTypesProvider.MediaTypeForPlatform("db")
    if err != nil {
        return nil, err
    }
    foundLayers := ociinstaller.FindLayersForMediaType(layers, mediaType[0])
    if len(foundLayers) != 1 {
        return nil, fmt.Errorf("invalid Image - should contain 1 installation file per platform, found %d", len(foundLayers))
    }
    
    // VALIDATE ANNOTATION
    archiveDir := foundLayers[0].Annotations["org.opencontainers.image.title"]
    if archiveDir == "" {
        return nil, fmt.Errorf(
            "invalid OCI image: missing or empty 'org.opencontainers.image.title' annotation in layer %s",
            foundLayers[0].MediaType,
        )
    }
    res.ArchiveDir = archiveDir

    // ... similar validation for other annotations
}

Benefits

1. Clear error messages - users immediately know image is malformed
2. Fail fast - error at image parsing, not during file operations
3. Better debugging - identifies which layer/annotation is missing
4. Prevents confusion - no mysterious empty filename errors

Validation Checklist

Should validate these annotations:

• DB Image: ArchiveDir (required), ReadmeFile (optional), LicenseFile (optional)
• FDW Image: BinaryFile (required), ControlFile (required), SqlFile (required), ReadmeFile (optional), LicenseFile (optional)
• Assets Image: ReportUI (optional)

Required annotations should error if missing/empty. Optional annotations can remain empty.

Related Tests

• pkg/ociinstaller/db_test.go::TestGetImageData_MissingAnnotations_BugDocumentation

References

• Task 7 completion report: .ai/milestones/wave-3-untested-packages/tasks/task-7-ociinstaller-COMPLETED.md