qodalis-cli-server-plugin-users 1.0.0b6__tar.gz → 1.0.0b7__tar.gz

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qodalis-cli-server-plugin-users
-Version: 1.0.0b6
+Version: 1.0.0b7
 Summary: User management plugin for Qodalis CLI servers — authentication, sessions, groups, and audit log
 Project-URL: Homepage, https://github.com/qodalis-solutions/cli-server-python
 Project-URL: Repository, https://github.com/qodalis-solutions/cli-server-python

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qodalis-cli-server-plugin-users"
-version = "1.0.0b6"
+version = "1.0.0b7"
 description = "User management plugin for Qodalis CLI servers — authentication, sessions, groups, and audit log"
 readme = { text = "", content-type = "text/plain" }
 license = "MIT"

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/__init__.py

@@ -10,6 +10,7 @@ from typing import Any, Callable, Optional
 from .cli_users_builder import CliUsersBuilder, CliUsersPlugin
 from .errors import UsersApiError
 from .models import (
+    ApiToken,
     AuditEntry,
     AuditQueryOptions,
     Credentials,
@@ -30,12 +31,14 @@ from .services.auth_service import (
 from .services.users_service import UsersService
 from .server_protection import ServerProtectionMiddleware
 from .shell_access import UsersShellAccess
+from .stores.in_memory_api_token_store import InMemoryApiTokenStore
 from .stores.in_memory_audit_store import InMemoryAuditStore
 from .stores.in_memory_credential_store import InMemoryCredentialStore
 from .stores.in_memory_group_store import InMemoryGroupStore
 from .stores.in_memory_session_store import InMemorySessionStore
 from .stores.in_memory_user_store import InMemoryUserStore
 from .stores.interfaces import (
+    IApiTokenStore,
     IAuditStore,
     ICredentialStore,
     IGroupStore,
@@ -44,6 +47,7 @@ from .stores.interfaces import (
 )
 
 __all__ = [
+    "ApiToken",
     "AuditEntry",
     "AuditQueryOptions",
     "AuthContext",
@@ -55,11 +59,13 @@ __all__ = [
     "ExternalAuthAdapter",
     "ExternalAuthResult",
     "Group",
+    "IApiTokenStore",
     "IAuditStore",
     "ICredentialStore",
     "IGroupStore",
     "ISessionStore",
     "IUserStore",
+    "InMemoryApiTokenStore",
     "InMemoryAuditStore",
     "InMemoryCredentialStore",
     "InMemoryGroupStore",

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/cli_users_builder.py

@@ -30,6 +30,7 @@ from fastapi import APIRouter
 from .controllers.audit_controller import create_audit_router
 from .controllers.groups_controller import create_groups_router
 from .controllers.sessions_controller import create_sessions_router
+from .controllers.tokens_controller import create_tokens_router
 from .controllers.users_controller import create_users_router
 from .middleware.auth_middleware import create_auth_dependencies
 from .models import ExternalAuthAdapter
@@ -48,12 +49,14 @@ from .services.auth_service import (
     BroadcastFn,
 )
 from .services.users_service import UsersService
+from .stores.in_memory_api_token_store import InMemoryApiTokenStore
 from .stores.in_memory_audit_store import InMemoryAuditStore
 from .stores.in_memory_credential_store import InMemoryCredentialStore
 from .stores.in_memory_group_store import InMemoryGroupStore
 from .stores.in_memory_session_store import InMemorySessionStore
 from .stores.in_memory_user_store import InMemoryUserStore
 from .stores.interfaces import (
+    IApiTokenStore,
     IAuditStore,
     ICredentialStore,
     IGroupStore,
@@ -85,6 +88,7 @@ class CliUsersPlugin:
     credential_store: ICredentialStore
     group_store: IGroupStore
     audit_store: IAuditStore
+    api_token_store: Optional[IApiTokenStore] = None
     default_admin_password: Optional[str] = None
     cleanup_interval_ms: int = DEFAULT_CLEANUP_INTERVAL_MS
     #: Protect every CLI server route/socket when mounted (B1).
@@ -219,6 +223,8 @@ class CliUsersBuilder:
         self._credential_store: ICredentialStore | None = None
         self._audit_store: IAuditStore | None = None
         self._group_store: IGroupStore | None = None
+        self._api_token_store: IApiTokenStore | None = None
+        self._allow_non_expiring_tokens = False
         self._auth_adapter: ExternalAuthAdapter | None = None
         self._default_admin_password: str | None = None
         self._session_timeout_ms = DEFAULT_SESSION_TIMEOUT_MS
@@ -253,6 +259,17 @@ class CliUsersBuilder:
         self._group_store = store
         return self
 
+    def set_api_token_store(self, store: IApiTokenStore) -> CliUsersBuilder:
+        """Replace the API token store (default in-memory)."""
+        self._api_token_store = store
+        return self
+
+    def set_allow_non_expiring_tokens(self, allow: bool = True) -> CliUsersBuilder:
+        """Allow API tokens that never expire (``expiresInDays: null``;
+        default ``False``)."""
+        self._allow_non_expiring_tokens = allow
+        return self
+
     def set_auth_adapter(self, adapter: ExternalAuthAdapter | None) -> CliUsersBuilder:
         """Delegate authentication to the host app (see README)."""
         self._auth_adapter = adapter
@@ -341,9 +358,11 @@ class CliUsersBuilder:
                 rate_limit_window_ms=self._rate_limit_window_ms,
                 trust_proxy=self._trust_proxy,
                 allowed_origins=self._allowed_origins,
+                allow_non_expiring_tokens=self._allow_non_expiring_tokens,
             ),
             broadcast_fn=broadcast_fn,
             auth_adapter=self._auth_adapter,
+            api_token_store=self._api_token_store or InMemoryApiTokenStore(),
         )
         users_service = UsersService(auth_service)
 
@@ -358,6 +377,7 @@ class CliUsersBuilder:
             credential_store=auth_service.credential_store,
             group_store=auth_service.group_store,
             audit_store=auth_service.audit_store,
+            api_token_store=auth_service.api_token_store,
             default_admin_password=self._default_admin_password,
             cleanup_interval_ms=self._cleanup_interval_ms,
             protect_server=self._protect_server,
@@ -382,4 +402,5 @@ class CliUsersBuilder:
             auth_service, users_service, get_auth, require_permission,
         ))
         router.include_router(create_audit_router(auth_service, require_permission))
+        router.include_router(create_tokens_router(auth_service, get_auth))
         return plugin

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/controllers/__init__.py

@@ -3,11 +3,13 @@
 from .audit_controller import create_audit_router
 from .groups_controller import create_groups_router
 from .sessions_controller import create_sessions_router
+from .tokens_controller import create_tokens_router
 from .users_controller import create_users_router
 
 __all__ = [
     "create_audit_router",
     "create_groups_router",
     "create_sessions_router",
+    "create_tokens_router",
     "create_users_router",
 ]

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/controllers/sessions_controller.py

@@ -21,6 +21,7 @@ from ..services.auth_service import AuthContext, AuthService
 from ._routing import collection, new_router
 
 MANAGED_BY_HOST = "Authentication is managed by the host application"
+NOT_A_SESSION = "not a session"
 
 
 def create_sessions_router(
@@ -63,6 +64,8 @@ def create_sessions_router(
 
         @router.delete("/current", status_code=204)
         async def logout(ctx: AuthContext = Depends(get_auth_pending)):
+            if ctx.api_token is not None:
+                raise not_found(NOT_A_SESSION)
             if ctx.token:
                 await auth_service.logout(ctx.token)
             return Response(status_code=204)
@@ -74,7 +77,8 @@ def create_sessions_router(
 
     @router.get("/current")
     async def current_session(ctx: AuthContext = Depends(get_auth_pending)):
-        assert ctx.session is not None
+        if ctx.session is None:
+            raise not_found(NOT_A_SESSION)
         return auth_service.session_payload(ctx.session, ctx.user, ctx.permissions)
 
     @collection(router, "GET")

qodalis_cli_server_plugin_users-1.0.0b7/qodalis_cli_users/controllers/tokens_controller.py

@@ -0,0 +1,140 @@
+"""API tokens controller — ``/tokens``.
+
+- ``GET    /tokens``           own tokens (authenticated)
+- ``GET    /tokens?all=true``  every user's tokens (``tokens:read``)
+- ``POST   /tokens``           create a token (authenticated, session only)
+- ``DELETE /tokens/{id}``      revoke (owner, or ``tokens:revoke``)
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from typing import Any, Callable
+
+from fastapi import APIRouter, Depends, Response
+
+from ..errors import UsersApiError, bad_request, conflict, forbidden, not_found
+from ..models import ApiToken, CreateApiTokenRequest, now_ms
+from ..permissions import TOKENS_READ, TOKENS_REVOKE
+from ..services.auth_service import AuthContext, AuthService, hash_token
+from ..validation import sanitize, validate_permissions
+from ._routing import collection, new_router
+
+TOKEN_NAME_RE = re.compile(r"^[A-Za-z0-9._ -]{1,64}$")
+TOKEN_NAME_MAX = 64
+MAX_TOKENS_PER_USER = 20
+DEFAULT_EXPIRES_IN_DAYS = 90
+MAX_EXPIRES_IN_DAYS = 365
+DAY_MS = 24 * 60 * 60 * 1000
+
+API_TOKENS_CANNOT_CREATE = "forbidden: API tokens cannot create tokens"
+MANAGED_BY_HOST = "Authentication is managed by the host application"
+
+
+def _validate_name(raw: Any) -> str:
+    if not isinstance(raw, str) or not TOKEN_NAME_RE.match(raw):
+        raise bad_request("name must be 1-64 characters of [A-Za-z0-9._ -]")
+    return raw
+
+
+def _expires_at(body: CreateApiTokenRequest, allow_never: bool, now: int) -> int | None:
+    if "expiresInDays" not in body.model_fields_set:
+        return now + DEFAULT_EXPIRES_IN_DAYS * DAY_MS
+    days = body.expiresInDays
+    if days is None:
+        if not allow_never:
+            raise bad_request("non-expiring tokens are not allowed")
+        return None
+    if isinstance(days, float) and days.is_integer():
+        days = int(days)
+    if isinstance(days, bool) or not isinstance(days, int) or not 1 <= days <= MAX_EXPIRES_IN_DAYS:
+        raise bad_request(f"expiresInDays must be an integer between 1 and {MAX_EXPIRES_IN_DAYS}")
+    return now + days * DAY_MS
+
+
+def _scope(ctx: AuthContext, raw: Any) -> list[str] | None:
+    """``None`` (omitted/null) = unscoped; ``[]`` = an empty scope.  Field
+    errors (400) are raised before the coverage check (403)."""
+    if raw is None:
+        return None
+    if not isinstance(raw, list) or not all(isinstance(p, str) and p for p in raw):
+        raise bad_request("permissions must be an array of strings")
+    perms = validate_permissions(raw) or []
+    for perm in perms:
+        if not ctx.can(perm):
+            raise forbidden(f"forbidden: cannot grant {sanitize(perm, 128)}")
+    return perms
+
+
+def create_tokens_router(
+    auth_service: AuthService,
+    get_auth: Callable,
+) -> APIRouter:
+    router = new_router("/tokens", "tokens")
+    store = auth_service.api_token_store
+
+    @collection(router, "GET")
+    async def list_tokens(all: str | None = None, ctx: AuthContext = Depends(get_auth)):  # noqa: A002
+        if all not in (None, "true", "false"):
+            raise bad_request("all must be true or false")
+        all = all == "true"  # noqa: A001
+        if all and not ctx.can(TOKENS_READ):
+            raise forbidden(f"forbidden: missing permission {TOKENS_READ}")
+        tokens = await store.get_tokens(None if all else ctx.user.id)
+        tokens.sort(key=lambda t: t.created_at)
+        return [await auth_service.api_token_view(t) for t in tokens]
+
+    @collection(router, "POST", status_code=201)
+    async def create_token(body: CreateApiTokenRequest, ctx: AuthContext = Depends(get_auth)):
+        # A leaked token must not be able to mint more tokens.
+        if ctx.api_token is not None:
+            raise forbidden(API_TOKENS_CANNOT_CREATE)
+        if ctx.session is None or ctx.external:
+            raise UsersApiError(501, MANAGED_BY_HOST)
+        name = _validate_name(body.name)
+        now = now_ms()
+        expires_at = _expires_at(body, auth_service.options.allow_non_expiring_tokens, now)
+        permissions = _scope(ctx, body.permissions)
+        existing = await store.get_tokens(ctx.user.id)
+        if any(t.name.lower() == name.lower() for t in existing):
+            raise conflict(f"token '{name}' already exists")
+        # Expired tokens stay listed but do not count toward the limit.
+        if sum(1 for t in existing if not t.is_expired(now)) >= MAX_TOKENS_PER_USER:
+            raise bad_request(f"a user may have at most {MAX_TOKENS_PER_USER} tokens")
+        token = auth_service.generate_api_token()
+        record = await store.create_token(ApiToken(
+            id=uuid.uuid4().hex,
+            user_id=ctx.user.id,
+            name=name,
+            token_hash=hash_token(token),
+            created_at=now,
+            expires_at=expires_at,
+            permissions=permissions,
+        ))
+        await auth_service.audit(
+            "token_created", ctx.user.name,
+            details=f"{record.name} ({record.id})",
+            actor=ctx.user.name, actor_id=ctx.user.id, user_id=ctx.user.id,
+            metadata={"tokenId": record.id, "tokenName": record.name},
+        )
+        return {"token": token, "apiToken": record.to_view(ctx.user.name)}
+
+    @router.delete("/{token_id}", status_code=204)
+    async def revoke_token(token_id: str, ctx: AuthContext = Depends(get_auth)):
+        record = await store.get_token(token_id)
+        if record is None or (record.user_id != ctx.user.id and not ctx.can(TOKENS_REVOKE)):
+            raise not_found("token not found")
+        await store.delete_token(record.id)
+        owner = await auth_service.user_store.get_user(record.user_id)
+        # The audit also notifies change listeners: sockets opened with this
+        # token are re-checked and closed (4401 "session ended").
+        await auth_service.audit(
+            "token_revoked", owner.name if owner else record.user_id,
+            details=f"{record.name} ({record.id})",
+            actor=ctx.user.name, actor_id=ctx.user.id, user_id=record.user_id,
+            metadata={"tokenId": record.id, "tokenName": record.name},
+        )
+        return Response(status_code=204)
+
+    return router

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/controllers/users_controller.py

@@ -20,6 +20,7 @@ from ..services.users_service import UsersService
 from ._routing import collection, new_router
 
 MANAGED_BY_HOST = "Authentication is managed by the host application"
+API_TOKENS_CANNOT_CHANGE_PASSWORDS = "forbidden: API tokens cannot change passwords"
 
 
 def create_users_router(
@@ -148,6 +149,8 @@ def create_users_router(
         request: Request,
         ctx: AuthContext = Depends(get_auth_pending),
     ):
+        if ctx.api_token is not None:
+            raise forbidden(API_TOKENS_CANNOT_CHANGE_PASSWORDS)
         target = await user_store.get_user(id_or_name)
         is_self = ctx.is_self(target)
         # While a password change is pending only the own password may change.

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/models.py

@@ -142,6 +142,46 @@ class Session:
         return result
 
 
+@dataclass
+class ApiToken:
+    """A long-lived API token (``qcli_pat_…``).
+
+    Stores keep only ``token_hash`` (SHA-256 hex of the token), never the
+    token itself.  ``permissions`` is an optional scope: ``None`` means the
+    token carries the user's full (live) permissions.
+    """
+
+    id: str = ""
+    user_id: str = ""
+    #: 1-64 characters of ``[A-Za-z0-9._ -]``, unique per user (case-insensitive).
+    name: str = ""
+    token_hash: str = ""
+    created_at: int = field(default_factory=now_ms)
+    #: Epoch ms, or ``None`` when the token never expires.
+    expires_at: int | None = None
+    #: Updated at most once per 60 seconds.
+    last_used_at: int | None = None
+    permissions: list[str] | None = None
+
+    def is_expired(self, now: int | None = None) -> bool:
+        return self.expires_at is not None and (now if now is not None else now_ms()) >= self.expires_at
+
+    def to_view(self, user_name: str) -> dict[str, Any]:
+        """``GET /tokens`` shape — never includes the token or its hash."""
+        result: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "userId": self.user_id,
+            "userName": user_name,
+            "createdAt": self.created_at,
+            "expiresAt": self.expires_at,
+            "lastUsedAt": self.last_used_at,
+        }
+        if self.permissions is not None:
+            result["permissions"] = list(self.permissions)
+        return result
+
+
 @dataclass
 class AuditEntry:
     id: str = field(default_factory=_new_id)
@@ -251,6 +291,14 @@ class VerifyPasswordRequest(_Body):
     password: str
 
 
+class CreateApiTokenRequest(_Body):
+    name: Any = None
+    #: Integer 1-365 (default 90); ``null`` = never expires (when allowed).
+    #: Typed ``Any`` so missing, ``null`` and wrong types can be told apart.
+    expiresInDays: Any = None  # noqa: N815
+    permissions: Any = None
+
+
 class CreateGroupRequest(_Body):
     name: str
     description: str | None = None

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/permissions.py

@@ -23,6 +23,8 @@ SESSIONS_READ = "sessions:read"
 SESSIONS_REVOKE = "sessions:revoke"
 AUDIT_READ = "audit:read"
 AUDIT_CLEAR = "audit:clear"
+TOKENS_READ = "tokens:read"
+TOKENS_REVOKE = "tokens:revoke"
 
 ADMIN_GROUP = "admin"
 USERS_GROUP = "users"

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/server_protection.py

@@ -38,7 +38,7 @@ PUBLIC_PATHS: list[tuple[re.Pattern[str], frozenset[str] | None]] = [
 
 #: Routes of the users plugin itself — they authenticate in their own
 #: dependencies (with CSRF and password-change gating).
-SELF_PROTECTED = re.compile(r"^/api/v1/qcli/(sessions|users|groups|audit)(/.*)?$")
+SELF_PROTECTED = re.compile(r"^/api/v1/qcli/(sessions|users|groups|audit|tokens)(/.*)?$")
 
 #: HTTP permission rules, first match wins: (path, methods or None, permission).
 HTTP_RULES: list[Rule] = [
@@ -48,6 +48,9 @@ HTTP_RULES: list[Rule] = [
     (re.compile(r"^/api/(v1/)?qcli/jobs(/.*)?$"), frozenset({"GET", "HEAD"}), "jobs:read"),
     (re.compile(r"^/api/(v1/)?qcli/jobs(/.*)?$"), None, "jobs:manage"),
     (re.compile(r"^/api/(v1/)?qcli/execute(/stream)?/?$"), None, "commands:execute"),
+    # MCP endpoint (tools run commands; each tool also needs the processor's
+    # required permissions).
+    (re.compile(r"^/api/qcli/mcp/?$"), None, "commands:execute"),
 ]
 
 WS_RULES: list[tuple[re.Pattern[str], str | None]] = [

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/services/auth_service.py

@@ -18,6 +18,7 @@ from typing import Any, Awaitable, Callable, Optional, Union
 from .._http import forwarded_client_ip
 from ..errors import UsersApiError, forbidden, unauthorized
 from ..models import (
+    ApiToken,
     AuditEntry,
     ExternalAuthResult,
     Session,
@@ -27,6 +28,7 @@ from ..models import (
 )
 from ..permissions import ADMIN_GROUP, USERS_GROUP, has_permission, merge_permissions, permission_matches
 from ..stores.interfaces import (
+    IApiTokenStore,
     IAuditStore,
     ICredentialStore,
     IGroupStore,
@@ -58,6 +60,12 @@ INSUFFICIENT_PRIVILEGES = "insufficient privileges for this user"
 
 _MAX_TRACKED_KEYS = 10_000
 
+#: Prefix of API tokens (``qcli_pat_`` + 32 random bytes, base64url, no
+#: padding): bearer tokens with it are looked up in the API token store.
+API_TOKEN_PREFIX = "qcli_pat_"
+#: ``last_used_at`` is written at most once per this interval.
+API_TOKEN_LAST_USED_INTERVAL_MS = 60 * 1000
+
 #: Receives the JSON-encoded event; may be sync or async.
 BroadcastFn = Callable[[str], Union[Awaitable[None], None]]
 #: ``(user_id, json_message)`` — delivers to sockets of that user only.
@@ -89,8 +97,18 @@ class AuthContext:
     groups: list[str]
     permissions: list[str]
     session: Session | None = None
+    #: The raw session bearer token (``None`` for API tokens and adapters).
     token: str | None = None
     external: bool = False
+    #: Set when authenticated by an API token (then ``session`` is ``None``).
+    api_token: ApiToken | None = None
+
+    @property
+    def api_token_id(self) -> str | None:
+        return self.api_token.id if self.api_token is not None else None
+
+    #: Server auth-context name of :attr:`api_token_id`.
+    token_id = api_token_id
 
     def can(self, permission: str) -> bool:
         return has_permission(self.permissions, permission)
@@ -123,6 +141,7 @@ class _Ticket:
     user_id: str
     expires_at: int
     external_ctx: AuthContext | None = None
+    api_token_id: str | None = None
 
 
 @dataclass
@@ -143,6 +162,8 @@ class AuthServiceOptions:
     #: always accepted.
     allowed_origins: list[str] | None = None
     ticket_ttl_ms: int = TICKET_TTL_MS
+    #: Allow API tokens that never expire (``expiresInDays: null``).
+    allow_non_expiring_tokens: bool = False
 
 
 class AuthService:
@@ -160,6 +181,7 @@ class AuthService:
         options: AuthServiceOptions | None = None,
         broadcast_fn: BroadcastFn | None = None,
         auth_adapter: Optional[Callable[[Any], Any]] = None,
+        api_token_store: IApiTokenStore | None = None,
     ) -> None:
         if group_store is None:
             from ..stores.in_memory_group_store import InMemoryGroupStore
@@ -169,6 +191,10 @@ class AuthService:
         self.credential_store = credential_store
         self.audit_store = audit_store
         self.group_store = group_store
+        if api_token_store is None:
+            from ..stores.in_memory_api_token_store import InMemoryApiTokenStore
+            api_token_store = InMemoryApiTokenStore()
+        self.api_token_store = api_token_store
         self.options = options or AuthServiceOptions()
         self.broadcast_fn = broadcast_fn
         #: Set when mounted on a CLI server: user-scoped event delivery.
@@ -514,6 +540,8 @@ class AuthService:
             return True
         if ctx.external:
             return True
+        if ctx.api_token is not None:
+            return await self.is_api_token_active(ctx.api_token.id, ctx.user.id)
         if ctx.session is None:
             return False
         session = await self.session_store.get_session_by_id(ctx.session.id)
@@ -555,7 +583,10 @@ class AuthService:
         )
 
     async def authenticate_token(self, token: str) -> AuthContext:
-        """Resolve a bearer token to the live user; raises 401 otherwise."""
+        """Resolve a bearer token (session or API token) to the live user;
+        raises 401 otherwise."""
+        if token.startswith(API_TOKEN_PREFIX):
+            return await self.authenticate_api_token(token)
         token_hash = hash_token(token)
         session = await self.session_store.get_session(token_hash)
         if not session:
@@ -566,6 +597,55 @@ class AuthService:
         ctx.token = token
         return ctx
 
+    # ------------------------------------------------------------------
+    # API tokens
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def generate_api_token() -> str:
+        """``qcli_pat_`` + 32 random bytes, base64url without padding."""
+        return API_TOKEN_PREFIX + secrets.token_urlsafe(32)
+
+    async def context_for_api_token(self, record: ApiToken) -> AuthContext:
+        if record.is_expired():
+            raise unauthorized("invalid or expired token")
+        user = await self.user_store.get_user(record.user_id)
+        if not user or user.id != record.user_id or user.disabled:
+            raise unauthorized("invalid or expired token")
+        groups = list(user.groups or [])
+        permissions = await self.effective_permissions(groups)
+        if record.permissions is not None:
+            # Scoped: keep only scope entries the user still holds.
+            permissions = [p for p in record.permissions if has_permission(permissions, p)]
+        return AuthContext(user=user, groups=groups, permissions=permissions, api_token=record)
+
+    async def authenticate_api_token(self, token: str) -> AuthContext:
+        """Resolve an API token to its live user and (scoped) permissions."""
+        record = await self.api_token_store.get_token_by_hash(hash_token(token))
+        if record is None:
+            raise unauthorized("invalid or expired token")
+        ctx = await self.context_for_api_token(record)
+        now = now_ms()
+        if record.last_used_at is None or now - record.last_used_at >= API_TOKEN_LAST_USED_INTERVAL_MS:
+            await self.api_token_store.update_last_used(record.id, now)
+            record.last_used_at = now
+        return ctx
+
+    async def is_api_token_active(self, token_id: str, user_id: str) -> bool:
+        """Token not revoked/expired and its user neither disabled nor deleted."""
+        record = await self.api_token_store.get_token(token_id)
+        if record is None or record.user_id != user_id:
+            return False
+        try:
+            await self.context_for_api_token(record)
+        except UsersApiError:
+            return False
+        return True
+
+    async def api_token_view(self, record: ApiToken) -> dict[str, Any]:
+        user = await self.user_store.get_user(record.user_id)
+        return record.to_view(user.name if user else "")
+
     async def authenticate_external(self, request: Any) -> AuthContext:
         assert self.auth_adapter is not None
         result = self.auth_adapter(request)
@@ -616,6 +696,7 @@ class AuthService:
             user_id=ctx.user.id,
             expires_at=now + self.options.ticket_ttl_ms,
             external_ctx=ctx if ctx.external else None,
+            api_token_id=ctx.api_token_id,
         )
         return ticket, self.options.ticket_ttl_ms // 1000
 
@@ -633,6 +714,14 @@ class AuthService:
             return None
         if entry.external_ctx is not None:
             return entry.external_ctx
+        if entry.api_token_id is not None:
+            record = await self.api_token_store.get_token(entry.api_token_id)
+            if record is None or record.user_id != entry.user_id:
+                return None
+            try:
+                return await self.context_for_api_token(record)
+            except UsersApiError:
+                return None
         if entry.session_id is None:
             return None
         session = await self.session_store.get_session_by_id(entry.session_id)
@@ -776,6 +865,7 @@ class AuthService:
 
 
 __all__ = [
+    "API_TOKEN_PREFIX",
     "AuthContext",
     "AuthService",
     "AuthServiceOptions",

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/services/users_service.py

@@ -209,7 +209,10 @@ class UsersService:
         await self.credentials.delete_credentials(target.id)
         self.auth.reset_failures(target.id)
         actor = _actor(ctx)
+        # Sessions first (sends session-kicked), then the user's API tokens.
         await self.auth.revoke_user_sessions(target.id, "user_deleted", **actor)
+        await self.auth.api_token_store.delete_user_tokens(target.id)
+        self.auth.notify_change()
         await self.auth.audit("user_deleted", target.name, user_id=target.id, **actor)
 
     async def change_password(

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/shell_access.py

@@ -71,6 +71,8 @@ class UsersShellAccess:
         ctx = principal.context
         if ctx.external:
             return await self._adapter_active(principal)
+        if ctx.api_token is not None:
+            return await self._api_token_active(principal)
         if principal.session_id is None:
             return False
         session = await self.auth.session_store.get_session_by_id(principal.session_id)
@@ -83,6 +85,24 @@ class UsersShellAccess:
             return PERMISSION_REMOVED
         return True
 
+    async def _api_token_active(self, principal: UsersShellPrincipal) -> bool | str:
+        """API token identities: the token must still exist and be unexpired,
+        its user enabled; the (scoped) permissions are re-evaluated."""
+        token = principal.context.api_token
+        assert token is not None
+        record = await self.auth.api_token_store.get_token(token.id)
+        if record is None or record.user_id != principal.user_id:
+            return False
+        try:
+            fresh = await self.auth.context_for_api_token(record)
+        except Exception:
+            return False
+        if fresh.must_change_password:
+            return False
+        if not fresh.can(SHELL_PERMISSION):
+            return PERMISSION_REMOVED
+        return True
+
     async def _adapter_active(self, principal: UsersShellPrincipal) -> bool | str:
         """Adapter identities have no stored session: ask the external auth
         adapter again with the shell's WebSocket (its headers and cookies).

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/stores/__init__.py

@@ -1,6 +1,7 @@
 """Users plugin store implementations."""
 
 from .interfaces import (
+    IApiTokenStore,
     IUserStore,
     ISessionStore,
     ICredentialStore,
@@ -12,8 +13,11 @@ from .in_memory_session_store import InMemorySessionStore
 from .in_memory_credential_store import InMemoryCredentialStore
 from .in_memory_audit_store import InMemoryAuditStore
 from .in_memory_group_store import InMemoryGroupStore
+from .in_memory_api_token_store import InMemoryApiTokenStore
 
 __all__ = [
+    "IApiTokenStore",
+    "InMemoryApiTokenStore",
     "IAuditStore",
     "ICredentialStore",
     "IGroupStore",

qodalis_cli_server_plugin_users-1.0.0b7/qodalis_cli_users/stores/in_memory_api_token_store.py

@@ -0,0 +1,46 @@
+"""In-memory implementation of IApiTokenStore."""
+
+from __future__ import annotations
+
+import copy
+
+from ..models import ApiToken
+from .interfaces import IApiTokenStore
+
+
+class InMemoryApiTokenStore(IApiTokenStore):
+    def __init__(self) -> None:
+        self._tokens: dict[str, ApiToken] = {}  # keyed by id
+
+    async def create_token(self, token: ApiToken) -> ApiToken:
+        self._tokens[token.id] = copy.deepcopy(token)
+        return copy.deepcopy(token)
+
+    async def get_token_by_hash(self, token_hash: str) -> ApiToken | None:
+        for token in self._tokens.values():
+            if token.token_hash == token_hash:
+                return copy.deepcopy(token)
+        return None
+
+    async def get_token(self, token_id: str) -> ApiToken | None:
+        token = self._tokens.get(token_id)
+        return copy.deepcopy(token) if token else None
+
+    async def get_tokens(self, user_id: str | None = None) -> list[ApiToken]:
+        return [
+            copy.deepcopy(t) for t in self._tokens.values()
+            if user_id is None or t.user_id == user_id
+        ]
+
+    async def delete_token(self, token_id: str) -> None:
+        self._tokens.pop(token_id, None)
+
+    async def delete_user_tokens(self, user_id: str) -> None:
+        for token_id, token in list(self._tokens.items()):
+            if token.user_id == user_id:
+                del self._tokens[token_id]
+
+    async def update_last_used(self, token_id: str, last_used_at: int) -> None:
+        token = self._tokens.get(token_id)
+        if token:
+            token.last_used_at = last_used_at

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/stores/interfaces.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from ..models import (
+    ApiToken,
     AuditEntry,
     AuditQueryOptions,
     Credentials,
@@ -199,7 +200,44 @@ class IGroupStore(ABC):
         ...
 
 
+class IApiTokenStore(ABC):
+    """Persistence interface for API tokens.
+
+    ``token_hash`` is the SHA-256 (hex) of the token — raw tokens never reach
+    the store.
+    """
+
+    @abstractmethod
+    async def create_token(self, token: ApiToken) -> ApiToken:
+        ...
+
+    @abstractmethod
+    async def get_token_by_hash(self, token_hash: str) -> ApiToken | None:
+        ...
+
+    @abstractmethod
+    async def get_token(self, token_id: str) -> ApiToken | None:
+        ...
+
+    @abstractmethod
+    async def get_tokens(self, user_id: str | None = None) -> list[ApiToken]:
+        """Every token, or only the tokens of ``user_id``."""
+
+    @abstractmethod
+    async def delete_token(self, token_id: str) -> None:
+        ...
+
+    @abstractmethod
+    async def delete_user_tokens(self, user_id: str) -> None:
+        ...
+
+    @abstractmethod
+    async def update_last_used(self, token_id: str, last_used_at: int) -> None:
+        ...
+
+
 __all__ = [
+    "IApiTokenStore",
     "IAuditStore",
     "ICredentialStore",
     "IGroupStore",

{qodalis_cli_server_plugin_users-1.0.0b6 → qodalis_cli_server_plugin_users-1.0.0b7}/qodalis_cli_users/validation.py

@@ -10,7 +10,10 @@ from .errors import bad_request
 
 NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._@-]*$")
 NAME_MAX = 64
-EMAIL_RE = re.compile(r"^[^\s@]+@[^\s@]+$")
+# Email: dot-atom local part (max 64) @ DNS labels ending in a letters-only TLD, or localhost; same rule as web-cli and the other servers.
+EMAIL_RE = re.compile(
+    r"(?=[^@]{1,64}@)[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:localhost|(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]{2,63})"
+)
 EMAIL_MAX = 254
 PERMISSION_RE = re.compile(r"^(\*|[a-z0-9_.-]+(:([a-z0-9_.-]+|\*))*)$", re.IGNORECASE)
 PERMISSION_MAX = 128
@@ -58,7 +61,7 @@ def validate_name(value: str, kind: str = "name") -> str:
 def validate_email(value: str) -> str:
     if not value:
         raise bad_request("email is required")
-    if len(value) > EMAIL_MAX or has_control_chars(value) or not EMAIL_RE.match(value):
+    if len(value) > EMAIL_MAX or has_control_chars(value) or not EMAIL_RE.fullmatch(value):
         raise bad_request("invalid email")
     return value