storax #

Android storage access for Flutter — SAF-aware, OEM-safe, and honest.

storax is an Android-focused Flutter plugin that provides a correct, OEM-aware, SAF-compliant file access layer for real-world apps.

It is designed for developers who need truthful filesystem access instead of fragile shortcuts that break across devices.

This is not a file picker wrapper.
It is a storage abstraction that understands Android’s actual security model.

Why storax exists #

On modern Android:

• Paths may exist but be unreadable
• File explorers can see files your app cannot
• USB behaves differently across OEMs
• “All Files Access” does not mean all files
• SAF and native paths must coexist

Most plugins hide these realities.
storax embraces them and exposes a clean, predictable API.

Core Capabilities #

🔹 Unified Storage Roots #

Retrieve a merged view of:

• Internal storage
• External SD card (where allowed)
• USB / OTG devices
• Adopted storage
• User-selected SAF folders

final roots = await storax.getAllRoots();

Each root includes:

• Type (native / saf)
• Path or URI
• Read/write capability
• Storage statistics (native only)

🔹 Native + SAF Directory Browsing #

List directories using either:

• Native filesystem paths or
• SAF tree URIs

await storax.listDirectory(
  target: pathOrUri,
  isSaf: trueOrFalse,
);

✔ Non-recursive ✔ UI-safe ✔ OEM-tolerant

🔹 Recursive Traversal (Off UI Thread) #

For search, indexing, analytics:

await storax.traverseDirectory(
  target: pathOrUri,
  isSaf: true,
  maxDepth: 5,
  filters: {
    "extensions": ["pdf", "jpg"],
    "minSize": 1024,
  },
);

• Depth-limited
• Filter-aware
• Executed on a native worker thread (no ANRs)

🔹 Path → SAF Resolution (Important) #

When opening a file by path, storax:

1. Checks whether the path belongs to a persisted SAF tree
2. Transparently resolves it to a SAF document URI
3. Falls back to FileProvider only when valid

This avoids common crashes on Android 11+.

await storax.openFile(path: "/storage/...");

🔹 File Opening (User-Safe) #

Supports:

• Native paths
• SAF URIs
• file:// URIs

With:

• MIME detection
• URI permission propagation
• Chooser-based opening

await storax.openFile(
  path: filePath,
  mime: "application/pdf",
);

🔹 SAF Folder Picker #

Used when native access is restricted:

await storax.openSafFolderPicker();

• Persisted permissions
• Emits events when selected

🔹 USB Attach / Detach Events #

Detects:

• USB device attach
• USB removal
• Filesystem mount/unmount

storax.events.listen((event) {
  if (event.type == StoraxEventType.usbAttached) {
    // Refresh roots or ask for SAF access
  }
});

⚠️ USB access is never automatic — user permission is required.

🔹 Permission Handling (Honest) #

final hasAccess = await storax.hasAllFilesAccess();
await storax.requestAllFilesAccess();

• Correct for Android 11+
• Does not assume permission equals access
• SAF remains authoritative where required

🔹 OEM Diagnostics #

final oem = await storax.detectOEM();
final health = await storax.permissionHealthCheck();

Useful for:

• Debug screens
• Support logs
• OEM-specific bug reports

Architecture Highlights #

• Single-threaded native IO executor
• No blocking on UI thread
• Defensive OEM handling
• SAF permission persistence
• Cache-assisted SAF path resolution
• Explicit error reporting (no silent failures)

What storax does NOT do #

• ❌ No background filesystem scanning
• ❌ No silent access to USB storage
• ❌ No bypass of /Android/data or /Android/obb
• ❌ No fake “Recent files” reconstruction
• ❌ No OEM-only privileged APIs

These are system-level restrictions and cannot be bypassed reliably.

Known Unavoidable Android/OEM Limitations #

Some restrictions are enforced at:

• SELinux
• Kernel
• Privileged system app level

Including:

• Access to /Android/data
• Auto-reading USB storage
• Background directory traversal
• Consistency with OEM file explorers

storax intentionally avoids unsafe workarounds.

Supported Platforms #

This plugin is intentionally Android-only.

Who should use this plugin #

• File managers
• Backup / restore tools
• Document-heavy apps
• Media utilities
• OEM / enterprise apps
• Power-user tools

If your app needs correct file access, not illusions — this is for you.

License #

MIT

Philosophy #

Respect the OS. Fail loudly. Never lie about access.

👨‍💻 Author #

Sumit Kumar