feat: implement encryption key rotation and enhance security for credential syncing

Author: ErcinDedeoglu

docs/DEV-SETUP.md

@@ -150,6 +150,24 @@ After first run, the plugin creates `~/.config/opencode/opencode-sync.json`:
 }
 ```
 
+## Encryption Key Rotation
+
+To rotate encryption keys without losing access to credentials:
+
+1. Add both keys to config on ALL machines:
+```json
+{
+  "encryptionKey": "new-key-here",
+  "oldEncryptionKey": "old-key-here"
+}
+```
+
+2. Restart OpenCode on each machine - it will:
+   - Decrypt using `oldEncryptionKey` (fallback)
+   - Re-encrypt using `encryptionKey` on next push
+
+3. After all machines have synced, remove `oldEncryptionKey`
+
 ## Troubleshooting
 
 ### Plugin not loading

docs/LLM-INSTALL.md

@@ -41,18 +41,35 @@ Guide the user step by step:
 8. IMPORTANT: Tell user to copy the token immediately (starts with "github_pat_")
 9. Ask user: "Please paste your token here" - Save this as TOKEN
 
-### Step 4: Generate Encryption Key
-Tell the user:
-"I'll generate a secure encryption key for you. This encrypts your data before uploading to GitHub."
+### Step 4: Encryption Key (Optional)
+Ask the user:
+"Do you want to encrypt your credentials (auth tokens) before syncing? This adds extra security but requires the same key on all machines."
 
-Generate a random 32-character alphanumeric string for the user, or ask them to provide their own (minimum 16 characters).
-Save this as ENCRYPTION_KEY.
+If YES:
+- Generate a random 32-character alphanumeric string, or let user provide their own (minimum 16 characters)
+- Save this as ENCRYPTION_KEY
+- IMPORTANT: Tell user to save this key securely. If lost, encrypted credentials cannot be recovered.
+- WARNING: All machines must use the same key. Adding encryption later will break sync on machines without the key.
 
-IMPORTANT: Tell user to save this key securely. If lost, synced data cannot be decrypted.
+If NO:
+- Skip this step. Credentials will sync in plain text (still protected by GitHub's private repo authentication).
 
 ### Step 5: Create Configuration
 Create or update the OpenCode config file with these values:
 
+Without encryption:
+{
+  "plugins": {
+    "oc-sync": {
+      "token": "<TOKEN from Step 3>",
+      "owner": "<OWNER from Step 2>",
+      "repo": "<REPO from Step 2>",
+      "branch": "main"
+    }
+  }
+}
+
+With encryption:
 {
   "plugins": {
     "oc-sync": {
@@ -79,13 +96,38 @@ If user reports errors:
 - "401 Unauthorized": Token is invalid or expired. Generate a new one.
 - "403 Forbidden": Token lacks required permissions. Recreate with Contents read/write.
 - "Encryption error": Key is less than 16 characters or contains invalid characters.
+- "Decryption failed": Wrong encryption key or data was synced with a different key.
+
+### Key Rotation (Advanced)
+If user needs to change their encryption key:
+
+1. On ALL machines, update config to include BOTH keys:
+{
+  "plugins": {
+    "oc-sync": {
+      "token": "...",
+      "owner": "...",
+      "repo": "...",
+      "encryptionKey": "<NEW_KEY>",
+      "oldEncryptionKey": "<OLD_KEY>"
+    }
+  }
+}
+
+2. Restart OpenCode on each machine. The plugin will:
+   - Decrypt using old key (fallback)
+   - Re-encrypt using new key on push
+
+3. After ALL machines have synced with the new key, remove oldEncryptionKey from config.
+
+IMPORTANT: Do NOT remove oldEncryptionKey until all machines have synced at least once with the new configuration.
 
 ### Summary
 After setup, confirm with user:
 - GitHub username: [OWNER]
 - Repository: [REPO] (private)
 - Token: configured (never display full token)
-- Encryption: enabled with [length]-character key
+- Encryption: enabled/disabled
 - Status: Ready to sync
 ```
 

src/plugin/state-manager.ts

@@ -7,7 +7,7 @@
 import type { PathConfig } from '../types/paths.js';
 import { DEFAULT_CONFIG, type SyncConfig, type SyncCategory } from '../types/index.js';
 import { SyncEngine } from '../sync/engine/index.js';
-import { RepoStorageBackend } from '../storage/index.js';
+import { RepoStorageBackend, type RepoClientConfig } from '../storage/index.js';
 import { createFileWatcher } from '../sync/watcher/index.js';
 import { loadConfig, saveConfig, loadLocalState, generateMachineId } from '../data/index.js';
 import type { PluginState } from './types.js';
