/security

security_implementation

Local-first architecture for sensitive credentials, with native macOS protection layers and strict API abuse controls.

synced_to_your_icloud

Session metadata synced via CloudKit (Your iCloud) for cross-Mac continuity:

  • +Session labels and groups
  • +Hostnames, ports, and usernames
  • +Visual settings (colors, icons, notes, tags)
  • +Credential links (ID only, not content)

never_synced_local_only

Secret payloads are not synced to CloudKit (Your iCloud); runtime and temporary local handling still applies:

  • xPasswords and private key payloads are not synced to CloudKit (Your iCloud)
  • xPrivate key material can be written to temporary local files during connection flow
  • xMaster-derived key is cleared on lock, while runtime credential caches are restored on unlock

architecture_rationale

Reduced Attack Surface

Server credentials are as exposed as your physical Mac, not a remote cloud database.

Zero-Knowledge Sync

CloudKit (Your iCloud) sync carries metadata only; secret payloads are intentionally excluded.

Physical Presence

On new Macs, sync metadata first and add secrets once into local vault storage.

1. Industry-Standard Encryption

Everything in your vault is encrypted using AES-GCM (Advanced Encryption Standard in Galois/Counter Mode) via Apple's CryptoKit. AES-GCM provides both confidentiality (hiding the data) and authenticity (ensuring the data hasn't been tampered with).

2. Master Password & Key Derivation

Sensitive data is only as strong as the key used to encrypt it. We use PBKDF2 (Password-Based Key Derivation Function 2) to transform your Master Password into a cryptographic key:

  • -Iterations: 100,000 rounds of hashing (HMAC-SHA256) to make "brute-force" attacks computationally expensive.
  • -Salt: A unique, random 32-byte salt is generated the first time you set up your vault, ensuring that identical passwords on different machines produce completely different keys.

3. Secure Storage (macOS Keychain)

While the data is encrypted, the resulting "ciphertext" needs to be stored somewhere. macXterm uses the macOS Keychain (Security.framework) with the following protections:

  • -Access Class: We use kSecAttrAccessibleWhenUnlocked, which means encrypted blobs are only available while your Mac is unlocked.
  • -Scope Note: App Sandbox is currently disabled in entitlements, so this is not relying on sandbox isolation guarantees.

4. Key Lifecycle on Lock/Unlock

Locking clears the master-derived encryption key from active memory. Unlock flow restores runtime credential caches for app operation, so this is not a strict zero-persistence model for all secret-adjacent data.

5. Private Key Handling

Vault storage keeps imported private key material encrypted at rest. During connection setup, key material may be written to a temporary local file for SSH interoperability, then removed during cleanup.

6. Rate Limiting & Abuse Prevention

To prevent brute-force attacks against our API endpoints, macXterm implements strict rate-limiting mechanisms via Upstash Redis. Access is explicitly limited per IP address to ensure fair usage and maintain maximum security.

summary_matrix

FeatureImplementationBenefit
EncryptionAES-256 GCMMilitary-grade encryption & anti-tampering
Key StrengthPBKDF2 (100k iterations)Protects against password cracking
StoragemacOS Keychain (WhenUnlocked)Native at-rest protection while device is unlocked
Runtime ModelMaster key cleared on lock + runtime caches on unlockBalances operational UX with key lifecycle controls
Abuse PreventionUpstash Redis Rate LimitingPrevents brute-force attacks on our APIs