lsh-framework 3.2.5 → 3.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 gwicho38
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,10 @@
-# LSH v3.1.19 - Encrypted Secrets Manager
+# LSH — Encrypted Secrets Manager
 
 **The simplest way to sync `.env` files across all your machines.**
 
-`lsh` is an encrypted secrets manager that syncs your environment files across development machines with AES-256 encryption via the IPFS network. Push once, pull anywhere.
+`lsh` is an encrypted secrets manager that syncs your environment files across development machines with AES-256 encryption over the IPFS network. Secrets are encrypted locally, addressed by content (CID), and published under a deterministic IPNS name derived from your shared key — so a teammate with the same key can pull the latest version with no account or server.
+
+> **Durability note:** by default the encrypted content is pinned **only on the machine that pushed it** and served peer-to-peer. Another machine can pull as long as a node that holds the content is online and the IPNS record is still live. For "pull anywhere, anytime" durability, configure a remote pinning service (see [Durable sync](#durable-sync-remote-pinning)).
 
 [![npm version](https://badge.fury.io/js/lsh-framework.svg)](https://badge.fury.io/js/lsh-framework)
 [![Node.js CI](https://github.com/gwicho38/lsh/actions/workflows/node.js.yml/badge.svg)](https://github.com/gwicho38/lsh/actions/workflows/node.js.yml)
@@ -71,25 +73,49 @@ lsh pull --env staging
 ## How It Works
 
 ```
-Your Machine                    Storacha (IPFS Network)
-┌─────────────┐                 ┌─────────────────────┐
-│   .env      │   AES-256       │  Encrypted Blob     │
-│  (secrets)  │ ───encrypt───►  │  (content-addressed)│
-└─────────────┘                 └─────────────────────┘
-                                         │
-                                         ▼
-Another Machine                 ┌─────────────────────┐
-┌─────────────┐   AES-256       │  Registry           │
-│   .env      │ ◄──decrypt────  │  (points to blob)   │
-│  (secrets)  │                 └─────────────────────┘
-└─────────────┘
+Machine A (push)                Local Kubo (IPFS) node          IPFS DHT / swarm
+┌─────────────┐   AES-256       ┌─────────────────────┐         ┌──────────────────┐
+│   .env      │ ───encrypt───►  │ ipfs add (pin local)│ ──────► │ IPNS record:     │
+│  (secrets)  │                 │  → CID              │ publish │  name → CID      │
+└─────────────┘                 └─────────────────────┘         │ (key-derived)    │
+                                                                 └──────────────────┘
+                                                                          │ resolve
+Machine B (pull)                                                          ▼
+┌─────────────┐   AES-256       ┌─────────────────────┐  fetch   ┌──────────────────┐
+│   .env      │ ◄──decrypt────  │ ipfs cat <CID>      │ ◄─────── │ a node holding   │
+│  (secrets)  │                 └─────────────────────┘  swarm   │ the block (A or  │
+└─────────────┘                                                  │ a pinning svc)   │
+                                                                 └──────────────────┘
 ```
 
-1. Your `.env` is encrypted locally with AES-256
-2. Encrypted data uploads to IPFS via Storacha
-3. A registry tracks the latest version per repository
-4. Other machines pull via the content ID (CID)
-5. Decryption happens locally with your shared key
+1. Your `.env` is encrypted locally with AES-256 (the key never leaves the machine).
+2. The ciphertext is added to your **local Kubo (IPFS) daemon** and pinned there, producing a content ID (CID).
+3. The CID is published to **IPNS** under a name derived deterministically from `LSH_SECRETS_KEY` + repo + environment (`HMAC-SHA256`), so teammates need only the shared key.
+4. Another machine derives the same IPNS name, resolves it to the latest CID over the network, and fetches the ciphertext over the IPFS swarm.
+5. Decryption happens locally with the shared key.
+
+**What this means:** the encrypted block is only guaranteed to exist where it was pushed. Cross-machine pull works while a node holding the block is online (the publisher, a peer that cached it, or — recommended — a [remote pinning service](#durable-sync-remote-pinning)).
+
+## Durable sync (remote pinning)
+
+Out of the box, `lsh sync` is zero-config but **not durable**: the encrypted content lives only on the machine that pushed it. If that machine sleeps or goes offline before a teammate pulls — and no peer has cached the block — the pull will stall. `lsh sync push` warns you when no durable pin is configured.
+
+To make secrets available "anytime, anywhere", point `lsh` at any IPFS **remote pinning service** (Pinata, Filebase, 4EVERLAND, web3.storage, an IPFS Cluster, etc.). `lsh` uses your local Kubo daemon's remote-pinning support — no extra dependency, and your encryption key never leaves your machine (the service only ever stores ciphertext).
+
+```bash
+# 1. Register a pinning service with your local Kubo daemon (one-time)
+ipfs pin remote service add pinata https://api.pinata.cloud/psa <YOUR_JWT>
+
+# 2. Tell lsh which service to use (only needed if more than one is configured)
+export LSH_SECRETS_KEY=<your-key>
+export LSH_PIN_SERVICE=pinata
+
+# 3. Push — content is now pinned remotely and survives this machine going offline
+lsh sync push --env dev
+# → "Pinned: pinata (durable)"
+```
+
+If exactly one remote service is configured, `lsh` uses it automatically and `LSH_PIN_SERVICE` is optional.
 
 ## Installation
 
@@ -138,16 +164,18 @@ lsh pull
 # 1. Install LSH
 npm install -g lsh-framework
 
-# 2. Authenticate with Storacha (one-time)
-lsh storacha login your@email.com
+# 2. Install + start a local IPFS (Kubo) daemon (one-time)
+lsh sync init
 
-# 3. Add your encryption key
+# 3. Add your encryption key (shared with your other machines / team)
 echo "LSH_SECRETS_KEY=your-shared-key" > .env
 
-# 4. Pull secrets
-lsh pull
+# 4. Pull secrets (resolves the latest version via IPNS)
+lsh sync pull
 ```
 
+> Requires a local IPFS (Kubo) daemon — `lsh sync init` installs and starts one. The pushing machine must be online (or a pinning service configured) for others to fetch the content.
+
 ## Multi-Environment Support
 
 ```bash
@@ -215,10 +243,10 @@ eval "$(lsh list --format export)"
 
 ## Security
 
-- **AES-256-CBC** encryption for all secrets
+- **AES-256** encryption for all secrets (the key never leaves your machine)
 - **Content-addressed storage** - tamper-proof IPFS CIDs
-- **Zero-knowledge** - Storacha never sees your unencrypted data
-- **Local-first** - Works offline with cached secrets
+- **Zero-knowledge** - the IPFS network (and any pinning service) only ever sees ciphertext
+- **Local-first** - works offline with cached secrets
 
 ### Best Practices
 
@@ -258,16 +286,25 @@ lsh key
 lsh push --force
 ```
 
-### "Storacha authentication required"
+### Pull hangs or "Could not resolve secrets from network"
+
+The IPNS name resolved but no online node is serving the content (or the IPNS record expired). Either:
 
 ```bash
-lsh storacha login your@email.com
-# Check email for verification
+# On the machine that pushed: make sure its daemon is running, then re-push
+lsh sync status
+lsh sync push --env dev
+
+# Better: configure a remote pinning service so content stays available
+# even when the pushing machine is offline (see "Durable sync" below)
 ```
 
-### Pull fails after clearing metadata
+### "IPFS daemon not running"
 
-v3.0.0 fix: Pull now automatically checks the Storacha registry when local metadata is missing.
+```bash
+lsh sync init     # install + start a local Kubo daemon
+lsh sync status   # verify it is up
+```
 
 ```bash
 # If secrets were pushed before, pull should auto-recover
@@ -314,8 +351,9 @@ lsh -i
 # Required
 LSH_SECRETS_KEY=<your-encryption-key>
 
-# Optional - Storacha (default enabled)
-LSH_STORACHA_ENABLED=true
+# Optional - name of a kubo remote pinning service for durable sync
+# (configure once with: ipfs pin remote service add <name> <endpoint> <key>)
+LSH_PIN_SERVICE=<service-name>
 
 # Optional - Supabase backend
 SUPABASE_URL=https://xxx.supabase.co

package/dist/commands/ipfs.js

@@ -9,6 +9,7 @@ import { getIPFSSync } from '../lib/ipfs-sync.js';
 import { deriveKeyInfo, ensureKeyImported } from '../lib/ipns-key-manager.js';
 import { getGitRepoInfo } from '../lib/git-utils.js';
 import { ENV_VARS, DEFAULTS } from '../constants/index.js';
+import { extractErrorMessage } from '../lib/lsh-error.js';
 /**
  * Register IPFS commands
  */
@@ -107,8 +108,7 @@ export function registerIPFSCommands(program) {
             console.log('');
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('\n❌ Failed to check status:'), err.message);
+            console.error(chalk.red('\n❌ Failed to check status:'), extractErrorMessage(error));
             process.exit(1);
         }
     });
@@ -134,9 +134,8 @@ export function registerIPFSCommands(program) {
             console.log('');
         }
         catch (error) {
-            const err = error;
             spinner.fail(chalk.red('Installation failed'));
-            console.error(chalk.red(err.message));
+            console.error(chalk.red(extractErrorMessage(error)));
             process.exit(1);
         }
     });
@@ -150,8 +149,7 @@ export function registerIPFSCommands(program) {
             await manager.uninstall();
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('\n❌ Uninstallation failed:'), err.message);
+            console.error(chalk.red('\n❌ Uninstallation failed:'), extractErrorMessage(error));
             process.exit(1);
         }
     });
