From 8f7f8ea22639b5e16d8a652e6b99c5ffeb7cc71b Mon Sep 17 00:00:00 2001 From: redth Date: Tue, 31 Mar 2026 17:23:54 -0400 Subject: [PATCH] Add keystore cloud sync documentation Document how keystore sync works, what data gets uploaded, supported cloud providers with their encryption models, local storage locations, and practical considerations for users. Link from README keystore section to the new doc. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- docs/keystore-sync.md | 50 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 docs/keystore-sync.md diff --git a/README.md b/README.md index 0e70377..fdfa696 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ MAUI Sherpa is a desktop application for **macOS**, **Windows**, and **Linux** t - Create and manage Android signing keystores - View certificate signatures and details - Export PEPK keys for Google Play -- Cloud sync keystores across machines +- Cloud sync keystores across machines ([learn more](docs/keystore-sync.md)) ### 🍎 Apple Developer Tools (macOS only) - **Xcode Management**: Browse available Xcode versions, download directly from Apple with authenticated sign-in (SRP + 2FA), and install — all from within the app diff --git a/docs/keystore-sync.md b/docs/keystore-sync.md new file mode 100644 index 0000000..db1c9fe --- /dev/null +++ b/docs/keystore-sync.md @@ -0,0 +1,50 @@ +# Keystore Cloud Sync + +MAUI Sherpa can sync your Android signing keystores to a cloud secrets provider, making them available across machines. This document explains how the feature works, what data is stored where, and what to keep in mind when using it. + +## How It Works + +When you sync a keystore to the cloud, three pieces of data are uploaded as separate secrets: + +| Secret | Contents | +|--------|----------| +| `KEYSTORE_{alias}_JKS` | The keystore file (binary) | +| `KEYSTORE_{alias}_PWD` | The keystore password (plaintext UTF-8) | +| `KEYSTORE_{alias}_META` | JSON metadata (alias, type, creation date, notes) | + +When you download a keystore from the cloud, the file is saved to your local keystores directory and the password is stored in your platform's secure storage (macOS Keychain / Windows DPAPI). + +## Supported Providers + +| Provider | Authentication | Encryption Model | +|----------|---------------|-----------------| +| **Azure Key Vault** | Service Principal (Tenant ID, Client ID, Client Secret) | Azure-managed (server-side) | +| **AWS Secrets Manager** | Access Key ID + Secret Access Key | AWS KMS (server-side) | +| **Google Secret Manager** | Service Account JSON credentials | Google-managed (server-side) | +| **Azure DevOps** | Personal Access Token | Azure-managed (server-side) | +| **Infisical** | Machine Identity (Client ID + Client Secret) | Server-side | +| **1Password** | Desktop app auth or Service Account Token | End-to-end encrypted (1Password) | +| **Vaultwarden / Bitwarden** | Email + Master Password + API Key | Client-side encryption (AES-256, PBKDF2 key derivation) | + +All providers communicate over HTTPS/TLS. + +## Local Storage + +| Data | Location | +|------|----------| +| Keystore files | `~/Library/Application Support/MauiSherpa/keystores/` (macOS) | +| Keystore metadata | `~/Library/Application Support/MauiSherpa/android-keystores.json` | +| Keystore passwords | macOS Keychain (Release) / fallback file (Debug builds only) | +| Cloud provider credentials | macOS Keychain (Release) / fallback file (Debug builds only) | + +On Windows, the app data directory is `%APPDATA%\MauiSherpa\` and passwords use Windows DPAPI. + +## Things to Know + +- **Your keystore password is uploaded to the cloud provider.** This is necessary for the sync feature to work — when you download a keystore on another machine, the password needs to come with it. The security of that password depends entirely on your cloud provider. + +- **Server-side vs client-side encryption matters.** With Azure Key Vault, AWS, Google, Azure DevOps, and Infisical, the provider manages encryption — meaning the provider (and anyone with access to your account) can read your secrets. With 1Password and Vaultwarden/Bitwarden, encryption happens on your machine before data leaves it. + +- **Use dedicated credentials with minimal permissions.** For cloud providers that support IAM or RBAC (Azure, AWS, Google), create a service principal or service account scoped to only the secrets your keystores need. Don't reuse broad admin credentials. + +- **Keystore files on disk are not separately encrypted by MAUI Sherpa.** They rely on the keystore format's own encryption (PKCS12 or JKS) plus OS file permissions. The keystore password is what protects the key material inside.