Security: validate extracted archive trees against ZIP-slip / symlink-escape

[mimeding]

Summary

Why this matters (business)

Osaurus unzips archives in four user-visible install paths:

1. Plugins — signature-verified bundles installed from the central repository.
2. Skills — user-dragged .zip files that ship a SKILL.md and supporting assets.
3. CLI osaurus tools install — local or downloaded plugin archives.
4. CLI MCP bundles — .mcpb bundles loaded by osaurus bundle load.

All four shell out to /usr/bin/unzip. macOS Info-ZIP refuses absolute-path entries and most ..-laden entries on its own, which closes the most-cited ZIP-slip variants. What it still lets through is the symlink-via-archive variant: a .zip entry that, when extracted, becomes a symbolic link inside the destination pointing OUT of it (/etc, ~/.ssh/id_rsa, the user's main project folder, etc.). Subsequent file reads through that link break out of the temp directory the caller assumed it owned.

For plugins that's mitigated by signature verification + minisign — an attacker would have to compromise a publisher key. For skills, MCP bundles, and CLI installs from URLs, the archive is fully attacker-controllable.

What's wrong (technical)

Every site looks like this:

    private func unzip(zipURL: URL, to destination: URL) throws {
        let task = Process()
        task.executableURL = URL(fileURLWithPath: "/usr/bin/env")
        task.arguments = ["unzip", "-o", zipURL.path, "-d", destination.path]
        ...

…and the caller immediately starts reading files out of the extracted tree (findFirstDylib, findSkillMd, manifest.json). Nothing between unzip and "read everything as trusted" inspects what just got written.

Fix

Add a single, public, pure-Foundation validator in OsaurusRepository:

public enum ArchiveSafety {
    public static func validate(extractedRoot: URL) throws { ... }
}

The validator walks every entry the extractor produced. For each:

1. After .standardized, the entry's path must lie inside the extraction root (catches anything /usr/bin/unzip might let through in a future version).
2. After .resolvingSymlinksInPath(), the resolved path must also lie inside the extraction root. This is the symlink-escape check.

Both prefix comparisons use a trailing-/-bracketed root (so sibling directories like /work/foo-evil can't match against root /work/foo), and the root itself is symlink-resolved so the macOS /var → /private/var pattern doesn't cause spurious failures.

On the first escape, throws a structured ArchiveSafetyError listing the offending entry. Callers throw their existing typed errors (PluginInstallError.layoutInvalid, SkillFileError.invalidSkillArchive, BundleLoadError.extractionFailed) so the user-facing UX is unchanged from a normal "bad archive" flow.

Wired in at all four extraction call sites. Tests cover:

• Clean tree accepted (regression guard so legitimate archives keep working).
• Symlink escape rejected.
• Internal symlink accepted (so cross-references inside the archive still work).
• Missing extraction root rejected (helps surface call-site bugs).

Scope decisions

• Streaming-time validation (parsing the ZIP central directory before extraction) would let us reject early without writing anything to disk. That requires either a ZIP library dependency or hand-parsing the format, and the same logic would have to live in four places. Post-extraction validation is the smallest correct fix that works for every existing call site without dragging in a new dep.
• The validator only runs after extraction; the few-millisecond window between unzip returning and validate finishing is acceptable because the destination is a freshly-created temp directory the caller owns. No other process should be reading from it.

Changes

• Behavior change (additive — clean archives still install; only escaping entries are rejected)
• UI change
• Refactor / chore
• Tests (new ArchiveSafetyTests)
• Docs

Test Plan

cd Packages/OsaurusCore && swift test --filter ArchiveSafetyTests

Manually craft a skill archive with a malicious symlink:

mkdir test-skill && cd test-skill
echo "name: test" > SKILL.md
ln -s /etc bad
zip -y -r ../test-skill.zip .

Drop test-skill.zip on the Skills view. Expected: Invalid skill archive. Previously: skill installs and any code reading skill assets would read through the symlink into /etc.

Checklist

• I have read CONTRIBUTING.md
• I added/updated tests where reasonable
• I updated docs/README as needed (n/a — internal hardening)
• I verified build on macOS with Xcode 16.4+ (authored in a Linux sandbox; verified each touched file via swiftc -frontend -parse; tests use only Foundation FileManager APIs that work the same on both platforms)