qodalis-cli-server-plugin-users 1.0.0b6__py3-none-any.whl

qodalis_cli_users/stores/in_memory_group_store.py

@@ -0,0 +1,65 @@
+"""In-memory implementation of IGroupStore."""
+
+from __future__ import annotations
+
+import copy
+
+from ..models import Group, now_ms
+from .interfaces import IGroupStore
+
+
+class InMemoryGroupStore(IGroupStore):
+    """Groups keyed by lower-cased name; the name is stored as given."""
+
+    def __init__(self) -> None:
+        self._groups: dict[str, Group] = {}
+
+    async def get_groups(self) -> list[Group]:
+        return [copy.deepcopy(g) for g in self._groups.values()]
+
+    async def get_group(self, name: str) -> Group | None:
+        group = self._groups.get(name.lower())
+        return copy.deepcopy(group) if group else None
+
+    async def create_group(
+        self,
+        name: str,
+        description: str | None = None,
+        permissions: list[str] | None = None,
+        *,
+        built_in: bool = False,
+    ) -> Group:
+        key = name.lower()
+        if key in self._groups:
+            raise ValueError(f"group already exists: {name}")
+        now = now_ms()
+        group = Group(
+            name=name,
+            description=description,
+            permissions=list(permissions or []),
+            built_in=built_in,
+            created_at=now,
+            updated_at=now,
+        )
+        self._groups[key] = group
+        return copy.deepcopy(group)
+
+    async def update_group(
+        self,
+        name: str,
+        *,
+        description: str | None = None,
+        permissions: list[str] | None = None,
+    ) -> Group:
+        group = self._groups.get(name.lower())
+        if not group:
+            raise KeyError(f"group not found: {name}")
+        if description is not None:
+            group.description = description
+        if permissions is not None:
+            group.permissions = list(permissions)
+        group.updated_at = now_ms()
+        return copy.deepcopy(group)
+
+    async def delete_group(self, name: str) -> None:
+        self._groups.pop(name.lower(), None)

qodalis_cli_users/stores/in_memory_session_store.py

@@ -0,0 +1,71 @@
+"""In-memory implementation of ISessionStore."""
+
+from __future__ import annotations
+
+import copy
+
+from ..models import Session, SessionMetadata, now_ms
+from .interfaces import ISessionStore
+
+
+class InMemorySessionStore(ISessionStore):
+    def __init__(self) -> None:
+        self._sessions: dict[str, Session] = {}  # keyed by token hash
+
+    async def create_session(
+        self,
+        user_id: str,
+        token_hash: str,
+        metadata: SessionMetadata,
+        *,
+        user_name: str = "",
+    ) -> Session:
+        now = now_ms()
+        session = Session(
+            token_hash=token_hash,
+            user_id=user_id,
+            user_name=user_name,
+            created_at=now,
+            last_activity=now,
+            metadata=metadata or SessionMetadata(),
+        )
+        self._sessions[token_hash] = session
+        return copy.deepcopy(session)
+
+    async def get_session(self, token_hash: str) -> Session | None:
+        session = self._sessions.get(token_hash)
+        return copy.deepcopy(session) if session else None
+
+    async def get_session_by_id(self, session_id: str) -> Session | None:
+        for session in self._sessions.values():
+            if session.id == session_id:
+                return copy.deepcopy(session)
+        return None
+
+    async def get_active_sessions(self) -> list[Session]:
+        return [copy.deepcopy(s) for s in self._sessions.values()]
+
+    async def delete_session(self, token_hash: str) -> None:
+        self._sessions.pop(token_hash, None)
+
+    async def delete_session_by_id(self, session_id: str) -> None:
+        for token, session in list(self._sessions.items()):
+            if session.id == session_id:
+                del self._sessions[token]
+                return
+
+    async def delete_user_sessions(self, user_id: str) -> None:
+        for token, session in list(self._sessions.items()):
+            if session.user_id == user_id:
+                del self._sessions[token]
+
+    async def update_last_activity(self, token_hash: str) -> None:
+        session = self._sessions.get(token_hash)
+        if session:
+            session.last_activity = now_ms()
+
+    async def cleanup(self, max_age_ms: int) -> None:
+        cutoff = now_ms() - max_age_ms
+        for token, session in list(self._sessions.items()):
+            if session.last_activity < cutoff:
+                del self._sessions[token]

