@dambrogia/openclaw-agents-backup 0.1.0

package/src/backup.ts

@@ -0,0 +1,190 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { BackupConfig, BackupResult, BackupChange, AgentArchiveMetadata } from './types';
+import {
+  pathExists,
+  rsyncDirectory,
+  writeJsonFile,
+  ensureDirectoryExists,
+  executeCommand,
+  getCurrentTimestamp,
+  findAllFiles
+} from './utils';
+import { listAgents, validateAgentBinding } from './agentLister';
+import { encryptFile } from './encryptionService';
+
+/**
+ * Perform backup of all agents to the configured backup repository
+ */
+export async function performBackup(workspacePath: string): Promise<BackupResult> {
+  try {
+    // Load backup configuration
+    const configPath = path.join(workspacePath, '.backupconfig.json');
+    if (!pathExists(configPath)) {
+      return {
+        success: false,
+        message: 'Backup config not found at .backupconfig.json',
+        agentsProcessed: 0,
+        changes: [],
+        error: 'Missing .backupconfig.json'
+      };
+    }
+
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8')) as BackupConfig;
+    const backupRepoPath = config.backupRepoPath;
+
+    if (!pathExists(backupRepoPath)) {
+      return {
+        success: false,
+        message: `Backup repository not found at ${backupRepoPath}`,
+        agentsProcessed: 0,
+        changes: [],
+        error: 'Backup repo not initialized'
+      };
+    }
+
+    // Get encryption password from environment
+    const encryptionPassword = process.env.BACKUP_ENCRYPTION_PASSWORD;
+    if (!encryptionPassword) {
+      return {
+        success: false,
+        message: 'Backup encryption password not set',
+        agentsProcessed: 0,
+        changes: [],
+        error: 'Missing BACKUP_ENCRYPTION_PASSWORD environment variable'
+      };
+    }
+
+    // Get list of agents
+    const agents = await listAgents();
+
+    // Validate agents
+    const validAgents = agents.filter((agent) => {
+      const valid = validateAgentBinding(agent);
+      if (!valid) {
+        console.warn(`Agent ${agent.id} failed validation, skipping`);
+      }
+      return valid;
+    });
+
+    const changes: BackupChange[] = [];
+    const archivesPath = path.join(backupRepoPath, 'archives');
+    ensureDirectoryExists(archivesPath);
+
+    // Back up each agent
+    for (const agent of validAgents) {
+      const agentArchivePath = path.join(archivesPath, agent.id);
+      ensureDirectoryExists(agentArchivePath);
+
+      const backupChange: BackupChange = {
+        agentId: agent.id,
+        workspaceChanged: false,
+        agentDirChanged: false
+      };
+
+      try {
+        // Write agent metadata
+        const metadata: AgentArchiveMetadata = {
+          id: agent.id,
+          identityName: agent.identityName,
+          identityEmoji: agent.identityEmoji,
+          identitySource: agent.identitySource,
+          workspace: agent.workspace,
+          agentDir: agent.agentDir,
+          model: agent.model,
+          bindings: agent.bindings,
+          isDefault: agent.isDefault,
+          routes: agent.routes,
+          backedUpAt: getCurrentTimestamp()
+        };
+        writeJsonFile(path.join(agentArchivePath, 'agent.json'), metadata);
+
+        // Sync workspace
+        const workspaceDestination = path.join(agentArchivePath, 'workspace');
+        ensureDirectoryExists(workspaceDestination);
+        backupChange.workspaceChanged = rsyncDirectory(agent.workspace, workspaceDestination);
+
+        // Sync agent directory (includes both agent/ and sessions/ directories)
+        // Source: ${agentDir}/.. to capture agent/ and sessions/ together
+        const agentDirParent = path.join(agent.agentDir, '..');
+        const agentDirDestination = path.join(agentArchivePath, 'agentDir');
+        ensureDirectoryExists(agentDirDestination);
+        backupChange.agentDirChanged = rsyncDirectory(agentDirParent, agentDirDestination);
+
+        // Encrypt all files in agentDir backup
+        const allFiles = findAllFiles(agentDirDestination);
+        for (const file of allFiles) {
+          // Skip already encrypted files
+          if (file.endsWith('.enc')) {
+            continue;
+          }
+
+          try {
+            const encryptedPath = `${file}.enc`;
+            encryptFile(file, encryptedPath, encryptionPassword);
+            // Delete plaintext after successful encryption
+            fs.unlinkSync(file);
+          } catch (error) {
+            backupChange.error = `Failed to encrypt ${file}: ${error}`;
+            throw error;
+          }
+        }
+
+        changes.push(backupChange);
+      } catch (error) {
+        backupChange.error = String(error);
+        changes.push(backupChange);
+      }
+    }
+
+    // Always commit since metadata (backedUpAt) is always updated
+    try {
+      await gitCommitBackup(backupRepoPath);
+    } catch (error) {
+      return {
+        success: false,
+        message: 'Backup completed but git commit failed',
+        agentsProcessed: validAgents.length,
+        changes,
+        error: String(error)
+      };
+    }
+
+    return {
+      success: true,
+      message: `Backed up ${validAgents.length} agents. Changes: ${changes.filter((c) => c.workspaceChanged || c.agentDirChanged).length}`,
+      agentsProcessed: validAgents.length,
+      changes
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: 'Backup failed',
+      agentsProcessed: 0,
+      changes: [],
+      error: String(error)
+    };
+  }
+}
+
+/**
+ * Commit backup changes to git repository
+ */
+async function gitCommitBackup(repoPath: string): Promise<void> {
+  const currentDir = process.cwd();
+  try {
+    process.chdir(repoPath);
+
+    // Stage all changes
+    executeCommand('git add -A');
+
+    // Create commit message
+    const timestamp = getCurrentTimestamp();
+    const commitMessage = `Backup: ${timestamp}`;
+
+    // Commit changes
+    executeCommand(`git commit -m "${commitMessage}"`);
+  } finally {
+    process.chdir(currentDir);
+  }
+}

