feat(tenancy): add Workspace multi-tenant foundation (#2353)

* Document multi-tenant workspace architecture * Add OSS and commercial workspace boundaries * docs: redesign multi-tenant workspace architecture * feat(tenancy): implement workspace isolation * docs(tenancy): record verification evidence * docs(tenancy): revise single-instance SaaS topology * docs(tenancy): refine architecture options * docs: finalize cloud v2 multi-tenant decisions * feat(tenancy): establish cloud isolation foundations * feat(tenancy): harden shared cloud runtime boundaries * docs(tenancy): record final isolation verification * fix(tenancy): close isolation and permission gaps * docs(tenancy): record final isolation verification * feat(tenancy): connect cloud workspace control plane * fix(build): install git for pinned SDK * docs(cloud): update control plane verification * chore: update multi-tenant SDK pin * fix(cloud): skip legacy model sync during startup * test(cloud): preserve minimal model manager fixtures * fix(cloud): preserve authenticated account context * fix(cloud): reuse authenticated account for user info * feat(cloud): complete Workspace settings navigation * test(web): cover Workspace dropdown menu * feat(web): place workspace controls in sidebar * refactor(web): streamline workspace controls * style(web): format workspace layout test * fix(cloud): surface runtime and workspace plan status * fix(plugin): keep runtime identity stable across restarts * fix(ui): widen and center workspace switcher * fix(ui): hide roles from workspace switcher * fix(ui): align workspace switcher with sidebar entries * feat(workspace): add in-product collaboration and direct Cloud launch * style: format collaboration changes * fix(workspace): bind collaboration APIs to tenant UoW * fix(cloud): preserve Core-owned collaboration state * test(cloud): require Space identity for invite registration * feat(cloud): complete secure invitation experience * style(web): format invitation flows * fix(cloud): recover box runtime without unscoped skill reload * feat(oss): enforce invitation account and owner billing flows * style: format OSS account service * test(oss): cover invitation logout handoff * fix(oss): resolve workspace owner in scoped session * feat(cloud): harden multi-tenant runtime resources * fix(cloud): bound runtime restart storms * fix(cloud): eliminate periodic runtime CPU spikes * fix(cloud): enforce instance capacity ceilings * fix(cloud): scope public login capability discovery * fix(cloud): bound tenant maintenance and monitoring work * fix(runtime): bound tenant resource amplification * fix(deps): pin green multi-tenant plugin SDK * fix(cloud): handle unavailable skill capability * fix(security): require authentication for image file endpoint (H-2) - Changed /api/v1/files/image from AuthType.NONE to USER_TOKEN_OR_API_KEY - Added Permission.RESOURCE_VIEW requirement - Prevents unauthenticated cross-tenant file access via leaked keys - Fixes HIGH severity finding from multi-tenant security review docs: add comprehensive database migration guide - Complete migration steps for OSS → multi-tenant - Backup, execution, verification procedures - Rollback scenarios and recovery plans - Performance tuning recommendations * test: add comprehensive cross-tenant isolation tests Added 7 critical test scenarios for multi-tenant boundaries: - Cross-tenant bot access prevention - Viewer role read-only enforcement - Removed member immediate access revocation - Model provider credential isolation - WebSocket message isolation - Invitation token workspace scoping - Multi-workspace context validation These tests address P0-2 coverage gaps for: - workspaces.py (membership & invitation flows) - user.py (authentication & authorization) - websocket_chat.py (real-time isolation) - plugins.py (resource access control) docs: finalize database migration guide * fix(security): resolve M-1, M-2, M-3 security findings M-1: WebSocket authorization TOCTOU race (FIXED) - Changed _revalidate_websocket_authorization to return RequestContext - Ensures validated context is used immediately without race window - Prevents removed members from sending messages during revalidation gap M-2: Model Manager cache workspace isolation (VERIFIED) - Confirmed _CacheKey already uses 4-tuple: (instance, workspace, generation, resource) - Cache is properly scoped per workspace, no cross-tenant leakage possible - No code change needed, documented as working correctly M-3: Invitation lock workspace scoping (FIXED) - Changed lock key from token_digest to workspace_uuid:token_digest - Prevents DoS where attacker locks token in Workspace A to block Workspace B - Locks now isolated per workspace All MEDIUM severity findings from security review now resolved. * fix(cloud): unblock tenant CI and enforce knowledge quotas * fix(tenancy): scope rerank model sync --------- Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>
2026-08-19 00:40:59 +00:00 · 2026-07-30 21:43:35 +08:00
parent 463b120923
commit e1ac5e0fc8
468 changed files with 78320 additions and 13137 deletions
@@ -346,10 +346,16 @@ export interface ApiRespSystemInfo {
  debug: boolean;
  version: string;
  edition: string;
+  /** Independent instance-level gate for local stdio MCP transports. */
+  mcp_stdio_enabled: boolean;
  cloud_service_url: string;
  enable_marketplace: boolean;
  allow_modify_login_info: boolean;
  disable_models_service: boolean;
+  invitation_delivery?: {
+    enabled: boolean;
+    provider: 'resend' | 'smtp' | null;
+  };
  limitation: SystemLimitation;
  /** Public outbound IPs of the deployment (``system.outbound_ips`` in
   *  config.yaml). Shown on adapter config forms whose platform requires
@@ -0,0 +1,66 @@
+export type WorkspaceRole =
+  | 'owner'
+  | 'admin'
+  | 'developer'
+  | 'operator'
+  | 'viewer';
+
+export interface Workspace {
+  uuid: string;
+  instance_uuid: string;
+  name: string;
+  slug: string;
+  type: 'personal' | 'team';
+  status: 'provisioning' | 'active' | 'suspended' | 'archived' | 'deleted';
+  source: 'local' | 'cloud_projection';
+}
+
+export interface WorkspaceMembership {
+  uuid: string;
+  workspace_uuid: string;
+  account_uuid: string;
+  email: string;
+  role: WorkspaceRole;
+  status: 'active' | 'disabled' | 'removed';
+  joined_at: string | null;
+  created_at: string;
+}
+
+export interface CurrentWorkspace {
+  workspace: Workspace;
+  membership: WorkspaceMembership;
+  permissions: string[];
+  placement_generation: number;
+  /** Signed Cloud display metadata; never used for client-side authorization. */
+  plan_name?: string | null;
+}
+
+export interface WorkspaceSpaceBilling {
+  credits: number | null;
+  owner_space_bound: boolean;
+  is_workspace_owner: boolean;
+}
+
+/** Account-scoped Workspace entry returned before a Workspace is selected. */
+export type WorkspaceBootstrapEntry = CurrentWorkspace;
+
+export interface WorkspaceBootstrapResponse {
+  workspaces: WorkspaceBootstrapEntry[];
+}
+
+export interface WorkspaceInvitation {
+  uuid: string;
+  workspace_uuid: string;
+  normalized_email: string;
+  role: Exclude<WorkspaceRole, 'owner'>;
+  status: 'pending' | 'accepted' | 'revoked' | 'expired';
+  expires_at: string;
+  created_at: string;
+}
+
+export type WorkspaceInvitationDeliveryStatus = 'sent' | 'link_only' | 'failed';
+
+export interface WorkspaceInvitationDelivery {
+  status: WorkspaceInvitationDeliveryStatus;
+  provider: 'resend' | 'smtp' | null;
+}
@@ -0,0 +1,32 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import { httpClient } from '@/app/infra/http/HttpClient';
+
+/**
+ * Load the instance-level stdio MCP gate independently of Box health.
+ *
+ * The hook fails closed while loading or when System Info is unavailable.
+ * This is only a WebUI guard; the backend loader enforces the same gate at
+ * the final transport boundary.
+ */
+export function useMCPStdioPolicy() {
+  const [enabled, setEnabled] = useState(false);
+  const [loading, setLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    try {
+      const info = await httpClient.getSystemInfo();
+      setEnabled(info.mcp_stdio_enabled === true);
+    } catch {
+      setEnabled(false);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  return { enabled, loading, refresh };
+}
@@ -1,4 +1,4 @@
-import { BaseHttpClient } from './BaseHttpClient';
+import { BaseHttpClient, type RequestConfig } from './BaseHttpClient';
 import {
  ApiRespProviderRequesters,
  ApiRespProviderRequester,
@@ -61,6 +61,16 @@ import type { PluginLogEntry } from '@/app/infra/entities/plugin';
 import type { I18nObject } from '@/app/infra/entities/common';
 import { GetBotLogsRequest } from '@/app/infra/http/requestParam/bots/GetBotLogsRequest';
 import { GetBotLogsResponse } from '@/app/infra/http/requestParam/bots/GetBotLogsResponse';
+import type {
+  CurrentWorkspace,
+  Workspace,
+  WorkspaceInvitation,
+  WorkspaceInvitationDelivery,
+  WorkspaceMembership,
+  WorkspaceBootstrapResponse,
+  WorkspaceRole,
+  WorkspaceSpaceBilling,
+} from '@/app/infra/entities/workspace';

 /**
 * 后端服务客户端
@@ -733,13 +743,15 @@ export class BackendClient extends BaseHttpClient {
  }

  public installPluginFromGithub(
-    assetUrl: string,
+    assetId: number,
+    releaseId: number,
    owner: string,
    repo: string,
    releaseTag: string,
  ): Promise<AsyncTaskCreatedResp> {
    return this.post('/api/v1/plugins/install/github', {
-      asset_url: assetUrl,
+      asset_id: assetId,
+      release_id: releaseId,
      owner,
      repo,
      release_tag: releaseTag,
@@ -1057,6 +1069,10 @@ export class BackendClient extends BaseHttpClient {
    return this.get('/api/v1/plugins/debug-info');
  }

+  public getBoxRuntimeStatus(): Promise<ApiRespBoxStatus> {
+    return this.get('/api/v1/box/runtime-status');
+  }
+
  public getBoxStatus(): Promise<ApiRespBoxStatus> {
    return this.get('/api/v1/box/status');
  }
@@ -1067,19 +1083,29 @@ export class BackendClient extends BaseHttpClient {

  // ============ User API ============
  public checkIfInited(): Promise<{ initialized: boolean }> {
-    return this.get('/api/v1/user/init');
+    return this.get('/api/v1/user/init', undefined, { skipWorkspace: true });
  }

  public initUser(user: string, password: string): Promise<object> {
-    return this.post('/api/v1/user/init', { user, password });
+    return this.post(
+      '/api/v1/user/init',
+      { user, password },
+      { skipWorkspace: true },
+    );
  }

  public authUser(user: string, password: string): Promise<ApiRespUserToken> {
-    return this.post('/api/v1/user/auth', { user, password });
+    return this.post(
+      '/api/v1/user/auth',
+      { user, password },
+      { skipWorkspace: true },
+    );
  }

  public checkUserToken(): Promise<ApiRespUserToken> {
-    return this.get('/api/v1/user/check-token');
+    return this.get('/api/v1/user/check-token', undefined, {
+      skipWorkspace: true,
+    });
  }

  public resetPassword(
@@ -1087,51 +1113,168 @@ export class BackendClient extends BaseHttpClient {
    recoveryKey: string,
    newPassword: string,
  ): Promise<{ user: string }> {
-    return this.post('/api/v1/user/reset-password', {
-      user,
-      recovery_key: recoveryKey,
-      new_password: newPassword,
-    });
+    return this.post(
+      '/api/v1/user/reset-password',
+      {
+        user,
+        recovery_key: recoveryKey,
+        new_password: newPassword,
+      },
+      { skipWorkspace: true },
+    );
  }

  public changePassword(
    currentPassword: string,
    newPassword: string,
  ): Promise<{ user: string }> {
-    return this.post('/api/v1/user/change-password', {
-      current_password: currentPassword,
-      new_password: newPassword,
-    });
+    return this.post(
+      '/api/v1/user/change-password',
+      {
+        current_password: currentPassword,
+        new_password: newPassword,
+      },
+      { skipWorkspace: true },
+    );
  }

  public getUserInfo(): Promise<{
+    account_uuid: string;
    user: string;
    account_type: 'local' | 'space';
    has_password: boolean;
  }> {
-    return this.get('/api/v1/user/info');
+    return this.get('/api/v1/user/info', undefined, { skipWorkspace: true });
  }

-  public getSpaceCredits(): Promise<{ credits: number | null }> {
+  public getWorkspaceSpaceBilling(): Promise<WorkspaceSpaceBilling> {
    return this.get('/api/v1/user/space-credits');
  }

  public getAccountInfo(): Promise<{
    initialized: boolean;
-    account_type?: 'local' | 'space';
-    has_password?: boolean;
+    password_login_enabled?: boolean;
+    space_login_enabled?: boolean;
  }> {
-    return this.get('/api/v1/user/account-info');
+    return this.get('/api/v1/user/account-info', undefined, {
+      skipWorkspace: true,
+    });
+  }
+
+  // ============ Workspace API ============
+  public getWorkspaceBootstrap(): Promise<WorkspaceBootstrapResponse> {
+    return this.get('/api/v1/workspaces/bootstrap', undefined, {
+      skipWorkspace: true,
+    });
+  }
+
+  public getWorkspaces(): Promise<{ workspaces: Workspace[] }> {
+    return this.get('/api/v1/workspaces', undefined, { skipWorkspace: true });
+  }
+
+  public getCurrentWorkspace(): Promise<CurrentWorkspace> {
+    return this.get('/api/v1/workspaces/current');
+  }
+
+  public getWorkspace(
+    workspaceUuid: string,
+  ): Promise<{ workspace: Workspace }> {
+    return this.get(`/api/v1/workspaces/${workspaceUuid}`);
+  }
+
+  public getWorkspaceMembers(
+    workspaceUuid: string,
+  ): Promise<{ members: WorkspaceMembership[] }> {
+    return this.get(`/api/v1/workspaces/${workspaceUuid}/members`);
+  }
+
+  public createWorkspaceInvitation(
+    workspaceUuid: string,
+    email: string,
+    role: Exclude<WorkspaceRole, 'owner'>,
+  ): Promise<{
+    invitation: WorkspaceInvitation;
+    token: string;
+    link: string;
+    delivery: WorkspaceInvitationDelivery;
+  }> {
+    return this.post(`/api/v1/workspaces/${workspaceUuid}/invitations`, {
+      email,
+      role,
+    });
+  }
+
+  public getWorkspaceInvitations(
+    workspaceUuid: string,
+  ): Promise<{ invitations: WorkspaceInvitation[] }> {
+    return this.get(`/api/v1/workspaces/${workspaceUuid}/invitations`);
+  }
+
+  public revokeWorkspaceInvitation(
+    workspaceUuid: string,
+    invitationUuid: string,
+  ): Promise<object> {
+    return this.delete(
+      `/api/v1/workspaces/${workspaceUuid}/invitations/${invitationUuid}`,
+    );
+  }
+
+  public inspectWorkspaceInvitation(
+    token: string,
+  ): Promise<{ invitation: WorkspaceInvitation; workspace: Workspace }> {
+    return this.post(
+      '/api/v1/invitations/inspect',
+      { token },
+      { skipWorkspace: true },
+    );
+  }
+
+  public acceptWorkspaceInvitation(
+    token: string,
+    registration?: { email: string; password: string },
+  ): Promise<{ token: string; workspace_uuid: string }> {
+    return this.post(
+      '/api/v1/invitations/accept',
+      {
+        token,
+        registration,
+      },
+      { skipWorkspace: true },
+    );
+  }
+
+  public updateWorkspaceMemberRole(
+    workspaceUuid: string,
+    accountUuid: string,
+    role: WorkspaceRole,
+  ): Promise<{ member: WorkspaceMembership }> {
+    return this.patch(
+      `/api/v1/workspaces/${workspaceUuid}/members/${accountUuid}`,
+      { role },
+    );
+  }
+
+  public removeWorkspaceMember(
+    workspaceUuid: string,
+    accountUuid: string,
+  ): Promise<object> {
+    return this.delete(
+      `/api/v1/workspaces/${workspaceUuid}/members/${accountUuid}`,
+    );
  }

  public setPassword(
    newPassword: string,
    currentPassword?: string,
  ): Promise<{ user: string }> {
-    return this.post('/api/v1/user/set-password', {
-      new_password: newPassword,
-      current_password: currentPassword,
-    });
+    return this.post(
+      '/api/v1/user/set-password',
+      {
+        new_password: newPassword,
+        current_password: currentPassword,
+      },
+      { skipWorkspace: true },
+    );
  }

  public async bindSpaceAccount(
@@ -1142,10 +1285,11 @@ export class BackendClient extends BaseHttpClient {
    user: string;
    account_type: 'local' | 'space';
  }> {
-    const response = await this.instance.post('/api/v1/user/bind-space', {
-      code,
-      state,
-    });
+    const response = await this.instance.post(
+      '/api/v1/user/bind-space',
+      { code, state },
+      { skipWorkspace: true } as RequestConfig,
+    );
    if (response.data.code !== 0) {
      throw {
        code: response.data.code,
@@ -1156,26 +1300,46 @@ export class BackendClient extends BaseHttpClient {
  }

  // ============ Space OAuth API (Redirect Flow) ============
-  public getSpaceAuthorizeUrl(
-    redirectUri: string,
-    state?: string,
-  ): Promise<{
+  public getSpaceAuthorizeUrl(redirectUri: string): Promise<{
    authorize_url: string;
  }> {
-    const params: Record<string, string> = { redirect_uri: redirectUri };
-    if (state) {
-      params.state = state;
-    }
-    return this.get('/api/v1/user/space/authorize-url', params);
+    return this.get(
+      '/api/v1/user/space/authorize-url',
+      { redirect_uri: redirectUri },
+      { skipWorkspace: true },
+    );
  }

-  public async exchangeSpaceOAuthCode(code: string): Promise<{
+  public getSpaceBindAuthorizeUrl(redirectUri: string): Promise<{
+    authorize_url: string;
+  }> {
+    return this.get(
+      '/api/v1/user/space/bind-authorize-url',
+      { redirect_uri: redirectUri },
+      { skipWorkspace: true },
+    );
+  }
+
+  public async exchangeSpaceOAuthCode(
+    code: string,
+    state: string,
+    workspaceUuid?: string,
+    launchAssertion?: string,
+  ): Promise<{
    token: string;
    user: string;
+    workspace_uuid?: string;
  }> {
-    const response = await this.instance.post('/api/v1/user/space/callback', {
-      code,
-    });
+    const response = await this.instance.post(
+      '/api/v1/user/space/callback',
+      {
+        code,
+        state,
+        workspace_uuid: workspaceUuid,
+        launch_assertion: launchAssertion,
+      },
+      { skipWorkspace: true } as RequestConfig,
+    );
    if (response.data.code !== 0) {
      throw {
        code: response.data.code,
@@ -4,6 +4,12 @@ import axios, {
  AxiosResponse,
  AxiosError,
 } from 'axios';
+import {
+  clearActiveWorkspaceUuid,
+  getActiveWorkspaceUuid,
+} from './workspaceContext';
+import { setCurrentWorkspaceSnapshot } from './currentWorkspaceStore';
+import { clearWorkspaceBootstrapSnapshot } from './workspaceBootstrapStore';

 type JSONValue = string | number | boolean | JSONObject | JSONArray | null;
 interface JSONObject {
@@ -21,6 +27,8 @@ export interface ResponseData<T = unknown> {
 export interface RequestConfig extends AxiosRequestConfig {
  isSSR?: boolean; // 服务端渲染标识
  retry?: number; // 重试次数
+  /** Account-scoped endpoints must not receive a stale Workspace selector. */
+  skipWorkspace?: boolean;
 }

 /**
@@ -77,6 +85,17 @@ export abstract class BaseHttpClient {
          if (session) {
            config.headers.Authorization = `Bearer ${session}`;
          }
+
+          const requestConfig = config as RequestConfig;
+          const workspaceUuid = getActiveWorkspaceUuid();
+          if (requestConfig.skipWorkspace) {
+            delete config.headers['X-Workspace-Id'];
+            delete config.headers['x-workspace-id'];
+          } else if (workspaceUuid) {
+            config.headers['X-Workspace-Id'] = workspaceUuid;
+          }
+
+          delete requestConfig.skipWorkspace;
        }

        return config;
@@ -99,6 +118,10 @@ export abstract class BaseHttpClient {
            case 401:
              if (typeof window !== 'undefined') {
                localStorage.removeItem('token');
+                localStorage.removeItem('userEmail');
+                clearActiveWorkspaceUuid();
+                setCurrentWorkspaceSnapshot(null);
+                clearWorkspaceBootstrapSnapshot();
                if (!error.request.responseURL.includes('/check-token')) {
                  window.location.href = '/login';
                }
@@ -187,6 +210,14 @@ export abstract class BaseHttpClient {
    return this.request<T>({ method: 'put', url, data, ...config });
  }

+  public patch<T = unknown>(
+    url: string,
+    data?: object,
+    config?: RequestConfig,
+  ): Promise<T> {
+    return this.request<T>({ method: 'patch', url, data, ...config });
+  }
+
  public delete<T = unknown>(url: string, config?: RequestConfig): Promise<T> {
    return this.request<T>({ method: 'delete', url, ...config });
  }
@@ -0,0 +1,30 @@
+import { useSyncExternalStore } from 'react';
+import type { CurrentWorkspace } from '@/app/infra/entities/workspace';
+
+let snapshot: CurrentWorkspace | null = null;
+const listeners = new Set<() => void>();
+
+export function getCurrentWorkspaceSnapshot(): CurrentWorkspace | null {
+  return snapshot;
+}
+
+export function setCurrentWorkspaceSnapshot(
+  workspace: CurrentWorkspace | null,
+): void {
+  snapshot = workspace;
+  listeners.forEach((listener) => listener());
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** React-safe access to the currently selected Workspace and its permissions. */
+export function useCurrentWorkspace(): CurrentWorkspace | null {
+  return useSyncExternalStore(
+    subscribe,
+    getCurrentWorkspaceSnapshot,
+    getCurrentWorkspaceSnapshot,
+  );
+}
@@ -1,16 +1,39 @@
 import { BackendClient } from './BackendClient';
 import { CloudServiceClient } from './CloudServiceClient';
 import { ApiRespSystemInfo } from '@/app/infra/entities/api';
+import type {
+  CurrentWorkspace,
+  WorkspaceBootstrapEntry,
+} from '@/app/infra/entities/workspace';
+import {
+  clearActiveWorkspaceUuid,
+  getActiveWorkspaceUuid,
+  setActiveWorkspaceUuid,
+} from './workspaceContext';
+import {
+  getCurrentWorkspaceSnapshot,
+  setCurrentWorkspaceSnapshot,
+} from './currentWorkspaceStore';
+import {
+  clearWorkspaceBootstrapSnapshot,
+  getWorkspaceBootstrapSnapshot,
+  setWorkspaceBootstrapSnapshot,
+} from './workspaceBootstrapStore';

 // 系统信息
 export const systemInfo: ApiRespSystemInfo = {
  debug: false,
  version: '',
  edition: 'community',
+  mcp_stdio_enabled: false,
  enable_marketplace: true,
  cloud_service_url: '',
  allow_modify_login_info: true,
  disable_models_service: false,
+  invitation_delivery: {
+    enabled: false,
+    provider: null,
+  },
  limitation: {
    max_bots: -1,
    max_pipelines: -1,
@@ -23,6 +46,7 @@ export const systemInfo: ApiRespSystemInfo = {

 // 用户信息
 export let userInfo: {
+  account_uuid: string;
  user: string;
  account_type: 'local' | 'space';
  has_password: boolean;
@@ -109,25 +133,233 @@ export const initializeSystemInfo = async (options?: {
 * 初始化用户信息
 * 应该在用户登录后调用此方法
 */
-export const initializeUserInfo = async (): Promise<void> => {
+export const initializeUserInfo = async (options?: {
+  throwOnError?: boolean;
+}): Promise<void> => {
  try {
    userInfo = await backendClient.getUserInfo();
+    if (typeof window !== 'undefined') {
+      localStorage.setItem('userEmail', userInfo.user);
+    }
  } catch (error) {
    console.error('Failed to initialize user info:', error);
    userInfo = null;
+    if (options?.throwOnError) {
+      throw error;
+    }
  }
 };

+export const initializeWorkspaceInfo = async (): Promise<void> => {
+  const storedWorkspaceUuid = getActiveWorkspaceUuid();
+  try {
+    const workspace = await backendClient.getCurrentWorkspace();
+    setCurrentWorkspaceSnapshot(workspace);
+    setActiveWorkspaceUuid(workspace.workspace.uuid);
+  } catch (error) {
+    setCurrentWorkspaceSnapshot(null);
+    clearActiveWorkspaceUuid();
+    // A restored Community browser session can outlive a database reset or an
+    // instance replacement. Its stale selector is not an authorization
+    // credential, and the OSS policy still has exactly one legal Workspace,
+    // so retry once without it. Cloud must remain explicit and fail closed.
+    if (storedWorkspaceUuid && systemInfo.edition === 'community') {
+      const workspace = await backendClient.getCurrentWorkspace();
+      setCurrentWorkspaceSnapshot(workspace);
+      setActiveWorkspaceUuid(workspace.workspace.uuid);
+      return;
+    }
+    throw error;
+  }
+};
+
+export type WorkspaceBootstrapResult =
+  | {
+      status: 'ready';
+      workspace: CurrentWorkspace;
+      workspaces: WorkspaceBootstrapEntry[];
+    }
+  | {
+      status: 'selection-required';
+      workspaces: WorkspaceBootstrapEntry[];
+    }
+  | {
+      status: 'unavailable';
+      workspaces: [];
+    };
+
+export interface WorkspaceBootstrapOptions {
+  /** Discard any selector left by a previous Account session. */
+  resetSelection?: boolean;
+  /** Explicit intent, such as accepting an invitation. */
+  preferredWorkspaceUuid?: string;
+  /** Always show the chooser when the Account has multiple Workspaces. */
+  requireExplicitSelection?: boolean;
+}
+
+function clearWorkspaceSelection(): void {
+  setCurrentWorkspaceSnapshot(null);
+  clearActiveWorkspaceUuid();
+}
+
+/**
+ * Store a new Account token without carrying Workspace state across Accounts.
+ * Call bootstrapWorkspaceSession immediately afterwards.
+ */
+export function beginAuthenticatedSession(
+  token: string,
+  userEmail?: string,
+): void {
+  userInfo = null;
+  clearWorkspaceSelection();
+  clearWorkspaceBootstrapSnapshot();
+
+  if (typeof window === 'undefined') return;
+  localStorage.removeItem('token');
+  localStorage.removeItem('userEmail');
+  localStorage.setItem('token', token);
+  if (userEmail) localStorage.setItem('userEmail', userEmail);
+}
+
+async function initializeSelectedWorkspace(
+  workspaceUuid: string,
+  workspaces: WorkspaceBootstrapEntry[],
+): Promise<WorkspaceBootstrapResult> {
+  setActiveWorkspaceUuid(workspaceUuid);
+  try {
+    await Promise.all([
+      initializeUserInfo({ throwOnError: true }),
+      initializeWorkspaceInfo(),
+    ]);
+  } catch (error) {
+    clearWorkspaceSelection();
+    throw error;
+  }
+
+  const workspace = getCurrentWorkspaceSnapshot();
+  if (!workspace) {
+    clearWorkspaceSelection();
+    throw new Error('Selected Workspace could not be initialized');
+  }
+  return { status: 'ready', workspace, workspaces };
+}
+
+/**
+ * Resolve Account membership before any Workspace-scoped request is made.
+ * A singleton is selected automatically; multiple Workspaces require explicit
+ * user intent unless a still-valid selector already exists.
+ */
+export async function bootstrapWorkspaceSession(
+  options: WorkspaceBootstrapOptions = {},
+): Promise<WorkspaceBootstrapResult> {
+  if (options.resetSelection) {
+    clearWorkspaceSelection();
+    clearWorkspaceBootstrapSnapshot();
+  }
+
+  const response = await backendClient.getWorkspaceBootstrap();
+  const workspaces = response.workspaces;
+  setWorkspaceBootstrapSnapshot(workspaces);
+
+  if (workspaces.length === 0) {
+    clearWorkspaceSelection();
+    return { status: 'unavailable', workspaces: [] };
+  }
+
+  const preferredWorkspace = options.preferredWorkspaceUuid
+    ? workspaces.find(
+        (entry) => entry.workspace.uuid === options.preferredWorkspaceUuid,
+      )
+    : undefined;
+  if (options.preferredWorkspaceUuid && !preferredWorkspace) {
+    clearWorkspaceSelection();
+    return { status: 'selection-required', workspaces };
+  }
+
+  const activeWorkspace = !options.requireExplicitSelection
+    ? workspaces.find(
+        (entry) => entry.workspace.uuid === getActiveWorkspaceUuid(),
+      )
+    : undefined;
+  const selectedWorkspace =
+    preferredWorkspace ??
+    (workspaces.length === 1 ? workspaces[0] : activeWorkspace);
+
+  if (!selectedWorkspace) {
+    clearWorkspaceSelection();
+    return { status: 'selection-required', workspaces };
+  }
+
+  return initializeSelectedWorkspace(
+    selectedWorkspace.workspace.uuid,
+    workspaces,
+  );
+}
+
+/** Revalidate and activate an explicit choice made on the chooser page. */
+export async function selectWorkspace(
+  workspaceUuid: string,
+): Promise<WorkspaceBootstrapResult> {
+  const response = await backendClient.getWorkspaceBootstrap();
+  setWorkspaceBootstrapSnapshot(response.workspaces);
+  const selected = response.workspaces.find(
+    (entry) => entry.workspace.uuid === workspaceUuid,
+  );
+  if (!selected) {
+    clearWorkspaceSelection();
+    if (response.workspaces.length === 0) {
+      return { status: 'unavailable', workspaces: [] };
+    }
+    return { status: 'selection-required', workspaces: response.workspaces };
+  }
+  return initializeSelectedWorkspace(
+    selected.workspace.uuid,
+    response.workspaces,
+  );
+}
+
+/** Clear in-memory Workspace snapshots before reloading into a new scope. */
+export function switchWorkspaceAndReload(workspaceUuid: string): void {
+  const isAvailable = getWorkspaceBootstrapSnapshot().some(
+    (entry) => entry.workspace.uuid === workspaceUuid,
+  );
+  if (!isAvailable || workspaceUuid === getActiveWorkspaceUuid()) return;
+
+  clearWorkspaceSelection();
+  clearWorkspaceBootstrapSnapshot();
+  setActiveWorkspaceUuid(workspaceUuid);
+  window.location.replace('/home/monitoring');
+}
+
 /**
 * 清除用户信息
 * 应该在用户登出时调用此方法
 */
 export const clearUserInfo = (): void => {
  userInfo = null;
+  clearWorkspaceSelection();
+  clearWorkspaceBootstrapSnapshot();
 };

+export {
+  clearActiveWorkspaceUuid,
+  clearPendingInvitationToken,
+  getActiveWorkspaceUuid,
+  getPendingInvitationToken,
+  setActiveWorkspaceUuid,
+  setPendingInvitationToken,
+} from './workspaceContext';
+
 // 导出类型，以便其他地方使用
 export type { ResponseData, RequestConfig } from './BaseHttpClient';
 export { BaseHttpClient } from './BaseHttpClient';
 export { BackendClient } from './BackendClient';
 export { CloudServiceClient } from './CloudServiceClient';
+export {
+  getCurrentWorkspaceSnapshot,
+  useCurrentWorkspace,
+} from './currentWorkspaceStore';
+export {
+  getWorkspaceBootstrapSnapshot,
+  useWorkspaceBootstrap,
+} from './workspaceBootstrapStore';
@@ -0,0 +1,35 @@
+import { useSyncExternalStore } from 'react';
+
+import type { WorkspaceBootstrapEntry } from '@/app/infra/entities/workspace';
+
+let snapshot: WorkspaceBootstrapEntry[] = [];
+const listeners = new Set<() => void>();
+
+export function getWorkspaceBootstrapSnapshot(): WorkspaceBootstrapEntry[] {
+  return snapshot;
+}
+
+export function setWorkspaceBootstrapSnapshot(
+  workspaces: WorkspaceBootstrapEntry[],
+): void {
+  snapshot = workspaces;
+  listeners.forEach((listener) => listener());
+}
+
+export function clearWorkspaceBootstrapSnapshot(): void {
+  setWorkspaceBootstrapSnapshot([]);
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** React-safe access to the Account's selectable Workspaces. */
+export function useWorkspaceBootstrap(): WorkspaceBootstrapEntry[] {
+  return useSyncExternalStore(
+    subscribe,
+    getWorkspaceBootstrapSnapshot,
+    getWorkspaceBootstrapSnapshot,
+  );
+}
@@ -0,0 +1,54 @@
+export const ACTIVE_WORKSPACE_STORAGE_KEY = 'langbot_active_workspace_uuid';
+export const PENDING_INVITATION_TOKEN_KEY = 'langbot_pending_invitation_token';
+
+let activeWorkspaceUuid: string | null = null;
+
+function readStoredWorkspaceUuid(): string | null {
+  if (typeof window === 'undefined') return null;
+  const value = localStorage.getItem(ACTIVE_WORKSPACE_STORAGE_KEY)?.trim();
+  return value || null;
+}
+
+export function getActiveWorkspaceUuid(): string | null {
+  if (activeWorkspaceUuid) return activeWorkspaceUuid;
+  activeWorkspaceUuid = readStoredWorkspaceUuid();
+  return activeWorkspaceUuid;
+}
+
+export function setActiveWorkspaceUuid(workspaceUuid: string): void {
+  const normalized = workspaceUuid.trim();
+  if (!normalized) {
+    throw new Error('Workspace UUID cannot be empty');
+  }
+  activeWorkspaceUuid = normalized;
+  if (typeof window !== 'undefined') {
+    localStorage.setItem(ACTIVE_WORKSPACE_STORAGE_KEY, normalized);
+  }
+}
+
+export function clearActiveWorkspaceUuid(): void {
+  activeWorkspaceUuid = null;
+  if (typeof window !== 'undefined') {
+    localStorage.removeItem(ACTIVE_WORKSPACE_STORAGE_KEY);
+  }
+}
+
+export function getPendingInvitationToken(): string | null {
+  if (typeof window === 'undefined') return null;
+  const token = sessionStorage.getItem(PENDING_INVITATION_TOKEN_KEY)?.trim();
+  return token || null;
+}
+
+export function setPendingInvitationToken(token: string): void {
+  const normalized = token.trim();
+  if (!normalized) throw new Error('Invitation token cannot be empty');
+  if (typeof window !== 'undefined') {
+    sessionStorage.setItem(PENDING_INVITATION_TOKEN_KEY, normalized);
+  }
+}
+
+export function clearPendingInvitationToken(): void {
+  if (typeof window !== 'undefined') {
+    sessionStorage.removeItem(PENDING_INVITATION_TOKEN_KEY);
+  }
+}
@@ -2,6 +2,8 @@
 * WebSocket客户端类
 * 用于管理WebSocket连接和消息处理
 */
+import { getActiveWorkspaceUuid } from '@/app/infra/http/workspaceContext';
+
 export interface WebSocketMessage {
  id: number;
  role: 'user' | 'assistant';
@@ -91,7 +93,22 @@ export class WebSocketClient {
        this.ws.onopen = () => {
          this.reconnectAttempts = 0;
          this.isConnecting = false;
-          this.startHeartbeat();
+          const token = this.token || localStorage.getItem('token');
+          const workspaceUuid = getActiveWorkspaceUuid();
+          if (!token || !workspaceUuid) {
+            const error = new Error('WebSocket认证信息缺失');
+            this.onErrorCallback?.(error);
+            this.ws?.close();
+            reject(error);
+            return;
+          }
+          this.ws?.send(
+            JSON.stringify({
+              type: 'authenticate',
+              token,
+              workspace_uuid: workspaceUuid,
+            }),
+          );
        };

        // 接收消息
@@ -103,6 +120,7 @@ export class WebSocketClient {
            // 第一次连接成功
            if (data.type === 'connected' && data.connection_id) {
              this.connectionId = data.connection_id;
+              this.startHeartbeat();
              resolve(data.connection_id);
            }
          } catch (error) {