@@ -171,9 +169,8 @@ export function registerIPFSCommands(program) {
             console.log('');
         }
         catch (error) {
-            const err = error;
             spinner.fail(chalk.red('Initialization failed'));
-            console.error(chalk.red(err.message));
+            console.error(chalk.red(extractErrorMessage(error)));
             process.exit(1);
         }
     });
@@ -187,8 +184,7 @@ export function registerIPFSCommands(program) {
             await manager.start();
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('\n❌ Failed to start daemon:'), err.message);
+            console.error(chalk.red('\n❌ Failed to start daemon:'), extractErrorMessage(error));
             process.exit(1);
         }
     });
@@ -202,8 +198,7 @@ export function registerIPFSCommands(program) {
             await manager.stop();
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('\n❌ Failed to stop daemon:'), err.message);
+            console.error(chalk.red('\n❌ Failed to stop daemon:'), extractErrorMessage(error));
             process.exit(1);
         }
     });

package/dist/commands/sync.js

@@ -14,6 +14,7 @@ import { IPFSClientManager } from '../lib/ipfs-client-manager.js';
 import { getGitRepoInfo } from '../lib/git-utils.js';
 import { deriveKeyInfo, ensureKeyImported } from '../lib/ipns-key-manager.js';
 import { ENV_VARS, DEFAULTS } from '../constants/index.js';