package/src/cli.ts

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { performBackup, performRestore } from './index';
+
+/**
+ * CLI entry point for backup/restore operations
+ */
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  const workspace = process.env.OPENCLAW_WORKSPACE || '/root/.openclaw/workspace';
+  const configPath = path.join(workspace, '.backupconfig.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error('❌ Error: .backupconfig.json not found at ' + configPath);
+    process.exit(1);
+  }
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const backupRepoPath = config.backupRepoPath;
+
+  try {
+    switch (command) {
+      case 'backup':
+        await handleBackup(workspace);
+        break;
+
+      case 'restore':
+        await handleRestore(backupRepoPath, workspace, args);
+        break;
+
+      case 'history':
+        await handleHistory(backupRepoPath);
+        break;
+
+      case '--help':
+      case '-h':
+      case undefined:
+        showHelp();
+        break;
+
+      default:
+        console.error('❌ Unknown command: ' + command);
+        showHelp();
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(`❌ Error: ${error}`);
+    process.exit(1);
+  }
+}
+
+async function handleBackup(workspace: string): Promise<void> {
+  console.log('🔄 Starting backup...');
+  const result = await performBackup(workspace);
+
+  if (result.success) {
+    console.log('✅ Backup complete');
+    console.log(`   Agents processed: ${result.agentsProcessed}`);
+    console.log(
+      `   Changes: ${result.changes.filter((c) => c.workspaceChanged || c.agentDirChanged).length}`
+    );
+    result.changes.forEach((change) => {
+      if (change.workspaceChanged || change.agentDirChanged) {
+        console.log(`   - ${change.agentId}: workspace=${change.workspaceChanged}, agentDir=${change.agentDirChanged}`);
+      }
+    });
+  } else {
+    console.error(`❌ Backup failed: ${result.message}`);
+    if (result.error) {
+      console.error(`   ${result.error}`);
+    }
+    process.exit(1);
+  }
+}
+
+async function handleRestore(
+  backupRepoPath: string,
+  workspace: string,
+  args: string[]
+): Promise<void> {
+  let targetSha: string | null = null;
+  let confirmAuthOverwrite = false;
+
+  // Check for --sha argument
+  const shaIndex = args.indexOf('--sha');
+  if (shaIndex !== -1 && shaIndex + 1 < args.length) {
+    targetSha = args[shaIndex + 1];
+    console.log(`🔄 Restoring to commit: ${targetSha}`);
+  } else {
+    console.log('🔄 Restoring to latest backup...');
+  }
+
+  // Check for --confirm-auth-overwrite flag
+  if (args.includes('--confirm-auth-overwrite')) {
+    confirmAuthOverwrite = true;
+  }
+
+  const result = await performRestore(backupRepoPath, targetSha, workspace, confirmAuthOverwrite);
+
+  if (result.success) {
+    console.log('✅ Restore complete');
+    console.log(`   Agents restored: ${result.agentsRestored}`);
+  } else {
+    if (result.authOverwriteWarning) {
+      console.warn(`⚠️  ${result.message}`);
+      console.warn(`\n   To restore including sensitive credentials, run:\n   backup-agents restore ${targetSha ? `--sha ${targetSha}` : ''} --confirm-auth-overwrite`);
+    } else {
+      console.error(`❌ Restore failed: ${result.message}`);
+      if (result.error) {
+        console.error(`   ${result.error}`);
+      }
+    }
+    process.exit(1);
+  }
+}
+
+async function handleHistory(backupRepoPath: string): Promise<void> {
+  const { executeCommand } = require('./utils');
+
+  console.log('📜 Backup history:\n');
+  try {
+    const log = executeCommand(`cd ${backupRepoPath} && git log --oneline -20`);
+    console.log(log);
+  } catch (error) {
+    console.error(`❌ Failed to fetch history: ${error}`);
+    process.exit(1);
+  }
+}
+
+function showHelp(): void {
+  console.log(`
+@dambrogia/openclaw-agents-backup CLI
+
+Usage:
+  backup-agents [command] [options]
+
+Commands:
+  backup                          Backup all agents now
+  restore [options]               Restore agents
+  history                         Show recent backup history
+  --help, -h                      Show this help message
+
+Restore Options:
+  --sha SHA                       Restore to specific commit
+  --confirm-auth-overwrite        Allow overwriting auth-profiles.json (API tokens)
+
+Examples:
+  # Backup now
+  backup-agents backup
+
+  # Restore latest
+  backup-agents restore
+
+  # Restore to specific point in time
+  backup-agents restore --sha abc123def456
+
+  # Restore including sensitive credentials
+  backup-agents restore --confirm-auth-overwrite
+
+  # View backup history
+  backup-agents history
+
+Environment:
+  OPENCLAW_WORKSPACE             Path to OpenClaw workspace (default: /root/.openclaw/workspace)
+  BACKUP_ENCRYPTION_PASSWORD     Password for encrypting/decrypting files (required)
+`);
+}
+
+main().catch((error) => {
+  console.error(`❌ Unexpected error: ${error}`);
+  process.exit(1);
+});

