agentic-factory-bridge 1.2.0 → 1.3.0

package/bridge.js

@@ -1,31 +1,32 @@
 /**
- * Agentic Factory Bridge — Local bridge between Atos Agentic Factory and OpenCode CLI.
+ * OpenCode Bridge — Local bridge between Atos Agentic Factory and OpenCode CLI.
  *
- * This lightweight Express server runs on the user's machine (port 3001)
+ * This lightweight Express server runs on the developer's machine (port 3001)
  * and acts as an intermediary:
  *   1. Receives execution requests from the marketplace frontend
  *   2. Spawns `opencode run --format json` with the given prompt
  *   3. Reports results back to the marketplace backend via PATCH
  *
  * Security features:
- *   - CORS restricted to allowed origins
+ *   - CORS restricted to allowed origins (localhost:4200 by default)
  *   - HMAC token authentication on all mutating endpoints
- *   - Input sanitization to prevent command injection
+ *   - Input sanitization (prompt, model) to prevent command injection
  *   - Rate limiting on sensitive endpoints
  *   - Bounded in-memory store with TTL
  *   - Body size limits
  *   - No sensitive info leaked in /health
  *
  * Usage:
- *   npm install -g agentic-factory-bridge
- *   agentic-factory-bridge start
+ *   cd opencode-bridge
+ *   npm install
+ *   npm start
  *
  * Environment variables:
  *   BRIDGE_PORT          — Port to listen on (default: 3001)
  *   MARKETPLACE_API_URL  — Marketplace backend URL (default: http://localhost:3000/api)
  *   OPENCODE_PATH        — Path to opencode binary (default: "opencode" — must be in PATH)
  *   BRIDGE_SECRET        — Shared secret for HMAC authentication (default: auto-generated)
- *   BRIDGE_CORS_ORIGIN   — Allowed CORS origins, comma-separated
+ *   BRIDGE_CORS_ORIGIN   — Allowed CORS origins, comma-separated (default: http://localhost:4200,https://atos-agentic-factory.onrender.com,https://atos-agentic-factory-qzwe.onrender.com)
  */
 
 const express = require('express');
@@ -37,14 +38,13 @@ const https = require('https');
 const path = require('path');
 const fs = require('fs');
 
-const BRIDGE_VERSION = require(path.join(__dirname, 'package.json')).version;
-
 // ---------------------------------------------------------------------------
 // Configuration
 // ---------------------------------------------------------------------------
 const PORT = parseInt(process.env.BRIDGE_PORT || '3001', 10);
 const MARKETPLACE_API_URL = process.env.MARKETPLACE_API_URL || 'http://localhost:3000/api';
 const OPENCODE_PATH = process.env.OPENCODE_PATH || 'opencode';
+const BRIDGE_VERSION = require(path.join(__dirname, 'package.json')).version;
 
 // Security configuration
 const BRIDGE_SECRET = process.env.BRIDGE_SECRET || crypto.randomBytes(32).toString('hex');
@@ -54,23 +54,31 @@ const CORS_ORIGIN =
 
 // Rate limiting configuration
 const RATE_LIMITS = {
-  execute: { windowMs: 60000, max: 10 },
-  install: { windowMs: 3600000, max: 2 },
-  register: { windowMs: 3600000, max: 3 },
-  update: { windowMs: 3600000, max: 3 },
+  execute: { windowMs: 60000, max: 10 }, // 10 executions per minute
+  install: { windowMs: 3600000, max: 2 }, // 2 installs per hour
+  register: { windowMs: 3600000, max: 3 }, // 3 registrations per hour
+  update: { windowMs: 3600000, max: 3 }, // 3 updates per hour
 };
 
 // In-memory store limits
 const MAX_EXECUTIONS = 100;
-const EXECUTION_TTL_MS = 3600000;
+const EXECUTION_TTL_MS = 3600000; // 1 hour
 
 // ---------------------------------------------------------------------------
 // Security: Input sanitization
 // ---------------------------------------------------------------------------
 
