Device-Bound Encryption: How Syncore Keeps Your API Keys Safe

The Plaintext Secret Problem

The default way to configure MCP tools is a JSON file that looks like this:

{
  "mcpServers": {
    "gmail": {
      "env": {
        "GMAIL_CLIENT_SECRET": "GOCSPX-your-actual-secret-here"
      }
    }
  }
}

This file sits in your home directory, readable by any process running as your user. If your machine is compromised, if you accidentally commit it to a repo, if a malicious npm package reads environment variables — your credentials are gone.

We built Syncore's credential system to make this impossible by construction.

Layer 1: Device-Bound Master Key

When you first run syncore login, we generate a 256-bit random master key and store it in your OS-native keychain — Keychain Access on macOS, libsecret on Linux, Windows Credential Manager on Windows. This key never touches disk in plaintext. It is bound to your device and your user account.

Every subsequent operation that reads or writes credentials fetches this key from the keychain first. If the keychain lookup fails (the key was deleted, permissions changed, the user isn't the key owner), credential operations fail safely rather than falling back to unencrypted storage.

Layer 2: Encrypted Credential Files

All OAuth tokens and API keys are encrypted with AES-256-GCM using the master key before being written to disk. Each encrypted blob includes a random 96-bit nonce so identical secrets produce different ciphertext on every write.

The file structure looks like:

~/.syncore/
  credentials/
    gmail.enc        # AES-256-GCM encrypted OAuth tokens
    notion.enc
    perplexity.enc
  identity.enc       # Encrypted Supabase session (identity JWT)

No plaintext secrets anywhere on disk.

Layer 3: Atomic Writes

A subtle but critical detail: we write credential files atomically. The sequence is:

1. Encrypt the new credential blob in memory

2. Write it to a temp file in the same directory (gmail.enc.tmp)

3. rename() the temp file over the existing file

The rename() syscall is atomic on all POSIX systems. This means there's no window where a partial write leaves a corrupted credential file. Either you have the old credentials or the new ones — never a broken intermediate state. This matters when the token refresh daemon is running concurrently with a skill execution that's also reading credentials.

Layer 4: Vault Sync (Optional)

For users who work across multiple machines, Syncore provides an encrypted vault sync via Supabase. Credentials are encrypted client-side before upload — we only ever see the ciphertext. The vault stores your credentials indexed by provider, and syncore update pulls the latest from the vault and re-encrypts them with the local machine key.

If you prefer to stay entirely local, you can opt out of vault sync. The device-bound encryption layers work identically in offline mode.

What This Means for MCP Tool Developers

If you're writing an MCP skill for the Syncore ecosystem, you never handle credentials directly. The Syncore daemon injects provider tokens as environment variables at skill execution time, just before spawning the skill process. The skill sees GMAIL_ACCESS_TOKEN in its environment and uses it — but it never reads or writes to the credential store itself.

This isolation means a buggy skill can't accidentally leak credentials, and a compromised skill process can't exfiltrate the master key because it never has access to it.

The Threat Model

What Syncore protects against:

• Plaintext secrets in config files being committed to git
• Secrets readable by other processes running as your user (they're encrypted at rest)
• Partial writes corrupting credentials (atomic rename)
• Token expiry causing silent failures (proactive refresh daemon)

What Syncore doesn't protect against:

• A fully compromised OS where the attacker can dump keychain contents
• A malicious skill that exfiltrates tokens from its own environment at runtime

The second threat is a property of any system that injects credentials into subprocess environments. We mitigate it through skill review and code signing, but can't eliminate it architecturally. This is the same threat model as any secrets manager that injects env vars.