package/src/encryptionService.ts

@@ -0,0 +1,126 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+
+const ALGORITHM = 'aes-256-gcm';
+const SALT_LENGTH = 16;
+const IV_LENGTH = 16;
+const AUTH_TAG_LENGTH = 16;
+const PBKDF2_ITERATIONS = 100000;
+const PBKDF2_DIGEST = 'sha256';
+
+export interface EncryptionHeader {
+  salt: Buffer;
+  iv: Buffer;
+  authTag: Buffer;
+}
+
+/**
+ * Encrypt a file with AES-256-GCM using PBKDF2 key derivation
+ * @param inputPath Path to input file
+ * @param outputPath Path to output file (.jsonl.enc)
+ * @param password Encryption password
+ */
+export function encryptFile(inputPath: string, outputPath: string, password: string): void {
+  // Generate random salt and IV
+  const salt = crypto.randomBytes(SALT_LENGTH);
+  const iv = crypto.randomBytes(IV_LENGTH);
+
+  // Derive key from password using PBKDF2
+  const key = crypto.pbkdf2Sync(password, salt, PBKDF2_ITERATIONS, 32, PBKDF2_DIGEST);
+
+  // Read plaintext
+  const plaintext = fs.readFileSync(inputPath);
+
+  // Encrypt
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  // Write: [salt][iv][authTag][ciphertext]
+  const output = Buffer.concat([salt, iv, authTag, encrypted]);
+  fs.writeFileSync(outputPath, output);
+}
+
+/**
+ * Decrypt a file encrypted with encryptFile()
+ * @param inputPath Path to input file (.jsonl.enc)
+ * @param outputPath Path to output file
+ * @param password Encryption password
+ */
+export function decryptFile(inputPath: string, outputPath: string, password: string): void {
+  // Read encrypted file
+  const encrypted = fs.readFileSync(inputPath);
+
+  // Parse header: [salt][iv][authTag][ciphertext]
+  if (encrypted.length < SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH) {
+    throw new Error('Invalid encrypted file: too short');
+  }
+
+  let offset = 0;
+  const salt = encrypted.subarray(offset, (offset += SALT_LENGTH));
+  const iv = encrypted.subarray(offset, (offset += IV_LENGTH));
+  const authTag = encrypted.subarray(offset, (offset += AUTH_TAG_LENGTH));
+  const ciphertext = encrypted.subarray(offset);
+
+  // Derive key from password using same parameters
+  const key = crypto.pbkdf2Sync(password, salt, PBKDF2_ITERATIONS, 32, PBKDF2_DIGEST);
+
+  // Decrypt
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+
+  try {
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    fs.writeFileSync(outputPath, plaintext);
+  } catch (error) {
+    throw new Error(`Decryption failed: invalid password or corrupted file - ${error}`);
+  }
+}
+
+/**
+ * Encrypt a buffer with AES-256-GCM
+ * @param data Buffer to encrypt
+ * @param password Encryption password
+ * @returns Encrypted buffer with header
+ */
+export function encryptBuffer(data: Buffer, password: string): Buffer {
+  const salt = crypto.randomBytes(SALT_LENGTH);
+  const iv = crypto.randomBytes(IV_LENGTH);
+
+  const key = crypto.pbkdf2Sync(password, salt, PBKDF2_ITERATIONS, 32, PBKDF2_DIGEST);
+
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  return Buffer.concat([salt, iv, authTag, encrypted]);
+}
+
+/**
+ * Decrypt a buffer encrypted with encryptBuffer()
+ * @param encrypted Encrypted buffer with header
+ * @param password Encryption password
+ * @returns Decrypted buffer
+ */
+export function decryptBuffer(encrypted: Buffer, password: string): Buffer {
+  if (encrypted.length < SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH) {
+    throw new Error('Invalid encrypted buffer: too short');
+  }
+
+  let offset = 0;
+  const salt = encrypted.subarray(offset, (offset += SALT_LENGTH));
+  const iv = encrypted.subarray(offset, (offset += IV_LENGTH));
+  const authTag = encrypted.subarray(offset, (offset += AUTH_TAG_LENGTH));
+  const ciphertext = encrypted.subarray(offset);
+
+  const key = crypto.pbkdf2Sync(password, salt, PBKDF2_ITERATIONS, 32, PBKDF2_DIGEST);
+
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+
+  try {
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch (error) {
+    throw new Error(`Decryption failed: invalid password or corrupted data - ${error}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './backup';
+export * from './restore';
+export * from './agentLister';
+export * from './utils';

package/src/restore.ts

@@ -0,0 +1,143 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { RestoreResult, AgentArchiveMetadata } from './types';
+import { pathExists, rsyncDirectory, readJsonFile, ensureDirectoryExists, findEncryptedFiles } from './utils';
+import { decryptFile } from './encryptionService';
+
+/**
+ * Restore agents from backup to specified git SHA or latest
+ * @param backupRepoPath Path to backup repository
+ * @param targetSha Git SHA to restore from (if null, uses current state)
+ * @param workspacePath Base path where agents will be restored
+ * @param confirmAuthOverwrite If true, allows overwriting auth-profiles.json without warning
+ */
+export async function performRestore(
+  backupRepoPath: string,
+  targetSha: string | null,
+  _workspacePath: string,
+  confirmAuthOverwrite: boolean = false
+): Promise<RestoreResult> {
+  try {
+    if (!pathExists(backupRepoPath)) {
+      return {
+        success: false,
+        message: `Backup repository not found at ${backupRepoPath}`,
+        agentsRestored: 0,
+        error: 'Backup repo not found'
+      };
+    }
+
+    const archivesPath = path.join(backupRepoPath, 'archives');
+    if (!pathExists(archivesPath)) {
+      return {
+        success: false,
+        message: 'Archives directory not found in backup repository',
+        agentsRestored: 0,
+        error: 'No archives found'
+      };
+    }
+
+    // Get encryption password from environment
+    const encryptionPassword = process.env.BACKUP_ENCRYPTION_PASSWORD;
+    if (!encryptionPassword) {
+      return {
+        success: false,
+        message: 'Backup encryption password not set',
+        agentsRestored: 0,
+        error: 'Missing BACKUP_ENCRYPTION_PASSWORD environment variable'
+      };
+    }
+
+    // If target SHA specified, we would ideally check out that commit
+    // For now, we work with current state (could be enhanced)
+    if (targetSha) {
+      console.warn(`Note: targetSha specified (${targetSha}) but not implemented in this version`);
+    }
+
+    // List all agent directories
+    const agentDirs = fs
+      .readdirSync(archivesPath, { withFileTypes: true })
+      .filter((dirent) => dirent.isDirectory())
+      .map((dirent) => dirent.name);
+
+    let agentsRestored = 0;
+    const errors: string[] = [];
+
+    // Restore each agent
+    for (const agentId of agentDirs) {
+      const agentArchivePath = path.join(archivesPath, agentId);
+      const metadataPath = path.join(agentArchivePath, 'agent.json');
+
+      try {
+        // Read metadata
+        const metadata = readJsonFile<AgentArchiveMetadata>(metadataPath);
+
+        // Restore workspace
+        const workspaceSource = path.join(agentArchivePath, 'workspace');
+        if (pathExists(workspaceSource)) {
+          ensureDirectoryExists(metadata.workspace);
+          rsyncDirectory(workspaceSource, metadata.workspace);
+        }
+
+        // Restore agent directory
+        const agentDirSource = path.join(agentArchivePath, 'agentDir');
+        if (pathExists(agentDirSource)) {
+          // Decrypt all .enc files before restoring
+          const encryptedFiles = findEncryptedFiles(agentDirSource);
+          for (const encFile of encryptedFiles) {
+            try {
+              const plainPath = encFile.substring(0, encFile.length - 4); // Remove .enc suffix
+              decryptFile(encFile, plainPath, encryptionPassword);
+              // Delete encrypted file after successful decryption
+              fs.unlinkSync(encFile);
+            } catch (error) {
+              throw new Error(`Failed to decrypt ${encFile}: ${error}`);
+            }
+          }
+
+          // Check if auth-profiles.json exists in the backup
+          const backupAuthPath = path.join(agentDirSource, 'agent', 'auth-profiles.json');
+          if (pathExists(backupAuthPath)) {
+            if (!confirmAuthOverwrite) {
+              return {
+                success: false,
+                message: 'Backup contains sensitive auth-profiles.json (API tokens). Use --confirm-auth-overwrite to proceed.',
+                agentsRestored: 0,
+                authOverwriteWarning: true
+              };
+            }
+          }
+
+          ensureDirectoryExists(metadata.agentDir);
+          rsyncDirectory(agentDirSource, metadata.agentDir);
+        }
+
+        agentsRestored++;
+      } catch (error) {
+        errors.push(`Agent ${agentId}: ${error}`);
+      }
+    }
+
+    if (errors.length > 0) {
+      return {
+        success: false,
+        message: `Restored ${agentsRestored} agents with errors`,
+        agentsRestored,
+        error: errors.join('\n')
+      };
+    }
+
+    return {
+      success: true,
+      message: `Successfully restored ${agentsRestored} agents`,
+      agentsRestored
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: 'Restore operation failed',
+      agentsRestored: 0,
+      error: String(error)
+    };
+  }
+}