@@ -37,18 +37,35 @@ export function initializeEngine(): void {
   if (!state.config) return;
   if (!state.config.repoOwner || !state.config.repoName) return;
 
-  const backend = new RepoStorageBackend({
+  const backendConfig: RepoClientConfig = {
     token: state.config.token,
     owner: state.config.repoOwner,
     repo: state.config.repoName,
-  });
-
-  state.engine = new SyncEngine({
-    config: state.config,
-    backend,
-    localState: state.localState,
-    passphrase: state.passphrase ?? undefined,
-  });
+  };
+  if (state.config.branch) {
+    backendConfig.branch = state.config.branch;
+  }
+  const backend = new RepoStorageBackend(backendConfig);
+
+  // Support key rotation: oldEncryptionKey from config is used as fallback for decryption
+  const oldKey = state.oldPassphrase ?? state.config.oldEncryptionKey;
+
+  state.engine = new SyncEngine(
+    oldKey
+      ? {
+          config: state.config,
+          backend,
+          localState: state.localState,
+          passphrase: state.passphrase ?? undefined,
+          oldPassphrase: oldKey,
+        }
+      : {
+          config: state.config,
+          backend,
+          localState: state.localState,
+          passphrase: state.passphrase ?? undefined,
+        }
+  );
 
   state.isInitialized = true;
 }

src/plugin/types.ts

@@ -14,6 +14,8 @@ export interface PluginState {
   engine: SyncEngine | null;
   watcher: FileWatcher | null;
   passphrase: string | null;
+  /** Previous encryption key for key rotation */
+  oldPassphrase: string | null;
   isInitialized: boolean;
 }
 
@@ -24,6 +26,7 @@ export function createInitialState(): PluginState {
     engine: null,
     watcher: null,
     passphrase: null,
+    oldPassphrase: null,
     isInitialized: false,
   };
 }

src/storage/repo/repo-client.ts

@@ -20,6 +20,8 @@ export interface RepoClientConfig {
   token: string;
   owner: string;
   repo: string;
+  /** Branch to use for sync (auto-detected if not specified, created if missing) */
+  branch?: string;
   maxRetries?: number;
   retryDelayMs?: number;
 }
