Cloud storage
The cloud home is one location in storage the user already owns. Every provider is driven through the same storage interface in coven; what differs per provider is sign-in, setup, and how other people and devices reach it.
Providers
Section titled “Providers”| Provider | Sign-in | Your own new device | A person you invite |
|---|---|---|---|
| S3-compatible | Access key + secret | Restore code, plus your access key, carried beside it in the QR code | An access key made for them |
| Dropbox | OAuth, held by coven | Restore code, then sign in to your Dropbox | The library’s shared folder is shared with their account |
| OneDrive | OAuth, held by coven | Restore code, then sign in to your OneDrive | The library’s folder is shared with their account |
| iCloud (CloudKit) | Apple Account, no sign-in | Restore code, also offered from iCloud Keychain | The library’s CloudKit zone is shared with their Apple Account |
S3-compatible covers AWS, Backblaze B2, Cloudflare R2, Wasabi, and anything else speaking the API. The setup form asks only for bucket, region, endpoint, and access key; coven recognizes known services by the endpoint’s host and fills in how to talk to them. Advanced holds the optional key prefix and a choice of service profile, automatic by default. For a service coven doesn’t know, Detect Settings probes the bucket with the key and shows what it found. Setup checks the provider before anything is saved, so a typo fails at setup, not at the first sync, and bae states coven’s reason in plain words. Dropbox, OneDrive, and iCloud exist only in the full bae edition; baeium builds compile them out.
Sign-in and folders
Section titled “Sign-in and folders”coven runs the Dropbox and OneDrive sign-in itself, so no token passes through bae. On desktop the browser opens the provider’s page and a local listener receives the one redirect; on mobile the platform’s sign-in sheet does. coven keeps the tokens in the OS keyring and refreshes one once when the provider rejects it; a failed refresh shows in the sync status as a Sign In action rather than a silent retry loop.
After sign-in, the user picks where the library lives. On Dropbox that is a shared folder, since a household library is shared with the other people’s accounts; bae uses Full Dropbox access for this, not an app folder. With no shared folder yet, bae says to share one in Dropbox and look again. On OneDrive it is any folder, browsed from the top, and a new one can be made there.
CloudKit needs no flow at all: coven drives it on Apple platforms as the signed-in Apple Account.
The home’s layout
Section titled “The home’s layout”Inside the home, every object path starts with the library’s store id: coven’s numbered sequence of changes, its snapshots, join requests, and stored files. Several libraries can share one Dropbox or OneDrive folder without touching each other’s objects.
Every object is encrypted and stored under a random name; there is no plaintext mode. bae’s files are coven files that rows of four synced tables reference: release_files, covers, artist_images, and the avatar on each people row. A file’s path is fixed when it is staged, so renaming an album never moves it. See Encryption.
Behavior under real networks
Section titled “Behavior under real networks”Reads for playback are ranged: the player fetches the encrypted chunks it needs rather than whole files, and fetches ahead while a file plays in order. Rate limiting and transient provider errors retry on one backoff schedule, honoring the provider’s retry-after when given. The upload queue survives restarts: an upload interrupted by quitting the app resumes rather than restarts, and paused uploads stay paused.