@aiwerk/mcp-bridge 2.8.44 → 2.9.0

package/README.md

@@ -3,6 +3,7 @@
 [![CI](https://github.com/AIWerk/mcp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/AIWerk/mcp-bridge/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@aiwerk/mcp-bridge.svg)](https://www.npmjs.com/package/@aiwerk/mcp-bridge)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Status: active](https://img.shields.io/badge/status-active-brightgreen.svg)](#status)
 
 **Your AI, Connected to Everything.** Multiplex multiple MCP servers into one interface. One config, one connection, all your tools.
 
@@ -10,6 +11,32 @@
 
 Works with **Claude Code**, **Codex (OpenAI)**, **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **OpenClaw**, or any MCP client.
 
+## Status
+
+`@aiwerk/mcp-bridge` is **actively developed** as of 2026-05-03.
+
+The primary use case is the **local install path for the AIWerk catalog** at
+[aiwerkmcp.com](https://aiwerkmcp.com). Some recipes (those marked
+`localOnly: true`, e.g. `chrome-devtools`) need a browser, display, USB
+device or user-specific local path that the hosted bridge cannot reach;
+this package is the recommended way to run them.
+
+It also serves:
+
+- **OpenClaw plugin users** via [`@aiwerk/openclaw-mcp-bridge`](https://github.com/AIWerk/openclaw-mcp-bridge),
+  which embeds this library and ships its own recipe-install tooling.
+- **Self-hosted / offline deployments** where the hosted service is not an
+  option.
+- **Library consumers** that import `McpRouter`, transports and the OAuth2
+  token manager directly.
+
+Active development tracks the **Universal Recipe Spec v2** alongside the
+hosted bridge — new fields like `localOnly`, `multiInstance`,
+`auth.options[]` and `envBinding` are being ported, and the bundled
+`servers/` directory is being kept in sync with the catalog. The install
+helper does not fetch recipes over HTTP — recipes come from the bundled
+`servers/` directory only.
+
 ## Why?
 
 Most AI agents connect to MCP servers one-by-one. With 10+ servers, that's 10+ connections, 200+ tools in context, and thousands of wasted tokens.
@@ -27,7 +54,7 @@ Most AI agents connect to MCP servers one-by-one. With 10+ servers, that's 10+ c
 - **Graceful shutdown**: clean process termination and connection cleanup
 - **Direct mode**: all tools registered individually with automatic prefixing
 - **3 transports**: stdio, SSE, streamable-http
-- **Built-in catalog**: 14 pre-configured servers, install with one command (bundled servers deprecated — use [MCP Catalog](https://catalog.aiwerk.ch) with 104+ recipes instead)
+- **Bundled recipe examples**: 14+ reference server recipes in `servers/` — copy one as a starting point for your own config, or bring your own MCP server entirely
 - **Zero config secrets in files**: `${ENV_VAR}` resolution from `.env`
 
 ## Install
@@ -565,6 +592,12 @@ NOTION_TOKEN=ntn_xxxxx
 
 Use `${VAR_NAME}` in config — resolved from `.env` + system env.
 
+You can also set env vars via CLI or at runtime:
+```bash
+mcp-bridge set-env TODOIST_API_TOKEN your-token-here
+```
+Or via the agent: `mcp(action="set-env", params={key: "TODOIST_API_TOKEN", value: "..."})`
+
 ## CLI Reference
 
 ```bash
@@ -581,8 +614,9 @@ mcp-bridge init --register codex        # Init + register with Codex
 mcp-bridge init --register cursor       # Init + register with Cursor
 mcp-bridge init --register windsurf     # Init + register with Windsurf
 mcp-bridge install <server>       # Install from online catalog
+mcp-bridge set-env <KEY> <value>  # Set an API key in ~/.mcp-bridge/.env
 mcp-bridge catalog                # Browse 100+ available servers
-mcp-bridge servers                # List configured servers
+mcp-bridge servers                # List configured servers and current mode
 mcp-bridge search <query>         # Search catalog by keyword
 mcp-bridge update [--check]       # Check for / install updates
 mcp-bridge --version              # Print version
@@ -599,6 +633,7 @@ When connected to an MCP client (Claude Code, Codex, Cursor, etc.), the bridge e
 ```
 mcp(action="search", params={query: "task management"})  # Search catalog
 mcp(action="install", params={name: "todoist"})           # Install server (persisted to config)
+mcp(action="set-env", params={key: "TODOIST_API_TOKEN", value: "your-key"})  # Set API key
 mcp(action="catalog")                                      # Browse all servers
 mcp(action="list", server="todoist")                       # Discover tools on a server
 mcp(action="call", server="todoist", tool="find-tasks", params={query: "today"})

package/dist/bin/mcp-bridge.js

@@ -4,14 +4,14 @@ import { join, dirname, resolve, extname } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 import { execFileSync, execSync } from "child_process";
-import { loadConfig, initConfigDir, warnDeprecatedBundledRecipes, recipeToServerConfig, collectRequiredEnvVars } from "../src/config.js";
+import { loadConfig, initConfigDir, recipeToServerConfig, collectRequiredEnvVars } from "../src/config.js";
 import { StandaloneServer } from "../src/standalone-server.js";
 import { PACKAGE_VERSION } from "../src/protocol.js";
 import { checkForUpdate, runUpdate } from "../src/update-checker.js";
 import { FileTokenStore } from "../src/token-store.js";
 import { performAuthCodeLogin, performDeviceCodeLogin } from "../src/cli-auth.js";
 import { RateLimiter } from "../src/rate-limiter.js";
-import { CatalogClient } from "../src/catalog-client.js";
+import { CatalogClient, CatalogError, CatalogSignatureError } from "../src/catalog-client.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // After tsc, this file lives at dist/bin/mcp-bridge.js.
@@ -136,6 +136,12 @@ function parseArgs(argv) {
             case "install":
                 args.command = "install";
                 break;
+            case "search":
+                args.command = "search";
+                break;
+            case "catalog":
+                args.command = "catalog";
+                break;
             case "remove":
             case "uninstall":
                 args.command = "remove";
@@ -143,15 +149,9 @@ function parseArgs(argv) {
             case "set-env":
                 args.command = "set-env";
                 break;
-            case "catalog":
-                args.command = "catalog";
-                break;
             case "servers":
                 args.command = "servers";
                 break;
-            case "search":
-                args.command = "search";
-                break;
             case "update":
                 args.command = "update";
                 break;
@@ -195,12 +195,12 @@ Usage:
   mcp-bridge --sse --port 3000      Start as SSE server
   mcp-bridge --http --port 3000     Start as streamable-http server
   mcp-bridge init [--register <client>] [--mode router|direct]  Create config + optionally register
-  mcp-bridge install <server>       Install a server from the catalog
+  mcp-bridge install <server>       Install a server from the AIWerk catalog (signature-verified)
+  mcp-bridge catalog [--offline]    List available servers from the catalog
+  mcp-bridge search <query>         Search the catalog by keyword
   mcp-bridge remove <server>        Remove a configured server
   mcp-bridge set-env <KEY> <value>  Set an API key in ~/.mcp-bridge/.env
-  mcp-bridge catalog [--offline]    List available servers
-  mcp-bridge servers                List configured servers
-  mcp-bridge search <query>         Search catalog by keyword
+  mcp-bridge servers                List configured servers and current mode
   mcp-bridge usage                  Show current per-server call usage
   mcp-bridge limit <server> [--daily N] [--monthly N]
                                     Set per-server rate limits (0 = unlimited)
@@ -362,28 +362,6 @@ function registerClient(client, bridgeCmd, bridgeArgs, cmd) {
         }
     }
 }
-async function cmdCatalog(logger, offline) {
-    const client = new CatalogClient({ logger });
-    try {
-        const result = await client.list({ limit: 200 });
-        const recipes = result.results || [];
-        process.stdout.write(`\nAvailable servers (${recipes.length} from catalog.aiwerk.ch):\n\n`);
-        process.stdout.write("  Server                Auth        Category         Description\n");
-        process.stdout.write("  " + "─".repeat(90) + "\n");
-        for (const r of recipes) {
-            const name = (r.name || "").padEnd(22);
-            const auth = (r.authSummary || "none").padEnd(12);
-            const cat = (r.category || "").padEnd(17);
-            const desc = (r.description || "").slice(0, 60);
-            process.stdout.write(`  ${name}${auth}${cat}${desc}\n`);
-        }
-        process.stdout.write("\n");
-    }
-    catch (err) {
-        logger.error(`Failed to fetch catalog: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
-    }
-}
 function cmdServers(logger, configPath) {
     try {
         const config = loadConfig({ configPath, logger });
@@ -411,27 +389,6 @@ function cmdServers(logger, configPath) {
         process.exit(1);
     }
 }
-async function cmdSearch(query, logger) {
-    const client = new CatalogClient({ logger });
-    try {
-        const searchResponse = await client.search(query);
-        const results = Array.isArray(searchResponse) ? searchResponse : searchResponse.results || [];
-        if (results.length === 0) {
-            process.stdout.write(`No servers matching "${query}"\n`);
-            return;
-        }
-        process.stdout.write(`\nSearch results for "${query}" (${results.length} found):\n\n`);
-        for (const [i, r] of results.entries()) {
-            const auth = r.authSummary || (r.authRequired ? "required" : "none");
-            process.stdout.write(`  ${i + 1}  ${(r.name || "").padEnd(22)}[${auth}] ${r.description || ""}\n`);
-        }
-        process.stdout.write("\n");
-    }
-    catch (err) {
-        logger.error(`Search failed: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
-    }
-}
 function resolveConfigPath(configPath) {
     if (!configPath) {
         return join(homedir(), ".mcp-bridge", "config.json");
@@ -547,27 +504,22 @@ function cmdLimit(args, logger) {
 async function cmdInstall(serverName, args, logger) {
     const configPath = resolveConfigPath(args.configPath);
     const configDir = dirname(configPath);
-    // Ensure config dir exists
     if (!existsSync(configDir)) {
         mkdirSync(configDir, { recursive: true });
     }
-    // Ensure config file exists
     if (!existsSync(configPath)) {
         writeFileSync(configPath, JSON.stringify({ servers: {} }, null, 2) + "\n", "utf-8");
         logger.info(`Created config: ${configPath}`);
     }
-    // Read current config
     const raw = JSON.parse(readFileSync(configPath, "utf-8"));
     if (!raw.servers)
         raw.servers = {};
-    // Check if already configured
     if (raw.servers[serverName]) {
         process.stdout.write(`Server "${serverName}" is already configured.\n`);
         process.stdout.write(`Config: ${configPath}\n`);
         return;
     }
-    // Fetch recipe from catalog
-    process.stdout.write(`Fetching recipe for ${serverName}...\n`);
+    process.stdout.write(`Fetching recipe for ${serverName} from bridge.aiwerk.ch...\n`);
     const cacheDir = join(configDir, "recipes");
     const client = new CatalogClient({ cacheDir, logger });
     let recipe;
@@ -575,74 +527,100 @@ async function cmdInstall(serverName, args, logger) {
         recipe = await client.resolve(serverName);
     }
     catch (err) {
-        logger.error(`Recipe not found: ${serverName}`);
+        if (err instanceof CatalogSignatureError) {
+            logger.error(err.message);
+            process.stderr.write(`\nThe recipe was rejected because its Ed25519 signature did not match the AIWerk catalog public key. This means either the catalog was tampered with in transit, or your local cache was modified. Nothing has been written to your config.\n`);
+        }
+        else if (err instanceof CatalogError) {
+            logger.error(err.message);
+        }
+        else {
+            logger.error(`Failed to fetch recipe: ${err instanceof Error ? err.message : String(err)}`);
+        }
         process.exit(1);
     }
-    // Convert recipe to server config
+    if (recipe.localOnly) {
+        process.stdout.write(`\nNote: "${serverName}" is marked localOnly — it needs your local environment (browser, display, USB, or user-specific paths) and cannot run on the hosted bridge. You are installing it locally, which is the right place.\n\n`);
+    }
     const serverConfig = recipeToServerConfig(recipe);
     if (!serverConfig) {
         logger.error(`Unsupported recipe format for "${serverName}"`);
         process.exit(1);
     }
-    // Check required env vars
     const requiredVars = collectRequiredEnvVars(recipe);
-    const missing = requiredVars.filter(v => !process.env[v]);
-    // Add to config
+    const missing = requiredVars.filter((v) => v !== "__AUTH_REQUIRED__" && !process.env[v]);
     raw.servers[serverName] = serverConfig;
     writeFileSync(configPath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
-    process.stdout.write(`\n✓ Added "${serverName}" to ${configPath}\n\n`);
+    process.stdout.write(`✓ Added "${serverName}" to ${configPath}\n\n`);
     if (missing.length > 0) {
-        process.stdout.write(`⚠ Missing environment variables:\n`);
+        process.stdout.write(`Missing environment variables:\n`);
         for (const v of missing) {
             process.stdout.write(`  ${v}\n`);
         }
-        // Show credentials URL if available
         const credUrl = recipe.auth?.credentialsUrl;
-        if (credUrl) {
+        if (typeof credUrl === "string") {
             process.stdout.write(`\nGet credentials: ${credUrl}\n`);
         }
         process.stdout.write(`\nSet them in your environment or ~/.mcp-bridge/.env before starting the bridge.\n`);
     }
-    else {
+    else if (requiredVars.length > 0) {
         process.stdout.write(`All required environment variables are set. Ready to use.\n`);
     }
-    // Pre-discover tools and cache them (so direct mode has tools on first start)
-    // Try even with missing env vars — many servers respond to tools/list without auth
-    process.stdout.write(`\nDiscovering tools...\n`);
-    {
-        try {
-            const { StdioTransport } = await import("../src/transport-stdio.js");
-            const { SseTransport } = await import("../src/transport-sse.js");
-            const { StreamableHttpTransport } = await import("../src/transport-streamable-http.js");
-            const { fetchToolsList, initializeProtocol, PACKAGE_VERSION } = await import("../src/protocol.js");
-            let transport;
-            if (serverConfig.transport === "stdio") {
-                transport = new StdioTransport(serverConfig, { servers: {} }, logger, async () => { });
-            }
-            else if (serverConfig.transport === "sse") {
-                transport = new SseTransport(serverConfig, { servers: {} }, logger, async () => { });
-            }
-            else if (serverConfig.transport === "streamable-http") {
-                transport = new StreamableHttpTransport(serverConfig, { servers: {} }, logger, async () => { });
-            }
-            if (transport) {
-                await transport.connect();
-                await initializeProtocol(transport, PACKAGE_VERSION);
-                const tools = await fetchToolsList(transport);
-                // Save to cache
-                const cacheToolDir = join(configDir, "cache");
-                mkdirSync(cacheToolDir, { recursive: true });
-                writeFileSync(join(cacheToolDir, `${serverName}-tools.json`), JSON.stringify(tools, null, 2), "utf-8");
-                process.stdout.write(`✓ Cached ${tools.length} tools from "${serverName}"\n`);
-                // Disconnect
-                await transport.disconnect().catch(() => { });
-            }
+    else {
+        process.stdout.write(`No credentials required. Ready to use.\n`);
+    }
+}
+async function cmdCatalog(args, logger) {
+    const configPath = resolveConfigPath(args.configPath);
+    const cacheDir = join(dirname(configPath), "recipes");
+    const client = new CatalogClient({ cacheDir, logger });
+    if (args.offline) {
+        const cached = client.listCached();
+        if (cached.length === 0) {
+            process.stdout.write(`No cached recipes. Run 'mcp-bridge install <server>' to fetch one.\n`);
+            return;
+        }
+        process.stdout.write(`\nCached recipes (${cached.length}):\n\n`);
+        for (const name of cached.sort()) {
+            const r = client.getCached(name);
+            const desc = r?.description ?? "";
+            process.stdout.write(`  ${name.padEnd(24)}${desc.slice(0, 60)}\n`);
         }
-        catch (discErr) {
-            // Non-fatal: tool discovery is a nice-to-have, server still installed
-            logger.info(`Tool discovery skipped: ${discErr instanceof Error ? discErr.message : String(discErr)}`);
-            process.stdout.write(`Tool discovery skipped (server will discover tools on first use).\n`);
+        return;
+    }
+    try {
+        const { results } = await client.list({ limit: 100 });
+        process.stdout.write(`\nAvailable servers (${results.length} from bridge.aiwerk.ch):\n\n`);
+        for (const r of results) {
+            const desc = (r.description ?? "").slice(0, 60);
+            process.stdout.write(`  ${r.name.padEnd(24)}${desc}\n`);
         }
+        process.stdout.write(`\nInstall: mcp-bridge install <name>\n`);
+    }
+    catch (err) {
+        logger.error(`Failed to fetch catalog: ${err instanceof Error ? err.message : String(err)}`);
+        process.stderr.write(`Use 'mcp-bridge catalog --offline' to list cached recipes.\n`);
+        process.exit(1);
+    }
+}
+async function cmdSearch(query, logger) {
+    const client = new CatalogClient({ logger });
+    try {
+        const results = await client.search(query);
+        if (results.length === 0) {
+            process.stdout.write(`No matches for "${query}".\n`);
+            return;
+        }
+        process.stdout.write(`\nMatches for "${query}" (${results.length}):\n\n`);
+        for (const r of results) {
+            const desc = (r.description ?? "").slice(0, 60);
+            process.stdout.write(`  ${r.name.padEnd(24)}${desc}\n`);
+        }
+        process.stdout.write(`\nInstall: mcp-bridge install <name>\n`);
+    }
+    catch (err) {
+        logger.error(`Search failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
     }
 }
 function cmdRemove(serverName, args, logger) {
@@ -812,23 +790,10 @@ async function cmdAuth(args, logger) {
                 process.stdout.write(`  ${name.padEnd(maxName)}${label.padEnd(14)}${envStatus.slice(0, 27).padEnd(28)}${status}\n`);
                 // Show help for missing env vars
                 if (status === "missing env vars") {
-                    try {
-                        const cacheDir = join(dirname(resolveConfigPath(args.configPath)), "recipes");
-                        const helpClient = new CatalogClient({ cacheDir, logger });
-                        const recipe = await helpClient.resolve(name);
-                        const recipeAuth = recipe?.auth;
-                        if (recipeAuth?.credentialsUrl) {
-                            process.stdout.write(`  ${" ".repeat(maxName)}Get credentials: ${recipeAuth.credentialsUrl}\n`);
-                        }
-                        if (recipeAuth?.instructions) {
-                            process.stdout.write(`  ${" ".repeat(maxName)}${recipeAuth.instructions}\n`);
-                        }
-                        const missingKeys = envKeys.filter(k => !envVars.has(k) && !process.env[k]);
-                        if (missingKeys.length > 0) {
-                            process.stdout.write(`  ${" ".repeat(maxName)}Set with: mcp-bridge set-env ${missingKeys[0]} <your-key>\n`);
-                        }
+                    const missingKeys = envKeys.filter(k => !envVars.has(k) && !process.env[k]);
+                    if (missingKeys.length > 0) {
+                        process.stdout.write(`  ${" ".repeat(maxName)}Set with: mcp-bridge set-env ${missingKeys[0]} <your-key>\n`);
                     }
-                    catch { /* recipe not in cache, skip help */ }
                 }
                 shown.add(name);
             }
@@ -928,8 +893,6 @@ async function cmdServe(args, logger) {
         logger.error("HTTP auth not configured. Set http.auth in config or use stdio mode.");
         process.exit(1);
     }
-    // Warn about deprecated bundled recipes (v2.8.0+)
-    warnDeprecatedBundledRecipes(logger);
     const server = new StandaloneServer(config, logger);
     // Graceful shutdown
     const shutdown = async () => {
@@ -961,19 +924,9 @@ async function main() {
         case "init":
             cmdInit(logger, args.register, args.mode);
             break;
-        case "catalog":
-            await cmdCatalog(logger, args.offline);
-            break;
         case "servers":
             cmdServers(logger, args.configPath);
             break;
-        case "search":
-            if (args.positional.length === 0) {
-                process.stderr.write("Usage: mcp-bridge search <query>\n");
-                process.exit(1);
-            }
-            await cmdSearch(args.positional[0], logger);
-            break;
         case "usage":
             cmdUsage(args.configPath, logger);
             break;
@@ -987,6 +940,16 @@ async function main() {
             }
             await cmdInstall(args.positional[0], args, logger);
             break;
+        case "catalog":
+            await cmdCatalog(args, logger);
+            break;
+        case "search":
+            if (args.positional.length === 0) {
+                process.stderr.write("Usage: mcp-bridge search <query>\n");
+                process.exit(1);
+            }
+            await cmdSearch(args.positional.join(" "), logger);
+            break;
         case "remove":
             if (args.positional.length === 0) {
                 process.stderr.write("Usage: mcp-bridge remove <server>\n");

package/dist/src/catalog-client.d.ts

@@ -1,8 +1,11 @@
 /**
- * CatalogClient — REST client for the AIWerk MCP Catalog API.
+ * CatalogClient — REST client for the AIWerk MCP catalog at bridge.aiwerk.ch.
  *
- * Default endpoint: https://catalog.aiwerk.ch
- * Supports local file caching with offline fallback.
+ * Restored 2026-05-03 after maintenance mode ended. Endpoint moved from the
+ * historical catalog.aiwerk.ch to bridge.aiwerk.ch/api/recipes/<name>/download.
+ * Every fetched recipe is Ed25519-verified against the bundled AIWerk public
+ * key before it is cached or returned. Unsigned or tampered recipes are
+ * refused.
  */
 import type { Logger } from "./types.js";
 export interface CatalogSearchResult {
@@ -12,6 +15,13 @@ export interface CatalogSearchResult {
     quality?: number;
     [key: string]: unknown;
 }
+export interface RecipeSignature {
+    algorithm: string;
+    publisherId: string;
+    value: string;
+    signedFields: string[];
+    signedAt: string;
+}
 export interface CatalogRecipe {
     name: string;
     description?: string;
@@ -30,6 +40,9 @@ export interface CatalogRecipe {
         headers?: Record<string, string>;
     }>;
     install?: {
+        method?: string;
+        package?: string;
+        version?: string;
         npm?: {
             package: string;
             version?: string;
@@ -44,34 +57,49 @@ export interface CatalogRecipe {
         envVars?: string[];
         credentialsUrl?: string;
     };
+    signature?: RecipeSignature;
+    localOnly?: boolean;
     [key: string]: unknown;
 }
 export declare class CatalogError extends Error {
     constructor(message: string);
 }
+export declare class CatalogSignatureError extends CatalogError {
+    constructor(message: string);
+}
 /**
- * CatalogClient — REST client for the AIWerk MCP Catalog API.
- *
- * NOTE: File I/O operations (readCache, writeCache, etc.) are intentionally
- * synchronous. This is acceptable for CLI tools and bridge startup, but
- * should be converted to async if used in hot paths (e.g., per-request).
+ * Verify the Ed25519 signature on a recipe against the bundled AIWerk public
+ * key. Throws CatalogSignatureError on any failure (missing signature, wrong
+ * algorithm, tampered payload, key mismatch).
+ */
+export declare function verifyRecipeSignature(recipe: CatalogRecipe): void;
+export interface CatalogClientOptions {
+    baseUrl?: string;
+    cacheDir?: string;
+    logger?: Logger;
+    staleDays?: number;
+    /** Skip signature verification (testing only). */
+    skipSignatureVerify?: boolean;
+}
+/**
+ * REST client for the AIWerk MCP catalog. File I/O is intentionally
+ * synchronous — fine for CLI tools and bridge startup. Signature verification
+ * runs on every fetch (including cache reads) so a tampered cache cannot
+ * silently slip through.
  */
 export declare class CatalogClient {
     private baseUrl;
     private cacheDir;
     private logger;
     private staleMs;
-    constructor(opts?: {
-        baseUrl?: string;
-        cacheDir?: string;
-        logger?: Logger;
-        staleDays?: number;
-    });
+    private skipSignatureVerify;
+    constructor(opts?: CatalogClientOptions);
     private fetchJson;
     private cachePath;
     private readCache;
     private writeCache;
     private isCacheStale;
+    private verifyOrThrow;
     /** Search for recipes by keyword. */
     search(query: string): Promise<CatalogSearchResult[]>;
     /** List recipes with optional filtering. */
@@ -79,23 +107,23 @@ export declare class CatalogClient {
         limit?: number;
         category?: string;
         sort?: string;
-        hostedSafe?: boolean;
     }): Promise<{
         results: CatalogSearchResult[];
         total: number;
     }>;
-    /** Download a recipe from the catalog and cache it locally. */
-    download(name: string): Promise<CatalogRecipe>;
     /**
-     * Resolve a recipe — returns cached if available, otherwise fetches from catalog.
-     * Falls back to cache when the catalog is unreachable (offline mode).
+     * Download a recipe from the catalog, verify its signature, and cache it
+     * locally. Throws CatalogSignatureError if the recipe is unsigned or
+     * tampered — nothing is written to the cache in that case.
      */
-    resolve(name: string): Promise<CatalogRecipe>;
+    download(name: string): Promise<CatalogRecipe>;
     /**
-     * Bootstrap by downloading the top N most popular recipes.
-     * Skips already-cached recipes unless they are stale.
+     * Resolve a recipe by name. Returns the cached copy if fresh; otherwise
+     * fetches from the catalog. Falls back to a stale cache if the network is
+     * unreachable. Signature is verified on both fresh and cached paths so a
+     * tampered cache cannot slip through.
      */
-    bootstrap(limit?: number, hostedSafe?: boolean): Promise<string[]>;
+    resolve(name: string): Promise<CatalogRecipe>;
     /** Synchronously read a recipe from local cache. Returns null if not cached. */
     getCached(name: string): CatalogRecipe | null;
     /** List all recipe names in the local cache. */