@mastra/hono 1.7.21-alpha.2 → 1.7.21-alpha.4

package/dist/index.js

@@ -89,7 +89,162 @@ function createAuthMiddleware({ mastra, requiresAuth = true }) {
 	};
 }
 //#endregion
+//#region src/browser-stream/upgrade-tickets.ts
+const TICKET_BYTES = 32;
+/**
+* How long an issued ticket stays valid. A ticket is minted immediately before
+* the socket is opened, so this only has to cover the round trip plus the
+* handshake — short enough that a ticket leaked from a log is useless by the
+* time anyone can act on it.
+*/
+const UPGRADE_TICKET_TTL_MS = 3e4;
+/**
+* Ceiling on tracked per-agent issuance counters, so the limiter can't grow
+* without bound as agent ids are invented. Counters are evicted oldest first.
+*/
+const MAX_TRACKED_AGENTS = 500;
+/** 256 bits of base64url, so the ticket can't be guessed or enumerated. */
+function createTicketValue() {
+	const bytes = new Uint8Array(TICKET_BYTES);
+	globalThis.crypto.getRandomValues(bytes);
+	return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+* Short-lived, single-use credentials for browser WebSocket upgrades.
+*
+* A browser cannot set an `Authorization` header on a WebSocket handshake, so a
+* deployment that authenticates with a header token would otherwise have to put
+* that reusable token in the handshake URL, where proxies and access logs can
+* retain it. Instead the client asks an authenticated HTTP route for a ticket,
+* and the ticket — worthless once spent, and scoped to one agent and thread —
+* travels in the URL instead.
+*
+* In-process, like the `ViewerRegistry` and the browser sessions it serves: a
+* screencast is bound to the process holding the browser, so a ticket store
+* shared across replicas would buy nothing. A ticket presented to a different
+* replica fails for the same reason the stream itself would.
+*
+* Issuance is bounded so the mint endpoint can't be turned into memory or CPU
+* exhaustion: tickets that are never spent live at most one TTL, a full store
+* rejects instead of growing, and each agent has a request allowance. Expiry is
+* swept from the front of the insertion-ordered map, so cleanup costs the
+* number of entries actually expired rather than a scan of every outstanding
+* ticket per request.
+*/
+var UpgradeTicketStore = class {
+	#tickets = /* @__PURE__ */ new Map();
+	#issuance = /* @__PURE__ */ new Map();
+	#now;
+	constructor(now = () => Date.now()) {
+		this.#now = now;
+	}
+	/**
+	* Issue a ticket bound to one agent and thread. Returns `{ ok: false }` when
+	* the agent exceeded its allowance or the store is at capacity.
+	*/
+	issue(agentId, threadId, ttlMs = UPGRADE_TICKET_TTL_MS) {
+		const now = this.#now();
+		this.#prune(now);
+		if (this.#tickets.size >= 500) return {
+			ok: false,
+			reason: "capacity"
+		};
+		const window = this.#issuance.get(agentId);
+		if (!window || now - window.windowStart >= 6e4) this.#trackIssuance(agentId, {
+			windowStart: now,
+			count: 0
+		});
+		else if (window.count >= 30) return {
+			ok: false,
+			reason: "rate-limited"
+		};
+		this.#issuance.get(agentId).count += 1;
+		const ticket = createTicketValue();
+		this.#tickets.set(ticket, {
+			agentId,
+			threadId,
+			expiresAt: now + ttlMs
+		});
+		return {
+			ok: true,
+			ticket,
+			expiresIn: Math.ceil(ttlMs / 1e3)
+		};
+	}
+	/**
+	* Spend a ticket. Returns `true` only when the ticket is unexpired and was
+	* issued for this exact agent and thread, in which case it is consumed and a
+	* second presentation fails.
+	*/
+	consume(ticket, agentId, threadId) {
+		const entry = this.#tickets.get(ticket);
+		if (!entry) return false;
+		if (entry.expiresAt <= this.#now()) return false;
+		if (entry.agentId !== agentId) return false;
+		if ((entry.threadId ?? void 0) !== (threadId ?? void 0)) return false;
+		this.#tickets.delete(ticket);
+		return true;
+	}
+	/**
+	* Drop expired tickets from the front of the insertion-ordered map. Tickets
+	* are inserted in issue order and share a TTL, so the entries after the first
+	* live one are live too and the sweep can stop there.
+	*/
+	#prune(now) {
+		for (const [ticket, entry] of this.#tickets) {
+			if (entry.expiresAt > now) break;
+			this.#tickets.delete(ticket);
+		}
+	}
+	/** Record an issuance window, evicting the oldest counter when at the cap. */
+	#trackIssuance(agentId, window) {
+		this.#issuance.delete(agentId);
+		this.#issuance.set(agentId, window);
+		if (this.#issuance.size > MAX_TRACKED_AGENTS) {
+			const oldest = this.#issuance.keys().next().value;
+			if (oldest !== void 0) this.#issuance.delete(oldest);
+		}
+	}
+};
+//#endregion
 //#region src/browser-stream/index.ts
