clawkeep 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
   <img src="assets/banner.jpg" alt="ClawKeep" width="100%" />
 </p>
 
-<h1 align="center">🐾 ClawKeep</h1>
+<h1 align="center">ClawKeep</h1>
 
 <p align="center">
   <strong>Private, encrypted backups that just work.</strong><br>
@@ -108,9 +108,32 @@ Your backup target receives **encrypted chunks only**. No metadata. No history.
 | Target | Status | Description |
 |---|---|---|
 | **Local path** | ✅ Available | Any mounted folder — NAS, USB drive, network share |
-| **S3 / R2** | 🔜 Coming soon | Object storage (AWS, Cloudflare, MinIO) |
+| **S3 / R2** | ✅ Available | Object storage (Cloudflare R2, AWS S3, MinIO, Backblaze B2, Wasabi) |
 | **ClawKeep Cloud** | 🔜 Coming soon | Managed zero-knowledge backup |
 
+### S3 / R2 Setup
+
+```bash
+# Configure S3-compatible target
+clawkeep backup s3 \
+  --endpoint https://your-account.r2.cloudflarestorage.com \
+  --bucket my-backups \
+  --access-key AKIAIOSFODNN7EXAMPLE \
+  --secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
+  --region auto \
+  --prefix clawkeep/
+
+# Or use environment variables for credentials
+export CLAWKEEP_S3_ACCESS_KEY=your-access-key
+export CLAWKEEP_S3_SECRET_KEY=your-secret-key
+clawkeep backup s3 --endpoint https://... --bucket my-backups
+
+# Sync encrypted chunks to S3
+clawkeep backup sync
+```
+
+Works with any S3-compatible service: **Cloudflare R2** (zero egress fees), **AWS S3**, **Backblaze B2**, **MinIO**, **Wasabi**, and more.
+
 ## Commands
 
 | Command | What it does |
@@ -264,7 +287,7 @@ const oldContent = await claw.showFileAtCommit('abc123', 'config.yaml');
 
 ## Roadmap
 
-- [ ] S3 / R2 / MinIO backend
+- [x] S3 / R2 / MinIO backend
 - [ ] `clawkeep.com` — zero-knowledge cloud backup
 - [ ] End-to-end encrypted team sharing
 - [ ] Webhooks on file changes

package/bin/clawkeep.js

@@ -89,12 +89,29 @@ program
   .description('Manage backup target (local, cloud, s3, git)')
   .option('-d, --dir <path>', 'Target directory', '.')
   .option('-p, --password <pass>', 'Encryption password (or CLAWKEEP_PASSWORD env)')
+  .option('--endpoint <url>', 'S3 endpoint URL')
+  .option('--bucket <name>', 'S3 bucket name')
+  .option('--access-key <key>', 'S3 access key ID')
+  .option('--secret-key <key>', 'S3 secret access key')
+  .option('--region <region>', 'S3 region (default: auto)')
+  .option('--prefix <prefix>', 'S3 key prefix')
   .action((subcommand, targetPath, opts) => {
     opts.args = targetPath ? [targetPath] : [];
     opts.path = targetPath;
     require('../src/commands/backup')(subcommand, opts.args, opts);
   });
 
