Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat(kiosk): enforce consumer capabilities server-side (#10032)

Kiran Gadhave4964b98b37cc
diff --git a/frontend/src/core/network/__tests__/api.test.ts b/frontend/src/core/network/__tests__/api.test.ts
index 7798bb9662..37368f15f9 100644
--- a/frontend/src/core/network/__tests__/api.test.ts
+++ b/frontend/src/core/network/__tests__/api.test.ts
@@ -1,6 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { beforeEach, describe, expect, it, vi } from "vitest";
+import { HTTPError } from "@/utils/errors";
import { API } from "../api";
// Mock fetch globally
@@ -77,4 +78,20 @@ describe("API", () => {
expect.objectContaining({ method: "POST" }),
);
});
+
+ it("openapi-client error rejects with HTTPError carrying the status", async () => {
+ const body = { detail: "This connection is read-only for this action." };
+ await expect(
+ API.handleResponseReturnNull({
+ error: body,
+ response: { status: 403, statusText: "Forbidden" } as Response,
+ }),
+ ).rejects.toMatchObject({ status: 403, cause: body });
+ await expect(
+ API.handleResponseReturnNull({
+ error: body,
+ response: { status: 403, statusText: "Forbidden" } as Response,
+ }),
+ ).rejects.toBeInstanceOf(HTTPError);
+ });
});
diff --git a/frontend/src/core/network/__tests__/requests-toasting.test.tsx b/frontend/src/core/network/__tests__/requests-toasting.test.tsx
new file mode 100644
index 0000000000..713b50550b
--- /dev/null
+++ b/frontend/src/core/network/__tests__/requests-toasting.test.tsx
@@ -0,0 +1,46 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { HTTPError } from "@/utils/errors";
+
+const toastMock = vi.fn();
+vi.mock("@/components/ui/use-toast", () => ({
+ toast: (...args: unknown[]) => toastMock(...args),
+}));
+
+import { createErrorToastingRequests } from "../requests-toasting";
+import type { EditRequests, RunRequests } from "../types";
+
+function requestsThatReject(error: unknown): EditRequests & RunRequests {
+ return createErrorToastingRequests({
+ sendRun: vi.fn().mockRejectedValue(error),
+ } as unknown as EditRequests & RunRequests);
+}
+
+describe("createErrorToastingRequests", () => {
+ beforeEach(() => {
+ toastMock.mockClear();
+ });
+
+ it("suppresses the error toast for a capability 403", async () => {
+ const requests = requestsThatReject(
+ new HTTPError(403, "Forbidden", {
+ detail: "This connection is read-only for this action.",
+ }),
+ );
+ await expect(requests.sendRun({} as never)).rejects.toBeInstanceOf(
+ HTTPError,
+ );
+ expect(toastMock).not.toHaveBeenCalled();
+ });
+
+ it("shows a danger toast for other request errors", async () => {
+ const requests = requestsThatReject(new HTTPError(500, "Server Error"));
+ await expect(requests.sendRun({} as never)).rejects.toBeInstanceOf(
+ HTTPError,
+ );
+ expect(toastMock).toHaveBeenCalledWith(
+ expect.objectContaining({ variant: "danger" }),
+ );
+ });
+});
diff --git a/frontend/src/core/network/api.ts b/frontend/src/core/network/api.ts
index d64d5a13b7..084363cccc 100644
--- a/frontend/src/core/network/api.ts
+++ b/frontend/src/core/network/api.ts
@@ -1,6 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { createMarimoClient } from "@marimo-team/marimo-api";
+import { HTTPError } from "../../utils/errors";
import { Logger } from "../../utils/Logger";
import { Strings } from "../../utils/strings";
import { getRuntimeManager } from "../runtime/config";
@@ -50,7 +51,7 @@ export const API = {
const errorBody = isJson
? await response.json()
: await response.text();
- throw new Error(response.statusText, { cause: errorBody });
+ throw new HTTPError(response.status, response.statusText, errorBody);
}
if (isJson) {
return response.json() as RESP;
@@ -83,7 +84,7 @@ export const API = {
})
.then((response) => {
if (!response.ok) {
- throw new Error(response.statusText);
+ throw new HTTPError(response.status, response.statusText);
}
if (
response.headers.get("Content-Type")?.startsWith("application/json")
@@ -108,8 +109,13 @@ export const API = {
response: Response;
}): Promise<T> => {
if (response.error) {
- // oxlint-disable-next-line typescript/prefer-promise-reject-errors
- return Promise.reject(response.error);
+ return Promise.reject(
+ new HTTPError(
+ response.response.status,
+ response.response.statusText,
+ response.error,
+ ),
+ );
}
return Promise.resolve(response.data as T);
},
@@ -118,8 +124,13 @@ export const API = {
response: Response;
}): Promise<null> => {
if (response.error) {
- // oxlint-disable-next-line typescript/prefer-promise-reject-errors
- return Promise.reject(response.error);
+ return Promise.reject(
+ new HTTPError(
+ response.response.status,
+ response.response.statusText,
+ response.error,
+ ),
+ );
}
return Promise.resolve(null);
},
diff --git a/frontend/src/core/network/requests-toasting.tsx b/frontend/src/core/network/requests-toasting.tsx
index f91e960df1..12d07564f6 100644
--- a/frontend/src/core/network/requests-toasting.tsx
+++ b/frontend/src/core/network/requests-toasting.tsx
@@ -5,7 +5,7 @@ import { useAtomValue } from "jotai";
import { Spinner } from "@/components/icons/spinner";
import { Button } from "@/components/ui/button";
import { toast } from "@/components/ui/use-toast";
-import { NoKernelConnectedError, prettyError } from "@/utils/errors";
+import { HTTPError, NoKernelConnectedError, prettyError } from "@/utils/errors";
import { Logger } from "@/utils/Logger";
import { useConnectToRuntime } from "../runtime/config";
import { store } from "../state/jotai";
@@ -109,6 +109,14 @@ export function createErrorToastingRequests(
throw error;
}
+ // A capability 403: the connection is read-only for this action. The
+ // live capability notification already moved the UI to viewer state,
+ // so don't alarm the user with an error toast.
+ if (error instanceof HTTPError && error.status === 403) {
+ Logger.warn(`Request refused, connection is read-only: ${key}`);
+ throw error;
+ }
+
const title = MESSAGES[keyString];
const message = prettyError(error);
if (title) {
diff --git a/frontend/src/utils/errors.ts b/frontend/src/utils/errors.ts
index a89c0d2322..2ef6b67771 100644
--- a/frontend/src/utils/errors.ts
+++ b/frontend/src/utils/errors.ts
@@ -62,6 +62,21 @@ function safeJSONParse(message: string): unknown {
}
}
+/**
+ * A failed HTTP response. Carries the status code so callers can branch on it
+ * (e.g. treat a capability 403 as a benign viewer state). The response body is
+ * kept as `cause` so `prettyError` can surface its `detail`.
+ */
+export class HTTPError extends Error {
+ readonly status: number;
+
+ constructor(status: number, statusText: string, body?: unknown) {
+ super(statusText, { cause: body });
+ this.name = "HTTPError";
+ this.status = status;
+ }
+}
+
export class CellNotInitializedError extends Error {
constructor(
message = "The cell containing this UI element has not been run yet. Please run the cell first.",
diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.py
index 8d52de9149..5af6757643 100644
--- a/marimo/_messaging/notification.py
+++ b/marimo/_messaging/notification.py
@@ -294,18 +294,35 @@ class ConsumerCapabilities(msgspec.Struct, frozen=True):
"""Per-consumer access capabilities for a session connection.
- editor: `{edit: True, interact: True}`
- - viewer: `{edit: False, interact: False}`
+ - interactor: `{edit: False, interact: True}` (default for a secondary
+ connection: drives UI state but cannot edit the notebook)
+ - read-only viewer: `{edit: False, interact: False}` (opt-in, set by a
+ deployment's capability provider)
- These gate the frontend UI; they are not the server's authority boundary.
- Scopes are granted per session mode (see `@requires`), so in an edit session
- every connection (viewers included) carries the `edit` scope and can issue
- edit requests. A viewer's read-only status is enforced by the client hiding
- edit affordances, not by the server rejecting the request.
+ The server enforces these: control requests are gated against the issuing
+ consumer's stored capabilities at the control-request chokepoint (the
+ authority) and mirrored as an advisory HTTP 403 at the request handlers.
+ Commands classified as `read` in `marimo._session.capabilities` (such as
+ completions and previews) are always permitted.
"""
edit: bool
interact: bool
+ # Canonical role presets. Declared here and assigned below the class
+ # because each value is an instance of the class itself, which does not
+ # exist yet inside the body (cf. `datetime.min`/`datetime.max`).
+ EDITOR: ClassVar[ConsumerCapabilities]
+ INTERACTOR: ClassVar[ConsumerCapabilities]
+ VIEWER: ClassVar[ConsumerCapabilities]
+
+
+ConsumerCapabilities.EDITOR = ConsumerCapabilities(edit=True, interact=True)
+ConsumerCapabilities.INTERACTOR = ConsumerCapabilities(
+ edit=False, interact=True
+)
+ConsumerCapabilities.VIEWER = ConsumerCapabilities(edit=False, interact=False)
+
class ConsumerCapabilitiesNotification(
Notification, tag="consumer-capabilities"
diff --git a/marimo/_pyodide/bootstrap.py b/marimo/_pyodide/bootstrap.py
index 71080d329b..65a72ab717 100644
--- a/marimo/_pyodide/bootstrap.py
+++ b/marimo/_pyodide/bootstrap.py
@@ -139,9 +139,7 @@ def create_session(
app_config=app.config,
kiosk=False,
capabilities=KernelCapabilitiesNotification(),
- consumer_capabilities=ConsumerCapabilities(
- edit=True, interact=True
- ),
+ consumer_capabilities=ConsumerCapabilities.EDITOR,
)
),
)
diff --git a/marimo/_server/api/deps.py b/marimo/_server/api/deps.py
index 0abd4d3db9..0e87e338b5 100644
--- a/marimo/_server/api/deps.py
+++ b/marimo/_server/api/deps.py
@@ -163,9 +163,9 @@ class AppState(AppStateBase):
LOGGER.warning(
"Valid consumers ids: %s",
[
- list(session.consumers.values())
+ list(session.room.consumers)
for session in self.session_manager.sessions.values()
- if session.consumers
+ if session.room.consumers
],
)
raise ValueError(f"Invalid session id: {session_id}")
diff --git a/marimo/_server/api/endpoints/config.py b/marimo/_server/api/endpoints/config.py
index 1b562cffeb..ca72f1f6df 100644
--- a/marimo/_server/api/endpoints/config.py
+++ b/marimo/_server/api/endpoints/config.py
@@ -8,7 +8,7 @@ from starlette.background import BackgroundTask
from starlette.responses import JSONResponse
from marimo import _loggers
-from marimo._config.config import PartialMarimoConfig
+from marimo._config.config import MarimoConfig, PartialMarimoConfig
from marimo._dependencies.dependencies import DependencyManager
from marimo._messaging.msgspec_encoder import asdict
from marimo._messaging.notification import MissingPackageAlertNotification
@@ -16,7 +16,10 @@ from marimo._runtime.commands import UpdateUserConfigCommand
from marimo._runtime.packages.utils import is_python_isolated
from marimo._server.ai.mcp.config import is_mcp_config_empty
from marimo._server.api.deps import AppState
-from marimo._server.api.utils import parse_request
+from marimo._server.api.utils import (
+ enforce_consumer_capability,
+ parse_request,
+)
from marimo._server.lsp import any_lsp_server_running
from marimo._server.models.models import (
SaveUserConfigurationRequest,
@@ -68,6 +71,13 @@ async def save_user_config(
body = await parse_request(
request, cls=SaveUserConfigurationRequest, allow_unknown_keys=True
)
+ # Refuse read-only connections before writing anything to disk.
+ if session is not None:
+ enforce_consumer_capability(
+ app_state,
+ UpdateUserConfigCommand(cast(MarimoConfig, body.config)),
+ )
+
# TODO: we may want to validate deep-partial here, but validating with PartialMarimoConfig it too strict
# so we just cast to PartialMarimoConfig
config = app_state.config_manager.save_config(
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index 40d2d68ceb..bbe86ee117 100644
--- a/marimo/_server/api/endpoints/execution.py
+++ b/marimo/_server/api/endpoints/execution.py
@@ -21,6 +21,7 @@ from marimo._server.api.endpoints.ws.ws_connection_validator import (
from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGER
from marimo._server.api.utils import (
dispatch_control_request,
+ enforce_consumer_capability,
get_code_mode_credentials,
parse_request,
)
@@ -86,13 +87,15 @@ async def set_ui_element_values(
"""
app_state = AppState(request)
body = await parse_request(request, cls=UpdateUIElementValuesRequest)
+ command = UpdateUIElementCommand(
+ object_ids=body.object_ids,
+ values=body.values,
+ token=str(uuid4()),
+ request=HTTPRequest.from_request(request),
+ )
+ enforce_consumer_capability(app_state, command)
app_state.require_current_session().put_control_request(
- UpdateUIElementCommand(
- object_ids=body.object_ids,
- values=body.values,
- token=str(uuid4()),
- request=HTTPRequest.from_request(request),
- ),
+ command,
from_consumer_id=ConsumerId(app_state.require_current_session_id()),
)
@@ -250,8 +253,10 @@ async def run_cell(
app_state = AppState(request)
body = await parse_request(request, cls=ExecuteCellsRequest)
body.request = HTTPRequest.from_request(request)
+ command = body.as_command()
+ enforce_consumer_capability(app_state, command)
app_state.require_current_session().put_control_request(
- body.as_command(),
+ command,
from_consumer_id=ConsumerId(app_state.require_current_session_id()),
)
diff --git a/marimo/_server/api/endpoints/files.py b/marimo/_server/api/endpoints/files.py
index 45550b1596..9143531937 100644
--- a/marimo/_server/api/endpoints/files.py
+++ b/marimo/_server/api/endpoints/files.py
@@ -11,7 +11,10 @@ from starlette.responses import PlainTextResponse
from marimo import _loggers
from marimo._runtime.commands import RenameNotebookCommand
from marimo._server.api.deps import AppState
-from marimo._server.api.utils import parse_request
+from marimo._server.api.utils import (
+ enforce_consumer_capability,
+ parse_request,
+)
from marimo._server.files.path_validator import PathValidator
from marimo._server.models.models import (
BaseResponse,
@@ -125,8 +128,10 @@ async def rename_file(
Path(directory), Path(filename)
)
+ command = RenameNotebookCommand(filename=filename)
+ enforce_consumer_capability(app_state, command)
app_state.require_current_session().put_control_request(
- RenameNotebookCommand(filename=filename),
+ command,
from_consumer_id=ConsumerId(app_state.require_current_session_id()),
)
diff --git a/marimo/_server/api/endpoints/secrets.py b/marimo/_server/api/endpoints/secrets.py
index 53109bf20a..6881e01392 100644
--- a/marimo/_server/api/endpoints/secrets.py
+++ b/marimo/_server/api/endpoints/secrets.py
@@ -10,7 +10,11 @@ from marimo import _loggers
from marimo._runtime.commands import RefreshSecretsCommand
from marimo._secrets.secrets import write_secret
from marimo._server.api.deps import AppState
-from marimo._server.api.utils import dispatch_control_request, parse_request
+from marimo._server.api.utils import (
+ dispatch_control_request,
+ enforce_consumer_capability,
+ parse_request,
+)
from marimo._server.models.models import (
BaseResponse,
ListSecretKeysRequest,
@@ -84,12 +88,15 @@ async def create_secret(request: Request) -> BaseResponse:
app_state = AppState(request)
session_id = app_state.require_current_session_id()
+ command = RefreshSecretsCommand()
+ enforce_consumer_capability(app_state, command)
+
# Write to the provider
write_secret(body, app_state.config_manager.get_config(hide_secrets=False))
# Refresh the secrets
app_state.require_current_session().put_control_request(
- RefreshSecretsCommand(),
+ command,
from_consumer_id=ConsumerId(session_id),
)
return SuccessResponse(success=True)
diff --git a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py b/marimo/_server/api/endpoints/ws/ws_kernel_ready.py
index 7e8e795af0..724b07b93a 100644
--- a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py
+++ b/marimo/_server/api/endpoints/ws/ws_kernel_ready.py
@@ -86,8 +86,10 @@ def build_kernel_ready(
last_execution_time=last_execution_time,
app_config=session.app_file_manager.app.config,
kiosk=kiosk,
- consumer_capabilities=ConsumerCapabilities(
- edit=not kiosk, interact=not kiosk
+ consumer_capabilities=(
+ ConsumerCapabilities.INTERACTOR
+ if kiosk
+ else ConsumerCapabilities.EDITOR
),
capabilities=KernelCapabilitiesNotification(),
auto_instantiated=auto_instantiated,
diff --git a/marimo/_server/api/utils.py b/marimo/_server/api/utils.py
index ce8c36a427..05f50ceafc 100644
--- a/marimo/_server/api/utils.py
+++ b/marimo/_server/api/utils.py
@@ -31,7 +31,7 @@ if TYPE_CHECKING:
from starlette.datastructures import UploadFile
from starlette.requests import Request
- from marimo._server.api.deps import AppStateBase
+ from marimo._server.api.deps import AppState, AppStateBase
from marimo._session.session import Session
@@ -91,6 +91,37 @@ class RequestAsCommand(Protocol):
def as_command(self) -> CommandMessage: ...
+def enforce_consumer_capability(
+ app_state: AppState, command: CommandMessage
+) -> None:
+ """Raise 403 if the calling consumer lacks the command's capability.
+
+ Advisory mirror of the control-request chokepoint: gives HTTP clients an
+ honest refusal. The chokepoint remains the authority.
+
+ Raises marimo's `HTTPException` rather than Starlette's so the status
+ survives the global error handler, which rewrites Starlette 403s to 401s
+ to prompt for authentication. A capability refusal is not an auth failure.
+ """
+ from marimo._messaging.notification import ConsumerCapabilities
+ from marimo._session.capabilities import consumer_can
+ from marimo._utils.http import HTTPException
+
+ session = app_state.require_current_session()
+ consumer_id = ConsumerId(app_state.require_current_session_id())
+ consumer = session.room.get_consumer(consumer_id)
+ capabilities = (
+ session.room.get_capabilities(consumer)
+ if consumer is not None
+ else ConsumerCapabilities.VIEWER
+ )
+ if not consumer_can(capabilities, type(command)):
+ raise HTTPException(
+ status_code=403,
+ detail="This connection is read-only for this action.",
+ )
+
+
async def dispatch_control_request(
request: Request,
cls: type[CommandMessage] | CommandMessage,
@@ -107,6 +138,7 @@ async def dispatch_control_request(
body = cls
if isinstance(body, RequestAsCommand):
body = body.as_command()
+ enforce_consumer_capability(app_state, body)
app_state.require_current_session().put_control_request(
body,
from_consumer_id=ConsumerId(app_state.require_current_session_id()),
diff --git a/marimo/_session/capabilities.py b/marimo/_session/capabilities.py
new file mode 100644
index 0000000000..9d77f9c574
--- /dev/null
+++ b/marimo/_session/capabilities.py
@@ -0,0 +1,111 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Capability enforcement: which capability a kernel command requires.
+
+The capability a command requires is the minimum a consumer must hold to issue
+it. `read` is the floor every consumer holds; `interact` drives shared-kernel UI
+state; `edit` mutates the notebook. Every command is triaged into exactly one
+tier; an unclassified command raises rather than defaulting.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from marimo._runtime import commands
+
+if TYPE_CHECKING:
+ from marimo._messaging.notification import ConsumerCapabilities
+
+
+class Capability(Enum):
+ READ = "read"
+ INTERACT = "interact"
+ EDIT = "edit"
+
+
+# InvokeFunctionCommand is interact-tier, not read-tier: although table/df
+# paging is read-shaped, the same command also invokes arbitrary user code
+# (mo.ui.chat model calls, mo.lazy loaders, from_panel callbacks) and touches
+# the filesystem (file_browser). Per-function read-tiering is a kernel-side
+# follow-up; until then a pure spectator's table is frozen on page 1.
+_INTERACT_COMMANDS: frozenset[type] = frozenset(
+ {
+ commands.UpdateUIElementCommand,
+ commands.ModelCommand,
+ commands.InvokeFunctionCommand,
+ }
+)
+
+# Read-tier commands never mutate notebook or reactive state and never invoke
+# user code: completions and data/secret previews and listings.
+_READ_COMMANDS: frozenset[type] = frozenset(
+ {
+ commands.CodeCompletionCommand,
+ commands.PreviewDatasetColumnCommand,
+ commands.PreviewSQLTableCommand,
+ commands.ListSQLTablesCommand,
+ commands.ListSQLSchemasCommand,
+ commands.ValidateSQLCommand,
+ commands.ListDataSourceConnectionCommand,
+ commands.StorageListEntriesCommand,
+ commands.StorageDownloadCommand,
+ commands.ListSecretKeysCommand,
+ commands.GetCacheInfoCommand,
+ }
+)
+
+# Edit-tier commands mutate the notebook, its reactive state, or the kernel
+# lifecycle. Enumerated explicitly so a deliberate edit-tier command is
+# distinguishable from one that was never triaged: the latter raises in
+# `required_capability` instead of being silently classified as edit.
+_EDIT_COMMANDS: frozenset[type] = frozenset(
+ {
+ commands.CreateNotebookCommand,
+ commands.RenameNotebookCommand,
+ commands.ExecuteCellsCommand,
+ commands.ExecuteScratchpadCommand,
+ commands.ExecuteStaleCellsCommand,
+ commands.DebugCellCommand,
+ commands.DeleteCellCommand,
+ commands.SyncGraphCommand,
+ commands.UpdateCellConfigCommand,
+ commands.InstallPackagesCommand,
+ commands.UpdateUserConfigCommand,
+ commands.RefreshSecretsCommand,
+ commands.ClearCacheCommand,
+ commands.StopKernelCommand,
+ }
+)
+
+
+def required_capability(command_type: type) -> Capability:
+ """The minimum capability required to issue a command of this type.
+
+ Every command in the `CommandMessage` union is triaged into exactly one
+ tier, enforced by `test_every_command_is_classified`. A command that
+ reaches here unclassified is a programming error (a new command that was
+ never triaged), so fail loud rather than silently granting or denying it.
+ Raising is itself fail-closed: callers surface it as a refusal, not a grant.
+ """
+ if command_type in _READ_COMMANDS:
+ return Capability.READ
+ if command_type in _INTERACT_COMMANDS:
+ return Capability.INTERACT
+ if command_type in _EDIT_COMMANDS:
+ return Capability.EDIT
+ raise AssertionError(
+ f"Command {command_type.__name__} is not classified into a capability tier."
+ )
+
+
+def consumer_can(
+ capabilities: ConsumerCapabilities, command_type: type
+) -> bool:
+ """Whether a consumer with `capabilities` may issue this command type."""
+ required = required_capability(command_type)
+ if required is Capability.READ:
+ return True
+ if required is Capability.INTERACT:
+ return capabilities.interact
+ return capabilities.edit
diff --git a/marimo/_session/consumer_policy.py b/marimo/_session/consumer_policy.py
index 8f26e0bc30..e6c9f68d22 100644
--- a/marimo/_session/consumer_policy.py
+++ b/marimo/_session/consumer_policy.py
@@ -34,10 +34,13 @@ def initial_capabilities(
has_live_editor = session.connection_state() == ConnectionState.OPEN
+ # A secondary connection defaults to an interactor: it can drive UI state
+ # but not edit the notebook. Pure read-only (interact=False) is opt-in, set
+ # by a deployment's capability provider rather than the local default.
if connection_params.kiosk or has_live_editor:
- return ConsumerCapabilities(edit=False, interact=False)
+ return ConsumerCapabilities.INTERACTOR
- return ConsumerCapabilities(edit=True, interact=True)
+ return ConsumerCapabilities.EDITOR
def can_take_over_editing(
diff --git a/marimo/_session/room.py b/marimo/_session/room.py
index c2e32df5c7..064b62becc 100644
--- a/marimo/_session/room.py
+++ b/marimo/_session/room.py
@@ -8,6 +8,7 @@ session) and can have multiple kiosk consumers.
from __future__ import annotations
+from dataclasses import dataclass
from typing import TYPE_CHECKING
from marimo import _loggers
@@ -26,6 +27,17 @@ if TYPE_CHECKING:
from marimo._session.consumer import SessionConsumer
+@dataclass
+class _ConsumerState:
+ """A consumer in a room and its current capabilities.
+
+ Capabilities are mutable: a takeover restamps them in place.
+ """
+
+ consumer: SessionConsumer
+ capabilities: ConsumerCapabilities
+
+
class Room:
"""
A room is a collection of SessionConsumers
@@ -35,7 +47,7 @@ class Room:
def __init__(self) -> None:
self.main_consumer: SessionConsumer | None = None
- self.consumers: dict[SessionConsumer, ConsumerId] = {}
+ self.consumers: dict[ConsumerId, _ConsumerState] = {}
@property
def size(self) -> int:
@@ -45,12 +57,22 @@ class Room:
self,
consumer: SessionConsumer,
*,
- consumer_id: ConsumerId,
# Whether the consumer is the main session consumer
# We only allow one main consumer, the rest are kiosk consumers
main: bool,
+ capabilities: ConsumerCapabilities | None = None,
) -> None:
- self.consumers[consumer] = consumer_id
+ if capabilities is None:
+ # Non-main connections default to interactors (drive UI state, no
+ # edit). Pure read-only is opt-in, passed explicitly by the caller.
+ capabilities = (
+ ConsumerCapabilities.EDITOR
+ if main
+ else ConsumerCapabilities.INTERACTOR
+ )
+ self.consumers[consumer.consumer_id] = _ConsumerState(
+ consumer=consumer, capabilities=capabilities
+ )
if main:
assert self.main_consumer is None, (
"Main session consumer already exists"
@@ -58,25 +80,34 @@ class Room:
self.main_consumer = consumer
def remove_consumer(self, consumer: SessionConsumer) -> None:
- if consumer not in self.consumers:
+ state = self.consumers.get(consumer.consumer_id)
+ if state is None:
LOGGER.debug(
"Attempted to remove a consumer that was not in room."
)
return
+ if state.consumer is not consumer:
+ # A newer consumer re-registered under this id (reconnect or
+ # takeover race). Tear down the stale socket but leave the live
+ # registration intact.
+ consumer.on_detach()
+ return
+
if consumer == self.main_consumer:
self.main_consumer = None
- self.consumers.pop(consumer)
+ self.consumers.pop(consumer.consumer_id)
consumer.on_detach()
def promote_consumer_to_main(self, consumer: SessionConsumer) -> None:
"""Promote a consumer to be the main consumer of the room.
- Demotes the current main consumer (editor) to a regular consumer (reader).
- Emits a targeted notification to each targeted consumer to inform capability change.
+ Demotes the current main consumer (editor) to an interactor
+ (`edit=False, interact=True`). Notifies each affected consumer of its
+ capability change.
"""
- assert consumer in self.consumers, (
+ assert consumer.consumer_id in self.consumers, (
"Consumer must be in the room to be promoted."
)
previous_main_consumer = self.main_consumer
@@ -88,10 +119,16 @@ class Room:
self.main_consumer = consumer
if previous_main_consumer is not None:
+ self.consumers[
+ previous_main_consumer.consumer_id
+ ].capabilities = ConsumerCapabilities.INTERACTOR
self._notify_consumer_capability_change(
previous_main_consumer,
self.get_capabilities(previous_main_consumer),
)
+ self.consumers[
+ consumer.consumer_id
+ ].capabilities = ConsumerCapabilities.EDITOR
self._notify_consumer_capability_change(
consumer, self.get_capabilities(consumer)
)
@@ -99,15 +136,15 @@ class Room:
def get_capabilities(
self, consumer: SessionConsumer
) -> ConsumerCapabilities:
- """Get the capabilities of a consumer based on its role in the room."""
- is_editor = consumer is self.main_consumer
- return ConsumerCapabilities(edit=is_editor, interact=is_editor)
+ """Get the stored capabilities of a consumer in this room."""
+ state = self.consumers.get(consumer.consumer_id)
+ if state is None:
+ return ConsumerCapabilities.VIEWER
+ return state.capabilities
def get_consumer(self, consumer_id: ConsumerId) -> SessionConsumer | None:
- for consumer, cid in self.consumers.items():
- if cid == consumer_id:
- return consumer
- return None
+ state = self.consumers.get(consumer_id)
+ return state.consumer if state is not None else None
def _notify_consumer_capability_change(
self, consumer: SessionConsumer, capabilities: ConsumerCapabilities
@@ -126,7 +163,8 @@ class Room:
except_consumer: ConsumerId | None,
) -> None:
"""Broadcast a notification to all consumers except the one specified."""
- for consumer in self.consumers:
+ for state in self.consumers.values():
+ consumer = state.consumer
if consumer.consumer_id == except_consumer:
continue
if consumer.connection_state() == ConnectionState.OPEN:
diff --git a/marimo/_session/session.py b/marimo/_session/session.py
index 6149396e0b..1eab5275a7 100644
--- a/marimo/_session/session.py
+++ b/marimo/_session/session.py
@@ -16,9 +16,7 @@ from marimo import _loggers
from marimo._cli.sandbox import SandboxMode
from marimo._config.manager import MarimoConfigManager, ScriptConfigManager
from marimo._messaging.notebook.document import NotebookDocument
-from marimo._messaging.notification import (
- NotificationMessage,
-)
+from marimo._messaging.notification import NotificationMessage
from marimo._messaging.serde import serialize_kernel_message
from marimo._messaging.types import KernelMessage
from marimo._runtime import commands
@@ -29,6 +27,7 @@ from marimo._runtime.commands import (
HTTPRequest,
UpdateUIElementCommand,
)
+from marimo._session.capabilities import consumer_can, required_capability
from marimo._session.consumer import SessionConsumer
from marimo._session.events import SessionEventBus
from marimo._session.extensions.extensions import (
@@ -65,7 +64,7 @@ from marimo._types.ids import ConsumerId
from marimo._utils.repr import format_repr
if TYPE_CHECKING:
- from collections.abc import Iterator, Mapping
+ from collections.abc import Iterator
from marimo._runtime.virtual_file import VirtualFileStorageType
from marimo._server.models.models import InstantiateNotebookRequest
@@ -307,11 +306,6 @@ class SessionImpl(Session):
if extension in self.extensions:
self.extensions.remove(extension)
- @property
- def consumers(self) -> Mapping[SessionConsumer, ConsumerId]:
- """Get the consumers in the session."""
- return self.room.consumers
-
async def rename_path(self, new_path: str) -> None:
"""Rename the path of the session."""
old_path = self.app_file_manager.path
@@ -349,9 +343,39 @@ class SessionImpl(Session):
request: commands.CommandMessage,
from_consumer_id: ConsumerId | None,
) -> None:
- """Put a control request in the control queue."""
+ """Put a control request in the control queue.
+
+ Drops requests from consumers that lack the capability the command
+ requires. `from_consumer_id is None` denotes a system-originated
+ request and is always allowed.
+ """
+ if not self._consumer_may_issue(request, from_consumer_id):
+ LOGGER.warning(
+ "Dropping %s from consumer %s: command requires %s capability",
+ type(request).__name__,
+ from_consumer_id,
+ required_capability(type(request)).value,
+ )
+ return
self._event_bus.emit_received_command(self, request, from_consumer_id)
+ def _consumer_may_issue(
+ self,
+ request: commands.CommandMessage,
+ from_consumer_id: ConsumerId | None,
+ ) -> bool:
+ if from_consumer_id is None:
+ return True
+ consumer = self.room.get_consumer(from_consumer_id)
+ if consumer is None:
+ # A stale or forged consumer id is not in the room: drop it rather
+ # than fall back to read-tier, which `consumer_can` grants
+ # unconditionally.
+ return False
+ return consumer_can(
+ self.room.get_capabilities(consumer), type(request)
+ )
+
def put_input(self, text: str) -> None:
"""Put an input() request in the input queue."""
self._event_bus.emit_received_stdin(self, text)
@@ -385,11 +409,7 @@ class SessionImpl(Session):
# Consumers are also extensions, so we want to attach them to the session
self.extensions.add(session_consumer)
session_consumer.on_attach(self, self._event_bus)
- self.room.add_consumer(
- session_consumer,
- consumer_id=session_consumer.consumer_id,
- main=main,
- )
+ self.room.add_consumer(session_consumer, main=main)
def get_current_state(self) -> SessionView:
"""Return the current state of the session."""
diff --git a/marimo/_session/session_repository.py b/marimo/_session/session_repository.py
index 65a3565a94..1490aef582 100644
--- a/marimo/_session/session_repository.py
+++ b/marimo/_session/session_repository.py
@@ -48,7 +48,7 @@ class SessionRepository:
def get_by_consumer_id(self, consumer_id: ConsumerId) -> Session | None:
"""Find a session by consumer ID (for kiosk mode)."""
for session in self._sessions.values():
- if consumer_id in session.consumers.values():
+ if session.room.get_consumer(consumer_id) is not None:
return session
return None
diff --git a/marimo/_session/types.py b/marimo/_session/types.py
index b896dd3ac3..583da58dba 100644
--- a/marimo/_session/types.py
+++ b/marimo/_session/types.py
@@ -16,7 +16,7 @@ from typing import TYPE_CHECKING, Any, Protocol
if TYPE_CHECKING:
import asyncio
import threading
- from collections.abc import Iterator, Mapping
+ from collections.abc import Iterator
from marimo._config.manager import MarimoConfigManager
from marimo._messaging.notebook.document import NotebookDocument
@@ -141,11 +141,6 @@ class Session(Protocol):
"""The notebook document this session reflects."""
...
- @property
- def consumers(self) -> Mapping[SessionConsumer, ConsumerId]:
- """Get the consumers in the session."""
- ...
-
def kernel_state(self) -> KernelState:
"""Get the state of the kernel."""
...
diff --git a/marimo/_session/utils.py b/marimo/_session/utils.py
index 8d1cf40683..32e44bdf86 100644
--- a/marimo/_session/utils.py
+++ b/marimo/_session/utils.py
@@ -20,8 +20,10 @@ def send_message_to_consumer(
consumer_id: ConsumerId | None,
) -> None:
"""Send a message operation to a specific consumer in a session."""
- notification = serialize_kernel_message(operation)
- if session.connection_state() == ConnectionState.OPEN:
- for consumer, c_id in session.consumers.items():
- if c_id == consumer_id:
- consumer.notify(notification)
+ if consumer_id is None:
+ return
+ if session.connection_state() != ConnectionState.OPEN:
+ return
+ consumer = session.room.get_consumer(consumer_id)
+ if consumer is not None:
+ consumer.notify(serialize_kernel_message(operation))
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index c74348c720..7e264d8830 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -860,13 +860,15 @@ components:
type: object
ConsumerCapabilities:
description: "Per-consumer access capabilities for a session connection.\n\n\
- \ - editor: `{edit: True, interact: True}`\n - viewer: `{edit: False,\
- \ interact: False}`\n\n These gate the frontend UI; they are not the server's\
- \ authority boundary.\n Scopes are granted per session mode (see `@requires`),\
- \ so in an edit session\n every connection (viewers included) carries the\
- \ `edit` scope and can issue\n edit requests. A viewer's read-only status\
- \ is enforced by the client hiding\n edit affordances, not by the server\
- \ rejecting the request."
+ \ - editor: `{edit: True, interact: True}`\n - interactor: `{edit: False,\
+ \ interact: True}` (default for a secondary\n connection: drives UI state\
+ \ but cannot edit the notebook)\n - read-only viewer: `{edit: False, interact:\
+ \ False}` (opt-in, set by a\n deployment's capability provider)\n\n \
+ \ The server enforces these: control requests are gated against the issuing\n\
+ \ consumer's stored capabilities at the control-request chokepoint (the\n\
+ \ authority) and mirrored as an advisory HTTP 403 at the request handlers.\n\
+ \ Commands classified as `read` in `marimo._session.capabilities` (such\
+ \ as\n completions and previews) are always permitted."
properties:
edit:
type: boolean
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 65f0dc2cda..5176641a4d 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -3932,13 +3932,16 @@ export interface components {
* @description Per-consumer access capabilities for a session connection.
*
* - editor: `{edit: True, interact: True}`
- * - viewer: `{edit: False, interact: False}`
- *
- * These gate the frontend UI; they are not the server's authority boundary.
- * Scopes are granted per session mode (see `@requires`), so in an edit session
- * every connection (viewers included) carries the `edit` scope and can issue
- * edit requests. A viewer's read-only status is enforced by the client hiding
- * edit affordances, not by the server rejecting the request.
+ * - interactor: `{edit: False, interact: True}` (default for a secondary
+ * connection: drives UI state but cannot edit the notebook)
+ * - read-only viewer: `{edit: False, interact: False}` (opt-in, set by a
+ * deployment's capability provider)
+ *
+ * The server enforces these: control requests are gated against the issuing
+ * consumer's stored capabilities at the control-request chokepoint (the
+ * authority) and mirrored as an advisory HTTP 403 at the request handlers.
+ * Commands classified as `read` in `marimo._session.capabilities` (such as
+ * completions and previews) are always permitted.
*/
ConsumerCapabilities: {
edit: boolean;
diff --git a/tests/_server/api/endpoints/test_config_endpoints.py b/tests/_server/api/endpoints/test_config_endpoints.py
index 1e37071c1e..c4f60ad3c0 100644
--- a/tests/_server/api/endpoints/test_config_endpoints.py
+++ b/tests/_server/api/endpoints/test_config_endpoints.py
@@ -79,6 +79,38 @@ def test_save_user_config_with_partial_config(client: TestClient) -> None:
assert "success" in response.json()
+@with_session(SESSION_ID)
+def test_save_user_config_denied_capability_does_not_write(
+ client: TestClient,
+) -> None:
+ """A capability-denied request must not touch the config on disk.
+
+ Regression: enforcement used to run after save_config, so a read-only
+ connection could persist the config before receiving its 403.
+ """
+ from unittest.mock import patch
+
+ from marimo._utils.http import HTTPException
+
+ config_manager = get_user_config_manager(client)
+
+ with (
+ patch(
+ "marimo._server.api.endpoints.config.enforce_consumer_capability",
+ side_effect=HTTPException(status_code=403, detail="read-only"),
+ ),
+ patch.object(config_manager, "save_config") as save_config,
+ ):
+ response = client.post(
+ "/api/kernel/save_user_config",
+ headers=HEADERS,
+ json={"config": {"display": {"theme": "dark"}}},
+ )
+
+ assert response.status_code == 403, response.text
+ save_config.assert_not_called()
+
+
def test_save_user_config_starts_lsp_when_ty_enabled(
client: TestClient, monkeypatch: pytest.MonkeyPatch
) -> None:
diff --git a/tests/_server/api/endpoints/test_execution.py b/tests/_server/api/endpoints/test_execution.py
index 685bb3bd0c..06f920625d 100644
--- a/tests/_server/api/endpoints/test_execution.py
+++ b/tests/_server/api/endpoints/test_execution.py
@@ -5,6 +5,7 @@ import json
import sys
import time
from typing import TYPE_CHECKING
+from unittest.mock import MagicMock
import pytest
@@ -12,7 +13,11 @@ from marimo._code_mode.screenshot_meta import (
SCREENSHOT_AUTH_TOKEN_KEY,
SCREENSHOT_SERVER_URL_KEY,
)
+from marimo._messaging.notification import ConsumerCapabilities
+from marimo._runtime.commands import ExecuteCellsCommand
+from marimo._server.api.utils import enforce_consumer_capability
from marimo._types.ids import CellId_t, SessionId
+from marimo._utils.http import HTTPException
from marimo._utils.lists import first
from tests._server.api.endpoints.ws_helpers import (
HEADERS as WS_HEADERS,
@@ -627,7 +632,7 @@ def test_takeover_transfers_edit_without_disconnect(
"resumed": True,
"consumer_capabilities": {
"edit": False,
- "interact": False,
+ "interact": True,
},
}
),
@@ -643,9 +648,34 @@ def test_takeover_transfers_edit_without_disconnect(
vw = receive_until("consumer-capabilities", viewer)
assert ed["data"]["consumer_capabilities"] == {
"edit": False,
- "interact": False,
+ "interact": True,
}
assert vw["data"]["consumer_capabilities"] == {
"edit": True,
"interact": True,
}
+
+
+def _app_state_for_consumer(caps: ConsumerCapabilities) -> object:
+ app_state = MagicMock()
+ app_state.require_current_session_id.return_value = "consumer-1"
+ session = app_state.require_current_session.return_value
+ session.room.get_consumer.return_value = object()
+ session.room.get_capabilities.return_value = caps
+ return app_state
+
+
+def test_enforce_consumer_capability_blocks_viewer() -> None:
+ # A default viewer is an interactor (edit=False); an edit-tier command is
+ # still refused.
+ app_state = _app_state_for_consumer(ConsumerCapabilities.INTERACTOR)
+ command = ExecuteCellsCommand(cell_ids=[], codes=[])
+ with pytest.raises(HTTPException) as exc_info:
+ enforce_consumer_capability(app_state, command) # type: ignore[arg-type]
+ assert exc_info.value.status_code == 403
+
+
+def test_enforce_consumer_capability_allows_editor() -> None:
+ app_state = _app_state_for_consumer(ConsumerCapabilities.EDITOR)
+ command = ExecuteCellsCommand(cell_ids=[], codes=[])
+ enforce_consumer_capability(app_state, command) # type: ignore[arg-type]
diff --git a/tests/_server/api/endpoints/test_kiosk.py b/tests/_server/api/endpoints/test_kiosk.py
index 370c34a59c..cb5eae2b67 100644
--- a/tests/_server/api/endpoints/test_kiosk.py
+++ b/tests/_server/api/endpoints/test_kiosk.py
@@ -41,7 +41,7 @@ async def test_connect_kiosk_with_session(client: TestClient) -> None:
"resumed": True,
"consumer_capabilities": {
"edit": False,
- "interact": False,
+ "interact": True,
},
}
),
@@ -100,7 +100,7 @@ def test_second_edit_connection_joins_as_viewer(client: TestClient) -> None:
"resumed": True,
"consumer_capabilities": {
"edit": False,
- "interact": False,
+ "interact": True,
},
}
),
diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.py
index 5605f86e58..2792d22427 100644
--- a/tests/_server/api/endpoints/test_ws.py
+++ b/tests/_server/api/endpoints/test_ws.py
@@ -316,7 +316,7 @@ async def test_connects_to_existing_session_with_same_file(
# Check in the same room
session_manager = get_session_manager(client)
assert len(session_manager.sessions) == 1
- assert len(session_manager.sessions["123"].consumers) == 2
+ assert session_manager.sessions["123"].room.size == 2
data2 = websocket2.receive_json()
assert_parse_ready_response(data2)
diff --git a/tests/_server/api/endpoints/ws_helpers.py b/tests/_server/api/endpoints/ws_helpers.py
index 795342f4f2..5d586e20cb 100644
--- a/tests/_server/api/endpoints/ws_helpers.py
+++ b/tests/_server/api/endpoints/ws_helpers.py
@@ -47,7 +47,9 @@ def create_response(
response.update(
{
"consumer_capabilities": asdict(
- ConsumerCapabilities(edit=not kiosk, interact=not kiosk)
+ ConsumerCapabilities.INTERACTOR
+ if kiosk
+ else ConsumerCapabilities.EDITOR
)
}
)
diff --git a/tests/_server/test_errors.py b/tests/_server/test_errors.py
index 0e8d6fd189..f2720de0a5 100644
--- a/tests/_server/test_errors.py
+++ b/tests/_server/test_errors.py
@@ -79,6 +79,27 @@ async def test_marimo_http_exception():
assert response.body == b'{"detail":"Bad request"}'
+async def test_marimo_http_exception_403_preserved():
+ """A capability refusal (marimo 403) must not be rewritten to 401.
+
+ Starlette 403s are rewritten to 401 to prompt for auth; a read-only
+ refusal is not an auth failure, so it is raised as a marimo HTTPException
+ and must reach the client as 403.
+ """
+ exc = MarimoHTTPException(
+ status_code=403, detail="This connection is read-only for this action."
+ )
+ request = Request(
+ {
+ "type": "http",
+ "path": "/api/kernel/run",
+ "headers": [(b"accept", b"application/json")],
+ }
+ )
+ response = await handle_error(request, exc)
+ assert response.status_code == 403
+
+
async def test_module_not_found_error():
# Mock AppState and session
mock_app_state = MagicMock()
diff --git a/tests/_server/test_sessions.py b/tests/_server/test_sessions.py
index 8d0694ecda..9caf664551 100644
--- a/tests/_server/test_sessions.py
+++ b/tests/_server/test_sessions.py
@@ -415,7 +415,7 @@ def test_session_with_kiosk_consumers() -> None:
# Assert startup of kiosk consumer
assert session.room.main_consumer != kiosk_consumer
- assert kiosk_consumer in session.room.consumers
+ assert kiosk_consumer.consumer_id in session.room.consumers
kiosk_consumer.on_attach.assert_called_once()
assert kiosk_consumer.on_detach.call_count == 0
assert session.connection_state() == ConnectionState.OPEN
diff --git a/tests/_session/test_capabilities.py b/tests/_session/test_capabilities.py
new file mode 100644
index 0000000000..7ca35704dd
--- /dev/null
+++ b/tests/_session/test_capabilities.py
@@ -0,0 +1,115 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import typing
+
+import pytest
+
+from marimo._messaging.notification import ConsumerCapabilities
+from marimo._runtime import commands
+from marimo._session.capabilities import (
+ _EDIT_COMMANDS,
+ _INTERACT_COMMANDS,
+ _READ_COMMANDS,
+ Capability,
+ consumer_can,
+ required_capability,
+)
+
+EDITOR = ConsumerCapabilities.EDITOR
+INTERACTOR = ConsumerCapabilities.INTERACTOR
+VIEWER = ConsumerCapabilities.VIEWER
+
+
+def test_role_presets_have_expected_bits() -> None:
+ # Everything else references the presets by name; pin their definitions
+ # here so a change to the role bit-patterns cannot pass silently.
+ assert (EDITOR.edit, EDITOR.interact) == (True, True)
+ assert (INTERACTOR.edit, INTERACTOR.interact) == (False, True)
+ assert (VIEWER.edit, VIEWER.interact) == (False, False)
+
+
+def test_required_capability_classifies_commands() -> None:
+ assert required_capability(commands.ExecuteCellsCommand) is Capability.EDIT
+ assert (
+ required_capability(commands.ExecuteScratchpadCommand)
+ is Capability.EDIT
+ )
+ assert (
+ required_capability(commands.UpdateUIElementCommand)
+ is Capability.INTERACT
+ )
+ # InvokeFunctionCommand smuggles arbitrary user code (chat/lazy/panel),
+ # so it is interact-tier, not read-tier.
+ assert (
+ required_capability(commands.InvokeFunctionCommand)
+ is Capability.INTERACT
+ )
+ assert (
+ required_capability(commands.CodeCompletionCommand) is Capability.READ
+ )
+ assert (
+ required_capability(commands.PreviewDatasetColumnCommand)
+ is Capability.READ
+ )
+
+
+def test_unknown_command_raises() -> None:
+ class MysteryCommand: ...
+
+ with pytest.raises(AssertionError, match="not classified"):
+ required_capability(MysteryCommand)
+
+
+def test_every_command_is_classified() -> None:
+ """Every enforceable command must be deliberately tiered.
+
+ A new command added to the `CommandMessage` union without a capability
+ tier would default to `edit` at runtime, so this test forces the author
+ to place it in exactly one of the three sets instead.
+ """
+ all_commands = set(typing.get_args(commands.CommandMessage))
+ classified = _READ_COMMANDS | _INTERACT_COMMANDS | _EDIT_COMMANDS
+
+ unclassified = all_commands - classified
+ assert not unclassified, (
+ "commands missing a capability tier in capabilities.py: "
+ f"{sorted(c.__name__ for c in unclassified)}"
+ )
+
+ stale = classified - all_commands
+ assert not stale, (
+ "commands classified in capabilities.py but not in CommandMessage: "
+ f"{sorted(c.__name__ for c in stale)}"
+ )
+
+ for pair in (
+ (_READ_COMMANDS, _INTERACT_COMMANDS),
+ (_READ_COMMANDS, _EDIT_COMMANDS),
+ (_INTERACT_COMMANDS, _EDIT_COMMANDS),
+ ):
+ assert not (pair[0] & pair[1]), (
+ "a command is classified in more than one tier: "
+ f"{sorted(c.__name__ for c in pair[0] & pair[1])}"
+ )
+
+
+def test_viewer_can_only_read() -> None:
+ assert consumer_can(VIEWER, commands.CodeCompletionCommand) is True
+ assert consumer_can(VIEWER, commands.PreviewDatasetColumnCommand) is True
+ # Viewers cannot invoke functions (could run user code / touch the fs).
+ assert consumer_can(VIEWER, commands.InvokeFunctionCommand) is False
+ assert consumer_can(VIEWER, commands.UpdateUIElementCommand) is False
+ assert consumer_can(VIEWER, commands.ExecuteCellsCommand) is False
+
+
+def test_interactor_can_interact_not_edit() -> None:
+ assert consumer_can(INTERACTOR, commands.UpdateUIElementCommand) is True
+ assert consumer_can(INTERACTOR, commands.InvokeFunctionCommand) is True
+ assert consumer_can(INTERACTOR, commands.ExecuteCellsCommand) is False
+
+
+def test_editor_can_do_everything() -> None:
+ assert consumer_can(EDITOR, commands.ExecuteCellsCommand) is True
+ assert consumer_can(EDITOR, commands.UpdateUIElementCommand) is True
+ assert consumer_can(EDITOR, commands.InvokeFunctionCommand) is True
diff --git a/tests/_session/test_consumer_policy.py b/tests/_session/test_consumer_policy.py
index 2b001ad821..c37cd49745 100644
--- a/tests/_session/test_consumer_policy.py
+++ b/tests/_session/test_consumer_policy.py
@@ -23,21 +23,21 @@ def test_initial_capabilities_editor_when_no_live_editor() -> None:
session = MagicMock()
session.connection_state.return_value = ConnectionState.ORPHANED
caps = initial_capabilities(session, _params(kiosk=False))
- assert caps == ConsumerCapabilities(edit=True, interact=True)
+ assert caps == ConsumerCapabilities.EDITOR
def test_initial_capabilities_viewer_when_live_editor() -> None:
session = MagicMock()
session.connection_state.return_value = ConnectionState.OPEN
caps = initial_capabilities(session, _params(kiosk=False))
- assert caps == ConsumerCapabilities(edit=False, interact=False)
+ assert caps == ConsumerCapabilities.INTERACTOR
def test_initial_capabilities_viewer_when_kiosk_requested() -> None:
session = MagicMock()
session.connection_state.return_value = ConnectionState.ORPHANED
caps = initial_capabilities(session, _params(kiosk=True))
- assert caps == ConsumerCapabilities(edit=False, interact=False)
+ assert caps == ConsumerCapabilities.INTERACTOR
def test_can_take_over_editing_allows_locally() -> None:
diff --git a/tests/_session/test_control_request_enforcement.py b/tests/_session/test_control_request_enforcement.py
new file mode 100644
index 0000000000..f2b0fc7bda
--- /dev/null
+++ b/tests/_session/test_control_request_enforcement.py
@@ -0,0 +1,70 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+from marimo._messaging.notification import ConsumerCapabilities
+from marimo._runtime import commands
+from marimo._session.session import SessionImpl
+from marimo._types.ids import ConsumerId
+
+
+def _session_with_capabilities(
+ caps: ConsumerCapabilities,
+ *,
+ consumer_present: bool = True,
+) -> tuple[SessionImpl, MagicMock]:
+ session = SessionImpl.__new__(SessionImpl)
+ event_bus = MagicMock()
+ session._event_bus = event_bus
+ room = MagicMock()
+ room.get_consumer.return_value = object() if consumer_present else None
+ room.get_capabilities.return_value = caps
+ session.room = room
+ return session, event_bus
+
+
+def _run_command() -> commands.CommandMessage:
+ return commands.ExecuteCellsCommand(cell_ids=[], codes=[])
+
+
+def test_viewer_run_request_is_dropped() -> None:
+ session, event_bus = _session_with_capabilities(
+ ConsumerCapabilities.VIEWER
+ )
+ session.put_control_request(
+ _run_command(), from_consumer_id=ConsumerId("viewer")
+ )
+ event_bus.emit_received_command.assert_not_called()
+
+
+def test_editor_run_request_passes() -> None:
+ session, event_bus = _session_with_capabilities(
+ ConsumerCapabilities.EDITOR
+ )
+ session.put_control_request(
+ _run_command(), from_consumer_id=ConsumerId("editor")
+ )
+ event_bus.emit_received_command.assert_called_once()
+
+
+def test_system_request_bypasses_enforcement() -> None:
+ session, event_bus = _session_with_capabilities(
+ ConsumerCapabilities.VIEWER
+ )
+ session.put_control_request(_run_command(), from_consumer_id=None)
+ event_bus.emit_received_command.assert_called_once()
+
+
+def test_missing_consumer_read_request_is_dropped() -> None:
+ session, event_bus = _session_with_capabilities(
+ ConsumerCapabilities.VIEWER,
+ consumer_present=False,
+ )
+ # Read-tier commands are granted unconditionally once a consumer is found,
+ # so a stale or forged id must be dropped before that check.
+ session.put_control_request(
+ commands.CodeCompletionCommand(id="c", document="", cell_id="cell-0"),
+ from_consumer_id=ConsumerId("ghost"),
+ )
+ event_bus.emit_received_command.assert_not_called()
diff --git a/tests/_session/test_room.py b/tests/_session/test_room.py
index 99b1b2a0a9..0ac8841800 100644
--- a/tests/_session/test_room.py
+++ b/tests/_session/test_room.py
@@ -15,6 +15,7 @@ class FakeConsumer(SessionConsumer):
self._cid = ConsumerId(cid)
self.received: list[KernelMessage] = []
self.state = ConnectionState.OPEN
+ self.detached = False
@property
def consumer_id(self) -> ConsumerId:
@@ -30,7 +31,7 @@ class FakeConsumer(SessionConsumer):
del session, event_bus
def on_detach(self) -> None:
- return
+ self.detached = True
def _caps(received: list[KernelMessage]) -> list[ConsumerCapabilities]:
@@ -44,9 +45,9 @@ def _caps(received: list[KernelMessage]) -> list[ConsumerCapabilities]:
def _room_with(editor: FakeConsumer, *viewers: FakeConsumer) -> Room:
room = Room()
- room.add_consumer(editor, consumer_id=editor.consumer_id, main=True)
+ room.add_consumer(editor, main=True)
for v in viewers:
- room.add_consumer(v, consumer_id=v.consumer_id, main=False)
+ room.add_consumer(v, main=False)
return room
@@ -60,12 +61,8 @@ def test_get_consumer_resolves_by_id() -> None:
def test_get_capabilities_editor_vs_viewer() -> None:
a, b = FakeConsumer("a"), FakeConsumer("b")
room = _room_with(a, b)
- assert room.get_capabilities(a) == ConsumerCapabilities(
- edit=True, interact=True
- )
- assert room.get_capabilities(b) == ConsumerCapabilities(
- edit=False, interact=False
- )
+ assert room.get_capabilities(a) == ConsumerCapabilities.EDITOR
+ assert room.get_capabilities(b) == ConsumerCapabilities.INTERACTOR
def test_promote_demotes_old_grants_new_no_disconnect() -> None:
@@ -76,15 +73,11 @@ def test_promote_demotes_old_grants_new_no_disconnect() -> None:
assert room.main_consumer is b
# both still members; no disconnect
- assert a in room.consumers
- assert b in room.consumers
- # old editor -> viewer caps; new editor -> editor caps
- assert _caps(a.received) == [
- ConsumerCapabilities(edit=False, interact=False)
- ]
- assert _caps(b.received) == [
- ConsumerCapabilities(edit=True, interact=True)
- ]
+ assert a.consumer_id in room.consumers
+ assert b.consumer_id in room.consumers
+ # old editor -> interactor caps; new editor -> editor caps
+ assert _caps(a.received) == [ConsumerCapabilities.INTERACTOR]
+ assert _caps(b.received) == [ConsumerCapabilities.EDITOR]
def test_promote_third_viewer_untouched() -> None:
@@ -107,6 +100,47 @@ def test_promote_skips_closed_consumer() -> None:
a.state = ConnectionState.CLOSED
room.promote_consumer_to_main(b)
assert _caps(a.received) == [] # closed: not notified
- assert _caps(b.received) == [
- ConsumerCapabilities(edit=True, interact=True)
- ]
+ assert _caps(b.received) == [ConsumerCapabilities.EDITOR]
+
+
+def test_stored_capabilities_override_slot() -> None:
+ a, b = FakeConsumer("a"), FakeConsumer("b")
+ room = Room()
+ room.add_consumer(a, main=True)
+ # b is not main, but is stamped interact-capable explicitly
+ room.add_consumer(
+ b,
+ main=False,
+ capabilities=ConsumerCapabilities.INTERACTOR,
+ )
+ assert room.get_capabilities(b) == ConsumerCapabilities.INTERACTOR
+
+
+def test_remove_stale_duplicate_keeps_live_consumer() -> None:
+ live = FakeConsumer("a")
+ room = _room_with(live)
+
+ stale = FakeConsumer("a")
+ room.remove_consumer(stale)
+
+ assert room.get_consumer(ConsumerId("a")) is live
+ assert stale.detached
+ assert not live.detached
+
+
+def test_remove_consumer_detaches_and_drops() -> None:
+ a, b = FakeConsumer("a"), FakeConsumer("b")
+ room = _room_with(a, b)
+
+ room.remove_consumer(b)
+
+ assert b.consumer_id not in room.consumers
+ assert b.detached
+
+
+def test_promote_restamps_stored_capabilities() -> None:
+ a, b = FakeConsumer("a"), FakeConsumer("b")
+ room = _room_with(a, b)
+ room.promote_consumer_to_main(b)
+ assert room.get_capabilities(b) == ConsumerCapabilities.EDITOR
+ assert room.get_capabilities(a) == ConsumerCapabilities.INTERACTOR