+/**
+ * Dangerous shell characters/patterns that could enable command injection.
+ * Blocks: & | ; ` $() ${ } < > \n \r and common Windows cmd injection patterns.
+ */
 const DANGEROUS_PATTERNS = /[&|;`$<>{}()\n\r]/;
 const DANGEROUS_WIN_PATTERNS = /(\^[&|<>])|(%[a-zA-Z0-9]+%)/;
 
+/**
+ * Sanitizes a string input to prevent command injection.
+ * Returns { safe: boolean, cleaned: string, reason?: string }
+ */
 function sanitizeInput(input, fieldName, maxLength = 10000) {
   if (typeof input !== 'string') {
     return { safe: false, cleaned: '', reason: `${fieldName} must be a string` };
@@ -99,6 +107,10 @@ function sanitizeInput(input, fieldName, maxLength = 10000) {
   return { safe: true, cleaned: input.trim() };
 }
 
+/**
+ * Validates a model string (e.g. "anthropic/claude-sonnet-4-20250514").
+ * Only allows alphanumeric, hyphens, dots, underscores, and forward slashes.
+ */
 function validateModel(model) {
   if (!model) return { safe: true, cleaned: '' };
   if (typeof model !== 'string') {
@@ -121,6 +133,13 @@ function validateModel(model) {
 // Security: HMAC token authentication
 // ---------------------------------------------------------------------------
 
+/**
+ * Generates an HMAC-SHA256 token from a timestamp and the bridge secret.
+ * The frontend must send this token in the X-Bridge-Token header.
+ *
+ * Token format: <timestamp>.<hmac>
+ * The timestamp is validated to be within 5 minutes of the current time.
+ */
 function generateBridgeToken() {
   const timestamp = Date.now().toString();
   const hmac = crypto.createHmac('sha256', BRIDGE_SECRET).update(timestamp).digest('hex');
@@ -129,17 +148,27 @@ function generateBridgeToken() {
 
 function verifyBridgeToken(token) {
   if (!token || typeof token !== 'string') return false;
+
   const parts = token.split('.');
   if (parts.length !== 2) return false;
+
   const [timestamp, hmac] = parts;
   const ts = parseInt(timestamp, 10);
   if (isNaN(ts)) return false;
+
+  // Check timestamp is within 5 minutes
   const now = Date.now();
   if (Math.abs(now - ts) > 5 * 60 * 1000) return false;
+
+  // Verify HMAC
   const expected = crypto.createHmac('sha256', BRIDGE_SECRET).update(timestamp).digest('hex');
   return crypto.timingSafeEqual(Buffer.from(hmac, 'hex'), Buffer.from(expected, 'hex'));
 }
 
+/**
+ * Express middleware that requires a valid bridge token on mutating endpoints.
+ * The token is sent in the X-Bridge-Token header.
+ */
 function requireBridgeAuth(req, res, next) {
   const token = req.headers['x-bridge-token'];
   if (!verifyBridgeToken(token)) {
@@ -151,21 +180,24 @@ function requireBridgeAuth(req, res, next) {
 }
 
 // ---------------------------------------------------------------------------
-// Security: Rate limiting
+// Security: Rate limiting (simple in-memory)
 // ---------------------------------------------------------------------------
 
+/** @type {Map<string, { count: number, resetAt: number }>} */
 const rateLimitStore = new Map();
 
-function rateLimit(key, config) {
+function rateLimit(key, config = { windowMs: 60000, max: 10 }) {
   return (req, res, next) => {
     const ip = req.ip || req.connection.remoteAddress || 'unknown';
     const storeKey = `${key}:${ip}`;
     const now = Date.now();
     let entry = rateLimitStore.get(storeKey);
+
     if (!entry || now >= entry.resetAt) {
       entry = { count: 0, resetAt: now + config.windowMs };
       rateLimitStore.set(storeKey, entry);
     }
+
     entry.count++;
     if (entry.count > config.max) {
       const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
@@ -178,6 +210,7 @@ function rateLimit(key, config) {
   };
 }
 
+// Cleanup stale rate limit entries every 10 minutes
 setInterval(() => {
   const now = Date.now();
   for (const [key, entry] of rateLimitStore) {
@@ -186,18 +219,24 @@ setInterval(() => {
 }, 600000);
 
 // ---------------------------------------------------------------------------
-// In-memory execution store
+// In-memory execution store (bounded with TTL)
 // ---------------------------------------------------------------------------
 
+/** @type {Map<string, { id: string, status: string, startedAt: Date, prompt: string, agentId?: string, model?: string, response?: string, error?: string, logs: string[] }>} */
 const executions = new Map();
 
+/**
+ * Evicts old executions to stay within MAX_EXECUTIONS and EXECUTION_TTL_MS.
+ */
 function evictStaleExecutions() {
   const now = Date.now();
+  // First: evict expired entries
   for (const [id, exec] of executions) {
     if (now - exec.startedAt.getTime() > EXECUTION_TTL_MS) {
       executions.delete(id);
     }
   }
+  // Then: if still over limit, evict oldest
   if (executions.size > MAX_EXECUTIONS) {
     const sorted = Array.from(executions.entries()).sort(
       (a, b) => a[1].startedAt.getTime() - b[1].startedAt.getTime(),
@@ -209,12 +248,16 @@ function evictStaleExecutions() {
   }
 }
 
+// Run eviction every 5 minutes
 setInterval(evictStaleExecutions, 300000);
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Makes an HTTP(S) request with JSON body.
+ */
 function httpRequest(method, url, body, token) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(url);
@@ -248,6 +291,9 @@ function httpRequest(method, url, body, token) {
   });
 }
 
+/**
+ * Reports execution result back to the marketplace backend.
+ */
 async function reportToBackend(executionId, update, token) {
   const url = `${MARKETPLACE_API_URL}/opencode/executions/${executionId}`;
   try {
@@ -258,27 +304,37 @@ async function reportToBackend(executionId, update, token) {
   }
 }
 
+/**
+ * Spawns the OpenCode CLI and returns a promise that resolves with the output.
+ * SECURITY: shell is always false to prevent command injection.
+ */
 function runOpenCode(prompt, model) {
   return new Promise((resolve, reject) => {
     const args = ['run', prompt, '--format', 'json'];
     if (model) {
       args.push('--model', model);
     }
+
     console.log(`[bridge] Spawning: ${OPENCODE_PATH} ${args.join(' ')}`);
+
     const proc = spawn(OPENCODE_PATH, args, {
       stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 300000,
-      shell: false,
+      timeout: 300000, // 5 minutes max
+      shell: false, // SECURITY: never use shell to prevent injection
       windowsHide: true,
     });
+
     let stdout = '';
     let stderr = '';
+
     proc.stdout.on('data', (data) => {
       stdout += data.toString();
     });
+
     proc.stderr.on('data', (data) => {
       stderr += data.toString();
     });
+
     proc.on('close', (code) => {
       if (code === 0) {
         resolve({ stdout, stderr, code });
@@ -286,6 +342,7 @@ function runOpenCode(prompt, model) {
         reject(new Error(`OpenCode exited with code ${code}: ${stderr || stdout}`));
       }
     });
+
     proc.on('error', (err) => {
       reject(new Error(`Failed to spawn OpenCode: ${err.message}`));
     });
@@ -297,6 +354,7 @@ function runOpenCode(prompt, model) {
 // ---------------------------------------------------------------------------
 const app = express();
 
+// SECURITY: Restrict CORS to known origins only
 const allowedOrigins = CORS_ORIGIN.split(',').map((o) => o.trim());
 
 // Private Network Access (Chrome 94+) — handle preflight BEFORE cors middleware
@@ -310,6 +368,7 @@ app.use((req, res, next) => {
 app.use(
   cors({
     origin: (origin, callback) => {
+      // Allow requests with no origin (curl, server-to-server)
       if (!origin) return callback(null, true);
       if (allowedOrigins.includes(origin)) return callback(null, true);
       callback(new Error(`CORS: origin ${origin} not allowed`));
@@ -324,8 +383,10 @@ app.use((_req, res, next) => {
   next();
 });
 
+// SECURITY: Limit body size to 1MB
 app.use(express.json({ limit: '1mb' }));
 
+// Security headers
 app.use((_req, res, next) => {
   res.set('X-Content-Type-Options', 'nosniff');
   res.set('X-Frame-Options', 'DENY');
@@ -334,28 +395,47 @@ app.use((_req, res, next) => {
 });
 
 // ---------------------------------------------------------------------------
-// Public endpoints
+// Public endpoints (no auth required)
 // ---------------------------------------------------------------------------
 
+/**
+ * GET /health — Health check for the bridge.
+ * SECURITY: No sensitive information exposed.
+ */
 app.get('/health', (_req, res) => {
   res.json({
     status: 'ok',
-    bridge: 'agentic-factory-bridge',
+    bridge: 'opencode-bridge',
     version: BRIDGE_VERSION,
     uptime: Math.floor(process.uptime()),
     activeExecutions: executions.size,
   });
 });
 
+/**
+ * GET /bridge-token — Get a fresh HMAC token for authenticating requests.
+ * This endpoint is public so the frontend can get a token before making requests.
+ * The token is time-limited (5 minutes) and HMAC-signed with the bridge secret.
+ */
 app.get('/bridge-token', (_req, res) => {
   const token = generateBridgeToken();
   res.json({ token, expiresIn: 300 });
 });
 
 // ---------------------------------------------------------------------------
-// Protected endpoints
+// Protected endpoints (require X-Bridge-Token header)
 // ---------------------------------------------------------------------------
 
+/**
+ * POST /execute — Launch an OpenCode execution.
+ *
+ * Body:
+ *   - executionId: string  — ID of the execution record in the marketplace DB
+ *   - prompt: string       — The prompt to send to OpenCode
+ *   - agentId?: string     — Agent ID (for context)
+ *   - model?: string       — Model override (e.g. "anthropic/claude-sonnet-4-20250514")
+ *   - token: string        — JWT token for reporting back to the marketplace backend
+ */
 app.post(
   '/execute',
   requireBridgeAuth,
@@ -364,13 +444,18 @@ app.post(
     const { executionId, prompt, agentId, model, token } = req.body;
 
     if (!executionId || !prompt) {
-      return res.status(400).json({ error: 'Missing required fields: executionId, prompt' });
+      return res.status(400).json({
+        error: 'Missing required fields: executionId, prompt',
+      });
     }
+
     if (!token) {
-      return res
-        .status(400)
-        .json({ error: 'Missing required field: token (JWT for backend callback)' });
+      return res.status(400).json({
+        error: 'Missing required field: token (JWT for backend callback)',
+      });
     }
+
+    // SECURITY: Validate executionId format (UUID)
     if (
       typeof executionId !== 'string' ||
       !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(executionId)
@@ -378,17 +463,22 @@ app.post(
       return res.status(400).json({ error: 'executionId must be a valid UUID' });
     }
 
+    // SECURITY: Sanitize prompt
     const promptCheck = sanitizeInput(prompt, 'prompt');
     if (!promptCheck.safe) {
       return res.status(400).json({ error: promptCheck.reason });
     }
+
+    // SECURITY: Validate model
     const modelCheck = validateModel(model);
     if (!modelCheck.safe) {
       return res.status(400).json({ error: modelCheck.reason });
     }
 
+    // Evict stale executions before adding new one
     evictStaleExecutions();
 
+    // Store execution locally
     const execution = {
       id: executionId,
       status: 'running',
@@ -400,29 +490,43 @@ app.post(
     };
     executions.set(executionId, execution);
 
-    res.json({ message: 'Execution started', executionId, status: 'running' });
+    // Respond immediately — execution happens in background
+    res.json({
+      message: 'Execution started',
+      executionId,
+      status: 'running',
+    });
 
+    // Run OpenCode in background
     const startTime = Date.now();
+
     try {
       execution.logs.push(`[${new Date().toISOString()}] Starting OpenCode CLI...`);
+
       const result = await runOpenCode(promptCheck.cleaned, modelCheck.cleaned || undefined);
       const executionTime = Date.now() - startTime;
+
       execution.status = 'completed';
       execution.logs.push(`[${new Date().toISOString()}] Completed in ${executionTime}ms`);
 
+      // Parse the JSON output from OpenCode
       let response = result.stdout;
       let tokensUsed = null;
       let cost = null;
+
       try {
         const parsed = JSON.parse(result.stdout);
         response = parsed.response || parsed.output || parsed.result || result.stdout;
         tokensUsed = parsed.tokens || parsed.tokensUsed || null;
         cost = parsed.cost || null;
       } catch {
+        // stdout might not be valid JSON — use as-is
         execution.logs.push(`[${new Date().toISOString()}] Output is not JSON, using raw text`);
       }
 
       execution.response = response;
+
+      // Report success to marketplace backend
       await reportToBackend(
         executionId,
         {
@@ -441,6 +545,8 @@ app.post(
       execution.status = 'failed';
       execution.error = err.message;
       execution.logs.push(`[${new Date().toISOString()}] Error: ${err.message}`);
+
+      // Report failure to marketplace backend
       await reportToBackend(
         executionId,
         {
@@ -456,6 +562,9 @@ app.post(
   },
 );
 
+/**
+ * GET /status/:executionId — Check execution status.
+ */
 app.get('/status/:executionId', requireBridgeAuth, (req, res) => {
   const execution = executions.get(req.params.executionId);
   if (!execution) {
@@ -472,6 +581,9 @@ app.get('/status/:executionId', requireBridgeAuth, (req, res) => {
   });
 });
 
+/**
+ * GET /executions — List all tracked executions.
+ */
 app.get('/executions', requireBridgeAuth, (_req, res) => {
   const list = Array.from(executions.values()).map((e) => ({
     id: e.id,
@@ -483,6 +595,9 @@ app.get('/executions', requireBridgeAuth, (_req, res) => {
   res.json(list);
 });
 
+/**
+ * DELETE /executions — Clear all tracked executions from memory.
+ */
 app.delete('/executions', requireBridgeAuth, (_req, res) => {
   const count = executions.size;
   executions.clear();
@@ -663,56 +778,67 @@ app.get('/agents/:name/check', (req, res) => {
 });
 
 /**
- * POST /agents/install — Download manifest from marketplace API and install agent locally.
- * Body: { name: string, marketplaceUrl?: string, agentId: string }
+ * POST /agents/install — Install agent locally from inline data or by fetching from marketplace API.
+ * Body: { name: string, agentId: string, agentData?: object, marketplaceUrl?: string }
+ *
+ * If agentData is provided, it is used directly (no API call needed).
+ * Otherwise, falls back to fetching the manifest from the marketplace API.
  */
 app.post(
   '/agents/install',
   requireBridgeAuth,
-  rateLimit('install'),
+  rateLimit('install', RATE_LIMITS.install),
   express.json(),
   async (req, res) => {
-    const { agentId } = req.body;
+    const { agentId, agentData } = req.body;
     let { name } = req.body;
 
-    if (!agentId) {
-      return res.status(400).json({ error: 'agentId is required' });
+    if (!agentId && !agentData) {
+      return res.status(400).json({ error: 'agentId or agentData is required' });
     }
 
     try {
-      // Fetch manifest from marketplace API
-      const apiUrl =
-        req.body.marketplaceUrl ||
-        process.env.MARKETPLACE_API_URL ||
-        'https://atos-agentic-factory-qzwe.onrender.com/api';
-      const manifestUrl = `${apiUrl}/agents/${encodeURIComponent(agentId)}/opencode-manifest`;
+      let manifest;
 
-      const manifest = await new Promise((resolve, reject) => {
-        const urlObj = new URL(manifestUrl);
-        const client = urlObj.protocol === 'https:' ? https : http;
-        const request = client.get(manifestUrl, { timeout: 15000 }, (response) => {
-          if (response.statusCode !== 200) {
-            reject(new Error(`API returned ${response.statusCode}`));
-            return;
-          }
-          let data = '';
-          response.on('data', (chunk) => {
-            data += chunk;
-          });
-          response.on('end', () => {
-            try {
-              resolve(JSON.parse(data));
-            } catch (e) {
-              reject(new Error('Invalid JSON response from API'));
+      if (agentData && typeof agentData === 'object') {
+        // Use inline agent data directly — no API fetch needed
+        console.log(`[Agent Hub] Using inline agent data for "${agentData.name || name}"`);
+        manifest = agentData;
+      } else {
+        // Fallback: fetch manifest from marketplace API
+        const apiUrl =
+          req.body.marketplaceUrl ||
+          process.env.MARKETPLACE_API_URL ||
+          'https://atos-agentic-factory-qzwe.onrender.com/api';
+        const manifestUrl = `${apiUrl}/agents/${encodeURIComponent(agentId)}/opencode-manifest`;
+
+        manifest = await new Promise((resolve, reject) => {
+          const urlObj = new URL(manifestUrl);
+          const client = urlObj.protocol === 'https:' ? https : http;
+          const request = client.get(manifestUrl, { timeout: 15000 }, (response) => {
+            if (response.statusCode !== 200) {
+              reject(new Error(`API returned ${response.statusCode}`));
+              return;
             }
+            let data = '';
+            response.on('data', (chunk) => {
+              data += chunk;
+            });
+            response.on('end', () => {
+              try {
+                resolve(JSON.parse(data));
+              } catch (e) {
+                reject(new Error('Invalid JSON response from API'));
+              }
+            });
+          });
+          request.on('error', reject);
+          request.on('timeout', () => {
+            request.destroy();
+            reject(new Error('Request timeout'));
           });
         });
-        request.on('error', reject);
-        request.on('timeout', () => {
-          request.destroy();
-          reject(new Error('Request timeout'));
-        });
-      });
+      }
 
       // Use name from manifest if not provided
       const agentName = sanitizeAgentName(name || manifest.name);
@@ -720,6 +846,11 @@ app.post(
         return res.status(400).json({ error: 'Invalid agent name' });
       }
 
+      // Ensure sourceUrl is set for sync tracking
+      if (!manifest.sourceUrl && agentId) {
+        manifest.sourceUrl = `/agents/${agentId}`;
+      }
+
       // Generate .md file content
       const mdContent = generateAgentMd(manifest);
 
@@ -766,6 +897,10 @@ app.delete('/agents/:name', requireBridgeAuth, (req, res) => {
 
 /**
  * PUT /agents/:name/update — Re-download and update an existing agent.
+ * Body: { agentId: string, agentData?: object, marketplaceUrl?: string }
+ *
+ * If agentData is provided, it is used directly (no API call needed).
+ * Otherwise, falls back to fetching the manifest from the marketplace API.
  */
 app.put('/agents/:name/update', requireBridgeAuth, async (req, res) => {
   const name = sanitizeAgentName(req.params.name);
@@ -778,45 +913,59 @@ app.put('/agents/:name/update', requireBridgeAuth, async (req, res) => {
     return res.status(404).json({ error: `Agent "${name}" not found locally` });
   }
 
-  // Get agentId from existing metadata or request body
-  const { agentId } = req.body || {};
-  if (!agentId) {
-    return res.status(400).json({ error: 'agentId is required for update' });
+  // Get agentId and optional agentData from request body
+  const { agentId, agentData } = req.body || {};
+  if (!agentId && !agentData) {
+    return res.status(400).json({ error: 'agentId or agentData is required for update' });
   }
 
   try {
-    const apiUrl =
-      req.body.marketplaceUrl ||
-      process.env.MARKETPLACE_API_URL ||
-      'https://atos-agentic-factory-qzwe.onrender.com/api';
-    const manifestUrl = `${apiUrl}/agents/${encodeURIComponent(agentId)}/opencode-manifest`;
-
-    const manifest = await new Promise((resolve, reject) => {
-      const urlObj = new URL(manifestUrl);
-      const client = urlObj.protocol === 'https:' ? https : http;
-      const request = client.get(manifestUrl, { timeout: 15000 }, (response) => {
-        if (response.statusCode !== 200) {
-          reject(new Error(`API returned ${response.statusCode}`));
-          return;
-        }
-        let data = '';
-        response.on('data', (chunk) => {
-          data += chunk;
-        });
-        response.on('end', () => {
-          try {
-            resolve(JSON.parse(data));
-          } catch (e) {
-            reject(new Error('Invalid JSON response from API'));
+    let manifest;
+
+    if (agentData && typeof agentData === 'object') {
+      // Use inline agent data directly
+      console.log(`[Agent Hub] Using inline agent data for update "${name}"`);
+      manifest = agentData;
+    } else {
+      // Fallback: fetch from API
+      const apiUrl =
+        req.body.marketplaceUrl ||
+        process.env.MARKETPLACE_API_URL ||
+        'https://atos-agentic-factory-qzwe.onrender.com/api';
+      const manifestUrl = `${apiUrl}/agents/${encodeURIComponent(agentId)}/opencode-manifest`;
+
+      manifest = await new Promise((resolve, reject) => {
+        const urlObj = new URL(manifestUrl);
+        const client = urlObj.protocol === 'https:' ? https : http;
+        const request = client.get(manifestUrl, { timeout: 15000 }, (response) => {
+          if (response.statusCode !== 200) {
+            reject(new Error(`API returned ${response.statusCode}`));
+            return;
           }
+          let data = '';
+          response.on('data', (chunk) => {
+            data += chunk;
+          });
+          response.on('end', () => {
+            try {
+              resolve(JSON.parse(data));
+            } catch (e) {
+              reject(new Error('Invalid JSON response from API'));
+            }
+          });
+        });
+        request.on('error', reject);
+        request.on('timeout', () => {
+          request.destroy();
+          reject(new Error('Request timeout'));
         });
       });
-      request.on('error', reject);
-      request.on('timeout', () => {
-        request.destroy();
-        reject(new Error('Request timeout'));
-      });
-    });
+    }
+
+    // Ensure sourceUrl is set for sync tracking
+    if (!manifest.sourceUrl && agentId) {
+      manifest.sourceUrl = `/agents/${agentId}`;
+    }
 
     const mdContent = generateAgentMd(manifest);
     fs.writeFileSync(filePath, mdContent, 'utf8');
@@ -838,22 +987,30 @@ app.put('/agents/:name/update', requireBridgeAuth, async (req, res) => {
 // Smart Detection
 // ---------------------------------------------------------------------------
 
+/**
+ * Checks if a command exists on the system PATH.
+ * SECURITY: Only checks the configured OPENCODE_PATH, not arbitrary commands.
+ */
 function checkCommandExists(command) {
   return new Promise((resolve) => {
     const isWin = process.platform === 'win32';
     const checkCmd = isWin ? 'where' : 'which';
+
     const proc = spawn(checkCmd, [command], {
       stdio: ['pipe', 'pipe', 'pipe'],
       timeout: 10000,
       shell: false,
     });
+
     let stdout = '';
     proc.stdout.on('data', (data) => {
       stdout += data.toString();
     });
+
     proc.on('close', (code) => {
       if (code === 0 && stdout.trim()) {
         const cmdPath = stdout.trim().split('\n')[0].trim();
+        // Now get version
         const versionProc = spawn(command, ['--version'], {
           stdio: ['pipe', 'pipe', 'pipe'],
           timeout: 10000,
@@ -867,7 +1024,11 @@ function checkCommandExists(command) {
           versionOut += d.toString();
         });
         versionProc.on('close', () => {
-          resolve({ installed: true, version: versionOut.trim() || 'unknown', path: cmdPath });
+          resolve({
+            installed: true,
+            version: versionOut.trim() || 'unknown',
+            path: cmdPath,
+          });
         });
         versionProc.on('error', () => {
           resolve({ installed: true, version: 'unknown', path: cmdPath });
@@ -876,12 +1037,16 @@ function checkCommandExists(command) {
         resolve({ installed: false, version: null, path: null });
       }
     });
+
     proc.on('error', () => {
       resolve({ installed: false, version: null, path: null });
     });
   });
 }
 
+/**
+ * GET /check-opencode — Check if OpenCode CLI is installed on the system.
+ */
 app.get('/check-opencode', async (_req, res) => {
   try {
     const result = await checkCommandExists(OPENCODE_PATH);
@@ -895,41 +1060,55 @@ app.get('/check-opencode', async (_req, res) => {
   }
 });
 
+/**
+ * POST /install-opencode — Install OpenCode CLI via npm install -g opencode-ai.
+ * SECURITY: Rate-limited, auth required, fixed command (no user input in spawn args).
+ */
 app.post(
   '/install-opencode',
   requireBridgeAuth,
   rateLimit('install', RATE_LIMITS.install),
   async (_req, res) => {
     console.log('[bridge] Installing OpenCode CLI via npm install -g opencode-ai...');
+
     try {
       await new Promise((resolve, reject) => {
         const proc = spawn('npm', ['install', '-g', 'opencode-ai'], {
           stdio: ['pipe', 'pipe', 'pipe'],
-          timeout: 120000,
+          timeout: 120000, // 2 minutes max
           shell: true,
         });
+
         let stdout = '';
         let stderr = '';
+
         proc.stdout.on('data', (data) => {
           stdout += data.toString();
           console.log(`[bridge] npm install stdout: ${data.toString().trim()}`);
         });
+
         proc.stderr.on('data', (data) => {
           stderr += data.toString();
         });
+
         proc.on('close', (code) => {
-          if (code === 0) resolve({ success: true, stdout, stderr });
-          else
+          if (code === 0) {
+            resolve({ success: true, stdout, stderr });
+          } else {
             reject(
               new Error(`npm install -g opencode-ai failed with code ${code}: ${stderr || stdout}`),
             );
+          }
         });
+
         proc.on('error', (err) => {
           reject(new Error(`Failed to spawn npm: ${err.message}`));
         });
       });
 
+      // Verify installation
       const check = await checkCommandExists(OPENCODE_PATH);
+
       res.json({
         success: true,
         message: 'OpenCode CLI installed successfully',
@@ -952,12 +1131,17 @@ app.post(
 // Protocol Registration
 // ---------------------------------------------------------------------------
 
+/**
+ * POST /register-protocol — Register the opencode:// protocol handler on Windows.
+ * SECURITY: Rate-limited, auth required, only executes the known script.
+ */
 app.post(
   '/register-protocol',
   requireBridgeAuth,
   rateLimit('register', RATE_LIMITS.register),
   async (_req, res) => {
     const isWin = process.platform === 'win32';
+
     if (!isWin) {
       return res.status(400).json({
         success: false,
@@ -968,6 +1152,7 @@ app.post(
     const scriptPath = path.join(__dirname, 'install-protocol.ps1');
     const handlerPath = path.join(__dirname, 'opencode-handler.cmd');
 
+    // Check that required files exist
     if (!fs.existsSync(scriptPath)) {
       return res.status(404).json({
         success: false,
@@ -994,20 +1179,27 @@ app.post(
             shell: false,
           },
         );
+
         let stdout = '';
         let stderr = '';
+
         proc.stdout.on('data', (data) => {
           stdout += data.toString();
           console.log(`[bridge] ps1 stdout: ${data.toString().trim()}`);
         });
+
         proc.stderr.on('data', (data) => {
           stderr += data.toString();
         });
+
         proc.on('close', (code) => {
-          if (code === 0) resolve({ stdout, stderr });
-          else
+          if (code === 0) {
+            resolve({ stdout, stderr });
+          } else {
             reject(new Error(`install-protocol.ps1 exited with code ${code}: ${stderr || stdout}`));
+          }
         });
+
         proc.on('error', (err) => {
           reject(new Error(`Failed to spawn PowerShell: ${err.message}`));
         });
@@ -1158,14 +1350,16 @@ app.post(
 );
 
 // ---------------------------------------------------------------------------
-// Start server
+// Start server — listen only on loopback (127.0.0.1)
 // ---------------------------------------------------------------------------
 app.listen(PORT, '127.0.0.1', () => {
   const isAutoSecret = !process.env.BRIDGE_SECRET;
   console.log('');
   console.log('  +----------------------------------------------+');
   console.log('  |                                              |');
-  console.log(`  |   Agentic Factory Bridge v${BRIDGE_VERSION.padEnd(19)}|`);
+  console.log(
+    `  |   OpenCode Bridge v${BRIDGE_VERSION} (secured)${' '.repeat(Math.max(0, 14 - BRIDGE_VERSION.length))}|`,
+  );
   console.log(`  |   Listening on http://127.0.0.1:${PORT}        |`);
   console.log('  |                                              |');
   const origins = CORS_ORIGIN.split(',').map((o) => o.trim());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-factory-bridge",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Local bridge for Atos Agentic Factory — connects the marketplace to OpenCode CLI on your machine",
   "main": "bridge.js",
   "bin": {