+const TICKET_BODY_MAX_BYTES = 4 * 1024;
+/**
+* Resolve an `allowedOrigins` value against the request's `Origin` header.
+*
+* Mirrors Hono's `cors.origin` semantics so the same config value means the same
+* thing on the upgrade as it does on the HTTP routes: `'*'` allows everything,
+* array entries match literally, and a callback is only an approval when it
+* returns the request's own origin (the value Hono would echo back) or `'*'`.
+*/
+async function isOriginAllowed(allowedOrigins, origin, c) {
+	if (Array.isArray(allowedOrigins)) return allowedOrigins.includes(origin);
+	if (typeof allowedOrigins === "function") {
+		const allowed = await allowedOrigins(origin, c);
+		return allowed === origin || allowed === "*";
+	}
+	return allowedOrigins === "*" || allowedOrigins === origin;
+}
+/**
+* Is the `Origin` header the server's own origin?
+*
+* A Studio served by this server connects back to the same host, and operators
+* don't add their own origin to a CORS allowlist because same-origin requests
+* never needed CORS. Comparing hosts (rather than scheme + host) keeps that
+* working behind TLS-terminating proxies, where the server sees `http` while the
+* browser sends `https`.
+*/
+function isSameOrigin(origin, requestHost) {
+	if (!requestHost) return false;
+	let originHost;
+	try {
+		originHost = new URL(origin).host;
+	} catch {
+		return false;
+	}
+	const host = (requestHost.split(",")[0] ?? "").trim();
+	return originHost !== "" && originHost.toLowerCase() === host.toLowerCase();
+}
 /**
 * Set up WebSocket-based browser stream endpoint for real-time screencast viewing.
 *
@@ -99,6 +254,17 @@ function createAuthMiddleware({ mastra, requiresAuth = true }) {
 * - Broadcasts frames to all connected viewers
 * - Stops screencast when last viewer disconnects
 *
+* All routes are authenticated with the server's auth configuration. Browsers
+* cannot attach an `Authorization` header to a WebSocket upgrade, so
+* session-cookie providers authenticate from the upgrade request's cookies.
+* Clients that authenticate with a header token instead request a short-lived,
+* single-use ticket from `POST ${apiPrefix}/agents/:agentId/browser/stream-ticket`
+* and pass it to the upgrade as `?ticket=`, which keeps the reusable credential
+* out of the URL. Non-browser clients can pass the token as the `apiKey` query
+* parameter — use a short-lived token, since a URL can be retained in proxy and
+* access logs, and prefer the `Authorization` header on the HTTP routes where the
+* client can set one.
+*
 * **Note**: Requires `ws` package to be installed. If not available, returns null
 * and logs a warning. Browser streaming will be disabled but everything else works.
 *
@@ -114,6 +280,7 @@ function createAuthMiddleware({ mastra, requiresAuth = true }) {
 *
 * const app = new Hono();
 * const browserStream = await setupBrowserStream(app, {
+*   mastra,
 *   getToolset: (agentId) => browserToolsets.get(agentId),
 * });
 *
@@ -136,7 +303,24 @@ async function setupBrowserStream(app, config) {
 	const registry = new ViewerRegistry();
 	const rawPrefix = config.apiPrefix ?? "/api";
 	const apiPrefix = (rawPrefix.endsWith("/") ? rawPrefix.slice(0, -1) : rawPrefix) || "/api";
-	app.get("/browser/:agentId/stream", upgradeWebSocket((c) => {
+	const authenticate = createAuthMiddleware({ mastra: config.mastra });
+	const upgradeTickets = new UpgradeTicketStore();
+	const authorizeUpgrade = async (c, next) => {
+		const ticket = c.req.query("ticket");
+		if (!ticket) return authenticate(c, next);
+		const agentId = c.req.param("agentId");
+		if (!upgradeTickets.consume(ticket, agentId, c.req.query("threadId"))) return c.json({ error: "Invalid or expired upgrade ticket" }, 401);
+		return next();
+	};
+	const allowedOrigins = config.allowedOrigins;
+	const checkOrigin = async (c, next) => {
+		const origin = c.req.header("origin");
+		if (!allowedOrigins || !origin) return next();
+		if (isSameOrigin(origin, c.req.header("x-forwarded-host") ?? c.req.header("host"))) return next();
+		if (!await isOriginAllowed(allowedOrigins, origin, c)) return c.text("Forbidden", 403);
+		return next();
+	};
+	app.get("/browser/:agentId/stream", checkOrigin, authorizeUpgrade, upgradeWebSocket((c) => {
 		const agentId = c.req.param("agentId");
 		const threadId = c.req.query("threadId");
 		const viewerKey = threadId ? `${agentId}:${threadId}` : agentId;
@@ -158,7 +342,29 @@ async function setupBrowserStream(app, config) {
 			}
 		};
 	}));
-	app.get(`${apiPrefix}/agents/:agentId/browser/session`, async (c) => {
+	const ticketBodyLimit = bodyLimit({
+		maxSize: TICKET_BODY_MAX_BYTES,
+		onError: (c) => c.json({ error: "Request body too large" }, 413)
+	});
+	app.post(`${apiPrefix}/agents/:agentId/browser/stream-ticket`, authenticate, ticketBodyLimit, async (c) => {
+		const agentId = c.req.param("agentId");
+		if (!agentId) return c.json({ error: "Agent ID is required" }, 400);
+		let threadId = c.req.query("threadId");
+		try {
+			const body = await c.req.json();
+			if (!threadId && typeof body?.threadId === "string") threadId = body.threadId;
+		} catch {}
+		const issued = upgradeTickets.issue(agentId, threadId);
+		if (!issued.ok) {
+			const error = issued.reason === "capacity" ? "Too many outstanding browser stream upgrade tickets" : "Too many browser stream upgrade tickets requested";
+			return c.json({ error }, 429);
+		}
+		return c.json({
+			ticket: issued.ticket,
+			expiresIn: issued.expiresIn
+		});
+	});
+	app.get(`${apiPrefix}/agents/:agentId/browser/session`, authenticate, async (c) => {
 		const agentId = c.req.param("agentId");
 		if (!agentId) return c.json({ error: "Agent ID is required" }, 400);
 		const threadId = c.req.query("threadId");
@@ -173,7 +379,7 @@ async function setupBrowserStream(app, config) {
 			screencastAvailable: true
 		});
 	});
-	app.post(`${apiPrefix}/agents/:agentId/browser/close`, async (c) => {
+	app.post(`${apiPrefix}/agents/:agentId/browser/close`, authenticate, ticketBodyLimit, async (c) => {
 		const agentId = c.req.param("agentId");
 		if (!agentId) return c.json({ error: "Agent ID is required" }, 400);
 		const toolset = await config.getToolset(agentId);