mercury-agent 0.4.28 → 0.5.0

package/src/core/api.ts

@@ -1,105 +1,125 @@
-import { timingSafeEqual } from "node:crypto";
-import { Hono } from "hono";
-import type { ApiContext, AuthContext, Env } from "./api-types.js";
-import { resolveRole } from "./permissions.js";
-import {
-  config,
-  connections,
-  control,
-  conversations,
-  extensions,
-  media,
-  messages,
-  mutes,
-  permissions,
-  prefs,
-  roles,
-  spaces,
-  tasks,
-  tradestation,
-  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> {
-  const app = new 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);
-      }
-    }
-
-    // Parse auth headers
-    const callerId = c.req.header("x-mercury-caller");
-    const spaceId = c.req.header("x-mercury-space");
-
-    if (!callerId || !spaceId) {
-      return c.json(
-        { error: "Missing X-Mercury-Caller or X-Mercury-Space headers" },
-        400,
-      );
-    }
-
-    // Resolve role
-    const seededAdmins = apiCtx.config.admins
-      ? apiCtx.config.admins
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean)
-      : [];
-
-    apiCtx.db.ensureSpace(spaceId);
-    const role = resolveRole(apiCtx.db, spaceId, callerId, seededAdmins);
-
-    // Store in request context
-    c.set("auth", { callerId, spaceId, role } as AuthContext);
-    c.set("apiCtx", apiCtx);
-    await next();
-  });
-
-  // ─── Mount Routes ───────────────────────────────────────────────────────
-
-  app.route("/", control);
-  app.route("/tasks", tasks);
-  app.route("/config", config);
-  app.route("/prefs", prefs);
-  app.route("/roles", roles);
-  app.route("/permissions", permissions);
-  app.route("/spaces", spaces);
-  app.route("/conversations", conversations);
-  app.route("/media", media);
-  app.route("/messages", messages);
-  app.route("/mutes", mutes);
-  app.route("/ext", extensions);
-  app.route("/connections", connections);
-  app.route("/tradestation", tradestation);
-  app.route("/tts", tts);
-
-  // ─── Fallback ───────────────────────────────────────────────────────────
-
-  app.all("*", (c) => {
-    return c.json({ error: "Not found" }, 404);
-  });
-
-  return app;
-}
-
-// Re-export types for convenience
-export type { ApiContext, AuthContext, Env } from "./api-types.js";
+import { timingSafeEqual } from "node:crypto";
+import { Hono } from "hono";
+import type { ApiContext, AuthContext, Env } from "./api-types.js";
+import { verifyCallerToken } from "./caller-token.js";
+import { resolveRole } from "./permissions.js";
+import {
+  capability,
+  config,
+  connections,
+  control,
+  conversations,
+  extensions,
+  media,
+  messages,
+  mutes,
+  permissions,
+  prefs,
+  roles,
+  spaces,
+  tasks,
+  tradestation,
+  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> {
+  const app = new 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);
+      }
+    }
+
+    // Resolve caller identity. A per-turn caller token (minted host-side at
+    // container spawn) is authoritative and unspoofable — prefer it over the
+    // x-mercury-caller / x-mercury-space headers, which any code holding the
+    // shared API_SECRET could forge. Headers remain the fallback for callers
+    // that predate tokens (backward compatibility).
+    let callerId = c.req.header("x-mercury-caller");
+    let spaceId = c.req.header("x-mercury-space");
+
+    const callerToken = c.req.header("x-mercury-token");
+    if (callerToken) {
+      const verified = verifyCallerToken(
+        callerToken,
+        apiCtx.config.callerTokenKey,
+      );
+      if (!verified) {
+        return c.json({ error: "Invalid or expired caller token" }, 401);
+      }
+      callerId = verified.callerId;
+      spaceId = verified.spaceId;
+    }
+
+    if (!callerId || !spaceId) {
+      return c.json(
+        { error: "Missing X-Mercury-Caller or X-Mercury-Space headers" },
+        400,
+      );
+    }
+
+    // Resolve role
+    const seededAdmins = apiCtx.config.admins
+      ? apiCtx.config.admins
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+
+    apiCtx.db.ensureSpace(spaceId);
+    const role = resolveRole(apiCtx.db, spaceId, callerId, seededAdmins);
+
+    // Store in request context
+    c.set("auth", { callerId, spaceId, role } as AuthContext);
+    c.set("apiCtx", apiCtx);
+    await next();
+  });
+
+  // ─── Mount Routes ───────────────────────────────────────────────────────
+
+  app.route("/", control);
+  app.route("/tasks", tasks);
+  app.route("/config", config);
+  app.route("/prefs", prefs);
+  app.route("/roles", roles);
+  app.route("/permissions", permissions);
+  app.route("/spaces", spaces);
+  app.route("/conversations", conversations);
+  app.route("/media", media);
+  app.route("/messages", messages);
+  app.route("/mutes", mutes);
+  app.route("/ext", extensions);
+  app.route("/connections", connections);
+  app.route("/tradestation", tradestation);
+  app.route("/tts", tts);
+  app.route("/capability", capability);
+
+  // ─── Fallback ───────────────────────────────────────────────────────────
+
+  app.all("*", (c) => {
+    return c.json({ error: "Not found" }, 404);
+  });
+
+  return app;
+}
+
+// Re-export types for convenience
+export type { ApiContext, AuthContext, Env } from "./api-types.js";