+import { extractErrorMessage } from '../lib/lsh-error.js';
 /**
  * Register sync commands
  */
@@ -81,9 +82,8 @@ export function registerSyncCommands(program) {
                 installSpinner.succeed(chalk.green('IPFS client installed'));
             }
             catch (error) {
-                const err = error;
                 installSpinner.fail(chalk.red('Failed to install IPFS'));
-                console.error(chalk.red(err.message));
+                console.error(chalk.red(extractErrorMessage(error)));
                 process.exit(1);
             }
         }
@@ -98,14 +98,14 @@ export function registerSyncCommands(program) {
             initSpinner.succeed(chalk.green('IPFS repository initialized'));
         }
         catch (error) {
-            const err = error;
+            const msg = extractErrorMessage(error);
             // Check if already initialized
-            if (err.message.includes('already') || err.message.includes('exists')) {
+            if (msg.includes('already') || msg.includes('exists')) {
                 initSpinner.succeed(chalk.green('IPFS repository already initialized'));
             }
             else {
                 initSpinner.fail(chalk.red('Failed to initialize IPFS'));
-                console.error(chalk.red(err.message));
+                console.error(chalk.red(msg));
                 process.exit(1);
             }
         }
@@ -116,9 +116,8 @@ export function registerSyncCommands(program) {
             startSpinner.succeed(chalk.green('IPFS daemon started'));
         }
         catch (error) {
-            const err = error;
             startSpinner.fail(chalk.red('Failed to start daemon'));
-            console.error(chalk.red(err.message));
+            console.error(chalk.red(extractErrorMessage(error)));
             process.exit(1);
         }
         // Final status
@@ -148,8 +147,7 @@ export function registerSyncCommands(program) {
             console.log(chalk.green('✓ IPFS daemon running'));
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red(err.message));
+            console.error(chalk.red(extractErrorMessage(error)));
             process.exit(1);
         }
         // Step 2: Read and validate .env file
