@cyanmycelium/mcp-broker 0.2.0 → 0.4.0

package/src/broker/broker.server.ts

@@ -1,9 +1,8 @@
-import { McpGrammar, McpServerBuilder, LoopbackTransport } from "@cyanmycelium/mcp-core";
-import type { IMcpServer, IMessageTransport } from "@cyanmycelium/mcp-core";
+import { McpServerBuilder, LoopbackTransport } from "@cyanmycelium/mcp-core";
+import type { GrammarResolverOptions, IMcpServer, IMessageTransport } from "@cyanmycelium/mcp-core";
 import { BrokerInfoBehavior } from "./behaviors/broker.behavior.info.js";
 import { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers.js";
-import { brokerGrammarKey, defaultBrokerLocaleResolver, defaultBrokerUserAgentResolver, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom } from "./broker.grammars.js";
-import type { BrokerLocaleResolver, BrokerUserAgent, BrokerUserAgentResolver } from "./broker.grammars.js";
+import { iterAvailableBrokerGrammars, iterBrokerGrammarsFrom } from "./broker.grammars.js";
 import type { BrokerContext } from "./broker.context.js";
 
 /**
@@ -22,32 +21,33 @@ export const BROKER_PROVIDER_NAME = "_broker";
  */
 export interface StartBrokerServerOptions {
     /**
-     * Picks a locale (BCP-47 base language, by convention) for the current
-     * session. Defaults to {@link defaultBrokerLocaleResolver} which reads
-     * `MCP_BROKER_LOCALE` and keeps the ISO 639-1 prefix.
-     */
-    localeResolver?: BrokerLocaleResolver;
-
-    /**
-     * Picks a user-agent family for the connecting client. Defaults to
-     * {@link defaultBrokerUserAgentResolver} which substring-matches
-     * `clientInfo.name` against known LLM families.
-     */
-    userAgentResolver?: BrokerUserAgentResolver;
-
-    /**
-     * Source of the raw locale string fed to the locale resolver. Defaults
-     * to `process.env.MCP_BROKER_LOCALE`. Override when the locale lives
-     * somewhere else (config file, session metadata, HTTP header proxy, ...).
+     * Overrides for the built-in grammar resolver from `@cyanmycelium/mcp-core`.
+     *
+     * The broker installs sensible defaults: `localeSource` reads
+     * `process.env.MCP_BROKER_LOCALE`, the `agents` map uses the mcp-core
+     * defaults (`claude`, `gpt`, `mistral`, `copilot`, `default`), the
+     * narrowing chain is BCP-47-style, and `fallbackKey` is `default:en`
+     * so the baseline grammar always matches as last resort.
+     *
+     * Pass partial overrides here to inject a custom `localeSource` (e.g.
+     * pull from an HTTP header proxied by your transport), enable the
+     * `versionFrom` dimension, or extend the `agents` map with additional
+     * LLM families. Anything you omit keeps the broker default.
      */
-    localeSource?: () => string | undefined;
+    grammarResolverOptions?: Partial<GrammarResolverOptions>;
 
     /**
      * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
-     * files are merged **on top of** the packaged grammars. Local entries win
-     * on conflicts; missing entries fall through to the packaged values.
+     * files are registered **in addition to** the packaged grammars.
+     *
+     * Both packaged and local entries are registered raw against the server
+     * via `withGrammar(brokerGrammarKey(ua, locale), grammar)`. The
+     * candidate-chain resolution implemented by `McpServer.initialize` in
+     * mcp-core@0.3.0 then walks the chain and merges the four layers
+     * (behavior, adapter, static, store) for the first matching key —
+     * the old hand-rolled pre-merge cascade is no longer needed.
      *
-     * When `undefined` (default), only the packaged grammars are used.
+     * When `undefined` (default), only the packaged grammars are loaded.
      */
     localGrammarsDir?: string;
 }
@@ -75,87 +75,45 @@ export async function startBrokerServer(
     server: IMcpServer;
     clientTransport: IMessageTransport;
 }> {
-    const localeResolver = options.localeResolver ?? defaultBrokerLocaleResolver;
-    const userAgentResolver = options.userAgentResolver ?? defaultBrokerUserAgentResolver;
-    const localeSource = options.localeSource ?? (() => process.env["MCP_BROKER_LOCALE"]);
-
     const [serverEnd, clientEnd] = LoopbackTransport.createPair();
 
-    const builder = new McpServerBuilder().withName(BROKER_PROVIDER_NAME).withTransport(serverEnd).register(new BrokerInfoBehavior(context), new BrokerProvidersBehavior(context));
-
-    // Discover every grammar by scanning two directories:
-    //   1. The packaged grammars shipped with the broker.
-    //   2. Optionally, a user-supplied directory whose entries are merged
-    //      ON TOP of the packaged ones (local wins on conflicts).
-    //
-    // Then build the (userAgent × locale) matrix. Within each user-agent,
-    // the grammar cascades on top of "default:<locale>" so per-user-agent
-    // files can stay partial.
-    const defaults = new Map<string, McpGrammar>(); // locale → grammar
-    const overrides = new Map<BrokerUserAgent, Map<string, McpGrammar>>(); // userAgent → locale → grammar
-
-    function ingest(entry: { userAgent: BrokerUserAgent; locale: string; grammar: McpGrammar }, isOverride: boolean): void {
-        if (entry.userAgent === "default") {
-            const existing = defaults.get(entry.locale);
-            const merged = existing && isOverride ? McpGrammar.merge(existing, entry.grammar) : entry.grammar;
-            defaults.set(entry.locale, merged);
-        } else {
-            let byLocale = overrides.get(entry.userAgent);
-            if (!byLocale) {
-                byLocale = new Map();
-                overrides.set(entry.userAgent, byLocale);
-            }
-            const existing = byLocale.get(entry.locale);
-            const merged = existing && isOverride ? McpGrammar.merge(existing, entry.grammar) : entry.grammar;
-            byLocale.set(entry.locale, merged);
-        }
+    // Without an initializer, McpServerBuilder reports `version: "0.0.0"` in the
+    // `initialize` handshake. Supply the real package version from the context.
+    const builder = new McpServerBuilder()
+        .withName(BROKER_PROVIDER_NAME)
+        .withTransport(serverEnd)
+        .withInitializer({
+            initialize: () => ({
+                protocolVersion: "2024-11-05",
+                serverInfo: { name: BROKER_PROVIDER_NAME, version: context.version },
+            }),
+        })
+        .register(new BrokerInfoBehavior(context), new BrokerProvidersBehavior(context));
+
+    // Register every `(userAgent, locale)` JSON found on disk as a raw
+    // grammar layer. The candidate-chain resolution in
+    // McpServer.initialize (mcp-core@0.3.0) walks the resolver's chain
+    // and merges all matching layers — so partial user-agent files no
+    // longer need to be pre-merged with the default-locale baseline at
+    // boot. Local overrides come after packaged entries; identical keys
+    // get overlaid via the registry's last-write-wins.
+    for (const entry of iterAvailableBrokerGrammars()) {
+        builder.withGrammar(entry.key, entry.grammar);
     }
-
-    for (const entry of iterAvailableBrokerGrammars()) ingest(entry, false);
     if (options.localGrammarsDir) {
-        for (const entry of iterBrokerGrammarsFrom(options.localGrammarsDir)) ingest(entry, true);
-    }
-
-    const availableKeys = new Set<string>();
-
-    // Register every "default:<locale>" as-is.
-    for (const [locale, grammar] of defaults) {
-        const key = brokerGrammarKey("default", locale);
-        builder.withGrammar(key, grammar);
-        availableKeys.add(key);
-    }
-
-    // Register every "<userAgent>:<locale>" as merge(default:<locale>, ua:<locale>).
-    // The user-agent grammar wins per entry; missing entries cascade from default.
-    for (const [agent, byLocale] of overrides) {
-        for (const [locale, uaGrammar] of byLocale) {
-            const baseline = defaults.get(locale);
-            const merged = baseline ? McpGrammar.merge(baseline, uaGrammar) : uaGrammar;
-            const key = brokerGrammarKey(agent, locale);
-            builder.withGrammar(key, merged);
-            availableKeys.add(key);
+        for (const entry of iterBrokerGrammarsFrom(options.localGrammarsDir)) {
+            builder.withGrammar(entry.key, entry.grammar);
         }
     }
 
-    builder.withGrammarResolver((clientInfo) => {
-        // localeResolver returns the full fallback chain (most specific first),
-        // ending with the universal "en". The user-agent axis is the broker's
-        // own concern: per locale, prefer the user-agent-specific grammar, then
-        // fall back to the "default" agent.
-        const locales = localeResolver(localeSource());
-        const userAgent = userAgentResolver(clientInfo);
-        const userAgents = userAgent === "default" ? ["default"] : [userAgent, "default"];
-
-        for (const locale of locales) {
-            for (const ua of userAgents) {
-                const key = brokerGrammarKey(ua, locale);
-                if (availableKeys.has(key)) return key;
-            }
-        }
-
-        // None of the candidates is on disk → return an empty key. McpServer
-        // then falls back to the behavior's baseline descriptions (English).
-        return "";
+    // Wire the resolver via mcp-core's declarative helper. The broker
+    // ships sensible defaults (locale from MCP_BROKER_LOCALE env, agents
+    // from mcp-core's catalogue, BCP-47 narrowing, default:en fallback);
+    // anything the host application sets via `grammarResolverOptions`
+    // takes precedence.
+    builder.withGrammarResolver({
+        localeSource: () => process.env["MCP_BROKER_LOCALE"],
+        ...(options.grammarResolverOptions ?? {}),
     });
 
     // No reconnect policy → the McpServer does not attempt to reopen the loopback

package/src/broker/index.ts

@@ -13,12 +13,10 @@ export {
     brokerBaselineResourceTemplateName,
     brokerBaselineToolDescription,
     brokerGrammarKey,
-    defaultBrokerLocaleResolver,
-    defaultBrokerUserAgentResolver,
     iterAvailableBrokerGrammars,
+    iterBrokerGrammarsFrom,
     loadBrokerGrammar,
-    resolveBrokerLocale,
-    resolveBrokerUserAgent,
+    parseBrokerGrammarStem,
 } from "./broker.grammars.js";
-export type { BrokerLocale, BrokerLocaleResolver, BrokerUserAgent, BrokerUserAgentResolver } from "./broker.grammars.js";
+export type { BrokerGrammarEntry, BrokerLocale, BrokerUserAgent } from "./broker.grammars.js";
 export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport } from "./broker.context.js";

package/src/config.ts

@@ -73,6 +73,43 @@ export interface BrokerConfig {
         command: string;
         args?: string[];
         env?: Record<string, string>;
+        /** When `true`, the upstream joins the `_all` aggregate slot once connected. */
+        aggregate?: boolean;
+    }>;
+
+    /**
+     * Remote MCP servers the broker connects out to and exposes as provider
+     * slots. Each entry is reached by URL (Streamable HTTP / SSE / WebSocket);
+     * local servers should be shipped as `.mcpb` bundles instead.
+     */
+    mcpServers?: Array<{
+        name: string;
+        url: string;
+        transport?: "streamable-http" | "sse" | "websocket";
+        headers?: Record<string, string>;
+        /** Defaults to `true`; set to `false` to exclude this upstream from the `_all` aggregate slot. */
+        aggregate?: boolean;
+    }>;
+
+    /**
+     * Local `.mcpb` bundles the broker loads at startup and runs as stdio
+     * provider slots. A bundle is a ZIP with a `manifest.json`; the broker
+     * verifies a detached signature against a trusted public key before
+     * unpacking and spawning it.
+     */
+    mcpbBundles?: Array<{
+        /** Provider slot name the bundle is bound to. */
+        name: string;
+        /** Path to the `.mcpb` file (resolved against the config file's directory). */
+        path: string;
+        /** Path to the trusted public key (PEM) used to verify the detached signature. */
+        publicKey: string;
+        /** Path to the detached signature file. Defaults to `<path>.sig`. */
+        signature?: string;
+        /** Values substituted into the manifest's `${user_config.*}` placeholders. */
+        userConfig?: Record<string, string | number | boolean | Array<string | number>>;
+        /** Defaults to `true`; set to `false` to exclude this bundle from the `_all` aggregate slot. */
+        aggregate?: boolean;
     }>;
 }
 

package/src/index.ts

@@ -3,20 +3,20 @@ export { WsTunnelBuilder } from "./ws.tunnel.builder.js";
 export type { WsTunnelOptions, StaticMount } from "./ws.tunnel.js";
 export { StdioUpstream } from "./stdio.upstream.js";
 export type { StdioUpstreamConfig } from "./stdio.upstream.js";
+export { RemoteUpstream } from "./remote.upstream.js";
+export type { RemoteUpstreamConfig } from "./remote.upstream.js";
+export type { Upstream } from "./upstream.js";
+
+// `.mcpb` bundle loading — verifies + unpacks a bundle into a stdio upstream.
+export { loadMcpbBundle } from "./mcpb.loader.js";
+export type { McpbBundleConfig } from "./mcpb.loader.js";
+export { unzipMcpb } from "./mcpb.unzip.js";
 
 // Broker introspection — tier 1.
 export { BrokerInfoBehavior, BrokerProvidersBehavior, startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
 export type { StartBrokerServerOptions } from "./broker/index.js";
-export {
-    brokerGrammarKey,
-    defaultBrokerLocaleResolver,
-    defaultBrokerUserAgentResolver,
-    iterAvailableBrokerGrammars,
-    loadBrokerGrammar,
-    resolveBrokerLocale,
-    resolveBrokerUserAgent,
-} from "./broker/index.js";
-export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport, BrokerLocale, BrokerLocaleResolver, BrokerUserAgent, BrokerUserAgentResolver } from "./broker/index.js";
+export { brokerGrammarKey, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerGrammar } from "./broker/index.js";
+export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport, BrokerLocale, BrokerUserAgent } from "./broker/index.js";
 
 export { VERSION, PACKAGE_NAME } from "./version.js";
 

package/src/mcpb.loader.ts

@@ -0,0 +1,186 @@
+/**
+ * Loads a local `.mcpb` bundle into a {@link StdioUpstreamConfig}.
+ *
+ * A `.mcpb` bundle is a ZIP holding a `manifest.json` whose `server.mcp_config`
+ * describes a stdio MCP server process. The broker:
+ *
+ * 1. verifies a **detached signature** of the `.mcpb` file against a trusted
+ *    public key (PEM) — integrity *and* provenance, using `node:crypto` only;
+ * 2. unpacks the archive;
+ * 3. reads the manifest, expands the `mcp_config` placeholders, and produces a
+ *    `StdioUpstreamConfig` that the existing upstream wiring spawns.
+ *
+ * The broker stays compatible with the `.mcpb` format without depending on the
+ * `@anthropic-ai/mcpb` package: the bundle's *own* (native PKCS#7) signature is
+ * never parsed — the detached signature layer is the broker's trust anchor.
+ *
+ * Any failure (missing files, bad signature, malformed manifest, missing
+ * `user_config` value) is logged and yields `null`: the bundle is refused and
+ * no process is ever spawned. Never auto-runs an unverified bundle.
+ */
+import { createPublicKey, verify, X509Certificate, type KeyObject } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { unzipMcpb } from "./mcpb.unzip.js";
+import type { StdioUpstreamConfig } from "./stdio.upstream.js";
+
+/** A `.mcpb` bundle entry from the broker config file. */
+export interface McpbBundleConfig {
+    /** Provider slot name the bundle is bound to. */
+    name: string;
+    /** Path to the `.mcpb` file. */
+    path: string;
+    /** Path to the trusted public key (PEM) verifying the detached signature. */
+    publicKey: string;
+    /** Path to the detached signature file. Defaults to `<path>.sig`. */
+    signature?: string;
+    /** Values substituted into the manifest's `${user_config.*}` placeholders. */
+    userConfig?: Record<string, string | number | boolean | Array<string | number>>;
+    /** When `false`, the bundle stays out of the `_all` aggregate slot. Defaults to `true`. */
+    aggregate?: boolean;
+}
+
+interface McpConfig {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    platform_overrides?: Record<string, { command?: string; args?: string[]; env?: Record<string, string> }>;
+}
+
+/** Loads a PEM that holds either an X.509 certificate or a bare public key. */
+function loadPublicKey(pem: string): KeyObject {
+    if (pem.includes("BEGIN CERTIFICATE")) {
+        return new X509Certificate(pem).publicKey;
+    }
+    return createPublicKey(pem);
+}
+
+/** Verifies the detached `signature` of `data` against `publicKey`. */
+function verifyDetachedSignature(data: Buffer, signature: Buffer, publicKey: KeyObject): boolean {
+    // Ed25519/Ed448 are used without a separate hash algorithm; RSA/EC need one.
+    const keyType = publicKey.asymmetricKeyType;
+    const algorithm = keyType === "ed25519" || keyType === "ed448" ? null : "sha256";
+    return verify(algorithm, data, publicKey, signature);
+}
+
+/** Resolves a single `${...}` placeholder key, or `undefined` when unknown. */
+function resolvePlaceholder(key: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string | number | boolean | Array<string | number> | undefined {
+    if (key === "__dirname") return dirname;
+    if (key === "HOME") return homedir();
+    if (key === "DESKTOP") return join(homedir(), "Desktop");
+    if (key === "DOCUMENTS") return join(homedir(), "Documents");
+    if (key === "DOWNLOADS") return join(homedir(), "Downloads");
+    if (key === "pathSeparator" || key === "/") return sep;
+    if (key.startsWith("user_config.")) {
+        const name = key.slice("user_config.".length);
+        const value = userConfig?.[name];
+        if (value === undefined) throw new Error(`missing user_config value: "${name}"`);
+        return value;
+    }
+    return undefined;
+}
+
+/** Expands placeholders in a scalar string (command, env value). */
+function expandScalar(input: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string {
+    return input.replace(/\$\{([^}]+)\}/g, (match, key: string) => {
+        const value = resolvePlaceholder(key, dirname, userConfig);
+        if (value === undefined) return match; // unknown placeholder — leave verbatim
+        if (Array.isArray(value)) throw new Error(`placeholder "\${${key}}" is multi-valued and cannot be used here`);
+        return String(value);
+    });
+}
+
+/** Expands one manifest argument; a standalone multi-valued placeholder spreads. */
+function expandArg(arg: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string[] {
+    const standalone = /^\$\{(user_config\.[^}]+)\}$/.exec(arg);
+    if (standalone) {
+        const value = resolvePlaceholder(standalone[1], dirname, userConfig);
+        if (Array.isArray(value)) return value.map(String);
+        return [String(value)];
+    }
+    return [expandScalar(arg, dirname, userConfig)];
+}
+
+/**
+ * Verifies, unpacks and resolves a `.mcpb` bundle into a `StdioUpstreamConfig`.
+ *
+ * @param cfg      The bundle entry from the broker config.
+ * @param baseDir  Directory the bundle paths are resolved against.
+ * @returns        A ready upstream config, or `null` when the bundle is refused.
+ */
+export async function loadMcpbBundle(cfg: McpbBundleConfig, baseDir: string): Promise<StdioUpstreamConfig | null> {
+    const tag = `[mcp-broker] mcpb bundle "${cfg.name}"`;
+    try {
+        const mcpbPath = resolve(baseDir, cfg.path);
+        const publicKeyPath = resolve(baseDir, cfg.publicKey);
+        const signaturePath = cfg.signature ? resolve(baseDir, cfg.signature) : `${mcpbPath}.sig`;
+
+        for (const [label, file] of [
+            ["bundle", mcpbPath],
+            ["public key", publicKeyPath],
+            ["signature", signaturePath],
+        ] as const) {
+            if (!existsSync(file)) {
+                console.error(`${tag}: ${label} file not found at ${file} — bundle refused.`);
+                return null;
+            }
+        }
+
+        // ── Signature verification (mandatory) ──────────────────────────────
+        const bundleBytes = readFileSync(mcpbPath);
+        const signatureBytes = readFileSync(signaturePath);
+        const publicKey = loadPublicKey(readFileSync(publicKeyPath, "utf8"));
+        if (!verifyDetachedSignature(bundleBytes, signatureBytes, publicKey)) {
+            console.error(`${tag}: detached signature is invalid for the configured public key — bundle refused.`);
+            return null;
+        }
+
+        // ── Unpack ──────────────────────────────────────────────────────────
+        const outputDir = resolve(baseDir, ".cache", "mcpb", cfg.name);
+        rmSync(outputDir, { recursive: true, force: true });
+        unzipMcpb(mcpbPath, outputDir);
+
+        // ── Manifest → mcp_config ───────────────────────────────────────────
+        const manifestPath = join(outputDir, "manifest.json");
+        if (!existsSync(manifestPath)) {
+            console.error(`${tag}: manifest.json missing inside the bundle — bundle refused.`);
+            return null;
+        }
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { server?: { mcp_config?: McpConfig } };
+        const mcpConfig = manifest.server?.mcp_config;
+        if (!mcpConfig) {
+            console.error(`${tag}: manifest has no server.mcp_config — bundle refused.`);
+            return null;
+        }
+
+        // Platform-specific overrides replace the base fields when present.
+        const override = mcpConfig.platform_overrides?.[process.platform];
+        const command = override?.command ?? mcpConfig.command;
+        const rawArgs = override?.args ?? mcpConfig.args ?? [];
+        const rawEnv = { ...mcpConfig.env, ...override?.env };
+        if (!command) {
+            console.error(`${tag}: manifest mcp_config has no command — bundle refused.`);
+            return null;
+        }
+
+        // ── Placeholder expansion ───────────────────────────────────────────
+        const expandedCommand = expandScalar(command, outputDir, cfg.userConfig);
+        const expandedArgs = rawArgs.flatMap((arg) => expandArg(arg, outputDir, cfg.userConfig));
+        const expandedEnv: Record<string, string> = {};
+        for (const [key, value] of Object.entries(rawEnv)) {
+            expandedEnv[key] = expandScalar(value, outputDir, cfg.userConfig);
+        }
+
+        return {
+            name: cfg.name,
+            command: expandedCommand,
+            args: expandedArgs,
+            env: Object.keys(expandedEnv).length > 0 ? expandedEnv : undefined,
+            aggregate: cfg.aggregate ?? true,
+        };
+    } catch (err) {
+        console.error(`${tag}: ${(err as Error).message} — bundle refused.`);
+        return null;
+    }
+}

package/src/mcpb.unzip.ts

@@ -0,0 +1,103 @@
+/**
+ * Minimal ZIP extractor for `.mcpb` bundles, built on `node:zlib` only.
+ *
+ * A `.mcpb` bundle is an ordinary ZIP archive. The broker deliberately avoids
+ * the `@anthropic-ai/mcpb` package so it stays compatible with the format
+ * without being coupled to Anthropic's tooling — hence this small reader.
+ *
+ * Supports the two compression methods used in practice: stored (0) and
+ * deflate (8). ZIP64 archives are rejected with a clear error (`.mcpb` bundles
+ * are small and never need it). Any trailing bytes after the End Of Central
+ * Directory record — e.g. a native PKCS#7 signature block — are ignored, since
+ * extraction is driven entirely by the central directory.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { inflateRawSync } from "node:zlib";
+
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_HEADER_SIGNATURE = 0x02014b50;
+const LOCAL_HEADER_SIGNATURE = 0x04034b50;
+
+/** Locates the End Of Central Directory record by scanning backwards. */
+function findEocd(buf: Buffer): number {
+    // The EOCD is 22 bytes plus a comment of up to 65535 bytes.
+    const minPos = Math.max(0, buf.length - 22 - 0xffff);
+    for (let pos = buf.length - 22; pos >= minPos; pos--) {
+        if (buf.readUInt32LE(pos) === EOCD_SIGNATURE) return pos;
+    }
+    throw new Error("not a ZIP archive (no End Of Central Directory record found)");
+}
+
+/**
+ * Extracts every entry of the `.mcpb` archive at `mcpbPath` into `destDir`.
+ * `destDir` is created if missing. Entries whose resolved path would escape
+ * `destDir` (zip-slip) are rejected.
+ */
+export function unzipMcpb(mcpbPath: string, destDir: string): void {
+    const buf = readFileSync(mcpbPath);
+    const eocd = findEocd(buf);
+
+    const totalEntries = buf.readUInt16LE(eocd + 10);
+    const centralDirOffset = buf.readUInt32LE(eocd + 16);
+    if (centralDirOffset === 0xffffffff || totalEntries === 0xffff) {
+        throw new Error("ZIP64 archives are not supported");
+    }
+
+    const absDest = resolve(destDir);
+    mkdirSync(absDest, { recursive: true });
+
+    let pos = centralDirOffset;
+    for (let i = 0; i < totalEntries; i++) {
+        if (buf.readUInt32LE(pos) !== CENTRAL_HEADER_SIGNATURE) {
+            throw new Error(`corrupt ZIP: bad central directory header at offset ${pos}`);
+        }
+        const method = buf.readUInt16LE(pos + 10);
+        const compressedSize = buf.readUInt32LE(pos + 20);
+        const uncompressedSize = buf.readUInt32LE(pos + 24);
+        const nameLen = buf.readUInt16LE(pos + 28);
+        const extraLen = buf.readUInt16LE(pos + 30);
+        const commentLen = buf.readUInt16LE(pos + 32);
+        const localHeaderOffset = buf.readUInt32LE(pos + 42);
+        const name = buf.toString("utf8", pos + 46, pos + 46 + nameLen);
+        pos += 46 + nameLen + extraLen + commentLen;
+
+        if (compressedSize === 0xffffffff || uncompressedSize === 0xffffffff || localHeaderOffset === 0xffffffff) {
+            throw new Error("ZIP64 archives are not supported");
+        }
+
+        // Resolve the destination path and reject zip-slip escapes.
+        const target = resolve(absDest, name);
+        const rel = relative(absDest, target);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            throw new Error(`unsafe ZIP entry path (zip-slip): ${name}`);
+        }
+
+        // Directory entry.
+        if (name.endsWith("/")) {
+            mkdirSync(target, { recursive: true });
+            continue;
+        }
+
+        // Parse the local header to locate the entry's data.
+        if (buf.readUInt32LE(localHeaderOffset) !== LOCAL_HEADER_SIGNATURE) {
+            throw new Error(`corrupt ZIP: bad local header for "${name}"`);
+        }
+        const localNameLen = buf.readUInt16LE(localHeaderOffset + 26);
+        const localExtraLen = buf.readUInt16LE(localHeaderOffset + 28);
+        const dataStart = localHeaderOffset + 30 + localNameLen + localExtraLen;
+        const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+
+        let data: Buffer;
+        if (method === 0) {
+            data = compressed;
+        } else if (method === 8) {
+            data = inflateRawSync(compressed);
+        } else {
+            throw new Error(`unsupported ZIP compression method ${method} for "${name}"`);
+        }
+
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, data);
+    }
+}