package/src/core/caller-token.ts

@@ -0,0 +1,101 @@
+/**
+ * Caller-bound capability token.
+ *
+ * Mercury's in-container CLIs authenticate to the host control-plane API with a
+ * single shared `API_SECRET` and, historically, assert their identity via the
+ * spoofable `x-mercury-caller` / `x-mercury-space` headers. Because `API_SECRET`
+ * is readable inside the container, any code there could claim to be any caller.
+ *
+ * This module mints a short-lived, HMAC-signed token at container spawn, bound
+ * to `{callerId, spaceId}`. The host verifies it and uses the token payload as
+ * the authoritative identity for authorization — so a container cannot forge a
+ * different caller.
+ *
+ * The signing key NEVER enters a container. When no key is configured
+ * (`callerTokenKey`), an ephemeral random key is generated once per host process
+ * — sufficient because tokens are per-turn and short-lived. A configured key is
+ * only needed when minting and verification happen in separate processes.
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+export interface CallerTokenClaims {
+  callerId: string;
+  spaceId: string;
+  /** Expiry, unix seconds. */
+  exp: number;
+}
+
+/** Ephemeral host-only key, generated lazily when no key is configured. */
+let ephemeralKey: Buffer | null = null;
+
+function resolveKey(configuredKey?: string): Buffer {
+  if (configuredKey && configuredKey.length > 0) {
+    return Buffer.from(configuredKey, "utf8");
+  }
+  if (!ephemeralKey) {
+    ephemeralKey = randomBytes(32);
+  }
+  return ephemeralKey;
+}
+
+/** Mint a signed caller token. `configuredKey` falls back to a host ephemeral key. */
+export function mintCallerToken(
+  claims: CallerTokenClaims,
+  configuredKey?: string,
+): string {
+  const key = resolveKey(configuredKey);
+  const payload = Buffer.from(
+    JSON.stringify({ c: claims.callerId, s: claims.spaceId, exp: claims.exp }),
+    "utf8",
+  ).toString("base64url");
+  const sig = createHmac("sha256", key).update(payload).digest("base64url");
+  return `${payload}.${sig}`;
+}
+
+/**
+ * Verify a caller token. Returns the bound identity on success, or null if the
+ * signature is invalid, the payload is malformed, or the token has expired.
+ */
+export function verifyCallerToken(
+  token: string,
+  configuredKey?: string,
+  nowSeconds?: number,
+): { callerId: string; spaceId: string } | null {
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) return null;
+
+  const payload = token.slice(0, dot);
+  const sig = token.slice(dot + 1);
+
+  const key = resolveKey(configuredKey);
+  const expected = createHmac("sha256", key)
+    .update(payload)
+    .digest("base64url");
+
+  const sigBuf = Buffer.from(sig);
+  const expBuf = Buffer.from(expected);
+  if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
+    return null;
+  }
+
+  let decoded: { c?: unknown; s?: unknown; exp?: unknown };
+  try {
+    decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+  } catch {
+    return null;
+  }
+
+  if (
+    typeof decoded.c !== "string" ||
+    typeof decoded.s !== "string" ||
+    typeof decoded.exp !== "number"
+  ) {
+    return null;
+  }
+
+  const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+  if (decoded.exp < now) return null;
+
+  return { callerId: decoded.c, spaceId: decoded.s };
+}