qodalis_cli_users/stores/in_memory_user_store.py

@@ -0,0 +1,102 @@
+"""In-memory implementation of IUserStore."""
+
+from __future__ import annotations
+
+import copy
+
+from ..models import User, now_ms
+from .interfaces import IUserStore
+
+
+class InMemoryUserStore(IUserStore):
+    """Keeps users in a dict.  Returns copies so callers never alias the
+    stored records (changes must go through :meth:`update_user`)."""
+
+    def __init__(self) -> None:
+        self._users: dict[str, User] = {}
+
+    async def get_users(self) -> list[User]:
+        return [copy.deepcopy(u) for u in self._users.values()]
+
+    def _find(self, id_or_name: str) -> User | None:
+        if id_or_name in self._users:
+            return self._users[id_or_name]
+        lower = id_or_name.lower()
+        for user in self._users.values():
+            if user.name.lower() == lower:
+                return user
+        return None
+
+    async def get_user(self, id_or_name: str) -> User | None:
+        user = self._find(id_or_name)
+        return copy.deepcopy(user) if user else None
+
+    async def create_user(
+        self,
+        name: str,
+        email: str,
+        groups: list[str] | None = None,
+        data: dict | None = None,
+        *,
+        disabled: bool = False,
+        home_dir: str | None = None,
+        must_change_password: bool = False,
+    ) -> User:
+        lower = name.lower()
+        for user in self._users.values():
+            if user.name.lower() == lower:
+                raise ValueError(f"user already exists: {name}")
+
+        now = now_ms()
+        user = User(
+            name=name,
+            email=email,
+            groups=list(groups or []),
+            disabled=disabled,
+            must_change_password=must_change_password,
+            home_dir=home_dir,
+            data=copy.deepcopy(data),
+            created_at=now,
+            updated_at=now,
+        )
+        self._users[user.id] = user
+        return copy.deepcopy(user)
+
+    async def update_user(
+        self,
+        user_id: str,
+        *,
+        name: str | None = None,
+        email: str | None = None,
+        groups: list[str] | None = None,
+        disabled: bool | None = None,
+        data: dict | None = None,
+        home_dir: str | None = None,
+        last_login_at: int | None = None,
+        must_change_password: bool | None = None,
+    ) -> User:
+        user = self._users.get(user_id)
+        if not user:
+            raise KeyError(f"user not found: {user_id}")
+
+        if name is not None:
+            user.name = name
+        if email is not None:
+            user.email = email
+        if groups is not None:
+            user.groups = list(groups)
+        if disabled is not None:
+            user.disabled = disabled
+        if data is not None:
+            user.data = copy.deepcopy(data)
+        if home_dir is not None:
+            user.home_dir = home_dir
+        if last_login_at is not None:
+            user.last_login_at = last_login_at
+        if must_change_password is not None:
+            user.must_change_password = must_change_password
+        user.updated_at = now_ms()
+        return copy.deepcopy(user)
+
+    async def delete_user(self, user_id: str) -> None:
+        self._users.pop(user_id, None)

qodalis_cli_users/stores/interfaces.py