+// cloud
+program
+  .command('cloud [subcommand]')
+  .description('Connect to ClawKeep Cloud')
+  .option('-d, --dir <path>', 'Target directory', '.')
+  .option('--api-key <key>', 'API key (headless)')
+  .option('--workspace <id>', 'Workspace ID (headless)')
+  .option('--endpoint <url>', 'API endpoint')
+  .option('-p, --password <pass>', 'Encryption password')
+  .action((sub, opts) => require('../src/commands/cloud')(sub, opts));
+
 // watch
 program
   .command('watch')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawkeep",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Private, encrypted backups with time-travel restore. Zero-knowledge protection for AI agents, configs, and everything you care about.",
   "main": "src/index.js",
   "bin": {

package/src/commands/backup.js

@@ -69,7 +69,7 @@ async function showStatus(bm) {
     }
 
     // Encryption status
-    if (cfg.target === 'local') {
+    if (cfg.target === 'local' || cfg.target === 's3' || cfg.target === 'cloud') {
       console.log(`  Encrypted:   ${cfg.passwordSet ? chalk.green('\u2713 yes') : chalk.yellow('\u26a0 password not set')}`);
       if (cfg.chunkCount > 0) {
         console.log(`  Chunks:      ${cfg.chunkCount}`);
@@ -106,6 +106,21 @@ async function setTarget(bm, typeOrArgs, opts) {
       process.exit(1);
     }
     options.url = url;
+  } else if (type === 's3') {
+    const endpoint = opts.endpoint || process.env.CLAWKEEP_S3_ENDPOINT;
+    const bucket = opts.bucket || process.env.CLAWKEEP_S3_BUCKET;
+    const accessKey = opts.accessKey || process.env.CLAWKEEP_S3_ACCESS_KEY;
+    const secretKey = opts.secretKey || process.env.CLAWKEEP_S3_SECRET_KEY;
+    const region = opts.region || process.env.CLAWKEEP_S3_REGION || 'auto';
+    const prefix = opts.prefix || process.env.CLAWKEEP_S3_PREFIX || '';
+
+    if (!endpoint || !bucket || !accessKey || !secretKey) {
+      console.error(chalk.red('  Missing S3 config. Required: --endpoint, --bucket, --access-key, --secret-key'));
+      console.error(chalk.dim('  Or use env vars: CLAWKEEP_S3_ENDPOINT, CLAWKEEP_S3_BUCKET, CLAWKEEP_S3_ACCESS_KEY, CLAWKEEP_S3_SECRET_KEY'));
+      process.exit(1);
+    }
+
+    options = { endpoint, bucket, accessKey, secretKey, region, prefix };
   }
 
   const spinner = ora('Setting up backup target...').start();
@@ -123,8 +138,8 @@ async function setTarget(bm, typeOrArgs, opts) {
       console.log(`  ${chalk.yellow('\u26a0')} ${test.message}`);
     }
 
-    // Remind about password for local targets
-    if (type === 'local' && !bm.hasPassword()) {
+    // Remind about password for encrypted targets
+    if ((type === 'local' || type === 's3' || type === 'cloud') && !bm.hasPassword()) {
       console.log('');
       console.log(chalk.yellow('  \u26a0 Set a password before syncing:'));
       console.log(chalk.dim('  $ clawkeep backup set-password'));
@@ -161,9 +176,10 @@ async function doSetPassword(bm, opts) {
 
 async function doSync(bm, opts) {
   const cfg = bm.getConfig();
-  const password = cfg.target === 'local' ? getPassword(opts) : null;
+  const needsPassword = cfg.target === 'local' || cfg.target === 's3' || cfg.target === 'cloud';
+  const password = needsPassword ? getPassword(opts) : null;
 
-  if (cfg.target === 'local' && !password) {
+  if (needsPassword && !password) {
     console.error(chalk.red('  Password required for encrypted sync.'));
     console.error(chalk.dim('  Use: CLAWKEEP_PASSWORD=xxx clawkeep backup sync'));
     process.exit(1);

package/src/commands/cloud.js

@@ -0,0 +1,292 @@
+'use strict';
+
+const chalk = require('chalk');
+const ora = require('ora');
+const path = require('path');
+const crypto = require('crypto');
+const http = require('http');
+const { exec } = require('child_process');
+const ClawGit = require('../core/git');
+const BackupManager = require('../core/backup');
+const { loadCredentials, saveCredentials, clearCredentials } = require('../core/credentials');
+
+const DEFAULT_ENDPOINT = 'https://clawkeep.com';
+const CALLBACK_TIMEOUT = 120000;
+
+module.exports = async function cloud(subcommand, opts) {
+  if (!subcommand || subcommand === 'setup') {
+    return doSetup(opts);
+  } else if (subcommand === 'status') {
+    return doStatus(opts);
+  } else if (subcommand === 'logout') {
+    return doLogout();
+  } else {
+    console.error(chalk.red(`  Unknown subcommand: ${subcommand}`));
+    console.error(chalk.dim('  Usage: clawkeep cloud [setup|status|logout]'));
+    process.exit(1);
+  }
+};
+
+async function doSetup(opts) {
+  const dir = path.resolve(opts.dir || '.');
+  const endpoint = (opts.endpoint || DEFAULT_ENDPOINT).replace(/\/$/, '');
+  const apiKey = opts.apiKey || process.env.CLAWKEEP_API_KEY;
+  const workspace = opts.workspace;
+
+  // Headless mode: --api-key and --workspace provided directly
+  if (apiKey && workspace) {
+    return doHeadlessSetup(dir, apiKey, workspace, endpoint, opts);
+  }
+
+  // SSH detection
+  if (process.env.SSH_CLIENT && !apiKey) {
+    console.log('');
+    console.log(chalk.yellow('  Detected SSH session. Browser flow may not work.'));
+    console.log(chalk.dim('  Use headless mode instead:'));
+    console.log(chalk.dim('  $ clawkeep cloud setup --api-key ck_live_xxx --workspace ws_xxx'));
+    console.log('');
+    process.exit(1);
+  }
+
+  // Browser callback flow
+  return doBrowserSetup(dir, endpoint, opts);
+}
+
+async function doHeadlessSetup(dir, apiKey, workspace, endpoint, opts) {
+  const spinner = ora('Configuring ClawKeep Cloud...').start();
+  try {
+    // Save global credentials
+    saveCredentials({ apiKey, endpoint });
+
+    // Configure project if initialized
+    const claw = new ClawGit(dir);
+    if (await claw.isInitialized()) {
+      const bm = new BackupManager(claw);
+      await bm.setTarget('cloud', { workspace, endpoint });
+
+      // Set password if provided
+      const password = opts.password || process.env.CLAWKEEP_PASSWORD;
+      if (password && !bm.hasPassword()) {
+        bm.setPassword(password);
+      }
+
+      // Test connection
+      const test = await bm.test();
+      if (test.ok) {
+        spinner.succeed('Connected to ClawKeep Cloud');
+        console.log(`  ${chalk.green('\u2713')} ${test.message}${test.latencyMs ? ` (${test.latencyMs}ms)` : ''}`);
+      } else {
+        spinner.warn('Credentials saved but connection test failed');
+        console.log(`  ${chalk.yellow('\u26a0')} ${test.message}`);
+      }
+    } else {
+      spinner.succeed('Credentials saved');
+      console.log(chalk.dim('  Run `clawkeep init` in a project directory, then `clawkeep cloud setup` again.'));
+    }
+
+    console.log('');
+    console.log(`  ${chalk.dim('API Key')}    ${maskKey(apiKey)}`);
+    console.log(`  ${chalk.dim('Workspace')}  ${workspace}`);
+    console.log(`  ${chalk.dim('Endpoint')}   ${endpoint}`);
+    console.log('');
+  } catch (err) {
+    spinner.fail('Setup failed');
+    console.error(chalk.red('  ' + err.message));
+    process.exit(1);
+  }
+}
+
+async function doBrowserSetup(dir, endpoint, opts) {
+  const state = crypto.randomBytes(24).toString('hex');
+
+  console.log('');
+  console.log(chalk.bold.cyan('  \ud83d\udc3e ClawKeep Cloud Setup'));
+  console.log('');
+
+  // Start temporary callback server
+  const { port, promise } = await startCallbackServer(state);
+
+  // Build connect URL
+  const dirName = path.basename(path.resolve(dir));
+  const connectUrl = `${endpoint}/connect?callback_port=${port}&state=${state}&dir_name=${encodeURIComponent(dirName)}`;
+
+  console.log(chalk.dim('  Opening browser...'));
+  console.log('');
+  console.log(`  ${chalk.dim('If it doesn\'t open, visit:')} `);
+  console.log(`  ${chalk.cyan(connectUrl)}`);
+  console.log('');
+
+  // Open browser
+  openBrowser(connectUrl);
+
+  const spinner = ora('Waiting for browser authorization...').start();
+
+  try {
+    const result = await promise;
+    spinner.succeed('Authorization received');
+
+    // Save credentials
+    saveCredentials({ apiKey: result.apiKey, endpoint });
+
+    // Configure project
+    const claw = new ClawGit(dir);
+    if (await claw.isInitialized()) {
+      const bm = new BackupManager(claw);
+      await bm.setTarget('cloud', { workspace: result.workspace, endpoint });
+
+      const password = opts.password || process.env.CLAWKEEP_PASSWORD;
+      if (password && !bm.hasPassword()) {
+        bm.setPassword(password);
+      }
+
+      const test = await bm.test();
+      if (test.ok) {
+        console.log(`  ${chalk.green('\u2713')} ${test.message}${test.latencyMs ? ` (${test.latencyMs}ms)` : ''}`);
+      }
+
+      if (!bm.hasPassword()) {
+        console.log('');
+        console.log(chalk.yellow('  \u26a0 Set a password before syncing:'));
+        console.log(chalk.dim('  $ clawkeep backup set-password'));
+      }
+    }
+
+    console.log('');
+    console.log(`  ${chalk.dim('Workspace')}  ${result.workspace}`);
+    console.log('');
+  } catch (err) {
+    spinner.fail(err.message || 'Setup failed');
+    process.exit(1);
+  }
+}
+
+function startCallbackServer(expectedState) {
+  return new Promise((resolveSetup) => {
+    let settled = false;
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, 'http://localhost');
+      if (url.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+
+      const apiKey = url.searchParams.get('api_key');
+      const workspace = url.searchParams.get('workspace');
+      const state = url.searchParams.get('state');
+
+      if (state !== expectedState) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h2>Error: Invalid state parameter</h2><p>Please try again from the CLI.</p></body></html>');
+        return;
+      }
+
+      if (!apiKey || !workspace) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h2>Error: Missing parameters</h2><p>Please try again from the CLI.</p></body></html>');
+        return;
+      }
+
+      // Success
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`<html><body style="font-family:system-ui;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#0a0a0a;color:#fafafa">
+        <div style="text-align:center">
+          <h1 style="font-size:3rem;margin-bottom:0.5rem">\u2713</h1>
+          <h2>Connected!</h2>
+          <p style="color:#888">You can close this tab and return to the terminal.</p>
+        </div>
+      </body></html>`);
+
+      settled = true;
+      server.close();
+      resolveResult({ apiKey, workspace });
+    });
+
+    let resolveResult;
+    const resultPromise = new Promise((resolve, reject) => {
+      resolveResult = resolve;
+
+      // Timeout
+      setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          server.close();
+          reject(new Error('Timed out waiting for browser authorization (120s)'));
+        }
+      }, CALLBACK_TIMEOUT);
+    });
+
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      resolveSetup({ port, promise: resultPromise });
+    });
+  });
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+  if (platform === 'darwin') {
+    cmd = `open "${url}"`;
+  } else if (platform === 'win32') {
+    cmd = `start "" "${url}"`;
+  } else {
+    cmd = `xdg-open "${url}"`;
+  }
+  exec(cmd, () => {});
+}
+
+async function doStatus(opts) {
+  const creds = loadCredentials();
+  const dir = path.resolve(opts.dir || '.');
+
+  console.log('');
+  console.log(chalk.bold('  ClawKeep Cloud'));
+  console.log('');
+
+  if (!creds) {
+    console.log(`  ${chalk.yellow('\u25cf')} Not connected`);
+    console.log('');
+    console.log(chalk.dim('  Run: clawkeep cloud setup'));
+    console.log('');
+    return;
+  }
+
+  console.log(`  ${chalk.dim('API Key')}    ${maskKey(creds.apiKey)}`);
+  console.log(`  ${chalk.dim('Endpoint')}   ${creds.endpoint}`);
+
+  // Show project-level info if initialized
+  try {
+    const claw = new ClawGit(dir);
+    if (await claw.isInitialized()) {
+      const bm = new BackupManager(claw);
+      const cfg = bm.getConfig();
+      if (cfg.target === 'cloud') {
+        console.log(`  ${chalk.dim('Workspace')}  ${cfg.workspaceId}`);
+        console.log(`  ${chalk.dim('Last sync')}  ${cfg.lastSync || 'never'}`);
+        console.log(`  ${chalk.dim('Encrypted')}  ${cfg.passwordSet ? chalk.green('\u2713 yes') : chalk.yellow('\u26a0 no password set')}`);
+      } else {
+        console.log('');
+        console.log(chalk.dim('  This project is not targeting cloud. Run `clawkeep cloud setup` in this directory.'));
+      }
+    }
+  } catch {
+    // Not initialized, just show global info
+  }
+  console.log('');
+}
+
+async function doLogout() {
+  clearCredentials();
+  console.log('');
+  console.log(chalk.green('  \u2713 Logged out of ClawKeep Cloud'));
+  console.log(chalk.dim('  Credentials removed. Project backup configs unchanged.'));
+  console.log('');
+}
+
+function maskKey(key) {
+  if (!key) return chalk.dim('none');
+  if (key.length <= 12) return key.slice(0, 4) + '***';
+  return key.slice(0, 12) + '***' + key.slice(-4);
+}