@@ -228,9 +226,8 @@ export function registerSyncCommands(program) {
             console.log('');
         }
         catch (error) {
-            const err = error;
             uploadSpinner.fail(chalk.red('Sync failed'));
-            console.error(chalk.red(err.message));
+            console.error(chalk.red(extractErrorMessage(error)));
             process.exit(1);
         }
     });
@@ -251,8 +248,7 @@ export function registerSyncCommands(program) {
                 await ipfsManager.ensureDaemonRunning();
             }
             catch (error) {
-                const err = error;
-                spinner.fail(chalk.red(err.message));
+                spinner.fail(chalk.red(extractErrorMessage(error)));
                 process.exit(1);
             }
             // Read .env file
@@ -306,35 +302,59 @@ export function registerSyncCommands(program) {
             spinner.succeed(chalk.green('Uploaded to IPFS!'));
             console.log('');
             console.log(chalk.bold('CID:'), chalk.cyan(cid));
-            // Publish to IPNS
+            const repoName = gitInfo?.repoName || DEFAULTS.DEFAULT_ENVIRONMENT;
+            const env = options.env || DEFAULTS.DEFAULT_ENVIRONMENT;
+            // Publish to IPNS so teammates can `lsh sync pull` without a CID.
+            let ipnsPublished = false;
             if (encryptionKey) {
                 try {
-                    const repoName = gitInfo?.repoName || DEFAULTS.DEFAULT_ENVIRONMENT;
-                    const env = options.env || DEFAULTS.DEFAULT_ENVIRONMENT;
                     const keyInfo = deriveKeyInfo(encryptionKey, repoName, env);
                     const ipnsName = await ensureKeyImported(ipfsSync.getApiUrl(), keyInfo);
                     if (ipnsName) {
                         const publishedName = await ipfsSync.publishToIPNS(cid, keyInfo.keyName);
                         if (publishedName) {
                             console.log(chalk.bold('IPNS:'), chalk.cyan(publishedName));
+                            ipnsPublished = true;
                         }
                     }
                 }
-                catch {
-                    // Non-fatal
+                catch (error) {
+                    console.error(chalk.yellow(`IPNS publish error: ${extractErrorMessage(error)}`));
                 }
             }
+            // Durable remote pin (best-effort): makes the content survive this
+            // machine going offline. No-op unless a pinning service is configured.
+            const pinnedService = await ipfsSync.addRemotePin(cid, `lsh-${repoName}-${env}`);
+            if (pinnedService) {
+                console.log(chalk.bold('Pinned:'), chalk.cyan(`${pinnedService} (durable)`));
+            }
             console.log('');
             console.log(chalk.gray('Teammates can pull with just:'));
             console.log(chalk.cyan('  lsh sync pull'));
             console.log(chalk.gray('Or by specific CID:'));
             console.log(chalk.cyan(`  lsh sync pull ${cid}`));
             console.log('');
+            // Honest durability reporting — do not claim success the user cannot rely on.
+            if (!pinnedService) {
+                console.log(chalk.yellow('⚠️  No remote pin — this content lives ONLY on this machine.'));
+                console.log(chalk.gray('   If this machine goes offline, teammates cannot fetch it.'));
+                console.log(chalk.gray('   Enable durable pinning (one-time):'));
+                console.log(chalk.gray('     ipfs pin remote service add <name> <endpoint> <key>'));
+                console.log(chalk.gray('     export LSH_PIN_SERVICE=<name>'));
+                console.log('');
+            }
+            if (!ipnsPublished) {
+                spinner.warn(chalk.yellow('IPNS publish failed — teammates CANNOT `lsh sync pull` (no CID) until you re-push.'));
+                console.log(chalk.gray(`   They can still pull by explicit CID:  lsh sync pull ${cid}`));
+                console.log('');
+                // The headline promise ("teammates can pull with just: lsh sync pull") failed,
+                // so exit non-zero rather than reporting a success the user cannot rely on.
+                process.exit(1);
+            }
         }
         catch (error) {
-            const err = error;
             spinner.fail(chalk.red('Push failed'));
-            console.error(chalk.red(err.message));
+            console.error(chalk.red(extractErrorMessage(error)));
             process.exit(1);
         }
     });