@@ -0,0 +1,208 @@
+"""Abstract store interfaces for the users plugin.
+
+Implement these to persist users, sessions, credentials, groups and the audit
+log in your own storage.  All business rules (permissions, cascades,
+protections) live in the plugin; stores are plain persistence.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from ..models import (
+    AuditEntry,
+    AuditQueryOptions,
+    Credentials,
+    Group,
+    Session,
+    SessionMetadata,
+    User,
+)
+
+
+class IUserStore(ABC):
+    """Persistence interface for user records."""
+
+    @abstractmethod
+    async def get_users(self) -> list[User]:
+        ...
+
+    @abstractmethod
+    async def get_user(self, id_or_name: str) -> User | None:
+        """Look a user up by id, or by name (case-insensitive)."""
+
+    async def get_user_by_email(self, email: str) -> User | None:
+        """Look a user up by email (case-insensitive).
+
+        Default implementation scans :meth:`get_users`; override for
+        efficiency.
+        """
+        lower = email.strip().lower()
+        for user in await self.get_users():
+            if user.email.lower() == lower:
+                return user
+        return None
+
+    @abstractmethod
+    async def create_user(
+        self,
+        name: str,
+        email: str,
+        groups: list[str] | None = None,
+        data: dict | None = None,
+        *,
+        disabled: bool = False,
+        home_dir: str | None = None,
+        must_change_password: bool = False,
+    ) -> User:
+        ...
+
+    @abstractmethod
+    async def update_user(
+        self,
+        user_id: str,
+        *,
+        name: str | None = None,
+        email: str | None = None,
+        groups: list[str] | None = None,
+        disabled: bool | None = None,
+        data: dict | None = None,
+        home_dir: str | None = None,
+        last_login_at: int | None = None,
+        must_change_password: bool | None = None,
+    ) -> User:
+        """Update the given fields (``None`` = unchanged).  Raises
+        ``KeyError`` when the user does not exist."""
+
+    @abstractmethod
+    async def delete_user(self, user_id: str) -> None:
+        ...
+
+
+class ISessionStore(ABC):
+    """Persistence interface for sessions.
+
+    Sessions are keyed by ``token_hash`` — the SHA-256 (hex) of the bearer
+    token; raw tokens never reach the store.  Also addressable by id.
+    """
+
+    @abstractmethod
+    async def create_session(
+        self,
+        user_id: str,
+        token_hash: str,
+        metadata: SessionMetadata,
+        *,
+        user_name: str = "",
+    ) -> Session:
+        ...
+
+    @abstractmethod
+    async def get_session(self, token_hash: str) -> Session | None:
+        ...
+
+    @abstractmethod
+    async def get_session_by_id(self, session_id: str) -> Session | None:
+        ...
+
+    @abstractmethod
+    async def get_active_sessions(self) -> list[Session]:
+        ...
+
+    @abstractmethod
+    async def delete_session(self, token_hash: str) -> None:
+        ...
+
+    @abstractmethod
+    async def delete_session_by_id(self, session_id: str) -> None:
+        ...
+
+    @abstractmethod
+    async def delete_user_sessions(self, user_id: str) -> None:
+        ...
+
+    @abstractmethod
+    async def update_last_activity(self, token_hash: str) -> None:
+        ...
+
+    @abstractmethod
+    async def cleanup(self, max_age_ms: int) -> None:
+        """Delete sessions idle for longer than ``max_age_ms``."""
+
+
+class ICredentialStore(ABC):
+    """Persistence interface for user credentials."""
+
+    @abstractmethod
+    async def set_password(self, user_id: str, hash_: str, salt: str) -> None:
+        ...
+
+    @abstractmethod
+    async def get_credentials(self, user_id: str) -> Credentials | None:
+        ...
+
+    @abstractmethod
+    async def delete_credentials(self, user_id: str) -> None:
+        ...
+
+
+class IAuditStore(ABC):
+    """Persistence interface for audit log entries."""
+
+    @abstractmethod
+    async def log(self, entry: AuditEntry) -> None:
+        ...
+
+    @abstractmethod
+    async def get_entries(self, options: AuditQueryOptions | None = None) -> list[AuditEntry]:
+        """Entries newest-first, filtered by ``options``."""
+
+    @abstractmethod
+    async def clear(self) -> None:
+        ...
+
+
+class IGroupStore(ABC):
+    """Persistence interface for user groups.  Lookups are case-insensitive."""
+
+    @abstractmethod
+    async def get_groups(self) -> list[Group]:
+        ...
+
+    @abstractmethod
+    async def get_group(self, name: str) -> Group | None:
+        ...
+
+    @abstractmethod
+    async def create_group(
+        self,
+        name: str,
+        description: str | None = None,
+        permissions: list[str] | None = None,
+        *,
+        built_in: bool = False,
+    ) -> Group:
+        """Raises ``ValueError`` when a group with that name exists."""
+
+    @abstractmethod
+    async def update_group(
+        self,
+        name: str,
+        *,
+        description: str | None = None,
+        permissions: list[str] | None = None,
+    ) -> Group:
+        """Update the given fields (``None`` = unchanged).  Raises
+        ``KeyError`` when the group does not exist."""
+
+    @abstractmethod
+    async def delete_group(self, name: str) -> None:
+        ...
+
+
+__all__ = [
+    "IAuditStore",
+    "ICredentialStore",
+    "IGroupStore",
+    "ISessionStore",
+    "IUserStore",
+]

qodalis_cli_users/validation.py

@@ -0,0 +1,100 @@
+"""Input validation rules (security contract B7)."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+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_MAX = 254
+PERMISSION_RE = re.compile(r"^(\*|[a-z0-9_.-]+(:([a-z0-9_.-]+|\*))*)$", re.IGNORECASE)
+PERMISSION_MAX = 128
+PERMISSIONS_PER_GROUP_MAX = 100
+DESCRIPTION_MAX = 256
+DATA_MAX_BYTES = 16 * 1024
+BODY_MAX_BYTES = 1024 * 1024
+PASSWORD_MAX = 1024
+
+# Control characters, plus lone UTF-16 surrogates (valid in JSON escapes but
+# not encodable as UTF-8: stored, they make every response containing them fail).
+_CONTROL_RE = re.compile(r"[\u0000-\u001f\u007f\ud800-\udfff]")
+_SURROGATE_RE = re.compile(r"[\ud800-\udfff]")
+
+
+def has_control_chars(value: str) -> bool:
+    return bool(_CONTROL_RE.search(value))
+
+
+def has_lone_surrogates(value: str) -> bool:
+    return bool(_SURROGATE_RE.search(value))
+
+
+def sanitize(value: str | None, max_len: int | None = None) -> str | None:
+    """Strip control characters (incl. ANSI ESC) and truncate."""
+    if value is None:
+        return None
+    cleaned = _CONTROL_RE.sub("", value)
+    return cleaned[:max_len] if max_len is not None else cleaned
+
+
+def validate_name(value: str, kind: str = "name") -> str:
+    if not value:
+        raise bad_request(f"{kind} is required")
+    if len(value) > NAME_MAX:
+        raise bad_request(f"{kind} must be at most {NAME_MAX} characters")
+    if not NAME_RE.match(value):
+        raise bad_request(
+            f"invalid {kind}: must start with a letter or digit and contain only "
+            "letters, digits, '.', '_', '@' or '-'"
+        )
+    return value
+
+
+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):
+        raise bad_request("invalid email")
+    return value
+
+
+def validate_text(value: str | None, field: str, max_len: int) -> str | None:
+    if value is None:
+        return None
+    if has_control_chars(value):
+        raise bad_request(f"{field} must not contain control characters")
+    if len(value) > max_len:
+        raise bad_request(f"{field} must be at most {max_len} characters")
+    return value
+
+
+def validate_permissions(permissions: list[str] | None) -> list[str] | None:
+    if permissions is None:
+        return None
+    if len(permissions) > PERMISSIONS_PER_GROUP_MAX:
+        raise bad_request(f"at most {PERMISSIONS_PER_GROUP_MAX} permissions per group")
+    out: list[str] = []
+    for raw in permissions:
+        p = raw.strip()
+        if not p or len(p) > PERMISSION_MAX or not PERMISSION_RE.match(p):
+            raise bad_request(f"invalid permission: {sanitize(raw, PERMISSION_MAX)}")
+        if p.lower() not in (x.lower() for x in out):
+            out.append(p)
+    return out
+
+
+def validate_data(data: dict[str, Any] | None) -> dict[str, Any] | None:
+    if data is None:
+        return None
+    try:
+        size = len(json.dumps(data, separators=(",", ":"), ensure_ascii=False).encode("utf-8"))
+    except (TypeError, ValueError) as exc:
+        raise bad_request("invalid data") from exc
+    if size > DATA_MAX_BYTES:
+        raise bad_request(f"data must be at most {DATA_MAX_BYTES} bytes")
+    return data