shell-session-manager 2.0.0__tar.gz → 2.1.0__tar.gz

{shell_session_manager-2.0.0 → shell_session_manager-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shell-session-manager
-Version: 2.0.0
+Version: 2.1.0
 Summary: Async subprocess session manager with incremental stdin/stdout/stderr support
 Author-Email: =?utf-8?b?WWFubGkg55uQ57KS?= <yanli@mail.one>
 License-Expression: Apache-2.0
@@ -67,3 +67,16 @@ async def main() -> None:
 
 anyio.run(main)
 ```
+
+## shellctl server
+
+Run the HTTP API locally with:
+
+```bash
+pdm run shellctl serve --listen 127.0.0.1:8765
+```
+
+Pass `--auth-token your-token` when you want bearer auth enforced. `shellctl
+serve` also reads `SHELLCTL_AUTH_TOKEN`, so you can export the token instead of
+passing the flag. Leave the flag/env var unset or empty to start without
+requiring an Authorization header.

{shell_session_manager-2.0.0 → shell_session_manager-2.1.0}/README.md

@@ -49,3 +49,16 @@ async def main() -> None:
 
 anyio.run(main)
 ```
+
+## shellctl server
+
+Run the HTTP API locally with:
+
+```bash
+pdm run shellctl serve --listen 127.0.0.1:8765
+```
+
+Pass `--auth-token your-token` when you want bearer auth enforced. `shellctl
+serve` also reads `SHELLCTL_AUTH_TOKEN`, so you can export the token instead of
+passing the flag. Leave the flag/env var unset or empty to start without
+requiring an Authorization header.

{shell_session_manager-2.0.0 → shell_session_manager-2.1.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "shell-session-manager"
-version = "2.0.0"
+version = "2.1.0"
 description = "Async subprocess session manager with incremental stdin/stdout/stderr support"
 authors = [
     { name = "Yanli 盐粒", email = "yanli@mail.one" },

{shell_session_manager-2.0.0 → shell_session_manager-2.1.0}/src/shell_session_manager/shellctl/server/api.py

@@ -88,7 +88,10 @@ def create_app(
     def verify_auth(
         authorization: Annotated[str | None, Header()] = None,
     ) -> None:
-        expected = f"Bearer {resolved_config.auth_token}"
+        token = resolved_config.auth_token
+        if token is None:
+            return
+        expected = f"Bearer {token}"
         if authorization != expected:
             raise ShellctlServerError(
                 401, "unauthorized", "Missing or invalid bearer token"

{shell_session_manager-2.0.0 → shell_session_manager-2.1.0}/src/shell_session_manager/shellctl/server/cli.py

@@ -26,7 +26,15 @@ cli = typer.Typer(no_args_is_help=True, pretty_exceptions_enable=False)
 @cli.command("serve")
 def serve_command(
     listen: str = "127.0.0.1:8765",
-    auth_token_env: str = DEFAULT_AUTH_TOKEN_ENV,
+    auth_token: str | None = typer.Option(
+        None,
+        "--auth-token",
+        envvar=DEFAULT_AUTH_TOKEN_ENV,
+        help=(
+            "Bearer token value. You can also set SHELLCTL_AUTH_TOKEN. "
+            "Leave it unset or empty to disable HTTP bearer auth."
+        ),
+    ),
     state_dir: Path | None = None,
     runtime_dir: Path | None = None,
     gc_interval_seconds: float = DEFAULT_GC_INTERVAL_SECONDS,
@@ -37,7 +45,7 @@ def serve_command(
     host, port = _parse_listen(listen)
     config = ShellctlConfig(
         listen=listen,
-        auth_token_env=auth_token_env,
+        auth_token=auth_token,
         state_dir=state_dir or default_state_dir(),
         runtime_dir=runtime_dir,
         gc_interval_seconds=gc_interval_seconds,

{shell_session_manager-2.0.0 → shell_session_manager-2.1.0}/src/shell_session_manager/shellctl/server/config.py

@@ -34,10 +34,14 @@ class ShellctlConfig:
     `shellctl_command` deliberately defaults to `python -m ...server` so the
     tmux-side commands stay pinned to the same interpreter environment that
     launched the API server.
+
+    Bearer auth is opt-in: if the explicit `auth_token` and the fallback
+    `SHELLCTL_AUTH_TOKEN` environment variable are both missing or empty,
+    `shellctl serve` accepts requests without checking an Authorization header.
     """
 
     listen: str = "127.0.0.1:8765"
-    auth_token_env: str = DEFAULT_AUTH_TOKEN_ENV
+    auth_token: str | None = None
     state_dir: Path = field(default_factory=default_state_dir)
     runtime_dir: Path | None = None
     gc_interval_seconds: float = DEFAULT_GC_INTERVAL_SECONDS
@@ -67,6 +71,12 @@ class ShellctlConfig:
     def __post_init__(self) -> None:
         if self.runtime_dir is None:
             object.__setattr__(self, "runtime_dir", default_runtime_dir(self.state_dir))
+        token = self.auth_token
+        if token is None:
+            token = os.environ.get(DEFAULT_AUTH_TOKEN_ENV)
+        if not token:
+            token = None
+        object.__setattr__(self, "auth_token", token)
 
     @property
     def jobs_dir(self) -> Path:
@@ -90,14 +100,5 @@ class ShellctlConfig:
         runtime_dir = cast(Path, self.runtime_dir)
         return runtime_dir / "bin" / "shellctl-runner"
 
-    @property
-    def auth_token(self) -> str:
-        token = os.environ.get(self.auth_token_env)
-        if not token:
-            raise RuntimeError(
-                f"Missing bearer token in environment variable {self.auth_token_env}"
-            )
-        return token
-
 
 __all__ = ["ShellctlConfig"]

{shell_session_manager-2.0.0 → shell_session_manager-2.1.0}/src/shell_session_manager/shellctl/server/service.py

@@ -31,6 +31,7 @@ from shell_session_manager.shellctl.server.tmux import (
     TmuxControllerProtocol,
 )
 from shell_session_manager.shellctl.shared import (
+    DEFAULT_AUTH_TOKEN_ENV,
     DeleteJobResponse,
     InputJobRequest,
     JobInfo,
@@ -97,9 +98,12 @@ class ShellctlService:
             await connection.run_sync(SQLModel.metadata.create_all)
 
     async def initialize(self) -> None:
-        """Prepare directories, database, runner script, and tmux state."""
+        """Prepare directories, database, runner script, and tmux state.
+
+        Auth is configured at the API layer, so service startup must also work
+        when `shellctl serve` is intentionally running without a bearer token.
+        """
 
-        _ = self.config.auth_token
         await self.initialize_database()
         self._ensure_dir(cast(Path, self.config.runtime_dir))
         self._ensure_dir(self.config.jobs_dir)
@@ -966,7 +970,7 @@ class ShellctlService:
     def _runner_script_source(self) -> str:
         tmux_socket = shlex.quote(str(self.config.tmux_socket))
         state_dir = shlex.quote(str(self.config.state_dir))
-        auth_env = shlex.quote(self.config.auth_token_env)
+        auth_env = shlex.quote(DEFAULT_AUTH_TOKEN_ENV)
         shellctl_command = " ".join(
             shlex.quote(part) for part in self.config.shellctl_command
         )

{shell_session_manager-2.0.0 → shell_session_manager-2.1.0}/tests/test_shellctl_service.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import importlib
 import os
 import sqlite3
 import subprocess
@@ -23,6 +24,7 @@ from shell_session_manager.shellctl.server import (
     create_app,
 )
 from shell_session_manager.shellctl.shared import (
+    DEFAULT_AUTH_TOKEN_ENV,
     InputJobRequest,
     JobStatusName,
     JobStatusView,
@@ -34,6 +36,8 @@ from shell_session_manager.shellctl.shared import (
     job_session_name,
 )
 
+server_cli_module = importlib.import_module("shell_session_manager.shellctl.server.cli")
+
 
 class FakeTmuxController:
     def __init__(self) -> None:
@@ -85,10 +89,16 @@ class FakeTmuxController:
         self.pipe_active.pop(job_id, None)
 
 
-async def _create_service(tmp_path: Path) -> tuple[ShellctlService, FakeTmuxController]:
+async def _create_service(
+    tmp_path: Path, *, auth_token: str | None = None
+) -> tuple[ShellctlService, FakeTmuxController]:
     fake_tmux = FakeTmuxController()
     service = ShellctlService(
-        ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run"),
+        ShellctlConfig(
+            auth_token=auth_token,
+            state_dir=tmp_path / "state",
+            runtime_dir=tmp_path / "run",
+        ),
         tmux=fake_tmux,
     )
     await service.initialize_database()
@@ -96,6 +106,26 @@ async def _create_service(tmp_path: Path) -> tuple[ShellctlService, FakeTmuxCont
     return service, fake_tmux
 
 
+def _capture_serve_config(
+    monkeypatch: pytest.MonkeyPatch,
+) -> tuple[dict[str, object], CliRunner]:
+    captured: dict[str, object] = {}
+
+    def fake_create_app(config: ShellctlConfig):
+        captured["config"] = config
+        return object()
+
+    def fake_run(app: object, *, host: str, port: int, log_level: str) -> None:
+        captured["app"] = app
+        captured["host"] = host
+        captured["port"] = port
+        captured["log_level"] = log_level
+
+    monkeypatch.setattr(server_cli_module, "create_app", fake_create_app)
+    monkeypatch.setattr(server_cli_module.uvicorn, "run", fake_run)
+    return captured, CliRunner()
+
+
 async def _seed_job(
     service: ShellctlService,
     *,
@@ -788,12 +818,24 @@ async def test_allocate_job_dir_retries_on_atomic_mkdir_collision(
     await service.shutdown()
 
 
+@pytest.mark.anyio
+async def test_service_initialize_allows_missing_auth_token(tmp_path: Path) -> None:
+    service = ShellctlService(
+        ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run"),
+        tmux=FakeTmuxController(),
+    )
+
+    await service.initialize()
+
+    assert service.config.runner_path.exists()
+    await service.shutdown()
+
+
 @pytest.mark.anyio
 async def test_http_routes_inject_shellctl_service_dependency(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    tmp_path: Path,
 ) -> None:
-    monkeypatch.setenv("SHELLCTL_AUTH_TOKEN", "route-token")
-    service, _fake_tmux = await _create_service(tmp_path)
+    service, _fake_tmux = await _create_service(tmp_path, auth_token="route-token")
     app = create_app(service.config, service=service)
     transport = httpx.ASGITransport(app=app)
 
@@ -815,6 +857,223 @@ async def test_http_routes_inject_shellctl_service_dependency(
     await service.shutdown()
 
 
+@pytest.mark.anyio
+async def test_http_routes_enforce_auth_from_environment_fallback(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "route-token")
+    service, _fake_tmux = await _create_service(tmp_path)
+    app = create_app(service.config, service=service)
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://shellctl.test"
+    ) as client:
+        unauthenticated = await client.get("/v1/jobs")
+        authenticated = await client.get(
+            "/v1/jobs", headers={"Authorization": "Bearer route-token"}
+        )
+
+    assert unauthenticated.status_code == 401
+    assert authenticated.status_code == 200
+    await service.shutdown()
+
+
+@pytest.mark.anyio
+async def test_create_app_without_explicit_config_reads_auth_token_from_environment(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def noop_initialize(self: ShellctlService) -> None:
+        return None
+
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "route-token")
+    monkeypatch.setattr(ShellctlService, "initialize", noop_initialize)
+    monkeypatch.setattr(ShellctlService, "start_background_gc", lambda self: None)
+    monkeypatch.setattr(
+        ShellctlService, "start_background_pipe_monitor", lambda self: None
+    )
+
+    app = create_app()
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://shellctl.test"
+    ) as client:
+        response = await client.get("/v1/jobs")
+
+    assert app.state.shellctl_service.config.auth_token == "route-token"
+    assert response.status_code == 401
+    await app.state.shellctl_service.shutdown()
+
+
+@pytest.mark.anyio
+async def test_http_routes_skip_auth_when_token_missing(tmp_path: Path) -> None:
+    service, _fake_tmux = await _create_service(tmp_path)
+    app = create_app(service.config, service=service)
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://shellctl.test"
+    ) as client:
+        response = await client.get("/v1/jobs")
+
+    assert response.status_code == 200
+    assert response.json() == {"jobs": []}
+    await service.shutdown()
+
+
+@pytest.mark.anyio
+async def test_http_routes_skip_auth_when_token_is_empty(tmp_path: Path) -> None:
+    service, _fake_tmux = await _create_service(tmp_path, auth_token="")
+    app = create_app(service.config, service=service)
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://shellctl.test"
+    ) as client:
+        response = await client.get("/v1/jobs")
+
+    assert response.status_code == 200
+    assert response.json() == {"jobs": []}
+    await service.shutdown()
+
+
+def test_shellctl_config_reads_auth_token_from_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "env-token")
+
+    config = ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run")
+
+    assert config.auth_token == "env-token"
+
+
+def test_shellctl_config_treats_empty_environment_auth_token_as_disabled(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "")
+
+    config = ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run")
+
+    assert config.auth_token is None
+
+
+def test_serve_cli_passes_direct_auth_token_to_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--listen",
+            "0.0.0.0:9999",
+            "--auth-token",
+            "direct-token",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert captured["host"] == "0.0.0.0"
+    assert captured["port"] == 9999
+    assert captured["log_level"] == "info"
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token == "direct-token"
+
+
+def test_serve_cli_prefers_explicit_auth_token_over_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "env-token")
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--auth-token",
+            "direct-token",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token == "direct-token"
+
+
+def test_serve_cli_treats_empty_auth_token_as_disabled(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--auth-token",
+            "",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token is None
+
+
+def test_serve_cli_explicit_empty_auth_token_beats_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "env-token")
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--auth-token",
+            "",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token is None
+
+
+def test_serve_cli_reads_auth_token_from_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "env-token")
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token == "env-token"
+
+
 def test_runner_exit_cli_accepts_runner_option_contract(tmp_path: Path) -> None:
     async def setup_running_job() -> ShellctlConfig:
         service, _fake_tmux = await _create_service(tmp_path)