feat: update local authentication mode to require a non-placeholder token of at least 50 characters

backend/.env.example

@@ -10,7 +10,8 @@ BASE_URL=
 
 # Auth mode: clerk or local.
 AUTH_MODE=local
-LOCAL_AUTH_TOKEN=change-me
+# REQUIRED when AUTH_MODE=local (must be non-placeholder and at least 50 chars).
+LOCAL_AUTH_TOKEN=
 
 # Clerk (auth only; used when AUTH_MODE=clerk)
 CLERK_SECRET_KEY=

backend/app/core/auth.py

@@ -16,6 +16,7 @@ from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from pydantic import BaseModel, ValidationError
 from starlette.concurrency import run_in_threadpool
 
+from app.core.auth_mode import AuthMode
 from app.core.config import settings
 from app.core.logging import get_logger
 from app.db import crud
@@ -244,7 +245,7 @@ async def _fetch_clerk_profile(clerk_user_id: str) -> tuple[str | None, str | No
 
 async def delete_clerk_user(clerk_user_id: str) -> None:
     """Delete a Clerk user via the official Clerk SDK."""
-    if settings.auth_mode != "clerk":
+    if settings.auth_mode != AuthMode.CLERK:
         return
 
     secret = settings.clerk_secret_key.strip()
@@ -422,7 +423,7 @@ async def get_auth_context(
     session: AsyncSession = SESSION_DEP,
 ) -> AuthContext:
     """Resolve required authenticated user context for the configured auth mode."""
-    if settings.auth_mode == "local":
+    if settings.auth_mode == AuthMode.LOCAL:
         local_auth = await _resolve_local_auth_context(
             request=request,
             session=session,
@@ -466,7 +467,7 @@ async def get_auth_context_optional(
     """Resolve user context if available, otherwise return `None`."""
     if request.headers.get("X-Agent-Token"):
         return None
-    if settings.auth_mode == "local":
+    if settings.auth_mode == AuthMode.LOCAL:
         return await _resolve_local_auth_context(
             request=request,
             session=session,

backend/app/core/auth_mode.py

@@ -0,0 +1,12 @@
+"""Shared auth-mode enum values."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class AuthMode(str, Enum):
+    """Supported authentication modes for backend and frontend."""
+
+    CLERK = "clerk"
+    LOCAL = "local"

backend/app/core/config.py

@@ -3,13 +3,24 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Literal, Self
+from typing import Self
 
 from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from app.core.auth_mode import AuthMode
+
 BACKEND_ROOT = Path(__file__).resolve().parents[2]
 DEFAULT_ENV_FILE = BACKEND_ROOT / ".env"
+LOCAL_AUTH_TOKEN_MIN_LENGTH = 50
+LOCAL_AUTH_TOKEN_PLACEHOLDERS = frozenset(
+    {
+        "change-me",
+        "changeme",
+        "replace-me",
+        "replace-with-strong-random-token",
+    },
+)
 
 
 class Settings(BaseSettings):
@@ -27,7 +38,7 @@ class Settings(BaseSettings):
     database_url: str = "postgresql+psycopg://postgres:postgres@localhost:5432/openclaw_agency"
 
     # Auth mode: "clerk" for Clerk JWT auth, "local" for shared bearer token auth.
-    auth_mode: Literal["clerk", "local"]
+    auth_mode: AuthMode
     local_auth_token: str = ""
 
     # Clerk auth (auth only; roles stored in DB)
@@ -51,15 +62,20 @@ class Settings(BaseSettings):
 
     @model_validator(mode="after")
     def _defaults(self) -> Self:
-        if self.auth_mode == "clerk":
+        if self.auth_mode == AuthMode.CLERK:
             if not self.clerk_secret_key.strip():
                 raise ValueError(
                     "CLERK_SECRET_KEY must be set and non-empty when AUTH_MODE=clerk.",
                 )
-        elif self.auth_mode == "local":
-            if not self.local_auth_token.strip():
+        elif self.auth_mode == AuthMode.LOCAL:
+            token = self.local_auth_token.strip()
+            if (
+                not token
+                or len(token) < LOCAL_AUTH_TOKEN_MIN_LENGTH
+                or token.lower() in LOCAL_AUTH_TOKEN_PLACEHOLDERS
+            ):
                 raise ValueError(
-                    "LOCAL_AUTH_TOKEN must be set and non-empty when AUTH_MODE=local.",
+                    "LOCAL_AUTH_TOKEN must be at least 50 characters and non-placeholder when AUTH_MODE=local.",
                 )
         # In dev, default to applying Alembic migrations at startup to avoid
         # schema drift (e.g. missing newly-added columns).

backend/tests/conftest.py

@@ -10,6 +10,6 @@ if str(ROOT) not in sys.path:
     sys.path.insert(0, str(ROOT))
 
 # Tests should fail fast if auth-mode wiring breaks, but still need deterministic
-# defaults during import-time settings initialization.
-os.environ.setdefault("AUTH_MODE", "local")
-os.environ.setdefault("LOCAL_AUTH_TOKEN", "test-local-token")
+# defaults during import-time settings initialization, regardless of shell env.
+os.environ["AUTH_MODE"] = "local"
+os.environ["LOCAL_AUTH_TOKEN"] = "test-local-token-0123456789-0123456789-0123456789x"

backend/tests/test_authenticate_request_flow.py

@@ -9,6 +9,7 @@ import pytest
 from fastapi import HTTPException
 
 from app.core import auth
+from app.core.auth_mode import AuthMode
 from app.models.users import User
 
 
@@ -21,7 +22,7 @@ class _FakeSession:
 async def test_get_auth_context_raises_401_when_clerk_signed_out(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    monkeypatch.setattr(auth.settings, "auth_mode", "clerk")
+    monkeypatch.setattr(auth.settings, "auth_mode", AuthMode.CLERK)
     monkeypatch.setattr(auth.settings, "clerk_secret_key", "sk_test_dummy")
 
     from clerk_backend_api.security.types import AuthStatus, RequestState
@@ -45,7 +46,7 @@ async def test_get_auth_context_raises_401_when_clerk_signed_out(
 async def test_get_auth_context_uses_request_state_payload_claims(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    monkeypatch.setattr(auth.settings, "auth_mode", "clerk")
+    monkeypatch.setattr(auth.settings, "auth_mode", AuthMode.CLERK)
     monkeypatch.setattr(auth.settings, "clerk_secret_key", "sk_test_dummy")
 
     from clerk_backend_api.security.types import AuthStatus, RequestState
@@ -88,7 +89,7 @@ async def test_get_auth_context_uses_request_state_payload_claims(
 async def test_get_auth_context_optional_returns_none_for_agent_token(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    monkeypatch.setattr(auth.settings, "auth_mode", "clerk")
+    monkeypatch.setattr(auth.settings, "auth_mode", AuthMode.CLERK)
     monkeypatch.setattr(auth.settings, "clerk_secret_key", "sk_test_dummy")
 
     async def _boom(_request: Any) -> Any:  # pragma: no cover
@@ -108,7 +109,7 @@ async def test_get_auth_context_optional_returns_none_for_agent_token(
 async def test_get_auth_context_local_mode_requires_valid_bearer_token(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    monkeypatch.setattr(auth.settings, "auth_mode", "local")
+    monkeypatch.setattr(auth.settings, "auth_mode", AuthMode.LOCAL)
     monkeypatch.setattr(auth.settings, "local_auth_token", "expected-token")
 
     async def _fake_local_user(_session: Any) -> User:
@@ -131,7 +132,7 @@ async def test_get_auth_context_local_mode_requires_valid_bearer_token(
 async def test_get_auth_context_optional_local_mode_returns_none_without_token(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    monkeypatch.setattr(auth.settings, "auth_mode", "local")
+    monkeypatch.setattr(auth.settings, "auth_mode", AuthMode.LOCAL)
     monkeypatch.setattr(auth.settings, "local_auth_token", "expected-token")
 
     async def _boom(_session: Any) -> User:  # pragma: no cover

backend/tests/test_config_auth_mode.py

@@ -0,0 +1,70 @@
+# ruff: noqa: INP001
+"""Settings validation tests for auth-mode configuration."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from app.core.auth_mode import AuthMode
+from app.core.config import Settings
+
+
+def test_local_mode_requires_non_empty_token() -> None:
+    with pytest.raises(
+        ValidationError,
+        match="LOCAL_AUTH_TOKEN must be at least 50 characters and non-placeholder when AUTH_MODE=local",
+    ):
+        Settings(
+            _env_file=None,
+            auth_mode=AuthMode.LOCAL,
+            local_auth_token="",
+        )
+
+
+def test_local_mode_requires_minimum_length() -> None:
+    with pytest.raises(
+        ValidationError,
+        match="LOCAL_AUTH_TOKEN must be at least 50 characters and non-placeholder when AUTH_MODE=local",
+    ):
+        Settings(
+            _env_file=None,
+            auth_mode=AuthMode.LOCAL,
+            local_auth_token="x" * 49,
+        )
+
+
+def test_local_mode_rejects_placeholder_token() -> None:
+    with pytest.raises(
+        ValidationError,
+        match="LOCAL_AUTH_TOKEN must be at least 50 characters and non-placeholder when AUTH_MODE=local",
+    ):
+        Settings(
+            _env_file=None,
+            auth_mode=AuthMode.LOCAL,
+            local_auth_token="change-me",
+        )
+
+
+def test_local_mode_accepts_real_token() -> None:
+    token = "a" * 50
+    settings = Settings(
+        _env_file=None,
+        auth_mode=AuthMode.LOCAL,
+        local_auth_token=token,
+    )
+
+    assert settings.auth_mode == AuthMode.LOCAL
+    assert settings.local_auth_token == token
+
+
+def test_clerk_mode_requires_secret_key() -> None:
+    with pytest.raises(
+        ValidationError,
+        match="CLERK_SECRET_KEY must be set and non-empty when AUTH_MODE=clerk",
+    ):
+        Settings(
+            _env_file=None,
+            auth_mode=AuthMode.CLERK,
+            clerk_secret_key="",
+        )

backend/tests/test_local_auth_integration.py

@@ -14,6 +14,7 @@ from sqlmodel.ext.asyncio.session import AsyncSession
 
 from app.api.users import router as users_router
 from app.core import auth as auth_module
+from app.core.auth_mode import AuthMode
 from app.core.config import settings
 from app.db.session import get_session
 
@@ -51,7 +52,7 @@ async def test_local_auth_users_me_requires_and_accepts_valid_token(
     expected_email = f"local-{unique_suffix}@localhost"
     expected_name = "Local Integration User"
 
-    monkeypatch.setattr(settings, "auth_mode", "local")
+    monkeypatch.setattr(settings, "auth_mode", AuthMode.LOCAL)
     monkeypatch.setattr(settings, "local_auth_token", "integration-token")
     monkeypatch.setattr(auth_module, "LOCAL_AUTH_USER_ID", expected_user_id)
     monkeypatch.setattr(auth_module, "LOCAL_AUTH_EMAIL", expected_email)