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

package/dist/browser-stream/index.d.ts

@@ -1,5 +1,45 @@
+import type { Mastra } from '@mastra/core/mastra';
 import type { BrowserStreamConfig, BrowserStreamResult } from '@mastra/server/browser-stream';
-import type { Env, Hono, Schema } from 'hono';
+import type { Context, Env, Hono, Schema } from 'hono';
+/**
+ * Allowed `Origin` values for browser WebSocket upgrades. Accepts the same shape
+ * as Hono's `cors.origin` option.
+ */
+export type BrowserStreamOrigin = string | string[] | ((origin: string, c: Context) => Promise<string | undefined | null> | string | undefined | null);
+/**
+ * Hono-specific browser stream configuration.
+ */
+export interface HonoBrowserStreamConfig extends BrowserStreamConfig {
+    /**
+     * Mastra instance used to authenticate requests to the browser stream routes.
+     *
+     * Every route registered by {@link setupBrowserStream} — the WebSocket upgrade,
+     * the session probe, the close endpoint, and the upgrade-ticket endpoint — is
+     * gated by the server auth middleware. Without this, an unauthenticated caller
+     * could watch and drive an agent's browser. When the instance has no
+     * `server.auth` configured the middleware is a no-op.
+     */
+    mastra: Mastra;
+    /**
+     * Origin allowlist for the browser WebSocket upgrade.
+     *
+     * Browsers always send an `Origin` header on a WebSocket handshake and attach
+     * the session cookie to it, so without an allowlist a page on any origin could
+     * open a cookie-authenticated stream and drive the agent's browser. When this is
+     * set, an upgrade from an origin that isn't allowed is rejected with `403`.
+     *
+     * Values are matched the way Hono's `cors.origin` matches them: array entries
+     * literally, and a callback only approves an origin when it returns that same
+     * origin (or `'*'`). The server's own origin always passes, because a CORS
+     * allowlist names the *other* origins and never includes the server itself.
+     *
+     * Requests without an `Origin` header (non-browser clients) are not affected,
+     * and the check is skipped entirely when this is unset. The deployer passes the
+     * explicitly configured `server.cors.origin` here; its permissive default is
+     * left as-is so cross-origin Studio deployments keep working.
+     */
+    allowedOrigins?: BrowserStreamOrigin;
+}
 /**
  * Set up WebSocket-based browser stream endpoint for real-time screencast viewing.
  *
@@ -9,6 +49,17 @@ import type { Env, Hono, Schema } from 'hono';
  * - 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.
  *
@@ -24,6 +75,7 @@ import type { Env, Hono, Schema } from 'hono';
  *
  * const app = new Hono();
  * const browserStream = await setupBrowserStream(app, {
+ *   mastra,
  *   getToolset: (agentId) => browserToolsets.get(agentId),
  * });
  *
@@ -31,5 +83,5 @@ import type { Env, Hono, Schema } from 'hono';
  * browserStream?.injectWebSocket(server);
  * ```
  */
-export declare function setupBrowserStream<E extends Env, S extends Schema, B extends string>(app: Hono<E, S, B>, config: BrowserStreamConfig): Promise<BrowserStreamResult | null>;
+export declare function setupBrowserStream<E extends Env, S extends Schema, B extends string>(app: Hono<E, S, B>, config: HonoBrowserStreamConfig): Promise<BrowserStreamResult | null>;
 //# sourceMappingURL=index.d.ts.map

package/dist/browser-stream/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser-stream/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAC9F,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EACxF,GAAG,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAuIrC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser-stream/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAC9F,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAqB,MAAM,EAAE,MAAM,MAAM,CAAC;AAQ1E;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,MAAM,EAAE,GACR,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;AAErG;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EACxF,GAAG,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAuPrC"}

package/dist/browser-stream/upgrade-tickets.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+export declare const UPGRADE_TICKET_TTL_MS = 30000;
+/**
+ * Ceiling on tickets held in memory at once. A ticket is only useful during the
+ * round trip between minting and the upgrade, so a store this full is a client
+ * asking for tickets it never spends — reject rather than keep allocating.
+ */
+export declare const MAX_OUTSTANDING_TICKETS = 500;
+/** How many tickets one agent may be issued inside {@link TICKET_ISSUANCE_WINDOW_MS}. */
+export declare const TICKET_ISSUANCE_LIMIT = 30;
+/** Length of the per-agent issuance window. */
+export declare const TICKET_ISSUANCE_WINDOW_MS = 60000;
+export interface IssuedUpgradeTicket {
+    ticket: string;
+    /** Lifetime in seconds, for the client's `expiresIn` field. */
+    expiresIn: number;
+}
+export type UpgradeTicketIssueResult = ({
+    ok: true;
+} & IssuedUpgradeTicket) | {
+    ok: false;
+    reason: 'rate-limited' | 'capacity';
+};
+/**
+ * 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.
+ */
+export declare class UpgradeTicketStore {
+    #private;
+    constructor(now?: () => number);
+    /**
+     * 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: string, threadId?: string, ttlMs?: number): UpgradeTicketIssueResult;
+    /**
+     * 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: string, agentId: string, threadId?: string): boolean;
+}
+//# sourceMappingURL=upgrade-tickets.d.ts.map

package/dist/browser-stream/upgrade-tickets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-tickets.d.ts","sourceRoot":"","sources":["../../src/browser-stream/upgrade-tickets.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,+CAA+C;AAC/C,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAmBhD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,wBAAwB,GAChC,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,mBAAmB,CAAC,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,UAAU,CAAA;CAAE,CAAC;AAYvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAkB;;IAK7B,YAAY,GAAG,GAAE,MAAM,MAAyB,EAE/C;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,MAA8B,GAAG,wBAAwB,CAoBzG;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CASnE;CAuBF"}

package/dist/index.cjs

@@ -90,7 +90,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.
 *
@@ -100,6 +255,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.
 *
@@ -115,6 +281,7 @@ function createAuthMiddleware({ mastra, requiresAuth = true }) {
 *
 * const app = new Hono();
 * const browserStream = await setupBrowserStream(app, {
+*   mastra,
 *   getToolset: (agentId) => browserToolsets.get(agentId),
 * });
 *
@@ -137,7 +304,24 @@ async function setupBrowserStream(app, config) {
 	const registry = new _mastra_server_browser_stream.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;
@@ -159,7 +343,29 @@ async function setupBrowserStream(app, config) {
 			}
 		};
 	}));
-	app.get(`${apiPrefix}/agents/:agentId/browser/session`, async (c) => {
+	const ticketBodyLimit = (0, hono_body_limit.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");
@@ -174,7 +380,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);