@mastra/connect 1.1.0-alpha.3 → 1.1.0-alpha.5

package/dist/index.cjs

@@ -4,6 +4,7 @@ let zod = require("zod");
 let _mastra_core_observability = require("@mastra/core/observability");
 let _mastra_core_tools = require("@mastra/core/tools");
 let crypto = require("crypto");
+let _mastra_core_request_context = require("@mastra/core/request-context");
 //#region src/errors.ts
 const MAX_DETAIL_LENGTH = 2e3;
 var MastraConnectError = class extends Error {
@@ -236,6 +237,20 @@ function stripTrailingSlashes(url) {
 	while (end > 0 && url[end - 1] === "/") end--;
 	return url.slice(0, end);
 }
+/** Header asserting the end-user resource key on platform data-path calls. */
+const RESOURCE_ID_HEADER = "x-mastra-resource-id";
+/**
+* Validates an end-user resource key against the platform contract: an opaque
+* string of 1–256 characters after trimming. Returns the trimmed key.
+* Mirrors the platform's `resourceIdSchema` so an invalid key fails here —
+* before any platform call — instead of as an opaque 400.
+*/
+function validateResourceId(resourceId) {
+	if (typeof resourceId !== "string") throw new MastraConnectError("invalid_options", `Invalid resourceId: expected a string, got ${typeof resourceId}.`);
+	const trimmed = resourceId.trim();
+	if (trimmed.length < 1 || trimmed.length > 256) throw new MastraConnectError("invalid_options", `Invalid resourceId: expected 1-256 characters after trimming, got ${trimmed.length}.`);
+	return trimmed;
+}
 function resolveClient(options) {
 	const accessToken = options?.accessToken?.trim() || process.env.MASTRA_PLATFORM_ACCESS_TOKEN?.trim() || process.env.MASTRA_PLATFORM_SECRET_KEY?.trim();
 	if (!accessToken) throw new MastraConnectError("missing_access_token", "Missing Mastra platform access token: set MASTRA_PLATFORM_ACCESS_TOKEN (or MASTRA_PLATFORM_SECRET_KEY), or pass client.accessToken.");
@@ -248,11 +263,14 @@ function resolveClient(options) {
 	if (orgId) headers["x-organization-id"] = orgId;
 	const projectId = options?.projectId?.trim() || process.env.MASTRA_PROJECT_ID?.trim();
 	if (projectId) headers["x-mastra-project-id"] = projectId;
+	const resourceId = options?.resourceId !== void 0 ? validateResourceId(options.resourceId) : void 0;
+	if (resourceId !== void 0) headers[RESOURCE_ID_HEADER] = resourceId;
 	return {
 		baseUrl,
 		headers,
 		fetch: options?.fetch ?? globalThis.fetch,
-		accessToken
+		accessToken,
+		resourceId
 	};
 }
 function redact(message, accessToken) {
@@ -344,12 +362,31 @@ const connectionSchema = zod.z.object({
 	connectedByUserId: zod.z.string().nullish(),
 	connectedAt: zod.z.string().nullish(),
 	createdAt: zod.z.string().nullish(),
-	accountLabel: zod.z.string().nullish()
+	accountLabel: zod.z.string().nullish(),
+	/** End-user resource key the connection is scoped to; null/absent = global. */
+	resourceId: zod.z.string().nullish()
 });
 const connectionListSchema = zod.z.object({ connections: zod.z.array(connectionSchema) });
+/**
+* One credential-form field from the platform catalog, as the hosted connect
+* surface needs it. Lenient subset of the platform's `VendorAuthField`.
+*/
+const catalogAuthFieldSchema = zod.z.object({
+	name: zod.z.string(),
+	label: zod.z.string().nullish(),
+	description: zod.z.string().nullish(),
+	placeholder: zod.z.string().nullish(),
+	secret: zod.z.boolean().nullish(),
+	required: zod.z.boolean().nullish(),
+	order: zod.z.number().nullish()
+});
 const integrationCatalogEntrySchema = zod.z.object({
 	id: zod.z.string(),
-	capabilities: zod.z.object({ mcp: zod.z.boolean().optional() })
+	capabilities: zod.z.object({ mcp: zod.z.boolean().optional() }),
+	displayName: zod.z.string().nullish(),
+	logoUrl: zod.z.string().nullish(),
+	authType: zod.z.string().nullish(),
+	authFields: zod.z.array(catalogAuthFieldSchema).nullish()
 });
 const integrationCatalogResponseSchema = zod.z.object({ integrations: zod.z.array(integrationCatalogEntrySchema) });
 /**
@@ -386,7 +423,11 @@ const connectionContextSchema = zod.z.object({
 	metadata: zod.z.record(zod.z.string(), zod.z.unknown()).nullable()
 });
 async function listProjectConnections(client, projectId) {
-	const response = await platformFetch(client, `/v2/projects/${encodeURIComponent(projectId)}/connections`);
+	const query = client.resourceId !== void 0 ? `?${new URLSearchParams({
+		resourceId: client.resourceId,
+		includeGlobal: "true"
+	})}` : "";
+	const response = await platformFetch(client, `/v2/projects/${encodeURIComponent(projectId)}/connections${query}`);
 	if (!response.ok) await throwPlatformError(response, `listing connections for project ${projectId}`);
 	const parsed = connectionListSchema.safeParse(await parsePlatformJson(response, `listing connections for project ${projectId}`));
 	if (!parsed.success) throw new MastraConnectError("platform_error", `Platform returned an unexpected connection list shape for project ${projectId}.`);
@@ -540,6 +581,34 @@ async function proxyRequestWithResponse(client, connectionId, options) {
 		};
 	}
 }
+const connectSessionSchema = zod.z.object({
+	connectionId: zod.z.string(),
+	integrationId: zod.z.string(),
+	connectUrl: zod.z.string(),
+	sessionToken: zod.z.string(),
+	expiresAt: zod.z.string()
+});
+/**
+* Creates a project-scoped connect session. A resource-scoped client passes
+* its resource key in the body, so the resulting connection is owned by that
+* end user; an unscoped client creates a global connection.
+*/
+async function createProjectConnectSession(client, projectId, integrationId) {
+	const response = await platformFetch(client, `/v2/projects/${encodeURIComponent(projectId)}/integrations/${encodeURIComponent(integrationId)}/connect-sessions`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(client.resourceId !== void 0 ? { resourceId: client.resourceId } : {})
+	});
+	if (!response.ok) await throwPlatformError(response, `creating a connect session for ${integrationId}`);
+	const parsed = connectSessionSchema.safeParse(await parsePlatformJson(response, `creating a connect session for ${integrationId}`));
+	if (!parsed.success) throw new MastraConnectError("platform_error", `Platform returned an unexpected connect-session shape for ${integrationId}.`);
+	return parsed.data;
+}
+/** Disconnects a connection. The platform tears down the vendor side asynchronously. */
+async function disconnectConnection(client, connectionId) {
+	const response = await platformFetch(client, `/v2/connections/${encodeURIComponent(connectionId)}`, { method: "DELETE" });
+	if (!response.ok) await throwPlatformError(response, `disconnecting connection ${connectionId}`);
+}
 //#endregion
 //#region src/toolset.ts
 /**
@@ -668,7 +737,8 @@ function toNamedConnections(candidates) {
 		named.push({
 			id: connection.id,
 			name,
-			accountLabel: connection.accountLabel ?? null
+			accountLabel: connection.accountLabel ?? null,
+			resourceId: connection.resourceId ?? null
 		});
 	}
 	return named;
@@ -786,8 +856,9 @@ function listConnectionsToolKey(integrationId) {
 * of the active connections. Deterministic, no I/O — reads a captured snapshot.
 */
 function buildListConnectionsTool(integrationId, connections) {
+	const listToolKey = listConnectionsToolKey(integrationId);
 	return (0, _mastra_core_tools.createTool)({
-		id: listConnectionsToolKey(integrationId),
+		id: listToolKey,
 		description: `List the available connections for the ${integrationId} provider. Use the returned 'name' values as connection_name on other ${integrationId} tools.`,
 		inputSchema: zod.z.object({}),
 		outputSchema: zod.z.object({ connections: zod.z.array(zod.z.object({
@@ -853,6 +924,7 @@ function buildProxyMultiConnectionTools(input) {
 */
 async function buildMcpMultiConnectionTools(input) {
 	const { registration, connections, allowTools, disallowTools, requireApproval, client, mcpClients, resolverId } = input;
+	const globalClient = input.globalClient ?? client;
 	const requireApprovalFor = Array.isArray(requireApproval) ? compileToolMatcher(requireApproval) : void 0;
 	const listToolKey = listConnectionsToolKey(registration.integrationId);
 	const innerAllowTools = allowTools?.filter((name) => name !== listToolKey);
@@ -869,7 +941,7 @@ async function buildMcpMultiConnectionTools(input) {
 			const cacheKey = `${registration.integrationId}::${connection.id}`;
 			let entry = mcpClients.get(cacheKey);
 			if (!entry) {
-				const transport = platformMcpTransport(client, connection.id);
+				const transport = platformMcpTransport(connection.resourceId == null ? globalClient : client, connection.id);
 				entry = {
 					integrationId: registration.integrationId,
 					connectionId: connection.id,
@@ -15444,7 +15516,7 @@ function findFreeSlotsTool(proxy) {
 				if (totalDuration >= minDurationMs) freeSlots.push({
 					start: input.timeMin,
 					end: input.timeMax,
-					durationMinutes: Math.floor(totalDuration / (60 * 1e3))
+					durationMinutes: Math.floor(totalDuration / 6e4)
 				});
 			} else {
 				const firstBusyPeriod = mergedBusyPeriods[0];
@@ -15455,7 +15527,7 @@ function findFreeSlotsTool(proxy) {
 						if (gapDuration >= minDurationMs) freeSlots.push({
 							start: input.timeMin,
 							end: firstBusyPeriod.start,
-							durationMinutes: Math.floor(gapDuration / (60 * 1e3))
+							durationMinutes: Math.floor(gapDuration / 6e4)
 						});
 					}
 				}
@@ -15470,7 +15542,7 @@ function findFreeSlotsTool(proxy) {
 						if (gapDuration >= minDurationMs) freeSlots.push({
 							start: currentPeriod.end,
 							end: nextPeriod.start,
-							durationMinutes: Math.floor(gapDuration / (60 * 1e3))
+							durationMinutes: Math.floor(gapDuration / 6e4)
 						});
 					}
 				}
@@ -15482,7 +15554,7 @@ function findFreeSlotsTool(proxy) {
 						if (gapDuration >= minDurationMs) freeSlots.push({
 							start: lastBusyPeriod.end,
 							end: input.timeMax,
-							durationMinutes: Math.floor(gapDuration / (60 * 1e3))
+							durationMinutes: Math.floor(gapDuration / 6e4)
 						});
 					}
 				}
@@ -45982,11 +46054,12 @@ function cleanBlock(block) {
 			].includes(key)) continue;
 			if (value === null) continue;
 			if (Array.isArray(value)) cleanedContent[key] = value;
-			else if (isRecord$1(value)) if (value["object"] === "block") {
-				const nestedBlock = cleanBlock(value);
-				if (nestedBlock !== null) cleanedContent[key] = nestedBlock;
+			else if (isRecord$1(value)) {
+				if (value["object"] === "block") {
+					const nestedBlock = cleanBlock(value);
+					if (nestedBlock !== null) cleanedContent[key] = nestedBlock;
+				} else cleanedContent[key] = value;
 			} else cleanedContent[key] = value;
-			else cleanedContent[key] = value;
 		}
 		cleaned[blockType] = cleanedContent;
 	}
@@ -68646,9 +68719,11 @@ function updatePriceTool(proxy) {
 				...input.tax_behavior !== void 0 && { tax_behavior: input.tax_behavior }
 			};
 			const params = new URLSearchParams();
-			for (const [key, value] of Object.entries(updateData)) if (value !== void 0 && value !== null) if (typeof value === "object" && !Array.isArray(value)) {
-				for (const [nestedKey, nestedValue] of Object.entries(value)) if (nestedValue !== void 0 && nestedValue !== null) params.append(`${key}[${nestedKey}]`, String(nestedValue));
-			} else params.append(key, String(value));
+			for (const [key, value] of Object.entries(updateData)) if (value !== void 0 && value !== null) {
+				if (typeof value === "object" && !Array.isArray(value)) {
+					for (const [nestedKey, nestedValue] of Object.entries(value)) if (nestedValue !== void 0 && nestedValue !== null) params.append(`${key}[${nestedKey}]`, String(nestedValue));
+				} else params.append(key, String(value));
+			}
 			const proxyConfig = {
 				endpoint: `/v1/prices/${encodeURIComponent(input.id)}`,
 				data: params.toString(),
@@ -75231,8 +75306,266 @@ function resolveProviderConnection(request, candidates) {
 const DEFAULT_TTL_MS$1 = 3e4;
 /** Minimum wait after a failed platform fetch before another background revalidation. */
 const FAILURE_COOLDOWN_MS$1 = 3e4;
+/** Maximum resource-scoped snapshots kept per shared state; least recently used evicts first. */
+const MAX_RESOURCE_SNAPSHOTS = 50;
+/**
+* Grace period after a resource snapshot is evicted before its MCP clients
+* become eligible for disconnect, so an agent call that resolved tools just
+* before eviction does not lose its transport mid-tool-call.
+*/
+const EVICTION_LINGER_MS = 6e4;
+const GLOBAL_SCOPE_KEY = "global";
 let nextResolverId = 0;
 /**
+* Maximum shared states kept in the registry. Each distinct option set (for
+* example an inline `fetch` closure or a rotated access token) mints one
+* state holding snapshots and open MCP transports; without a bound those
+* accumulate for the life of the process. Least recently acquired evicts
+* first and is disconnected; a resolver still holding an evicted state keeps
+* working — it just refetches and reopens transports on its next resolution.
+*/
+const MAX_SHARED_STATES = 32;
+const sharedStates = /* @__PURE__ */ new Map();
+const functionIds = /* @__PURE__ */ new WeakMap();
+let nextFunctionId = 0;
+/** Stable per-process id for a function identity (custom fetch), for use in the registry key. */
+function identityId(fn) {
+	if (!fn) return void 0;
+	let id = functionIds.get(fn);
+	if (id === void 0) {
+		id = ++nextFunctionId;
+		functionIds.set(fn, id);
+	}
+	return id;
+}
+/** Deterministic JSON with sorted object keys, so option objects written in any order share a key. */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (value && typeof value === "object") return `{${Object.entries(value).filter(([, entryValue]) => entryValue !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+function sharedStateKey(projectId, ttlMs, options) {
+	return stableStringify({
+		projectId,
+		ttlMs,
+		providers: options.providers,
+		allowTools: options.allowTools,
+		disallowTools: options.disallowTools,
+		requireApproval: options.requireApproval,
+		client: {
+			baseUrl: options.client?.baseUrl,
+			orgId: options.client?.orgId,
+			accessToken: options.client?.accessToken,
+			fetch: identityId(options.client?.fetch)
+		}
+	});
+}
+function acquireSharedState(projectId, ttlMs, options, normalizedProviders) {
+	const key = sharedStateKey(projectId, ttlMs, options);
+	let state = sharedStates.get(key);
+	if (!state) {
+		state = {
+			resolverId: ++nextResolverId,
+			projectId,
+			ttlMs,
+			options,
+			normalizedProviders,
+			mcpClients: /* @__PURE__ */ new Map(),
+			scopes: /* @__PURE__ */ new Map(),
+			evictionHolds: [],
+			lastAcquiredAt: Date.now()
+		};
+		sharedStates.set(key, state);
+		evictSharedStates(key);
+	}
+	state.lastAcquiredAt = Date.now();
+	return state;
+}
+/** Evicts and disconnects the least recently acquired states beyond the registry bound. */
+function evictSharedStates(justAcquiredKey) {
+	let excess = sharedStates.size - MAX_SHARED_STATES;
+	if (excess <= 0) return;
+	const candidates = Array.from(sharedStates.entries()).filter(([key]) => key !== justAcquiredKey).sort((a, b) => a[1].lastAcquiredAt - b[1].lastAcquiredAt);
+	for (const [key, state] of candidates) {
+		if (excess <= 0) break;
+		sharedStates.delete(key);
+		excess -= 1;
+		setTimeout(() => void disconnectState(state).catch(() => {}), EVICTION_LINGER_MS).unref?.();
+	}
+}
+function scopeKey(resourceId) {
+	return resourceId === void 0 ? GLOBAL_SCOPE_KEY : `resource:${resourceId}`;
+}
+/** Gets or creates the scope for a resource key, touching its LRU clock. */
+function acquireScope(state, resourceId) {
+	const key = scopeKey(resourceId);
+	let scope = state.scopes.get(key);
+	if (!scope) {
+		scope = {
+			resourceId,
+			client: resolveClient({
+				...state.options.client,
+				projectId: state.projectId,
+				...resourceId === void 0 ? {} : { resourceId }
+			}),
+			lastUsedAt: Date.now()
+		};
+		state.scopes.set(key, scope);
+		if (resourceId !== void 0) evictResourceScopes(state);
+	}
+	scope.lastUsedAt = Date.now();
+	return scope;
+}
+/**
+* Bounds the per-resource snapshot map. Evicted scopes' MCP keys get a
+* linger hold so transports stay alive for calls resolved just before
+* eviction; a timer re-runs the prune once the hold expires. Scopes with a
+* fetch in flight are skipped this round.
+*/
+function evictResourceScopes(state) {
+	const resourceScopes = Array.from(state.scopes.entries()).filter(([key]) => key !== GLOBAL_SCOPE_KEY);
+	let excess = resourceScopes.length - MAX_RESOURCE_SNAPSHOTS;
+	if (excess <= 0) return;
+	resourceScopes.sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt);
+	let scheduledPrune = false;
+	for (const [key, scope] of resourceScopes) {
+		if (excess <= 0) break;
+		if (scope.inflight) continue;
+		state.scopes.delete(key);
+		excess -= 1;
+		if (scope.cache && scope.cache.mcpKeys.size > 0) {
+			state.evictionHolds.push({
+				mcpKeys: scope.cache.mcpKeys,
+				expiresAt: Date.now() + EVICTION_LINGER_MS
+			});
+			if (!scheduledPrune) {
+				scheduledPrune = true;
+				setTimeout(() => void pruneStaleMcpClients(state), 60010).unref?.();
+			}
+		}
+	}
+}
+/**
+* Disconnects MCP clients no longer referenced by any scope's current
+* snapshot or by an unexpired eviction hold. Runs after every snapshot
+* refresh (a connection removed on the platform drops its transport, as
+* before) and when eviction holds expire.
+*/
+async function pruneStaleMcpClients(state) {
+	if (state.closing) return;
+	const now = Date.now();
+	state.evictionHolds = state.evictionHolds.filter((hold) => hold.expiresAt > now);
+	const active = /* @__PURE__ */ new Set();
+	for (const scope of state.scopes.values()) for (const key of scope.cache?.mcpKeys ?? []) active.add(key);
+	for (const hold of state.evictionHolds) for (const key of hold.mcpKeys) active.add(key);
+	const stale = Array.from(state.mcpClients.entries()).filter(([key]) => !active.has(key));
+	for (const [key] of stale) state.mcpClients.delete(key);
+	await Promise.allSettled(stale.map(([, entry]) => entry.client.disconnect()));
+}
+/**
+* Loads the connection list and the integration catalog for one scope. A
+* catalog failure only matters when an active connection needs catalog-backed
+* MCP discovery; otherwise checked-in HTTP providers resolve with an empty
+* catalog.
+*/
+async function loadSnapshotInputs(state, client) {
+	const [connectionsResult, catalogResult] = await Promise.allSettled([listProjectConnections(client, state.projectId), listIntegrations(client)]);
+	if (connectionsResult.status === "rejected") throw connectionsResult.reason;
+	const connections = connectionsResult.value;
+	if (catalogResult.status === "fulfilled") return {
+		connections,
+		catalog: catalogResult.value,
+		catalogAvailable: true
+	};
+	const { overrides, only } = state.normalizedProviders;
+	const checkedIn = new Set(PROVIDERS.map((registration) => registration.integrationId));
+	if (connections.some((connection) => connection.status === "active" && !checkedIn.has(connection.integrationId) && !overrides[connection.integrationId]?.disabled && (only === void 0 || only.has(connection.integrationId)))) throw catalogResult.reason;
+	const reason = catalogResult.reason;
+	console.warn(`[@mastra/connect] Platform catalog unavailable (${reason instanceof Error ? reason.message : String(reason)}); resolving checked-in providers only.`);
+	return {
+		connections,
+		catalog: [],
+		catalogAvailable: false
+	};
+}
+/**
+* Fetches a fresh snapshot for one scope, deduplicating concurrent calls per
+* scope. Rejects on failure. A refresh requested while the state is closing
+* starts after the close completes (against a freshly acquired scope, since
+* closing clears the scope map).
+*/
+function refreshScope(state, scope) {
+	if (state.closing) return state.closing.then(() => refreshScope(state, acquireScope(state, scope.resourceId)));
+	if (!scope.inflight) scope.inflight = (async () => {
+		try {
+			const { connections, catalog, catalogAvailable } = await loadSnapshotInputs(state, scope.client);
+			const requests = buildRequests(state.normalizedProviders, catalog, catalogAvailable);
+			const clientOptions = {
+				...state.options.client,
+				projectId: state.projectId,
+				...scope.resourceId === void 0 ? {} : { resourceId: scope.resourceId }
+			};
+			const { record, mcpKeys } = await mapTools(connections, requests, state.options, clientOptions, scope.client, state.mcpClients, state.resolverId);
+			scope.cache = {
+				snapshot: record,
+				fetchedAt: Date.now(),
+				mcpKeys
+			};
+			scope.lastFailureAt = void 0;
+			await pruneStaleMcpClients(state);
+			return record;
+		} catch (error) {
+			scope.lastFailureAt = Date.now();
+			throw error;
+		} finally {
+			scope.inflight = void 0;
+		}
+	})();
+	return scope.inflight;
+}
+/** Serves a scope's snapshot: fresh from cache, stale with background revalidation, or a blocking first fetch. */
+async function resolveScope(state, resourceId) {
+	const scope = acquireScope(state, resourceId);
+	if (scope.cache && Date.now() - scope.cache.fetchedAt < state.ttlMs) return scope.cache.snapshot;
+	if (scope.cache) {
+		const staleSnapshot = scope.cache.snapshot;
+		if (!(scope.lastFailureAt !== void 0 && Date.now() - scope.lastFailureAt < FAILURE_COOLDOWN_MS$1) && !scope.inflight && !state.closing) {
+			const staleFetchedAt = scope.cache.fetchedAt;
+			refreshScope(state, scope).catch((error) => {
+				console.warn(`[@mastra/connect] Keeping cached tools (fetched ${Date.now() - staleFetchedAt}ms ago); platform refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+			});
+		}
+		return staleSnapshot;
+	}
+	return refreshScope(state, scope);
+}
+/**
+* Closes every MCP transport and clears every cached snapshot in the shared
+* state. Any refresh in progress settles first so it cannot repopulate the
+* cache or register an MCP client after cleanup; refreshes requested
+* meanwhile wait for the close and start afterwards. The state stays usable:
+* the next resolution fetches fresh.
+*/
+function disconnectState(state) {
+	state.closing ??= (async () => {
+		try {
+			let pending = Array.from(state.scopes.values(), (scope) => scope.inflight).filter(Boolean);
+			while (pending.length > 0) {
+				await Promise.allSettled(pending);
+				pending = Array.from(state.scopes.values(), (scope) => scope.inflight).filter(Boolean);
+			}
+			state.scopes.clear();
+			state.evictionHolds = [];
+			const clients = Array.from(state.mcpClients.values(), (entry) => entry.client);
+			state.mcpClients.clear();
+			await Promise.allSettled(clients.map((mcp) => mcp.disconnect()));
+		} finally {
+			state.closing = void 0;
+		}
+	})();
+	return state.closing;
+}
+/**
 * Returns a live toolset resolver over the project's Platform connections.
 * HTTP providers are loaded from the shipped `PROVIDERS` registry. MCP providers
 * are discovered from the Platform integration catalog. Tools from every supported
@@ -75261,13 +75594,14 @@ function tools(options = {}) {
 	if (!projectId) throw new MastraConnectError("missing_project_id", "Missing project id: set MASTRA_PROJECT_ID or pass projectId.");
 	if (options.ttlMs !== void 0 && (!Number.isFinite(options.ttlMs) || options.ttlMs < 0)) throw new MastraConnectError("invalid_options", `Invalid ttlMs (${options.ttlMs}): expected a finite number of milliseconds >= 0.`);
 	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS$1;
-	const clientOptions = {
+	if (options.client?.resourceId !== void 0) throw new MastraConnectError("invalid_options", "Set resourceId on the tools() options (tools({ resourceId })), not on client.resourceId.");
+	const resourceIdOption = options.resourceId;
+	if (resourceIdOption !== void 0 && typeof resourceIdOption !== "string" && typeof resourceIdOption !== "function") throw new MastraConnectError("invalid_options", `Invalid resourceId: expected a string or a function, got ${typeof resourceIdOption}.`);
+	const staticResourceId = typeof resourceIdOption === "string" ? validateResourceId(resourceIdOption) : void 0;
+	resolveClient({
 		...options.client,
 		projectId
-	};
-	const client = resolveClient(clientOptions);
-	const resolverId = ++nextResolverId;
-	const mcpClients = /* @__PURE__ */ new Map();
+	});
 	const normalizedProviders = normalizeProviderOverrides(options.providers);
 	const providerOverrides = normalizedProviders.overrides;
 	validateProviderIds(providerOverrides);
@@ -75276,90 +75610,45 @@ function tools(options = {}) {
 	rejectRemovedAutoApproveTools(providerOverrides);
 	if (options.allowTools !== void 0 && options.disallowTools !== void 0) throw new MastraConnectError("invalid_options", "Top-level allowTools and disallowTools are mutually exclusive; set at most one.");
 	if (options.requireApproval !== void 0 && typeof options.requireApproval !== "boolean" && !(Array.isArray(options.requireApproval) && options.requireApproval.every((name) => typeof name === "string"))) throw new MastraConnectError("invalid_options", "Top-level requireApproval must be a boolean or an array of tool keys.");
-	let cache;
-	let inflight;
-	let closing;
-	let lastFailureAt;
-	/**
-	* Loads the connection list and the integration catalog. A catalog failure
-	* only matters when an active connection needs catalog-backed MCP discovery;
-	* otherwise checked-in HTTP providers resolve with an empty catalog.
-	*/
-	const loadSnapshotInputs = async () => {
-		const [connectionsResult, catalogResult] = await Promise.allSettled([listProjectConnections(client, projectId), listIntegrations(client)]);
-		if (connectionsResult.status === "rejected") throw connectionsResult.reason;
-		const connections = connectionsResult.value;
-		if (catalogResult.status === "fulfilled") return {
-			connections,
-			catalog: catalogResult.value,
-			catalogAvailable: true
-		};
-		const checkedIn = new Set(PROVIDERS.map((registration) => registration.integrationId));
-		if (connections.some((connection) => connection.status === "active" && !checkedIn.has(connection.integrationId) && !providerOverrides[connection.integrationId]?.disabled && (normalizedProviders.only === void 0 || normalizedProviders.only.has(connection.integrationId)))) throw catalogResult.reason;
-		const reason = catalogResult.reason;
-		console.warn(`[@mastra/connect] Platform catalog unavailable (${reason instanceof Error ? reason.message : String(reason)}); resolving checked-in providers only.`);
-		return {
-			connections,
-			catalog: [],
-			catalogAvailable: false
-		};
+	const state = acquireSharedState(projectId, ttlMs, options, normalizedProviders);
+	const validateDynamicResourceId = (raw) => raw === void 0 || raw === null ? void 0 : validateResourceId(raw);
+	const resolve = (ctx) => {
+		if (typeof resourceIdOption === "function") return Promise.resolve(resourceIdOption(ctx)).then((raw) => resolveScope(state, validateDynamicResourceId(raw)));
+		return resolveScope(state, staticResourceId);
 	};
-	/**
-	* Fetches a fresh snapshot, deduplicating concurrent calls. Rejects on
-	* failure. A refresh requested while `disconnect()` runs starts after it.
-	*/
-	const refresh = () => {
-		if (closing) return closing.then(refresh);
-		if (!inflight) inflight = (async () => {
-			try {
-				const { connections, catalog, catalogAvailable } = await loadSnapshotInputs();
-				const snapshot = await mapTools(connections, buildRequests(normalizedProviders, catalog, catalogAvailable), options, clientOptions, client, mcpClients, resolverId);
-				cache = {
-					snapshot,
-					fetchedAt: Date.now()
-				};
-				lastFailureAt = void 0;
-				return snapshot;
-			} catch (error) {
-				lastFailureAt = Date.now();
-				throw error;
-			} finally {
-				inflight = void 0;
-			}
-		})();
-		return inflight;
-	};
-	const resolve = async () => {
-		if (cache && Date.now() - cache.fetchedAt < ttlMs) return cache.snapshot;
-		if (cache) {
-			const staleSnapshot = cache.snapshot;
-			if (!(lastFailureAt !== void 0 && Date.now() - lastFailureAt < FAILURE_COOLDOWN_MS$1) && !inflight && !closing) {
-				const staleFetchedAt = cache.fetchedAt;
-				refresh().catch((error) => {
-					console.warn(`[@mastra/connect] Keeping cached tools (fetched ${Date.now() - staleFetchedAt}ms ago); platform refresh failed: ${error instanceof Error ? error.message : String(error)}`);
-				});
-			}
-			return staleSnapshot;
-		}
-		return refresh();
-	};
-	const resolver = Object.assign(resolve, {
-		refresh,
-		disconnect: () => {
-			closing ??= (async () => {
-				try {
-					while (inflight) await inflight.catch(() => void 0);
-					cache = void 0;
-					const clients = Array.from(mcpClients.values(), (entry) => entry.client);
-					mcpClients.clear();
-					await Promise.allSettled(clients.map((mcp) => mcp.disconnect()));
-				} finally {
-					closing = void 0;
-				}
-			})();
-			return closing;
+	const resolver = finalizeResolver(Object.assign(resolve, promiseSurface(resolve), {
+		refresh: () => {
+			if (typeof resourceIdOption === "function") return Promise.resolve(resourceIdOption(void 0)).then((raw) => {
+				const resourceId = validateDynamicResourceId(raw);
+				return refreshScope(state, acquireScope(state, resourceId));
+			});
+			return refreshScope(state, acquireScope(state, staticResourceId));
 		},
+		disconnect: () => disconnectState(state),
 		with: (extra) => withExtraTools(resolver, extra)
+	}));
+	return resolver;
+}
+/**
+* The Promise surface shared by every resolver shape. Each method resolves
+* fresh, so `await resolver` always reflects the current snapshot.
+*/
+function promiseSurface(resolve) {
+	return {
+		then: (onFulfilled, onRejected) => resolve().then(onFulfilled, onRejected),
+		catch: (onRejected) => resolve().catch(onRejected),
+		finally: (onFinally) => resolve().finally(onFinally)
+	};
+}
+/**
+* Adds the `Symbol.toStringTag` the Promise interface requires. Done with
+* `defineProperty` because async functions carry a non-writable inherited
+* tag ('AsyncFunction') that a plain assignment would throw on.
+*/
+function finalizeResolver(resolver) {
+	Object.defineProperty(resolver, Symbol.toStringTag, {
+		value: "ToolsResolver",
+		configurable: true
 	});
 	return resolver;
 }
@@ -75368,8 +75657,9 @@ function tools(options = {}) {
 * (and MCP clients) for at once. Callbacks are expected to produce a small,
 * closed set of option shapes (one per role, say); the cap exists so a
 * callback that accidentally derives options from unbounded per-request data
-* cannot leak an MCP client per request. Eviction is least-recently-used and
-* disconnects the evicted variant's transports.
+* cannot retain an unbounded number of resolver wrappers. Eviction is
+* least-recently-used; the separately bounded shared-state registry owns
+* transport cleanup so resource-only variants cannot disconnect each other.
 */
 const MAX_OPTION_VARIANTS = 32;
 /**
@@ -75384,15 +75674,6 @@ const MAX_OPTION_VARIANTS = 32;
 function dynamicTools(getOptions) {
 	const variants = /* @__PURE__ */ new Map();
 	let closing;
-	const disconnectEvicted = (entry) => {
-		entry.resolver.disconnect().catch((error) => {
-			console.warn(`[@mastra/connect] Failed to disconnect evicted tools variant: ${error instanceof Error ? error.message : String(error)}`);
-		});
-	};
-	const releaseVariant = (entry) => {
-		entry.inUse -= 1;
-		if (entry.evicted && entry.inUse === 0) disconnectEvicted(entry);
-	};
 	const acquireVariant = async (ctx) => {
 		if (closing) await closing;
 		const options = await getOptions(ctx);
@@ -75403,40 +75684,23 @@ function dynamicTools(getOptions) {
 		if (existing) {
 			variants.delete(key);
 			variants.set(key, existing);
-			existing.inUse += 1;
 			return existing;
 		}
-		const entry = {
-			resolver: tools(options),
-			inUse: 1,
-			evicted: false
-		};
+		const entry = { resolver: tools(options) };
 		variants.set(key, entry);
 		if (variants.size > MAX_OPTION_VARIANTS) {
-			const [oldestKey, oldest] = variants.entries().next().value;
+			const [oldestKey] = variants.entries().next().value;
 			variants.delete(oldestKey);
 			console.warn(`[@mastra/connect] tools() options callback produced more than ${MAX_OPTION_VARIANTS} distinct options values; evicting the least recently used variant. Derive options from a small, closed set of inputs (e.g. roles), not per-request data.`);
-			oldest.evicted = true;
-			if (oldest.inUse === 0) disconnectEvicted(oldest);
 		}
 		return entry;
 	};
 	const resolve = async (ctx) => {
-		const entry = await acquireVariant(ctx);
-		try {
-			return await entry.resolver(ctx);
-		} finally {
-			releaseVariant(entry);
-		}
+		return (await acquireVariant(ctx)).resolver(ctx);
 	};
-	const resolver = Object.assign(resolve, {
+	const resolver = finalizeResolver(Object.assign(resolve, promiseSurface(resolve), {
 		refresh: async () => {
-			const entry = await acquireVariant(void 0);
-			try {
-				return await entry.resolver.refresh();
-			} finally {
-				releaseVariant(entry);
-			}
+			return (await acquireVariant(void 0)).resolver.refresh();
 		},
 		disconnect: () => {
 			closing ??= (async () => {
@@ -75451,7 +75715,7 @@ function dynamicTools(getOptions) {
 			return closing;
 		},
 		with: (extra) => withExtraTools(resolver, extra)
-	});
+	}));
 	return resolver;
 }
 /** Identity registry for non-serializable option values (e.g. a custom `client.fetch`). */
@@ -75501,7 +75765,7 @@ function withExtraTools(base, extra) {
 			...extraTools
 		};
 	};
-	const resolver = Object.assign(resolve, {
+	const resolver = finalizeResolver(Object.assign(resolve, promiseSurface(resolve), {
 		refresh: async () => {
 			const [baseTools, extraTools] = await Promise.all([base.refresh(), resolveExtra()]);
 			return {
@@ -75511,7 +75775,7 @@ function withExtraTools(base, extra) {
 		},
 		disconnect: () => base.disconnect(),
 		with: (more) => withExtraTools(resolver, more)
-	});
+	}));
 	return resolver;
 }
 /**
@@ -75617,9 +75881,19 @@ function buildRequests(providers, catalog, catalogAvailable) {
 	}
 	return requests;
 }
-/** Maps one platform connection list snapshot to a flat tool record without allowing ambiguous tool ownership. */
+/**
+* Maps one platform connection list snapshot to a flat tool record without
+* allowing ambiguous tool ownership. Returns the `${integrationId}::${connectionId}`
+* keys the snapshot's MCP tools depend on; the caller prunes clients no scope
+* references anymore.
+*/
 async function mapTools(connections, requests, options, clientOptions, client, mcpClients, resolverId) {
 	const byIntegrationId = groupByIntegrationId(connections);
+	const globalClient = clientOptions.resourceId === void 0 ? client : resolveClient({
+		...clientOptions,
+		resourceId: void 0
+	});
+	const clientFor = (connectionId) => connections.find((connection) => connection.id === connectionId)?.resourceId == null ? globalClient : client;
 	const activeMcpKeys = /* @__PURE__ */ new Set();
 	const result = {};
 	const toolOwners = /* @__PURE__ */ new Map();
@@ -75636,27 +75910,28 @@ async function mapTools(connections, requests, options, clientOptions, client, m
 				connectionId: request.options.connectionId
 			}, candidates);
 			if (resolution.kind === "skip") continue;
-			if (resolution.kind === "single") if (request.registration.transport === "mcp") {
-				activeMcpKeys.add(`${integrationId}::${resolution.connectionId}`);
-				providerTools = await discoverMcpTools({
-					registration: request.registration,
-					connectionId: resolution.connectionId,
-					allowTools: request.options.allowTools,
-					disallowTools: request.options.disallowTools,
-					requireApproval: request.options.requireApproval,
-					client,
-					mcpClients,
-					resolverId
-				});
-			} else {
-				providerTools = request.registration.createTools({
-					connectionId: resolution.connectionId,
-					client: clientOptions,
-					...providerFilterOptions(request.options)
-				});
-				applyProxyRequireApproval(providerTools, integrationId, request.options.requireApproval);
-			}
-			else if (request.registration.transport === "mcp") {
+			if (resolution.kind === "single") {
+				if (request.registration.transport === "mcp") {
+					activeMcpKeys.add(`${integrationId}::${resolution.connectionId}`);
+					providerTools = await discoverMcpTools({
+						registration: request.registration,
+						connectionId: resolution.connectionId,
+						allowTools: request.options.allowTools,
+						disallowTools: request.options.disallowTools,
+						requireApproval: request.options.requireApproval,
+						client: clientFor(resolution.connectionId),
+						mcpClients,
+						resolverId
+					});
+				} else {
+					providerTools = request.registration.createTools({
+						connectionId: resolution.connectionId,
+						client: clientOptions,
+						...providerFilterOptions(request.options)
+					});
+					applyProxyRequireApproval(providerTools, integrationId, request.options.requireApproval);
+				}
+			} else if (request.registration.transport === "mcp") {
 				for (const connection of resolution.connections) activeMcpKeys.add(`${integrationId}::${connection.id}`);
 				providerTools = await buildMcpMultiConnectionTools({
 					registration: request.registration,
@@ -75665,6 +75940,7 @@ async function mapTools(connections, requests, options, clientOptions, client, m
 					disallowTools: request.options.disallowTools,
 					requireApproval: request.options.requireApproval,
 					client,
+					globalClient,
 					mcpClients,
 					resolverId
 				});
@@ -75703,10 +75979,10 @@ async function mapTools(connections, requests, options, clientOptions, client, m
 		];
 		for (const entry of defaultEntries) if (!matchedDefaultEntries.has(entry)) console.warn(`[@mastra/connect] Top-level entry '${entry}' matched no tools on any resolved provider.`);
 	}
-	const staleClients = Array.from(mcpClients.entries()).filter(([key]) => !activeMcpKeys.has(key));
-	for (const [key] of staleClients) mcpClients.delete(key);
-	await Promise.allSettled(staleClients.map(([, entry]) => entry.client.disconnect()));
-	return result;
+	return {
+		record: result,
+		mcpKeys: activeMcpKeys
+	};
 }
 /**
 * Applies the top-level default filter to a provider that set no filter of
@@ -76093,9 +76369,501 @@ function selectChannelConnection(integrationId, pinnedId, candidates) {
 /**
 * Fetches the raw credential for a connection, for building custom
 * interactions (own SDKs, MCP servers). Never log the result.
+*
+* Pass `resourceId` when the connection is scoped to an end user: the call
+* then asserts `x-mastra-resource-id`, which the platform requires for
+* resource-scoped connections (mismatch or omission → not found).
 */
 async function credential(connectionId, options) {
-	return getCredential(resolveClient(options?.client), connectionId);
+	return getCredential(resolveClient(options?.resourceId !== void 0 ? {
+		...options?.client,
+		resourceId: options.resourceId
+	} : options?.client), connectionId);
+}
+//#endregion
+//#region src/user-connect-page.ts
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/**
+* Serializes data for embedding inside an inline `<script>`: escapes `<` so a
+* value containing `<\/script>` cannot break out of the tag, and the JS line
+* separators that are invalid inside string literals.
+*/
+function toScriptJson(value) {
+	return JSON.stringify(value).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+/** Only https URLs are rendered as a logo; anything else is dropped. */
+function safeLogoUrl(logoUrl) {
+	if (!logoUrl) return null;
+	try {
+		const parsed = new URL(logoUrl);
+		return parsed.protocol === "https:" ? parsed.href : null;
+	} catch {
+		return null;
+	}
+}
+function renderConnectPage(params) {
+	const displayName = params.provider.displayName?.trim() || params.provider.id;
+	const logoUrl = safeLogoUrl(params.provider.logoUrl);
+	const data = toScriptJson({
+		basePath: params.basePath,
+		providerId: params.provider.id,
+		displayName,
+		returnTo: params.returnTo
+	});
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex" />
+<title>Connect ${escapeHtml(displayName)}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font-family: system-ui, -apple-system, sans-serif; display: flex; min-height: 100vh; margin: 0; align-items: center; justify-content: center; background: Canvas; color: CanvasText; }
+  main { text-align: center; padding: 2rem; max-width: 26rem; }
+  img.logo { width: 56px; height: 56px; border-radius: 12px; object-fit: contain; }
+  h1 { font-size: 1.25rem; margin: 1rem 0 0.5rem; }
+  p { color: GrayText; font-size: 0.9rem; line-height: 1.4; }
+  button { font: inherit; padding: 0.6rem 1.6rem; border-radius: 8px; border: 1px solid GrayText; background: ButtonFace; color: ButtonText; cursor: pointer; }
+  button:disabled { opacity: 0.6; cursor: default; }
+  #status { min-height: 1.5rem; margin-top: 1rem; }
+  #status.error { color: #c0392b; }
+  a { color: inherit; }
+</style>
+</head>
+<body>
+<main>
+  ${logoUrl ? `<img class="logo" src="${escapeHtml(logoUrl)}" alt="" />` : ""}
+  <h1>Connect ${escapeHtml(displayName)}</h1>
+  <p>You'll be sent to ${escapeHtml(displayName)} to authorize access. This window stays open until the connection is ready.</p>
+  <button id="connect" type="button">Connect ${escapeHtml(displayName)}</button>
+  <p id="status" role="status"></p>
+</main>
+<script>
+(function () {
+  var data = ${data};
+  var button = document.getElementById('connect');
+  var status = document.getElementById('status');
+  var POLL_INTERVAL_MS = 2000;
+  var MAX_POLLS = 150; // 5 minutes
+
+  function setStatus(text, isError) {
+    status.textContent = text;
+    status.className = isError ? 'error' : '';
+  }
+
+  function finish(connectionId) {
+    if (data.returnTo) {
+      var sep = data.returnTo.indexOf('?') === -1 ? '?' : '&';
+      window.location.assign(
+        data.returnTo + sep + 'connectionId=' + encodeURIComponent(connectionId) + '&status=active',
+      );
+      return;
+    }
+    setStatus('Connected. You can close this window.', false);
+  }
+
+  function poll(connectionId, popup, attempt) {
+    if (attempt >= MAX_POLLS) {
+      button.disabled = false;
+      setStatus('Timed out waiting for the connection. Try again.', true);
+      return;
+    }
+    fetch(data.basePath + '/connections/' + encodeURIComponent(connectionId) + '/status', {
+      credentials: 'same-origin',
+      headers: { accept: 'application/json' },
+    })
+      .then(function (res) {
+        // A pending connection may briefly be invisible; keep polling on 404.
+        if (res.status === 404) return { status: 'pending' };
+        if (!res.ok) throw new Error('status check failed');
+        return res.json();
+      })
+      .then(function (body) {
+        if (body.status === 'active') {
+          if (popup && !popup.closed) popup.close();
+          finish(connectionId);
+          return;
+        }
+        if (body.status === 'error') {
+          button.disabled = false;
+          setStatus('The connection failed. Try again.', true);
+          return;
+        }
+        setTimeout(function () {
+          poll(connectionId, popup, attempt + 1);
+        }, POLL_INTERVAL_MS);
+      })
+      .catch(function () {
+        setTimeout(function () {
+          poll(connectionId, popup, attempt + 1);
+        }, POLL_INTERVAL_MS);
+      });
+  }
+
+  button.addEventListener('click', function () {
+    button.disabled = true;
+    setStatus('Starting…', false);
+    // Open the popup synchronously inside the click gesture so popup blockers
+    // allow it; it is navigated once the session exists.
+    var popup = window.open('about:blank', 'mastra-connect', 'width=600,height=700');
+    fetch(data.basePath + '/' + encodeURIComponent(data.providerId) + '/sessions', {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: { accept: 'application/json' },
+    })
+      .then(function (res) {
+        if (!res.ok) throw new Error('session creation failed');
+        return res.json();
+      })
+      .then(function (session) {
+        if (popup && !popup.closed) {
+          popup.location = session.connectUrl;
+          setStatus('Finish authorizing in the popup…', false);
+        } else {
+          // Popup blocked: offer a manual link instead of auto-navigating away.
+          status.textContent = '';
+          var link = document.createElement('a');
+          link.href = session.connectUrl;
+          link.target = '_blank';
+          link.rel = 'noopener';
+          link.textContent = 'Popup blocked — click here to authorize';
+          status.appendChild(link);
+        }
+        poll(session.connectionId, popup, 0);
+      })
+      .catch(function () {
+        if (popup && !popup.closed) popup.close();
+        button.disabled = false;
+        setStatus('Could not start the connection. Try again.', true);
+      });
+  });
+})();
+<\/script>
+</body>
+</html>`;
+}
+//#endregion
+//#region src/user-connect-routes.ts
+/** Route paths that can never be used as a provider id (they collide with static segments). */
+const RESERVED_PROVIDER_IDS = /* @__PURE__ */ new Set([
+	"providers",
+	"connections",
+	"sessions"
+]);
+const NO_STORE = "no-store, private";
+function errorResponse(c, error) {
+	c.header("cache-control", NO_STORE);
+	return c.json({ error: {
+		code: error.code,
+		message: error.message
+	} }, error.status);
+}
+/**
+* Maps a platform-call failure to a safe end-user response. Platform detail
+* strings never reach the end user — this is an unauthenticated-adjacent
+* surface, and the details describe the developer's platform account.
+*/
+function toRouteError(error) {
+	if (error instanceof MastraConnectError) {
+		if (error.code === "connection_not_found") return {
+			status: 404,
+			code: "connection_not_found",
+			message: "Connection not found."
+		};
+		if (error.code === "missing_access_token" || error.code === "missing_project_id" || error.code === "invalid_options") return {
+			status: 500,
+			code: "misconfigured",
+			message: "Connect routes are not configured correctly."
+		};
+		return {
+			status: 502,
+			code: "platform_error",
+			message: "Platform request failed."
+		};
+	}
+	return {
+		status: 500,
+		code: "internal_error",
+		message: "Unexpected error."
+	};
+}
+function logRouteError(c, error) {
+	try {
+		const logger = c.get?.("mastra")?.getLogger?.();
+		if (logger?.error) {
+			logger.error(`[userConnectRoutes] ${error instanceof Error ? error.message : String(error)}`);
+			return;
+		}
+	} catch {}
+	console.error("[userConnectRoutes]", error instanceof Error ? error.message : error);
+}
+const UNAUTHORIZED = {
+	status: 401,
+	code: "unauthorized",
+	message: "No end-user identity for this request. Configure server.auth with mapUserToResourceId, or pass a resourceId callback to userConnectRoutes()."
+};
+/** Fixed base used to prove a relative `returnTo` cannot escape the origin. */
+const RETURN_TO_BASE = "https://relative.invalid";
+/**
+* Validates a `returnTo` redirect target. Relative paths (`/done`) are always
+* allowed; protocol-relative (`//host`), backslash tricks, and non-http(s)
+* schemes are rejected; absolute URLs require their origin to be allowlisted.
+*/
+function validateReturnTo(raw, allowedOrigins) {
+	if (raw === void 0 || raw === "") return {
+		ok: true,
+		value: null
+	};
+	if (raw.startsWith("/")) {
+		if (raw.startsWith("//") || raw.startsWith("/\\")) return { ok: false };
+		let resolved;
+		try {
+			resolved = new URL(raw, RETURN_TO_BASE);
+		} catch {
+			return { ok: false };
+		}
+		if (resolved.origin !== RETURN_TO_BASE) return { ok: false };
+		if (resolved.pathname.startsWith("//")) return { ok: false };
+		return {
+			ok: true,
+			value: `${resolved.pathname}${resolved.search}${resolved.hash}`
+		};
+	}
+	let parsed;
+	try {
+		parsed = new URL(raw);
+	} catch {
+		return { ok: false };
+	}
+	if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return { ok: false };
+	if (parsed.username || parsed.password) return { ok: false };
+	if (!allowedOrigins.includes(parsed.origin)) return { ok: false };
+	return {
+		ok: true,
+		value: parsed.href
+	};
+}
+function connectionScope(connection) {
+	return connection.resourceId == null ? "global" : "user";
+}
+/**
+* Builds the mountable end-user connect surface as `ApiRoute[]` for
+* `server.apiRoutes`. The routes do no authentication of their own — the
+* server's auth pipeline authenticates the request and
+* `server.auth.mapUserToResourceId` establishes the end-user resource key the
+* routes are gated on. Every platform call happens server-side with the
+* configured platform token; the browser only ever talks to these routes.
+*
+* ```ts
+* server: {
+*   auth: myAuth,
+*   apiRoutes: [...userConnectRoutes({ providers: ['linear', 'slack'] })],
+* }
+* ```
+*/
+function userConnectRoutes(options) {
+	if (!Array.isArray(options.providers) || options.providers.length === 0) throw new MastraConnectError("invalid_options", "userConnectRoutes requires a non-empty providers allowlist: the end-user surface never defaults open.");
+	const providers = options.providers.map((provider) => {
+		const id = typeof provider === "string" ? provider.trim().toLowerCase() : "";
+		if (!id) throw new MastraConnectError("invalid_options", "Invalid provider id in userConnectRoutes providers allowlist.");
+		if (RESERVED_PROVIDER_IDS.has(id) || id.includes("/")) throw new MastraConnectError("invalid_options", `Invalid provider id '${id}': reserved route segment.`);
+		return id;
+	});
+	const allowlist = new Set(providers);
+	const basePath = options.basePath ?? "/connect";
+	if (!basePath.startsWith("/") || basePath.endsWith("/") || basePath.includes(":") || basePath.includes("*")) throw new MastraConnectError("invalid_options", `Invalid basePath '${basePath}': expected an absolute path without a trailing slash or route parameters.`);
+	const projectId = options.projectId?.trim() || process.env.MASTRA_PROJECT_ID?.trim();
+	if (!projectId) throw new MastraConnectError("missing_project_id", "Missing project id: set MASTRA_PROJECT_ID or pass projectId.");
+	if (options.client?.resourceId !== void 0) throw new MastraConnectError("invalid_options", "userConnectRoutes derives the resource key per request; do not set client.resourceId.");
+	if (options.resourceId !== void 0 && typeof options.resourceId !== "function") throw new MastraConnectError("invalid_options", "Invalid resourceId: userConnectRoutes expects a callback deriving the key per request.");
+	const allowedOrigins = options.returnTo?.allowedOrigins ?? [];
+	/** Resolves the caller's resource key or null when the request carries no usable identity. */
+	const identify = async (c) => {
+		const requestContext = c.get?.("requestContext");
+		let raw;
+		if (options.resourceId) try {
+			raw = await options.resourceId({
+				requestContext,
+				user: requestContext?.get("user")
+			});
+		} catch (error) {
+			logRouteError(c, error);
+			return null;
+		}
+		else raw = requestContext?.get(_mastra_core_request_context.MASTRA_RESOURCE_ID_KEY);
+		if (typeof raw !== "string" || raw.trim() === "") return null;
+		try {
+			return validateResourceId(raw);
+		} catch (error) {
+			logRouteError(c, error);
+			return null;
+		}
+	};
+	/**
+	* Wraps a handler with the shared gate: resolve the caller identity (401
+	* when absent), resolve a resource-scoped platform client, set no-store,
+	* and map failures to safe responses.
+	*/
+	const gated = (handler) => async (c) => {
+		c.header("cache-control", NO_STORE);
+		const resourceId = await identify(c);
+		if (resourceId === null) return errorResponse(c, UNAUTHORIZED);
+		let client;
+		try {
+			client = resolveClient({
+				...options.client,
+				resourceId
+			});
+		} catch (error) {
+			logRouteError(c, error);
+			return errorResponse(c, toRouteError(error));
+		}
+		try {
+			return await handler(c, client, resourceId);
+		} catch (error) {
+			logRouteError(c, error);
+			return errorResponse(c, toRouteError(error));
+		}
+	};
+	/** Lists the caller's visible connections (global + own), filtered to the allowlist. */
+	const listVisibleConnections = async (client) => {
+		return (await listProjectConnections(client, projectId)).filter((connection) => allowlist.has(connection.integrationId.toLowerCase()));
+	};
+	const providerParam = (c) => {
+		const provider = String(c.req.param("provider") ?? "").trim().toLowerCase();
+		return allowlist.has(provider) ? provider : null;
+	};
+	const notFound = (c, code, message) => errorResponse(c, {
+		status: 404,
+		code,
+		message
+	});
+	return [
+		{
+			path: `${basePath}/providers`,
+			method: "GET",
+			requiresAuth: true,
+			handler: gated(async (c, client) => {
+				const catalog = await listIntegrations(client);
+				const byId = new Map(catalog.map((entry) => [entry.id.toLowerCase(), entry]));
+				const visible = providers.flatMap((id) => {
+					const entry = byId.get(id);
+					if (!entry) return [];
+					return [{
+						id: entry.id,
+						displayName: entry.displayName ?? null,
+						logoUrl: entry.logoUrl ?? null,
+						authType: entry.authType ?? null,
+						authFields: entry.authFields ?? null
+					}];
+				});
+				return c.json({ providers: visible });
+			})
+		},
+		{
+			path: `${basePath}/connections`,
+			method: "GET",
+			requiresAuth: true,
+			handler: gated(async (c, client) => {
+				const connections = await listVisibleConnections(client);
+				return c.json({ connections: connections.map((connection) => ({
+					id: connection.id,
+					integrationId: connection.integrationId,
+					status: connection.status,
+					accountLabel: connection.accountLabel ?? null,
+					scope: connectionScope(connection)
+				})) });
+			})
+		},
+		{
+			path: `${basePath}/connections/:id/status`,
+			method: "GET",
+			requiresAuth: true,
+			handler: gated(async (c, client) => {
+				const id = String(c.req.param("id") ?? "");
+				const connection = (await listVisibleConnections(client)).find((candidate) => candidate.id === id);
+				if (!connection) return notFound(c, "connection_not_found", "Connection not found.");
+				return c.json({
+					id: connection.id,
+					status: connection.status,
+					scope: connectionScope(connection)
+				});
+			})
+		},
+		{
+			path: `${basePath}/connections/:id`,
+			method: "DELETE",
+			requiresAuth: true,
+			handler: gated(async (c, client) => {
+				const id = String(c.req.param("id") ?? "");
+				const connection = (await listVisibleConnections(client)).find((candidate) => candidate.id === id);
+				if (!connection) return notFound(c, "connection_not_found", "Connection not found.");
+				if (connectionScope(connection) === "global") return errorResponse(c, {
+					status: 403,
+					code: "forbidden",
+					message: "Global connections cannot be disconnected from the end-user surface."
+				});
+				await disconnectConnection(client, connection.id);
+				return c.body(null, 204);
+			})
+		},
+		{
+			path: `${basePath}/:provider/sessions`,
+			method: "POST",
+			requiresAuth: true,
+			handler: gated(async (c, client) => {
+				const provider = providerParam(c);
+				if (!provider) return notFound(c, "provider_not_found", "Provider not available.");
+				const session = await createProjectConnectSession(client, projectId, provider);
+				return c.json({
+					connectionId: session.connectionId,
+					integrationId: session.integrationId,
+					connectUrl: session.connectUrl,
+					sessionToken: session.sessionToken,
+					expiresAt: session.expiresAt
+				}, 201);
+			})
+		},
+		{
+			path: `${basePath}/:provider`,
+			method: "GET",
+			requiresAuth: true,
+			handler: gated(async (c, client) => {
+				const provider = providerParam(c);
+				if (!provider) return notFound(c, "provider_not_found", "Provider not available.");
+				const returnTo = validateReturnTo(c.req.query("returnTo") ?? void 0, allowedOrigins);
+				if (!returnTo.ok) return errorResponse(c, {
+					status: 400,
+					code: "invalid_return_to",
+					message: "Invalid returnTo: use a relative path, or allowlist the origin via returnTo.allowedOrigins."
+				});
+				const entry = (await listIntegrations(client)).find((candidate) => candidate.id.toLowerCase() === provider);
+				if (!entry) return notFound(c, "provider_not_found", "Provider not available.");
+				c.header("content-security-policy", [
+					"default-src 'none'",
+					"script-src 'unsafe-inline'",
+					"style-src 'unsafe-inline'",
+					"img-src https:",
+					"connect-src 'self'",
+					"base-uri 'none'",
+					"form-action 'none'",
+					"frame-ancestors 'none'"
+				].join("; "));
+				return c.html(renderConnectPage({
+					basePath,
+					provider: {
+						id: entry.id,
+						displayName: entry.displayName,
+						logoUrl: entry.logoUrl
+					},
+					returnTo: returnTo.value
+				}));
+			})
+		}
+	];
 }
 //#endregion
 exports.CHANNELS = CHANNELS;
@@ -76104,5 +76872,6 @@ exports.PROVIDERS = PROVIDERS;
 exports.channels = channels;
 exports.credential = credential;
 exports.tools = tools;
+exports.userConnectRoutes = userConnectRoutes;
 
 //# sourceMappingURL=index.cjs.map