@@ -357,8 +377,7 @@ export function registerSyncCommands(program) {
                     await ipfsManager.ensureDaemonRunning();
                 }
                 catch (error) {
-                    const err = error;
-                    spinner.fail(chalk.red(err.message));
+                    spinner.fail(chalk.red(extractErrorMessage(error)));
                     process.exit(1);
                 }
                 // Get encryption key
@@ -400,8 +419,7 @@ export function registerSyncCommands(program) {
                 spinner.start('Downloading from IPFS...');
             }
             catch (error) {
-                const err = error;
-                spinner.fail(chalk.red(`IPNS resolution failed: ${err.message}`));
+                spinner.fail(chalk.red(`IPNS resolution failed: ${extractErrorMessage(error)}`));
                 process.exit(1);
             }
         }
@@ -480,9 +498,8 @@ export function registerSyncCommands(program) {
             console.log('');
         }
         catch (error) {
-            const err = error;
             spinner.fail(chalk.red('Pull failed'));
-            console.error(chalk.red(err.message));
+            console.error(chalk.red(extractErrorMessage(error)));
             process.exit(1);
         }
     });
@@ -565,8 +582,7 @@ export function registerSyncCommands(program) {
             console.log('');
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('Failed to check status:'), err.message);
+            console.error(chalk.red('Failed to check status:'), extractErrorMessage(error));
             process.exit(1);
         }
     });
@@ -615,8 +631,7 @@ export function registerSyncCommands(program) {
             console.log('');
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('Failed to get history:'), err.message);
+            console.error(chalk.red('Failed to get history:'), extractErrorMessage(error));
             process.exit(1);
         }
     });
@@ -648,9 +663,8 @@ export function registerSyncCommands(program) {
             }
         }
         catch (error) {
-            const err = error;
             spinner.fail(chalk.red('Verification failed'));
-            console.error(chalk.red(err.message));
+            console.error(chalk.red(extractErrorMessage(error)));
             process.exit(1);
         }
     });
@@ -665,8 +679,7 @@ export function registerSyncCommands(program) {
             console.log(chalk.green('✅ Sync history cleared'));
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('Failed to clear history:'), err.message);
+            console.error(chalk.red('Failed to clear history:'), extractErrorMessage(error));
             process.exit(1);
         }
     });
@@ -690,8 +703,7 @@ export function registerSyncCommands(program) {
             await manager.start();
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('Failed to start daemon:'), err.message);
+            console.error(chalk.red('Failed to start daemon:'), extractErrorMessage(error));
             process.exit(1);
         }
     });
@@ -705,8 +717,7 @@ export function registerSyncCommands(program) {
             await manager.stop();
         }
         catch (error) {
-            const err = error;
-            console.error(chalk.red('Failed to stop daemon:'), err.message);
+            console.error(chalk.red('Failed to stop daemon:'), extractErrorMessage(error));
             process.exit(1);
         }
     });

package/dist/constants/config.js

