mercury-agent 0.11.0 → 0.12.0

package/README.md

@@ -361,8 +361,8 @@ Optional project file **`mercury.yaml`** (or **`mercury.yml`**) supplies non-sec
 
 | Variable | Description |
 |----------|-------------|
-| `MERCURY_API_SECRET` | Shared secret for `/api/*` routes. When set, requires `Authorization: Bearer <secret>`. Auto-generated by `mercury setup`. |
-| `MERCURY_CHAT_API_KEY` | Optional API key for `/chat` endpoint. When set, requires Bearer token. When unset, `/chat` is open (for local use). |
+| `MERCURY_API_SECRET` | Shared secret for `/api/*`, `/dashboard/*` and `/chat`. Requires `Authorization: Bearer <secret>`; when unset those routes refuse to serve (503). Auto-generated by `mercury setup`. |
+| `MERCURY_CHAT_API_KEY` | Optional dedicated key for the `/chat` endpoint. Falls back to `MERCURY_API_SECRET` when unset; with neither configured, `/chat` returns 503. |
 
 **Auth:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/src/cli/mercury.ts

@@ -2058,6 +2058,18 @@ program
       }
 
       const url = `http://localhost:${options.port}/chat`;
+
+      // /chat fails closed: it requires MERCURY_CHAT_API_KEY (or falls back
+      // to MERCURY_API_SECRET). Resolve the key the way the running service
+      // does: `.env` values win over process env.
+      const chatEnvPath = join(CWD, ".env");
+      const chatEnvVars = existsSync(chatEnvPath)
+        ? loadEnvFile(chatEnvPath)
+        : {};
+      const chatEnv = { ...process.env, ...chatEnvVars };
+      const chatKey =
+        chatEnv.MERCURY_CHAT_API_KEY || chatEnv.MERCURY_API_SECRET;
+
       const body: Record<string, unknown> = {
         text,
         callerId: options.caller,
@@ -2087,7 +2099,10 @@ program
       try {
         const res = await fetch(url, {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
+          headers: {
+            "Content-Type": "application/json",
+            ...(chatKey ? { authorization: `Bearer ${chatKey}` } : {}),
+          },
           body: JSON.stringify(body),
         });
 

package/src/config.ts

@@ -248,7 +248,11 @@ const schema = z.object({
   profile: z.string().optional(),
 
   // ─── Security ─────────────────────────────────────────────────────
-  /** Shared secret for API authentication. Required for /api/* routes. */
+  /**
+   * Shared secret for API authentication. Required for /api/* routes —
+   * when unset, /api/* (and /chat, absent a chatApiKey) refuse to serve
+   * with 503 rather than running unauthenticated.
+   */
   apiSecret: z.string().optional(),
   /**
    * Host-only HMAC key for signing per-turn caller tokens. Never injected into
@@ -257,7 +261,10 @@ const schema = z.object({
    * minting and verification run in separate processes.
    */
   callerTokenKey: z.string().optional(),
-  /** Optional API key for the /chat endpoint. When unset, /chat is open (for local use). */
+  /**
+   * API key for the /chat endpoint. Falls back to apiSecret when unset;
+   * with neither configured, /chat refuses to serve (503).
+   */
   chatApiKey: z.string().optional(),
   /**
    * URL of the Mercury Cloud Console managing this agent (e.g. "https://console.mercury.app").

package/src/core/api.ts

@@ -1,6 +1,7 @@
-import { timingSafeEqual } from "node:crypto";
 import { Hono } from "hono";
+import { logger } from "../logger.js";
 import type { ApiContext, AuthContext, Env } from "./api-types.js";
+import { authorizeApiSecret } from "./auth.js";
 import { verifyCallerToken } from "./caller-token.js";
 import { resolveRole } from "./permissions.js";
 import {
@@ -25,11 +26,6 @@ import {
   tts,
 } from "./routes/index.js";
 
-function safeCompare(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
-}
-
 // ─── App Factory ──────────────────────────────────────────────────────────
 
 export function createApiApp(apiCtx: ApiContext): Hono<Env> {
@@ -38,17 +34,27 @@ export function createApiApp(apiCtx: ApiContext): Hono<Env> {
   // ─── Auth Middleware ────────────────────────────────────────────────────
 
   app.use("*", async (c, next) => {
-    // Validate API secret when configured
-    const secret = apiCtx.config.apiSecret;
-    if (secret) {
-      const authHeader = c.req.header("authorization");
-      const token = authHeader?.startsWith("Bearer ")
-        ? authHeader.slice(7)
-        : undefined;
-
-      if (!token || !safeCompare(token, secret)) {
-        return c.json({ error: "Unauthorized" }, 401);
-      }
+    // Validate API secret. Fails closed: an agent host started without
+    // MERCURY_API_SECRET refuses to serve the control plane rather than
+    // serving it unauthenticated (auth guards gate on the ABSENCE of the
+    // secret, never wrap the comparison in a presence check).
+    const auth = authorizeApiSecret(
+      c.req.header("authorization"),
+      apiCtx.config.apiSecret,
+    );
+    if (!auth.ok) {
+      logger.warn("API auth denied", {
+        status: auth.status,
+        path: c.req.path,
+        callerId: c.req.header("x-mercury-caller"),
+        spaceId: c.req.header("x-mercury-space"),
+      });
+      return c.json(
+        auth.status === 503
+          ? { error: "MERCURY_API_SECRET must be set for /api" }
+          : { error: "Unauthorized" },
+        auth.status,
+      );
     }
 
     // Resolve caller identity. A per-turn caller token (minted host-side at

package/src/core/auth.ts

@@ -0,0 +1,28 @@
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * Authorize a request against a shared Bearer secret. Fails closed: returns
+ * 503 when no secret is configured (an endpoint must never silently run
+ * unauthenticated), 401 on a missing or mismatched token, `ok` when valid.
+ * Length is checked before `timingSafeEqual` (which throws on unequal buffer
+ * lengths); the comparison itself is constant-time.
+ *
+ * Single implementation for every secret-gated surface: `/api/*`, `/chat`,
+ * `/dashboard/*`, `/pre-build-ext-image`.
+ */
+export function authorizeApiSecret(
+  authHeader: string | undefined,
+  secret: string | undefined,
+): { ok: true } | { ok: false; status: 401 | 503 } {
+  if (!secret) return { ok: false, status: 503 };
+  const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
+  const tokenBuf = Buffer.from(token);
+  const secretBuf = Buffer.from(secret);
+  if (
+    tokenBuf.length !== secretBuf.length ||
+    !timingSafeEqual(tokenBuf, secretBuf)
+  ) {
+    return { ok: false, status: 401 };
+  }
+  return { ok: true };
+}

package/src/core/routes/chat.ts

@@ -1,10 +1,10 @@
-import { timingSafeEqual } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { Hono } from "hono";
 import { logger } from "../../logger.js";
 import { ensureSpaceWorkspace } from "../../storage/memory.js";
 import type { IngressMessage, MessageAttachment } from "../../types.js";
+import { authorizeApiSecret } from "../auth.js";
 import { type AutoSpaceConfig, resolveConversation } from "../conversation.js";
 import { extToMime, mimeToMediaType } from "../media.js";
 import type { MercuryCoreRuntime } from "../runtime.js";
@@ -44,23 +44,28 @@ export function createChatRoute(core: MercuryCoreRuntime): Hono {
       return c.json({ error: "Content-Type must be application/json" }, 415);
     }
 
-    // Validate chat API key when configured
-    const chatApiKey = core.config.chatApiKey;
-    let authenticated = false;
-    if (chatApiKey) {
-      const authHeader = c.req.header("authorization");
-      const token = authHeader?.startsWith("Bearer ")
-        ? authHeader.slice(7)
-        : undefined;
-
-      if (
-        !token ||
-        token.length !== chatApiKey.length ||
-        !timingSafeEqual(Buffer.from(token), Buffer.from(chatApiKey))
-      ) {
-        return c.json({ error: "Unauthorized" }, 401);
-      }
-      authenticated = true;
+    // Validate the chat API key, falling back to the API secret when no
+    // dedicated key is configured — the fallback is another secret, never
+    // no-auth. Fails closed: with neither configured, /chat refuses to serve
+    // (503) instead of invoking a paid model unauthenticated. `||`, not `??`:
+    // a present-but-blank MERCURY_CHAT_API_KEY= in .env yields "", which must
+    // fall back to the API secret, not lock /chat at 503.
+    const chatApiKey = core.config.chatApiKey || core.config.apiSecret;
+    const auth = authorizeApiSecret(c.req.header("authorization"), chatApiKey);
+    if (!auth.ok) {
+      logger.warn("Chat auth denied", {
+        status: auth.status,
+        path: c.req.path,
+      });
+      return c.json(
+        auth.status === 503
+          ? {
+              error:
+                "MERCURY_CHAT_API_KEY or MERCURY_API_SECRET must be set for /chat",
+            }
+          : { error: "Unauthorized" },
+        auth.status,
+      );
     }
 
     const body = await c.req.json().catch(() => null);
@@ -164,15 +169,14 @@ export function createChatRoute(core: MercuryCoreRuntime): Hono {
       }
     }
 
-    if (authenticated) {
-      // Fires at most once per actual override: after the re-promotion the
-      // row is admin again, so later requests return an empty list.
-      for (const id of core.db.seedAdmins(spaceId, [callerId])) {
-        logger.warn(
-          "Authenticated chat caller re-promoted: stored role overridden",
-          { spaceId, callerId: id },
-        );
-      }
+    // Every request past the guard above is authenticated.
+    // Fires at most once per actual override: after the re-promotion the
+    // row is admin again, so later requests return an empty list.
+    for (const id of core.db.seedAdmins(spaceId, [callerId])) {
+      logger.warn(
+        "Authenticated chat caller re-promoted: stored role overridden",
+        { spaceId, callerId: id },
+      );
     }
 
     const ingress: IngressMessage = {

package/src/main.ts

@@ -133,6 +133,12 @@ async function main() {
     port: config.port,
   });
 
+  if (!config.apiSecret) {
+    logger.warn(
+      "MERCURY_API_SECRET is not set — /api/*, /dashboard/* and /chat will refuse to serve (503) until it is configured",
+    );
+  }
+
   // ─── Inner-container API unix socket (gVisor only) ─────────────────────
   // In runsc mode the outer container leaves docker0, so inner containers can no
   // longer reach the API over TCP. They reach it via a per-container unix socket

package/src/server.ts

@@ -1,4 +1,3 @@
-import { timingSafeEqual } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,6 +7,7 @@ import type { WhatsAppBaileysAdapter } from "./adapters/whatsapp.js";
 import type { AppConfig } from "./config.js";
 import { resolveProjectPath } from "./config.js";
 import { createApiApp } from "./core/api.js";
+import { authorizeApiSecret } from "./core/auth.js";
 import { createChatRoute } from "./core/routes/chat.js";
 import { createConsoleApp } from "./core/routes/console.js";
 import { createDashboardRoutes } from "./core/routes/dashboard.js";
@@ -43,30 +43,9 @@ export interface ServerContext {
   packageRoot: string;
 }
 
-/**
- * Authorize an infra request against the `MERCURY_API_SECRET` Bearer token —
- * the same secret enforced by `/api/*` and `/api/console/*`. Returns 503 when no
- * secret is configured (a side-effecting endpoint must never silently run
- * unauthenticated), 401 on a missing or mismatched token, `ok` when valid.
- * Length is checked before `timingSafeEqual` (which throws on unequal buffer
- * lengths); the comparison itself is constant-time. Exported for testing.
- */
-export function authorizeApiSecret(
-  authHeader: string | undefined,
-  secret: string | undefined,
-): { ok: true } | { ok: false; status: 401 | 503 } {
-  if (!secret) return { ok: false, status: 503 };
-  const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
-  const tokenBuf = Buffer.from(token);
-  const secretBuf = Buffer.from(secret);
-  if (
-    tokenBuf.length !== secretBuf.length ||
-    !timingSafeEqual(tokenBuf, secretBuf)
-  ) {
-    return { ok: false, status: 401 };
-  }
-  return { ok: true };
-}
+// Shared fail-closed Bearer-secret guard — lives in core/auth.ts; re-exported
+// so existing importers (tests, tooling) keep working after the move.
+export { authorizeApiSecret };
 
 export function createApp(ctx: ServerContext): Hono {
   const {
@@ -167,19 +146,26 @@ export function createApp(ctx: ServerContext): Hono {
     packageRoot,
   });
 
-  // Login route — validates token, sets session cookie, redirects to dashboard
+  // Login route — validates token, sets session cookie, redirects to dashboard.
+  // Fails closed like every other secret-gated surface: no configured secret
+  // means 503, never an unauthenticated session.
   app.get("/dashboard/login", (c) => {
-    const secret = config.apiSecret;
-    if (!secret) {
-      return c.redirect("/dashboard");
-    }
     const token = c.req.query("token");
-    if (
-      !token ||
-      token.length !== secret.length ||
-      !timingSafeEqual(Buffer.from(token), Buffer.from(secret))
-    ) {
-      return c.text("Invalid or missing token", 401);
+    const auth = authorizeApiSecret(
+      token ? `Bearer ${token}` : undefined,
+      config.apiSecret,
+    );
+    if (!auth.ok) {
+      logger.warn("Dashboard auth denied", {
+        status: auth.status,
+        path: c.req.path,
+      });
+      return c.text(
+        auth.status === 503
+          ? "MERCURY_API_SECRET must be set for /dashboard"
+          : "Invalid or missing token",
+        auth.status,
+      );
     }
     c.header(
       "Set-Cookie",
@@ -192,27 +178,33 @@ export function createApp(ctx: ServerContext): Hono {
     // Login route handled above — skip auth
     if (c.req.path === "/dashboard/login") return next();
 
-    const secret = config.apiSecret;
-    if (secret) {
-      const authHeader = c.req.header("authorization");
-      const token = authHeader?.startsWith("Bearer ")
-        ? authHeader.slice(7)
-        : undefined;
-      const cookie = c.req.header("cookie");
-      const cookieToken = cookie
-        ?.split(";")
-        .map((s) => s.trim())
-        .find((s) => s.startsWith("mercury_token="))
-        ?.split("=")[1];
-
-      const provided = token || cookieToken;
-      if (
-        !provided ||
-        provided.length !== secret.length ||
-        !timingSafeEqual(Buffer.from(provided), Buffer.from(secret))
-      ) {
-        return c.json({ error: "Unauthorized" }, 401);
-      }
+    const authHeader = c.req.header("authorization");
+    const token = authHeader?.startsWith("Bearer ")
+      ? authHeader.slice(7)
+      : undefined;
+    const cookie = c.req.header("cookie");
+    const cookieToken = cookie
+      ?.split(";")
+      .map((s) => s.trim())
+      .find((s) => s.startsWith("mercury_token="))
+      ?.split("=")[1];
+
+    const provided = token || cookieToken;
+    const auth = authorizeApiSecret(
+      provided ? `Bearer ${provided}` : undefined,
+      config.apiSecret,
+    );
+    if (!auth.ok) {
+      logger.warn("Dashboard auth denied", {
+        status: auth.status,
+        path: c.req.path,
+      });
+      return c.json(
+        auth.status === 503
+          ? { error: "MERCURY_API_SECRET must be set for /dashboard" }
+          : { error: "Unauthorized" },
+        auth.status,
+      );
     }
     await next();
   });
@@ -266,6 +258,10 @@ export function createApp(ctx: ServerContext): Hono {
       config.apiSecret,
     );
     if (!auth.ok) {
+      logger.warn("Pre-build auth denied", {
+        status: auth.status,
+        path: c.req.path,
+      });
       return c.json(
         auth.status === 503
           ? { error: "MERCURY_API_SECRET must be set for /pre-build-ext-image" }