@klhapp/skillmux 1.9.1 → 1.9.2

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.2](https://github.com/klhq/skillmux/compare/v1.9.1...v1.9.2) (2026-08-30)
+
+
+### Fixed
+
+* **install:** refuse a file:// source without --allow-local-source (SMX-92) ([#156](https://github.com/klhq/skillmux/issues/156)) ([b4ffb4a](https://github.com/klhq/skillmux/commit/b4ffb4abec90f900113bcd5806274b5d5692d23c))
+* **server:** bound rate-limiter bucket map with LRU eviction (SMX-93) ([#155](https://github.com/klhq/skillmux/issues/155)) ([4dd1eb5](https://github.com/klhq/skillmux/commit/4dd1eb5a6d673f11f4ccd556fb4f189cf5fa828f))
+* **server:** compare fixed-length hashes in safeTokenEquals (SMX-94) ([#157](https://github.com/klhq/skillmux/issues/157)) ([ae225c0](https://github.com/klhq/skillmux/commit/ae225c0db88952fedd4e66d4f373455774635900))
+* **server:** refuse to bind a non-loopback host with auth disabled (SMX-91) ([#153](https://github.com/klhq/skillmux/issues/153)) ([2520408](https://github.com/klhq/skillmux/commit/252040867ed73ef1b82c6f97010842a9b399b498))
+
 ## [1.9.1](https://github.com/klhq/skillmux/compare/v1.9.0...v1.9.1) (2026-08-30)
 
 

package/docs/deployment.md

@@ -232,6 +232,16 @@ Keep `trust_proxy = false` unless a trusted reverse proxy overwrites
 `X-Forwarded-For`. A client can spoof that header when it reaches Skillmux
 directly.
 
+`skillmux serve --transport http` enforces this itself: it refuses to bind a
+non-loopback hostname (including Docker's default `0.0.0.0`) while
+`auth_enabled` is `false`, since that combination leaves `/mcp` and `/stats`
+open to anyone who can reach the port. `skillmux doctor` flags the same
+combination as `server_bind_posture`. If you're relying on network-level
+isolation instead of application auth — e.g. a container with no published
+port, reachable only inside a private Docker network — set
+`SKILLMUX_ALLOW_INSECURE_BIND=true` to start anyway; the server logs a loud
+warning each time it does.
+
 ## Health and metrics
 
 The HTTP server provides:

package/docs/skill-management.md

@@ -42,6 +42,17 @@ skillmux install owner/repo --fail-on high
 The scanner detects suspicious prompt-injection patterns, secrets, and risky
 instructions. Findings remain advisory unless you pass `--fail-on`.
 
+`install` refuses a `file://` source by default — a `file://` URL reaches the
+local filesystem directly, so honoring one unconditionally would let anything
+that can hand `skillmux install` a string (a webpage, another tool's output,
+an instruction an agent was told to follow) pull an arbitrary local
+repository into the shared vault. Pass `--allow-local-source` when installing
+from a local repo is a deliberate, interactive choice:
+
+```sh
+skillmux install file:///path/to/local/repo --allow-local-source
+```
+
 ## Scan a vault or candidate
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -42,6 +42,7 @@ import {
   cloneToTemp,
   deriveRepoName,
   installIntoVault,
+  isLocalFileUrl,
   resolveCloneCommit,
   resolveRepoSource,
   resolveSkillDir,
@@ -1619,15 +1620,18 @@ function parseInstallArgs(args: string[]): {
   force: boolean;
   dryRun: boolean;
   failOn?: ScanSeverity;
+  allowLocalSource: boolean;
 } {
   let repo: string | undefined;
   let force = false;
   let dryRun = false;
   let failOn: ScanSeverity | undefined;
+  let allowLocalSource = false;
   for (let i = 0; i < args.length; i++) {
     const option = args[i];
     if (option === "--force") force = true;
     else if (option === "--dry-run") dryRun = true;
+    else if (option === "--allow-local-source") allowLocalSource = true;
     else if (option === "--fail-on") {
       const value = args[++i];
       if (value !== "low" && value !== "medium" && value !== "high") {
@@ -1644,21 +1648,26 @@ function parseInstallArgs(args: string[]): {
       repo = option;
     }
   }
-  return { repo, force, dryRun, failOn };
+  return { repo, force, dryRun, failOn, allowLocalSource };
 }
 
 async function runInstall(
   args: string[],
   options: { isJson: boolean },
 ): Promise<void> {
-  const { repo, force, dryRun, failOn } = parseInstallArgs(args);
+  const { repo, force, dryRun, failOn, allowLocalSource } = parseInstallArgs(args);
   if (!repo) {
     throw new Error(
-      "usage: skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--json]",
+      "usage: skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--allow-local-source] [--json]",
     );
   }
 
   const source = resolveRepoSource(repo);
+  if (!allowLocalSource && isLocalFileUrl(source.url)) {
+    throw new Error(
+      `"${repo}" is a local (file://) source — pass --allow-local-source to install from it`,
+    );
+  }
   const cloneDir = await cloneToTemp(source.url);
   try {
     const resolved = resolveSkillDir(

package/src/config.ts

@@ -170,6 +170,18 @@ export function expandHome(path: string): string {
   return path.startsWith("~") ? join(homedir(), path.slice(1)) : path;
 }
 
+/**
+ * True only for hostnames the HTTP server can bind while staying unreachable
+ * from outside this machine. Deliberately narrower than adapters.ts's
+ * isLoopbackHost, which treats "0.0.0.0" as loopback for a different question
+ * (whether an admin *client* is talking to the local machine) — here "0.0.0.0"
+ * (and any other wildcard/public address) must read as non-loopback, since
+ * binding it is exactly what makes the server reachable from outside (SMX-91).
+ */
+export function isLoopbackBindHost(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "::1" || hostname === "127.0.0.1" || hostname.startsWith("127.");
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/doctor.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { createClients, RemoteInferenceError } from "./clients";
-import { embeddingDimension, expandHome } from "./config";
+import { embeddingDimension, expandHome, isLoopbackBindHost } from "./config";
 import { describeDeployment, type DeploymentIdentity } from "./deployment";
 import { parseManifest, resolveManifestPath, validateManifest } from "./manifest";
 import { readSkillmuxMarker } from "./sync";
@@ -51,6 +51,30 @@ export async function diagnose(
   }
   checks.push({ name: "vault", ok: existsSync(expandHome(config.vault_path)), detail: expandHome(config.vault_path) });
 
+  // SMX-91: `serve --transport http` itself refuses to start over this combination
+  // (assertSafeBindPosture in server.ts) unless SKILLMUX_ALLOW_INSECURE_BIND is set —
+  // surface it here too so it's visible without having to start the HTTP server first.
+  // An operator who has already set that env var has made an informed choice, so
+  // doctor treats it the same way the server does (ok, not a standing failure) —
+  // it doesn't re-litigate a decision the server itself already accepted.
+  if (config.server) {
+    const hostname = config.server.hostname ?? "127.0.0.1";
+    const insecureBindAcknowledged = environment.SKILLMUX_ALLOW_INSECURE_BIND === "true";
+    const bindIsSafe = isLoopbackBindHost(hostname) || config.server.auth_enabled || insecureBindAcknowledged;
+    checks.push({
+      name: "server_bind_posture",
+      ok: bindIsSafe,
+      detail: !bindIsSafe
+        ? `${hostname} is reachable beyond this machine with auth_enabled=false — ` +
+          "MCP tools and /stats would be open to anyone who can reach this port; " +
+          "set server.auth_enabled=true, bind a loopback hostname, or set SKILLMUX_ALLOW_INSECURE_BIND=true"
+        : insecureBindAcknowledged && !isLoopbackBindHost(hostname) && !config.server.auth_enabled
+          ? `${hostname}, auth_enabled=false, acknowledged via SKILLMUX_ALLOW_INSECURE_BIND`
+          : `${hostname}, auth_enabled=${config.server.auth_enabled}`,
+      failure_kind: bindIsSafe ? undefined : "configuration",
+    });
+  }
+
   for (const localPath of config.local_vault_paths) {
     const expanded = expandHome(localPath);
     checks.push({ name: `local_vault:${localPath}`, ok: existsSync(expanded), detail: expanded });

package/src/rate-limiter.ts

@@ -3,6 +3,14 @@ interface Bucket {
   lastRefillMs: number;
 }
 
+// SMX-93: bounds memory even when an attacker (behind a trust_proxy-honored
+// reverse proxy) mints unbounded distinct X-Forwarded-For values, or a
+// long-running deployment simply accumulates many distinct legitimate
+// clients over time. Past this many entries, the least-recently-used
+// bucket is evicted to make room — active clients are never evicted ahead
+// of idle ones.
+const DEFAULT_MAX_BUCKETS = 10_000;
+
 export interface RateLimitCheckInput {
   nowMs: number;
   auth_enabled: boolean;
@@ -22,12 +30,19 @@ export class RateLimiter {
   private enabled: boolean;
   private requests_per_minute: number;
   private trust_proxy: boolean;
+  private max_buckets: number;
   private buckets = new Map<string, Bucket>();
 
-  constructor(config: { enabled: boolean; requests_per_minute: number; trust_proxy?: boolean }) {
+  constructor(config: {
+    enabled: boolean;
+    requests_per_minute: number;
+    trust_proxy?: boolean;
+    max_buckets?: number;
+  }) {
     this.enabled = config.enabled;
     this.requests_per_minute = config.requests_per_minute;
     this.trust_proxy = config.trust_proxy ?? false;
+    this.max_buckets = config.max_buckets ?? DEFAULT_MAX_BUCKETS;
   }
 
   check(input: RateLimitCheckInput): RateLimitCheckResult {
@@ -59,7 +74,19 @@ export class RateLimiter {
 
     // 2. Retrieve or initialize bucket
     let bucket = this.buckets.get(id);
-    if (!bucket) {
+    if (bucket) {
+      // Map iteration order is insertion order, so re-inserting on touch
+      // marks this entry as most-recently-used and moves it out of the
+      // eviction path below.
+      this.buckets.delete(id);
+      this.buckets.set(id, bucket);
+    } else {
+      if (this.buckets.size >= this.max_buckets) {
+        const oldestId = this.buckets.keys().next().value;
+        if (oldestId !== undefined) {
+          this.buckets.delete(oldestId);
+        }
+      }
       bucket = {
         tokens: this.requests_per_minute,
         lastRefillMs: input.nowMs,

package/src/server.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
-import { timingSafeEqual } from "node:crypto";
+import { createHash, timingSafeEqual } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { createClients } from "./clients";
-import { loadConfig, resolveConfigPath } from "./config";
+import { isLoopbackBindHost, loadConfig, resolveConfigPath } from "./config";
 import { describeDeployment } from "./deployment";
 import { ConfigWatcher, type ReloadStatus } from "./config-watcher";
 import { RuntimeSnapshotManager } from "./snapshot";
@@ -40,6 +40,35 @@ export interface ServerHandle {
   stop(): Promise<void>;
 }
 
+/**
+ * Docker's documented deployment mode auto-switches hostname to "0.0.0.0"
+ * (config.ts's RUNNING_IN_DOCKER override) while server.auth_enabled still
+ * defaults to false and allowed_origins defaults to [] — which only blocks
+ * requests that carry an Origin header, so a plain server-to-server/curl
+ * request sails through unauthenticated. That default combination leaves MCP
+ * tools (resolve_skill/fetch_skill) and /stats (raw historical query text)
+ * open to anyone who can reach the port — the documented common case, not an
+ * edge case (SMX-91). Refuse to start rather than silently exposing it;
+ * SKILLMUX_ALLOW_INSECURE_BIND is the explicit, logged escape hatch for
+ * operators who rely on network-level isolation instead of application auth.
+ */
+export function assertSafeBindPosture(
+  hostname: string,
+  authEnabled: boolean,
+  env: Record<string, string | undefined> = process.env,
+): void {
+  if (isLoopbackBindHost(hostname) || authEnabled) return;
+  const message =
+    `refusing to bind "${hostname}" (reachable beyond this machine) with server.auth_enabled=false — ` +
+    "MCP tools (resolve_skill/fetch_skill) and /stats would be open to anyone who can reach this port. " +
+    "Set server.auth_enabled=true (with SKILLMUX_AUTH_TOKEN) or bind a loopback hostname instead. " +
+    "To start anyway — e.g. when network isolation is the intended boundary — set SKILLMUX_ALLOW_INSECURE_BIND=true.";
+  if (env.SKILLMUX_ALLOW_INSECURE_BIND !== "true") {
+    throw new Error(`skillmux: ${message}`);
+  }
+  console.error(`skillmux: WARNING — ${message}`);
+}
+
 let warnedAuthToken = false;
 function resolveAuthToken(envName: string): string {
   const value = process.env[envName];
@@ -59,11 +88,14 @@ function resolveAuthToken(envName: string): string {
   return "";
 }
 
-function safeTokenEquals(a: string, b: string): boolean {
-  const bufA = Buffer.from(a);
-  const bufB = Buffer.from(b);
-  if (bufA.length !== bufB.length) return false;
-  return timingSafeEqual(bufA, bufB);
+// SMX-94: comparing raw buffers made length itself observable — a
+// mismatched-length pair returns before ever reaching timingSafeEqual.
+// Hashing both sides to a fixed 32-byte digest first means every
+// comparison takes the same constant-time path regardless of input length.
+export function safeTokenEquals(a: string, b: string): boolean {
+  const hashA = createHash("sha256").update(a).digest();
+  const hashB = createHash("sha256").update(b).digest();
+  return timingSafeEqual(hashA, hashB);
 }
 
 export function createMcpServer(): McpServer {
@@ -206,6 +238,7 @@ export async function startServer(opts?: {
 
     const port = opts?.port ?? Number(process.env.PORT || 3000);
     const hostname = config.server?.hostname ?? "127.0.0.1";
+    assertSafeBindPosture(hostname, config.server?.auth_enabled ?? false);
     const bunServer = Bun.serve({
       port,
       hostname,