@@ -30,6 +30,9 @@ export const ENV_VARS = {
     // Secrets management
     LSH_SECRETS_KEY: 'LSH_SECRETS_KEY',
     LSH_MASTER_KEY: 'LSH_MASTER_KEY',
+    // Name of the kubo remote pinning service to use for durable sync
+    // (configured via `ipfs pin remote service add <name> <endpoint> <key>`).
+    LSH_PIN_SERVICE: 'LSH_PIN_SERVICE',
     // Feature flags
     LSH_LOCAL_STORAGE_QUIET: 'LSH_LOCAL_STORAGE_QUIET',
     LSH_V1_COMPAT: 'LSH_V1_COMPAT',

package/dist/lib/floating-point-arithmetic.js

@@ -25,7 +25,7 @@ export class FloatingPointArithmetic {
             return this.roundToPrecision(result);
         }
         catch (error) {
-            throw new Error(`Arithmetic error: ${error.message}`);
+            throw new Error(`Arithmetic error: ${error.message}`, { cause: error });
         }
     }
     /**
@@ -193,7 +193,7 @@ export class FloatingPointArithmetic {
             return result;
         }
         catch (error) {
-            throw new Error(`Expression evaluation failed: ${error.message}`);
+            throw new Error(`Expression evaluation failed: ${error.message}`, { cause: error });
         }
     }
     /**

package/dist/lib/ipfs-client-manager.js

@@ -5,14 +5,20 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { exec, spawn } from 'child_process';
+import { exec, execFile, spawn } from 'child_process';
 import { promisify } from 'util';
 import * as readline from 'readline';
 import { createLogger } from './logger.js';
 import { getPlatformInfo } from './platform-utils.js';
 import { getLshConfig } from './lsh-config.js';
 const execAsync = promisify(exec);
+// execFile does NOT spawn a shell: arguments are passed literally to the binary,
+// so interpolated values (e.g. a Kubo version) cannot inject shell commands.
+const execFileAsync = promisify(execFile);
 const logger = createLogger('IPFSClientManager');
+// Kubo releases are strict semver (e.g. "0.26.0"). Reject anything else before it
+// reaches a download URL or subprocess — defense in depth against command injection.
+const KUBO_VERSION_RE = /^\d+\.\d+\.\d+$/;
 /**
  * IPFS Client Manager
  *
@@ -91,6 +97,9 @@ export class IPFSClientManager {
         logger.info('📦 Installing IPFS client (Kubo)...');
         // Determine version to install
         const version = options.version || await this.getLatestKuboVersion();
+        if (!KUBO_VERSION_RE.test(version)) {
+            throw new Error(`Invalid Kubo version "${version}": expected semver like 0.26.0`);
+        }
         logger.info(`   Version: ${version}`);
         logger.info(`   Platform: ${platformInfo.platformName} ${platformInfo.arch}`);
         // Download and install based on platform
@@ -200,7 +209,7 @@ export class IPFSClientManager {
             }
             catch (initError) {
                 const err = initError;
-                throw new Error(`Failed to auto-initialize IPFS repo: ${err.message}`);
+                throw new Error(`Failed to auto-initialize IPFS repo: ${err.message}`, { cause: initError });
             }
         }
         logger.info('🚀 Starting IPFS daemon...');
@@ -267,6 +276,24 @@ export class IPFSClientManager {
      */
     async stop() {
         const pidPath = path.join(this.ipfsDir, 'daemon.pid');
+        // Try graceful shutdown via IPFS API first (works even without PID file)
+        try {
+            const response = await fetch('http://127.0.0.1:5001/api/v0/shutdown', {
+                method: 'POST',
+                signal: AbortSignal.timeout(5000),
+            });
+            if (response.ok) {
+                // Clean up PID file if it exists
+                if (fs.existsSync(pidPath)) {
+                    fs.unlinkSync(pidPath);
+                }
+                logger.info('✅ IPFS daemon stopped');
+                return;
+            }
+        }
+        catch {
+            // API shutdown failed, fall back to PID-based kill
+        }
         if (!fs.existsSync(pidPath)) {
             logger.info('ℹ️  IPFS daemon not running (no PID file)');
             return;
@@ -280,6 +307,13 @@ export class IPFSClientManager {
         }
         catch (error) {
             const err = error;
+            // Process already gone — clean up stale PID file
+            if (err.code === 'ESRCH') {
+                if (fs.existsSync(pidPath))
+                    fs.unlinkSync(pidPath);
+                logger.info('✅ IPFS daemon already stopped (stale PID file cleaned)');
+                return;
+            }
             logger.error(`❌ Failed to stop daemon: ${err.message}`);
             throw error;
         }
@@ -289,8 +323,12 @@ export class IPFSClientManager {
      */
     async getLatestKuboVersion() {
         try {
-            // Use GitHub API to get latest release
-            const response = await fetch('https://api.github.com/repos/ipfs/kubo/releases/latest');
+            // Use GitHub API to get latest release. Bound the request: an unbounded
+            // fetch hangs indefinitely on a blocked/slow network (e.g. CI runners),
+            // which would stall install() and time out tests before the fallback.
+            const response = await fetch('https://api.github.com/repos/ipfs/kubo/releases/latest', {
+                signal: AbortSignal.timeout(3000),
+            });
             const data = await response.json();
             // Remove 'v' prefix if present
             return data.tag_name.replace(/^v/, '');
@@ -308,11 +346,11 @@ export class IPFSClientManager {
         const downloadUrl = `https://dist.ipfs.tech/kubo/v${version}/kubo_v${version}_darwin-${arch}.tar.gz`;
         const tarPath = path.join(this.ipfsDir, 'kubo.tar.gz');
         logger.info('   Downloading Kubo...');
-        // Download
-        await execAsync(`curl -L -o ${tarPath} ${downloadUrl}`);
+        // Download (execFile: no shell, args passed literally)
+        await execFileAsync('curl', ['-L', '-o', tarPath, downloadUrl]);
         logger.info('   Extracting...');
         // Extract
-        await execAsync(`tar -xzf ${tarPath} -C ${this.ipfsDir}`);
+        await execFileAsync('tar', ['-xzf', tarPath, '-C', this.ipfsDir]);
         // Move binary
         const extractedBinPath = path.join(this.ipfsDir, 'kubo', 'ipfs');
         fs.mkdirSync(this.binDir, { recursive: true });
@@ -331,11 +369,11 @@ export class IPFSClientManager {
         const downloadUrl = `https://dist.ipfs.tech/kubo/v${version}/kubo_v${version}_linux-${arch}.tar.gz`;
         const tarPath = path.join(this.ipfsDir, 'kubo.tar.gz');
         logger.info('   Downloading Kubo...');
-        // Download
-        await execAsync(`curl -L -o ${tarPath} ${downloadUrl}`);
+        // Download (execFile: no shell, args passed literally)
+        await execFileAsync('curl', ['-L', '-o', tarPath, downloadUrl]);
         logger.info('   Extracting...');
         // Extract
-        await execAsync(`tar -xzf ${tarPath} -C ${this.ipfsDir}`);
+        await execFileAsync('tar', ['-xzf', tarPath, '-C', this.ipfsDir]);
         // Move binary
         const extractedBinPath = path.join(this.ipfsDir, 'kubo', 'ipfs');
         fs.mkdirSync(this.binDir, { recursive: true });
@@ -353,11 +391,11 @@ export class IPFSClientManager {
         const downloadUrl = `https://dist.ipfs.tech/kubo/v${version}/kubo_v${version}_windows-amd64.zip`;
         const zipPath = path.join(this.ipfsDir, 'kubo.zip');
         logger.info('   Downloading Kubo...');
-        // Download
-        await execAsync(`curl -L -o ${zipPath} ${downloadUrl}`);
+        // Download (execFile: no shell, args passed literally)
+        await execFileAsync('curl', ['-L', '-o', zipPath, downloadUrl]);
         logger.info('   Extracting...');
         // Extract (Windows has built-in tar that supports zip)
-        await execAsync(`tar -xf ${zipPath} -C ${this.ipfsDir}`);
+        await execFileAsync('tar', ['-xf', zipPath, '-C', this.ipfsDir]);
         // Move binary
         const extractedBinPath = path.join(this.ipfsDir, 'kubo', 'ipfs.exe');
         fs.mkdirSync(this.binDir, { recursive: true });