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.4.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.
• Encrypted Vault Format v2: threat model, leakage, device-local and optional iCloud Keychain custody, guided recovery, binary formats, opaque synchronization, rollback behavior, and security-review feature gates.
• Conflict Resolution Truth Table: normative encrypted-vault data-safety decisions, evidence, and open gates.
• 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.
• Conflict Resolution Truth Table And Safety Register: mission-critical audited decisions, data-loss and soft-lock findings, user recovery limits, and the mandatory maintenance procedure.
• Conflicts: conflict cases, current resolution behavior, design context, 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.
• Encrypted vaults are experimental and disabled by default pending independent cryptographic review. The feature flag is not a production-readiness claim.
• Every encrypted-vault activation route starts with a mandatory unsupported-feature and complete-data-loss warning whose continuation remains disabled for five seconds.
• Encrypted-vault onboarding always requires a verified offline recovery kit. Optional iCloud Keychain access is a separately gated convenience: it can open a vault on another trusted Apple device, but it does not replace offline recovery or revoke keys already imported by another device.
• Conflict handling is mission-critical. Read the Conflict Resolution Truth Table And Safety Register before relying on the provider for important files. Any change to conflict detection, mutation ordering, server conflict policy, retry/error behavior, or user recovery must update that file in the same change; a stale table is a release-blocking data-safety defect.
• The current conflict handling still delegates some decisions to kDrive. Read Conflicts for the broader design context.
• File creates stage bytes before their first network send. Existing-file content uploads use kDrive ETags with If-Match, stage local bytes before preflight, and preserve stale/raced edits as visible renamed copies unless File Provider explicitly requests fail-on-conflict. Combined move/rename/content/trash callbacks are applied in order; unapplied metadata is returned as still pending.
• SQLite snapshots cache metadata only. File contents and thumbnails are not stored there.
• On macOS 15 or later, Desktop & Documents protection is an explicit action. Encrypted domains preflight ownership and local key availability before presenting Apple's consent UI, then upload only opaque vault ciphertext. A legacy plaintext Potassium owner blocks the encrypted known-folder claim. Safe migration and destructive source purge are not implemented.

License

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