From 504480665e0007f8e3ed952d8451a1dd37a8f5aa Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:26:52 +0800 Subject: [PATCH 01/17] docs: propose the multi-user service in two stacked PRs Co-Authored-By: Claude Opus 5.5 --- docs/README.md | 1 + docs/proposals/multi-user-service.md | 145 +++++++++++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 docs/proposals/multi-user-service.md diff --git a/docs/README.md b/docs/README.md index 866d2ffbb..7a2fb305e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -102,6 +102,7 @@ docs/ | [model-role-routing.md](./proposals/model-role-routing.md) | Proposed | Model selection by runtime role. | | [move-selected-nodes-between-spaces.md](./proposals/move-selected-nodes-between-spaces.md) | Proposed | #142 selected-node and Frame-subtree moves between Spaces with bounded compensation. | | [multi-backend-storage.md](./proposals/multi-backend-storage.md) | Partly shipped | Phases 1–6: Blob and structured ports, SQLite, Postgres, Azure, async agents. | +| [multi-user-service.md](./proposals/multi-user-service.md) | Proposed | #228 follow-up: request-scoped Workspaces (PR A), then member agents, per-person credentials, grant admin and session renewal (PR B). | | [note-auto-height-stable-geometry.md](./proposals/note-auto-height-stable-geometry.md) | Proposed | Revision-aware offscreen Note measurement and stable auto-height geometry. | | [space-prompt-topology-scoping.md](./proposals/space-prompt-topology-scoping.md) | Shipped | Topology-derived global/direct-Agent targeting for Prompt Frames. | diff --git a/docs/proposals/multi-user-service.md b/docs/proposals/multi-user-service.md new file mode 100644 index 000000000..dc783d726 --- /dev/null +++ b/docs/proposals/multi-user-service.md @@ -0,0 +1,145 @@ +# Multi-User Service + +Status: Proposed +Last updated: 2026-10-28 + +Follows PR #237 (Bubble identity and per-user Space access) toward issue #228. Two stacked pull requests take one Huabu Server from "several people sign in and each edits their own Spaces in one shared Workspace" to a service several people can use day to day: each person has their own Workspaces, uses agents in them, and an operator admits people without scripts. + +Nothing changes in local mode (`HUABU_IDENTITY_PROVIDER=local`). Desktop and single-owner deployments keep one process-active Workspace, the same routes and the same UI. + +## What "ready for several users" means + +After both PRs, in Bubble mode: + +| Outcome | PR | +| ----------------------------------------------------------------------------------------------------------------------------------------- | --- | +| Each admitted person gets a personal Workspace on first sign-in and can create, rename, switch and delete Workspaces they own. | A | +| Two people work in different Workspaces at the same time. One person switching never moves another person. | A | +| Members run agents and conversations. An agent reaches only what the person who started it may reach. | B | +| Connected credentials and service leases are per person. One person's agent never uses another's GitHub token or service key. | B | +| A system owner admits members, revokes them and grants Workspace ownership from Settings. | B | +| A session that expires mid-edit is renewed without leaving the page, so unsaved edits survive. Sign-out can end the provider session too. | B | + +Out of scope for both: sharing a Workspace or Space between people beyond operator grants, quotas and billing, and Desktop as a multi-user client. + +## PR A — Request-scoped Workspaces + +### The Workspace a request runs in + +Each request runs in exactly one Workspace, resolved once in admission and carried in an `AsyncLocalStorage` context (`modules/workspace/context.ts`, new). `getWorkspaceHandle()`, `getWorkspacePath()`, `getWorkspaceKey()` and `space()` read that context. The rest of the Server's ~145 `space(canvasId)` call sites stay as they are. + +How the Workspace is chosen: + +- **Local mode:** the process-active Workspace, as today. Switching still changes it for every client, because local mode has one person. +- **Bubble mode:** the principal's _current Workspace_, a per-principal preference stored in Huabu (`principal_preferences`, referencing Bubble's `principalId`, as #228 proposes). Switching changes only that preference. It must be a Workspace the principal can read (`huabu.workspace.read`, new), else admission falls back to their personal Workspace. + +A per-principal preference rather than a Workspace header keeps images, frames, downloads and EventSource working without changes, since they cannot set headers. The cost is that one person's tabs share one current Workspace, which is also the behavior today. Per-tab Workspaces would need the Workspace in every URL and are not planned. + +Work that outlives the request (agents, memory updates, Task Runs, preprocessing, World preview reconciliation) captures the Workspace when it starts and runs inside it via `runInWorkspace(handle, fn)`. This replaces today's failure mode, where a switch mid-run either retargets the work or fails it with "inactive workspace". + +### Storage + +- **SQL namespaces per call, not per connection.** `useWorkspace()` mutates the one Postgres/SQLite connection's namespace today, so concurrent Workspaces would read each other's Spaces. The structured store reads the Workspace id from the context per query, and transactions bind it when they open. The one database-wide write order (`pg_advisory_xact_lock(WRITE_LOCK)`) stays: it also covers name allocation and the Workspace registry. A per-Workspace lock is a later throughput change. +- **Per-Workspace state.** The World id, canvas-dirs index, user-skill cache, external-note sessions and the Space-create and hierarchy chains move into a `WorkspaceRuntime` (`modules/workspace/runtime.ts`, new), created on first use per Workspace and evicted when idle. The process-wide reset hooks (`refreshCanvasDirIndex`, `invalidateUserSkill`, `resetExternalNoteSessions`) become methods on it. +- **Leases.** `acquireWorkspaceOperationLease()` counts per Workspace. It still stops a local-mode switch or a Workspace delete from stranding in-flight work, and no longer refuses a second live Workspace. +- **Blob prefixes use the Workspace id.** Azure blobs are prefixed by `getWorkspaceKey()`, which on Disk is the folder _path_, so moving a folder orphans them. This becomes the Workspace id, with a one-time copy-forward on first open. +- **Maps keyed by Space id alone** (canvas mutex, SSE listeners, memory worker, dir handles, tombstones, Agenetes turn owners) stay as they are. Space ids are random UUIDs or `createId('canvas')` and imports mint new ids. Workspace creation refuses a Disk folder whose Space ids collide with a live Workspace's. + +### Roles and capabilities + +This replaces #237's model. Huabu checks four capabilities, and the same names apply on a Workspace and on a Space: + +| Capability | Allows | +| -------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `huabu.read` | Seeing and opening the Workspace or Space, every `GET`, search, live streams. | +| `huabu.write` | Editing Spaces and creating them. From PR B, also running agents and conversations in them. | +| `huabu.manage` | Renaming and deleting it, granting roles on it. On a Workspace, also its memory, Skills and Workspace settings. | +| `huabu.admin` | System target only: deployment, Canary, folder Workspaces on the Server's filesystem, and People administration (PR B). | + +Roles: + +| Role | Granted on | Gives | +| ------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------- | +| `owner` (Bubble core) | system | `huabu.use`, `huabu.admin`. Bubble's system-owner rule also gives every capability on every Workspace and Space. | +| `member` (Bubble core) | system | `huabu.use`: admitted, and gets a personal Workspace. | +| `huabu.workspace.owner` | one Workspace | read, write, manage | +| `huabu.workspace.editor` | one Workspace | read, write | +| `huabu.workspace.viewer` | one Workspace | read | +| `huabu.space.owner` | one Space | read, write, manage on that Space and the Spaces inside it | + +- **Inheritance.** read, write and manage flow down Workspace → root Space → child Space, never up or sideways. +- **Who grants.** Granting a role on a Workspace or Space needs `huabu.manage` on it. Granting system roles needs `huabu.admin`. A member can therefore grant roles on their own Workspace. Neither PR adds a UI for that: sharing UI is a later step. +- **Admission.** Still system `member` or `owner`. A Workspace or Space grant alone does not admit anyone. +- **Space ownership on creation.** Creating a Space in a Workspace you can write claims `huabu.space.owner` on it, as in #237. This keeps a shared Space reachable by its creator if the Workspace grant is later narrowed. +- **Workspace-qualified Space targets.** `huabu.space` targets are `:`, and the parent of a root Space is its own Workspace, not "the active one". So a Space can be shared later without sharing its Workspace. +- **Migration from #237.** On first start, `huabu.space.owner` grants are rewritten to qualified targets in the Workspace that holds each Space. `huabu.workspace.owner` grants keep their meaning. A #237 grant that names no existing Space is dropped. +- **Later goal, not in these PRs.** Every request names its Workspace explicitly. Until then a request runs in its caller's current Workspace, and a Space shared from another Workspace is reached by switching to that Workspace. + +### Workspaces for members + +- **Personal Workspace.** On a member's first admitted request with no readable Workspace, Huabu creates "'s Workspace" and grants them `huabu.workspace.owner` on it, under a per-principal lock so two first requests create one. +- **Management.** `GET /api/workspaces` lists the Workspaces a caller can read. Any member may create one. Activating needs `huabu.read`; rename and delete need `huabu.manage`. Folder picking and path validation need `huabu.admin`, because they reach the Server's filesystem. On Disk storage, a member's new Workspace goes under the data directory. +- **System owner.** A system owner can reach every Workspace through Bubble's system-owner rule, and has a current Workspace like anyone else. + +### Agents in PR A + +Agents stay owner-only for members, as in #237. Each run now carries its Workspace: the reachback URL becomes `/api/rfs/w//`, and RFS runs the call in that Workspace. An owner's agent therefore keeps working when the owner switches away mid-run, instead of failing or reading the other Workspace. + +### Web + +- Boot no longer activates `registered[0]` in Bubble mode: the Server has already chosen the caller's current Workspace. +- The switcher lists the caller's Workspaces and is enabled for members. Switching posts to `/api/workspaces/:id/activate`, which in Bubble mode sets only the caller's preference. +- The Home folder name and `GET /api/workspace` path are withheld from members, closing a #237 limitation. + +### Proof + +The Postgres suite runs two principals in two Workspaces concurrently: creates, edits, SSE, search and uploads, with no cross-reads and no transaction aborts. It also checks that a switch in one browser leaves the other unchanged, that an owner's agent keeps its Workspace across the owner's switch, that #237 grants migrate, that a viewer cannot write and an editor cannot rename or delete, that personal Workspaces are created once under concurrent first requests, and that local mode's screenshots stay pixel-identical to `main`. + +## PR B — Members use agents, and the service is administrable + +### Per-run agent credentials + +Each agent run gets its own token, minted by the Server when the run starts. It names the requesting principal, the Workspace, the root Space and the thread, and expires with the run. The Agentlet passes it as the reachback credential instead of the machine token. RFS admits it as that principal, and Space access is checked as for that person's browser requests, so an agent can read or edit only what its starter can. The machine token keeps unrestricted reach only for the Agentlet's own control surface, never for Space content. + +This reopens `/api/agent`, `/api/acp`, `/api/agent-change-review` and Interactive View actions to members. It also covers the memory worker: a member's edits drive memory updates again, running in that person's Workspace under their authority. + +### Per-person credentials + +Model configuration and LLM keys, connected credentials, service-package leases and integration configuration move from data-directory scope to per principal in Bubble mode. Each person configures their own models and keys in Settings, and an agent run resolves models from its starter's configuration. A member with no model configured sees the Agent tool explain that, not a Server error. Operator-only settings (deployment, Canary, Workspaces on the Server's filesystem) stay system-owner-only. Settings shows a member only their own configuration. + +### Grant administration + +A Settings → People panel for system owners lists principals, and admits (`member`), revokes, and grants or removes `huabu.workspace.owner`. Huabu proxies these to Bubble's grant API in-process. Revoking `huabu.use` closes that person's open streams at the next revalidation, as #237 already does for Space grants. + +### Session lifecycle + +- **Refresh.** The sign-in flow requests a refresh token (`offline_access`), the Server holds it beside the access token in the session, and it renews the access token before it expires. +- **Re-sign-in in a popup.** When renewal is impossible, a lapsed session re-signs in through a popup, keeping the page and its unsaved edits. +- **Provider logout.** Sign-out optionally ends the provider session (RP-initiated logout) when the provider advertises `end_session_endpoint`. + +### Proof + +A member runs an agent that tries to read another member's Space through RFS and is refused. Their agent edits their own Space. Two members' connected credentials stay separate. An owner admits and revokes a member from the UI, and the revoked member's open page loses access within 30 seconds. A session that expires mid-edit renews or re-signs in without losing the edit. All of it is checked against real Auth0 and Entra sign-ins, as in #237. + +## Settled decisions + +Confirmed 2026-10-28: + +1. **Current Workspace per person, not per tab.** A Workspace in every URL was rejected as a much larger web and API change for a rare need. +2. **Workspace-qualified Space grants,** with an in-place migration of #237's grants, rather than relying on unique Space ids. Space grants stay so that one Space can be shared later. #237's roles are replaced by the model above. +3. **Automatic personal Workspace on first sign-in,** rather than no Workspace until an operator grants one. +4. **Per-person model keys** in PR B, rather than every member's agents using the operator's keys. + +## Code entry points + +| File/dir | Responsibility | +| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| [`modules/workspace.ts`](../../apps/server/src/modules/workspace.ts) | Today's process-active Workspace; becomes the local-mode default and the context reader. | +| [`modules/storage/storage.ts`](../../apps/server/src/modules/storage/storage.ts) | Storage facade, `space()`, World id, `activateWorkspace`. | +| [`modules/storage/backends/postgres/database.ts`](../../apps/server/src/modules/storage/backends/postgres/database.ts) | Connection namespace (`useWorkspace`) and write lock. | +| [`modules/identity/resources.ts`](../../apps/server/src/modules/identity/resources.ts) | Space parent resolution for Bubble inheritance. | +| [`modules/identity/bubble.ts`](../../apps/server/src/modules/identity/bubble.ts) | Huabu roles, capabilities and claims. | +| [`modules/security/space-access.ts`](../../apps/server/src/modules/security/space-access.ts) | Per-request Space guard and agent refusal. | +| [`modules/agent/acp/reachback-env.ts`](../../apps/server/src/modules/agent/acp/reachback-env.ts) | Agent reachback URL and credential. | +| [`modules/workspaces.route.ts`](../../apps/server/src/modules/workspaces.route.ts) | Workspace list, create, activate. | +| [`apps/web/src/store/workspaceStore.ts`](../../apps/web/src/store/workspaceStore.ts) | Web boot and switch. | From 6094f74db0065834ce848a07f69b0561a2dd267b Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:26:52 +0800 Subject: [PATCH 02/17] feat(workspace): run each call in its own Workspace scope A request or background job can now carry the Workspace it runs in through AsyncLocalStorage. The Workspace getters, the SQL stores, the Disk folder index and the SQL World id read that scope before the process-active Workspace, and operation leases count per Workspace. Local mode never opens a scope, so it behaves as before. Co-Authored-By: Claude Opus 5.5 --- .../storage/backends/disk/canvas-dirs.ts | 84 ++++++++++---- .../storage/backends/postgres/database.ts | 26 ++++- .../storage/backends/sqlite/database.ts | 20 +++- apps/server/src/modules/storage/index.ts | 1 + apps/server/src/modules/storage/storage.ts | 44 ++++++- apps/server/src/modules/workspace.ts | 107 +++++++++++------- apps/server/src/modules/workspace/context.ts | 77 +++++++++++++ 7 files changed, 282 insertions(+), 77 deletions(-) create mode 100644 apps/server/src/modules/workspace/context.ts diff --git a/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts b/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts index bd886d2fe..a29851646 100644 --- a/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts +++ b/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts @@ -23,7 +23,7 @@ import { toSafeFilename, } from '../../../../utils/naming.js'; import { spaceHierarchyShapeError } from '../../../canvas/persistence-validation.js'; -import { getWorkspacePath } from '../../../workspace.js'; +import { getWorkspaceDirectory, getWorkspacePath } from '../../../workspace.js'; export interface CanvasDirEntry { id: string; @@ -42,9 +42,29 @@ export interface CanvasDirEntry { parentEntryNodeId?: string | null; } -const index = new NameIndex(); -let worldEntry: CanvasDirEntry | null = null; -let scanned = false; +/** One Workspace folder's index. Several are live at once in Bubble mode. */ +interface DirIndexState { + readonly index: NameIndex; + worldEntry: CanvasDirEntry | null; + scanned: boolean; +} + +const states = new Map(); + +/** The index of the Workspace this call runs in. */ +function dirState(): DirIndexState { + const workspacePath = getWorkspacePath(); + let state = states.get(workspacePath); + if (!state) { + state = { + index: new NameIndex(), + worldEntry: null, + scanned: false, + }; + states.set(workspacePath, state); + } + return state; +} function readCanvasDirEntry( fullPath: string, @@ -103,11 +123,12 @@ function readCanvasDirEntry( } function scanWorkspace(): void { - index.reset([]); - worldEntry = null; + const state = dirState(); + state.index.reset([]); + state.worldEntry = null; const ws = getWorkspacePath(); if (!existsSync(ws)) { - scanned = true; + state.scanned = true; return; } @@ -124,8 +145,12 @@ function scanWorkspace(): void { }`, ); } - worldEntry = readCanvasDirEntry(worldRoot, WORLD_CANVAS_DIR_NAME, true); - if (!worldEntry) { + state.worldEntry = readCanvasDirEntry( + worldRoot, + WORLD_CANVAS_DIR_NAME, + true, + ); + if (!state.worldEntry) { throw new Error( `World canvas is missing or malformed: ${path.join( worldRoot, @@ -160,46 +185,50 @@ function scanWorkspace(): void { ); } duplicateOf.set(canvasEntry.id, entry); - index.add(canvasEntry); + state.index.add(canvasEntry); } - if (worldEntry && index.has(worldEntry.id)) { + const worldEntry = state.worldEntry; + if (worldEntry && state.index.has(worldEntry.id)) { throw new Error( `World canvasId duplicates an ordinary Space: ${worldEntry.id}`, ); } - scanned = true; + state.scanned = true; } function ensureScanned(): void { - if (!scanned) scanWorkspace(); + if (!dirState().scanned) scanWorkspace(); } /** Force a re-scan on next access (call after migrations / imports). */ export function refreshCanvasDirIndex(): void { - scanned = false; + // Every folder rescans, not only this call's: a refresh is rare, and a + // stale index is worse than a second scan. + states.clear(); } export function canvasDirName(canvasId: string): string { ensureScanned(); - if (worldEntry?.id === canvasId) return WORLD_CANVAS_DIR_NAME; - return index.get(canvasId)?.filename ?? canvasId; + if (dirState().worldEntry?.id === canvasId) return WORLD_CANVAS_DIR_NAME; + return dirState().index.get(canvasId)?.filename ?? canvasId; } /** Ordinary user-visible Spaces only. */ export function listCanvasDirEntries(): CanvasDirEntry[] { ensureScanned(); - return index.list(); + return dirState().index.list(); } /** Every executable Canvas scope, including the hidden World. */ export function listAllCanvasDirEntries(): CanvasDirEntry[] { ensureScanned(); + const { index, worldEntry } = dirState(); return worldEntry ? [...index.list(), worldEntry] : index.list(); } export function getWorldCanvasId(): string | null { ensureScanned(); - return worldEntry?.id ?? null; + return dirState().worldEntry?.id ?? null; } export function requireWorldCanvasId(): string { @@ -212,7 +241,7 @@ export function requireWorldCanvasId(): string { export function isWorldCanvasId(canvasId: string): boolean { ensureScanned(); - return worldEntry?.id === canvasId; + return dirState().worldEntry?.id === canvasId; } /** @@ -226,7 +255,9 @@ export function suggestCanvasDir( ensureScanned(); const base = toSafeFilename(title, fallback); return dedupeName(base, [ - ...index.list().map((entry) => entry.filename), + ...dirState() + .index.list() + .map((entry) => entry.filename), WORLD_CANVAS_DIR_NAME, ]); } @@ -237,7 +268,7 @@ export function registerCanvasDir( title: string | null, ): NameIndexResult { ensureScanned(); - return index.add({ id: canvasId, filename: dirName, title }); + return dirState().index.add({ id: canvasId, filename: dirName, title }); } export function patchCanvasDirTitle( @@ -245,12 +276,12 @@ export function patchCanvasDirTitle( title: string | null, ): void { ensureScanned(); - index.patch(canvasId, { title }); + dirState().index.patch(canvasId, { title }); } export function unregisterCanvasDir(canvasId: string): void { ensureScanned(); - index.remove(canvasId); + dirState().index.remove(canvasId); } /** Result of a strict on-disk rename. */ @@ -299,6 +330,7 @@ export function renameCanvasDirOnDisk( newDirName: string, ): CanvasDirRenameResult { ensureScanned(); + const { index, worldEntry } = dirState(); const entry = index.get(canvasId); if (!entry) return { ok: false, reason: 'not-found' }; @@ -306,7 +338,11 @@ export function renameCanvasDirOnDisk( worldEntry && normalizeForCompare(worldEntry.filename) === normalizeForCompare(newDirName) ) { - return { ok: false, reason: 'conflict', conflictWith: worldEntry.filename }; + return { + ok: false, + reason: 'conflict', + conflictWith: worldEntry.filename, + }; } if (normalizeForCompare(entry.filename) === normalizeForCompare(newDirName)) { diff --git a/apps/server/src/modules/storage/backends/postgres/database.ts b/apps/server/src/modules/storage/backends/postgres/database.ts index 2e85fef1e..cdf38b8e2 100644 --- a/apps/server/src/modules/storage/backends/postgres/database.ts +++ b/apps/server/src/modules/storage/backends/postgres/database.ts @@ -2,6 +2,7 @@ // Licensed under the MIT license. import { Pool, type PoolClient, type PoolConfig } from 'pg'; +import { currentWorkspaceScope } from '../../../workspace/context.js'; import { POSTGRES_MIGRATIONS } from './schema.js'; import { createKeyedMutex } from '../../../../utils/keyed-mutex.js'; @@ -180,14 +181,27 @@ export class PostgresStoreContext { useWorkspace(workspaceId: string | null): void { this.#workspaceId = workspaceId; } - activeWorkspaceId(): string | null { + + /** + * The Workspace this call runs in: its request's or background work's own + * scope where one is open, else the process-active one set by + * {@link useWorkspace}. Concurrent calls in different Workspaces therefore + * never read each other's rows through the one shared connection. + */ + #currentWorkspaceId(): string | null { + const scope = currentWorkspaceScope(); + if (scope !== undefined) return scope?.handle.workspaceId ?? null; return this.#workspaceId; } + activeWorkspaceId(): string | null { + return this.#currentWorkspaceId(); + } workspaceId(): string { this.assertOpen(); - if (!this.#workspaceId) + const workspaceId = this.#currentWorkspaceId(); + if (!workspaceId) throw new Error('No Workspace is active on the Postgres backend'); - return this.#workspaceId; + return workspaceId; } assertBoundWorkspace(bound: string, what: string): string { if (this.workspaceId() !== bound) @@ -220,10 +234,10 @@ export class PostgresStoreContext { /** Never hold a SQL transaction while composition performs blob I/O. */ transaction(operation: (database: PgExecutor) => Promise): Promise { this.assertOpen(); - const bound = this.#workspaceId; + const bound = this.#currentWorkspaceId(); const result = serializeTransactions(this.#admissionScope, async () => { this.assertOpen(); - if (bound !== this.#workspaceId) + if (bound !== this.#currentWorkspaceId()) throw new Error('Postgres operation belongs to an inactive Workspace'); const client = await this.#pool.connect(); // pg-pool drops its own idle listener while a client is checked out and @@ -238,7 +252,7 @@ export class PostgresStoreContext { await client.query('BEGIN'); await client.query("SET LOCAL lock_timeout = '5s'"); await client.query('SELECT pg_advisory_xact_lock($1)', [WRITE_LOCK]); - if (bound !== this.#workspaceId) + if (bound !== this.#currentWorkspaceId()) throw new Error( 'Postgres operation belongs to an inactive Workspace', ); diff --git a/apps/server/src/modules/storage/backends/sqlite/database.ts b/apps/server/src/modules/storage/backends/sqlite/database.ts index 5740be4b4..106d504f8 100644 --- a/apps/server/src/modules/storage/backends/sqlite/database.ts +++ b/apps/server/src/modules/storage/backends/sqlite/database.ts @@ -20,6 +20,7 @@ import { mkdirSync } from 'node:fs'; import path from 'node:path'; import { DatabaseSync } from 'node:sqlite'; +import { currentWorkspaceScope } from '../../../workspace/context.js'; import { SQLITE_MIGRATIONS, type SqliteMigration } from './schema.js'; import { getDataDir } from '../../../../data-dir.js'; @@ -236,21 +237,34 @@ export class SqliteStoreContext { this.#workspaceId = workspaceId; } + /** + * The Workspace this call runs in: its request's or background work's own + * scope where one is open, else the process-active one set by + * {@link useWorkspace}. Concurrent calls in different Workspaces therefore + * never read each other's rows through the one shared connection. + */ + #currentWorkspaceId(): string | null { + const scope = currentWorkspaceScope(); + if (scope !== undefined) return scope?.handle.workspaceId ?? null; + return this.#workspaceId; + } + /** The active Workspace id, or `null` when none has been selected. */ activeWorkspaceId(): string | null { - return this.#workspaceId; + return this.#currentWorkspaceId(); } /** The active Workspace id, or a refusal when none has been selected. */ workspaceId(): string { this.assertOpen(); - if (this.#workspaceId === null) { + const workspaceId = this.#currentWorkspaceId(); + if (workspaceId === null) { throw new SqliteWorkspaceScopeError( 'No Workspace is active on the SQLite backend. Activate one before ' + 'reading or writing Spaces.', ); } - return this.#workspaceId; + return workspaceId; } /** diff --git a/apps/server/src/modules/storage/index.ts b/apps/server/src/modules/storage/index.ts index 7e6cd62b2..00f4960a6 100644 --- a/apps/server/src/modules/storage/index.ts +++ b/apps/server/src/modules/storage/index.ts @@ -79,6 +79,7 @@ export type { export { activateWorkspace, + openWorkspace, adoptWorkspaceDirectory, closeStorage, composeStorage, diff --git a/apps/server/src/modules/storage/storage.ts b/apps/server/src/modules/storage/storage.ts index a959477ed..f91f3f876 100644 --- a/apps/server/src/modules/storage/storage.ts +++ b/apps/server/src/modules/storage/storage.ts @@ -67,7 +67,9 @@ import { type StorageProfile, } from './profile.js'; import { withSpacePutAdmission } from './space-lifecycle-admission.js'; +import { runInWorkspace } from '../workspace/context.js'; +import type { WorkspaceScope } from '../workspace/context.js'; import type { DiskSpaceImport } from './backends/disk/space-import.js'; import type { DiskSpaceTree } from './backends/disk/space-tree.js'; import type { SqliteSpaceSubstrate } from './backends/sqlite/space-extension.js'; @@ -370,7 +372,9 @@ let current: Storage | null = null; let workspaces: WorkspaceRepository | null = null; let sqlite: SqliteStoreContext | null = null; let postgres: PostgresStoreContext | null = null; -let activeWorldCanvasId: string | null = null; +// World ids per Workspace for backends without folders. Several Workspaces +// are open at once in Bubble mode, each with its own World. +const worldCanvasIds = new Map(); let spaceCreateTail: Promise = Promise.resolve(); /** @@ -699,7 +703,7 @@ export async function activateWorkspace( commitWorkspaceIdentity(workspace); if (sqlite) sqlite.useWorkspace(workspace.workspaceId); if (postgres) postgres.useWorkspace(workspace.workspaceId); - activeWorldCanvasId = null; + worldCanvasIds.delete(workspace.workspaceId); if ( workspaces instanceof SqliteWorkspaceRepository || workspaces instanceof PostgresWorkspaceRepository @@ -709,7 +713,35 @@ export async function activateWorkspace( // A Workspace with no World has no Portal target and no home view. On Disk // the World is written by workspace preparation; here the same step belongs // to activation, because activation is the whole of "open a Workspace". - activeWorldCanvasId = await ensure().structured.spaces().ensureWorld(); + worldCanvasIds.set( + workspace.workspaceId, + await ensure().structured.spaces().ensureWorld(), + ); +} + +/** + * Open a Workspace for the calls that run in it, without making it the + * process-active one. + * + * The scoped counterpart to {@link activateWorkspace}, for Bubble mode, where + * each request runs in its caller's Workspace. On Disk the folder is adopted + * and indexed on first use; elsewhere the World is ensured once per Workspace. + * Idempotent and cheap after the first call. + */ +export async function openWorkspace( + workspace: WorkspaceHandle, +): Promise { + const workspacePath = workspaceDirectory(workspace.workspaceId); + if (materializesWorkspaces() && !workspacePath) + throw new Error(`Workspace "${workspace.workspaceId}" has no folder`); + const scope: WorkspaceScope = { handle: workspace, path: workspacePath }; + if (!workspacePath && !worldCanvasIds.has(workspace.workspaceId)) { + const world = await runInWorkspace(scope, () => + ensure().structured.spaces().ensureWorld(), + ); + worldCanvasIds.set(workspace.workspaceId, world); + } + return scope; } /** @@ -722,7 +754,9 @@ export async function activateWorkspace( * it is synchronous in call sites that cannot await. */ export function getWorldCanvasId(): string | null { - return materializesWorkspaces() ? diskWorldCanvasId() : activeWorldCanvasId; + if (materializesWorkspaces()) return diskWorldCanvasId(); + const workspaceId = getWorkspaceHandle()?.workspaceId; + return workspaceId ? (worldCanvasIds.get(workspaceId) ?? null) : null; } export function requireWorldCanvasId(): string { @@ -762,7 +796,7 @@ export async function closeStorage(): Promise { workspaces = null; sqlite = null; postgres = null; - activeWorldCanvasId = null; + worldCanvasIds.clear(); try { if (storage) { const results = await Promise.allSettled([ diff --git a/apps/server/src/modules/workspace.ts b/apps/server/src/modules/workspace.ts index 4f2f9bbeb..3fd13a8b6 100644 --- a/apps/server/src/modules/workspace.ts +++ b/apps/server/src/modules/workspace.ts @@ -46,6 +46,7 @@ import { adoptWorkspaceDirectory, materializesWorkspaces, } from './storage/index.js'; +import { currentWorkspaceScope } from './workspace/context.js'; import { prepareWorkspaceOnDisk } from './workspace-prepare.js'; import { invalidateUserSkill } from '../prompt/index.js'; @@ -60,8 +61,9 @@ const ENV_KEY = 'HUABU_WORKSPACE'; let _workspaceHandle: WorkspaceHandle | null = null; let _workspacePath: string | null = null; let _managed = false; -let _leasedWorkspaceKey: string | null = null; -let _workspaceOperationLeaseCount = 0; +// Leases per Workspace key. Several Workspaces can be live at once in Bubble +// mode, each with its own in-flight work. +const _workspaceOperationLeases = new Map(); let _activatingWorkspacePath: string | null = null; /** @@ -114,7 +116,7 @@ export function isManagedMode(): boolean { } export function isWorkspaceConfigured(): boolean { - return _workspaceHandle !== null; + return getWorkspaceHandle() !== null; } /** @@ -160,14 +162,15 @@ export function initWorkspaceFromEnv(): void { * Throws if no workspace has been activated yet. */ export function getWorkspacePath(): string { - if (!_workspacePath) { + const workspacePath = getWorkspaceDirectory(); + if (!workspacePath) { throw new Error( 'Workspace path has not been configured. ' + 'Activate a workspace first (PUT /api/workspace) or set ' + `${ENV_KEY} in the environment.`, ); } - return _workspacePath; + return workspacePath; } /** @@ -178,6 +181,8 @@ export function getWorkspacePath(): string { * a directory should keep calling {@link getWorkspacePath} and let it refuse. */ export function getWorkspaceDirectory(): string | null { + const scope = currentWorkspaceScope(); + if (scope !== undefined) return scope?.path ?? null; return _workspacePath; } @@ -190,45 +195,63 @@ export function getWorkspaceDirectory(): string | null { * is the Workspace identity. */ export function getWorkspaceKey(): string { - if (_workspacePath) return _workspacePath; - if (_workspaceHandle) return `workspace:${_workspaceHandle.workspaceId}`; + const workspacePath = getWorkspaceDirectory(); + if (workspacePath) return workspacePath; + const handle = getWorkspaceHandle(); + if (handle) return `workspace:${handle.workspaceId}`; throw new Error( 'Workspace has not been configured. Activate a workspace first ' + `(PUT /api/workspace) or set ${ENV_KEY} in the environment.`, ); } -/** The active immutable Workspace identity, or null before configuration. */ +/** + * The immutable identity of the Workspace this call runs in: the request's + * own in Bubble mode, else the process-active one. `null` before + * configuration. + */ export function getWorkspaceHandle(): WorkspaceHandle | null { + const scope = currentWorkspaceScope(); + if (scope !== undefined) return scope?.handle ?? null; + return _workspaceHandle; +} + +/** The process-active Workspace, whatever Workspace this call runs in. */ +export function getProcessWorkspaceHandle(): WorkspaceHandle | null { return _workspaceHandle; } +/** The process-active Workspace's directory, or `null`. */ +export function getProcessWorkspaceDirectory(): string | null { + return _workspacePath; +} + /** - * Keep the currently-active workspace stable for an async operation. + * Keep the Workspace this call runs in stable for an async operation. * - * Multiple operations may hold leases concurrently. Switching to another - * workspace is rejected until every lease has been released; recommitting the - * same Workspace remains allowed. + * Multiple operations may hold leases concurrently, on one Workspace or + * several. Switching the process-active Workspace away from a leased one is + * rejected until its leases are released; recommitting the same Workspace + * remains allowed. */ export function acquireWorkspaceOperationLease(): WorkspaceOperationLease { const workspaceKey = getWorkspaceKey(); + const processKey = processWorkspaceKey(); + // A pending switch moves only the process-active Workspace, so it holds + // back new work there and nowhere else. if ( _activatingWorkspacePath !== null && + workspaceKey === processKey && _activatingWorkspacePath !== workspaceKey ) { throw new WorkspaceActivationInProgressError(); } - if ( - _workspaceOperationLeaseCount > 0 && - _leasedWorkspaceKey !== workspaceKey - ) { - throw new Error('Workspace operation lease invariant violated'); - } - - _leasedWorkspaceKey = workspaceKey; - _workspaceOperationLeaseCount += 1; + _workspaceOperationLeases.set( + workspaceKey, + (_workspaceOperationLeases.get(workspaceKey) ?? 0) + 1, + ); let released = false; return Object.freeze({ @@ -236,14 +259,24 @@ export function acquireWorkspaceOperationLease(): WorkspaceOperationLease { release(): void { if (released) return; released = true; - _workspaceOperationLeaseCount -= 1; - if (_workspaceOperationLeaseCount === 0) { - _leasedWorkspaceKey = null; - } + const remaining = (_workspaceOperationLeases.get(workspaceKey) ?? 1) - 1; + if (remaining > 0) _workspaceOperationLeases.set(workspaceKey, remaining); + else _workspaceOperationLeases.delete(workspaceKey); }, }); } +/** Whether any operation holds a lease on this Workspace key. */ +export function isWorkspaceLeased(workspaceKey: string): boolean { + return _workspaceOperationLeases.has(workspaceKey); +} + +function processWorkspaceKey(): string | null { + if (_workspacePath) return _workspacePath; + if (_workspaceHandle) return `workspace:${_workspaceHandle.workspaceId}`; + return null; +} + /** * Reserve a namespace switch before asynchronous preparation can touch it. * @@ -356,14 +389,7 @@ function commitResolvedWorkspacePath(resolvedPath: string): void { */ export function commitWorkspaceIdentity(workspace: WorkspaceHandle): void { assertNoWorkspaceActivationInProgress(); - const key = `workspace:${workspace.workspaceId}`; - if ( - _workspaceOperationLeaseCount > 0 && - _leasedWorkspaceKey !== null && - _leasedWorkspaceKey !== key - ) { - throw new WorkspaceOperationInProgressError(); - } + assertProcessWorkspaceChangeAllowed(`workspace:${workspace.workspaceId}`); _workspaceHandle = workspace; _workspacePath = null; refreshCanvasDirIndex(); @@ -375,7 +401,8 @@ export function commitWorkspaceIdentity(workspace: WorkspaceHandle): void { export function updateActiveWorkspaceHandle( workspace: WorkspaceHandle, ): boolean { - if (_workspaceHandle?.workspaceId !== workspace.workspaceId) return false; + if (getProcessWorkspaceHandle()?.workspaceId !== workspace.workspaceId) + return false; _workspaceHandle = workspace; return true; } @@ -401,11 +428,13 @@ function validateAbsolutePath(p: string): void { } function assertWorkspacePathChangeAllowed(resolvedPath: string): void { - if ( - _workspaceOperationLeaseCount > 0 && - _leasedWorkspaceKey !== null && - _leasedWorkspaceKey !== resolvedPath - ) { + assertProcessWorkspaceChangeAllowed(resolvedPath); +} + +/** Refuse to move the process-active Workspace away while work holds it. */ +function assertProcessWorkspaceChangeAllowed(nextKey: string): void { + const key = processWorkspaceKey(); + if (key !== null && key !== nextKey && isWorkspaceLeased(key)) { throw new WorkspaceOperationInProgressError(); } } diff --git a/apps/server/src/modules/workspace/context.ts b/apps/server/src/modules/workspace/context.ts new file mode 100644 index 000000000..fdf4fd18f --- /dev/null +++ b/apps/server/src/modules/workspace/context.ts @@ -0,0 +1,77 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +/** + * The Workspace one request, or one piece of background work, runs in. + * + * Local mode has one person and one process-active Workspace, and never fills + * a scope: every getter in `../workspace.ts` falls back to the process state, + * exactly as before. In Bubble mode each request runs in its caller's current + * Workspace, so two people can work in two Workspaces at once without either + * one moving the other. + * + * The scope travels with the async call chain. Work a request starts and that + * outlives it (an agent run, a memory update, a Task Run) keeps the Workspace + * it started in, even after its starter switches away. + */ + +import { AsyncLocalStorage } from 'node:async_hooks'; + +import type { WorkspaceHandle } from '../storage/index.js'; + +/** One Workspace, as the getters in `../workspace.ts` answer for it. */ +export interface WorkspaceScope { + readonly handle: WorkspaceHandle; + /** The Disk materialization, or `null` when the Workspace is a row. */ + readonly path: string | null; +} + +/** + * A request's slot, opened before identity is known and filled once. + * + * Opening comes first because only a callback-style `onRequest` hook can wrap + * the rest of Fastify's lifecycle in `run()`; choosing comes later, after + * admission has found the principal. An open slot that was never filled is a + * request with no Workspace, not a request in the process's. + */ +interface ScopeSlot { + scope: WorkspaceScope | null; +} + +const storage = new AsyncLocalStorage(); + +/** Run `fn` with an empty slot that {@link fillWorkspaceScope} may fill. */ +export function openWorkspaceScope(fn: () => T): T { + return storage.run({ scope: null }, fn); +} + +/** + * Choose the Workspace for the request this call runs inside. + * + * Refuses a second choice: a request reads one Workspace from start to finish, + * so a handler can never act in a different one from the one authorized. + */ +export function fillWorkspaceScope(scope: WorkspaceScope): void { + const slot = storage.getStore(); + if (!slot) throw new Error('No Workspace scope is open for this call'); + if (slot.scope && slot.scope.handle.workspaceId !== scope.handle.workspaceId) + throw new Error('This request already runs in another Workspace'); + slot.scope = scope; +} + +/** Run `fn`, and everything it starts, in one Workspace. */ +export function runInWorkspace(scope: WorkspaceScope, fn: () => T): T { + return storage.run({ scope }, fn); +} + +/** + * The scope this call runs in. + * + * `undefined` when no slot is open (local mode, startup, process work), so the + * caller uses the process-active Workspace. `null` when a slot is open but + * nothing was chosen, which is a request with no Workspace. + */ +export function currentWorkspaceScope(): WorkspaceScope | null | undefined { + const slot = storage.getStore(); + return slot ? slot.scope : undefined; +} From adc4fc01c394885c9f881f97418dfd72507e3669 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:26:52 +0800 Subject: [PATCH 03/17] feat(identity): per-person current Workspace and a new role model Bubble mode selects each admitted request's Workspace from the caller's stored current Workspace, creating a personal one for a new member. Roles become Workspace owner/editor/viewer plus Space owner, with read/write/manage flowing down Workspace -> Space -> child Space and huabu.admin on the system. Space grants name their Workspace (:); #237's grants are rewritten at startup. Co-Authored-By: Claude Opus 5.5 --- .../agent/memory/op-counter-hook.test.ts | 6 +- .../src/modules/artifact/send-blob.test.ts | 16 +- .../canvas/member-spaces.route.test.ts | 8 +- .../canvas/preprocess-access.route.test.ts | 1 + .../modules/canvas/space-hierarchy.test.ts | 1 + .../src/modules/identity/bubble.test.ts | 332 +++++++++++++----- apps/server/src/modules/identity/bubble.ts | 201 +++++++++-- apps/server/src/modules/identity/http.ts | 17 + apps/server/src/modules/identity/index.ts | 9 + .../src/modules/identity/preferences.ts | 71 ++++ apps/server/src/modules/identity/resources.ts | 52 ++- apps/server/src/modules/identity/service.ts | 48 ++- .../modules/identity/workspace-selection.ts | 109 ++++++ .../src/modules/security/space-access.test.ts | 1 + .../src/modules/workspace-activation.ts | 30 ++ .../src/modules/workspace.route.test.ts | 1 + 16 files changed, 771 insertions(+), 132 deletions(-) create mode 100644 apps/server/src/modules/identity/preferences.ts create mode 100644 apps/server/src/modules/identity/workspace-selection.ts diff --git a/apps/server/src/modules/agent/memory/op-counter-hook.test.ts b/apps/server/src/modules/agent/memory/op-counter-hook.test.ts index e1a6bc55a..f4ab3e19f 100644 --- a/apps/server/src/modules/agent/memory/op-counter-hook.test.ts +++ b/apps/server/src/modules/agent/memory/op-counter-hook.test.ts @@ -34,7 +34,11 @@ app.addHook('onRequest', async (request) => { principal: { principalId: 'carol', kind: 'user' }, member: true, owner: false, - access: { can: async () => true, claim: async () => {} }, + access: { + can: async () => true, + claim: async () => {}, + workspaces: async () => 'all' as const, + }, }); }); registerOpCounterHook(app); diff --git a/apps/server/src/modules/artifact/send-blob.test.ts b/apps/server/src/modules/artifact/send-blob.test.ts index 354ede104..d6c88df54 100644 --- a/apps/server/src/modules/artifact/send-blob.test.ts +++ b/apps/server/src/modules/artifact/send-blob.test.ts @@ -297,7 +297,11 @@ describe('sendBlob under per-Space access', () => { 'public, max-age=0', ]); expect( - await cache({ can: async () => true, claim: async () => {} }), + await cache({ + can: async () => true, + claim: async () => {}, + workspaces: async () => 'all' as const, + }), ).toEqual(['private, no-cache', 304, 'private, no-cache']); }); @@ -340,8 +344,12 @@ describe('sendBlob under per-Space access', () => { // Bubble mode, even for a system owner; a route's own policy stays // enforced beside the sandbox. const sandbox = 'sandbox allow-scripts allow-forms allow-popups'; - expect(await csp({ can: async () => true, claim: async () => {} })).toEqual( - [sandbox, ["connect-src 'none'", sandbox]], - ); + expect( + await csp({ + can: async () => true, + claim: async () => {}, + workspaces: async () => 'all' as const, + }), + ).toEqual([sandbox, ["connect-src 'none'", sandbox]]); }); }); diff --git a/apps/server/src/modules/canvas/member-spaces.route.test.ts b/apps/server/src/modules/canvas/member-spaces.route.test.ts index 2572cfb4d..f328eec68 100644 --- a/apps/server/src/modules/canvas/member-spaces.route.test.ts +++ b/apps/server/src/modules/canvas/member-spaces.route.test.ts @@ -52,6 +52,7 @@ describe('a member’s Spaces', () => { const app = await host({ can: async (_level, { id }) => id === child.canvasId, claim: async () => {}, + workspaces: async () => 'all' as const, }); const listed = (await app.inject('/canvas')).json().canvases; await app.close(); @@ -77,7 +78,11 @@ describe('a member’s Spaces', () => { principal: { principalId: 'carol', kind: 'user' }, member: true, owner, - access: { can: async () => true, claim: async () => {} }, + access: { + can: async () => true, + claim: async () => {}, + workspaces: async () => 'all' as const, + }, }); }); await app.register(canvasRoutes, { prefix: '/canvas' }); @@ -115,6 +120,7 @@ describe('a member’s Spaces', () => { claim: async () => { throw new Error('grant store unavailable'); }, + workspaces: async () => 'all', }); const response = await app.inject({ method: 'POST', diff --git a/apps/server/src/modules/canvas/preprocess-access.route.test.ts b/apps/server/src/modules/canvas/preprocess-access.route.test.ts index 4e1f8841a..dcca8c9e0 100644 --- a/apps/server/src/modules/canvas/preprocess-access.route.test.ts +++ b/apps/server/src/modules/canvas/preprocess-access.route.test.ts @@ -70,6 +70,7 @@ const carol = (owner: boolean): ResolvedIdentity => ({ access: { can: async (_level, { id }) => id === 'mine', claim: async () => {}, + workspaces: async () => 'all' as const, }, }); diff --git a/apps/server/src/modules/canvas/space-hierarchy.test.ts b/apps/server/src/modules/canvas/space-hierarchy.test.ts index acbcb6a54..93992ab9f 100644 --- a/apps/server/src/modules/canvas/space-hierarchy.test.ts +++ b/apps/server/src/modules/canvas/space-hierarchy.test.ts @@ -878,6 +878,7 @@ describe('Space ownership', () => { ); if (failClaim) throw new Error('grant store unavailable'); }, + workspaces: async () => 'all', }, }); }); diff --git a/apps/server/src/modules/identity/bubble.test.ts b/apps/server/src/modules/identity/bubble.test.ts index 5b4602dc9..62f0ef333 100644 --- a/apps/server/src/modules/identity/bubble.test.ts +++ b/apps/server/src/modules/identity/bubble.test.ts @@ -7,10 +7,12 @@ import { InMemoryBubbleStore } from '@octostaff/bubble'; import Fastify from 'fastify'; import { afterEach, describe, expect, it } from 'vitest'; -import { openBubbleIdentity } from './bubble.js'; +import { migrateSpaceGrants, openBubbleIdentity } from './bubble.js'; import { registerIdentity } from './http.js'; +import { createMemoryWorkspacePreferences } from './preferences.js'; import { getRequestIdentity } from './request.js'; import { isOwnerRequest } from '../security/owner.js'; +import { getWorkspaceHandle } from '../workspace.js'; import { registerSpaceAccess } from '../security/space-access.js'; import type { HuabuResource, ResourceDirectory } from './service.js'; @@ -60,17 +62,43 @@ async function revokeAll( await store.grants.remove(row.grantId); } -/** Workspace `w1` holds Spaces `a` and `b`, `a` holds `a1`; `w2` holds `c`. */ -const PARENTS: Record = { - a: { type: 'workspace', id: 'w1' }, - a1: { type: 'space', id: 'a' }, - b: { type: 'workspace', id: 'w1' }, - c: { type: 'workspace', id: 'w2' }, -}; -const RESOURCES: ResourceDirectory = { - workspaceExists: async (id) => id === 'w1' || id === 'w2', - spaceParent: async (id) => PARENTS[id] ?? null, +/** + * Workspace `w1` holds Spaces `a` and `b`, `a` holds `a1`; `w2` holds `c`. + * Workspaces made at runtime hold nothing. + */ +const PARENTS: Record> = { + w1: { + a: { type: 'workspace', id: 'w1' }, + a1: { type: 'space', id: 'a' }, + b: { type: 'workspace', id: 'w1' }, + }, + w2: { c: { type: 'workspace', id: 'w2' } }, }; +const scopeOf = (workspaceId: string) => ({ + handle: { workspaceId, name: workspaceId }, + path: null, +}); +function directory(): ResourceDirectory & { created: string[] } { + const created: string[] = []; + const exists = (id: string) => id in PARENTS || created.includes(id); + return { + created, + workspaceExists: async (id) => exists(id), + spaceParent: async (workspaceId, id) => PARENTS[workspaceId]?.[id] ?? null, + workspaceOfSpace: async (id) => + Object.keys(PARENTS).find((w) => id in PARENTS[w]) ?? null, + openWorkspace: async (id) => (exists(id) ? scopeOf(id) : null), + defaultWorkspace: async () => scopeOf('w1'), + createWorkspace: async (name) => { + created.push(`made-${created.length + 1}`); + return { + ...scopeOf(created.at(-1)!), + handle: { workspaceId: created.at(-1)!, name }, + }; + }, + }; +} +const RESOURCES = directory(); const servers: FastifyInstance[] = []; afterEach(async () => { @@ -84,19 +112,22 @@ async function host( owner?: string; revalidationIntervalMs?: number; secureOrigin?: boolean; + store?: BubbleStore; } = {}, ) { - const store = new InMemoryBubbleStore(); + const store = options.store ?? new InMemoryBubbleStore(); const lookups: string[] = []; + const resources = directory(); const bubble = await openBubbleIdentity({ authenticator: options.authenticator ?? AUTHENTICATORS, owner: 'owner' in options ? options.owner : 'admin', store, + preferences: createMemoryWorkspacePreferences(), resources: { - ...RESOURCES, - spaceParent: async (id) => { - lookups.push(id); - return RESOURCES.spaceParent(id); + ...resources, + spaceParent: async (workspaceId, id) => { + lookups.push(`${workspaceId}:${id}`); + return resources.spaceParent(workspaceId, id); }, }, }); @@ -112,25 +143,43 @@ async function host( registerSpaceAccess(app); app.get('/', { config: { identity: 'shell' } }, async () => 'shell'); app.get('/api/data', async () => ({ private: true })); - // Answers what the caller may do with each Space, and claims one on POST. + app.get('/api/workspace', async () => ({ + workspaceId: getWorkspaceHandle()?.workspaceId ?? null, + })); + app.post<{ Params: { id: string } }>( + '/api/choose/:id', + async (request, reply) => + (await bubble.service.chooseWorkspace!( + getRequestIdentity(request)!, + request.params.id, + )) + ? {} + : reply.code(403).send({}), + ); + // Answers what the caller may do with each Space of the Workspace the + // request runs in, and with that Workspace; claims a Space on POST. app.get('/api/access', async (request) => { const { access } = getRequestIdentity(request)!; - const levels = async (id: string) => + const levels = async (resource: HuabuResource) => ( await Promise.all( - (['read', 'write'] as const).map(async (level) => - (await access.can(level, { type: 'space', id })) ? level : '', + (['read', 'write', 'manage'] as const).map(async (level) => + (await access.can(level, resource)) ? level[0] : '', ), ) ).join(''); - return Object.fromEntries( - await Promise.all( - ['a', 'a1', 'b', 'c', 'missing'].map(async (id) => [ - id, - await levels(id), - ]), + const workspaceId = getWorkspaceHandle()?.workspaceId ?? ''; + return { + workspace: await levels({ type: 'workspace', id: workspaceId }), + ...Object.fromEntries( + await Promise.all( + ['a', 'a1', 'b', 'c', 'missing'].map(async (id) => [ + id, + await levels({ type: 'space', id }), + ]), + ), ), - ); + }; }); app.post<{ Params: { id: string } }>('/api/claim/:id', async (request) => { await getRequestIdentity(request)!.access.claim({ @@ -149,7 +198,7 @@ async function host( }; app.get('/api/events', events); app.get('/api/canvas/:canvasId/events', events); - return { app, store, lookups }; + return { app, store, lookups, resources }; } /** Whether a WebSocket on `path` opens and, when asked, carries a clean reply. */ @@ -374,7 +423,7 @@ describe('Bubble identity', () => { const { app, store } = await host({ revalidationIntervalMs: 20 }); const origin = await app.listen({ port: 0, host: '127.0.0.1' }); await grant(store, 'carol', 'member'); - const space = { type: 'huabu.space', id: 'b' } as const; + const space = { type: 'huabu.space', id: 'w1:b' } as const; await grant(store, 'carol', 'huabu.space.owner', space); const response = await fetch(`${origin}/api/canvas/b/events`, { headers: as('carol'), @@ -394,8 +443,8 @@ describe('Bubble identity', () => { it('answers every check in a request from one policy scope', async () => { const { app, lookups } = await host(); await app.inject({ url: '/api/access', headers: MASTER }); - // Ten questions about five Spaces, each Space resolved once. - expect(lookups.filter((id) => id === 'a')).toHaveLength(1); + // Eighteen questions, each Space resolved once. + expect(lookups.filter((id) => id === 'w1:a')).toHaveLength(1); }); it('serves the application shell to a browser that has not signed in', async () => { @@ -405,75 +454,199 @@ describe('Bubble identity', () => { expect((await app.inject('/api/data')).statusCode).toBe(401); }); - it('lets a member reach only the Spaces they own, and a Workspace owner every Space in it', async () => { + it('gives a new member one personal Workspace they own, however many first requests race', async () => { + const { app, store, resources } = await host(); + await grant(store, 'carol', 'member'); + const workspaces = await Promise.all( + Array.from({ length: 5 }, async () => + ( + await app.inject({ url: '/api/workspace', headers: as('carol') }) + ).json(), + ), + ); + expect(resources.created).toEqual(['made-1']); + expect(new Set(workspaces.map((w) => w.workspaceId))).toEqual( + new Set(['made-1']), + ); + const access = await app.inject({ + url: '/api/access', + headers: as('carol'), + }); + expect(access.json()).toMatchObject({ workspace: 'rwm', a: '', c: '' }); + + // A login without `member` gets no Workspace at all. + await app.inject({ url: '/api/identity', headers: as('erin') }); + expect(resources.created).toEqual(['made-1']); + }); + + it('gives each Workspace role its capabilities on every Space inside', async () => { const { app, store } = await host(); + const w1 = { type: 'huabu.workspace', id: 'w1' } as const; + const roles = { + olive: 'huabu.workspace.owner', + eddie: 'huabu.workspace.editor', + vera: 'huabu.workspace.viewer', + } as const; + for (const [principalId, role] of Object.entries(roles)) { + await grant(store, principalId, 'member'); + await grant(store, principalId, role, w1); + } const access = async (principalId: string) => ( await app.inject({ url: '/api/access', headers: as(principalId) }) ).json(); - for (const principalId of ['carol', 'dave']) - await grant(store, principalId, 'member'); - const none = { a: '', a1: '', b: '', c: '', missing: '' }; - expect(await access('carol')).toEqual(none); - - // Creating a Space makes its creator the owner of it and the Spaces inside - // it, and nobody else. - const claimed = await app.inject({ - method: 'POST', - url: '/api/claim/a', - headers: as('carol'), - }); - expect(claimed.statusCode).toBe(200); - expect(await access('carol')).toEqual({ - ...none, - a: 'readwrite', - a1: 'readwrite', + const of = (level: string) => ({ + workspace: level, + a: level, + a1: level, + b: level, + c: '', + missing: '', }); - expect(await access('dave')).toEqual(none); + expect(await access('olive')).toEqual(of('rwm')); + expect(await access('eddie')).toEqual(of('rw')); + expect(await access('vera')).toEqual(of('r')); + // The system owner reaches every Space that exists. + expect(await access('admin')).toEqual(of('rwm')); + }); - // A Workspace owner reaches its Spaces, not another Workspace's. - await grant(store, 'dave', 'huabu.workspace.owner', { - type: 'huabu.workspace', - id: 'w1', + it('scopes a Space grant to the Workspace it names', async () => { + const { app, store } = await host(); + await grant(store, 'carol', 'member'); + // Owning `a` in w1 enters w1, and reaches `a` and the Spaces inside it. + await grant(store, 'carol', 'huabu.space.owner', { + type: 'huabu.space', + id: 'w1:a', + }); + const access = async () => + (await app.inject({ url: '/api/access', headers: as('carol') })).json(); + expect(await access()).toEqual({ + workspace: '', + a: 'rwm', + a1: 'rwm', + b: '', + c: '', + missing: '', }); - expect(await access('dave')).toEqual({ - ...none, - a: 'readwrite', - a1: 'readwrite', - b: 'readwrite', + // The same id in another Workspace is another Space. + await grant(store, 'dave', 'member'); + await grant(store, 'dave', 'huabu.space.owner', { + type: 'huabu.space', + id: 'w2:a', }); + expect( + ( + await app.inject({ + method: 'POST', + url: '/api/choose/w1', + headers: as('dave'), + }) + ).statusCode, + ).toBe(403); - // The system owner reaches every Space that exists. - expect(await access('admin')).toEqual({ - a: 'readwrite', - a1: 'readwrite', - b: 'readwrite', - c: 'readwrite', - missing: '', + // Creating a Space claims it in the Workspace the request runs in. + await app.inject({ + method: 'POST', + url: '/api/claim/b', + headers: as('carol'), }); + expect( + (await store.grants.list({ principalId: 'carol' })).map( + (row) => row.target, + ), + ).toContainEqual({ type: 'huabu.space', id: 'w1:b' }); }); - it('leaves granting Space ownership to system owners', async () => { + it('switches only its caller, and only into a Workspace they may enter', async () => { const { app, store } = await host(); await grant(store, 'carol', 'member'); - await app.inject({ - method: 'POST', - url: '/api/claim/a', - headers: as('carol'), + await grant(store, 'dave', 'member'); + await grant(store, 'carol', 'huabu.workspace.viewer', { + type: 'huabu.workspace', + id: 'w2', + }); + const current = async (principalId: string) => + ( + await app.inject({ url: '/api/workspace', headers: as(principalId) }) + ).json().workspaceId; + expect(await current('carol')).toBe('w2'); + expect(await current('dave')).toBe('made-1'); + const choose = (principalId: string, id: string) => + app.inject({ + method: 'POST', + url: `/api/choose/${id}`, + headers: as(principalId), + }); + expect((await choose('carol', 'w1')).statusCode).toBe(403); + expect((await choose('carol', 'made-1')).statusCode).toBe(403); + expect((await choose('admin', 'w2')).statusCode).toBe(200); + expect([await current('admin'), await current('carol')]).toEqual([ + 'w2', + 'w2', + ]); + expect((await choose('admin', 'w1')).statusCode).toBe(200); + expect([await current('admin'), await current('carol')]).toEqual([ + 'w1', + 'w2', + ]); + }); + + it('lets whoever manages a Workspace or Space share it, and nobody else', async () => { + const { app, store } = await host(); + for (const principalId of ['olive', 'eddie']) + await grant(store, principalId, 'member'); + await grant(store, 'olive', 'huabu.workspace.owner', { + type: 'huabu.workspace', + id: 'w1', + }); + await grant(store, 'eddie', 'huabu.workspace.editor', { + type: 'huabu.workspace', + id: 'w1', }); - const share = (principalId: string) => + const share = (principalId: string, target: AuthzTarget, role: string) => app.inject({ method: 'POST', url: '/bubble/v1/grants', headers: as(principalId), - payload: { - target: { type: 'huabu.space', id: 'a' }, - principalId: 'dave', - role: 'huabu.space.owner', - }, + payload: { target, principalId: 'frank', role }, + }); + const space = { type: 'huabu.space', id: 'w1:a' } as const; + const workspace = { type: 'huabu.workspace', id: 'w1' } as const; + expect((await share('eddie', space, 'huabu.space.owner')).statusCode).toBe( + 403, + ); + expect( + (await share('eddie', workspace, 'huabu.workspace.viewer')).statusCode, + ).toBe(403); + expect( + (await share('olive', space, 'huabu.space.owner')).statusCode, + ).toBeLessThan(300); + expect( + (await share('olive', workspace, 'huabu.workspace.viewer')).statusCode, + ).toBeLessThan(300); + // System roles stay the administrator's. + expect( + (await share('olive', { type: 'system' }, 'member')).statusCode, + ).toBe(403); + }); + + it("rewrites #237's Space grants to name their Workspace, once", async () => { + const store = new InMemoryBubbleStore(); + for (const id of ['a', 'c', 'gone']) + await grant(store, 'carol', 'huabu.space.owner', { + type: 'huabu.space', + id, }); - expect((await share('carol')).statusCode).toBe(403); - expect((await share('admin')).statusCode).toBeLessThan(300); + await migrateSpaceGrants(store, RESOURCES); + await migrateSpaceGrants(store, RESOURCES); + expect( + (await store.grants.list({ principalId: 'carol' })).map( + (row) => row.target, + ), + ).toEqual([ + { type: 'huabu.space', id: 'w1:a' }, + { type: 'huabu.space', id: 'w2:c' }, + ]); }); it('carries a validated Bearer credential in an HttpOnly session cookie', async () => { @@ -557,6 +730,7 @@ describe('Bubble identity', () => { openBubbleIdentity({ authenticator: [{ driver: 'no-such-driver' }] as never, store: new InMemoryBubbleStore(), + preferences: createMemoryWorkspacePreferences(), resources: RESOURCES, }), ).rejects.toThrow(); diff --git a/apps/server/src/modules/identity/bubble.ts b/apps/server/src/modules/identity/bubble.ts index b67296c55..9596cc1e9 100644 --- a/apps/server/src/modules/identity/bubble.ts +++ b/apps/server/src/modules/identity/bubble.ts @@ -18,9 +18,19 @@ import { import { identityPrincipalSchema } from '@huabu/shared'; +import { getWorkspaceHandle } from '../workspace.js'; import { IdentityError } from './service.js'; +import { + chooseRequestWorkspace, + selectRequestWorkspace, +} from './workspace-selection.js'; -import type { IdentityService, ResourceDirectory } from './service.js'; +import type { WorkspacePreferences } from './preferences.js'; +import type { + HuabuResource, + IdentityService, + ResourceDirectory, +} from './service.js'; import type { BubbleAuthzOptions, BubbleStore, @@ -30,26 +40,44 @@ import type { FastifyPluginAsync } from 'fastify'; /** * Huabu's permission model, kept in Bubble's grant table and answered by - * Bubble's policy. On Bubble's system target, a `member` may use Huabu and an - * `owner` may also manage it; a system owner also holds every Huabu capability - * on every Workspace and Space. A Workspace owner may read and write every - * Space in that Workspace; a Space owner, that Space and the Spaces inside it. - * Only a system owner grants the ownership roles, so there is no sharing - * between members. + * Bubble's policy (`docs/proposals/multi-user-service.md`, "Roles and + * capabilities"). On the system target a `member` may use Huabu and an `owner` + * may also administer the deployment; Bubble's system-owner rule gives the + * latter every capability on every Workspace and Space too. On a Workspace or + * a Space the same three capability names apply, and they flow down from a + * Workspace to its root Spaces and from a Space to the Spaces inside it. */ const USE = 'huabu.use'; -const MANAGE = 'huabu.manage'; -const READ = 'huabu.space.read'; -const WRITE = 'huabu.space.write'; -const TARGET = { workspace: 'huabu.workspace', space: 'huabu.space' } as const; -const OWNER_ROLE = { - workspace: 'huabu.workspace.owner', - space: 'huabu.space.owner', +const ADMIN = 'huabu.admin'; +const CAPABILITY = { + read: 'huabu.read', + write: 'huabu.write', + manage: 'huabu.manage', } as const; +const { read: READ, write: WRITE, manage: MANAGE } = CAPABILITY; +const TARGET = { workspace: 'huabu.workspace', space: 'huabu.space' } as const; +const SPACE_OWNER = 'huabu.space.owner'; + +/** + * A Space's Bubble target names its Workspace too, so a Space can later be + * shared on its own and two Workspaces can never share a grant by id. + */ +export function spaceTargetId(workspaceId: string, canvasId: string): string { + return `${workspaceId}:${canvasId}`; +} + +function parseSpaceTargetId( + id: string, +): { workspaceId: string; canvasId: string } | null { + const at = id.indexOf(':'); + if (at <= 0 || at === id.length - 1) return null; + return { workspaceId: id.slice(0, at), canvasId: id.slice(at + 1) }; +} function huabuAuthz(resources: ResourceDirectory): BubbleAuthzOptions { + const flowing = [READ, WRITE, MANAGE]; return { - coreRoleCapabilities: { member: [USE], owner: [USE, MANAGE] }, + coreRoleCapabilities: { member: [USE], owner: [USE, ADMIN] }, targets: { [TARGET.workspace]: { resolve: async (id) => @@ -57,32 +85,84 @@ function huabuAuthz(resources: ResourceDirectory): BubbleAuthzOptions { }, [TARGET.space]: { resolve: async (id) => { - const parent = await resources.spaceParent(id); - return parent - ? { parent: { type: TARGET[parent.type], id: parent.id } } - : null; + const target = parseSpaceTargetId(id); + if (!target) return null; + const parent = await resources.spaceParent( + target.workspaceId, + target.canvasId, + ); + if (!parent) return null; + return { + parent: + parent.type === 'space' + ? { + type: TARGET.space, + id: spaceTargetId(target.workspaceId, parent.id), + } + : { type: TARGET.workspace, id: parent.id }, + }; }, }, }, + // Granting a role on a Workspace or Space takes `huabu.manage` there, so + // an owner can share what they own; nothing here grants system roles. roles: { - [OWNER_ROLE.workspace]: { + 'huabu.workspace.owner': { + grantableOn: [TARGET.workspace], + capabilities: [READ, WRITE, MANAGE], + managementCapability: MANAGE, + }, + 'huabu.workspace.editor': { grantableOn: [TARGET.workspace], capabilities: [READ, WRITE], managementCapability: MANAGE, }, - [OWNER_ROLE.space]: { + 'huabu.workspace.viewer': { + grantableOn: [TARGET.workspace], + capabilities: [READ], + managementCapability: MANAGE, + }, + [SPACE_OWNER]: { grantableOn: [TARGET.space], - capabilities: [READ, WRITE], + capabilities: [READ, WRITE, MANAGE], managementCapability: MANAGE, }, }, inheritance: [ - { from: TARGET.workspace, to: TARGET.space, capabilities: [READ, WRITE] }, - { from: TARGET.space, to: TARGET.space, capabilities: [READ, WRITE] }, + { from: TARGET.workspace, to: TARGET.space, capabilities: flowing }, + { from: TARGET.space, to: TARGET.space, capabilities: flowing }, ], }; } +/** + * Rewrite #237's Space grants, which named a Space by id alone, to name the + * Workspace holding it. A grant on a Space no Workspace holds is dropped. + * Idempotent: qualified grants are left alone. + */ +export async function migrateSpaceGrants( + store: BubbleStore, + resources: ResourceDirectory, +): Promise { + for (const grant of await store.grants.list()) { + const { target } = grant; + if (target.type !== TARGET.space || !('id' in target)) continue; + if (parseSpaceTargetId(target.id)) continue; + const workspaceId = await resources.workspaceOfSpace(target.id); + if (workspaceId) + await store.grants.add({ + target: { + type: TARGET.space, + id: spaceTargetId(workspaceId, target.id), + }, + principalId: grant.principalId, + role: grant.role, + grantedByPrincipalId: grant.grantedByPrincipalId ?? null, + }); + await store.grants.remove(grant.grantId); + } +} + /** Bubble's records live beside Huabu's, in a schema of their own. */ export async function openBubblePostgresStore( url: string, @@ -109,9 +189,10 @@ export async function openBubbleIdentity(options: { /** Principal provisioned as Bubble system owner. */ owner?: string; store: BubbleStore; + preferences: WorkspacePreferences; resources: ResourceDirectory; }): Promise<{ service: IdentityService; plugin: FastifyPluginAsync }> { - const { store, owner } = options; + const { store, owner, preferences } = options; const runtime = await createBubbleRuntime({ store, authenticator: options.authenticator, @@ -122,6 +203,12 @@ export async function openBubbleIdentity(options: { await store.close?.(); throw error; }); + await migrateSpaceGrants(store, options.resources).catch( + async (error: unknown) => { + await store.close?.(); + throw error; + }, + ); if (owner) { // Created without an external identity, which suits master-key callers; a // federated user is granted ownership through Bubble after first login. @@ -147,6 +234,15 @@ export async function openBubbleIdentity(options: { service: { provider: 'bubble', challenge: 'Bearer realm="Huabu"', + selectWorkspace: (identity) => + selectRequestWorkspace(identity, preferences, options.resources), + chooseWorkspace: (identity, workspaceId) => + chooseRequestWorkspace( + identity, + preferences, + options.resources, + workspaceId, + ), async authenticate({ authorization, header }) { if (!authorization || !/^Bearer\s+\S+$/i.test(authorization)) return null; @@ -169,24 +265,62 @@ export async function openBubbleIdentity(options: { // One grant load and ancestry walk per request; a later request or // stream revalidation authenticates again and gets a fresh scope. const policy = runtime.policy.scoped(); + const admin = await policy.can(ADMIN, principalId, { + type: 'system', + }); + // A Space is the one of that id in the Workspace this call runs in. + const target = (resource: HuabuResource) => { + if (resource.type === 'workspace') + return { type: TARGET.workspace, id: resource.id }; + const workspaceId = getWorkspaceHandle()?.workspaceId; + return workspaceId + ? { + type: TARGET.space, + id: spaceTargetId(workspaceId, resource.id), + } + : null; + }; return { principal: identityPrincipalSchema.parse(whoami.principal), member: await policy.can(USE, principalId, { type: 'system' }), - owner: await policy.can(MANAGE, principalId, { type: 'system' }), + owner: admin, access: { - can: (level, resource) => - policy.can(level === 'read' ? READ : WRITE, principalId, { - type: TARGET[resource.type], - id: resource.id, - }), + can: async (level, resource) => { + const resolved = target(resource); + return resolved + ? policy.can(CAPABILITY[level], principalId, resolved) + : false; + }, claim: async (resource) => { + const resolved = target(resource); + if (!resolved) + throw new Error('A Space is claimed inside a Workspace'); await store.grants.add({ - target: { type: TARGET[resource.type], id: resource.id }, + target: resolved, principalId, - role: OWNER_ROLE[resource.type], + role: + resource.type === 'space' + ? SPACE_OWNER + : 'huabu.workspace.owner', grantedByPrincipalId: principalId, }); }, + // A Space shared on its own makes its Workspace enterable; what + // the caller sees there is still decided Space by Space. + workspaces: async () => { + if (admin) return 'all'; + const ids = new Set(); + for (const grant of await store.grants.list({ principalId })) { + const granted = grant.target; + if (!('id' in granted)) continue; + if (granted.type === TARGET.workspace) ids.add(granted.id); + if (granted.type === TARGET.space) { + const space = parseSpaceTargetId(granted.id); + if (space) ids.add(space.workspaceId); + } + } + return [...ids]; + }, }, }; } catch (error) { @@ -237,6 +371,7 @@ export async function openBubbleIdentity(options: { app.server.off('upgrade', forward); await runtime.stop(); await store.close?.(); + await preferences.close(); }); }, }; diff --git a/apps/server/src/modules/identity/http.ts b/apps/server/src/modules/identity/http.ts index 31f40e518..4c0018e23 100644 --- a/apps/server/src/modules/identity/http.ts +++ b/apps/server/src/modules/identity/http.ts @@ -11,6 +11,10 @@ import { import { IdentityError, UNRESTRICTED_ACCESS } from './service.js'; import { isPublicRfsSkillBootstrapRequest } from '../remote_fs/public-skill.js'; import { isLoopbackRequest } from '../security/peer.js'; +import { + fillWorkspaceScope, + openWorkspaceScope, +} from '../workspace/context.js'; import type { IdentityCredentials, IdentityService } from './service.js'; import type { IdentityResponse } from '@huabu/shared'; @@ -72,6 +76,13 @@ export function registerIdentity( app.addHook('preClose', async () => { for (const close of activeResponses) close(); }); + // In Bubble mode every request runs in its caller's own Workspace. The slot + // must wrap the rest of the lifecycle, which only a callback hook can do; + // admission fills it below once it knows who is calling. + if (service.provider === 'bubble') + app.addHook('onRequest', (_request, _reply, done) => + openWorkspaceScope(done), + ); app.addHook('onRequest', async (request, reply) => { const path = request.url.split('?', 1)[0]; const identityRoute = path === '/api/identity' || path === SESSION_PATH; @@ -160,6 +171,12 @@ export function registerIdentity( code: 'ACCESS_REQUIRED', }); } + // A member's first request, `GET /api/identity` after sign-in included, + // is also where their personal Workspace is created. + if (identity.member && service.selectWorkspace) { + const scope = await service.selectWorkspace(identity); + if (scope) fillWorkspaceScope(scope); + } if ( service.provider === 'bubble' && !reply.raw.destroyed && diff --git a/apps/server/src/modules/identity/index.ts b/apps/server/src/modules/identity/index.ts index 01cbe29f4..630f72a55 100644 --- a/apps/server/src/modules/identity/index.ts +++ b/apps/server/src/modules/identity/index.ts @@ -3,6 +3,7 @@ import { resolveIdentityConfig } from './config.js'; import { createLocalIdentityService } from './local.js'; +import { openPostgresWorkspacePreferences } from './preferences.js'; import { storageResourceDirectory } from './resources.js'; import type { IdentityService, ResourceDirectory } from './service.js'; @@ -39,6 +40,7 @@ export function createIdentity( authenticator: authenticators as BubbleAuthConfig, owner, store: await bubble.openBubblePostgresStore(postgresUrl), + preferences: await openPostgresWorkspacePreferences(postgresUrl), resources, }); } @@ -48,6 +50,13 @@ export function createIdentity( challenge: 'Bearer realm="Huabu"', authenticate: async (credentials) => (await (opening ??= open())).service.authenticate(credentials), + selectWorkspace: async (identity) => + (await (opening ??= open())).service.selectWorkspace!(identity), + chooseWorkspace: async (identity, workspaceId) => + (await (opening ??= open())).service.chooseWorkspace!( + identity, + workspaceId, + ), }, bubble: async (app, options) => (await (opening ??= open())).plugin(app, options), diff --git a/apps/server/src/modules/identity/preferences.ts b/apps/server/src/modules/identity/preferences.ts new file mode 100644 index 000000000..a41526c2a --- /dev/null +++ b/apps/server/src/modules/identity/preferences.ts @@ -0,0 +1,71 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { Pool } from 'pg'; + +/** + * Each person's current Workspace, in Bubble mode. + * + * Huabu's own record about a Bubble principal, referencing its `principalId` + * as #228 proposes, so Bubble stays the only account directory. It lives in + * the Postgres Bubble already requires, in a schema of its own, whatever + * backend holds Huabu's content. + */ +export interface WorkspacePreferences { + current(principalId: string): Promise; + select(principalId: string, workspaceId: string): Promise; + close(): Promise; +} + +const SCHEMA = 'huabu_identity'; + +export async function openPostgresWorkspacePreferences( + url: string, +): Promise { + const pool = new Pool({ connectionString: url, max: 2 }); + pool.on('error', () => {}); + try { + await pool.query(`CREATE SCHEMA IF NOT EXISTS ${SCHEMA}`); + await pool.query( + `CREATE TABLE IF NOT EXISTS ${SCHEMA}.current_workspaces ( + principal_id text PRIMARY KEY, + workspace_id text NOT NULL, + updated_at timestamptz NOT NULL DEFAULT now() + )`, + ); + } catch (error) { + await pool.end(); + throw error; + } + return { + async current(principalId) { + const { rows } = await pool.query<{ workspace_id: string }>( + `SELECT workspace_id FROM ${SCHEMA}.current_workspaces WHERE principal_id = $1`, + [principalId], + ); + return rows[0]?.workspace_id ?? null; + }, + async select(principalId, workspaceId) { + await pool.query( + `INSERT INTO ${SCHEMA}.current_workspaces (principal_id, workspace_id) + VALUES ($1, $2) + ON CONFLICT (principal_id) + DO UPDATE SET workspace_id = EXCLUDED.workspace_id, updated_at = now()`, + [principalId, workspaceId], + ); + }, + close: () => pool.end(), + }; +} + +/** For tests and single-process use without a database. */ +export function createMemoryWorkspacePreferences(): WorkspacePreferences { + const current = new Map(); + return { + current: async (principalId) => current.get(principalId) ?? null, + select: async (principalId, workspaceId) => { + current.set(principalId, workspaceId); + }, + close: async () => {}, + }; +} diff --git a/apps/server/src/modules/identity/resources.ts b/apps/server/src/modules/identity/resources.ts index 07f31d1bd..9163f09fc 100644 --- a/apps/server/src/modules/identity/resources.ts +++ b/apps/server/src/modules/identity/resources.ts @@ -1,27 +1,59 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -import { getWorkspaceRepository, space } from '../storage/index.js'; -import { getWorkspaceHandle } from '../workspace.js'; +import { + getWorkspaceRepository, + openWorkspace, + space, +} from '../storage/index.js'; +import { runInWorkspace } from '../workspace/context.js'; +import { createWorkspace } from '../workspace-activation.js'; +import { getProcessWorkspaceHandle } from '../workspace.js'; import type { ResourceDirectory } from './service.js'; /** - * Huabu storage as the identity provider sees it. Only the active Workspace's - * Spaces exist here, World included, so a Space in any other Workspace is - * denied until Workspaces are served side by side. A child Space sits under - * its parent Space, so whoever may use a Space may use the Spaces inside it. + * Huabu storage as the identity provider sees it. A Space is found in the + * Workspace its grant names, World included, whichever Workspace the caller is + * in. A child Space sits under its parent Space, so whoever may use a Space + * may use the Spaces inside it. */ export const storageResourceDirectory: ResourceDirectory = { async workspaceExists(workspaceId) { return (await getWorkspaceRepository().get(workspaceId)) !== null; }, - async spaceParent(canvasId) { - const workspaceId = getWorkspaceHandle()?.workspaceId; - const record = workspaceId ? await space(canvasId).read() : null; - if (!workspaceId || !record) return null; + async spaceParent(workspaceId, canvasId) { + const workspace = await getWorkspaceRepository().get(workspaceId); + if (!workspace) return null; + const scope = await openWorkspace(workspace); + const record = await runInWorkspace(scope, () => space(canvasId).read()); + if (!record) return null; return record.parentSpaceId ? { type: 'space', id: record.parentSpaceId } : { type: 'workspace', id: workspaceId }; }, + async workspaceOfSpace(canvasId) { + for (const workspace of await getWorkspaceRepository().list()) { + try { + const scope = await openWorkspace(workspace); + if (await runInWorkspace(scope, () => space(canvasId).read())) + return workspace.workspaceId; + } catch { + // A Workspace whose folder is gone holds nothing to find. + } + } + return null; + }, + async openWorkspace(workspaceId) { + const workspace = await getWorkspaceRepository().get(workspaceId); + return workspace ? openWorkspace(workspace) : null; + }, + async defaultWorkspace() { + const workspace = + getProcessWorkspaceHandle() ?? (await getWorkspaceRepository().list())[0]; + return workspace ? openWorkspace(workspace) : null; + }, + async createWorkspace(name) { + return openWorkspace(await createWorkspace(name)); + }, }; diff --git a/apps/server/src/modules/identity/service.ts b/apps/server/src/modules/identity/service.ts index 2a2e6fe17..30fc16a28 100644 --- a/apps/server/src/modules/identity/service.ts +++ b/apps/server/src/modules/identity/service.ts @@ -1,6 +1,7 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +import type { WorkspaceScope } from '../workspace/context.js'; import type { IdentityPrincipal, IdentityResponse } from '@huabu/shared'; /** Supplied by a trusted transport, never copied from a request body. */ @@ -15,7 +16,10 @@ export interface ResolvedIdentity { principal: IdentityPrincipal; /** May use Huabu; every owner is a member. */ member: boolean; - /** May also change settings, credentials and agent configuration. */ + /** + * Administers the deployment (`huabu.admin`): settings, credentials, agent + * configuration and folder Workspaces. Every Workspace and Space, too. + */ owner: boolean; /** What this caller may do with individual Workspaces and Spaces. */ access: ResourceAccess; @@ -27,10 +31,22 @@ export interface HuabuResource { id: string; } +/** + * A Space is named by its id alone: it is always the Space of that id in the + * Workspace the call runs in (`../workspace/context.ts`). + */ +/** `manage`: rename, delete, grant on it; for a Workspace, its memory and Skills. */ +export type AccessLevel = 'read' | 'write' | 'manage'; + export interface ResourceAccess { - can(level: 'read' | 'write', resource: HuabuResource): Promise; + can(level: AccessLevel, resource: HuabuResource): Promise; /** Make the caller the owner of a resource it has just created. */ claim(resource: HuabuResource): Promise; + /** + * The Workspaces the caller may enter, or `'all'` for a caller who may + * enter any registered one. + */ + workspaces(): Promise; } /** @@ -40,6 +56,7 @@ export interface ResourceAccess { export const UNRESTRICTED_ACCESS: ResourceAccess = { can: async () => true, claim: async () => {}, + workspaces: async () => 'all', }; /** Where Huabu's resources sit, as the provider needs to know to authorize them. */ @@ -47,9 +64,20 @@ export interface ResourceDirectory { workspaceExists(workspaceId: string): Promise; /** * The Space's parent Space, or its Workspace when it is a root; `null` when - * there is no such Space. + * there is no such Space in that Workspace. */ - spaceParent(canvasId: string): Promise; + spaceParent( + workspaceId: string, + canvasId: string, + ): Promise; + /** The Workspace holding a Space, for migrating grants that named none. */ + workspaceOfSpace(canvasId: string): Promise; + /** A registered Workspace, opened for calls to run in; `null` if none. */ + openWorkspace(workspaceId: string): Promise; + /** Where a caller who may enter any Workspace lands first. */ + defaultWorkspace(): Promise; + /** A new Workspace, wherever this backend keeps one, opened. */ + createWorkspace(name: string): Promise; } /** Resolve afresh for each request so revocation is not hidden by a host cache. */ @@ -69,6 +97,18 @@ export interface IdentityService { * keeps its loopback rule for it; without this the machine is never an owner. */ machineOwner?(loopback: boolean): boolean; + /** + * The Workspace an admitted member's request runs in: their current one. + * Present when each request runs in its caller's own Workspace (Bubble + * mode); absent when the process-active Workspace serves everyone (local + * mode). + */ + selectWorkspace?(identity: ResolvedIdentity): Promise; + /** Make a Workspace the caller's current one; `null` when refused. */ + chooseWorkspace?( + identity: ResolvedIdentity, + workspaceId: string, + ): Promise; } export class IdentityError extends Error { diff --git a/apps/server/src/modules/identity/workspace-selection.ts b/apps/server/src/modules/identity/workspace-selection.ts new file mode 100644 index 000000000..2c8d63894 --- /dev/null +++ b/apps/server/src/modules/identity/workspace-selection.ts @@ -0,0 +1,109 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import type { WorkspacePreferences } from './preferences.js'; +import type { ResolvedIdentity, ResourceDirectory } from './service.js'; +import type { WorkspaceScope } from '../workspace/context.js'; + +/** + * One personal-Workspace creation per principal, however many first requests + * race. Keyed by directory too, so separate hosts never share a creation. + */ +const provisioning = new WeakMap< + ResourceDirectory, + Map> +>(); + +/** + * The Workspace a Bubble request runs in: its caller's current one, while they + * may still enter it. Otherwise the first Workspace they may enter, which + * becomes current. A member who may enter none gets a personal Workspace that + * they own. `null` for a caller with no Workspace at all, such as an + * administrator before any exists. + */ +export async function selectRequestWorkspace( + identity: ResolvedIdentity, + preferences: WorkspacePreferences, + resources: ResourceDirectory, +): Promise { + const { principalId } = identity.principal; + const allowed = await identity.access.workspaces(); + const may = (workspaceId: string) => + allowed === 'all' || allowed.includes(workspaceId); + + const preferred = await preferences.current(principalId); + if (preferred && may(preferred)) { + const scope = await resources.openWorkspace(preferred); + if (scope) return scope; + } + + const chosen = await firstEnterable(allowed, resources); + if (chosen) { + await preferences.select(principalId, chosen.handle.workspaceId); + return chosen; + } + if (allowed === 'all') return null; + return provisionPersonalWorkspace(identity, preferences, resources); +} + +/** + * Make one Workspace its caller's current one. Refused, with nothing changed, + * for a Workspace the caller may not enter or that does not exist. + */ +export async function chooseRequestWorkspace( + identity: ResolvedIdentity, + preferences: WorkspacePreferences, + resources: ResourceDirectory, + workspaceId: string, +): Promise { + const allowed = await identity.access.workspaces(); + if (allowed !== 'all' && !allowed.includes(workspaceId)) return null; + const scope = await resources.openWorkspace(workspaceId); + if (scope) + await preferences.select(identity.principal.principalId, workspaceId); + return scope; +} + +async function firstEnterable( + allowed: readonly string[] | 'all', + resources: ResourceDirectory, +): Promise { + // An administrator lands where the Server already is, as before. + if (allowed === 'all') return resources.defaultWorkspace(); + for (const workspaceId of allowed) { + const scope = await resources.openWorkspace(workspaceId); + if (scope) return scope; + } + return null; +} + +function provisionPersonalWorkspace( + identity: ResolvedIdentity, + preferences: WorkspacePreferences, + resources: ResourceDirectory, +): Promise { + const { principalId, displayName } = identity.principal; + let pending = provisioning.get(resources); + if (!pending) provisioning.set(resources, (pending = new Map())); + const running = pending.get(principalId); + if (running) return running; + const creating = (async () => { + // A request that read this principal's grants before a racing first + // request claimed its Workspace still finds that Workspace here: the + // preference is only ever set to one the principal may enter. + const already = await preferences.current(principalId); + const existing = already ? await resources.openWorkspace(already) : null; + if (existing) return existing; + const scope = await resources.createWorkspace( + `${displayName?.trim() || principalId}'s Workspace`, + ); + await identity.access.claim({ + type: 'workspace', + id: scope.handle.workspaceId, + }); + await preferences.select(principalId, scope.handle.workspaceId); + return scope; + })().finally(() => pending.delete(principalId)); + pending.set(principalId, creating); + return creating; +} diff --git a/apps/server/src/modules/security/space-access.test.ts b/apps/server/src/modules/security/space-access.test.ts index e47461b5a..5aa6e4717 100644 --- a/apps/server/src/modules/security/space-access.test.ts +++ b/apps/server/src/modules/security/space-access.test.ts @@ -38,6 +38,7 @@ function host() { claim: async ({ id }) => { claimed.push(id); }, + workspaces: async () => 'all', }, }); }); diff --git a/apps/server/src/modules/workspace-activation.ts b/apps/server/src/modules/workspace-activation.ts index f78634902..c283e87cb 100644 --- a/apps/server/src/modules/workspace-activation.ts +++ b/apps/server/src/modules/workspace-activation.ts @@ -11,7 +11,9 @@ */ import { fork, type ChildProcess } from 'node:child_process'; +import { randomUUID } from 'node:crypto'; import { existsSync } from 'node:fs'; +import { mkdir } from 'node:fs/promises'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -21,6 +23,14 @@ import { resolveWorkspacePath, WorkspaceActivationInProgressError, } from './workspace.js'; +import { getDataDir } from '../data-dir.js'; +import { + adoptWorkspaceDirectory, + createNamedWorkspace, + getWorkspaceRepository, + materializesWorkspaces, + type WorkspaceHandle, +} from './storage/index.js'; import { getLogger } from '../utils/logger.js'; const DEFAULT_ACTIVATION_TIMEOUT_MS = 70_000; @@ -209,3 +219,23 @@ export async function activateWorkspacePath( reservation.release(); } } + +/** + * Create a Workspace by name, on any backend, without activating it. + * + * Where a Workspace is a row this is the repository's own create. On Disk it + * is a new folder under the data directory, prepared in the isolated worker + * like any other: the creator never chooses where it lives, which is what lets + * someone without access to the Server's filesystem have one. + */ +export async function createWorkspace(name: string): Promise { + if (!materializesWorkspaces()) return createNamedWorkspace(name); + const workspacePath = path.join(getDataDir(), 'workspaces', randomUUID()); + await mkdir(workspacePath, { recursive: true }); + await runWorkspacePreparation(workspacePath); + const adopted = adoptWorkspaceDirectory(workspacePath); + return ( + (await getWorkspaceRepository().rename(adopted.workspaceId, name)) ?? + adopted + ); +} diff --git a/apps/server/src/modules/workspace.route.test.ts b/apps/server/src/modules/workspace.route.test.ts index 0211a8cc8..ea4321bfc 100644 --- a/apps/server/src/modules/workspace.route.test.ts +++ b/apps/server/src/modules/workspace.route.test.ts @@ -101,6 +101,7 @@ describe('workspace Space repository integration', () => { access: { can: async () => request.headers['x-world'] === 'yes', claim: async () => {}, + workspaces: async () => 'all' as const, }, }); }); From 2c15df61a4f174e056f1e71f434d8b0608368e05 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:34:12 +0800 Subject: [PATCH 04/17] feat(security): require manage to rename or delete a Space Routes can declare spaceAccess: 'manage'; the Space delete, delete-tree and rename routes now do, so a Workspace editor can change Spaces but not remove them. Co-Authored-By: Claude Opus 5.5 --- .../server/src/modules/canvas/canvas.route.ts | 67 +++++---- .../src/modules/canvas/space-card.route.ts | 140 +++++++++--------- .../modules/canvas/space-hierarchy.route.ts | 32 ++-- apps/server/src/modules/identity/request.ts | 35 ++++- .../src/modules/security/space-access.test.ts | 20 ++- .../src/modules/security/space-access.ts | 14 +- 6 files changed, 188 insertions(+), 120 deletions(-) diff --git a/apps/server/src/modules/canvas/canvas.route.ts b/apps/server/src/modules/canvas/canvas.route.ts index 29d3d6be0..b5efbfb6f 100644 --- a/apps/server/src/modules/canvas/canvas.route.ts +++ b/apps/server/src/modules/canvas/canvas.route.ts @@ -713,38 +713,43 @@ const canvasRoutes: FastifyPluginAsync = async (fastify) => { fastify.delete<{ Params: { canvasId: string }; Reply: ApiResult; - }>('/:canvasId', async function (request, reply) { - const { canvasId } = request.params; - return withSpaceHierarchyLock(async () => { - if (isWorldCanvasId(canvasId)) { - return reply - .code(403) - .send({ message: 'World canvas cannot be deleted' }); - } - try { - const preview = deletionPreview( - await getStructuredStore().spaces().list(), - canvasId, - ); - if (preview.spaces.length > 1) - return reply.code(409).send({ - code: 'SPACE_TREE_CONFIRMATION_REQUIRED', - message: 'Confirm the complete subtree before deleting this Space', - }); - await deleteSpaceTree(canvasId, preview.token); - } catch (error) { - if (error instanceof SpaceHierarchyError) - return reply.code(error.status).send({ - code: error.code, - message: error.message, - details: error.details, - }); - throw error; - } + }>( + '/:canvasId', + { config: { spaceAccess: 'manage' } }, + async function (request, reply) { + const { canvasId } = request.params; + return withSpaceHierarchyLock(async () => { + if (isWorldCanvasId(canvasId)) { + return reply + .code(403) + .send({ message: 'World canvas cannot be deleted' }); + } + try { + const preview = deletionPreview( + await getStructuredStore().spaces().list(), + canvasId, + ); + if (preview.spaces.length > 1) + return reply.code(409).send({ + code: 'SPACE_TREE_CONFIRMATION_REQUIRED', + message: + 'Confirm the complete subtree before deleting this Space', + }); + await deleteSpaceTree(canvasId, preview.token); + } catch (error) { + if (error instanceof SpaceHierarchyError) + return reply.code(error.status).send({ + code: error.code, + message: error.message, + details: error.details, + }); + throw error; + } - return reply.send({ success: true }); - }); - }); + return reply.send({ success: true }); + }); + }, + ); // Delete a node — removes its markdown sidecar. // diff --git a/apps/server/src/modules/canvas/space-card.route.ts b/apps/server/src/modules/canvas/space-card.route.ts index cbac72fa5..67a222f32 100644 --- a/apps/server/src/modules/canvas/space-card.route.ts +++ b/apps/server/src/modules/canvas/space-card.route.ts @@ -128,73 +128,81 @@ export function registerSpaceCardRoutes(app: FastifyInstance): void { } }); - app.patch('/:canvasId/title', async (request, reply) => { - const params = recentCanvasConversationParamsSchema.safeParse( - request.params, - ); - const body = renameSpaceBodySchema.safeParse(request.body); - if (!params.success || !body.success) - return reply.code(400).send({ message: 'Invalid Space rename' }); - const { canvasId } = params.data; - const lease = acquireWorkspaceOperationLease(); - try { - return await withCanvasMutex(canvasId, async () => { - const handle = space(canvasId); - const current = await handle.read(); - if (!current) - return reply.code(404).send({ message: 'Space not found' }); - if (current.title !== body.data.expectedTitle) - return reply.code(409).send({ - code: 'SPACE_TITLE_CHANGED', - message: 'The Space name changed. Refresh and try again.', - }); - const renamed = await getStructuredStore() - .spaces() - .rename({ canvasId, title: body.data.title }); - if (!renamed.ok) - return reply - .code( - renamed.reason === 'not-found' - ? 404 - : renamed.reason === 'world-forbidden' - ? 403 - : 409, - ) - .send({ - code: - renamed.reason === 'title-conflict' - ? 'CANVAS_TITLE_CONFLICT' - : 'SPACE_RENAME_REJECTED', - message: 'Unable to rename this Space', + app.patch( + '/:canvasId/title', + { config: { spaceAccess: 'manage' } }, + async (request, reply) => { + const params = recentCanvasConversationParamsSchema.safeParse( + request.params, + ); + const body = renameSpaceBodySchema.safeParse(request.body); + if (!params.success || !body.success) + return reply.code(400).send({ message: 'Invalid Space rename' }); + const { canvasId } = params.data; + const lease = acquireWorkspaceOperationLease(); + try { + return await withCanvasMutex(canvasId, async () => { + const handle = space(canvasId); + const current = await handle.read(); + if (!current) + return reply.code(404).send({ message: 'Space not found' }); + if (current.title !== body.data.expectedTitle) + return reply.code(409).send({ + code: 'SPACE_TITLE_CHANGED', + message: 'The Space name changed. Refresh and try again.', }); - const record = { - ...renamed.record, - version: current.version + 1, - updatedAt: Date.now(), - }; - const written = await handle.write({ - expectedVersion: current.version, - nextRecord: record, - nodeMutations: [], + const renamed = await getStructuredStore() + .spaces() + .rename({ canvasId, title: body.data.title }); + if (!renamed.ok) + return reply + .code( + renamed.reason === 'not-found' + ? 404 + : renamed.reason === 'world-forbidden' + ? 403 + : 409, + ) + .send({ + code: + renamed.reason === 'title-conflict' + ? 'CANVAS_TITLE_CONFLICT' + : 'SPACE_RENAME_REJECTED', + message: 'Unable to rename this Space', + }); + const record = { + ...renamed.record, + version: current.version + 1, + updatedAt: Date.now(), + }; + const written = await handle.write({ + expectedVersion: current.version, + nextRecord: record, + nodeMutations: [], + }); + if (!written.ok) + throw new Error( + `Space rename metadata write failed: ${written.reason}`, + ); + publishCanvasUpdate(canvasId, { + type: 'snapshot', + data: { version: record.version }, + }); + return reply.send({ + title: record.title, + updatedAt: record.updatedAt, + }); }); - if (!written.ok) - throw new Error( - `Space rename metadata write failed: ${written.reason}`, - ); - publishCanvasUpdate(canvasId, { - type: 'snapshot', - data: { version: record.version }, + } catch (error) { + request.log.error({ err: error, canvasId }, 'Space rename failed'); + return reply.code(500).send({ + code: 'SPACE_RENAME_FAILED', + message: + 'Unable to confirm the Space rename. Refresh before retrying.', }); - return reply.send({ title: record.title, updatedAt: record.updatedAt }); - }); - } catch (error) { - request.log.error({ err: error, canvasId }, 'Space rename failed'); - return reply.code(500).send({ - code: 'SPACE_RENAME_FAILED', - message: 'Unable to confirm the Space rename. Refresh before retrying.', - }); - } finally { - lease.release(); - } - }); + } finally { + lease.release(); + } + }, + ); } diff --git a/apps/server/src/modules/canvas/space-hierarchy.route.ts b/apps/server/src/modules/canvas/space-hierarchy.route.ts index 666ca5092..37167f195 100644 --- a/apps/server/src/modules/canvas/space-hierarchy.route.ts +++ b/apps/server/src/modules/canvas/space-hierarchy.route.ts @@ -105,18 +105,22 @@ export function registerSpaceHierarchyRoutes(fastify: FastifyInstance): void { ), ); }); - fastify.post('/:canvasId/delete-tree', async (request, reply) => { - const params = spaceHierarchyParamsSchema.safeParse(request.params); - const body = deleteSpaceTreeBodySchema.safeParse(request.body); - if (!params.success || !body.success) - return reply - .code(400) - .send({ message: 'Invalid subtree deletion request' }); - return respond(reply, async () => ({ - deletedCanvasIds: await deleteSpaceTree( - params.data.canvasId, - body.data.token, - ), - })); - }); + fastify.post( + '/:canvasId/delete-tree', + { config: { spaceAccess: 'manage' } }, + async (request, reply) => { + const params = spaceHierarchyParamsSchema.safeParse(request.params); + const body = deleteSpaceTreeBodySchema.safeParse(request.body); + if (!params.success || !body.success) + return reply + .code(400) + .send({ message: 'Invalid subtree deletion request' }); + return respond(reply, async () => ({ + deletedCanvasIds: await deleteSpaceTree( + params.data.canvasId, + body.data.token, + ), + })); + }, + ); } diff --git a/apps/server/src/modules/identity/request.ts b/apps/server/src/modules/identity/request.ts index c24d41e2a..1cf01a998 100644 --- a/apps/server/src/modules/identity/request.ts +++ b/apps/server/src/modules/identity/request.ts @@ -1,13 +1,17 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -import type { HuabuResource, ResolvedIdentity } from './service.js'; +import type { + AccessLevel, + HuabuResource, + ResolvedIdentity, +} from './service.js'; import type { FastifyRequest } from 'fastify'; const identities = new WeakMap(); const authorizations = new WeakMap< FastifyRequest, - Array<{ level: 'read' | 'write'; resource: HuabuResource }> + Array<{ level: AccessLevel; resource: HuabuResource }> >(); export function setRequestIdentity( @@ -27,7 +31,7 @@ export function getRequestIdentity( /** Record a resource access the request was granted, to recheck while it lasts. */ export function recordRequestAuthorization( request: FastifyRequest, - level: 'read' | 'write', + level: AccessLevel, resource: HuabuResource, ): void { const granted = authorizations.get(request) ?? []; @@ -37,6 +41,29 @@ export function recordRequestAuthorization( export function getRequestAuthorizations( request: FastifyRequest, -): ReadonlyArray<{ level: 'read' | 'write'; resource: HuabuResource }> { +): ReadonlyArray<{ level: AccessLevel; resource: HuabuResource }> { return authorizations.get(request) ?? []; } + +const workspaceChoosers = new WeakMap< + FastifyRequest, + (workspaceId: string) => Promise +>(); + +/** How this request's caller changes their own current Workspace. */ +export function setRequestWorkspaceChooser( + request: FastifyRequest, + choose: (workspaceId: string) => Promise, +): void { + workspaceChoosers.set(request, choose); +} + +/** + * Present when the caller has a current Workspace of their own (Bubble mode); + * absent when switching moves the process-active Workspace (local mode). + */ +export function getRequestWorkspaceChooser( + request: FastifyRequest, +): ((workspaceId: string) => Promise) | undefined { + return workspaceChoosers.get(request); +} diff --git a/apps/server/src/modules/security/space-access.test.ts b/apps/server/src/modules/security/space-access.test.ts index 5aa6e4717..d4446323e 100644 --- a/apps/server/src/modules/security/space-access.test.ts +++ b/apps/server/src/modules/security/space-access.test.ts @@ -34,7 +34,9 @@ function host() { owner: request.headers['x-owner'] === 'yes', access: { can: async (level, { id }) => - id === 'mine' || (id === 'shared' && level === 'read'), + id === 'mine' || + (id === 'shared' && level === 'read') || + (id === 'edit' && level !== 'manage'), claim: async ({ id }) => { claimed.push(id); }, @@ -46,6 +48,11 @@ function host() { const ok = async () => ({ ok: true }); app.get('/api/canvas/:canvasId', ok); app.put('/api/canvas/:canvasId', ok); + app.delete( + '/api/canvas/:canvasId', + { config: { spaceAccess: 'manage' } }, + ok, + ); app.post( '/api/canvas/:canvasId/search', { config: { spaceAccess: 'read' } }, @@ -80,6 +87,17 @@ function host() { } describe('Space access', () => { + it('needs manage, not only write, on a route that declares it', async () => { + const { app } = host(); + const remove = async (id: string) => + (await app.inject({ method: 'DELETE', url: `/api/canvas/${id}` })) + .statusCode; + expect(await remove('mine')).toBe(200); + expect(await remove('edit')).toBe(403); + expect(await remove('shared')).toBe(403); + expect(await remove('other')).toBe(404); + }); + it('reads and writes only the Spaces the identity provider allows', async () => { const { app } = host(); const status = async (method: 'GET' | 'PUT', id: string) => diff --git a/apps/server/src/modules/security/space-access.ts b/apps/server/src/modules/security/space-access.ts index 37daa7802..9ce61c387 100644 --- a/apps/server/src/modules/security/space-access.ts +++ b/apps/server/src/modules/security/space-access.ts @@ -9,12 +9,18 @@ import { } from '../identity/request.js'; import { UNRESTRICTED_ACCESS } from '../identity/service.js'; +import type { AccessLevel } from '../identity/service.js'; + import type { FastifyInstance, FastifyRequest } from 'fastify'; declare module 'fastify' { interface FastifyContextConfig { - /** A non-GET route that only reads the Space it names. */ - spaceAccess?: 'read'; + /** + * What a route needs on the Space it names, when not the method's + * default: `read` for a non-GET route that only reads it, `manage` for + * renaming or deleting it. + */ + spaceAccess?: 'read' | 'manage'; /** Starts or steers an agent outside the agent route prefixes. */ invokesAgent?: true; } @@ -110,7 +116,7 @@ export function registerSpaceAccess(app: FastifyInstance): void { }); } - const checks: Array<['read' | 'write', string]> = []; + const checks: Array<[AccessLevel, string]> = []; if (canvasId) checks.push([level, canvasId]); const destination = body?.destination as Fields; for (const [needed, value] of [ @@ -135,7 +141,7 @@ export function registerSpaceAccess(app: FastifyInstance): void { continue; } // Without read access the Space is indistinguishable from a missing one. - if (needed === 'write' && (await identity.access.can('read', space))) + if (needed !== 'read' && (await identity.access.can('read', space))) return reply.code(403).send({ message: 'Space is read-only for this principal', code: 'SPACE_ACCESS_REQUIRED', From a97596639cebeb767e4de4f962436575efdbfa2f Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:34:12 +0800 Subject: [PATCH 05/17] feat(workspaces): let each person list, create and switch their own Workspaces In Bubble mode the Workspace routes act for the caller alone: they list the Workspaces the caller may enter, create one by name (on Disk, a folder under the data directory) owned by its creator, switch only the caller's current Workspace, and rename or unregister by huabu.manage. Folder picking and paths stay with administrators. GET /api/workspace reports namedWorkspaces so the web app can offer a name-based switcher. A Disk and a Postgres suite run two members and an administrator through the real routes at once. Co-Authored-By: Claude Opus 5.5 --- .../src/modules/identity/bubble.test.ts | 2 +- apps/server/src/modules/identity/http.ts | 8 + .../identity/multi-user.remote.test.ts | 53 ++++ .../modules/identity/multi-user.scenarios.ts | 247 ++++++++++++++++++ .../src/modules/identity/multi-user.test.ts | 33 +++ .../src/modules/workspace-activation.ts | 11 +- apps/server/src/modules/workspace.route.ts | 42 ++- apps/server/src/modules/workspaces.route.ts | 149 +++++++++-- packages/shared/src/types/api/workspace.ts | 6 + 9 files changed, 515 insertions(+), 36 deletions(-) create mode 100644 apps/server/src/modules/identity/multi-user.remote.test.ts create mode 100644 apps/server/src/modules/identity/multi-user.scenarios.ts create mode 100644 apps/server/src/modules/identity/multi-user.test.ts diff --git a/apps/server/src/modules/identity/bubble.test.ts b/apps/server/src/modules/identity/bubble.test.ts index 62f0ef333..1ff91bda6 100644 --- a/apps/server/src/modules/identity/bubble.test.ts +++ b/apps/server/src/modules/identity/bubble.test.ts @@ -12,8 +12,8 @@ import { registerIdentity } from './http.js'; import { createMemoryWorkspacePreferences } from './preferences.js'; import { getRequestIdentity } from './request.js'; import { isOwnerRequest } from '../security/owner.js'; -import { getWorkspaceHandle } from '../workspace.js'; import { registerSpaceAccess } from '../security/space-access.js'; +import { getWorkspaceHandle } from '../workspace.js'; import type { HuabuResource, ResourceDirectory } from './service.js'; import type { BubbleStore } from '@octostaff/bubble'; diff --git a/apps/server/src/modules/identity/http.ts b/apps/server/src/modules/identity/http.ts index 4c0018e23..66f5b7c7f 100644 --- a/apps/server/src/modules/identity/http.ts +++ b/apps/server/src/modules/identity/http.ts @@ -5,6 +5,7 @@ import { timingSafeEqual } from 'node:crypto'; import { getRequestAuthorizations, + setRequestWorkspaceChooser, getRequestIdentity, setRequestIdentity, } from './request.js'; @@ -176,6 +177,13 @@ export function registerIdentity( if (identity.member && service.selectWorkspace) { const scope = await service.selectWorkspace(identity); if (scope) fillWorkspaceScope(scope); + const { chooseWorkspace } = service; + if (chooseWorkspace) + setRequestWorkspaceChooser( + request, + async (workspaceId) => + (await chooseWorkspace(identity, workspaceId)) !== null, + ); } if ( service.provider === 'bubble' && diff --git a/apps/server/src/modules/identity/multi-user.remote.test.ts b/apps/server/src/modules/identity/multi-user.remote.test.ts new file mode 100644 index 000000000..88220676f --- /dev/null +++ b/apps/server/src/modules/identity/multi-user.remote.test.ts @@ -0,0 +1,53 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { randomUUID } from 'node:crypto'; +import { mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import { afterEach, beforeEach } from 'vitest'; + +import { describeSeveralPeople } from './multi-user.scenarios.js'; +import { openPostgresTestDatabase } from '../storage/backends/postgres/test-support.js'; +import { closeStorage, initStorage } from '../storage/index.js'; + +/** + * The same people, on Postgres: every request goes through the one shared + * connection pool, so this is where a namespace leaking between concurrent + * Workspaces would show. + */ + +let tmp: string; +const restores: Array<() => Promise | void> = []; + +function setEnv(key: string, value: string): void { + const previous = process.env[key]; + restores.push(() => { + if (previous === undefined) delete process.env[key]; + else process.env[key] = previous; + }); + process.env[key] = value; +} + +beforeEach(async () => { + tmp = mkdtempSync(join(tmpdir(), 'huabu-multi-user-pg-')); + setEnv('HUABU_DATA_DIR', join(tmp, 'data')); + const database = await openPostgresTestDatabase(); + restores.push(database.cleanup); + const url = new URL(database.config.connectionString); + url.searchParams.set('options', database.config.options); + url.searchParams.set('application_name', `huabu-multi-user-${randomUUID()}`); + setEnv('HUABU_POSTGRES_URL', url.toString()); + await initStorage({ + structured: { kind: 'postgres' }, + blobs: { kind: 'disk' }, + }); +}); +afterEach(async () => { + await closeStorage(); + for (const restore of restores.splice(0).reverse()) await restore(); + rmSync(tmp, { recursive: true, force: true }); +}); + +describeSeveralPeople('Postgres', () => tmp); diff --git a/apps/server/src/modules/identity/multi-user.scenarios.ts b/apps/server/src/modules/identity/multi-user.scenarios.ts new file mode 100644 index 000000000..8fa141b25 --- /dev/null +++ b/apps/server/src/modules/identity/multi-user.scenarios.ts @@ -0,0 +1,247 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { join } from 'node:path'; + +import { InMemoryBubbleStore } from '@octostaff/bubble'; +import Fastify from 'fastify'; +import { afterEach, describe, expect, it } from 'vitest'; + +import { openBubbleIdentity } from './bubble.js'; +import { registerIdentity } from './http.js'; +import { createMemoryWorkspacePreferences } from './preferences.js'; +import { storageResourceDirectory } from './resources.js'; +import canvasRoutes from '../canvas/canvas.route.js'; +import { registerSpaceAccess } from '../security/space-access.js'; +import workspaceRoutes from '../workspace.route.js'; +import workspacesRoutes from '../workspaces.route.js'; + +import type { FastifyInstance } from 'fastify'; + +/** + * Several people on one Server, end to end: Bubble admission, the Space guard + * and the real routes, over real Disk storage. Each person works in their own + * Workspace at the same time, and one person's switch moves nobody else. + */ + +const MASTER = 'Bearer master-secret'; +const as = (principalId: string) => ({ + authorization: MASTER, + 'x-bubble-principal-id': principalId, +}); + +const servers: FastifyInstance[] = []; +afterEach(async () => { + await Promise.all(servers.splice(0).map((app) => app.close())); +}); + +async function host() { + const store = new InMemoryBubbleStore(); + const bubble = await openBubbleIdentity({ + authenticator: [ + { + driver: 'master-key', + masterKey: 'master-secret', + defaultPrincipalId: 'admin', + }, + ], + owner: 'admin', + store, + preferences: createMemoryWorkspacePreferences(), + resources: storageResourceDirectory, + }); + for (const principalId of ['carol', 'dave']) { + await store.principals.upsert({ principalId, kind: 'user' }); + await store.grants.add({ + target: { type: 'system' }, + principalId, + role: 'member', + grantedByPrincipalId: null, + }); + } + const app = Fastify(); + servers.push(app); + registerIdentity(app, { + service: bubble.service, + getConnectionToken: () => 'machine-secret', + }); + registerSpaceAccess(app); + await app.register(canvasRoutes, { prefix: '/api/canvas' }); + await app.register(workspaceRoutes, { prefix: '/api/workspace' }); + await app.register(workspacesRoutes, { prefix: '/api/workspaces' }); + + const call = async ( + principalId: string, + method: 'GET' | 'POST' | 'PATCH' | 'DELETE', + url: string, + payload?: object, + ) => { + const response = await app.inject({ + method, + url, + headers: as(principalId), + payload, + }); + return { + status: response.statusCode, + body: response.body ? response.json() : undefined, + }; + }; + const workspaceOf = async (principalId: string) => + (await call(principalId, 'GET', '/api/workspace')).body.workspaceId; + const spacesOf = async (principalId: string) => + ( + (await call(principalId, 'GET', '/api/canvas')).body.canvases as Array<{ + title: string; + }> + ) + .map((space) => space.title) + .sort(); + return { app, store, call, workspaceOf, spacesOf }; +} + +/** + * The scenarios, for one storage backend. `tmp` is a scratch directory the + * backend's setup owns; a folder path a member must not be able to adopt. + */ +export function describeSeveralPeople( + backend: string, + scratch: () => string, +): void { + describe(`several people on one Server (${backend})`, () => { + it('gives each member a Workspace of their own and keeps their Spaces apart', async () => { + const { call, workspaceOf, spacesOf } = await host(); + const [carolWs, daveWs, adminWs] = await Promise.all([ + workspaceOf('carol'), + workspaceOf('dave'), + workspaceOf('admin'), + ]); + expect(new Set([carolWs, daveWs, adminWs]).size).toBe(3); + + // Interleaved creates land in each caller's own Workspace. + const created = await Promise.all( + ['carol', 'dave', 'carol', 'dave'].map((principalId, index) => + call(principalId, 'POST', '/api/canvas', { + title: `${principalId} ${index}`, + }), + ), + ); + expect(created.map((response) => response.status)).toEqual([ + 201, 201, 201, 201, + ]); + expect(await spacesOf('carol')).toEqual(['carol 0', 'carol 2']); + expect(await spacesOf('dave')).toEqual(['dave 1', 'dave 3']); + expect(await spacesOf('admin')).toEqual([]); + + // Another person's Space is missing, not forbidden. + const carols = created[0].body.canvasId as string; + expect((await call('dave', 'GET', `/api/canvas/${carols}`)).status).toBe( + 404, + ); + expect((await call('carol', 'GET', `/api/canvas/${carols}`)).status).toBe( + 200, + ); + + // Members never learn where the Server keeps their folder. + const info = (await call('carol', 'GET', '/api/workspace')).body; + expect(info).toMatchObject({ + path: null, + capabilities: { + canChangeWorkspace: true, + nativePicker: false, + namedWorkspaces: true, + }, + }); + }); + + it('switches only its caller, among Workspaces they may enter', async () => { + const { call, workspaceOf, spacesOf } = await host(); + const daveWs = await workspaceOf('dave'); + const carolWs = await workspaceOf('carol'); + await call('carol', 'POST', '/api/canvas', { title: 'first' }); + + const made = await call('carol', 'POST', '/api/workspaces', { + name: 'Side project', + }); + expect(made.status).toBe(201); + expect(made.body).toMatchObject({ name: 'Side project', path: null }); + const listed = (await call('carol', 'GET', '/api/workspaces')) + .body as Array<{ + workspaceId: string; + active: boolean; + }>; + expect(listed.map((w) => w.workspaceId).sort()).toEqual( + [carolWs, made.body.workspaceId].sort(), + ); + + const switched = await call( + 'carol', + 'POST', + `/api/workspaces/${made.body.workspaceId}/activate`, + ); + expect(switched.body).toMatchObject({ active: true }); + expect(await workspaceOf('carol')).toBe(made.body.workspaceId); + expect(await spacesOf('carol')).toEqual([]); + expect(await workspaceOf('dave')).toBe(daveWs); + + // Someone else's Workspace is not there to switch to, rename or remove. + for (const [method, url] of [ + ['POST', `/api/workspaces/${daveWs}/activate`], + ['PATCH', `/api/workspaces/${daveWs}`], + ['DELETE', `/api/workspaces/${daveWs}`], + ] as const) { + const response = await call('carol', method, url, { name: 'mine now' }); + expect(response.status).toBe(404); + } + expect(await workspaceOf('dave')).toBe(daveWs); + + // Folder operations stay with the administrator. + expect( + ( + await call('carol', 'POST', '/api/workspaces', { + path: join(scratch(), 'elsewhere'), + }) + ).status, + ).toBe(400); + expect( + ( + await call('carol', 'POST', '/api/workspace/validate-path', { + path: '/', + }) + ).status, + ).toBe(403); + + // Back to the first Workspace; its Space is still there. + await call('carol', 'POST', `/api/workspaces/${carolWs}/activate`); + expect(await spacesOf('carol')).toEqual(['first']); + }); + + it('lets a viewer read a shared Workspace but not change it', async () => { + const { call, store, workspaceOf } = await host(); + const carolWs = await workspaceOf('carol'); + const space = await call('carol', 'POST', '/api/canvas', { + title: 'notes', + }); + await store.grants.add({ + target: { type: 'huabu.workspace', id: carolWs }, + principalId: 'dave', + role: 'huabu.workspace.viewer', + grantedByPrincipalId: 'carol', + }); + await workspaceOf('dave'); + await call('dave', 'POST', `/api/workspaces/${carolWs}/activate`); + const id = space.body.canvasId as string; + expect((await call('dave', 'GET', `/api/canvas/${id}`)).status).toBe(200); + expect((await call('dave', 'DELETE', `/api/canvas/${id}`)).status).toBe( + 403, + ); + expect( + ( + await call('dave', 'PATCH', `/api/workspaces/${carolWs}`, { + name: 'x', + }) + ).status, + ).toBe(404); + }); + }); +} diff --git a/apps/server/src/modules/identity/multi-user.test.ts b/apps/server/src/modules/identity/multi-user.test.ts new file mode 100644 index 000000000..1d212af9b --- /dev/null +++ b/apps/server/src/modules/identity/multi-user.test.ts @@ -0,0 +1,33 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import { afterEach, beforeEach } from 'vitest'; + +import { describeSeveralPeople } from './multi-user.scenarios.js'; +import { resetStorageCache } from '../storage/index.js'; +import { setWorkspacePath } from '../workspace.js'; + +let tmp: string; +let previousDataDir: string | undefined; + +beforeEach(() => { + tmp = mkdtempSync(join(tmpdir(), 'huabu-multi-user-')); + previousDataDir = process.env.HUABU_DATA_DIR; + process.env.HUABU_DATA_DIR = join(tmp, 'data'); + mkdirSync(join(tmp, 'server')); + resetStorageCache(); + // The Server's own Workspace, where the administrator lands. + setWorkspacePath(join(tmp, 'server')); +}); +afterEach(() => { + if (previousDataDir === undefined) delete process.env.HUABU_DATA_DIR; + else process.env.HUABU_DATA_DIR = previousDataDir; + resetStorageCache(); + rmSync(tmp, { recursive: true, force: true }); +}); + +describeSeveralPeople('Disk', () => tmp); diff --git a/apps/server/src/modules/workspace-activation.ts b/apps/server/src/modules/workspace-activation.ts index c283e87cb..4a340e1b5 100644 --- a/apps/server/src/modules/workspace-activation.ts +++ b/apps/server/src/modules/workspace-activation.ts @@ -17,6 +17,7 @@ import { mkdir } from 'node:fs/promises'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; +import { prepareWorkspaceOnDisk } from './workspace-prepare.js'; import { beginWorkspaceActivation, isManagedMode, @@ -224,15 +225,17 @@ export async function activateWorkspacePath( * Create a Workspace by name, on any backend, without activating it. * * Where a Workspace is a row this is the repository's own create. On Disk it - * is a new folder under the data directory, prepared in the isolated worker - * like any other: the creator never chooses where it lives, which is what lets - * someone without access to the Server's filesystem have one. + * is a new folder under the data directory: the creator never chooses where + * it lives, which is what lets someone without access to the Server's + * filesystem have one. An empty folder the Server just made is not the + * unresponsive cloud or network drive the preparation worker isolates, so it + * is prepared in-process. */ export async function createWorkspace(name: string): Promise { if (!materializesWorkspaces()) return createNamedWorkspace(name); const workspacePath = path.join(getDataDir(), 'workspaces', randomUUID()); await mkdir(workspacePath, { recursive: true }); - await runWorkspacePreparation(workspacePath); + prepareWorkspaceOnDisk(workspacePath); const adopted = adoptWorkspaceDirectory(workspacePath); return ( (await getWorkspaceRepository().rename(adopted.workspaceId, name)) ?? diff --git a/apps/server/src/modules/workspace.route.ts b/apps/server/src/modules/workspace.route.ts index a2f5cba3c..8187cf7a4 100644 --- a/apps/server/src/modules/workspace.route.ts +++ b/apps/server/src/modules/workspace.route.ts @@ -160,7 +160,9 @@ function sendError( } /** Build the canonical success payload describing the current workspace. */ -async function buildWorkspaceState(): Promise { +async function buildWorkspaceState( + personal: { admin: boolean } | null = null, +): Promise { const managed = isManagedMode(); const workspace = getWorkspaceHandle(); const configured = workspace !== null; @@ -171,26 +173,38 @@ async function buildWorkspaceState(): Promise { // Free-mode active absolute path. Never exposed in managed mode. // Null in managed mode, and null wherever a Workspace has no folder at // all. The client already renders a Workspace with no path. - path: workspace && !managed ? getWorkspaceDirectory() : null, + path: + workspace && !managed && (!personal || personal.admin) + ? getWorkspaceDirectory() + : null, // Persisted display label. Safe to send in either mode. name: workspace?.name ?? null, worldCanvasId: configured ? await getStructuredStore().spaces().worldId() : null, - capabilities: { - // Switching Workspaces means picking a folder in this API. A backend - // that keeps Workspaces as rows has one already open and no folder to - // offer, so the client stops showing a picker it could not honour. - canChangeWorkspace: !managed && materializesWorkspaces(), - nativePicker: - !managed && materializesWorkspaces() && canShowNativePicker(), - }, + capabilities: personal + ? // Each person switches among, and creates, Workspaces of their own + // by name; folders are not theirs to pick. + { + canChangeWorkspace: !managed, + nativePicker: false, + namedWorkspaces: true, + } + : { + // Switching Workspaces means picking a folder in this API. A backend + // that keeps Workspaces as rows has one already open and no folder to + // offer, so the client stops showing a picker it could not honour. + canChangeWorkspace: !managed && materializesWorkspaces(), + nativePicker: + !managed && materializesWorkspaces() && canShowNativePicker(), + }, }; } const workspaceRoutes: FastifyPluginAsync = async (app) => { - // The active Workspace is the whole Server's, so a principal with - // per-Space access (a Bubble member) may not change it. + // These routes pick folders on the Server and move the process-active + // Workspace, so in Bubble mode only an administrator reaches them; a person + // switches their own Workspace through `/api/workspaces`. app.addHook('preHandler', async (request, reply) => { if ( request.method !== 'GET' && @@ -208,7 +222,9 @@ const workspaceRoutes: FastifyPluginAsync = async (app) => { // Always available (clients need to know the mode). // ──────────────────────────────────────────────────────────────── app.get<{ Reply: ApiResult }>('/', async (request) => { - const state = await buildWorkspaceState(); + const state = await buildWorkspaceState( + isRestrictedRequest(request) ? { admin: isOwnerRequest(request) } : null, + ); // World is an ordinary Space here, advertised only to who may read it. if ( state.worldCanvasId && diff --git a/apps/server/src/modules/workspaces.route.ts b/apps/server/src/modules/workspaces.route.ts index 094a851a4..0bae50e69 100644 --- a/apps/server/src/modules/workspaces.route.ts +++ b/apps/server/src/modules/workspaces.route.ts @@ -7,6 +7,10 @@ import { z } from 'zod'; import { workspaceCreateSchema, workspaceRenameSchema } from '@huabu/shared'; +import { + getRequestIdentity, + getRequestWorkspaceChooser, +} from './identity/request.js'; import { migrateLegacyDesktopWorkspaceStore } from './legacy-desktop-workspace-store.js'; import { resetPreprocessDispatcher } from './preprocessing/index.js'; import { isOwnerRequest } from './security/owner.js'; @@ -26,16 +30,19 @@ import { } from './storage/index.js'; import { activateWorkspacePath, + createWorkspace, prepareWorkspacePath, WorkspaceActivationInProgressError, WorkspaceActivationTimeoutError, } from './workspace-activation.js'; import { commitWorkspacePath, + getProcessWorkspaceHandle, getWorkspaceDirectory, getWorkspaceHandle, getWorkspacePath, isManagedMode, + isWorkspaceLeased, resolveWorkspacePath, updateActiveWorkspaceHandle, } from './workspace.js'; @@ -87,7 +94,10 @@ function rejectReadOnlyMutation( return null; } -function descriptor(workspace: WorkspaceHandle): WorkspaceDescriptor { +function descriptor( + workspace: WorkspaceHandle, + showPath = true, +): WorkspaceDescriptor { const workspacePath = workspaceDirectory(workspace.workspaceId); const activeHandle = getWorkspaceHandle(); const activeDirectory = getWorkspaceDirectory(); @@ -105,7 +115,7 @@ function descriptor(workspace: WorkspaceHandle): WorkspaceDescriptor { name: workspace.name, // A Workspace's directory is a materialization fact the handle does not // carry, so it is resolved separately — and never sent in managed mode. - path: isManagedMode() ? null : workspacePath, + path: isManagedMode() || !showPath ? null : workspacePath, active, }; } @@ -188,17 +198,39 @@ interface WorkspaceParams { workspaceId: string; } -const workspacesRoutes: FastifyPluginAsync = async (app) => { - // Listing, creating and switching Workspaces act for the whole Server, so - // a principal with per-Space access (a Bubble member) may not. - app.addHook('preHandler', async (request, reply) => { - if (!isOwnerRequest(request) && isRestrictedRequest(request)) { - return reply.status(403).send({ - message: 'Forbidden: managing Workspaces requires an owner', - }); - } +/** + * In Bubble mode each person has Workspaces of their own and a current one, + * and these routes act for the caller alone: they list what the caller may + * enter, switch only the caller, and create, rename or unregister by the + * caller's grants. Folder Workspaces stay with administrators, because they + * name places on the Server's filesystem. Local mode acts for the Server, as + * it always has. + */ +function personal(request: FastifyRequest): boolean { + return isRestrictedRequest(request); +} + +async function enterable( + request: FastifyRequest, +): Promise { + const allowed = await getRequestIdentity(request)!.access.workspaces(); + const all = await getWorkspaceRepository().list(); + return allowed === 'all' + ? all + : all.filter((workspace) => allowed.includes(workspace.workspaceId)); +} + +async function canManage( + request: FastifyRequest, + workspaceId: string, +): Promise { + return getRequestIdentity(request)!.access.can('manage', { + type: 'workspace', + id: workspaceId, }); +} +const workspacesRoutes: FastifyPluginAsync = async (app) => { let legacyDesktopStoreImported = false; /** @@ -233,13 +265,39 @@ const workspacesRoutes: FastifyPluginAsync = async (app) => { importLegacyDesktopStore(); }); - app.get('/', async () => (await visibleWorkspaces()).map(descriptor)); + app.get('/', async (request) => { + if (!personal(request)) + return (await visibleWorkspaces()).map((w) => descriptor(w)); + const showPath = isOwnerRequest(request); + return (await enterable(request)).map((w) => descriptor(w, showPath)); + }); app.post<{ Body: WorkspaceCreateRequest }>('/', async (request, reply) => { + const parsed = workspaceCreateSchema.safeParse(request.body); + // A person's Workspace is made by name, wherever the backend keeps one, + // and is theirs. Choosing a folder is an administrator's, from localhost. + if (personal(request) && !(isOwnerRequest(request) && parsed.data?.path)) { + if (isManagedMode()) + return sendError(reply, 403, 'Workspace collection is read-only'); + if (!parsed.success || !parsed.data.name || parsed.data.path) + return sendError(reply, 400, 'Workspace name is required'); + try { + const workspace = await createWorkspace(parsed.data.name); + await getRequestIdentity(request)!.access.claim({ + type: 'workspace', + id: workspace.workspaceId, + }); + return reply + .status(201) + .send(descriptor(workspace, isOwnerRequest(request))); + } catch (error) { + return sendPreparationError(reply, error); + } + } + const rejected = rejectReadOnlyMutation(request, reply); if (rejected) return rejected; - const parsed = workspaceCreateSchema.safeParse(request.body); if (!parsed.success) { return sendError( reply, @@ -321,6 +379,13 @@ const workspacesRoutes: FastifyPluginAsync = async (app) => { async (request, reply) => { const parsedId = parseWorkspaceId(request.params.workspaceId, reply); if (typeof parsedId !== 'string') return parsedId; + if (personal(request)) { + const workspace = (await enterable(request)).find( + (w) => w.workspaceId === parsedId, + ); + if (!workspace) return sendError(reply, 404, 'Workspace not found'); + return reply.send(descriptor(workspace, isOwnerRequest(request))); + } const workspace = await findVisible(parsedId); if (!workspace) return sendError(reply, 404, 'Workspace not found'); return reply.send(descriptor(workspace)); @@ -330,6 +395,19 @@ const workspacesRoutes: FastifyPluginAsync = async (app) => { app.post<{ Params: WorkspaceParams }>( '/:workspaceId/activate', async (request, reply) => { + const choose = getRequestWorkspaceChooser(request); + if (personal(request)) { + const parsedId = parseWorkspaceId(request.params.workspaceId, reply); + if (typeof parsedId !== 'string') return parsedId; + // Switching moves the caller alone; the request itself still runs in + // the Workspace it was admitted to, so it answers for the new one. + if (!choose || !(await choose(parsedId))) + return sendError(reply, 404, 'Workspace not found'); + const workspace = await getWorkspaceRepository().get(parsedId); + if (!workspace) return sendError(reply, 404, 'Workspace not found'); + const chosen = descriptor(workspace, isOwnerRequest(request)); + return reply.send({ ...chosen, active: true }); + } const rejected = rejectReadOnlyMutation(request, reply); if (rejected) return rejected; const parsedId = parseWorkspaceId(request.params.workspaceId, reply); @@ -367,10 +445,17 @@ const workspacesRoutes: FastifyPluginAsync = async (app) => { app.patch<{ Params: WorkspaceParams; Body: WorkspaceRenameRequest }>( '/:workspaceId', async (request, reply) => { - const rejected = rejectReadOnlyMutation(request, reply); - if (rejected) return rejected; const parsedId = parseWorkspaceId(request.params.workspaceId, reply); if (typeof parsedId !== 'string') return parsedId; + if (personal(request)) { + if (isManagedMode()) + return sendError(reply, 403, 'Workspace collection is read-only'); + if (!(await canManage(request, parsedId))) + return sendError(reply, 404, 'Workspace not found'); + } else { + const rejected = rejectReadOnlyMutation(request, reply); + if (rejected) return rejected; + } const parsed = workspaceRenameSchema.safeParse(request.body); if (!parsed.success) { return sendError( @@ -387,7 +472,9 @@ const workspacesRoutes: FastifyPluginAsync = async (app) => { ); if (!workspace) return sendError(reply, 404, 'Workspace not found'); updateActiveWorkspaceHandle(workspace); - return reply.send(descriptor(workspace)); + return reply.send( + descriptor(workspace, !personal(request) || isOwnerRequest(request)), + ); } catch (error) { return sendError(reply, 400, (error as Error).message); } @@ -397,10 +484,36 @@ const workspacesRoutes: FastifyPluginAsync = async (app) => { app.delete<{ Params: WorkspaceParams }>( '/:workspaceId', async (request, reply) => { - const rejected = rejectReadOnlyMutation(request, reply); - if (rejected) return rejected; const parsedId = parseWorkspaceId(request.params.workspaceId, reply); if (typeof parsedId !== 'string') return parsedId; + if (personal(request)) { + if (isManagedMode()) + return sendError(reply, 403, 'Workspace collection is read-only'); + if (!(await canManage(request, parsedId))) + return sendError(reply, 404, 'Workspace not found'); + // Someone else's current Workspace moves them on at their next + // request; work in flight there is not stranded. + const workspace = await getWorkspaceRepository().get(parsedId); + const key = workspace + ? (workspaceDirectory(parsedId) ?? `workspace:${parsedId}`) + : null; + if (key && isWorkspaceLeased(key)) + return sendError( + reply, + 409, + 'Cannot unregister a Workspace while an operation is using it', + ); + // The process-active Workspace serves local callers and startup work. + if (getProcessWorkspaceHandle()?.workspaceId === parsedId) + return sendError( + reply, + 409, + 'Cannot unregister the active Workspace', + ); + } else { + const rejected = rejectReadOnlyMutation(request, reply); + if (rejected) return rejected; + } if (getWorkspaceHandle()?.workspaceId === parsedId) { return sendError(reply, 409, 'Cannot unregister the active Workspace'); } diff --git a/packages/shared/src/types/api/workspace.ts b/packages/shared/src/types/api/workspace.ts index 9ffc9dc5e..d5554f0a9 100644 --- a/packages/shared/src/types/api/workspace.ts +++ b/packages/shared/src/types/api/workspace.ts @@ -26,6 +26,12 @@ export const workspaceCapabilitiesSchema = z.object({ canChangeWorkspace: z.boolean(), /** Whether the server can show a native folder picker. */ nativePicker: z.boolean(), + /** + * Whether Workspaces are switched and created by name rather than by + * folder: each signed-in person has their own (Bubble mode). Absent from + * older servers. + */ + namedWorkspaces: z.boolean().optional(), }); export type WorkspaceCapabilities = z.infer; From b1b527e3c76ea99a9b1282aba64cbde52899035d Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:42:18 +0800 Subject: [PATCH 06/17] feat(rfs): keep an agent run in the Workspace it started in An agent's reachback URL now names its Workspace (/api/rfs/w//), and the RFS routes are also served under that prefix in that Workspace. A run no longer follows its starter's later switches or the process-active Workspace. The old unscoped URL keeps working for runs started before the upgrade. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/app.ts | 5 ++ .../src/modules/agent/acp/reachback-env.ts | 8 +- .../src/modules/remote_fs/public-skill.ts | 3 +- .../modules/workspace/scoped-routes.test.ts | 79 +++++++++++++++++++ .../src/modules/workspace/scoped-routes.ts | 37 +++++++++ 5 files changed, 129 insertions(+), 3 deletions(-) create mode 100644 apps/server/src/modules/workspace/scoped-routes.test.ts create mode 100644 apps/server/src/modules/workspace/scoped-routes.ts diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts index 638ea2dbe..a0ddcdab5 100644 --- a/apps/server/src/app.ts +++ b/apps/server/src/app.ts @@ -59,6 +59,7 @@ import { registerSpaceAccess } from './modules/security/space-access.js'; import serviceRoutes from './modules/services/services.route.js'; import { closeStorage } from './modules/storage/index.js'; import webRoutes from './modules/web/web.route.js'; +import { workspaceScopedRoutes } from './modules/workspace/scoped-routes.js'; import { registerWorkspaceRequiredGuard } from './modules/workspace-required.js'; import { initWorkspaceFromEnv } from './modules/workspace.js'; import workspaceRoutes from './modules/workspace.route.js'; @@ -183,6 +184,10 @@ app.register(skillsRoutes, { prefix: '/api/skills' }); app.register(workspaceRoutes, { prefix: '/api/workspace' }); app.register(workspacesRoutes, { prefix: '/api/workspaces' }); app.register(rfsRoutes, { prefix: '/api/rfs' }); +// An agent's reachback names the Workspace its run started in. +app.register(workspaceScopedRoutes(rfsRoutes), { + prefix: '/api/rfs/w/:workspaceId', +}); // ── External agent (ACP) transport host ─────────────────────────────── // Mount the Agenetes agentlet transport host (`@agenetes/agentlet-host`). diff --git a/apps/server/src/modules/agent/acp/reachback-env.ts b/apps/server/src/modules/agent/acp/reachback-env.ts index a33a7c1a6..db3c4c45b 100644 --- a/apps/server/src/modules/agent/acp/reachback-env.ts +++ b/apps/server/src/modules/agent/acp/reachback-env.ts @@ -9,7 +9,7 @@ * host over the canvas-scoped Remote File System (RFS) and attribute its * change-review activity to the right conversation: * - * - `HUABU_RFS_URL` — `/api/rfs/`, + * - `HUABU_RFS_URL` — `/api/rfs/w//`, * the canvas-scoped RFS base (capabilities / query / * download / upload / execute / agent / skill). Bakes the canvasId into the path * so the agent needs no separate canvas variable. @@ -27,6 +27,7 @@ import { getHostServerPort } from '../../../host-port.js'; import { resolveConfiguredPublicOrigin } from '../../security/public-origin.js'; +import { getWorkspaceHandle } from '../../workspace.js'; /** * Build the reachback env for an agent serving `threadId` in `canvasId`. @@ -45,8 +46,11 @@ export function buildReachbackEnv( if (port > 0) origin = `http://127.0.0.1:${port}`; } if (origin) { + // Named so the run keeps its Workspace after its starter switches. + const workspaceId = getWorkspaceHandle()?.workspaceId; + const scope = workspaceId ? `w/${encodeURIComponent(workspaceId)}/` : ''; env.HUABU_RFS_URL = new URL( - `/api/rfs/${encodeURIComponent(canvasId)}`, + `/api/rfs/${scope}${encodeURIComponent(canvasId)}`, origin, ).toString(); } diff --git a/apps/server/src/modules/remote_fs/public-skill.ts b/apps/server/src/modules/remote_fs/public-skill.ts index 21b504c41..83d435b71 100644 --- a/apps/server/src/modules/remote_fs/public-skill.ts +++ b/apps/server/src/modules/remote_fs/public-skill.ts @@ -1,7 +1,8 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -const PUBLIC_ROOT_SKILL_PATTERN = /^\/api\/rfs\/[^/?]+\/skill(?:\?.*)?$/; +const PUBLIC_ROOT_SKILL_PATTERN = + /^\/api\/rfs\/(?:w\/[^/?]+\/)?[^/?]+\/skill(?:\?.*)?$/; /** Only a credential-free root skill request may bypass the RFS auth gate. */ export function isPublicRfsSkillBootstrapRequest(input: { diff --git a/apps/server/src/modules/workspace/scoped-routes.test.ts b/apps/server/src/modules/workspace/scoped-routes.test.ts new file mode 100644 index 000000000..2580c2957 --- /dev/null +++ b/apps/server/src/modules/workspace/scoped-routes.test.ts @@ -0,0 +1,79 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import Fastify from 'fastify'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; + +import { runInWorkspace } from './context.js'; +import { workspaceScopedRoutes } from './scoped-routes.js'; +import { buildReachbackEnv } from '../agent/acp/reachback-env.js'; +import { resetStorageCache } from '../storage/index.js'; +import { createWorkspace } from '../workspace-activation.js'; +import { getWorkspaceHandle, setWorkspacePath } from '../workspace.js'; + +let tmp: string; +let previousDataDir: string | undefined; +beforeEach(() => { + tmp = mkdtempSync(join(tmpdir(), 'huabu-scoped-routes-')); + previousDataDir = process.env.HUABU_DATA_DIR; + process.env.HUABU_DATA_DIR = join(tmp, 'data'); + mkdirSync(join(tmp, 'server')); + resetStorageCache(); + setWorkspacePath(join(tmp, 'server')); +}); +afterEach(() => { + if (previousDataDir === undefined) delete process.env.HUABU_DATA_DIR; + else process.env.HUABU_DATA_DIR = previousDataDir; + resetStorageCache(); + rmSync(tmp, { recursive: true, force: true }); +}); + +describe('Workspace-scoped routes', () => { + it('run each call in the Workspace their prefix names', async () => { + const other = await createWorkspace('Other'); + const app = Fastify(); + const routes = async (scoped: typeof app) => { + scoped.get('/where', async () => ({ + workspaceId: getWorkspaceHandle()?.workspaceId, + })); + }; + await app.register(routes, { prefix: '/plain' }); + await app.register(workspaceScopedRoutes(routes), { + prefix: '/w/:workspaceId', + }); + + const processActive = getWorkspaceHandle()?.workspaceId; + expect((await app.inject('/plain/where')).json().workspaceId).toBe( + processActive, + ); + expect( + (await app.inject(`/w/${other.workspaceId}/where`)).json().workspaceId, + ).toBe(other.workspaceId); + expect((await app.inject('/w/no-such-workspace/where')).statusCode).toBe( + 404, + ); + await app.close(); + }); + + it('names the Workspace a run starts in in its reachback URL', async () => { + const other = await createWorkspace('Other'); + const previous = process.env.HUABU_PUBLIC_ORIGIN; + process.env.HUABU_PUBLIC_ORIGIN = 'https://huabu.example.com'; + try { + const env = runInWorkspace({ handle: other, path: null }, () => + buildReachbackEnv('thread-1', 'canvas-1'), + ); + expect(env).toEqual({ + HUABU_RFS_URL: `https://huabu.example.com/api/rfs/w/${other.workspaceId}/canvas-1`, + HUABU_THREAD_ID: 'thread-1', + }); + } finally { + if (previous === undefined) delete process.env.HUABU_PUBLIC_ORIGIN; + else process.env.HUABU_PUBLIC_ORIGIN = previous; + } + }); +}); diff --git a/apps/server/src/modules/workspace/scoped-routes.ts b/apps/server/src/modules/workspace/scoped-routes.ts new file mode 100644 index 000000000..6bdd12011 --- /dev/null +++ b/apps/server/src/modules/workspace/scoped-routes.ts @@ -0,0 +1,37 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { fillWorkspaceScope, openWorkspaceScope } from './context.js'; +import { getWorkspaceRepository, openWorkspace } from '../storage/index.js'; + +import type { FastifyPluginAsync } from 'fastify'; + +/** + * Serve `routes` under a `:workspaceId` prefix, each call running in that + * Workspace whatever the caller's current one or the process-active one is. + * + * For callers whose Workspace was fixed when they started: an agent run keeps + * the Workspace it was launched in for its whole life, so its reachback names + * it rather than following its starter's later switches. + */ +export function workspaceScopedRoutes( + routes: FastifyPluginAsync, +): FastifyPluginAsync { + return async (app) => { + // Own slot, wrapping the rest of the lifecycle; admission's, if any, was + // for the caller's current Workspace and does not apply here. + app.addHook('onRequest', (_request, _reply, done) => + openWorkspaceScope(done), + ); + app.addHook('onRequest', async (request, reply) => { + const { workspaceId } = request.params as { workspaceId?: string }; + const workspace = workspaceId + ? await getWorkspaceRepository().get(workspaceId) + : null; + if (!workspace) + return reply.code(404).send({ message: 'Workspace not found' }); + fillWorkspaceScope(await openWorkspace(workspace)); + }); + await app.register(routes); + }; +} From 4a58f0cda9c150dbeabcdce787008f1554bd8cae Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:42:18 +0800 Subject: [PATCH 07/17] feat(web): switch and create named Workspaces When the Server reports namedWorkspaces, boot keeps the Workspace the Server chose for the caller instead of activating the first registered one, the setup page lists the caller's Workspaces and creates one by name instead of picking a folder, and the header calls it a Workspace. Local mode renders as before. Co-Authored-By: Claude Opus 5.5 --- apps/web/src/api/workspace.ts | 14 ++ apps/web/src/i18n/resources/en/common.json | 10 +- apps/web/src/i18n/resources/zh-CN/common.json | 10 +- apps/web/src/pages/CanvasListPage.tsx | 11 +- apps/web/src/pages/WorkspaceSetupPage.tsx | 141 ++++++++++++++++-- apps/web/src/store/workspaceStore.test.ts | 39 +++++ apps/web/src/store/workspaceStore.ts | 22 ++- 7 files changed, 230 insertions(+), 17 deletions(-) diff --git a/apps/web/src/api/workspace.ts b/apps/web/src/api/workspace.ts index 1984e2c69..fc5781a9b 100644 --- a/apps/web/src/api/workspace.ts +++ b/apps/web/src/api/workspace.ts @@ -60,6 +60,20 @@ export async function listWorkspaces(): Promise { }); } +/** + * Create a Workspace by name, for a Server where each person keeps their own + * (`capabilities.namedWorkspaces`). The caller owns it; it is not activated. + */ +export async function createNamedWorkspace( + name: string, +): Promise { + return apiFetch(routes.workspaces, { + method: 'POST', + json: { name }, + fallbackMessage: 'Failed to create Workspace', + }); +} + /** Activate a registered Workspace by stable identity. */ export async function activateWorkspace( workspaceId: string, diff --git a/apps/web/src/i18n/resources/en/common.json b/apps/web/src/i18n/resources/en/common.json index 4ee5149fa..98be7fa91 100644 --- a/apps/web/src/i18n/resources/en/common.json +++ b/apps/web/src/i18n/resources/en/common.json @@ -665,7 +665,15 @@ "clickToSwitch": "Click to switch", "openPathFailed": "Failed to open path", "activationTimeout": "Opening Home folder “{{path}}” took longer than {{seconds}} seconds. Check that the cloud or network drive is available, then try again.", - "activationInProgress": "Another Home folder is still opening. Please wait for it to finish." + "activationInProgress": "Another Home folder is still opening. Please wait for it to finish.", + "yourWorkspaces": "Your Workspaces", + "introNamed": "Choose a Workspace for your Spaces, notes, and artifacts, or create one.", + "newWorkspace": "New Workspace", + "namePlaceholder": "Name, then press Enter", + "create": "Create", + "current": "Current", + "named": "Workspace: {{workspace}}", + "namedPrefix": "Workspace: " }, "spaceHierarchy": { "collectAction": "Collect into child Space", diff --git a/apps/web/src/i18n/resources/zh-CN/common.json b/apps/web/src/i18n/resources/zh-CN/common.json index 1774c4f3d..4a806e6ae 100644 --- a/apps/web/src/i18n/resources/zh-CN/common.json +++ b/apps/web/src/i18n/resources/zh-CN/common.json @@ -665,7 +665,15 @@ "clickToSwitch": "点击切换", "openPathFailed": "打开路径失败", "activationTimeout": "打开“{{path}}”已超过 {{seconds}} 秒。请检查云盘或网络磁盘是否可用，然后重试。", - "activationInProgress": "另一个主目录仍在打开，请等待其完成。" + "activationInProgress": "另一个主目录仍在打开，请等待其完成。", + "yourWorkspaces": "你的工作区", + "introNamed": "选择一个工作区来保存你的 Space、笔记和产物，或新建一个。", + "newWorkspace": "新建工作区", + "namePlaceholder": "输入名称，然后按 Enter", + "create": "创建", + "current": "当前", + "named": "工作区：{{workspace}}", + "namedPrefix": "工作区：" }, "spaceHierarchy": { "collectAction": "收纳为子 Space", diff --git a/apps/web/src/pages/CanvasListPage.tsx b/apps/web/src/pages/CanvasListPage.tsx index 9ad63d815..92bedab33 100644 --- a/apps/web/src/pages/CanvasListPage.tsx +++ b/apps/web/src/pages/CanvasListPage.tsx @@ -77,6 +77,9 @@ export default function CanvasListPage() { const canChangeWorkspace = useWorkspaceStore( (s) => s.capabilities?.canChangeWorkspace ?? true, ); + const namedWorkspaces = useWorkspaceStore( + (s) => s.capabilities?.namedWorkspaces === true, + ); const setCanvasCount = useWorkspaceStore((s) => s.setCanvasCount); const setSpaceTitle = useWorkspaceStore((s) => s.setSpaceTitle); const workspaceSyncing = useWorkspaceStore((s) => s.isSyncing); @@ -284,7 +287,9 @@ export default function CanvasListPage() { {workspacePath ? t('workspace.pathPrefix') - : t('workspace.workspacePrefix')} + : namedWorkspaces + ? t('workspace.namedPrefix') + : t('workspace.workspacePrefix')} {workspaceLabel} @@ -297,7 +302,9 @@ export default function CanvasListPage() {
{workspacePath ? t('workspace.path', { path: workspacePath }) - : t('workspace.workspace', { workspace: workspaceLabel })} + : namedWorkspaces + ? t('workspace.named', { workspace: workspaceLabel }) + : t('workspace.workspace', { workspace: workspaceLabel })}
{t('canvasList.canvasCount', { count: canvases.length })}
{canChangeWorkspace && ( diff --git a/apps/web/src/pages/WorkspaceSetupPage.tsx b/apps/web/src/pages/WorkspaceSetupPage.tsx index 1d6648aa4..bdd64fb8b 100644 --- a/apps/web/src/pages/WorkspaceSetupPage.tsx +++ b/apps/web/src/pages/WorkspaceSetupPage.tsx @@ -1,7 +1,7 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -import { FolderOpen, X } from 'lucide-react'; +import { Check, FolderOpen, Layers, X } from 'lucide-react'; import { useState } from 'react'; import { useTranslation } from 'react-i18next'; import { Navigate, useNavigate } from 'react-router-dom'; @@ -9,6 +9,7 @@ import { Navigate, useNavigate } from 'react-router-dom'; import { WorkspaceLoadingScreen } from './WorkspaceLoadingScreen'; import { Button } from '../components/Common/Button'; import { PathInput } from '../components/Common/PathInput'; +import { TextInput } from '../components/Common/TextInput'; import { toast } from '../components/Common/Toast'; import { APP_NAME } from '../config/app'; import { useWorkspaceStore } from '../store/workspaceStore'; @@ -40,6 +41,10 @@ export default function WorkspaceSetupPage() { (s) => s.activateRecentWorkspace, ); const selectWorkspace = useWorkspaceStore((s) => s.selectWorkspace); + const createWorkspace = useWorkspaceStore((s) => s.createWorkspace); + const named = useWorkspaceStore( + (s) => s.capabilities?.namedWorkspaces === true, + ); const storeError = useWorkspaceStore((s) => s.error); // Managed mode: workspace is locked by the server, nothing to choose. @@ -64,23 +69,137 @@ export default function WorkspaceSetupPage() {

{t('workspace.welcome', { appName: APP_NAME })}

-

{t('workspace.intro')}

+

+ {t(named ? 'workspace.introNamed' : 'workspace.intro')} +

- navigate('/', { replace: true })} - /> + {named ? ( + navigate('/', { replace: true })} + /> + ) : ( + navigate('/', { replace: true })} + /> + )} ); } +// ────────────────────────────────────────────────────────────────────── +// Named Workspaces: each signed-in person's own, chosen and created by name +// ────────────────────────────────────────────────────────────────────── + +interface NamedSetupProps { + isSyncing: boolean; + workspaces: WorkspaceDescriptor[]; + activateWorkspace: (workspaceId: string) => Promise; + createWorkspace: (name: string) => Promise; + onActivated: () => void; +} + +function NamedSetup({ + isSyncing, + workspaces, + activateWorkspace, + createWorkspace, + onActivated, +}: NamedSetupProps) { + const { t } = useTranslation(); + const [name, setName] = useState(''); + + const run = async (action: () => Promise) => { + try { + await action(); + onActivated(); + } catch (error) { + console.error('[workspace-setup] Could not open Workspace:', error); + toast(useWorkspaceStore.getState().error ?? t('workspace.switchFailed'), { + tone: 'danger', + }); + } + }; + + const create = () => { + const trimmed = name.trim(); + if (trimmed) void run(() => createWorkspace(trimmed)); + }; + + return ( + <> + {workspaces.length > 0 && ( +
+
+ {t('workspace.yourWorkspaces')} +
+
    + {workspaces.map((workspace) => ( +
  • + +
    • + ))} +
+
+ )} + + +
+ setName(event.target.value)} + onKeyDown={(event) => { + if (event.key === 'Enter') create(); + }} + placeholder={t('workspace.namePlaceholder')} + disabled={isSyncing} + className="min-w-0 flex-1" + /> + +
+ + ); +} + // ────────────────────────────────────────────────────────────────────── // Free-mode UI // ────────────────────────────────────────────────────────────────────── diff --git a/apps/web/src/store/workspaceStore.test.ts b/apps/web/src/store/workspaceStore.test.ts index fd23fa5b3..9da059f15 100644 --- a/apps/web/src/store/workspaceStore.test.ts +++ b/apps/web/src/store/workspaceStore.test.ts @@ -39,6 +39,16 @@ vi.mock('../hooks/useElectron', async (importOriginal) => ({ })); const apiMocks = vi.hoisted(() => ({ + createNamedWorkspace: vi.fn(async (name: string) => { + const created = { + workspaceId: '33333333-3333-4333-8333-333333333333', + name, + path: null, + active: false, + }; + apiState.workspaces = [created, ...apiState.workspaces]; + return created; + }), getWorkspaceInfo: vi.fn(async () => apiState.info as WorkspaceInfo), listWorkspaces: vi.fn(async () => apiState.workspaces), activateWorkspace: vi.fn(async (workspaceId: string) => { @@ -75,6 +85,7 @@ vi.mock('../api/workspace', () => ({ getWorkspaceInfo: apiMocks.getWorkspaceInfo, listWorkspaces: apiMocks.listWorkspaces, activateWorkspace: apiMocks.activateWorkspace, + createNamedWorkspace: apiMocks.createNamedWorkspace, putWorkspacePath: apiMocks.putWorkspacePath, removeWorkspace: apiMocks.removeWorkspace, })); @@ -559,6 +570,34 @@ describe('workspaceStore registry persistence', () => { }); }); + it('keeps the Workspace the Server chose for this person', async () => { + apiState.info = { + ...unconfiguredInfo(), + configured: true, + workspaceId: FIRST_ID, + name: 'First', + capabilities: { + canChangeWorkspace: true, + nativePicker: false, + namedWorkspaces: true, + }, + }; + await expect(useWorkspaceStore.getState().init()).resolves.toBe(true); + // Their current Workspace has no path, and is already theirs. + expect(apiMocks.activateWorkspace).not.toHaveBeenCalled(); + expect(useWorkspaceStore.getState()).toMatchObject({ + workspaceId: FIRST_ID, + workspaceName: 'First', + isReady: true, + }); + + await useWorkspaceStore.getState().createWorkspace('Side project'); + expect(apiMocks.createNamedWorkspace).toHaveBeenCalledWith('Side project'); + expect(apiMocks.activateWorkspace).toHaveBeenCalledWith( + '33333333-3333-4333-8333-333333333333', + ); + }); + it('restores the first Workspace from server-owned MRU order', async () => { await expect(useWorkspaceStore.getState().init()).resolves.toBe(true); diff --git a/apps/web/src/store/workspaceStore.ts b/apps/web/src/store/workspaceStore.ts index 7a9a66e8e..fe440ccbb 100644 --- a/apps/web/src/store/workspaceStore.ts +++ b/apps/web/src/store/workspaceStore.ts @@ -8,6 +8,7 @@ import { ApiError } from '../api/_client'; import { listCanvases } from '../api/canvas'; import { activateWorkspace, + createNamedWorkspace, getWorkspaceInfo, listWorkspaces, putWorkspacePath, @@ -109,6 +110,8 @@ interface WorkspaceState { /** (Free mode) Activate a registered Workspace by stable identity. */ activateRecentWorkspace: (workspaceId: string) => Promise; + /** Create a Workspace by name and switch to it (`namedWorkspaces`). */ + createWorkspace: (name: string) => Promise; /** (Free mode) Unregister an inactive Workspace. */ removeRecentWorkspace: (workspaceId: string) => void; @@ -383,8 +386,12 @@ export const useWorkspaceStore = create()((set, get) => ({ } // ── Free mode ── - // Server already activated (e.g. another tab beat us to it). - const activated = info.configured && Boolean(info.path); + // Server already activated (e.g. another tab beat us to it). Where each + // person has their own Workspaces, the Server has already chosen the + // caller's current one, which carries no path. + const activated = + info.configured && + (Boolean(info.path) || info.capabilities.namedWorkspaces === true); let registered: WorkspaceDescriptor[] = []; try { @@ -484,6 +491,17 @@ export const useWorkspaceStore = create()((set, get) => ({ ); }, + createWorkspace: async (name: string) => { + if (get().mode === 'managed') { + throw new Error('Workspace is locked by the server (managed mode)'); + } + await changeWorkspace(async () => { + const created = await createNamedWorkspace(name); + await activateWorkspace(created.workspaceId); + return getWorkspaceInfo(); + }, name); + }, + removeRecentWorkspace: (workspaceId: string) => { void removeWorkspace(workspaceId) .then(() => From 6a79a200c8def09c22a37ed99dd9a888295a96be Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:48:01 +0800 Subject: [PATCH 08/17] chore: tidy imports and a test type after repository checks Co-Authored-By: Claude Opus 5.5 --- apps/server/src/modules/security/space-access.ts | 1 - apps/server/src/modules/storage/backends/disk/canvas-dirs.ts | 2 +- apps/server/src/modules/storage/backends/postgres/database.ts | 2 +- apps/server/src/modules/storage/backends/sqlite/database.ts | 2 +- apps/server/src/modules/workspace/scoped-routes.test.ts | 4 +++- 5 files changed, 6 insertions(+), 5 deletions(-) diff --git a/apps/server/src/modules/security/space-access.ts b/apps/server/src/modules/security/space-access.ts index 9ce61c387..eb421b171 100644 --- a/apps/server/src/modules/security/space-access.ts +++ b/apps/server/src/modules/security/space-access.ts @@ -10,7 +10,6 @@ import { import { UNRESTRICTED_ACCESS } from '../identity/service.js'; import type { AccessLevel } from '../identity/service.js'; - import type { FastifyInstance, FastifyRequest } from 'fastify'; declare module 'fastify' { diff --git a/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts b/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts index a29851646..3df520055 100644 --- a/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts +++ b/apps/server/src/modules/storage/backends/disk/canvas-dirs.ts @@ -23,7 +23,7 @@ import { toSafeFilename, } from '../../../../utils/naming.js'; import { spaceHierarchyShapeError } from '../../../canvas/persistence-validation.js'; -import { getWorkspaceDirectory, getWorkspacePath } from '../../../workspace.js'; +import { getWorkspacePath } from '../../../workspace.js'; export interface CanvasDirEntry { id: string; diff --git a/apps/server/src/modules/storage/backends/postgres/database.ts b/apps/server/src/modules/storage/backends/postgres/database.ts index cdf38b8e2..df312c9d8 100644 --- a/apps/server/src/modules/storage/backends/postgres/database.ts +++ b/apps/server/src/modules/storage/backends/postgres/database.ts @@ -2,10 +2,10 @@ // Licensed under the MIT license. import { Pool, type PoolClient, type PoolConfig } from 'pg'; -import { currentWorkspaceScope } from '../../../workspace/context.js'; import { POSTGRES_MIGRATIONS } from './schema.js'; import { createKeyedMutex } from '../../../../utils/keyed-mutex.js'; +import { currentWorkspaceScope } from '../../../workspace/context.js'; import { assertSpaceMutationAllowed, beginSpaceDeleteAdmission, diff --git a/apps/server/src/modules/storage/backends/sqlite/database.ts b/apps/server/src/modules/storage/backends/sqlite/database.ts index 106d504f8..92eac9b2f 100644 --- a/apps/server/src/modules/storage/backends/sqlite/database.ts +++ b/apps/server/src/modules/storage/backends/sqlite/database.ts @@ -20,10 +20,10 @@ import { mkdirSync } from 'node:fs'; import path from 'node:path'; import { DatabaseSync } from 'node:sqlite'; -import { currentWorkspaceScope } from '../../../workspace/context.js'; import { SQLITE_MIGRATIONS, type SqliteMigration } from './schema.js'; import { getDataDir } from '../../../../data-dir.js'; +import { currentWorkspaceScope } from '../../../workspace/context.js'; import { assertSpaceMutationAllowed, beginSpaceDeleteAdmission, diff --git a/apps/server/src/modules/workspace/scoped-routes.test.ts b/apps/server/src/modules/workspace/scoped-routes.test.ts index 2580c2957..534b945e9 100644 --- a/apps/server/src/modules/workspace/scoped-routes.test.ts +++ b/apps/server/src/modules/workspace/scoped-routes.test.ts @@ -15,6 +15,8 @@ import { resetStorageCache } from '../storage/index.js'; import { createWorkspace } from '../workspace-activation.js'; import { getWorkspaceHandle, setWorkspacePath } from '../workspace.js'; +import type { FastifyPluginAsync } from 'fastify'; + let tmp: string; let previousDataDir: string | undefined; beforeEach(() => { @@ -36,7 +38,7 @@ describe('Workspace-scoped routes', () => { it('run each call in the Workspace their prefix names', async () => { const other = await createWorkspace('Other'); const app = Fastify(); - const routes = async (scoped: typeof app) => { + const routes: FastifyPluginAsync = async (scoped) => { scoped.get('/where', async () => ({ workspaceId: getWorkspaceHandle()?.workspaceId, })); From 0116f51f5ef25393ecbb3b89d08c2fe583c20a1b Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:48:01 +0800 Subject: [PATCH 09/17] docs: describe per-person Workspaces and the new roles Fold PR A into the architecture docs: the Workspace/Space role model, Workspace-qualified Space grants and their migration, per-person current Workspaces, the Workspace routes for members, the per-call storage scope and the Workspace-scoped RFS URL. The proposal records what PR A built and what it deliberately left. Co-Authored-By: Claude Opus 5.5 --- docs/architecture/agent-reachback.md | 4 +-- docs/architecture/canvas-storage.md | 5 ++-- docs/architecture/deployment-security.md | 35 ++++++++++++++++++++---- docs/proposals/multi-user-service.md | 11 ++++---- 4 files changed, 40 insertions(+), 15 deletions(-) diff --git a/docs/architecture/agent-reachback.md b/docs/architecture/agent-reachback.md index 7b9e9a4be..d268ce8f0 100644 --- a/docs/architecture/agent-reachback.md +++ b/docs/architecture/agent-reachback.md @@ -20,7 +20,7 @@ The shipped design record is [`agent-reachback-rfs.md`](../proposals/agent-reach ## Canvas-scoped HTTP surface -All endpoints are mounted under `/api/rfs/:canvasId`; `HUABU_RFS_URL` already contains that canvas-scoped base. +All endpoints are mounted under `/api/rfs/:canvasId`, and again under `/api/rfs/w/:workspaceId/:canvasId`, where they run in that Workspace whatever the caller's current one; `HUABU_RFS_URL` already contains the Workspace- and canvas-scoped base. | Endpoint | Responsibility | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | @@ -112,7 +112,7 @@ Parent lineage is best effort. The route resolves `parentThreadId` or `X-Huabu-H ## External-agent bootstrap -Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent environment. `HUABU_RFS_URL` is derived from the deployment-owned root `HUABU_PUBLIC_ORIGIN` plus `/api/rfs/`; a loopback deployment with no configured public origin uses its actual bound port as the explicit local fallback. Network binds require a non-loopback public origin before the Server listens, so a remote Agentlet never receives a success-shaped Server-local loopback URL. Every external-agent Deployment persists `external-agent/system_prompt.md` as its initial preamble, including Deployments first created by mode, model, or configuration control requests; startup repair backfills older undelivered records that omitted it. Bootstrap owns authentication and entry routing: prefer `node "$HUABU_RFS_ENTRY" get-skill` when the Agent has compatible Node and an advertised entry; otherwise fetch authenticated HTTP `/skill`. Node is not provisioned or required for Space access. Public `/skill` is bootstrap documentation, not a substitute for authenticated Space instructions. Focused workflows remain authenticated `/skill/:id` resources and are loaded through `get-skill ID` or native HTTP. +Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent environment. `HUABU_RFS_URL` is derived from the deployment-owned root `HUABU_PUBLIC_ORIGIN` plus `/api/rfs/w//`, naming the Workspace the run started in so it keeps it after its starter switches; a loopback deployment with no configured public origin uses its actual bound port as the explicit local fallback. Network binds require a non-loopback public origin before the Server listens, so a remote Agentlet never receives a success-shaped Server-local loopback URL. Every external-agent Deployment persists `external-agent/system_prompt.md` as its initial preamble, including Deployments first created by mode, model, or configuration control requests; startup repair backfills older undelivered records that omitted it. Bootstrap owns authentication and entry routing: prefer `node "$HUABU_RFS_ENTRY" get-skill` when the Agent has compatible Node and an advertised entry; otherwise fetch authenticated HTTP `/skill`. Node is not provisioned or required for Space access. Public `/skill` is bootstrap documentation, not a substitute for authenticated Space instructions. Focused workflows remain authenticated `/skill/:id` resources and are loaded through `get-skill ID` or native HTTP. Huabu injects `HUABU_SERVICE_SDK_URL`, an absolute `file://` URL for its own SDK in `packages/client-runtime/dist/service-sdk.js` or the installed `client-runtime/service-sdk.js`. Generic Agentlet protects this explicit bootstrap key against session overrides but ships no SDK itself. No old `AGENTLET_SERVICE_SDK_URL` alias or fallback exists; refresh old downloaded entries and restart Agents. Entries obtain only current configuration leases, not Package code, and provider credentials remain absent from startup environment until requested. diff --git a/docs/architecture/canvas-storage.md b/docs/architecture/canvas-storage.md index ee5c840e7..3383275d0 100644 --- a/docs/architecture/canvas-storage.md +++ b/docs/architecture/canvas-storage.md @@ -183,7 +183,7 @@ All six structured/blob pairings are selectable: `validateStorageProfile()` admi `backends/postgres/database.ts` owns a `pg.Pool` per context, shared by `PostgresStructuredStore` and `PostgresWorkspaceRepository`. Defaults are four connections, a five-second connection timeout, and a thirty-second idle timeout; callers may supply `PoolConfig` overrides. Initialization applies contiguous versioned migrations in a transaction under a database advisory lock, recording the version in `huabu_schema_version`. A future schema fails without modification, and migration failure rolls back so initialization can be retried. Health runs a liveness query. Closing drains the context's queued transactions and ends its pool; operations on a closed or uninitialized context fail. A structured store closes a context it constructed, while an injected context remains its caller's responsibility. -The v1 schema has the same record families shown in the SQLite table above, using PostgreSQL identity columns, foreign-key cascades, uniqueness constraints, and JSON-validating text columns. Shared `backends/sql/` codecs and rules own JSON serialization, identity/name validation, collision allocation, and Task/Run transitions; SQL dialect and migration history stay adapter-owned. Parameter values are bound. Workspace activation changes the context's active identity without reopening its pool; retained Space handles and queued operations reject an inactive Workspace. Forgetting a Workspace marks its membership row without deleting data. `ensureDefault()` reuses a registered Workspace or creates one if no registered Workspace remains, including after the last one was forgotten. +The v1 schema has the same record families shown in the SQLite table above, using PostgreSQL identity columns, foreign-key cascades, uniqueness constraints, and JSON-validating text columns. Shared `backends/sql/` codecs and rules own JSON serialization, identity/name validation, collision allocation, and Task/Run transitions; SQL dialect and migration history stay adapter-owned. Parameter values are bound. Workspace activation changes the context's active identity without reopening its pool; retained Space handles and queued operations reject an inactive Workspace. A call running in a Workspace scope (`modules/workspace/context.ts`, used in Bubble mode) reads that Workspace instead, per call, so concurrent calls in different Workspaces share the pool without sharing a namespace; transactions bind it when they open, and the one database-wide write order still applies. Forgetting a Workspace marks its membership row without deleting data. `ensureDefault()` reuses a registered Workspace or creates one if no registered Workspace remains, including after the last one was forgotten. Structured mutations run in native transactions with a five-second lock timeout and a database-wide transaction advisory lock. This conservative write order makes CAS, label allocation, Task/Run mutation, and node → Space record → delta batches atomic across independent pools. SQL failures roll back; failed rollback discards the connection, and a failed operation does not poison the next queued writer. Reads use the pool directly; bulk node reads use bounded batches, and streaming supports cancellation. @@ -241,7 +241,7 @@ Space deletion is serialized against composed blob puts by a writer-preferring a Cross-Space Move is an application-level compensated operation, not a new storage transaction. It holds an active-Workspace lease and both Canvas write mutexes, optionally creates a named destination Space, copies every referenced Blob to a fresh destination key before structural mutation, commits the destination Space, closes and rehomes eligible dormant Agent conversations under their turn leases, then deletes the source selection and optionally creates a `spacePreview` breadcrumb in one source executor batch. A determinate later failure rehomes completed conversations back before applying inverse source and destination deltas; after successful compensation, a request-created destination and its blobs are removed. Unknown Agenetes outcomes or compensation failures retain both Spaces for reconciliation and never trigger automatic destination deletion. Failure to remove a new destination after a determinate failure is surfaced explicitly rather than reported as an ordinary rejected move. BlobScope intentionally has no per-key deletion, so a failed move into an existing Space may leave freshly copied unreferenced blobs until that Space is deleted; referenced source blobs are retained because the source Space may still contain other references. The guarantee remains all-or-compensated while the Server continues running and receives determinate backend outcomes, matching the existing `SpaceHandle.write()` boundary. -Retained Disk Space repository and handle instances, blob scopes, and legacy `CanvasStore` instances reject use after the active Workspace changes. Each `spaces()` call returns a fresh Workspace-bound handle and each read rescans current Disk state. The Workspace-qualified LRU is cleared and rebuilt on the next lookup after a switch. The delete-session contract covers overlapping operations through one configured backend instance. Disk realizes it with the shared process-local coordinator; it is not a multi-process transaction or distributed lock, and a SQL adapter must supply an equivalent backend-instance fence using its own mechanisms. +Retained Disk Space repository and handle instances, blob scopes, and legacy `CanvasStore` instances reject use after the active Workspace changes. Every Workspace getter answers for the Workspace the call runs in: its scope where one is open, else the process-active one. The Disk directory index is kept per Workspace folder and the SQL World id per Workspace, so several Workspaces are served side by side; operation leases count per Workspace. Each `spaces()` call returns a fresh Workspace-bound handle and each read rescans current Disk state. The Workspace-qualified LRU is cleared and rebuilt on the next lookup after a switch. The delete-session contract covers overlapping operations through one configured backend instance. Disk realizes it with the shared process-local coordinator; it is not a multi-process transaction or distributed lock, and a SQL adapter must supply an equivalent backend-instance fence using its own mechanisms. The `chat_v2/` two-tier log and `threads.json` remain owned by Agenetes L2 (`FileEventLogStore`, SQLite-backed `FileTurnStore`, and `FileThreadStore`), wired in [agenetes/drivers.ts](../../apps/server/src/modules/agent/agenetes/drivers.ts); see [agent-architecture.md](./agent-architecture.md) §5. Workspace activation is coordinated by `apps/server/src/modules/workspace-activation.ts`; the isolated child entry is `workspace-prepare.worker.ts`, and the ordered migration sequence is centralized in `workspace-prepare.ts` with migration implementations under `modules/workspace/migrations/`. @@ -319,6 +319,7 @@ An explicit title rename is resolved before the protected node → record → de | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [storage/index.ts](../../apps/server/src/modules/storage/index.ts) | Portable Space facade and storage composition exports | | [structured.ts](../../apps/server/src/modules/storage/ports/structured.ts) | Space, node, and ordered-write ports | +| [workspace/context.ts](../../apps/server/src/modules/workspace/context.ts) | The Workspace a request or background job runs in | | [write-coordinator.ts](../../apps/server/src/modules/canvas/write-coordinator.ts) | Per-Canvas non-reentrant application mutex | | [canvas-executor.ts](../../apps/server/src/modules/canvas/canvas-executor.ts) | Editable command/inverse composition and ordered persistence | | [import-space-identity.ts](../../apps/server/src/modules/canvas/import-space-identity.ts) | Staged bundle identity discovery and storage migration | diff --git a/docs/architecture/deployment-security.md b/docs/architecture/deployment-security.md index 728bd19a9..505fbabfd 100644 --- a/docs/architecture/deployment-security.md +++ b/docs/architecture/deployment-security.md @@ -74,7 +74,7 @@ Bubble owns credential validation, its durable principal directory, issuer/subje `HUABU_BUBBLE_AUTH` is Bubble's ordered authenticator list as JSON, passed to Bubble unchanged; Bubble validates it at startup and a rejected list stops the Server. Every driver Bubble ships is therefore available: `local-token`, `master-key`, `auth0`, `entra`, and `default`. When unset, it is `[{"driver":"local-token"}]`. `master-key` must come last because it claims every Bearer token. Its key is a system-owner credential, and the embedded Agentlet and its agents inherit every environment variable outside the `HUABU_` namespace, so Huabu refuses to start when `BUBBLE_MASTER_KEY` is set or a `master-key` entry would read it: give the entry `"masterKeyEnvVar": "HUABU_BUBBLE_MASTER_KEY"` (any `HUABU_` variable) or an inline `masterKey`. `default` treats the Bearer text as the principal ID without verifying anything; Huabu refuses it when `HUABU_BIND_HOST` is not loopback. -Huabu authorizes its own routes with two permissions, which it adds to Bubble's core roles through the `coreRoleCapabilities` of Bubble's host `authz` model and checks on Bubble's `system` target with Bubble's policy. `huabu.use` admits a principal to Huabu and is carried by the `member` and `owner` roles. `huabu.manage` is the owner authority for Settings, OAuth, credential, External Agent Profile and similar routes, and is carried by `owner` only. So a system `member` grant makes a Huabu member, a system `owner` grant a Huabu owner; no other role, and no grant on a thread or principal, confers either. A principal with neither can inspect only `GET /api/identity`; other routes return 403 `ACCESS_REQUIRED`. A member reaches every route that does not itself require an owner. The local provider's principal always holds both. In Bubble a system grant also carries that role's Bubble authority over every thread. Bubble's first-user owner auto-grant is always off. `HUABU_BUBBLE_OWNER` names one principal that startup provisions as system owner, creating it when missing without an external identity. That suits a master-key caller: set the `master-key` entry's `defaultPrincipalId` to the same ID. Provisioning only adds; removing the variable does not revoke a stored grant. Owners authenticated by Auth0 or Entra receive their principal at first login, so an existing owner grants them `owner` on `system` through Bubble afterwards. +Huabu authorizes its own routes with two system permissions, which it adds to Bubble's core roles through the `coreRoleCapabilities` of Bubble's host `authz` model and checks on Bubble's `system` target with Bubble's policy. `huabu.use` admits a principal to Huabu and is carried by the `member` and `owner` roles. `huabu.admin` is the owner authority for Settings, OAuth, credential, External Agent Profile, folder Workspace and similar routes, and is carried by `owner` only. So a system `member` grant makes a Huabu member, a system `owner` grant a Huabu owner; no other role, and no grant on a thread or principal, confers either. A principal with neither can inspect only `GET /api/identity`; other routes return 403 `ACCESS_REQUIRED`. A member reaches every route that does not itself require an owner. The local provider's principal always holds both. In Bubble a system grant also carries that role's Bubble authority over every thread. Bubble's first-user owner auto-grant is always off. `HUABU_BUBBLE_OWNER` names one principal that startup provisions as system owner, creating it when missing without an external identity. That suits a master-key caller: set the `master-key` entry's `defaultPrincipalId` to the same ID. Provisioning only adds; removing the variable does not revoke a stored grant. Owners authenticated by Auth0 or Entra receive their principal at first login, so an existing owner grants them `owner` on `system` through Bubble afterwards. Bubble issues local tokens to bot principals only. An owner creates the bot and its token through Bubble's API, and the bot reaches Huabu's routes once it also holds the system-owner grant: @@ -93,15 +93,36 @@ Long-lived Bubble-authenticated HTTP responses, including existing SSE streams, ### Workspace and Space access -Huabu declares its own permission model to Bubble as host targets and roles, so grants live in Bubble's table and Bubble's policy answers every check. There are two target kinds: `huabu.workspace`, and `huabu.space`, whose parent is its parent Space or, for a root Space, its Workspace. Two roles carry `huabu.space.read` and `huabu.space.write`: `huabu.workspace.owner`, granted on a Workspace, and `huabu.space.owner`, granted on a Space. Both capabilities inherit downward along that parent chain, so a Workspace owner may use every Space in it and a Space owner may use that Space and every Space inside it. A system `owner` holds every Huabu capability everywhere, which is Bubble's root rule. Both ownership roles are managed by `huabu.manage`, so only a system owner grants or revokes them, for example `{"target":{"type":"huabu.workspace","id":""},"principalId":"dave","role":"huabu.workspace.owner"}` posted to `/bubble/v1/grants`. A member cannot share a Space with another member; that is deliberate for this stage. +Huabu declares its own permission model to Bubble as host targets and roles, so grants live in Bubble's table and Bubble's policy answers every check. There are two target kinds: `huabu.workspace`, named by Workspace id, and `huabu.space`, named `:` so that a grant never reaches a Space of the same id in another Workspace. A Space's parent is its parent Space or, for a root Space, its own Workspace. Three capabilities apply on both kinds and flow down that chain, never up or sideways: -Creating a Space makes its creator its `huabu.space.owner`. A selection move into a new Space claims it right after creating it, before any content leaves the source, so a failed claim is compensated like any other move failure. A move also requires read access to every Space whose artifact a moved node cites before copying it into the destination. That covers `POST /api/canvas`, bundle import, moving a selection into a new Space, adding a child Space, and detaching a Space to the root, where it no longer inherits from a parent. A Space created by an agent through the machine credential is claimed by nobody and is reachable only through Workspace or system ownership. +| Capability | Allows | +| -------------- | ----------------------------------------------------------------------------- | +| `huabu.read` | Seeing and opening the Workspace or Space, every `GET`, search, live streams. | +| `huabu.write` | Editing Spaces and creating them. | +| `huabu.manage` | Renaming and deleting it, and granting roles on it. | -One `preHandler` authorizes every request that names a Space before its route runs. The Space is the `canvasId` route parameter, query field or body field; when more than one is given they must agree, and conflicting, repeated or non-string ids answer 400 `SPACE_ACCESS_AMBIGUOUS`, so a handler never reads a different Space from the one authorized. A request that also names another Space is checked against both: the destination of a selection move, the new parent of a re-parent, the target of a conversation fork (write), and the source of an artifact clone (read). Safe methods need read and other methods need write; the few `POST` routes that only read declare it. A Space the caller may not read answers 404, exactly like a missing one, and one it may only read answers 403 `SPACE_ACCESS_REQUIRED` to a write. Agents and conversations are owner-only for now: a member gets 403 `AGENT_ACCESS_REQUIRED` from every `/api/agent`, `/api/acp`, `/api/agent-change-review` and `/api/rfs` route, from any route that declares `invokesAgent` (Interactive View actions), and from any request that names a thread, because an agent acts through the shared machine credential. RFS is that credential's own surface — it launches agents and Task Runs and leases shared service credentials — and the web app never calls it. For the same reason a member's edits never count towards the memory worker, which runs an agent over Workspace-wide memory and Skills, and a member's node preprocessing runs without LLM enrichment. That preprocessing also fetches only from public addresses: inside its run every outbound request, each redirect hop included, refuses at connect time any loopback, private, link-local, carrier-grade NAT or other non-public address (`modules/security/outbound.ts`), and the desktop fetch fallback is skipped. The Space list and Space cards omit or report as missing what the caller may not read. World is an ordinary Space under its Workspace, so only Workspace and system owners reach it. +| Role | Granted on | Gives | +| ------------------------ | ----------- | -------------------------------------------------- | +| `huabu.workspace.owner` | a Workspace | read, write, manage | +| `huabu.workspace.editor` | a Workspace | read, write | +| `huabu.workspace.viewer` | a Workspace | read | +| `huabu.space.owner` | a Space | read, write, manage on it and the Spaces inside it | -Workspaces are still activated one at a time for the whole Server. Listing, creating, renaming, removing or activating Workspaces, and changing the active one, is therefore owner-only, and Bubble mode's Postgres backend offers no Workspace switching in the UI. Only Spaces of the active Workspace exist for authorization; a Space of another Workspace is denied. Serving several Workspaces side by side is the next phase. +A system `owner` holds every Huabu capability everywhere, which is Bubble's root rule. Every role on a Workspace or Space is granted with `huabu.manage` there, so whoever owns a Workspace or Space may share it, for example `{"target":{"type":"huabu.workspace","id":""},"principalId":"dave","role":"huabu.workspace.viewer"}` posted to `/bubble/v1/grants`; system roles stay with system owners. A Workspace or Space grant alone does not admit anyone: admission still needs `huabu.use`. On startup, Space grants that name a Space by id alone, as the first Bubble release wrote them, are rewritten to name the Workspace holding that Space, and dropped when no Workspace does. -The local provider's owner and the Agentlet machine credential pass every Space check. An agent therefore acts with the machine credential's full RFS reach, which is why only owners may run one until credentials carry the caller's own authority. Workspace-level state such as `setting/user.md` memory and user Skills is shared by everyone in the Workspace. Each request authenticates once and answers all its checks from one Bubble policy scope, one grant load and one ancestry walk per Space. +Creating a Space makes its creator its `huabu.space.owner`. A selection move into a new Space claims it right after creating it, before any content leaves the source, so a failed claim is compensated like any other move failure. A move also requires read access to every Space whose artifact a moved node cites before copying it into the destination. That covers `POST /api/canvas`, bundle import, moving a selection into a new Space, adding a child Space, and detaching a Space to the root, where it no longer inherits from a parent. A Space created by an agent through the machine credential is claimed by nobody and is reachable through its Workspace or system ownership. + +One `preHandler` authorizes every request that names a Space before its route runs. The Space is the `canvasId` route parameter, query field or body field, in the Workspace the request runs in; when more than one is given they must agree, and conflicting, repeated or non-string ids answer 400 `SPACE_ACCESS_AMBIGUOUS`, so a handler never reads a different Space from the one authorized. A request that also names another Space is checked against both: the destination of a selection move, the new parent of a re-parent, the target of a conversation fork (write), and the source of an artifact clone (read). Safe methods need read and other methods need write; the few `POST` routes that only read declare it, and renaming or deleting a Space declares manage. A Space the caller may not read answers 404, exactly like a missing one, and one it may read but not change answers 403 `SPACE_ACCESS_REQUIRED`. Agents and conversations are owner-only for now: a member gets 403 `AGENT_ACCESS_REQUIRED` from every `/api/agent`, `/api/acp`, `/api/agent-change-review` and `/api/rfs` route, from any route that declares `invokesAgent` (Interactive View actions), and from any request that names a thread, because an agent acts through the shared machine credential. RFS is that credential's own surface — it launches agents and Task Runs and leases shared service credentials — and the web app never calls it. For the same reason a member's edits never count towards the memory worker, which runs an agent over Workspace-wide memory and Skills, and a member's node preprocessing runs without LLM enrichment. That preprocessing also fetches only from public addresses: inside its run every outbound request, each redirect hop included, refuses at connect time any loopback, private, link-local, carrier-grade NAT or other non-public address (`modules/security/outbound.ts`), and the desktop fetch fallback is skipped. The Space list and Space cards omit or report as missing what the caller may not read. World is an ordinary Space under its Workspace, so only those who may read the Workspace reach it. + +The local provider's owner and the Agentlet machine credential pass every Space check. An agent therefore acts with the machine credential's full RFS reach, which is why only owners may run one until credentials carry the caller's own authority. Workspace-level state such as `setting/user.md` memory and user Skills is shared by everyone in a Workspace. Each request authenticates once and answers all its checks from one Bubble policy scope, one grant load and one ancestry walk per Space. + +### Workspaces per person + +In Bubble mode each request runs in its caller's own current Workspace, so several people work in different Workspaces of one Server at once; local mode keeps one process-active Workspace for everyone. Admission chooses it after authentication: the caller's stored current Workspace while they may still enter it, else the first Workspace they may enter, which becomes current. The current Workspace is a per-principal row in the `huabu_identity.current_workspaces` table of `HUABU_POSTGRES_URL`, referencing Bubble's principal ID. A member who may enter no Workspace gets a personal one, "'s Workspace", owned by them, on their first admitted request; concurrent first requests in one process create one. A caller may enter a Workspace they hold a Workspace role on, or one holding a Space they hold a role on; a system owner may enter any, and lands first on the process-active one. The choice is carried through the request and everything it starts in an `AsyncLocalStorage` scope (`modules/workspace/context.ts`), which the Workspace getters, the storage backends' per-call namespace and the identity checks read; see [Multi-backend storage](./canvas-storage.md). + +`/api/workspaces` then acts for the caller alone. It lists the Workspaces they may enter, `active` marking their current one. `POST` with a `name` creates a Workspace they own, wherever the backend keeps one: a row on SQL backends, a folder under the data directory on Disk. Activating sets only their current Workspace. Renaming and unregistering need `huabu.manage` on that Workspace, and unregistering refuses a Workspace with work in flight or the process-active one; a person whose current Workspace was unregistered moves on at their next request. Folder Workspaces stay with system owners, from localhost, as do `/api/workspace` folder picking and path validation, because they name places on the Server's filesystem; members never receive a Workspace path. `GET /api/workspace` reports `capabilities.namedWorkspaces`, and the web app then switches and creates Workspaces by name. + +An agent run keeps the Workspace it started in: its reachback URL is `/api/rfs/w//`, and the RFS routes under that prefix run in that Workspace whatever its starter or the process does later. ### Browser sign-in @@ -154,6 +175,8 @@ The Desktop remote-client path uses the operating system's normal certificate va | [`apps/server/src/security/private-config.ts`](../../apps/server/src/security/private-config.ts) | Instance-specific private directory and automatic standalone master-key lifecycle. | | [`apps/server/src/modules/security/deployment-config.ts`](../../apps/server/src/modules/security/deployment-config.ts) | Resolve and fail closed on invalid bind, allowed-host, and Basic Auth combinations. | | [`apps/server/src/modules/identity/bubble.ts`](../../apps/server/src/modules/identity/bubble.ts) | Declare Huabu's Workspace and Space targets, roles and inheritance to Bubble. | +| [`apps/server/src/modules/identity/workspace-selection.ts`](../../apps/server/src/modules/identity/workspace-selection.ts) | Each Bubble request's Workspace: the caller's current one, or a personal one. | +| [`apps/server/src/modules/workspace/scoped-routes.ts`](../../apps/server/src/modules/workspace/scoped-routes.ts) | RFS served in the Workspace an agent run started in. | | [`apps/server/src/modules/security/space-access.ts`](../../apps/server/src/modules/security/space-access.ts) | Authorize every Space a request names; claim created Spaces. | | [`apps/server/src/modules/identity/http.ts`](../../apps/server/src/modules/identity/http.ts) | Admit callers and carry a browser's Bearer credential in its session cookie. | | [`apps/web/src/components/Shell/SignInGate.tsx`](../../apps/web/src/components/Shell/SignInGate.tsx) | Sign the browser in through Bubble's discovered provider before the app mounts. | diff --git a/docs/proposals/multi-user-service.md b/docs/proposals/multi-user-service.md index dc783d726..7e3ae3147 100644 --- a/docs/proposals/multi-user-service.md +++ b/docs/proposals/multi-user-service.md @@ -1,6 +1,6 @@ # Multi-User Service -Status: Proposed +Status: In-Progress — PR A implemented, PR B proposed Last updated: 2026-10-28 Follows PR #237 (Bubble identity and per-user Space access) toward issue #228. Two stacked pull requests take one Huabu Server from "several people sign in and each edits their own Spaces in one shared Workspace" to a service several people can use day to day: each person has their own Workspaces, uses agents in them, and an operator admits people without scripts. @@ -31,7 +31,7 @@ Each request runs in exactly one Workspace, resolved once in admission and carri How the Workspace is chosen: - **Local mode:** the process-active Workspace, as today. Switching still changes it for every client, because local mode has one person. -- **Bubble mode:** the principal's _current Workspace_, a per-principal preference stored in Huabu (`principal_preferences`, referencing Bubble's `principalId`, as #228 proposes). Switching changes only that preference. It must be a Workspace the principal can read (`huabu.workspace.read`, new), else admission falls back to their personal Workspace. +- **Bubble mode:** the principal's _current Workspace_, a per-principal row stored in Huabu (`huabu_identity.current_workspaces`, referencing Bubble's `principalId`, as #228 proposes). Switching changes only that row. It must be a Workspace the principal may enter, else admission falls back to the first one they may enter, or a new personal Workspace. A per-principal preference rather than a Workspace header keeps images, frames, downloads and EventSource working without changes, since they cannot set headers. The cost is that one person's tabs share one current Workspace, which is also the behavior today. Per-tab Workspaces would need the Workspace in every URL and are not planned. @@ -40,10 +40,11 @@ Work that outlives the request (agents, memory updates, Task Runs, preprocessing ### Storage - **SQL namespaces per call, not per connection.** `useWorkspace()` mutates the one Postgres/SQLite connection's namespace today, so concurrent Workspaces would read each other's Spaces. The structured store reads the Workspace id from the context per query, and transactions bind it when they open. The one database-wide write order (`pg_advisory_xact_lock(WRITE_LOCK)`) stays: it also covers name allocation and the Workspace registry. A per-Workspace lock is a later throughput change. -- **Per-Workspace state.** The World id, canvas-dirs index, user-skill cache, external-note sessions and the Space-create and hierarchy chains move into a `WorkspaceRuntime` (`modules/workspace/runtime.ts`, new), created on first use per Workspace and evicted when idle. The process-wide reset hooks (`refreshCanvasDirIndex`, `invalidateUserSkill`, `resetExternalNoteSessions`) become methods on it. +- **Per-Workspace state.** The SQL World id and the Disk directory index are kept per Workspace. The user-skill cache rebuilds whenever the calling Workspace differs, which is correct and costs only a rescan. The Space-create and hierarchy chains stay process-wide: they serialize, which costs throughput, not correctness. Queues that outlive a request (memory passes, World-preview reconciliation, preprocessing) run each item in its enqueuer's scope, because they chain promises from the enqueuing call. - **Leases.** `acquireWorkspaceOperationLease()` counts per Workspace. It still stops a local-mode switch or a Workspace delete from stranding in-flight work, and no longer refuses a second live Workspace. -- **Blob prefixes use the Workspace id.** Azure blobs are prefixed by `getWorkspaceKey()`, which on Disk is the folder _path_, so moving a folder orphans them. This becomes the Workspace id, with a one-time copy-forward on first open. -- **Maps keyed by Space id alone** (canvas mutex, SSE listeners, memory worker, dir handles, tombstones, Agenetes turn owners) stay as they are. Space ids are random UUIDs or `createId('canvas')` and imports mint new ids. Workspace creation refuses a Disk folder whose Space ids collide with a live Workspace's. +- **Maps keyed by Space id alone** (canvas mutex, SSE listeners, memory worker, dir handles, tombstones, Agenetes turn owners) stay as they are. Space ids are random UUIDs or `createId('canvas')`, imports mint new ids, and personal Workspaces start empty. The one way to repeat an id is an administrator adopting a copy of a Disk folder as a second Workspace; that is a known limitation, not guarded. + +Not changed: Azure blobs are still prefixed by the Workspace key, which on Disk is the folder path. That predates this work and does not affect several people working at once. ### Roles and capabilities From 53058b726e40a313b0d24314c851c17fb069799b Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 17:53:35 +0800 Subject: [PATCH 10/17] feat(identity): administer people through /api/people A Bubble administrator can list every principal with their system and Workspace roles, admit or revoke a member, and give or remove a Workspace role, without scripts against Bubble's API. Revoking one's own access is refused. Changes apply on the next request. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/app.ts | 5 + apps/server/src/modules/identity/bubble.ts | 98 ++++++++++++++++++- apps/server/src/modules/identity/index.ts | 11 +++ .../modules/identity/multi-user.scenarios.ts | 66 ++++++++++++- .../src/modules/identity/people.route.ts | 85 ++++++++++++++++ apps/server/src/modules/identity/service.ts | 27 ++++- packages/shared/src/types/api/identity.ts | 30 ++++++ 7 files changed, 316 insertions(+), 6 deletions(-) create mode 100644 apps/server/src/modules/identity/people.route.ts diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts index a0ddcdab5..c1c06a23c 100644 --- a/apps/server/src/app.ts +++ b/apps/server/src/app.ts @@ -42,6 +42,7 @@ import { resetExternalNoteSessions } from './modules/canvas/external-watcher.js' import externalNoteRoutes from './modules/canvas/external.route.js'; import syncRoutes from './modules/canvas/sync.route.js'; import { createIdentity, registerIdentity } from './modules/identity/index.js'; +import peopleRoutes from './modules/identity/people.route.js'; import integrationsRoutes from './modules/integrations/integrations.route.js'; import interactiveViewRoutes from './modules/interactive-view/interactive-view.route.js'; import rfsRoutes from './modules/remote_fs/rfs.route.js'; @@ -145,6 +146,10 @@ registerIdentity(app, { // An embedded Bubble serves its own API beside Huabu's, behind the same host, // origin and rate-limit guards; clients address it as `/bubble`. if (identity.bubble) app.register(identity.bubble, { prefix: '/bubble' }); +app.register(peopleRoutes, { + prefix: '/api/people', + service: identity.service, +}); // Register @fastify/static to enable `reply.sendFile()`. // Actual artifact serving uses a dynamic root resolved at request time diff --git a/apps/server/src/modules/identity/bubble.ts b/apps/server/src/modules/identity/bubble.ts index 9596cc1e9..c9da3b584 100644 --- a/apps/server/src/modules/identity/bubble.ts +++ b/apps/server/src/modules/identity/bubble.ts @@ -18,6 +18,7 @@ import { import { identityPrincipalSchema } from '@huabu/shared'; + import { getWorkspaceHandle } from '../workspace.js'; import { IdentityError } from './service.js'; import { @@ -29,8 +30,10 @@ import type { WorkspacePreferences } from './preferences.js'; import type { HuabuResource, IdentityService, + PeopleDirectory, ResourceDirectory, } from './service.js'; +import type { WorkspaceRole } from '@huabu/shared'; import type { BubbleAuthzOptions, BubbleStore, @@ -57,6 +60,92 @@ const CAPABILITY = { const { read: READ, write: WRITE, manage: MANAGE } = CAPABILITY; const TARGET = { workspace: 'huabu.workspace', space: 'huabu.space' } as const; const SPACE_OWNER = 'huabu.space.owner'; +const WORKSPACE_ROLE = { + owner: 'huabu.workspace.owner', + editor: 'huabu.workspace.editor', + viewer: 'huabu.workspace.viewer', +} as const satisfies Record; + +/** People administration over Bubble's principal and grant tables. */ +function bubblePeople(store: BubbleStore): PeopleDirectory { + const SYSTEM = { type: 'system' } as const; + const roleOf = (role: string): WorkspaceRole | null => + (Object.keys(WORKSPACE_ROLE) as WorkspaceRole[]).find( + (key) => WORKSPACE_ROLE[key] === role, + ) ?? null; + return { + async list() { + const [principals, grants] = await Promise.all([ + store.principals.list(), + store.grants.list(), + ]); + return principals.map((principal) => { + const held = grants.filter( + (grant) => grant.principalId === principal.principalId, + ); + const system = held.filter((grant) => grant.target.type === 'system'); + const workspaces = new Map(); + for (const grant of held) { + const role = roleOf(grant.role); + if ( + grant.target.type === TARGET.workspace && + 'id' in grant.target && + role + ) + workspaces.set(grant.target.id, role); + } + return { + principal: identityPrincipalSchema.parse({ + principalId: principal.principalId, + kind: principal.kind, + ...(principal.displayName + ? { displayName: principal.displayName } + : {}), + ...(principal.email ? { email: principal.email } : {}), + ...(principal.avatarUrl ? { avatarUrl: principal.avatarUrl } : {}), + }), + member: system.some((grant) => grant.role === 'member'), + admin: system.some((grant) => grant.role === 'owner'), + workspaces: [...workspaces].map(([workspaceId, role]) => ({ + workspaceId, + role, + })), + }; + }); + }, + async setMember(principalId, member, by) { + if (!(await store.principals.get(principalId))) return false; + const rows = await store.grants.list({ target: SYSTEM, principalId }); + const current = rows.filter((row) => row.role === 'member'); + if (member && current.length === 0) + await store.grants.add({ + target: SYSTEM, + principalId, + role: 'member', + grantedByPrincipalId: by, + }); + if (!member) + for (const row of current) await store.grants.remove(row.grantId); + return true; + }, + async setWorkspaceRole(principalId, workspaceId, role, by) { + if (!(await store.principals.get(principalId))) return false; + const target = { type: TARGET.workspace, id: workspaceId }; + const rows = await store.grants.list({ target, principalId }); + for (const row of rows) + if (roleOf(row.role) && row.role !== (role && WORKSPACE_ROLE[role])) + await store.grants.remove(row.grantId); + if (role && !rows.some((row) => row.role === WORKSPACE_ROLE[role])) + await store.grants.add({ + target, + principalId, + role: WORKSPACE_ROLE[role], + grantedByPrincipalId: by, + }); + return true; + }, + }; +} /** * A Space's Bubble target names its Workspace too, so a Space can later be @@ -107,17 +196,17 @@ function huabuAuthz(resources: ResourceDirectory): BubbleAuthzOptions { // Granting a role on a Workspace or Space takes `huabu.manage` there, so // an owner can share what they own; nothing here grants system roles. roles: { - 'huabu.workspace.owner': { + [WORKSPACE_ROLE.owner]: { grantableOn: [TARGET.workspace], capabilities: [READ, WRITE, MANAGE], managementCapability: MANAGE, }, - 'huabu.workspace.editor': { + [WORKSPACE_ROLE.editor]: { grantableOn: [TARGET.workspace], capabilities: [READ, WRITE], managementCapability: MANAGE, }, - 'huabu.workspace.viewer': { + [WORKSPACE_ROLE.viewer]: { grantableOn: [TARGET.workspace], capabilities: [READ], managementCapability: MANAGE, @@ -234,6 +323,7 @@ export async function openBubbleIdentity(options: { service: { provider: 'bubble', challenge: 'Bearer realm="Huabu"', + people: bubblePeople(store), selectWorkspace: (identity) => selectRequestWorkspace(identity, preferences, options.resources), chooseWorkspace: (identity, workspaceId) => @@ -301,7 +391,7 @@ export async function openBubbleIdentity(options: { role: resource.type === 'space' ? SPACE_OWNER - : 'huabu.workspace.owner', + : WORKSPACE_ROLE.owner, grantedByPrincipalId: principalId, }); }, diff --git a/apps/server/src/modules/identity/index.ts b/apps/server/src/modules/identity/index.ts index 630f72a55..72477062d 100644 --- a/apps/server/src/modules/identity/index.ts +++ b/apps/server/src/modules/identity/index.ts @@ -50,6 +50,17 @@ export function createIdentity( challenge: 'Bearer realm="Huabu"', authenticate: async (credentials) => (await (opening ??= open())).service.authenticate(credentials), + // Present from the start so routes can tell Bubble mode by it; each call + // opens Bubble on demand like every other member here. + people: { + list: async () => (await (opening ??= open())).service.people!.list(), + setMember: async (...args) => + (await (opening ??= open())).service.people!.setMember(...args), + setWorkspaceRole: async (...args) => + (await (opening ??= open())).service.people!.setWorkspaceRole( + ...args, + ), + }, selectWorkspace: async (identity) => (await (opening ??= open())).service.selectWorkspace!(identity), chooseWorkspace: async (identity, workspaceId) => diff --git a/apps/server/src/modules/identity/multi-user.scenarios.ts b/apps/server/src/modules/identity/multi-user.scenarios.ts index 8fa141b25..152426824 100644 --- a/apps/server/src/modules/identity/multi-user.scenarios.ts +++ b/apps/server/src/modules/identity/multi-user.scenarios.ts @@ -9,6 +9,7 @@ import { afterEach, describe, expect, it } from 'vitest'; import { openBubbleIdentity } from './bubble.js'; import { registerIdentity } from './http.js'; +import peopleRoutes from './people.route.js'; import { createMemoryWorkspacePreferences } from './preferences.js'; import { storageResourceDirectory } from './resources.js'; import canvasRoutes from '../canvas/canvas.route.js'; @@ -68,11 +69,15 @@ async function host() { registerSpaceAccess(app); await app.register(canvasRoutes, { prefix: '/api/canvas' }); await app.register(workspaceRoutes, { prefix: '/api/workspace' }); + await app.register(peopleRoutes, { + prefix: '/api/people', + service: bubble.service, + }); await app.register(workspacesRoutes, { prefix: '/api/workspaces' }); const call = async ( principalId: string, - method: 'GET' | 'POST' | 'PATCH' | 'DELETE', + method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', url: string, payload?: object, ) => { @@ -243,5 +248,64 @@ export function describeSeveralPeople( ).status, ).toBe(404); }); + + it('lets an administrator admit, revoke and give Workspace roles', async () => { + const { call, store, workspaceOf, spacesOf } = await host(); + await store.principals.upsert({ principalId: 'erin', kind: 'user' }); + // Signed in, not admitted. + expect((await call('erin', 'GET', '/api/canvas')).status).toBe(403); + expect((await call('carol', 'GET', '/api/people')).status).toBe(403); + + const listed = (await call('admin', 'GET', '/api/people')).body as Array<{ + principal: { principalId: string }; + member: boolean; + admin: boolean; + }>; + expect( + Object.fromEntries( + listed.map((p) => [p.principal.principalId, [p.member, p.admin]]), + ), + ).toMatchObject({ + admin: [false, true], + carol: [true, false], + erin: [false, false], + }); + + const admit = (principalId: string, member: boolean) => + call('admin', 'PUT', `/api/people/${principalId}/member`, { member }); + expect((await admit('erin', true)).status).toBe(204); + expect((await call('erin', 'GET', '/api/canvas')).status).toBe(200); + expect((await admit('nobody', true)).status).toBe(404); + expect((await admit('admin', false)).status).toBe(409); + + // A Workspace role lets Erin enter Carol's Workspace and edit there, + // beside the personal Workspace her first admitted request made. + const carolWs = await workspaceOf('carol'); + await call('carol', 'POST', '/api/canvas', { title: 'plan' }); + expect( + ( + await call('admin', 'PUT', `/api/people/erin/workspaces/${carolWs}`, { + role: 'editor', + }) + ).status, + ).toBe(204); + await call('erin', 'POST', `/api/workspaces/${carolWs}/activate`); + expect(await spacesOf('erin')).toEqual(['plan']); + const people = (await call('admin', 'GET', '/api/people')).body as Array<{ + principal: { principalId: string }; + workspaces: Array<{ workspaceId: string; role: string }>; + }>; + expect( + people.find((p) => p.principal.principalId === 'erin')?.workspaces, + ).toContainEqual({ workspaceId: carolWs, role: 'editor' }); + + // Removing it, then admission, takes effect on the next request. + await call('admin', 'PUT', `/api/people/erin/workspaces/${carolWs}`, { + role: null, + }); + expect(await spacesOf('erin')).not.toContain('plan'); + await admit('erin', false); + expect((await call('erin', 'GET', '/api/canvas')).status).toBe(403); + }); }); } diff --git a/apps/server/src/modules/identity/people.route.ts b/apps/server/src/modules/identity/people.route.ts new file mode 100644 index 000000000..4a0962948 --- /dev/null +++ b/apps/server/src/modules/identity/people.route.ts @@ -0,0 +1,85 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { + setPersonMemberSchema, + setPersonWorkspaceRoleSchema, +} from '@huabu/shared'; + +import { getRequestIdentity } from './request.js'; +import { getWorkspaceRepository } from '../storage/index.js'; + +import type { IdentityService } from './service.js'; +import type { FastifyPluginAsync } from 'fastify'; + +/** + * People administration for a Bubble deployment: who may use Huabu, and with + * which Workspace roles. An administrator's alone; absent in local mode, where + * there is one person. Revocation reaches open streams at their next + * revalidation, as every other grant change does. + */ +const peopleRoutes: FastifyPluginAsync<{ service: IdentityService }> = async ( + app, + { service }, +) => { + const people = service.people; + app.addHook('preHandler', async (request, reply) => { + if (!people) return reply.code(404).send({ message: 'Not found' }); + if (!getRequestIdentity(request)?.owner) + return reply.code(403).send({ + message: 'Administering people requires an administrator', + code: 'ADMIN_REQUIRED', + }); + }); + + app.get('/', async () => people!.list()); + + app.put<{ Params: { principalId: string } }>( + '/:principalId/member', + async (request, reply) => { + const body = setPersonMemberSchema.safeParse(request.body); + if (!body.success) + return reply.code(400).send({ message: 'Invalid request body' }); + const by = getRequestIdentity(request)!.principal.principalId; + // An administrator cannot lock themselves out from here. + if (!body.data.member && request.params.principalId === by) + return reply + .code(409) + .send({ message: 'You cannot revoke your own access' }); + if ( + !(await people!.setMember( + request.params.principalId, + body.data.member, + by, + )) + ) + return reply.code(404).send({ message: 'No such person' }); + return reply.code(204).send(); + }, + ); + + app.put<{ Params: { principalId: string; workspaceId: string } }>( + '/:principalId/workspaces/:workspaceId', + async (request, reply) => { + const body = setPersonWorkspaceRoleSchema.safeParse(request.body); + if (!body.success) + return reply.code(400).send({ message: 'Invalid request body' }); + const { principalId, workspaceId } = request.params; + if (body.data.role && !(await getWorkspaceRepository().get(workspaceId))) + return reply.code(404).send({ message: 'Workspace not found' }); + const by = getRequestIdentity(request)!.principal.principalId; + if ( + !(await people!.setWorkspaceRole( + principalId, + workspaceId, + body.data.role, + by, + )) + ) + return reply.code(404).send({ message: 'No such person' }); + return reply.code(204).send(); + }, + ); +}; + +export default peopleRoutes; diff --git a/apps/server/src/modules/identity/service.ts b/apps/server/src/modules/identity/service.ts index 30fc16a28..e29768b21 100644 --- a/apps/server/src/modules/identity/service.ts +++ b/apps/server/src/modules/identity/service.ts @@ -2,7 +2,12 @@ // Licensed under the MIT license. import type { WorkspaceScope } from '../workspace/context.js'; -import type { IdentityPrincipal, IdentityResponse } from '@huabu/shared'; +import type { + IdentityPrincipal, + IdentityResponse, + Person, + WorkspaceRole, +} from '@huabu/shared'; /** Supplied by a trusted transport, never copied from a request body. */ export interface IdentityCredentials { @@ -104,6 +109,8 @@ export interface IdentityService { * mode). */ selectWorkspace?(identity: ResolvedIdentity): Promise; + /** Who may use Huabu and with which Workspace roles; Bubble mode only. */ + readonly people?: PeopleDirectory; /** Make a Workspace the caller's current one; `null` when refused. */ chooseWorkspace?( identity: ResolvedIdentity, @@ -120,3 +127,21 @@ export class IdentityError extends Error { super(message); } } + +/** + * Administering people: admitting them to Huabu and giving them Workspace + * roles. Only an administrator's routes use it; the provider decides nothing + * here beyond storing the grants its policy then answers from. + */ +export interface PeopleDirectory { + list(): Promise; + /** `false` when there is no such principal. */ + setMember(principalId: string, member: boolean, by: string): Promise; + /** `null` removes every Workspace role they hold there. */ + setWorkspaceRole( + principalId: string, + workspaceId: string, + role: WorkspaceRole | null, + by: string, + ): Promise; +} diff --git a/packages/shared/src/types/api/identity.ts b/packages/shared/src/types/api/identity.ts index c162ee2ba..a9add34dc 100644 --- a/packages/shared/src/types/api/identity.ts +++ b/packages/shared/src/types/api/identity.ts @@ -22,3 +22,33 @@ export const identityResponseSchema = z.object({ owner: z.boolean(), }); export type IdentityResponse = z.infer; + +/** A Workspace role a person administration grant can give. */ +export const workspaceRoleSchema = z.enum(['owner', 'editor', 'viewer']); +export type WorkspaceRole = z.infer; + +/** One principal, as `GET /api/people` lists them for an administrator. */ +export const personSchema = z.object({ + principal: identityPrincipalSchema, + /** Holds system `member`: admitted to Huabu. */ + member: z.boolean(), + /** Holds system `owner`: administers the deployment. */ + admin: z.boolean(), + /** Workspace roles held directly, one entry per Workspace. */ + workspaces: z.array( + z.object({ workspaceId: z.string().min(1), role: workspaceRoleSchema }), + ), +}); +export type Person = z.infer; + +/** `PUT /api/people/:principalId/member`. */ +export const setPersonMemberSchema = z.object({ member: z.boolean() }); +export type SetPersonMemberRequest = z.infer; + +/** `PUT /api/people/:principalId/workspaces/:workspaceId`; `null` removes it. */ +export const setPersonWorkspaceRoleSchema = z.object({ + role: workspaceRoleSchema.nullable(), +}); +export type SetPersonWorkspaceRoleRequest = z.infer< + typeof setPersonWorkspaceRoleSchema +>; From cbe0a4450fd2228964047b55ce441ec580c392c0 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 18:06:44 +0800 Subject: [PATCH 11/17] feat(identity): give each member their own settings, keys and credentials A Bubble member's calls run in a personal settings namespace: the secret store keeps their model keys, OAuth and connected credentials under their own ids with no fallback to the deployment's environment, and model settings and agent defaults live under data/people//. Members may change their own settings; the deployment's stay with administrators. A member's default agent is always the Built-In one. Co-Authored-By: Claude Opus 5.5 --- .../src/modules/agent/agent-defaults.route.ts | 4 +- .../src/modules/agent/agent-defaults.ts | 22 +++- apps/server/src/modules/agent/llm.route.ts | 14 +-- apps/server/src/modules/agent/llm.ts | 103 +++++++++++----- apps/server/src/modules/identity/http.ts | 9 +- .../identity/personal-settings.test.ts | 115 ++++++++++++++++++ .../src/modules/identity/personal-settings.ts | 91 ++++++++++++++ .../integrations/ink-ocr-config.route.ts | 6 +- .../integrations/integrations.route.ts | 4 +- apps/server/src/modules/security/owner.ts | 10 ++ .../modules/services/services.route.test.ts | 1 + .../src/modules/services/services.route.ts | 4 +- apps/server/src/security/secret-store.ts | 45 ++++++- 13 files changed, 370 insertions(+), 58 deletions(-) create mode 100644 apps/server/src/modules/identity/personal-settings.test.ts create mode 100644 apps/server/src/modules/identity/personal-settings.ts diff --git a/apps/server/src/modules/agent/agent-defaults.route.ts b/apps/server/src/modules/agent/agent-defaults.route.ts index 9412298bd..92a2f3b73 100644 --- a/apps/server/src/modules/agent/agent-defaults.route.ts +++ b/apps/server/src/modules/agent/agent-defaults.route.ts @@ -14,7 +14,7 @@ import { import { getProfileSchemaCache } from './acp/profile-schema-cache.js'; import { getAgentDefaults, setAgentDefaults } from './agent-defaults.js'; -import { isOwnerRequest } from '../security/owner.js'; +import { canChangeOwnSettings } from '../security/owner.js'; import type { AgentDefaults, @@ -75,7 +75,7 @@ function projectDefaults(defaults: AgentDefaults): AgentDefaultsResponse { const agentDefaultsRoutes: FastifyPluginAsync = async (app) => { app.addHook('preHandler', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.status(403).send({ message: 'Forbidden: Utility Agent settings require owner authorization', diff --git a/apps/server/src/modules/agent/agent-defaults.ts b/apps/server/src/modules/agent/agent-defaults.ts index 0accc5686..751a4dfc4 100644 --- a/apps/server/src/modules/agent/agent-defaults.ts +++ b/apps/server/src/modules/agent/agent-defaults.ts @@ -10,6 +10,10 @@ import { agentDefaultsSchema } from '@huabu/shared'; import { getDataDir } from '../../data-dir.js'; import { atomicWriteJson } from '../../utils/fs.js'; +import { + personalSettingsOwner, + settingsFilePath, +} from '../identity/personal-settings.js'; import type { AgentDefaults, AgentProfileView } from '@huabu/shared'; @@ -35,7 +39,9 @@ interface AgentDefaultsStorage { } function configPath(): string { - return join(getDataDir(), 'agent-defaults.json'); + return personalSettingsOwner() + ? settingsFilePath('agent-defaults.json') + : join(getDataDir(), 'agent-defaults.json'); } const diskStorage: AgentDefaultsStorage = { @@ -125,9 +131,19 @@ export class AgentDefaultsService { } const service = new AgentDefaultsService(); -export const getAgentDefaults = (): AgentDefaults => service.getAgentDefaults(); +/** + * A member's own defaults always pick the Built-In agent: external agents run + * on the operator's machines under the operator's logins, so they stay the + * administrators'. + */ +export const getAgentDefaults = (): AgentDefaults => { + const defaults = service.getAgentDefaults(); + return personalSettingsOwner() + ? { ...defaults, profileId: 'huabu' } + : defaults; +}; export const requireDefaultAgentProfileId = (): string => - service.requireDefaultAgentProfileId(); + personalSettingsOwner() ? 'huabu' : service.requireDefaultAgentProfileId(); export const setAgentDefaults = (config: AgentDefaults): AgentDefaults => service.setAgentDefaults(config); export const initializeAgentDefaults = ( diff --git a/apps/server/src/modules/agent/llm.route.ts b/apps/server/src/modules/agent/llm.route.ts index a12a17cb8..524a1709f 100644 --- a/apps/server/src/modules/agent/llm.route.ts +++ b/apps/server/src/modules/agent/llm.route.ts @@ -27,7 +27,7 @@ import { verifyOAuthCredentials, } from './oauth.js'; import { getRootErrorMessage } from '../../utils/error-message.js'; -import { isOwnerRequest } from '../security/owner.js'; +import { canChangeOwnSettings } from '../security/owner.js'; import type { ApiResult, @@ -59,7 +59,7 @@ const llmRoutes: FastifyPluginAsync = async (app) => { app.put<{ Body: LLMConfigUpdate; Reply: ApiResult }>( '/config', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.status(403).send({ message: 'Forbidden: LLM settings can only be changed from localhost', }); @@ -86,7 +86,7 @@ const llmRoutes: FastifyPluginAsync = async (app) => { app.put<{ Body: LLMImageConfigUpdate; Reply: ApiResult }>( '/image-config', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.status(403).send({ message: 'Forbidden: LLM settings can only be changed from localhost', }); @@ -116,7 +116,7 @@ const llmRoutes: FastifyPluginAsync = async (app) => { app.put<{ Body: LLMUtilityConfigUpdate; Reply: ApiResult }>( '/utility-config', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.status(403).send({ message: 'Forbidden: LLM settings can only be changed from localhost', }); @@ -165,7 +165,7 @@ const llmRoutes: FastifyPluginAsync = async (app) => { Body: OAuthProviderBody; Reply: ApiResult; }>('/oauth/device-code', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.status(403).send({ message: 'Forbidden' }); } @@ -191,7 +191,7 @@ const llmRoutes: FastifyPluginAsync = async (app) => { Body: OAuthProviderBody; Reply: ApiResult; }>('/oauth/poll', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.status(403).send({ message: 'Forbidden' }); } @@ -234,7 +234,7 @@ const llmRoutes: FastifyPluginAsync = async (app) => { Body: OAuthProviderBody; Reply: ApiResult; }>('/oauth/logout', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.status(403).send({ message: 'Forbidden' }); } diff --git a/apps/server/src/modules/agent/llm.ts b/apps/server/src/modules/agent/llm.ts index ce7f6ba20..4dbe4464c 100644 --- a/apps/server/src/modules/agent/llm.ts +++ b/apps/server/src/modules/agent/llm.ts @@ -51,6 +51,10 @@ import { setSecret, } from '../../security/secret-store.js'; import { getLogger } from '../../utils/logger.js'; +import { + personalSettingsOwner, + settingsFilePath, +} from '../identity/personal-settings.js'; import type { Api, @@ -198,7 +202,15 @@ function getDataFilePath(filename: string): string { return join(getDataDir(), filename); } -const CONFIG_FILE = getDataFilePath('llm-config.json'); +/** + * The deployment's model settings, or a member's own in their personal + * settings namespace (`../identity/personal-settings.ts`). + */ +function configFile(): string { + return personalSettingsOwner() + ? settingsFilePath('llm-config.json') + : getDataFilePath('llm-config.json'); +} /** * Effective active configuration assembled from the persisted store — @@ -304,8 +316,8 @@ interface UtilityConfigPersisted { */ function loadPersistedStore(): PersistedStore { try { - if (!existsSync(CONFIG_FILE)) return { providers: {} }; - const raw = readFileSync(CONFIG_FILE, 'utf-8'); + if (!existsSync(configFile())) return { providers: {} }; + const raw = readFileSync(configFile(), 'utf-8'); const parsed = JSON.parse(raw) as Record; // Legacy shape — single active provider, fields at top level. @@ -413,13 +425,13 @@ function extractLegacyImageConfig( } function savePersistedStore(store: PersistedStore): void { - const dir = dirname(CONFIG_FILE); + const dir = dirname(configFile()); if (!existsSync(dir)) { mkdirSync(dir, { recursive: true }); } - writeFileSync(CONFIG_FILE, JSON.stringify(store, null, 2), 'utf-8'); + writeFileSync(configFile(), JSON.stringify(store, null, 2), 'utf-8'); try { - chmodSync(CONFIG_FILE, 0o600); + chmodSync(configFile(), 0o600); } catch { // Non-critical — best effort on platforms that support it } @@ -449,16 +461,30 @@ function loadPersistedConfig(): PersistedConfig | null { // ==================== Runtime State ==================== -let cachedModel: Model | null = null; -let activeConfig: PersistedConfig | null = null; +interface RuntimeState { + cachedModel: Model | null; + activeConfig: PersistedConfig | null; + /** + * Cached utility-tier model. Built from `store.utilityConfig` and + * invalidated whenever {@link setUtilityConfig} writes. When utility is + * following the chat model (no utility config), the resolver returns the + * chat model directly and this stays null. + */ + cachedUtilityModel: Model | null; +} -/** - * Cached utility-tier model. Built from `store.utilityConfig` and - * invalidated whenever {@link setUtilityConfig} writes. When utility is - * following the chat model (no utility config), the resolver returns the - * chat model directly and this stays null. - */ -let cachedUtilityModel: Model | null = null; +/** One runtime state per settings namespace: the deployment's, or a member's. */ +const runtimeStates = new Map(); + +function runtime(): RuntimeState { + const key = personalSettingsOwner() ?? ''; + let state = runtimeStates.get(key); + if (!state) { + state = { cachedModel: null, activeConfig: null, cachedUtilityModel: null }; + runtimeStates.set(key, state); + } + return state; +} /** * Resolve the API key for a provider. @@ -565,26 +591,34 @@ function buildModel(cfg: PersistedConfig): Model { /** Initialize the active configuration from persisted config or env vars. */ function ensureConfig(): PersistedConfig { - if (activeConfig) return activeConfig; + const state = runtime(); + if (state.activeConfig) return state.activeConfig; // Try persisted config const persisted = loadPersistedConfig(); if (persisted) { - activeConfig = persisted; - return activeConfig; + state.activeConfig = persisted; + return persisted; } + // The deployment's environment is the operator's, never a member's. + if (personalSettingsOwner()) + throw new Error( + 'No model configured. Choose a provider and add your key in Settings.', + ); + // Fall back to legacy Azure OpenAI env vars const azureKey = process.env.AZURE_OPENAI_API_KEY; const azureEndpoint = process.env.AZURE_OPENAI_API_ENDPOINT; const azureDeployment = process.env.AZURE_OPENAI_API_DEPLOYMENT_NAME; if (azureKey && azureEndpoint && azureDeployment) { - activeConfig = { + const azure: PersistedConfig = { provider: 'azure-openai', model: azureDeployment, }; - return activeConfig; + state.activeConfig = azure; + return azure; } // Try other providers from env vars @@ -592,8 +626,9 @@ function ensureConfig(): PersistedConfig { if (p.builtIn && getEnvApiKey(p.id as KnownProvider)) { const models = getModelsForProvider(p.id); if (models.length > 0) { - activeConfig = { provider: p.id, model: models[0].id }; - return activeConfig; + const found: PersistedConfig = { provider: p.id, model: models[0].id }; + state.activeConfig = found; + return found; } } } @@ -996,8 +1031,8 @@ export async function setLLMConfig( provider: update.provider, model: resolvedModel, }; - activeConfig = persisted; - cachedModel = null; + runtime().activeConfig = persisted; + runtime().cachedModel = null; if ( persisted.provider === 'openai' && (update.apiKey !== undefined || update.baseUrl !== undefined) @@ -1250,7 +1285,7 @@ export async function setUtilityConfig( if (!update.provider) { delete store.utilityConfig; savePersistedStore(store); - cachedUtilityModel = null; + runtime().cachedUtilityModel = null; return getUtilityConfig(); } @@ -1292,7 +1327,7 @@ export async function setUtilityConfig( } savePersistedStore(store); - cachedUtilityModel = null; + runtime().cachedUtilityModel = null; return getUtilityConfig(); } @@ -1304,9 +1339,11 @@ export async function setUtilityConfig( function getUtilityModel(): Model { const cfg = loadUtilityPersistedConfig(); if (!cfg) return getLLMModel(); - if (cachedUtilityModel) return cachedUtilityModel; - cachedUtilityModel = buildModel(cfg); - return cachedUtilityModel; + const state = runtime(); + if (state.cachedUtilityModel) return state.cachedUtilityModel; + const model = buildModel(cfg); + state.cachedUtilityModel = model; + return model; } /** @@ -1580,7 +1617,8 @@ export async function ensureApiKeyForRole( * Get a configured pi-ai Model instance for the active provider/model. */ export function getLLMModel(): Model { - if (cachedModel) return cachedModel; + const state = runtime(); + if (state.cachedModel) return state.cachedModel; const cfg = ensureConfig(); const apiKey = resolveApiKey(cfg.provider); @@ -1597,8 +1635,9 @@ export function getLLMModel(): Model { } } - cachedModel = buildModel(cfg); - return cachedModel; + const model = buildModel(cfg); + state.cachedModel = model; + return model; } /** diff --git a/apps/server/src/modules/identity/http.ts b/apps/server/src/modules/identity/http.ts index 66f5b7c7f..a6522b100 100644 --- a/apps/server/src/modules/identity/http.ts +++ b/apps/server/src/modules/identity/http.ts @@ -3,6 +3,7 @@ import { timingSafeEqual } from 'node:crypto'; +import { openPersonalSettings, useCaller } from './personal-settings.js'; import { getRequestAuthorizations, setRequestWorkspaceChooser, @@ -80,10 +81,15 @@ export function registerIdentity( // In Bubble mode every request runs in its caller's own Workspace. The slot // must wrap the rest of the lifecycle, which only a callback hook can do; // admission fills it below once it knows who is calling. - if (service.provider === 'bubble') + if (service.provider === 'bubble') { app.addHook('onRequest', (_request, _reply, done) => openWorkspaceScope(done), ); + // Likewise each member's settings, model keys and credentials are their own. + app.addHook('onRequest', (_request, _reply, done) => + openPersonalSettings(done), + ); + } app.addHook('onRequest', async (request, reply) => { const path = request.url.split('?', 1)[0]; const identityRoute = path === '/api/identity' || path === SESSION_PATH; @@ -174,6 +180,7 @@ export function registerIdentity( } // A member's first request, `GET /api/identity` after sign-in included, // is also where their personal Workspace is created. + if (identity.member && service.selectWorkspace) useCaller(identity); if (identity.member && service.selectWorkspace) { const scope = await service.selectWorkspace(identity); if (scope) fillWorkspaceScope(scope); diff --git a/apps/server/src/modules/identity/personal-settings.test.ts b/apps/server/src/modules/identity/personal-settings.test.ts new file mode 100644 index 000000000..964388176 --- /dev/null +++ b/apps/server/src/modules/identity/personal-settings.test.ts @@ -0,0 +1,115 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import type { ResolvedIdentity } from './service.js'; + +/** + * A member's model keys and connected credentials are their own: the secret + * store and the settings files answer from a personal namespace, and the + * deployment's environment, which is the operator's, is never theirs. + */ + +let tmp: string; +const saved: Record = {}; +const ENV = ['HUABU_DATA_DIR', 'HUABU_SECRET_KEY', 'TAVILY_API_KEY']; + +beforeEach(() => { + tmp = mkdtempSync(join(tmpdir(), 'huabu-personal-settings-')); + for (const key of ENV) saved[key] = process.env[key]; + process.env.HUABU_DATA_DIR = tmp; + process.env.TAVILY_API_KEY = 'operator-env-key'; + delete process.env.HUABU_SECRET_KEY; + vi.resetModules(); +}); +afterEach(() => { + for (const key of ENV) + if (saved[key] === undefined) delete process.env[key]; + else process.env[key] = saved[key]; + rmSync(tmp, { recursive: true, force: true }); +}); + +const person = (principalId: string, owner = false): ResolvedIdentity => ({ + principal: { principalId, kind: 'user' }, + member: true, + owner, + access: { + can: async () => true, + claim: async () => {}, + workspaces: async () => 'all', + }, +}); + +describe('personal settings', () => { + it('keeps each member’s credentials apart from the deployment’s and each other’s', async () => { + const store = await import('../../security/secret-store.js'); + const scope = await import('./personal-settings.js'); + const { SECRET_IDS } = await import('../../security/secret-ids.js'); + await store.initializeSecretStore(); + const as = (identity: ResolvedIdentity | null, fn: () => T) => + scope.openPersonalSettings(() => { + if (identity) scope.useCaller(identity); + return fn(); + }); + const tavily = SECRET_IDS.tavilyApiKey; + + // The deployment falls back to its environment; a member does not. + expect(as(null, () => store.getSecret(tavily))).toBe('operator-env-key'); + expect(as(person('carol'), () => store.getSecret(tavily))).toBeNull(); + + await as(person('carol'), () => store.setSecret(tavily, 'carol-key')); + await as(person('dave'), () => store.setSecrets({ [tavily]: 'dave-key' })); + expect(as(person('carol'), () => store.getSecret(tavily))).toBe( + 'carol-key', + ); + expect(as(person('dave'), () => store.getSecret(tavily))).toBe('dave-key'); + expect(as(null, () => store.getSecret(tavily))).toBe('operator-env-key'); + // An administrator uses the deployment's. + expect(as(person('admin', true), () => store.getSecret(tavily))).toBe( + 'operator-env-key', + ); + + // Settings files go under the member's own directory. + expect(as(person('carol'), () => scope.settingsFilePath('x.json'))).toMatch( + new RegExp(`^${tmp}/people/[0-9a-f]{32}/x\\.json$`), + ); + expect(as(null, () => scope.settingsFilePath('x.json'))).toBe( + join(tmp, 'x.json'), + ); + }); + + it('never namespaces the deployment’s own credentials', async () => { + const store = await import('../../security/secret-store.js'); + const scope = await import('./personal-settings.js'); + const { SECRET_IDS } = await import('../../security/secret-ids.js'); + await store.initializeSecretStore(); + await store.setSecret(SECRET_IDS.managedConnectionToken, 'machine'); + expect( + scope.openPersonalSettings(() => { + scope.useCaller(person('carol')); + return store.getSecret(SECRET_IDS.managedConnectionToken); + }), + ).toBe('machine'); + }); + + it('gives a member the Built-In agent by default, whatever the deployment picks', async () => { + const scope = await import('./personal-settings.js'); + const defaults = await import('../agent/agent-defaults.js'); + defaults.setAgentDefaults({ + profileId: 'external-x', + functionalModel: '', + }); + expect(defaults.getAgentDefaults().profileId).toBe('external-x'); + expect( + scope.openPersonalSettings(() => { + scope.useCaller(person('carol')); + return defaults.getAgentDefaults().profileId; + }), + ).toBe('huabu'); + }); +}); diff --git a/apps/server/src/modules/identity/personal-settings.ts b/apps/server/src/modules/identity/personal-settings.ts new file mode 100644 index 000000000..253bc77b6 --- /dev/null +++ b/apps/server/src/modules/identity/personal-settings.ts @@ -0,0 +1,91 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +/** + * Whose settings a call reads and writes. + * + * The deployment's settings, model keys and connected credentials belong to + * its administrators. In Bubble mode every member has their own instead: a + * call made for a member, and everything it starts (an agent run included), + * runs in that member's personal settings namespace, and the secret store and + * settings files answer from it. Local mode, administrators and the machine + * credential never open one, so they read the deployment's, exactly as before. + */ + +import { AsyncLocalStorage } from 'node:async_hooks'; +import { createHash } from 'node:crypto'; +import path from 'node:path'; + +import { getDataDir } from '../../data-dir.js'; + +import type { ResolvedIdentity, ResourceAccess } from './service.js'; + +interface Slot { + /** Whose personal settings this call uses; `null` for the deployment's. */ + principalId: string | null; + /** + * What the caller may reach, for work that outlives the request and no + * longer has it (an agent run's tools). `null` for an unrestricted caller. + */ + access: ResourceAccess | null; +} + +const storage = new AsyncLocalStorage(); + +/** Run `fn` with an empty slot that {@link usePersonalSettings} may fill. */ +export function openPersonalSettings(fn: () => T): T { + return storage.run({ principalId: null, access: null }, fn); +} + +/** + * Record who the call this runs inside is for: a member's own settings and + * access, or an administrator's access over the deployment's settings. + */ +export function useCaller(identity: ResolvedIdentity): void { + const slot = storage.getStore(); + if (!slot) throw new Error('No settings scope is open for this call'); + const personal = identity.member && !identity.owner; + const principalId = personal ? identity.principal.principalId : null; + if (slot.principalId && slot.principalId !== principalId) + throw new Error('This call already runs as another person'); + slot.principalId = principalId; + slot.access = identity.access; +} + +/** + * The access of the caller this call runs for, or `null` when it is + * unrestricted (local mode, the machine credential, startup work). + */ +export function callerAccess(): ResourceAccess | null { + return storage.getStore()?.access ?? null; +} + +/** The member whose settings this call uses, or `null` for the deployment's. */ +export function personalSettingsOwner(): string | null { + return storage.getStore()?.principalId ?? null; +} + +/** A name safe for a directory, the same for the same principal. */ +function personKey(principalId: string): string { + return createHash('sha256').update(principalId).digest('hex').slice(0, 32); +} + +/** + * Where a settings file lives for this call: in the data directory for the + * deployment, under `people//` for a member. + */ +export function settingsFilePath(fileName: string): string { + const owner = personalSettingsOwner(); + return owner + ? path.join(getDataDir(), 'people', personKey(owner), fileName) + : path.join(getDataDir(), fileName); +} + +/** + * The secret id this call stores `id` under: itself for the deployment, and + * namespaced for a member, so one person's keys are never another's. + */ +export function personalSecretId(id: string): string { + const owner = personalSettingsOwner(); + return owner ? `person:${personKey(owner)}:${id}` : id; +} diff --git a/apps/server/src/modules/integrations/ink-ocr-config.route.ts b/apps/server/src/modules/integrations/ink-ocr-config.route.ts index 8e3b58d02..193cfb2d1 100644 --- a/apps/server/src/modules/integrations/ink-ocr-config.route.ts +++ b/apps/server/src/modules/integrations/ink-ocr-config.route.ts @@ -5,7 +5,7 @@ import { inkOcrConfigUpdateSchema } from '@huabu/shared'; import { getInkOcrConfig, setInkOcrConfig } from './ink-ocr-config.js'; import { isSecretStoreWritable } from '../../security/secret-store.js'; -import { isOwnerRequest } from '../security/owner.js'; +import { canChangeOwnSettings } from '../security/owner.js'; import type { ApiResult, @@ -18,7 +18,7 @@ const inkOcrConfigRoutes: FastifyPluginAsync = async (app) => { app.get<{ Reply: ApiResult }>( '/config', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.code(403).send({ message: 'Forbidden: Ink OCR configuration requires owner authorization', @@ -43,7 +43,7 @@ const inkOcrConfigRoutes: FastifyPluginAsync = async (app) => { Body: InkOcrConfigUpdate; Reply: ApiResult; }>('/config', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.code(403).send({ message: 'Forbidden: Ink OCR configuration requires owner authorization', diff --git a/apps/server/src/modules/integrations/integrations.route.ts b/apps/server/src/modules/integrations/integrations.route.ts index 0e1acf421..f9a7598fe 100644 --- a/apps/server/src/modules/integrations/integrations.route.ts +++ b/apps/server/src/modules/integrations/integrations.route.ts @@ -18,7 +18,7 @@ import { getIntegrationsConfig, setIntegrationsConfig, } from './integrations.js'; -import { isOwnerRequest } from '../security/owner.js'; +import { canChangeOwnSettings } from '../security/owner.js'; import type { ApiResult, @@ -39,7 +39,7 @@ const integrationsRoutes: FastifyPluginAsync = async (app) => { Body: IntegrationsConfigUpdate; Reply: ApiResult; }>('/config', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.status(403).send({ message: 'Forbidden: integration keys require owner authorization', }); diff --git a/apps/server/src/modules/security/owner.ts b/apps/server/src/modules/security/owner.ts index b829fc375..d73059ddf 100644 --- a/apps/server/src/modules/security/owner.ts +++ b/apps/server/src/modules/security/owner.ts @@ -1,6 +1,7 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +import { personalSettingsOwner } from '../identity/personal-settings.js'; import { getRequestIdentity } from '../identity/request.js'; import type { FastifyRequest } from 'fastify'; @@ -9,3 +10,12 @@ import type { FastifyRequest } from 'fastify'; export function isOwnerRequest(request: FastifyRequest): boolean { return getRequestIdentity(request)?.owner === true; } + +/** + * Whether the caller may change the settings this call reads: an owner the + * deployment's, a Bubble member their own personal ones (model keys, agent + * defaults, connected credentials). + */ +export function canChangeOwnSettings(request: FastifyRequest): boolean { + return isOwnerRequest(request) || personalSettingsOwner() !== null; +} diff --git a/apps/server/src/modules/services/services.route.test.ts b/apps/server/src/modules/services/services.route.test.ts index e7f8c12da..8b2b03f0c 100644 --- a/apps/server/src/modules/services/services.route.test.ts +++ b/apps/server/src/modules/services/services.route.test.ts @@ -27,6 +27,7 @@ vi.mock('./index.js', async (importOriginal) => { vi.mock('../security/owner.js', () => ({ isOwnerRequest: mocks.isOwner, + canChangeOwnSettings: mocks.isOwner, })); const { default: serviceRoutes } = await import('./services.route.js'); diff --git a/apps/server/src/modules/services/services.route.ts b/apps/server/src/modules/services/services.route.ts index a31fd76d0..d1adbd389 100644 --- a/apps/server/src/modules/services/services.route.ts +++ b/apps/server/src/modules/services/services.route.ts @@ -3,7 +3,7 @@ import { serviceConfigUpdateSchema, serviceParamsSchema } from '@huabu/shared'; -import { isOwnerRequest } from '../security/owner.js'; +import { canChangeOwnSettings } from '../security/owner.js'; import { serviceProvisioner, ServiceProvisionError } from './index.js'; @@ -59,7 +59,7 @@ const serviceRoutes: FastifyPluginAsync = async (app) => { Body: ServiceConfigUpdate; Reply: ApiResult; }>('/:serviceId', async (request, reply) => { - if (!isOwnerRequest(request)) { + if (!canChangeOwnSettings(request)) { return reply.code(403).send({ message: 'Forbidden: Service settings require owner authorization', }); diff --git a/apps/server/src/security/secret-store.ts b/apps/server/src/security/secret-store.ts index 16063af14..337c6e5e1 100644 --- a/apps/server/src/security/secret-store.ts +++ b/apps/server/src/security/secret-store.ts @@ -15,6 +15,8 @@ import { } from './encrypted-file-secret-store.js'; import { EnvironmentSecretStore } from './environment-secret-store.js'; import { resolveStandaloneMasterKey } from './private-config.js'; +import { SECRET_IDS } from './secret-ids.js'; +import { personalSecretId } from '../modules/identity/personal-settings.js'; import type { SecretStore } from './secret-store-types.js'; @@ -56,16 +58,39 @@ function assertInitialized(): void { } } -/** Read UI-persisted credentials first, then deployment-owned environment values. */ +/** + * The deployment's own credentials, never anyone's personal ones: a member + * running in their personal settings neither reads nor writes these as theirs. + */ +const DEPLOYMENT_SECRET_IDS: ReadonlySet = new Set([ + SECRET_IDS.agentletConnectionToken, + SECRET_IDS.managedConnectionToken, + SECRET_IDS.remoteAccessPassword, +]); + +/** Where `id` is kept for this call: a member's own, or the deployment's. */ +function scopedId(id: string): { id: string; personal: boolean } { + if (DEPLOYMENT_SECRET_IDS.has(id)) return { id, personal: false }; + const personal = personalSecretId(id); + return { id: personal, personal: personal !== id }; +} + +/** + * Read UI-persisted credentials first, then deployment-owned environment + * values. A member's personal credentials have no environment fallback: the + * deployment's environment is the operator's. + */ export function getSecret(id: string): string | null { assertInitialized(); + const scoped = scopedId(id); + if (scoped.personal) return primaryStore?.get(scoped.id) ?? null; return primaryStore?.get(id) ?? environmentStore.get(id); } /** Read only the writable backend, excluding environment fallbacks. */ export function getPersistedSecret(id: string): string | null { assertInitialized(); - return primaryStore?.get(id) ?? null; + return primaryStore?.get(scopedId(id).id) ?? null; } /** Read saved credentials without creating storage for a new instance. */ @@ -90,8 +115,12 @@ export async function setSecret( value: string | null, ): Promise { assertInitialized(); - if (!primaryStore) await environmentStore.set(id, value); - else await primaryStore.set(id, value); + const scoped = scopedId(id); + if (!primaryStore) { + if (scoped.personal) + throw new Error('Personal credentials need a writable secret store'); + await environmentStore.set(id, value); + } else await primaryStore.set(scoped.id, value); } /** @@ -106,11 +135,15 @@ export async function setSecrets( assertInitialized(); if (!primaryStore) { for (const [id, value] of Object.entries(updates)) { - await environmentStore.set(id, value); + await setSecret(id, value); } return; } - await primaryStore.setMany(updates); + await primaryStore.setMany( + Object.fromEntries( + Object.entries(updates).map(([id, value]) => [scopedId(id).id, value]), + ), + ); } export function getSecretStoreKind(): string { From 2482eaf6cb86288d92b05e3f1737f12dc1d6d092 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 18:06:44 +0800 Subject: [PATCH 12/17] feat(agent): let members run the Built-In agent in their own access Members may now use /api/agent and conversations through a Space they can use; external agents, RFS and change-review configuration stay with administrators, since they act through the shared machine credential on the operator's machines. The Built-In agent's tools check the starter's access: World reads of another Space need read on it, Workspace memory and Skills need manage on the Workspace, and Task Run tools are refused. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/modules/agent/agent.route.ts | 9 +++ .../src/modules/agent/tools/executor.ts | 61 +++++++++++++++++-- apps/server/src/modules/identity/bubble.ts | 1 - .../src/modules/security/space-access.test.ts | 34 ++++++++--- .../src/modules/security/space-access.ts | 34 ++++++----- 5 files changed, 110 insertions(+), 29 deletions(-) diff --git a/apps/server/src/modules/agent/agent.route.ts b/apps/server/src/modules/agent/agent.route.ts index cd4bb88c6..c758db9be 100644 --- a/apps/server/src/modules/agent/agent.route.ts +++ b/apps/server/src/modules/agent/agent.route.ts @@ -56,6 +56,7 @@ import { import { buildHistoryFromTurns } from '../agent/conversation/transcript/history.js'; import { getLLMModel } from '../agent/llm.js'; import { hydrateCanvasNodes } from '../canvas/canvas-executor.js'; +import { personalSettingsOwner } from '../identity/personal-settings.js'; import { space } from '../storage/index.js'; import { canvasAcpNamespace } from '../workspace/paths.js'; @@ -831,6 +832,14 @@ const agentRoutes: FastifyPluginAsync = async ( agentTarget, fixedTarget, }); + // External agents run on the operator's machines under the operator's + // logins and reach every Space through the shared machine credential, so + // a member runs the Built-In agent, with their own model keys. + if (effectiveBinding?.kind === 'external' && personalSettingsOwner()) + return reply.code(403).send({ + message: 'External agents are available to administrators only', + code: 'AGENT_ACCESS_REQUIRED', + }); if (effectiveBinding?.kind === 'external') { request.log.info( { diff --git a/apps/server/src/modules/agent/tools/executor.ts b/apps/server/src/modules/agent/tools/executor.ts index 1d25de984..94573a722 100644 --- a/apps/server/src/modules/agent/tools/executor.ts +++ b/apps/server/src/modules/agent/tools/executor.ts @@ -69,11 +69,24 @@ import { } from './handlers/task.js'; import { handleWebSearch, type WebSearchArgs } from './handlers/web-search.js'; import { resolveWorldReadCanvasId } from '../../canvas/world-target-access.js'; -import { acquireWorkspaceOperationLease } from '../../workspace.js'; +import { + callerAccess, + personalSettingsOwner, +} from '../../identity/personal-settings.js'; +import { + acquireWorkspaceOperationLease, + getWorkspaceHandle, +} from '../../workspace.js'; import type { AgentToolResult } from '@earendil-works/pi-agent-core'; import type { NodeOrigin } from '@huabu/shared'; +const TASK_TOOLS: ReadonlySet = new Set([ + 'create_task', + 'start_task_run', + 'complete_task_run', +]); + /** * Per-request context every handler call receives. * @@ -134,10 +147,16 @@ export async function executeTool( throw new Error('targetCanvasId must be a string'); } const { targetCanvasId: _targetCanvasId, ...toolArgs } = value; - return { - ...toolArgs, - canvasId: await resolveWorldReadCanvasId(ownerCanvasId, requested), - } as unknown as T; + const canvasId = await resolveWorldReadCanvasId(ownerCanvasId, requested); + // An agent run reaches no further than the person who started it. + const access = callerAccess(); + if ( + access && + canvasId !== ownerCanvasId && + !(await access.can('read', { type: 'space', id: canvasId })) + ) + throw new Error(`Canvas ${canvasId} is not readable`); + return { ...toolArgs, canvasId } as unknown as T; }; const withStableWorkspace = async ( operation: () => T | Promise, @@ -153,6 +172,17 @@ export async function executeTool( } }; + // Task Runs start agents through the shared machine credential, which + // reaches every Space; a member's run may not. + if ( + TASK_TOOLS.has(name) && + callerAccess() && + personalSettingsOwner() !== null + ) + throw new Error( + `${name} is not available to this agent: Task Runs are the administrators'`, + ); + switch (name) { case 'report_ink_intent': return handleReportInkIntent(args as ReportInkIntentArgs, context); @@ -233,6 +263,27 @@ export async function executeTool( ); case 'fs_write': + { + // Workspace memory and Skills steer every agent in the Workspace, so + // changing them is the Workspace's managers'. A Space's own memory is + // checked like any other write to that Space. + const access = callerAccess(); + const workspaceId = getWorkspaceHandle()?.workspaceId; + const target = (args as { path?: unknown }).path; + if ( + access && + typeof target === 'string' && + target.replace(/^\.?\//, '') !== 'memory/space.md' && + !( + workspaceId && + (await access.can('manage', { type: 'workspace', id: workspaceId })) + ) + ) + throw new Error( + 'Changing Workspace memory or Skills needs manage access to the Workspace', + ); + } + // falls through // canvasId is conditionally needed (only for memory/canvas.md); // the handler enforces that. Pass it through when present so the // handler can resolve canvas-scoped paths, but do not require it diff --git a/apps/server/src/modules/identity/bubble.ts b/apps/server/src/modules/identity/bubble.ts index c9da3b584..ca015102a 100644 --- a/apps/server/src/modules/identity/bubble.ts +++ b/apps/server/src/modules/identity/bubble.ts @@ -18,7 +18,6 @@ import { import { identityPrincipalSchema } from '@huabu/shared'; - import { getWorkspaceHandle } from '../workspace.js'; import { IdentityError } from './service.js'; import { diff --git a/apps/server/src/modules/security/space-access.test.ts b/apps/server/src/modules/security/space-access.test.ts index d4446323e..3d271bb4a 100644 --- a/apps/server/src/modules/security/space-access.test.ts +++ b/apps/server/src/modules/security/space-access.test.ts @@ -158,23 +158,41 @@ describe('Space access', () => { expect((await titles('', { canvasId: ['mine'] })).statusCode).toBe(400); }); - it('keeps agents and conversations to owners, whatever Space a request names', async () => { + it('lets a member use the Built-In agent in their Spaces, and keeps external agents to administrators', async () => { const { app } = host(); const as = (owner: 'yes' | 'no') => ({ 'x-owner': owner }); + const member = async (request: { + method?: 'GET' | 'POST'; + url: string; + payload?: object; + }) => (await app.inject({ ...request, headers: as('no') })).statusCode; + // Conversations, through a Space they may use. + expect(await member({ url: '/api/agent/history/t1?canvasId=mine' })).toBe( + 200, + ); + expect( + await member({ + method: 'POST', + url: '/api/agent', + payload: { canvasId: 'mine' }, + }), + ).toBe(200); + expect(await member({ url: '/api/canvas/mine/threads/t1/changes' })).toBe( + 200, + ); + // Not through one they may not, nor without naming one. + expect(await member({ url: '/api/agent/history/t1?canvasId=other' })).toBe( + 404, + ); + expect(await member({ url: '/api/agent/history/t1' })).toBe(400); for (const request of [ - { url: '/api/agent/history/t1?canvasId=mine' }, - { url: '/api/agent/history/t1' }, - { method: 'POST', url: '/api/agent', payload: { canvasId: 'mine' } }, { method: 'POST', url: '/api/acp/threads/t1/permission?canvasId=mine' }, - { url: '/api/canvas/mine/threads/t1/changes' }, // The machine credential's own surface: agent launches, Task Runs and // shared service credentials. { method: 'POST', url: '/api/rfs/mine/services/web-search/lease' }, { method: 'POST', url: '/api/interactive-views/mine/n1/actions/a1' }, ] as const) { - expect( - (await app.inject({ ...request, headers: as('no') })).statusCode, - ).toBe(403); + expect(await member(request)).toBe(403); } expect( ( diff --git a/apps/server/src/modules/security/space-access.ts b/apps/server/src/modules/security/space-access.ts index eb421b171..82f903605 100644 --- a/apps/server/src/modules/security/space-access.ts +++ b/apps/server/src/modules/security/space-access.ts @@ -28,18 +28,16 @@ declare module 'fastify' { type Fields = Record | undefined; /** - * Agents act through the shared machine credential, which reaches every - * Space, so a member may not run or steer one until credentials carry the - * caller's own authority. RFS is that credential's own surface: it launches - * agents and Task Runs and leases shared service credentials, and the web - * app never calls it. Matched by route pattern, not URL spelling. + * External agents act through the shared machine credential, which reaches + * every Space, on the operator's machines and under the operator's logins, so + * a member may not run or steer one. RFS is that credential's own surface: it + * launches agents and Task Runs and leases shared service credentials, and + * the web app never calls it. The change-review routes configure the + * deployment. A member runs the Built-In agent instead, through `/api/agent`, + * in their own access and with their own model keys. Matched by route + * pattern, not URL spelling. */ -const AGENT_ROUTES = [ - '/api/agent', - '/api/acp', - '/api/agent-change-review', - '/api/rfs', -]; +const ADMIN_AGENT_ROUTES = ['/api/acp', '/api/agent-change-review', '/api/rfs']; /** * The one value a request gives for `field` across its route parameters, @@ -103,17 +101,23 @@ export function registerSpaceAccess(app: FastifyInstance): void { const route = request.routeOptions.url ?? ''; if ( !identity.owner && - (threadId || - request.routeOptions.config?.invokesAgent || - AGENT_ROUTES.some( + (request.routeOptions.config?.invokesAgent || + ADMIN_AGENT_ROUTES.some( (prefix) => route === prefix || route.startsWith(`${prefix}/`), )) ) { return reply.code(403).send({ - message: 'Agents and conversations require an owner', + message: 'External agents and their settings require an administrator', code: 'AGENT_ACCESS_REQUIRED', }); } + // A conversation lives in a Space, and is reached only through one the + // caller may use. + if (!identity.owner && threadId && !canvasId) + return reply.code(400).send({ + message: 'A conversation is addressed through its Space', + code: 'SPACE_ACCESS_AMBIGUOUS', + }); const checks: Array<[AccessLevel, string]> = []; if (canvasId) checks.push([level, canvasId]); From 8a8d7b8696cd2b99c7f7fd254cbe19a98669e2e7 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 18:12:15 +0800 Subject: [PATCH 13/17] feat(web): renew a lapsing session without leaving the page Sign-in now asks for offline_access and keeps the refresh token in page memory only. The page renews its session a minute before the access token expires and on any 401; if it cannot, the sign-in screen opens over the still-running app and signs in through a popup, then resends the saves the lapse refused. With HUABU_SIGN_OUT_PROVIDER=true, signing out also ends the identity provider's session through its end_session_endpoint. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/modules/identity/config.ts | 5 + apps/server/src/modules/identity/http.ts | 8 +- apps/server/src/modules/identity/index.ts | 1 + apps/server/src/modules/identity/service.ts | 2 + apps/web/src/api/identity.ts | 20 +- .../src/components/Panels/Header/AppMenu.tsx | 2 +- .../src/components/Shell/SignInGate.test.tsx | 80 +++++- apps/web/src/components/Shell/SignInGate.tsx | 85 +++++- apps/web/src/store/canvasStore.ts | 11 + apps/web/src/utils/oidcLogin.test.ts | 96 +++++++ apps/web/src/utils/oidcLogin.ts | 272 +++++++++++++++--- packages/shared/src/types/api/identity.ts | 4 +- 12 files changed, 515 insertions(+), 71 deletions(-) create mode 100644 apps/web/src/utils/oidcLogin.test.ts diff --git a/apps/server/src/modules/identity/config.ts b/apps/server/src/modules/identity/config.ts index 9b1c0c661..dddf61ab7 100644 --- a/apps/server/src/modules/identity/config.ts +++ b/apps/server/src/modules/identity/config.ts @@ -23,6 +23,8 @@ export type IdentityConfig = /** Principal provisioned as Bubble system owner at startup. */ owner?: string; postgresUrl: string; + /** Signing out of Huabu also ends the identity provider's session. */ + providerSignOut?: boolean; }; export function resolveIdentityConfig( @@ -67,6 +69,9 @@ export function resolveIdentityConfig( authenticators, ...(owner ? { owner } : {}), postgresUrl, + ...(env.HUABU_SIGN_OUT_PROVIDER === 'true' + ? { providerSignOut: true } + : {}), }; } diff --git a/apps/server/src/modules/identity/http.ts b/apps/server/src/modules/identity/http.ts index a6522b100..9cd01138d 100644 --- a/apps/server/src/modules/identity/http.ts +++ b/apps/server/src/modules/identity/http.ts @@ -259,7 +259,13 @@ export function registerIdentity( if (!identity) throw new Error('Identity admission did not resolve a principal'); const { principal, member, owner } = identity; - return { provider: service.provider, principal, member, owner }; + return { + provider: service.provider, + principal, + member, + owner, + ...(service.providerSignOut ? { providerSignOut: true } : {}), + }; }, ); diff --git a/apps/server/src/modules/identity/index.ts b/apps/server/src/modules/identity/index.ts index 72477062d..4f5db9fab 100644 --- a/apps/server/src/modules/identity/index.ts +++ b/apps/server/src/modules/identity/index.ts @@ -48,6 +48,7 @@ export function createIdentity( service: { provider: 'bubble', challenge: 'Bearer realm="Huabu"', + ...(config.providerSignOut ? { providerSignOut: true } : {}), authenticate: async (credentials) => (await (opening ??= open())).service.authenticate(credentials), // Present from the start so routes can tell Bubble mode by it; each call diff --git a/apps/server/src/modules/identity/service.ts b/apps/server/src/modules/identity/service.ts index e29768b21..26e171a4c 100644 --- a/apps/server/src/modules/identity/service.ts +++ b/apps/server/src/modules/identity/service.ts @@ -88,6 +88,8 @@ export interface ResourceDirectory { /** Resolve afresh for each request so revocation is not hidden by a host cache. */ export interface IdentityService { readonly provider: IdentityResponse['provider']; + /** Signing out also ends the identity provider's own session. */ + readonly providerSignOut?: boolean; readonly challenge: string; /** * Admits callers without any credential, as local mode does without Basic diff --git a/apps/web/src/api/identity.ts b/apps/web/src/api/identity.ts index 66fd9ff74..88ab80120 100644 --- a/apps/web/src/api/identity.ts +++ b/apps/web/src/api/identity.ts @@ -87,7 +87,25 @@ export async function endSession(): Promise { * staying put, when the Server did not confirm: the cookie would otherwise * admit the same account again on arrival. */ -export async function signOut(): Promise { +export async function signOut( + options: { providerSignOut?: boolean } = {}, +): Promise { await endSession(); + const { forgetTokens, providerSignOutUrl, heldAuthenticator } = + await import('../utils/oidcLogin'); + forgetTokens(); + // The provider's own session would otherwise sign the next person straight + // back in as this one, which matters on a shared computer. + if (options.providerSignOut) { + const authenticators = (await listInteractiveAuthenticators()) ?? []; + const authenticator = + heldAuthenticator() ?? + (authenticators.length === 1 ? authenticators[0] : null); + const url = authenticator ? await providerSignOutUrl(authenticator) : null; + if (url) { + window.location.assign(url); + return; + } + } window.location.assign('/'); } diff --git a/apps/web/src/components/Panels/Header/AppMenu.tsx b/apps/web/src/components/Panels/Header/AppMenu.tsx index c06da527a..eda5b7167 100644 --- a/apps/web/src/components/Panels/Header/AppMenu.tsx +++ b/apps/web/src/components/Panels/Header/AppMenu.tsx @@ -102,7 +102,7 @@ export const AppMenu: React.FC = ({ try { if (!(await savedBeforeSignOut())) failure = 'auth.signOutUnsaved'; else { - await signOut(); + await signOut({ providerSignOut: identity?.providerSignOut }); return; } } catch { diff --git a/apps/web/src/components/Shell/SignInGate.test.tsx b/apps/web/src/components/Shell/SignInGate.test.tsx index 7a8594263..35d9ee69b 100644 --- a/apps/web/src/components/Shell/SignInGate.test.tsx +++ b/apps/web/src/components/Shell/SignInGate.test.tsx @@ -14,7 +14,11 @@ vi.mock('../../pages/WorkspaceLoadingScreen', () => ({ WorkspaceLoadingScreen: () => null, })); const unsaved = vi.hoisted(() => vi.fn(() => false)); -vi.mock('../../store/canvasStore', () => ({ hasUnsavedCanvasEdits: unsaved })); +const resend = vi.hoisted(() => vi.fn(async () => {})); +vi.mock('../../store/canvasStore', () => ({ + hasUnsavedCanvasEdits: unsaved, + resendUnsavedCanvasEdits: resend, +})); vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key: string, values?: Record) => @@ -136,7 +140,7 @@ describe('SignInGate', () => { expect(container.textContent).toContain('Carol'); }); - it('warns that signing in again loses edits a lapsed session could not save', async () => { + it('keeps the app, and its unsaved edits, under the sign-in screen when a session lapses', async () => { routes['GET /api/identity'] = () => json(MEMBER); await mount(); expect(container.textContent).toBe('app'); @@ -144,20 +148,72 @@ describe('SignInGate', () => { routes['GET /api/identity'] = () => json({}, 401); routes['GET /bubble/v1/auth/authenticators'] = () => json({ authenticators: [ENTRA] }); - const lapse = async (hasUnsaved: boolean) => { - unsaved.mockReturnValue(hasUnsaved); - await act(async () => { - window.dispatchEvent(new Event(AUTH_REQUIRED_EVENT)); - }); - for (let i = 0; i < 5; i++) await act(async () => {}); - }; - await lapse(true); + unsaved.mockReturnValue(true); + await act(async () => { + window.dispatchEvent(new Event(AUTH_REQUIRED_EVENT)); + }); + for (let i = 0; i < 5; i++) await act(async () => {}); + // Signing in happens in a popup, so nothing is lost and nothing warns. + expect(container.textContent).toContain('app'); expect(container.textContent).toContain('auth.signInTitle'); - expect(container.textContent).toContain('auth.signInUnsaved'); - await lapse(false); expect(container.textContent).not.toContain('auth.signInUnsaved'); }); + it('renews a lapsing session in place with the refresh token the login gave', async () => { + sessionStorage.setItem( + 'huabu.oidc.pending', + JSON.stringify({ + state: 'expected', + verifier: 'verifier', + authenticator: ENTRA, + returnTo: '/canvas/mine', + }), + ); + window.history.replaceState( + null, + '', + '/auth/callback?code=the-code&state=expected', + ); + routes[ + 'GET https://login.example/tenant/v2.0/.well-known/openid-configuration' + ] = () => json({ token_endpoint: 'https://login.example/token' }); + let issued = 0; + routes['POST https://login.example/token'] = () => + json({ + access_token: `access-${++issued}`, + refresh_token: `refresh-${issued}`, + }); + routes['POST /api/identity/session'] = () => + new Response(null, { status: 204 }); + routes['GET /api/identity'] = () => json(MEMBER); + await mount(); + expect(container.textContent).toBe('app'); + + await act(async () => { + window.dispatchEvent(new Event(AUTH_REQUIRED_EVENT)); + }); + for (let i = 0; i < 5; i++) await act(async () => {}); + const grants = calls + .filter((call) => call.url === 'https://login.example/token') + .map((call) => + Object.fromEntries(new URLSearchParams(String(call.init?.body))), + ); + expect(grants[1]).toMatchObject({ + grant_type: 'refresh_token', + refresh_token: 'refresh-1', + client_id: 'spa', + }); + const sessions = calls.filter( + (call) => call.url === '/api/identity/session', + ); + expect( + new Headers(sessions.at(-1)?.init?.headers).get('Authorization'), + ).toBe('Bearer access-2'); + // The page never left, and what the lapse refused goes out again. + expect(container.textContent).toBe('app'); + expect(resend).toHaveBeenCalled(); + }); + it('completes a provider redirect by handing the token to the Server', async () => { sessionStorage.setItem( 'huabu.oidc.pending', diff --git a/apps/web/src/components/Shell/SignInGate.tsx b/apps/web/src/components/Shell/SignInGate.tsx index 242fbaa10..07091d7be 100644 --- a/apps/web/src/components/Shell/SignInGate.tsx +++ b/apps/web/src/components/Shell/SignInGate.tsx @@ -17,7 +17,13 @@ import { API_CONFIG } from '../../config/api'; import { APP_NAME } from '../../config/app'; import { WorkspaceLoadingScreen } from '../../pages/WorkspaceLoadingScreen'; import { useIdentityStore } from '../../store/identityStore'; -import { beginLogin, completeLogin } from '../../utils/oidcLogin'; +import { + beginLogin, + completeLogin, + refreshTokens, + signInWithPopup, + type SignedInTokens, +} from '../../utils/oidcLogin'; import { Button } from '../Common/Button'; import type { IdentityResponse } from '@huabu/shared'; @@ -73,6 +79,22 @@ export function SignInGate({ children }: { children: ReactNode }) { const callback = useRef>(undefined); // Once the app has run, a lapsed session can strand its unsaved edits. const appStarted = useRef(false); + const renewalTimer = useRef(undefined); + + /** + * Hand fresh tokens to the Server, and renew them a minute before they + * expire while this page holds a refresh token. + */ + const adopt = useCallback(async (tokens: SignedInTokens) => { + await startSession(tokens.accessToken); + window.clearTimeout(renewalTimer.current); + if (tokens.expiresIn && tokens.expiresIn > 90) + renewalTimer.current = window.setTimeout( + () => void refreshTokens().then((next) => next && adopt(next)), + (tokens.expiresIn - 60) * 1000, + ); + }, []); + useEffect(() => () => window.clearTimeout(renewalTimer.current), []); const check = useCallback( async (loginError?: string) => { @@ -136,32 +158,74 @@ export function SignInGate({ children }: { children: ReactNode }) { useEffect(() => { callback.current ??= (async () => { try { - const token = await completeLogin(); - if (token) await startSession(token); + const tokens = await completeLogin(); + if (tokens) await adopt(tokens); return undefined; } catch (error) { return error instanceof Error ? error.message : String(error); } })(); void callback.current.then((loginError) => check(loginError)); - }, [check]); + }, [check, adopt]); useEffect(() => { - const recheck = () => void check(); + // A lapsed session renews in place when this page holds a refresh token; + // whatever it refused is then sent again. + const recheck = () => + void (async () => { + const tokens = appStarted.current ? await refreshTokens() : null; + if (tokens) { + try { + await adopt(tokens); + await resend(); + } catch { + // Fall through to the sign-in check below. + } + } + await check(); + })(); window.addEventListener(AUTH_REQUIRED_EVENT, recheck); return () => window.removeEventListener(AUTH_REQUIRED_EVENT, recheck); - }, [check]); + }, [check, adopt]); + + /** Sign in again without leaving the page, then resend what was refused. */ + const signInInPlace = useCallback( + async (authenticator: InteractiveAuthenticator) => { + await adopt(await signInWithPopup(authenticator)); + await check(); + await resend(); + }, + [adopt, check], + ); if (state.kind === 'ready') return <>{children}; if (state.kind === 'checking') return ; + // The app keeps running under a lapsed session, so its edits survive. + if (state.kind === 'signIn' && appStarted.current) + return ( + <> + {children} +
+ +
+ + ); return ; } +async function resend(): Promise { + const { resendUnsavedCanvasEdits } = await import('../../store/canvasStore'); + await resendUnsavedCanvasEdits(); +} + /** The sign-in and no-access screens, in the Welcome page's frame. */ export function SignInScreen({ state, + onSignIn, }: { state: Exclude; + /** Sign in without leaving the page; the provider's redirect otherwise. */ + onSignIn?: (authenticator: InteractiveAuthenticator) => Promise; }) { const { t } = useTranslation(); const [pending, setPending] = useState(null); @@ -215,7 +279,12 @@ export function SignInScreen({ disabled={pending !== null} onClick={() => { setPending(authenticator.issuer); - void beginLogin(authenticator).catch(() => setPending(null)); + void (onSignIn ?? beginLogin)(authenticator).then( + () => { + if (onSignIn) setPending(null); + }, + () => setPending(null), + ); }} > {pending === authenticator.issuer @@ -253,7 +322,7 @@ export function SignInScreen({

)} - {state.kind === 'signIn' && state.unsavedEdits && ( + {state.kind === 'signIn' && state.unsavedEdits && !onSignIn && (

{t('auth.signInUnsaved')}

diff --git a/apps/web/src/store/canvasStore.ts b/apps/web/src/store/canvasStore.ts index 10837a9c5..e84081ccc 100644 --- a/apps/web/src/store/canvasStore.ts +++ b/apps/web/src/store/canvasStore.ts @@ -1134,6 +1134,17 @@ export function hasUnsavedCanvasEdits(): boolean { ); } +/** + * Resend what a lapsed session refused, once it has been renewed. Best + * effort: a save that fails again is reported as any other save failure. + */ +export async function resendUnsavedCanvasEdits(): Promise { + const { canvasId } = useCanvasStore.getState(); + if (!canvasId) return; + if (structureSaveErrors.has(canvasId)) structureScheduler.schedule(); + await drainPendingSaves(); +} + export class CanvasSubmissionSaveError extends Error { readonly code = 'canvas_save_failed'; diff --git a/apps/web/src/utils/oidcLogin.test.ts b/apps/web/src/utils/oidcLogin.test.ts new file mode 100644 index 000000000..e99345ce6 --- /dev/null +++ b/apps/web/src/utils/oidcLogin.test.ts @@ -0,0 +1,96 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { refreshTokens, signInWithPopup } from './oidcLogin'; + +const ENTRA = { + driver: 'entra', + interactive: true as const, + issuer: 'https://login.example/tenant/v2.0', + authorizationUrl: 'https://login.example/tenant/authorize', + clientId: 'spa', + scopes: ['api://huabu/access'], +}; + +afterEach(() => { + vi.unstubAllGlobals(); + vi.restoreAllMocks(); +}); + +describe('signing in again in a popup', () => { + it('redeems the code the popup posts back, with a verifier only this page held', async () => { + const popup = { closed: false, location: { href: '' } }; + vi.spyOn(window, 'open').mockReturnValue(popup as unknown as Window); + const bodies: Record[] = []; + vi.stubGlobal( + 'fetch', + vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { + const url = String(input); + if (url.endsWith('/.well-known/openid-configuration')) + return Response.json({ token_endpoint: 'https://login.example/t' }); + bodies.push( + Object.fromEntries(new URLSearchParams(String(init?.body))), + ); + return Response.json({ + access_token: 'fresh', + refresh_token: 'refresh', + expires_in: 3600, + }); + }), + ); + + const signingIn = signInWithPopup(ENTRA); + await vi.waitFor(() => expect(popup.location.href).not.toBe('')); + const sent = new URL(popup.location.href); + expect(sent.searchParams.get('scope')).toContain('offline_access'); + const state = sent.searchParams.get('state')!; + + // Another origin, or another login's state, is ignored. + window.dispatchEvent( + new MessageEvent('message', { + origin: 'https://evil.example', + data: { type: 'huabu.oidc.popup', state, code: 'stolen' }, + }), + ); + window.dispatchEvent( + new MessageEvent('message', { + origin: window.location.origin, + data: { type: 'huabu.oidc.popup', state: 'popup.other', code: 'x' }, + }), + ); + window.dispatchEvent( + new MessageEvent('message', { + origin: window.location.origin, + data: { type: 'huabu.oidc.popup', state, code: 'the-code' }, + }), + ); + + await expect(signingIn).resolves.toEqual({ + accessToken: 'fresh', + expiresIn: 3600, + }); + expect(bodies).toHaveLength(1); + expect(bodies[0]).toMatchObject({ + grant_type: 'authorization_code', + code: 'the-code', + client_id: 'spa', + }); + expect(bodies[0].code_verifier).toBeTruthy(); + + // The refresh token it brought renews the next session. + await expect(refreshTokens()).resolves.toMatchObject({ + accessToken: 'fresh', + }); + expect(bodies[1]).toMatchObject({ + grant_type: 'refresh_token', + refresh_token: 'refresh', + }); + }); + + it('fails plainly when the browser blocks the window', async () => { + vi.spyOn(window, 'open').mockReturnValue(null); + await expect(signInWithPopup(ENTRA)).rejects.toThrow(/blocked/); + }); +}); diff --git a/apps/web/src/utils/oidcLogin.ts b/apps/web/src/utils/oidcLogin.ts index aea32786d..186503aa4 100644 --- a/apps/web/src/utils/oidcLogin.ts +++ b/apps/web/src/utils/oidcLogin.ts @@ -6,11 +6,15 @@ import type { InteractiveAuthenticator } from '../api/identity'; /** * Browser login against whichever identity provider Bubble discovery names: * an OAuth authorization-code flow with PKCE, so no client secret is needed. - * Only the access token's handover to the Server outlives the redirect; the - * Server keeps it, and this module keeps nothing once the login completes. + * The Server keeps the access token in its session cookie. This page keeps a + * refresh token, when the provider issues one, in memory only: it renews the + * session in place while the page lives, and is gone with it. */ const PENDING_KEY = 'huabu.oidc.pending'; +/** A login run in a popup reports back to its opener instead of finishing. */ +const POPUP_STATE_PREFIX = 'popup.'; +const POPUP_MESSAGE = 'huabu.oidc.popup'; interface PendingLogin { state: string; @@ -19,6 +23,20 @@ interface PendingLogin { returnTo: string; } +/** What a token endpoint answers, as far as this module reads it. */ +export interface SignedInTokens { + accessToken: string; + /** Seconds until the access token expires, when the provider says. */ + expiresIn?: number; +} + +interface HeldRefresh { + authenticator: InteractiveAuthenticator; + refreshToken: string; +} + +let held: HeldRefresh | null = null; + function base64Url(bytes: Uint8Array): string { return btoa(String.fromCharCode(...bytes)) .replace(/\+/g, '-') @@ -37,46 +55,139 @@ function redirectUri(): string { return `${window.location.origin}${CALLBACK_PATH}`; } -/** Leave for the provider's login page; the browser returns to the callback. */ -export async function beginLogin( +async function authorizationUrl( authenticator: InteractiveAuthenticator, -): Promise { - const verifier = randomToken(); + state: string, + verifier: string, +): Promise { const challenge = base64Url( new Uint8Array( await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)), ), ); - const pending: PendingLogin = { - state: randomToken(), - verifier, - authenticator, - returnTo: `${window.location.pathname}${window.location.search}${window.location.hash}`, - }; - sessionStorage.setItem(PENDING_KEY, JSON.stringify(pending)); const params = new URLSearchParams({ response_type: 'code', client_id: authenticator.clientId, redirect_uri: redirectUri(), - scope: [...new Set([...authenticator.scopes, 'openid', 'profile'])].join( - ' ', - ), - state: pending.state, + // `offline_access` asks for a refresh token, so a lapsing session can be + // renewed without leaving the page. + scope: [ + ...new Set([ + ...authenticator.scopes, + 'openid', + 'profile', + 'offline_access', + ]), + ].join(' '), + state, code_challenge: challenge, code_challenge_method: 'S256', ...(authenticator.audience ? { audience: authenticator.audience } : {}), }); - window.location.assign(`${authenticator.authorizationUrl}?${params}`); + return `${authenticator.authorizationUrl}?${params}`; +} + +/** The provider's OpenID metadata, as far as this module reads it. */ +async function providerMetadata( + authenticator: InteractiveAuthenticator, +): Promise<{ token_endpoint?: string; end_session_endpoint?: string }> { + const metadata = await fetch( + `${authenticator.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`, + ); + if (!metadata.ok) throw new Error('Could not reach the sign-in provider'); + return (await metadata.json()) as { + token_endpoint?: string; + end_session_endpoint?: string; + }; +} + +async function requestTokens( + authenticator: InteractiveAuthenticator, + grant: Record, +): Promise { + const { token_endpoint: tokenEndpoint } = + await providerMetadata(authenticator); + if (!tokenEndpoint) + throw new Error('The sign-in provider has no token endpoint'); + const response = await fetch(tokenEndpoint, { + method: 'POST', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + body: new URLSearchParams({ client_id: authenticator.clientId, ...grant }), + }); + const token = (await response.json().catch(() => ({}))) as { + access_token?: string; + refresh_token?: string; + expires_in?: number; + error_description?: string; + }; + if (!response.ok || !token.access_token) + throw new Error( + token.error_description ?? 'Sign-in could not be completed', + ); + // Providers that rotate refresh tokens send a new one with each use. + if (token.refresh_token) + held = { authenticator, refreshToken: token.refresh_token }; + return { + accessToken: token.access_token, + ...(typeof token.expires_in === 'number' + ? { expiresIn: token.expires_in } + : {}), + }; +} + +function exchangeCode( + authenticator: InteractiveAuthenticator, + code: string, + verifier: string, +): Promise { + return requestTokens(authenticator, { + grant_type: 'authorization_code', + code, + redirect_uri: redirectUri(), + code_verifier: verifier, + }); +} + +/** Leave for the provider's login page; the browser returns to the callback. */ +export async function beginLogin( + authenticator: InteractiveAuthenticator, +): Promise { + const pending: PendingLogin = { + state: randomToken(), + verifier: randomToken(), + authenticator, + returnTo: `${window.location.pathname}${window.location.search}${window.location.hash}`, + }; + sessionStorage.setItem(PENDING_KEY, JSON.stringify(pending)); + window.location.assign( + await authorizationUrl(authenticator, pending.state, pending.verifier), + ); } /** * Finish a login the provider has just redirected back from, returning its - * access token, or `null` when this page load is not such a return. + * tokens, or `null` when this page load is not such a return. In a sign-in + * popup, hand the provider's answer to the page that opened it and close. */ -export async function completeLogin(): Promise { +export async function completeLogin(): Promise { const url = new URL(window.location.href); if (url.pathname !== CALLBACK_PATH) return null; const state = url.searchParams.get('state'); + if (state?.startsWith(POPUP_STATE_PREFIX) && window.opener) { + (window.opener as Window).postMessage( + { + type: POPUP_MESSAGE, + state, + code: url.searchParams.get('code'), + error: + url.searchParams.get('error_description') ?? + url.searchParams.get('error'), + }, + window.location.origin, + ); + window.close(); + return null; + } const raw = sessionStorage.getItem(PENDING_KEY); if (!state || !raw) return null; const pending = JSON.parse(raw) as PendingLogin; @@ -90,35 +201,102 @@ export async function completeLogin(): Promise { throw new Error(url.searchParams.get('error_description') ?? error); const code = url.searchParams.get('code'); if (!code) throw new Error('The sign-in response carried no code'); + return exchangeCode(pending.authenticator, code, pending.verifier); +} - const metadata = await fetch( - `${pending.authenticator.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`, +/** + * Sign in again in a popup, leaving this page and its unsaved edits in + * place. The verifier never leaves this page's memory; the popup only carries + * the provider's code back. + */ +export async function signInWithPopup( + authenticator: InteractiveAuthenticator, +): Promise { + const state = `${POPUP_STATE_PREFIX}${randomToken()}`; + const verifier = randomToken(); + const popup = window.open( + 'about:blank', + 'huabu-sign-in', + 'popup,width=520,height=680', ); - if (!metadata.ok) throw new Error('Could not reach the sign-in provider'); - const { token_endpoint: tokenEndpoint } = (await metadata.json()) as { - token_endpoint?: string; - }; - if (!tokenEndpoint) - throw new Error('The sign-in provider has no token endpoint'); + if (!popup) throw new Error('The browser blocked the sign-in window'); + popup.location.href = await authorizationUrl(authenticator, state, verifier); + const code = await new Promise((resolve, reject) => { + const closedPoll = window.setInterval(() => { + if (!popup.closed) return; + cleanup(); + reject(new Error('The sign-in window was closed')); + }, 500); + const onMessage = (event: MessageEvent) => { + const data = event.data as { + type?: string; + state?: string; + code?: string | null; + error?: string | null; + }; + if ( + event.origin !== window.location.origin || + data?.type !== POPUP_MESSAGE || + data.state !== state + ) + return; + cleanup(); + if (data.code) resolve(data.code); + else reject(new Error(data.error ?? 'Sign-in could not be completed')); + }; + const cleanup = () => { + window.clearInterval(closedPoll); + window.removeEventListener('message', onMessage); + }; + window.addEventListener('message', onMessage); + }); + return exchangeCode(authenticator, code, verifier); +} - const response = await fetch(tokenEndpoint, { - method: 'POST', - headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, - body: new URLSearchParams({ - grant_type: 'authorization_code', - code, - redirect_uri: redirectUri(), - client_id: pending.authenticator.clientId, - code_verifier: pending.verifier, - }), +/** + * A fresh access token from the refresh token this page holds, or `null` + * when it holds none or the provider refuses it. + */ +export async function refreshTokens(): Promise { + const current = held; + if (!current) return null; + try { + return await requestTokens(current.authenticator, { + grant_type: 'refresh_token', + refresh_token: current.refreshToken, + }); + } catch { + if (held === current) held = null; + return null; + } +} + +/** The provider this page signed in with, while it holds a refresh token. */ +export function heldAuthenticator(): InteractiveAuthenticator | null { + return held?.authenticator ?? null; +} + +/** Forget the refresh token, as signing out must. */ +export function forgetTokens(): void { + held = null; +} + +/** + * Where to send the browser to end the provider's own session, or `null` + * when the provider advertises no logout endpoint. + */ +export async function providerSignOutUrl( + authenticator: InteractiveAuthenticator, +): Promise { + const { end_session_endpoint: endpoint } = await providerMetadata( + authenticator, + ).catch(() => ({ + end_session_endpoint: undefined, + })); + if (!endpoint) return null; + const params = new URLSearchParams({ + client_id: authenticator.clientId, + post_logout_redirect_uri: `${window.location.origin}/`, }); - const token = (await response.json().catch(() => ({}))) as { - access_token?: string; - error_description?: string; - }; - if (!response.ok || !token.access_token) - throw new Error( - token.error_description ?? 'Sign-in could not be completed', - ); - return token.access_token; + return `${endpoint}?${params}`; } diff --git a/packages/shared/src/types/api/identity.ts b/packages/shared/src/types/api/identity.ts index a9add34dc..1faa7dc4b 100644 --- a/packages/shared/src/types/api/identity.ts +++ b/packages/shared/src/types/api/identity.ts @@ -18,8 +18,10 @@ export const identityResponseSchema = z.object({ principal: identityPrincipalSchema, /** May use Huabu at all. */ member: z.boolean(), - /** May also change settings, credentials and agent configuration. */ + /** Administers the deployment: its settings, agents and people. */ owner: z.boolean(), + /** Signing out should also end the identity provider's own session. */ + providerSignOut: z.boolean().optional(), }); export type IdentityResponse = z.infer; From af0803219fd988e9f016547725efb0d997d3da83 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 18:12:15 +0800 Subject: [PATCH 14/17] feat(web): People settings for administrators, own settings for members Administrators of a Bubble deployment get a People tab to admit or revoke people and give Workspace roles. A member's Agent tab shows only Built-In setup, their own models and keys, and Settings no longer loads the external agent and readiness data they cannot read. Co-Authored-By: Claude Opus 5.5 --- apps/web/src/api/_routes.ts | 6 + apps/web/src/api/people.ts | 48 +++++ .../src/components/Settings/SettingsModal.tsx | 34 +++- .../Settings/sections/PeopleSettings.tsx | 178 ++++++++++++++++++ apps/web/src/i18n/resources/en/common.json | 17 ++ apps/web/src/i18n/resources/zh-CN/common.json | 17 ++ apps/web/src/store/settingsUiStore.ts | 7 +- 7 files changed, 297 insertions(+), 10 deletions(-) create mode 100644 apps/web/src/api/people.ts create mode 100644 apps/web/src/components/Settings/sections/PeopleSettings.tsx diff --git a/apps/web/src/api/_routes.ts b/apps/web/src/api/_routes.ts index b0db57594..f0b027e86 100644 --- a/apps/web/src/api/_routes.ts +++ b/apps/web/src/api/_routes.ts @@ -33,6 +33,12 @@ export const routes = { workspaceActivate: (workspaceId: string) => `/workspaces/${enc(workspaceId)}/activate`, + // ── People (Bubble administration) ──────────────────────────────── + people: '/people', + personMember: (principalId: string) => `/people/${enc(principalId)}/member`, + personWorkspace: (principalId: string, workspaceId: string) => + `/people/${enc(principalId)}/workspaces/${enc(workspaceId)}`, + // ── LLM ─────────────────────────────────────────────────────────── llmConfig: '/llm/config', llmImageConfig: '/llm/image-config', diff --git a/apps/web/src/api/people.ts b/apps/web/src/api/people.ts new file mode 100644 index 000000000..2bde0859b --- /dev/null +++ b/apps/web/src/api/people.ts @@ -0,0 +1,48 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { apiFetch } from './_client'; +import { routes } from './_routes'; + +import type { + Person, + SetPersonMemberRequest, + SetPersonWorkspaceRoleRequest, + WorkspaceRole, +} from '@huabu/shared'; + +export type { Person, WorkspaceRole }; + +/** Everyone the identity provider knows, for an administrator. */ +export async function listPeople(): Promise { + return apiFetch(routes.people, { + fallbackMessage: 'Failed to list people', + }); +} + +/** Admit someone to Huabu, or revoke their access. */ +export async function setPersonMember( + principalId: string, + member: boolean, +): Promise { + const body: SetPersonMemberRequest = { member }; + await apiFetch(routes.personMember(principalId), { + method: 'PUT', + json: body, + fallbackMessage: 'Failed to change access', + }); +} + +/** Give someone a role on a Workspace; `null` removes it. */ +export async function setPersonWorkspaceRole( + principalId: string, + workspaceId: string, + role: WorkspaceRole | null, +): Promise { + const body: SetPersonWorkspaceRoleRequest = { role }; + await apiFetch(routes.personWorkspace(principalId, workspaceId), { + method: 'PUT', + json: body, + fallbackMessage: 'Failed to change the Workspace role', + }); +} diff --git a/apps/web/src/components/Settings/SettingsModal.tsx b/apps/web/src/components/Settings/SettingsModal.tsx index c04151db6..8635f2c4e 100644 --- a/apps/web/src/components/Settings/SettingsModal.tsx +++ b/apps/web/src/components/Settings/SettingsModal.tsx @@ -26,7 +26,9 @@ import { AgentBehaviorSettings } from './sections/AgentBehaviorSettings'; import { ExternalAgentRuntimeSettings } from './sections/ExternalAgentRuntimeSettings'; import { GeneralSettings } from './sections/GeneralSettings'; import { LLMSettings } from './sections/LLMSettings'; +import { PeopleSettings } from './sections/PeopleSettings'; import { ServicesSettings } from './sections/ServicesSettings'; +import { useIdentityStore } from '../../store/identityStore'; /** Identifiers for the settings tabs (left-nav order). */ type SettingsTab = SettingsTabId; @@ -34,7 +36,11 @@ type SettingsTab = SettingsTabId; interface TabDef { id: SettingsTab; /** i18n key for the tab label. */ - labelKey: 'settings.general' | 'settings.agent' | 'settings.services'; + labelKey: + | 'settings.general' + | 'settings.agent' + | 'settings.services' + | 'settings.people'; } const TABS: TabDef[] = [ @@ -42,6 +48,7 @@ const TABS: TabDef[] = [ { id: 'services', labelKey: 'settings.services' }, { id: 'general', labelKey: 'settings.general' }, ]; +const PEOPLE_TAB: TabDef = { id: 'people', labelKey: 'settings.people' }; interface SettingsModalProps { isOpen: boolean; @@ -64,6 +71,14 @@ export const SettingsModal: React.FC = ({ onClose, }) => { const { t } = useTranslation(); + const identity = useIdentityStore((s) => s.identity); + // A Bubble member configures only their own models and credentials; the + // deployment, its external agents and its people are the administrators'. + const member = identity?.provider === 'bubble' && !identity.owner; + const tabs = + identity?.provider === 'bubble' && identity.owner + ? [...TABS, PEOPLE_TAB] + : TABS; const llmInit = useLLMStore((s) => s.init); const acpInit = useAcpProfilesStore((s) => s.init); const loadDeploymentReadiness = useDeploymentReadinessStore((s) => s.load); @@ -101,19 +116,19 @@ export const SettingsModal: React.FC = ({ }, [isOpen, activeTab]); useEffect(() => { - if (!isOpen) return; + if (!isOpen || member) return; void loadDeploymentReadiness(); - }, [isOpen, loadDeploymentReadiness]); + }, [isOpen, member, loadDeploymentReadiness]); // Load each registry only when its owning tab is visible. useEffect(() => { if (!isOpen) return; const targetTab = requestedTab ?? activeTab; - if (targetTab === 'agent') void acpInit(); - if (targetTab === 'builtIn') { + if (targetTab === 'agent' && !member) void acpInit(); + if (targetTab === 'builtIn' || (targetTab === 'agent' && member)) { void llmInit(); } - }, [isOpen, requestedTab, activeTab, llmInit, acpInit]); + }, [isOpen, requestedTab, activeTab, member, llmInit, acpInit]); // Close on Escape. useEffect(() => { @@ -151,7 +166,7 @@ export const SettingsModal: React.FC = ({ if (!isOpen) return null; const activeLabelKey = - TABS.find((tab) => tab.id === activeTab)?.labelKey ?? 'settings.general'; + tabs.find((tab) => tab.id === activeTab)?.labelKey ?? 'settings.general'; const contentTitle = activeTab === 'agent' && externalAgentsNavigation ? externalAgentsNavigation.title @@ -191,7 +206,7 @@ export const SettingsModal: React.FC = ({ > {t('settings.title')} - {TABS.map(({ id, labelKey }) => { + {tabs.map(({ id, labelKey }) => { const active = id === activeTab || (id === 'agent' && activeTab === 'builtIn'); return ( @@ -274,8 +289,9 @@ export const SettingsModal: React.FC = ({ )} + {activeTab === 'people' && } {isAgentTab && - (activeTab === 'builtIn' ? ( + (activeTab === 'builtIn' || member ? ( ) : ( <> diff --git a/apps/web/src/components/Settings/sections/PeopleSettings.tsx b/apps/web/src/components/Settings/sections/PeopleSettings.tsx new file mode 100644 index 000000000..862854761 --- /dev/null +++ b/apps/web/src/components/Settings/sections/PeopleSettings.tsx @@ -0,0 +1,178 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { X } from 'lucide-react'; +import { useCallback, useEffect, useMemo, useState } from 'react'; +import { useTranslation } from 'react-i18next'; + +import { + listPeople, + setPersonMember, + setPersonWorkspaceRole, + type Person, + type WorkspaceRole, +} from '../../../api/people'; +import { listWorkspaces } from '../../../api/workspace'; +import { useIdentityStore } from '../../../store/identityStore'; +import { Button } from '../../Common/Button'; +import { Select } from '../../Common/Select'; +import { toast } from '../../Common/Toast'; +import { Toggle } from '../../Common/Toggle'; + +import type { WorkspaceDescriptor } from '../../../api/workspace'; + +const ROLES: WorkspaceRole[] = ['owner', 'editor', 'viewer']; + +function personName(person: Person): string { + const { principal } = person; + return principal.displayName ?? principal.email ?? principal.principalId; +} + +/** + * Who may use this Huabu, and with which Workspace roles. Shown to + * administrators of a Bubble deployment; changes apply on each person's + * next request. + */ +export function PeopleSettings() { + const { t } = useTranslation(); + const self = useIdentityStore((s) => s.identity?.principal.principalId); + const [people, setPeople] = useState(null); + const [workspaces, setWorkspaces] = useState([]); + const [busy, setBusy] = useState(false); + + const load = useCallback(async () => { + const [nextPeople, nextWorkspaces] = await Promise.all([ + listPeople(), + listWorkspaces(), + ]); + setPeople(nextPeople); + setWorkspaces(nextWorkspaces); + }, []); + + useEffect(() => { + void load().catch(() => toast(t('people.loadFailed'), { tone: 'danger' })); + }, [load, t]); + + const change = async (action: () => Promise) => { + setBusy(true); + try { + await action(); + await load(); + } catch (error) { + toast(error instanceof Error ? error.message : t('people.saveFailed'), { + tone: 'danger', + }); + } finally { + setBusy(false); + } + }; + + const workspaceName = useMemo(() => { + const names = new Map(workspaces.map((w) => [w.workspaceId, w.name])); + return (workspaceId: string) => names.get(workspaceId) ?? workspaceId; + }, [workspaces]); + + const roleOptions = ROLES.map((role) => ({ + value: role, + label: t(`people.role.${role}`), + })); + + if (!people) + return

{t('people.loading')}

; + + return ( +
+

{t('people.intro')}

+
    + {people.map((person) => { + const id = person.principal.principalId; + const held = new Set(person.workspaces.map((w) => w.workspaceId)); + const addable = workspaces.filter((w) => !held.has(w.workspaceId)); + return ( +
  • +
    +
    +
    + {personName(person)} +
    +
    + {person.admin + ? t('people.administrator') + : person.principal.email && person.principal.displayName + ? person.principal.email + : id} +
    +
    + + void change(() => setPersonMember(id, member)) + } + /> +
    + {person.workspaces.length > 0 && ( +
      + {person.workspaces.map(({ workspaceId, role }) => ( +
    • + + {workspaceName(workspaceId)} + + ({ + value: w.workspaceId, + label: w.name, + }))} + value="" + placeholder={t('people.addToWorkspace')} + disabled={busy} + onChange={(workspaceId) => + void change(() => + setPersonWorkspaceRole(id, workspaceId, 'viewer'), + ) + } + /> + )} +
      • + ); + })} +
    +
+ ); +} diff --git a/apps/web/src/i18n/resources/en/common.json b/apps/web/src/i18n/resources/en/common.json index 98be7fa91..ecb45b82c 100644 --- a/apps/web/src/i18n/resources/en/common.json +++ b/apps/web/src/i18n/resources/en/common.json @@ -181,6 +181,7 @@ "title": "Settings", "open": "Open settings", "general": "General", + "people": "People", "agent": "Agent", "capabilities": "Capabilities", "capabilitiesDescription": "These Huabu-managed services can be configured as needed. Availability to an external Agent depends on that Agent's own capabilities.", @@ -1541,5 +1542,21 @@ "conversationAgentUnconfigured": "Connect an external Agent before starting a new conversation.", "nodeSaveFailed": "Couldn't write \"{{name}}\" to disk — the file may be locked or not writable.", "rateLimited": "Too many requests. Try again in {{seconds}} seconds." + }, + "people": { + "loading": "Loading people…", + "loadFailed": "Could not load people.", + "saveFailed": "Could not save the change.", + "intro": "Who may use this Huabu, and which Workspaces they can open. People appear here after they first sign in. Changes apply on their next request.", + "administrator": "Administrator", + "access": "Access", + "roleIn": "Role in {{workspace}}", + "removeRole": "Remove from this Workspace", + "addToWorkspace": "Add to a Workspace…", + "role": { + "owner": "Owner", + "editor": "Editor", + "viewer": "Viewer" + } } } diff --git a/apps/web/src/i18n/resources/zh-CN/common.json b/apps/web/src/i18n/resources/zh-CN/common.json index 4a806e6ae..6da97bcf0 100644 --- a/apps/web/src/i18n/resources/zh-CN/common.json +++ b/apps/web/src/i18n/resources/zh-CN/common.json @@ -181,6 +181,7 @@ "title": "设置", "open": "打开设置", "general": "通用", + "people": "成员", "agent": "Agent", "capabilities": "能力", "capabilitiesDescription": "这些由 Huabu 管理的服务可按需配置。外部 Agent 能否使用这些服务，取决于该 Agent 自身支持的能力。", @@ -1541,5 +1542,21 @@ "conversationAgentUnconfigured": "请先连接外部 Agent，再开始新对话。", "nodeSaveFailed": "「{{name}}」写盘失败，可能文件被占用或没有写入权限。", "rateLimited": "请求过于频繁，请在 {{seconds}} 秒后重试。" + }, + "people": { + "loading": "正在加载成员…", + "loadFailed": "无法加载成员。", + "saveFailed": "无法保存更改。", + "intro": "谁可以使用此 Huabu，以及能打开哪些工作区。成员首次登录后会出现在这里。更改在其下一次请求时生效。", + "administrator": "管理员", + "access": "访问权限", + "roleIn": "在 {{workspace}} 中的角色", + "removeRole": "从此工作区移除", + "addToWorkspace": "添加到工作区…", + "role": { + "owner": "所有者", + "editor": "编辑者", + "viewer": "查看者" + } } } diff --git a/apps/web/src/store/settingsUiStore.ts b/apps/web/src/store/settingsUiStore.ts index 4f01610e1..64324df63 100644 --- a/apps/web/src/store/settingsUiStore.ts +++ b/apps/web/src/store/settingsUiStore.ts @@ -19,7 +19,12 @@ import { create } from 'zustand'; * open and then cleared so a later plain `open()` reopens on the last * tab the user was viewing rather than snapping back. */ -export type SettingsTabId = 'general' | 'agent' | 'services' | 'builtIn'; +export type SettingsTabId = + | 'general' + | 'agent' + | 'services' + | 'builtIn' + | 'people'; interface SettingsUiState { isOpen: boolean; From 2dd1da32f7960898ec2bce78018a9101e635f157 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 18:19:58 +0800 Subject: [PATCH 15/17] fix(agent): offer members the Built-In agent when they start a conversation The web app picks a new conversation's agent from GET /api/acp/profiles, which refused members, so they could not start one. Members now read a listing with no external profiles and Built-In as the selectable agent. The App menu calls the switcher "Switch Workspace" for named Workspaces, and the People panel's add picker aligns with its rows. Co-Authored-By: Claude Opus 5.5 --- .../src/modules/agent/acp/profiles.route.ts | 13 +++++++ .../src/modules/security/space-access.test.ts | 5 +++ .../src/modules/security/space-access.ts | 3 ++ .../src/components/Panels/Header/AppMenu.tsx | 9 ++++- .../Settings/sections/PeopleSettings.tsx | 34 ++++++++++--------- 5 files changed, 47 insertions(+), 17 deletions(-) diff --git a/apps/server/src/modules/agent/acp/profiles.route.ts b/apps/server/src/modules/agent/acp/profiles.route.ts index 99da03fde..b4f7187d1 100644 --- a/apps/server/src/modules/agent/acp/profiles.route.ts +++ b/apps/server/src/modules/agent/acp/profiles.route.ts @@ -33,6 +33,7 @@ import { } from '@agenetes/agentlet-host'; import { + HUABU_AGENT_PROFILE_ID, agentProfileParamsSchema, createAcpProfileBodySchema, patchAgentProfileBodySchema, @@ -52,6 +53,7 @@ import { readProfileCapabilities, } from './profile-capabilities.js'; import { invalidateProfileSchemaCache } from './profile-schema-cache.js'; +import { personalSettingsOwner } from '../../identity/personal-settings.js'; import { isOwnerRequest } from '../../security/owner.js'; import { getAgentDefaults, @@ -220,6 +222,17 @@ const acpProfilesRoutes: FastifyPluginAsync = async (app) => { app.get<{ Reply: ApiResult }>( '/profiles', async (request, reply) => { + // A member runs the Built-In agent only: no external profile, device or + // daemon of the operator's is theirs to see. + if (personalSettingsOwner()) + return { + profiles: [], + selectableProfileIds: [HUABU_AGENT_PROFILE_ID], + connectedDevices: [], + folderPickerAgentletId: null, + agentlet: getDaemonSupervisor().getStatus(), + agentDefaults: getAgentDefaults(), + }; if (denyRemote(request, reply)) return; const registry = getAgentProfileRegistry(); if (!registry) { diff --git a/apps/server/src/modules/security/space-access.test.ts b/apps/server/src/modules/security/space-access.test.ts index 3d271bb4a..d085aa02e 100644 --- a/apps/server/src/modules/security/space-access.test.ts +++ b/apps/server/src/modules/security/space-access.test.ts @@ -61,6 +61,8 @@ function host() { app.get('/api/agent/history/:threadId', ok); app.post('/api/agent', ok); app.post('/api/acp/threads/:threadId/permission', ok); + app.get('/api/acp/profiles', ok); + app.post('/api/acp/profiles', ok); app.get('/api/canvas/:canvasId/threads/:threadId/changes', ok); app.post('/api/canvas-titles', ok); app.post('/api/rfs/:canvasId/services/:serviceId/lease', ok); @@ -185,7 +187,10 @@ describe('Space access', () => { 404, ); expect(await member({ url: '/api/agent/history/t1' })).toBe(400); + // Listing agents shows them Built-In; changing profiles does not. + expect(await member({ url: '/api/acp/profiles' })).toBe(200); for (const request of [ + { method: 'POST', url: '/api/acp/profiles' }, { method: 'POST', url: '/api/acp/threads/t1/permission?canvasId=mine' }, // The machine credential's own surface: agent launches, Task Runs and // shared service credentials. diff --git a/apps/server/src/modules/security/space-access.ts b/apps/server/src/modules/security/space-access.ts index 82f903605..68a03517b 100644 --- a/apps/server/src/modules/security/space-access.ts +++ b/apps/server/src/modules/security/space-access.ts @@ -38,6 +38,8 @@ type Fields = Record | undefined; * pattern, not URL spelling. */ const ADMIN_AGENT_ROUTES = ['/api/acp', '/api/agent-change-review', '/api/rfs']; +/** The one external-agent route a member reads: it lists only Built-In. */ +const MEMBER_AGENT_LISTING = '/api/acp/profiles'; /** * The one value a request gives for `field` across its route parameters, @@ -101,6 +103,7 @@ export function registerSpaceAccess(app: FastifyInstance): void { const route = request.routeOptions.url ?? ''; if ( !identity.owner && + !(request.method === 'GET' && route === MEMBER_AGENT_LISTING) && (request.routeOptions.config?.invokesAgent || ADMIN_AGENT_ROUTES.some( (prefix) => route === prefix || route.startsWith(`${prefix}/`), diff --git a/apps/web/src/components/Panels/Header/AppMenu.tsx b/apps/web/src/components/Panels/Header/AppMenu.tsx index eda5b7167..d7065302c 100644 --- a/apps/web/src/components/Panels/Header/AppMenu.tsx +++ b/apps/web/src/components/Panels/Header/AppMenu.tsx @@ -76,6 +76,9 @@ export const AppMenu: React.FC = ({ const canChangeWorkspace = useWorkspaceStore( (s) => s.capabilities?.canChangeWorkspace ?? true, ); + const namedWorkspaces = useWorkspaceStore( + (s) => s.capabilities?.namedWorkspaces === true, + ); const identity = useIdentityStore((s) => s.identity); const worldCanvasId = useWorkspaceStore((s) => s.worldCanvasId); const worldEnabled = useWorkspaceStore((s) => s.worldEnabled); @@ -194,7 +197,11 @@ export const AppMenu: React.FC = ({ {canChangeWorkspace && ( navigate('/setup'))}> - {t('navigation.switchWorkspace')} + {t( + namedWorkspaces + ? 'workspace.switcher' + : 'navigation.switchWorkspace', + )} )} diff --git a/apps/web/src/components/Settings/sections/PeopleSettings.tsx b/apps/web/src/components/Settings/sections/PeopleSettings.tsx index 862854761..5c69fbded 100644 --- a/apps/web/src/components/Settings/sections/PeopleSettings.tsx +++ b/apps/web/src/components/Settings/sections/PeopleSettings.tsx @@ -152,22 +152,24 @@ export function PeopleSettings() { )} {addable.length > 0 && ( - ({ + value: w.workspaceId, + label: w.name, + }))} + value="" + placeholder={t('people.addToWorkspace')} + disabled={busy} + onChange={(workspaceId) => + void change(() => + setPersonWorkspaceRole(id, workspaceId, 'viewer'), + ) + } + /> + )} ); From c97a2bfc3336864fad05cb83514f11dcc3871aff Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 18:24:22 +0800 Subject: [PATCH 16/17] chore(identity): narrow instead of asserting non-null Co-Authored-By: Claude Opus 5.5 --- apps/server/src/modules/identity/bubble.ts | 8 +++++++- apps/server/src/modules/identity/index.ts | 12 +++++------- .../src/modules/identity/people.route.ts | 19 ++++++++++++------- apps/server/src/modules/identity/request.ts | 10 ++++++++++ apps/server/src/modules/workspaces.route.ts | 8 ++++---- 5 files changed, 38 insertions(+), 19 deletions(-) diff --git a/apps/server/src/modules/identity/bubble.ts b/apps/server/src/modules/identity/bubble.ts index ca015102a..6bcffdb9b 100644 --- a/apps/server/src/modules/identity/bubble.ts +++ b/apps/server/src/modules/identity/bubble.ts @@ -279,7 +279,13 @@ export async function openBubbleIdentity(options: { store: BubbleStore; preferences: WorkspacePreferences; resources: ResourceDirectory; -}): Promise<{ service: IdentityService; plugin: FastifyPluginAsync }> { +}): Promise<{ + service: IdentityService & + Required< + Pick + >; + plugin: FastifyPluginAsync; +}> { const { store, owner, preferences } = options; const runtime = await createBubbleRuntime({ store, diff --git a/apps/server/src/modules/identity/index.ts b/apps/server/src/modules/identity/index.ts index 4f5db9fab..1cf7ed836 100644 --- a/apps/server/src/modules/identity/index.ts +++ b/apps/server/src/modules/identity/index.ts @@ -54,18 +54,16 @@ export function createIdentity( // Present from the start so routes can tell Bubble mode by it; each call // opens Bubble on demand like every other member here. people: { - list: async () => (await (opening ??= open())).service.people!.list(), + list: async () => (await (opening ??= open())).service.people.list(), setMember: async (...args) => - (await (opening ??= open())).service.people!.setMember(...args), + (await (opening ??= open())).service.people.setMember(...args), setWorkspaceRole: async (...args) => - (await (opening ??= open())).service.people!.setWorkspaceRole( - ...args, - ), + (await (opening ??= open())).service.people.setWorkspaceRole(...args), }, selectWorkspace: async (identity) => - (await (opening ??= open())).service.selectWorkspace!(identity), + (await (opening ??= open())).service.selectWorkspace(identity), chooseWorkspace: async (identity, workspaceId) => - (await (opening ??= open())).service.chooseWorkspace!( + (await (opening ??= open())).service.chooseWorkspace( identity, workspaceId, ), diff --git a/apps/server/src/modules/identity/people.route.ts b/apps/server/src/modules/identity/people.route.ts index 4a0962948..200a09c97 100644 --- a/apps/server/src/modules/identity/people.route.ts +++ b/apps/server/src/modules/identity/people.route.ts @@ -6,7 +6,7 @@ import { setPersonWorkspaceRoleSchema, } from '@huabu/shared'; -import { getRequestIdentity } from './request.js'; +import { getRequestIdentity, requireRequestIdentity } from './request.js'; import { getWorkspaceRepository } from '../storage/index.js'; import type { IdentityService } from './service.js'; @@ -23,8 +23,13 @@ const peopleRoutes: FastifyPluginAsync<{ service: IdentityService }> = async ( { service }, ) => { const people = service.people; + if (!people) { + app.addHook('preHandler', async (_request, reply) => + reply.code(404).send({ message: 'Not found' }), + ); + return; + } app.addHook('preHandler', async (request, reply) => { - if (!people) return reply.code(404).send({ message: 'Not found' }); if (!getRequestIdentity(request)?.owner) return reply.code(403).send({ message: 'Administering people requires an administrator', @@ -32,7 +37,7 @@ const peopleRoutes: FastifyPluginAsync<{ service: IdentityService }> = async ( }); }); - app.get('/', async () => people!.list()); + app.get('/', async () => people.list()); app.put<{ Params: { principalId: string } }>( '/:principalId/member', @@ -40,14 +45,14 @@ const peopleRoutes: FastifyPluginAsync<{ service: IdentityService }> = async ( const body = setPersonMemberSchema.safeParse(request.body); if (!body.success) return reply.code(400).send({ message: 'Invalid request body' }); - const by = getRequestIdentity(request)!.principal.principalId; + const by = requireRequestIdentity(request).principal.principalId; // An administrator cannot lock themselves out from here. if (!body.data.member && request.params.principalId === by) return reply .code(409) .send({ message: 'You cannot revoke your own access' }); if ( - !(await people!.setMember( + !(await people.setMember( request.params.principalId, body.data.member, by, @@ -67,9 +72,9 @@ const peopleRoutes: FastifyPluginAsync<{ service: IdentityService }> = async ( const { principalId, workspaceId } = request.params; if (body.data.role && !(await getWorkspaceRepository().get(workspaceId))) return reply.code(404).send({ message: 'Workspace not found' }); - const by = getRequestIdentity(request)!.principal.principalId; + const by = requireRequestIdentity(request).principal.principalId; if ( - !(await people!.setWorkspaceRole( + !(await people.setWorkspaceRole( principalId, workspaceId, body.data.role, diff --git a/apps/server/src/modules/identity/request.ts b/apps/server/src/modules/identity/request.ts index 1cf01a998..3b41b0fb7 100644 --- a/apps/server/src/modules/identity/request.ts +++ b/apps/server/src/modules/identity/request.ts @@ -21,6 +21,16 @@ export function setRequestIdentity( identities.set(request, identity); } +/** The identity of a request admission has resolved; a server bug otherwise. */ +export function requireRequestIdentity( + request: FastifyRequest, +): ResolvedIdentity { + const identity = identities.get(request); + if (!identity) + throw new Error('Identity admission did not resolve a principal'); + return identity; +} + /** Transport-resolved identity, never a caller-supplied principal header/body. */ export function getRequestIdentity( request: FastifyRequest, diff --git a/apps/server/src/modules/workspaces.route.ts b/apps/server/src/modules/workspaces.route.ts index 0bae50e69..11242c42f 100644 --- a/apps/server/src/modules/workspaces.route.ts +++ b/apps/server/src/modules/workspaces.route.ts @@ -8,8 +8,8 @@ import { z } from 'zod'; import { workspaceCreateSchema, workspaceRenameSchema } from '@huabu/shared'; import { - getRequestIdentity, getRequestWorkspaceChooser, + requireRequestIdentity, } from './identity/request.js'; import { migrateLegacyDesktopWorkspaceStore } from './legacy-desktop-workspace-store.js'; import { resetPreprocessDispatcher } from './preprocessing/index.js'; @@ -213,7 +213,7 @@ function personal(request: FastifyRequest): boolean { async function enterable( request: FastifyRequest, ): Promise { - const allowed = await getRequestIdentity(request)!.access.workspaces(); + const allowed = await requireRequestIdentity(request).access.workspaces(); const all = await getWorkspaceRepository().list(); return allowed === 'all' ? all @@ -224,7 +224,7 @@ async function canManage( request: FastifyRequest, workspaceId: string, ): Promise { - return getRequestIdentity(request)!.access.can('manage', { + return requireRequestIdentity(request).access.can('manage', { type: 'workspace', id: workspaceId, }); @@ -283,7 +283,7 @@ const workspacesRoutes: FastifyPluginAsync = async (app) => { return sendError(reply, 400, 'Workspace name is required'); try { const workspace = await createWorkspace(parsed.data.name); - await getRequestIdentity(request)!.access.claim({ + await requireRequestIdentity(request).access.claim({ type: 'workspace', id: workspace.workspaceId, }); From a1964258b91e0080fa053899a47e07f0cbbb0150 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 28 Oct 2026 18:24:22 +0800 Subject: [PATCH 17/17] docs: describe member agents, personal settings, People and session renewal Fold PR B into the deployment-security architecture doc and record in the proposal why members run the Built-In agent while external agents, which hold the daemon's machine token and the operator's CLI logins, stay with administrators. Co-Authored-By: Claude Opus 5.5 --- docs/README.md | 2 +- docs/architecture/deployment-security.md | 14 ++++++- docs/proposals/multi-user-service.md | 48 ++++++++++++++---------- 3 files changed, 41 insertions(+), 23 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7a2fb305e..fc1712d2e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -102,7 +102,7 @@ docs/ | [model-role-routing.md](./proposals/model-role-routing.md) | Proposed | Model selection by runtime role. | | [move-selected-nodes-between-spaces.md](./proposals/move-selected-nodes-between-spaces.md) | Proposed | #142 selected-node and Frame-subtree moves between Spaces with bounded compensation. | | [multi-backend-storage.md](./proposals/multi-backend-storage.md) | Partly shipped | Phases 1–6: Blob and structured ports, SQLite, Postgres, Azure, async agents. | -| [multi-user-service.md](./proposals/multi-user-service.md) | Proposed | #228 follow-up: request-scoped Workspaces (PR A), then member agents, per-person credentials, grant admin and session renewal (PR B). | +| [multi-user-service.md](./proposals/multi-user-service.md) | Implemented | #228 follow-up: request-scoped Workspaces (PR A), then member agents, per-person credentials, grant admin and session renewal (PR B). | | [note-auto-height-stable-geometry.md](./proposals/note-auto-height-stable-geometry.md) | Proposed | Revision-aware offscreen Note measurement and stable auto-height geometry. | | [space-prompt-topology-scoping.md](./proposals/space-prompt-topology-scoping.md) | Shipped | Topology-derived global/direct-Agent targeting for Prompt Frames. | diff --git a/docs/architecture/deployment-security.md b/docs/architecture/deployment-security.md index 505fbabfd..3dde74056 100644 --- a/docs/architecture/deployment-security.md +++ b/docs/architecture/deployment-security.md @@ -112,9 +112,9 @@ A system `owner` holds every Huabu capability everywhere, which is Bubble's root Creating a Space makes its creator its `huabu.space.owner`. A selection move into a new Space claims it right after creating it, before any content leaves the source, so a failed claim is compensated like any other move failure. A move also requires read access to every Space whose artifact a moved node cites before copying it into the destination. That covers `POST /api/canvas`, bundle import, moving a selection into a new Space, adding a child Space, and detaching a Space to the root, where it no longer inherits from a parent. A Space created by an agent through the machine credential is claimed by nobody and is reachable through its Workspace or system ownership. -One `preHandler` authorizes every request that names a Space before its route runs. The Space is the `canvasId` route parameter, query field or body field, in the Workspace the request runs in; when more than one is given they must agree, and conflicting, repeated or non-string ids answer 400 `SPACE_ACCESS_AMBIGUOUS`, so a handler never reads a different Space from the one authorized. A request that also names another Space is checked against both: the destination of a selection move, the new parent of a re-parent, the target of a conversation fork (write), and the source of an artifact clone (read). Safe methods need read and other methods need write; the few `POST` routes that only read declare it, and renaming or deleting a Space declares manage. A Space the caller may not read answers 404, exactly like a missing one, and one it may read but not change answers 403 `SPACE_ACCESS_REQUIRED`. Agents and conversations are owner-only for now: a member gets 403 `AGENT_ACCESS_REQUIRED` from every `/api/agent`, `/api/acp`, `/api/agent-change-review` and `/api/rfs` route, from any route that declares `invokesAgent` (Interactive View actions), and from any request that names a thread, because an agent acts through the shared machine credential. RFS is that credential's own surface — it launches agents and Task Runs and leases shared service credentials — and the web app never calls it. For the same reason a member's edits never count towards the memory worker, which runs an agent over Workspace-wide memory and Skills, and a member's node preprocessing runs without LLM enrichment. That preprocessing also fetches only from public addresses: inside its run every outbound request, each redirect hop included, refuses at connect time any loopback, private, link-local, carrier-grade NAT or other non-public address (`modules/security/outbound.ts`), and the desktop fetch fallback is skipped. The Space list and Space cards omit or report as missing what the caller may not read. World is an ordinary Space under its Workspace, so only those who may read the Workspace reach it. +One `preHandler` authorizes every request that names a Space before its route runs. The Space is the `canvasId` route parameter, query field or body field, in the Workspace the request runs in; when more than one is given they must agree, and conflicting, repeated or non-string ids answer 400 `SPACE_ACCESS_AMBIGUOUS`, so a handler never reads a different Space from the one authorized. A request that also names another Space is checked against both: the destination of a selection move, the new parent of a re-parent, the target of a conversation fork (write), and the source of an artifact clone (read). Safe methods need read and other methods need write; the few `POST` routes that only read declare it, and renaming or deleting a Space declares manage. A Space the caller may not read answers 404, exactly like a missing one, and one it may read but not change answers 403 `SPACE_ACCESS_REQUIRED`. A member runs the Built-In agent and its conversations through `/api/agent`, in a Space they may use; a request naming a conversation must name its Space too (400 otherwise). External agents stay with administrators: a member gets 403 `AGENT_ACCESS_REQUIRED` from every `/api/acp`, `/api/agent-change-review` and `/api/rfs` route except `GET /api/acp/profiles`, which lists Built-In alone for them, from any route that declares `invokesAgent` (Interactive View actions), and from a run bound to an external agent. External agents act through the shared machine credential, which reaches every Space, on the operator's machines and under the operator's own CLI logins. RFS is that credential's own surface — it launches agents and Task Runs and leases shared service credentials — and the web app never calls it. The Built-In agent runs in-process, in the request's Workspace and caller scope, and its tools check the person who started it: a World conversation reads another Space only if they may read it, Workspace memory and Skills change only with `huabu.manage` on the Workspace, and the Task Run tools are refused. A member's edits still never count towards the memory worker, which runs an agent over Workspace-wide memory and Skills, and a member's node preprocessing runs without LLM enrichment. That preprocessing also fetches only from public addresses: inside its run every outbound request, each redirect hop included, refuses at connect time any loopback, private, link-local, carrier-grade NAT or other non-public address (`modules/security/outbound.ts`), and the desktop fetch fallback is skipped. The Space list and Space cards omit or report as missing what the caller may not read. World is an ordinary Space under its Workspace, so only those who may read the Workspace reach it. -The local provider's owner and the Agentlet machine credential pass every Space check. An agent therefore acts with the machine credential's full RFS reach, which is why only owners may run one until credentials carry the caller's own authority. Workspace-level state such as `setting/user.md` memory and user Skills is shared by everyone in a Workspace. Each request authenticates once and answers all its checks from one Bubble policy scope, one grant load and one ancestry walk per Space. +The local provider's owner and the Agentlet machine credential pass every Space check. An external agent therefore acts with the machine credential's full RFS reach, which is why only administrators may run one. Workspace-level state such as `setting/user.md` memory and user Skills is shared by everyone in a Workspace. Each request authenticates once and answers all its checks from one Bubble policy scope, one grant load and one ancestry walk per Space. ### Workspaces per person @@ -124,6 +124,14 @@ In Bubble mode each request runs in its caller's own current Workspace, so sever An agent run keeps the Workspace it started in: its reachback URL is `/api/rfs/w//`, and the RFS routes under that prefix run in that Workspace whatever its starter or the process does later. +### Personal settings + +In Bubble mode a member's calls run in their own settings namespace (`modules/identity/personal-settings.ts`), carried through the request and the agent runs it starts. The secret store keeps their model keys, OAuth credentials and connected-service keys under ids of their own, and gives them no fallback to the deployment's environment variables, which are the operator's. Their model settings and agent defaults live under `/people//`, and their default agent is always the Built-In one. So `/api/llm`, `/api/agent/defaults`, `/api/integrations`, `/api/services` and Ink OCR settings change the caller's own settings for a member and the deployment's for an administrator; the deployment's connection token and access password are never anyone's personal ones. A member with no model configured is told to add one in Settings. + +### People + +`/api/people` lets a system owner administer people without Bubble's API: list every principal Bubble knows with their system and Workspace roles, admit or revoke `member` (`PUT /api/people/:principalId/member`), and give or remove a Workspace role (`PUT /api/people/:principalId/workspaces/:workspaceId`). A principal appears after their first sign-in. An administrator cannot revoke their own access there. Settings shows it as the People tab. + ### Browser sign-in The SPA asks `GET /api/identity` before mounting. A local deployment answers at once and the app renders as before; a Basic Auth challenge remains the browser's. In Bubble mode a caller without a session sees a sign-in screen with one choice per interactive authenticator in Bubble's credential-free `/bubble/v1/auth/authenticators` discovery (the `entra` and `auth0` drivers). The SPA runs an OAuth authorization-code flow with PKCE against that provider: it reads the provider's endpoints from `/.well-known/openid-configuration`, redirects back to `/auth/callback`, and exchanges the code without a client secret. Register `/auth/callback` as a single-page-application redirect URI, and `` as an allowed web origin for the token request, and the `scopes` Bubble publishes as the API the app requests. An authenticated principal without `huabu.use` sees a no-access screen instead of the app. @@ -136,6 +144,8 @@ API clients can still send the Bearer token themselves: curl -H "Authorization: Bearer $BUBBLE_TOKEN" https://huabu.example/api/identity ``` +Sign-in asks for `offline_access`, and the page keeps the refresh token in memory only, never in storage. It renews the session a minute before the access token expires and on any `401`; when it cannot, the sign-in screen opens over the still-running app and signs in through a popup, whose code returns to the page by `postMessage` and is redeemed with a verifier only that page held, and the saves the lapse refused are sent again. With `HUABU_SIGN_OUT_PROVIDER=true`, `GET /api/identity` reports `providerSignOut`, and signing out also sends the browser to the provider's `end_session_endpoint`; register `/` as a post-logout redirect URI. + Changing providers does not migrate or link `local-owner` to a Bubble principal. Existing conversation records remain untouched. `pnpm start:desktop --server ` is a native client for the same remote deployment boundary. It accepts a root HTTP or HTTPS origin but does not weaken the Server's Host, Origin, CORS, or Basic Auth policy and does not inject allowed hosts. A `401` challenge from the selected exact origin opens a sandboxed Electron credential prompt; credentials remain in Chromium's current network session and are not placed in the command line, exposed to the renderer, or persisted by Huabu Desktop. diff --git a/docs/proposals/multi-user-service.md b/docs/proposals/multi-user-service.md index 7e3ae3147..d8e87f0c3 100644 --- a/docs/proposals/multi-user-service.md +++ b/docs/proposals/multi-user-service.md @@ -1,6 +1,6 @@ # Multi-User Service -Status: In-Progress — PR A implemented, PR B proposed +Status: Implemented — PR A (#356) and PR B Last updated: 2026-10-28 Follows PR #237 (Bubble identity and per-user Space access) toward issue #228. Two stacked pull requests take one Huabu Server from "several people sign in and each edits their own Spaces in one shared Workspace" to a service several people can use day to day: each person has their own Workspaces, uses agents in them, and an operator admits people without scripts. @@ -11,14 +11,14 @@ Nothing changes in local mode (`HUABU_IDENTITY_PROVIDER=local`). Desktop and sin After both PRs, in Bubble mode: -| Outcome | PR | -| ----------------------------------------------------------------------------------------------------------------------------------------- | --- | -| Each admitted person gets a personal Workspace on first sign-in and can create, rename, switch and delete Workspaces they own. | A | -| Two people work in different Workspaces at the same time. One person switching never moves another person. | A | -| Members run agents and conversations. An agent reaches only what the person who started it may reach. | B | -| Connected credentials and service leases are per person. One person's agent never uses another's GitHub token or service key. | B | -| A system owner admits members, revokes them and grants Workspace ownership from Settings. | B | -| A session that expires mid-edit is renewed without leaving the page, so unsaved edits survive. Sign-out can end the provider session too. | B | +| Outcome | PR | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | +| Each admitted person gets a personal Workspace on first sign-in and can create, rename, switch and delete Workspaces they own. | A | +| Two people work in different Workspaces at the same time. One person switching never moves another person. | A | +| Members run the Built-In agent and conversations, with their own model keys. It reaches only what the person who started it may reach. External agents stay with administrators. | B | +| Connected credentials and service leases are per person. One person's agent never uses another's GitHub token or service key. | B | +| A system owner admits members, revokes them and grants Workspace ownership from Settings. | B | +| A session that expires mid-edit is renewed without leaving the page, so unsaved edits survive. Sign-out can end the provider session too. | B | Out of scope for both: sharing a Workspace or Space between people beyond operator grants, quotas and billing, and Desktop as a multi-user client. @@ -98,29 +98,37 @@ The Postgres suite runs two principals in two Workspaces concurrently: creates, ## PR B — Members use agents, and the service is administrable -### Per-run agent credentials +### Members run the Built-In agent -Each agent run gets its own token, minted by the Server when the run starts. It names the requesting principal, the Workspace, the root Space and the thread, and expires with the run. The Agentlet passes it as the reachback credential instead of the machine token. RFS admits it as that principal, and Space access is checked as for that person's browser requests, so an agent can read or edit only what its starter can. The machine token keeps unrestricted reach only for the Agentlet's own control surface, never for Space content. +The first design gave each external agent run its own RFS token. Agentlet hands every agent process the daemon's own machine token (`AGENTLET_TOKEN`) by design, and refuses a session that sets it. So a member's external agent would hold an unrestricted credential beside any run token, and a prompt-injected agent could use it. External agents also run on the operator's machines under the operator's own CLI logins, so they cannot honour per-person keys either. So: -This reopens `/api/agent`, `/api/acp`, `/api/agent-change-review` and Interactive View actions to members. It also covers the memory worker: a member's edits drive memory updates again, running in that person's Workspace under their authority. +- **Members run the Built-In agent.** It runs in-process, never calls RFS, and its tools execute in the request's Workspace and caller scope. `/api/agent` and conversations are open to members through a Space they may use. +- **Its tools check the starter.** A World conversation reads another Space only if the starter may read it. Workspace memory and Skills change only with `huabu.manage` on the Workspace. The Task Run tools are refused, because Task Runs launch external agents through the machine credential. +- **External agents stay with administrators.** That covers `/api/acp`, RFS, change-review configuration, Interactive View actions and an external binding on `/api/agent`. A member's agent listing shows Built-In alone. -### Per-person credentials +Per-run credentials for external agents remain the way to open them to members later, and need Agentlet to stop giving agent processes the daemon token. -Model configuration and LLM keys, connected credentials, service-package leases and integration configuration move from data-directory scope to per principal in Bubble mode. Each person configures their own models and keys in Settings, and an agent run resolves models from its starter's configuration. A member with no model configured sees the Agent tool explain that, not a Server error. Operator-only settings (deployment, Canary, Workspaces on the Server's filesystem) stay system-owner-only. Settings shows a member only their own configuration. +### Personal settings + +A Bubble member's calls run in a personal settings namespace (`modules/identity/personal-settings.ts`), which also carries their access to the agent tools. + +- **Secrets.** The secret store namespaces their model keys, OAuth credentials and connected-service keys, with no fallback to the deployment's environment. +- **Settings files.** Model settings and agent defaults live under `/people//`. +- **Routes.** Members may change their own settings; the deployment's stay with administrators. Settings shows a member only Built-In setup and services. ### Grant administration -A Settings → People panel for system owners lists principals, and admits (`member`), revokes, and grants or removes `huabu.workspace.owner`. Huabu proxies these to Bubble's grant API in-process. Revoking `huabu.use` closes that person's open streams at the next revalidation, as #237 already does for Space grants. +`/api/people`, and a People tab for system owners, list principals, admit and revoke `member`, and give or remove Workspace roles. Revocation applies on the next request, and to open streams within 30 seconds. ### Session lifecycle -- **Refresh.** The sign-in flow requests a refresh token (`offline_access`), the Server holds it beside the access token in the session, and it renews the access token before it expires. -- **Re-sign-in in a popup.** When renewal is impossible, a lapsed session re-signs in through a popup, keeping the page and its unsaved edits. -- **Provider logout.** Sign-out optionally ends the provider session (RP-initiated logout) when the provider advertises `end_session_endpoint`. +- **Refresh.** Sign-in requests `offline_access`. The page holds the refresh token in memory only, and renews the session before expiry and on a 401. +- **Re-sign-in in a popup.** When renewal is impossible, the sign-in screen opens over the running app and signs in through a popup, then resends the refused saves. +- **Provider logout.** `HUABU_SIGN_OUT_PROVIDER=true` makes sign-out also end the provider session through `end_session_endpoint`. ### Proof -A member runs an agent that tries to read another member's Space through RFS and is refused. Their agent edits their own Space. Two members' connected credentials stay separate. An owner admits and revokes a member from the UI, and the revoked member's open page loses access within 30 seconds. A session that expires mid-edit renews or re-signs in without losing the edit. All of it is checked against real Auth0 and Entra sign-ins, as in #237. +A dev Server in Bubble mode, with Postgres content and Bubble records, runs two members whose model settings point at a local OpenAI-compatible mock that records each request's key. Each member's Built-In agent answers using only their own key. A member is refused in another member's Space, for an external binding and on `/api/acp`. The People tab admits people and gives Workspace roles. Renewal and the popup are unit-tested. They were not tried against real Auth0 or Entra. ## Settled decisions @@ -129,7 +137,7 @@ Confirmed 2026-10-28: 1. **Current Workspace per person, not per tab.** A Workspace in every URL was rejected as a much larger web and API change for a rare need. 2. **Workspace-qualified Space grants,** with an in-place migration of #237's grants, rather than relying on unique Space ids. Space grants stay so that one Space can be shared later. #237's roles are replaced by the model above. 3. **Automatic personal Workspace on first sign-in,** rather than no Workspace until an operator grants one. -4. **Per-person model keys** in PR B, rather than every member's agents using the operator's keys. +4. **Per-person model keys** in PR B, rather than every member's agents using the operator's keys. Members therefore run the Built-In agent; external agents, which use the operator's CLI logins, stay with administrators. ## Code entry points