potassiumProvider

potassiumProvider is a Swift/Xcode app that experiments with exposing an Infomaniak kDrive account through Apple's File Provider APIs.

⚠️ No Support Or Guarantee ⚠️

This project is a community effort. No support, uptime, compatibility, maintenance, or data-safety guarantee is provided. Treat it as experimental software and review the implementation carefully before using it with important data.

Documentation Index

• 0.3.0 Release Notes: actionable kDrive behavior, dependency state, validation, and remaining manual release gates.
• Architecture: targets, modules, persistence, runtime boundaries, and high-level data flow.
• App And Domains: SwiftUI setup app, kDrive loading, File Provider domain registration, and macOS Desktop & Documents controls.
• Authentication: OAuth PKCE, manual token entry, keychain storage, refresh behavior, and secret-handling rules.
• File Provider Lifecycle: Apple callbacks, known-folder locations, mutations, enumeration, and SQLite touch points.
• Contextual Actions: Finder/Files favorite, duplicate, restore, share-link, and version-history actions.
• Listing And Versioning: how Apple enumeration, sync anchors, kDrive listing APIs, SQLite caching, and item versions fit together.
• Persistence: app group files, domain JSON, SQLite snapshot tables, and what is not cached.
• kDrive API Mapping: provider operations mapped to potassiumChannel service calls and visible kDrive endpoints.
• Mutations: create, upload, replace, rename, move, trash, delete, server-authoritative returns, and later reconciliation.
• Conflicts: conflict cases, current resolution behavior, risks, and safer future direction.
• File Provider Cleanup: local development uninstall script, reset modes, stale registration repair, and safety boundary.
• Testing And Development: schemes, dependencies, commands, and local-state caveats.

Project Shape

The root Xcode project is the source of truth:

• App target: potassiumProvider
• File Provider extension target: potassiumProviderFileProvider
• File Provider UI extension target: potassiumProviderActions
• Shared framework target: PotassiumProviderCore
• Unit tests: potassiumProviderTests
• UI tests: potassiumProviderUITests

The local SynchronizingFilesUsingFileProviderExtensions/ folder is Apple's sample/reference project. It is useful for comparison, but it is not the source of truth for this app and is not integrated into the root Xcode project.

Supported validation platforms are iOS Simulator, macOS, and visionOS.

Useful Commands

List schemes and targets:

xcodebuild -list -project potassiumProvider.xcodeproj

Build the app and extension:

xcodebuild build \
  -project potassiumProvider.xcodeproj \
  -scheme potassiumProvider \
  -destination 'platform=iOS Simulator,OS=26.5,name=iPhone 17'

Build on Mac as well:

xcodebuild build \
  -project potassiumProvider.xcodeproj \
  -scheme potassiumProvider \
  -destination 'platform=macOS'

Build on visionOS as well:

xcodebuild build \
  -project potassiumProvider.xcodeproj \
  -scheme potassiumProvider \
  -destination 'generic/platform=visionOS'

Run unit tests:

xcodebuild test \
  -project potassiumProvider.xcodeproj \
  -scheme potassiumProvider \
  -destination 'platform=iOS Simulator,OS=26.5,name=iPhone 17'

Run unit tests on Mac as well:

xcodebuild test \
  -project potassiumProvider.xcodeproj \
  -scheme potassiumProvider \
  -destination 'platform=macOS'

Run unit tests on visionOS as well:

xcodebuild test \
  -project potassiumProvider.xcodeproj \
  -scheme potassiumProvider \
  -destination 'platform=visionOS Simulator,OS=26.5,name=Apple Vision Pro'

The shared scheme's Test action contains potassiumProviderTests only. UI automation remains a separate Xcode test-target workflow and does not run in the command-line matrix above.

Use xcodebuild -showdestinations to copy exact Mac or visionOS destinations if local Xcode requires a more specific variant.

Safety Notes

• Do not commit bearer tokens, refresh tokens, account identifiers, private links, or user data.
• The current conflict handling delegates many decisions to kDrive. Read Conflicts before relying on it for important files.
• SQLite snapshots cache metadata only. File contents and thumbnails are not stored there.
• On macOS 15 or later, Desktop & Documents sync is an explicit, experimental opt-in that always handles both folders together under Private/<current Mac name> on the selected kDrive. Existing active domains created before this layout remain directly under Private until sync is stopped and enabled again.

License

This project is licensed under the GNU General Public License v3.0, matching Infomaniak/ios-kDrive. See LICENSE for the full text.