@@ -61,7 +63,8 @@ export class RepoStorageBackend implements StorageBackend {
   private readonly baseUrl: string;
   private readonly maxRetries: number;
   private readonly retryDelayMs: number;
-  private detectedBranch: 'main' | 'master' | null = null;
+  private readonly configuredBranch: string | undefined;
+  private detectedBranch: string | null = null;
 
   constructor(config: RepoClientConfig) {
     this.token = config.token;
@@ -70,6 +73,7 @@ export class RepoStorageBackend implements StorageBackend {
     this.baseUrl = `https://api.github.com/repos/${config.owner}/${config.repo}`;
     this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.retryDelayMs = config.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    this.configuredBranch = config.branch;
   }
 
   public async exists(): Promise<boolean> {
@@ -94,7 +98,7 @@ export class RepoStorageBackend implements StorageBackend {
 
     // For files >1MB, GitHub returns empty content and provides download_url
     if (!data.content && data.size > 1000000) {
-      const branch = await this.getDefaultBranch();
+      const branch = await this.getBranch();
       const downloadUrl = `https://raw.githubusercontent.com/${this.owner}/${this.repo}/${branch}/${fullPath}`;
       const downloadRes = await fetchWithRetry(
         downloadUrl,
@@ -187,9 +191,20 @@ export class RepoStorageBackend implements StorageBackend {
     }
   }
 
-  private async getDefaultBranch(): Promise<'main' | 'master'> {
+  private async getBranch(): Promise<string> {
     if (this.detectedBranch) return this.detectedBranch;
 
+    // If branch is configured, use it (create if missing)
+    if (this.configuredBranch) {
+      const branchExists = await this.branchExists(this.configuredBranch);
+      if (!branchExists) {
+        await this.createBranch(this.configuredBranch);
+      }
+      this.detectedBranch = this.configuredBranch;
+      return this.configuredBranch;
+    }
+
+    // Auto-detect: try main first, then master
     const res = await this.fetch('/git/ref/heads/main');
     if (res.ok) {
       this.detectedBranch = 'main';
@@ -206,8 +221,54 @@ export class RepoStorageBackend implements StorageBackend {
     return 'main';
   }
 
+  private async branchExists(branch: string): Promise<boolean> {
+    const res = await this.fetch(`/git/ref/heads/${branch}`);
+    return res.ok;
+  }
+
+  private async createBranch(branch: string): Promise<void> {
+    // Get SHA from default branch (main or master)
+    const defaultBranch = await this.detectDefaultBranch();
+    const defaultRes = await this.fetch(`/git/ref/heads/${defaultBranch}`);
+    if (!defaultRes.ok) {
+      throw new RepoApiError(
+        `Cannot find default branch (${defaultBranch}) to create new branch from`,
+        404
+      );
+    }
+    const defaultRef = (await defaultRes.json()) as GitRef;
+    const baseSha = defaultRef.object.sha;
+
+    // Create new branch ref
+    const body = JSON.stringify({
+      ref: `refs/heads/${branch}`,
+      sha: baseSha,
+    });
+
+    const res = await this.fetch('/git/refs', { method: 'POST', body });
+    if (!res.ok) {
+      const errBody = (await res.json().catch(() => ({}))) as { message?: string };
+      throw new RepoApiError(
+        errBody.message ?? `Failed to create branch: ${branch}`,
+        res.status,
+        errBody
+      );
+    }
+  }
+
+  /** Detect default branch without creating - used as base for new branches */
+  private async detectDefaultBranch(): Promise<'main' | 'master'> {
+    const res = await this.fetch('/git/ref/heads/main');
+    if (res.ok) return 'main';
+
+    const masterRes = await this.fetch('/git/ref/heads/master');
+    if (masterRes.ok) return 'master';
+
+    return 'main';
+  }
+
   private async getHeadSha(): Promise<string> {
-    const branch = await this.getDefaultBranch();
+    const branch = await this.getBranch();
     const res = await this.fetch(`/git/ref/heads/${branch}`);
     if (!res.ok) {
       throw new RepoApiError(`Cannot find ${branch} branch`, 404);
@@ -314,7 +375,7 @@ export class RepoStorageBackend implements StorageBackend {
   private async updateRef(commitSha: string): Promise<void> {
     // force: false ensures proper CAS - GitHub will reject if HEAD moved
     const body = JSON.stringify({ sha: commitSha, force: false });
-    const branch = await this.getDefaultBranch();
+    const branch = await this.getBranch();
 
     const res = await this.fetch(`/git/refs/heads/${branch}`, { method: 'PATCH', body });
 

src/sync/engine/sync-engine.ts

@@ -35,12 +35,22 @@ export class SyncEngine {
   private readonly config: SyncEngineOptions['config'];
   private localState: LocalSyncState | null;
   private readonly passphrase: string | undefined;
+  private readonly oldPassphrase: string | undefined;
 
   constructor(options: SyncEngineOptions) {
     this.backend = options.backend;
     this.config = options.config;
     this.localState = options.localState;
     this.passphrase = options.passphrase;
+    this.oldPassphrase = options.oldPassphrase;
+  }
+
+  /** Get crypto options for encryption/decryption with key rotation support */
+  private getCryptoOptions(): { passphrase?: string; oldPassphrase?: string } {
+    const result: { passphrase?: string; oldPassphrase?: string } = {};
+    if (this.passphrase) result.passphrase = this.passphrase;
+    if (this.oldPassphrase) result.oldPassphrase = this.oldPassphrase;
+    return result;
   }
 
   public async sync(localData: CategoryData[]): Promise<SyncResult> {
@@ -144,7 +154,7 @@ export class SyncEngine {
       localData,
       this.config,
       this.localState,
-      this.passphrase,
+      this.getCryptoOptions(),
       existingFilenames
     );
     const storageFiles: Record<string, string | null> = {};
@@ -169,7 +179,7 @@ export class SyncEngine {
       manifest,
       storageFiles,
       this.config.sync,
-      this.passphrase,
+      this.getCryptoOptions(),
       this.backend
     );
     this.localState = buildLocalState(
@@ -191,7 +201,7 @@ export class SyncEngine {
       remoteManifest,
       storageFiles,
       localState: this.localState,
-      passphrase: this.passphrase,
+      passphrase: this.getCryptoOptions(),
       machineId: this.config.machineId,
       backend: this.backend,
     });

src/sync/engine/types.ts

@@ -6,12 +6,26 @@
 
 import type { SyncConfig, LocalSyncState } from '../../types/index.js';
 import type { StorageBackend } from '../../storage/index.js';
+import type { CryptoOptions } from '../operations/types.js';
 
 export interface SyncEngineOptions {
   config: SyncConfig;
   backend: StorageBackend;
   localState: LocalSyncState | null;
   passphrase: string | undefined;
+  /** Previous encryption key for key rotation */
+  oldPassphrase?: string;
+}
+
+/** Get crypto options from engine options */
+export function getCryptoOptions(options: {
+  passphrase?: string;
+  oldPassphrase?: string;
+}): CryptoOptions {
+  const result: CryptoOptions = {};
+  if (options.passphrase) result.passphrase = options.passphrase;
+  if (options.oldPassphrase) result.oldPassphrase = options.oldPassphrase;
+  return result;
 }
 
 export const MANIFEST_FILENAME = 'manifest.json';