package/src/commands/watch.js

@@ -143,7 +143,7 @@ function startWatcher(claw, dir, interval, autoPush, quiet) {
         if (config.backup && config.backup.autoSync && config.backup.target) {
           try {
             const bm = new BackupManager(claw);
-            await bm.sync();
+            await bm.sync(process.env.CLAWKEEP_PASSWORD || null);
             if (!quiet) console.log(`  ${chalk.dim(now)} ${chalk.blue('↑')} ${chalk.dim('synced to ' + (config.backup.targetLabel || config.backup.target))}`);
           } catch (syncErr) {
             if (!quiet) console.log(`  ${chalk.dim(now)} ${chalk.yellow('⚠')} ${chalk.dim('sync failed: ' + syncErr.message)}`);

package/src/core/backup.js

@@ -106,10 +106,25 @@ class BackupManager {
       await this.claw.setRemote(options.url);
     } else if (type === 's3') {
       config.backup.s3 = {
-        bucket: options.bucket || null,
-        prefix: options.prefix || null,
-        region: options.region || null,
+        endpoint: options.endpoint,
+        bucket: options.bucket,
+        region: options.region || 'auto',
+        accessKey: options.accessKey,
+        secretKey: options.secretKey,
+        prefix: options.prefix || '',
       };
+      // Generate workspace ID if not set
+      if (!config.backup.workspaceId) {
+        const dirname = path.basename(this.dir);
+        const suffix = crypto.randomBytes(4).toString('hex');
+        config.backup.workspaceId = dirname + '-' + suffix;
+      }
+    } else if (type === 'cloud') {
+      config.backup.cloud = {
+        workspace: options.workspace,
+        endpoint: options.endpoint || 'https://api.clawkeep.com',
+      };
+      config.backup.workspaceId = options.workspace;
     }
 
     this.claw.saveConfig(config);
@@ -125,8 +140,8 @@ class BackupManager {
     if (!target) throw new Error('No backup target configured');
 
     let result;
-    if (target === 'local') {
-      // Encrypted incremental sync
+    if (target === 'local' || target === 's3' || target === 'cloud') {
+      // Encrypted incremental sync (local, S3, or cloud)
       if (!password) throw new Error('Password required for encrypted sync');
       const transport = createTransport(backup, this.claw);
       const sm = new SyncManager(this.claw, transport, password);
@@ -134,10 +149,6 @@ class BackupManager {
     } else if (target === 'git') {
       await this.claw.push();
       result = { ok: true, target: 'git', synced: true };
-    } else if (target === 'cloud') {
-      throw new Error('ClawKeep Cloud is coming soon');
-    } else if (target === 's3') {
-      throw new Error('S3 backup is not yet implemented');
     }
 
     // Reload config (SyncManager may have saved changes)
@@ -195,9 +206,32 @@ class BackupManager {
         return { ok: false, message: 'Remote unreachable: ' + e.message };
       }
     } else if (target === 'cloud') {
-      return { ok: false, message: 'ClawKeep Cloud is coming soon' };
+      try {
+        const transport = createTransport(backup, this.claw);
+        await transport._ensureCredentials();
+        return { ok: true, message: 'Connected to ClawKeep Cloud', latencyMs: Date.now() - start };
+      } catch (e) {
+        return { ok: false, message: 'Cloud unreachable: ' + e.message };
+      }
     } else if (target === 's3') {
-      return { ok: false, message: 'S3 backup not yet implemented' };
+      const s3Config = backup.s3;
+      if (!s3Config?.endpoint || !s3Config?.bucket) {
+        return { ok: false, message: 'S3 not fully configured' };
+      }
+      try {
+        const S3Client = require('./s3-client');
+        const s3 = new S3Client({
+          endpoint: s3Config.endpoint,
+          bucket: s3Config.bucket,
+          region: s3Config.region || 'auto',
+          accessKey: s3Config.accessKey || process.env.CLAWKEEP_S3_ACCESS_KEY,
+          secretKey: s3Config.secretKey || process.env.CLAWKEEP_S3_SECRET_KEY,
+        });
+        await s3.listObjects('');
+        return { ok: true, message: 'Connected', latencyMs: Date.now() - start };
+      } catch (e) {
+        return { ok: false, message: 'S3 unreachable: ' + e.message };
+      }
     }
 
     return { ok: false, message: 'Unknown target: ' + target };
@@ -207,7 +241,9 @@ class BackupManager {
   async compact(password) {
     const config = this.claw.loadConfig();
     const backup = config.backup || {};
-    if (backup.target !== 'local') throw new Error('Compact only supported for local target');
+    if (backup.target !== 'local' && backup.target !== 's3' && backup.target !== 'cloud') {
+      throw new Error('Compact only supported for local, s3, and cloud targets');
+    }
     if (!password) throw new Error('Password required for compact');
 
     const transport = createTransport(backup, this.claw);
@@ -219,7 +255,7 @@ class BackupManager {
   async getSyncStatus(password) {
     const config = this.claw.loadConfig();
     const backup = config.backup || {};
-    if (backup.target !== 'local' || !password) {
+    if ((backup.target !== 'local' && backup.target !== 's3' && backup.target !== 'cloud') || !password) {
       return {
         synced: false,
         chunkCount: backup.chunkCount || 0,

package/src/core/credentials.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Mutable for testing
+let _credsDir = path.join(os.homedir(), '.clawkeep');
+let _credsFile = path.join(_credsDir, 'credentials.json');
+
+function _getDir() { return _credsDir; }
+function _getFile() { return _credsFile; }
+
+/**
+ * Load global credentials (API key + endpoint).
+ * Returns null if no credentials file or corrupted JSON.
+ */
+function loadCredentials() {
+  try {
+    if (!fs.existsSync(_getFile())) return null;
+    const data = JSON.parse(fs.readFileSync(_getFile(), 'utf8'));
+    if (!data.apiKey) return null;
+    return {
+      apiKey: data.apiKey,
+      endpoint: data.endpoint || 'https://api.clawkeep.com',
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save global credentials.
+ * @param {{ apiKey: string, endpoint?: string }} creds
+ */
+function saveCredentials(creds) {
+  if (!fs.existsSync(_getDir())) {
+    fs.mkdirSync(_getDir(), { recursive: true, mode: 0o700 });
+  }
+  const data = {
+    apiKey: creds.apiKey,
+    endpoint: creds.endpoint || 'https://api.clawkeep.com',
+  };
+  fs.writeFileSync(_getFile(), JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+}
+
+/**
+ * Remove global credentials file.
+ */
+function clearCredentials() {
+  try {
+    if (fs.existsSync(_getFile())) fs.unlinkSync(_getFile());
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Override paths for testing.
+ */
+function _setTestPaths(dir, file) {
+  _credsDir = dir;
+  _credsFile = file;
+}
+
+module.exports = { loadCredentials, saveCredentials, clearCredentials, _setTestPaths };

package/src/core/s3-client.js

@@ -0,0 +1,234 @@
+'use strict';
+
+const crypto = require('crypto');
+const https = require('https');
+const http = require('http');
+
+const EMPTY_HASH = crypto.createHash('sha256').update('').digest('hex');
+
+/**
+ * Lightweight S3 client with AWS Signature V4 signing.
+ * Zero external dependencies — uses Node.js built-in crypto + https.
+ * Works with: Cloudflare R2, AWS S3, Backblaze B2, MinIO, Wasabi.
+ */
+class S3Client {
+  constructor({ endpoint, bucket, region, accessKey, secretKey }) {
+    this.endpoint = endpoint.replace(/\/$/, '');
+    this.bucket = bucket;
+    this.region = region || 'auto';
+    this.accessKey = accessKey;
+    this.secretKey = secretKey;
+
+    const url = new URL(this.endpoint);
+    this.host = url.host;
+    this.isHttps = url.protocol === 'https:';
+  }
+
+  // --- AWS Signature V4 ---
+
+  _sha256(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+  }
+
+  _hmac(key, data) {
+    return crypto.createHmac('sha256', key).update(data).digest();
+  }
+
+  _signingKey(dateStamp) {
+    const kDate = this._hmac('AWS4' + this.secretKey, dateStamp);
+    const kRegion = this._hmac(kDate, this.region);
+    const kService = this._hmac(kRegion, 's3');
+    return this._hmac(kService, 'aws4_request');
+  }
+
+  _encodePath(p) {
+    return p.split('/').map(s => encodeURIComponent(s)).join('/');
+  }
+
+  _sign(method, objectPath, query, headers, payloadHash) {
+    const now = new Date();
+    const dateStamp = now.toISOString().slice(0, 10).replace(/-/g, '');
+    const amzDate = dateStamp + 'T' +
+      now.toISOString().slice(11, 19).replace(/:/g, '') + 'Z';
+
+    headers['x-amz-date'] = amzDate;
+    headers['x-amz-content-sha256'] = payloadHash;
+
+    // Sort headers by lowercase name
+    const sorted = Object.keys(headers)
+      .map(k => [k.toLowerCase(), headers[k]])
+      .sort(([a], [b]) => a.localeCompare(b));
+
+    const signedHeaders = sorted.map(([k]) => k).join(';');
+    const canonicalHeaders = sorted
+      .map(([k, v]) => k + ':' + String(v).trim())
+      .join('\n') + '\n';
+
+    // Query string (sorted by key)
+    let canonicalQuery = '';
+    if (query && Object.keys(query).length > 0) {
+      canonicalQuery = Object.entries(query)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => encodeURIComponent(k) + '=' + encodeURIComponent(v))
+        .join('&');
+    }
+
+    const canonicalRequest = [
+      method,
+      this._encodePath(objectPath),
+      canonicalQuery,
+      canonicalHeaders,
+      signedHeaders,
+      payloadHash,
+    ].join('\n');
+
+    const scope = dateStamp + '/' + this.region + '/s3/aws4_request';
+    const stringToSign = [
+      'AWS4-HMAC-SHA256',
+      amzDate,
+      scope,
+      this._sha256(canonicalRequest),
+    ].join('\n');
+
+    const signature = this._hmac(this._signingKey(dateStamp), stringToSign)
+      .toString('hex');
+
+    headers['authorization'] =
+      'AWS4-HMAC-SHA256 Credential=' + this.accessKey + '/' + scope +
+      ', SignedHeaders=' + signedHeaders +
+      ', Signature=' + signature;
+
+    return canonicalQuery;
+  }
+
+  // --- HTTP ---
+
+  async _request(method, key, opts = {}) {
+    const { query, body, headers: extra, retries = 3 } = opts;
+
+    const objectPath = key
+      ? '/' + this.bucket + '/' + key
+      : '/' + this.bucket;
+
+    const payloadHash = body ? this._sha256(body) : EMPTY_HASH;
+
+    const headers = { host: this.host, ...(extra || {}) };
+    if (body) {
+      headers['content-length'] = String(Buffer.byteLength(body));
+    }
+
+    const canonicalQuery = this._sign(method, objectPath, query, headers, payloadHash);
+    const urlStr = this.endpoint + objectPath +
+      (canonicalQuery ? '?' + canonicalQuery : '');
+
+    let lastError;
+    for (let attempt = 0; attempt < retries; attempt++) {
+      if (attempt > 0) {
+        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 500));
+      }
+      try {
+        const result = await this._doRequest(method, urlStr, headers, body);
+        if (result.statusCode >= 500 || result.statusCode === 429) {
+          lastError = new Error(`S3 ${method} ${key || '/'}: HTTP ${result.statusCode}`);
+          continue;
+        }
+        return result;
+      } catch (err) {
+        lastError = err;
+      }
+    }
+    throw lastError;
+  }
+
+  _doRequest(method, url, headers, body) {
+    return new Promise((resolve, reject) => {
+      const mod = this.isHttps ? https : http;
+      const req = mod.request(url, { method, headers }, (res) => {
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => {
+          resolve({
+            statusCode: res.statusCode,
+            headers: res.headers,
+            body: Buffer.concat(chunks),
+          });
+        });
+      });
+      req.on('error', reject);
+      req.setTimeout(60000, () => req.destroy(new Error('Request timeout')));
+      if (body) req.write(body);
+      req.end();
+    });
+  }
+
+  // --- S3 Operations ---
+
+  async putObject(key, body, contentType = 'application/octet-stream') {
+    const buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
+    const res = await this._request('PUT', key, {
+      body: buf,
+      headers: { 'content-type': contentType },
+    });
+    if (res.statusCode >= 300) throw this._error('PUT', key, res);
+    return { etag: res.headers['etag'] };
+  }
+
+  async getObject(key) {
+    const res = await this._request('GET', key);
+    if (res.statusCode >= 300) throw this._error('GET', key, res);
+    return res.body;
+  }
+
+  async headObject(key) {
+    const res = await this._request('HEAD', key, { retries: 1 });
+    if (res.statusCode === 404) return null;
+    if (res.statusCode >= 300) throw this._error('HEAD', key, res);
+    return {
+      size: parseInt(res.headers['content-length']) || 0,
+      lastModified: res.headers['last-modified'],
+      etag: res.headers['etag'],
+    };
+  }
+
+  async listObjects(prefix) {
+    const res = await this._request('GET', '', {
+      query: { 'list-type': '2', prefix: prefix || '' },
+    });
+    if (res.statusCode >= 300) throw this._error('LIST', prefix || '/', res);
+    return this._parseList(res.body.toString('utf8'));
+  }
+
+  async deleteObject(key) {
+    const res = await this._request('DELETE', key);
+    if (res.statusCode >= 300 && res.statusCode !== 404) {
+      throw this._error('DELETE', key, res);
+    }
+  }
+
+  // --- Helpers ---
+
+  _error(op, key, res) {
+    const body = res.body ? res.body.toString('utf8') : '';
+    const code = (body.match(/<Code>(.*?)<\/Code>/) || [])[1] || '';
+    const message = (body.match(/<Message>(.*?)<\/Message>/) || [])[1] || '';
+    const detail = code ? `${code}: ${message}` : `HTTP ${res.statusCode}`;
+    return new Error(`S3 ${op} ${key || '/'} failed \u2014 ${detail}`);
+  }
+
+  _parseList(xml) {
+    const objects = [];
+    const re = /<Contents>([\s\S]*?)<\/Contents>/g;
+    let m;
+    while ((m = re.exec(xml)) !== null) {
+      const c = m[1];
+      objects.push({
+        Key: (c.match(/<Key>(.*?)<\/Key>/) || [])[1] || '',
+        Size: parseInt((c.match(/<Size>(.*?)<\/Size>/) || [])[1] || '0'),
+        LastModified: (c.match(/<LastModified>(.*?)<\/LastModified>/) || [])[1] || '',
+      });
+    }
+    return objects;
+  }
+}
+
+module.exports = S3Client;

package/src/core/transport.js

@@ -2,6 +2,8 @@
 
 const fs = require('fs');
 const path = require('path');
+const https = require('https');
+const http = require('http');
 
 /**
  * Base transport interface for backup targets.
@@ -59,6 +61,144 @@ class LocalTransport extends BackupTransport {
   }
 }
 
+/**
+ * S3 transport — works with any S3-compatible service.
+ * Cloudflare R2, AWS S3, Backblaze B2, MinIO, Wasabi.
+ */
+class S3Transport extends BackupTransport {
+  constructor(s3Client, prefix) {
+    super();
+    this.s3 = s3Client;
+    this.prefix = prefix || '';
+  }
+
+  async writeFile(remotePath, buffer) {
+    await this.s3.putObject(this.prefix + remotePath, buffer);
+  }
+
+  async readFile(remotePath) {
+    return await this.s3.getObject(this.prefix + remotePath);
+  }
+
+  async deleteFile(remotePath) {
+    await this.s3.deleteObject(this.prefix + remotePath);
+  }
+
+  async listFiles(remoteDir) {
+    const prefix = this.prefix + remoteDir + (remoteDir.endsWith('/') ? '' : '/');
+    const objects = await this.s3.listObjects(prefix);
+    return objects
+      .map(obj => {
+        const key = obj.Key;
+        return key.startsWith(prefix) ? key.slice(prefix.length) : key;
+      })
+      .filter(f => f && !f.includes('/'));
+  }
+
+  async exists(remotePath) {
+    const head = await this.s3.headObject(this.prefix + remotePath);
+    return head !== null;
+  }
+}
+
+/**
+ * Cloud transport — wraps S3Transport with auto-fetched R2 credentials.
+ * Credentials are fetched from the ClawKeep Cloud API and cached until near-expiry.
+ */
+class CloudTransport extends BackupTransport {
+  constructor({ apiKey, workspace, endpoint }) {
+    super();
+    this.apiKey = apiKey;
+    this.workspace = workspace;
+    this.endpoint = (endpoint || 'https://api.clawkeep.com').replace(/\/$/, '');
+    this._inner = null;
+    this._credsExpiry = 0;
+  }
+
+  async _fetchCredentials() {
+    const url = `${this.endpoint}/api/workspaces/${this.workspace}/credentials`;
+    return new Promise((resolve, reject) => {
+      const parsed = new URL(url);
+      const mod = parsed.protocol === 'https:' ? https : http;
+      const req = mod.request(url, {
+        method: 'GET',
+        headers: {
+          'Authorization': 'Bearer ' + this.apiKey,
+          'Accept': 'application/json',
+        },
+      }, (res) => {
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => {
+          const body = Buffer.concat(chunks).toString('utf8');
+          if (res.statusCode >= 400) {
+            let msg = `Cloud API error: HTTP ${res.statusCode}`;
+            try { msg = JSON.parse(body).error?.message || msg; } catch {}
+            reject(new Error(msg));
+            return;
+          }
+          try {
+            resolve(JSON.parse(body));
+          } catch {
+            reject(new Error('Invalid JSON from cloud API'));
+          }
+        });
+      });
+      req.on('error', reject);
+      req.setTimeout(30000, () => req.destroy(new Error('Cloud API request timeout')));
+      req.end();
+    });
+  }
+
+  async _ensureCredentials() {
+    // Refresh if no inner transport or within 1 hour of expiry
+    const now = Date.now();
+    if (this._inner && this._credsExpiry - now > 3600000) return;
+
+    const data = await this._fetchCredentials();
+    const creds = data.credentials || data;
+
+    const S3Client = require('./s3-client');
+    const s3 = new S3Client({
+      endpoint: creds.endpoint,
+      bucket: creds.bucket,
+      region: creds.region || 'auto',
+      accessKey: creds.access_key_id,
+      secretKey: creds.secret_access_key,
+    });
+    this._inner = new S3Transport(s3, creds.prefix || `workspaces/${this.workspace}/`);
+    const expiresAt = creds.expires_at || data.expires_at;
+    this._credsExpiry = expiresAt
+      ? new Date(expiresAt).getTime()
+      : now + 3600000;
+  }
+
+  async writeFile(remotePath, buffer) {
+    await this._ensureCredentials();
+    return this._inner.writeFile(remotePath, buffer);
+  }
+
+  async readFile(remotePath) {
+    await this._ensureCredentials();
+    return this._inner.readFile(remotePath);
+  }
+
+  async deleteFile(remotePath) {
+    await this._ensureCredentials();
+    return this._inner.deleteFile(remotePath);
+  }
+
+  async listFiles(remoteDir) {
+    await this._ensureCredentials();
+    return this._inner.listFiles(remoteDir);
+  }
+
+  async exists(remotePath) {
+    await this._ensureCredentials();
+    return this._inner.exists(remotePath);
+  }
+}
+
 /**
  * Git remote transport — uses native git push/pull.
  * No chunks needed; git handles incremental natively.
@@ -91,12 +231,29 @@ function createTransport(backupConfig, clawGit) {
     return new GitTransport(clawGit);
   }
   if (target === 'cloud') {
-    throw new Error('ClawKeep Cloud is coming soon');
+    const { loadCredentials } = require('./credentials');
+    const creds = loadCredentials();
+    const apiKey = process.env.CLAWKEEP_API_KEY || creds?.apiKey;
+    const endpoint = backupConfig.cloud?.endpoint || creds?.endpoint || 'https://api.clawkeep.com';
+    const workspace = backupConfig.workspaceId;
+    if (!apiKey) throw new Error('No API key found. Run `clawkeep cloud setup` or set CLAWKEEP_API_KEY');
+    if (!workspace) throw new Error('No workspace configured. Run `clawkeep cloud setup`');
+    return new CloudTransport({ apiKey, workspace, endpoint });
   }
   if (target === 's3') {
-    throw new Error('S3 backup is not yet implemented');
+    const s3Config = backupConfig.s3;
+    if (!s3Config) throw new Error('No S3 config found');
+    const S3Client = require('./s3-client');
+    const s3 = new S3Client({
+      endpoint: s3Config.endpoint,
+      bucket: s3Config.bucket,
+      region: s3Config.region || 'auto',
+      accessKey: s3Config.accessKey || process.env.CLAWKEEP_S3_ACCESS_KEY,
+      secretKey: s3Config.secretKey || process.env.CLAWKEEP_S3_SECRET_KEY,
+    });
+    return new S3Transport(s3, s3Config.prefix || '');
   }
   throw new Error('Unknown target: ' + target);
 }
 
-module.exports = { BackupTransport, LocalTransport, GitTransport, createTransport };
+module.exports = { BackupTransport, LocalTransport, S3Transport, CloudTransport, GitTransport, createTransport };