messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/api/approvals.py

@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Dual-control (maker-checker) approval workflow for high-value actions (ASVS 2.3.5).
+
+Optional and **deny-by-default** (``[approvals]``, off unless enabled). When a gated operation is
+invoked it is **not executed inline**: a pending request (operation key + JSON params + requester) is
+persisted, and a **distinct** second user holding ``approvals:approve`` must release it — the requester
+can never approve their own (enforced server-side). On approval the captured operation is re-executed
+and **both identities** land in the hash-chained audit log. A request older than
+``[approvals].expiry_hours`` can no longer be approved.
+
+The registry (op key -> executor) is populated by the API wiring, where the engine is in scope; this
+module owns only the generic hold/approve/reject mechanics over the ``pending_approvals`` store table.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+from uuid import uuid4
+
+from messagefoundry.config.settings import ApprovalsSettings
+from messagefoundry.store.base import Store
+
+#: An executor re-runs a captured operation on approval, returning a small JSON-able result summary.
+Executor = Callable[[Mapping[str, Any]], Awaitable[dict[str, Any]]]
+
+
+@dataclass(frozen=True)
+class _Operation:
+    key: str
+    label: str  # human description, surfaced in the pending list + audit
+    execute: Executor
+
+
+class ApprovalError(Exception):
+    """A pending-approval decision could not be made. ``status`` is the HTTP code the API should map
+    to (404 unknown, 409 already-decided/expired, 403 self-approval)."""
+
+    def __init__(self, status: int, detail: str) -> None:
+        super().__init__(detail)
+        self.status = status
+        self.detail = detail
+
+
+class ApprovalGate:
+    """Holds the registry of approvable operations and the hold/approve/reject mechanics. One instance
+    per app; created with the live store + the resolved ``[approvals]`` settings."""
+
+    def __init__(self, store: Store, settings: ApprovalsSettings) -> None:
+        self._store = store
+        self._settings = settings
+        self._ops: dict[str, _Operation] = {}
+
+    def register(self, key: str, label: str, execute: Executor) -> None:
+        self._ops[key] = _Operation(key=key, label=label, execute=execute)
+
+    def _gated(self, operation: str) -> bool:
+        return self._settings.enabled and operation in self._settings.operations
+
+    async def guard(
+        self, operation: str, params: Mapping[str, Any], *, requester: str
+    ) -> str | None:
+        """Call at the start of a gated endpoint, **after** the requester's own permission/scope checks
+        pass. If dual-control is active for ``operation``, persist a pending request, audit
+        ``approval.requested``, and return its **id** (the endpoint should respond 202). Otherwise
+        return ``None`` — the endpoint executes inline exactly as before."""
+        if not self._gated(operation):
+            return None
+        now = time.time()
+        approval_id = uuid4().hex
+        expires_at = (
+            None if self._settings.expiry_hours == 0 else now + self._settings.expiry_hours * 3600.0
+        )
+        await self._store.create_pending_approval(
+            approval_id=approval_id,
+            operation=operation,
+            params=json.dumps(dict(params), sort_keys=True),
+            requester=requester,
+            requested_at=now,
+            expires_at=expires_at,
+        )
+        await self._store.record_audit(
+            "approval.requested",
+            actor=requester,
+            detail=json.dumps({"approval_id": approval_id, "operation": operation}),
+        )
+        return approval_id
+
+    async def list_pending(self) -> list[dict[str, Any]]:
+        rows = await self._store.list_pending_approvals(now=time.time())
+        return [
+            {
+                "id": str(r["id"]),
+                "operation": str(r["operation"]),
+                "label": self._label(str(r["operation"])),
+                "requester": str(r["requester"]),
+                "requested_at": float(r["requested_at"]),
+                "expires_at": (None if r["expires_at"] is None else float(r["expires_at"])),
+            }
+            for r in rows
+        ]
+
+    async def approve(self, approval_id: str, *, approver: str) -> dict[str, Any]:
+        """Release a pending request: the captured operation is re-executed and both identities are
+        audited. Refuses self-approval (the requester is not a valid second approver)."""
+        row = await self._require_pending(approval_id)
+        if str(row["requester"]) == approver:
+            raise ApprovalError(403, "you cannot approve your own request")
+        operation = str(row["operation"])
+        op = self._ops.get(operation)
+        if (
+            op is None
+        ):  # registered op was removed between request and approval — refuse, stay pending
+            raise ApprovalError(409, f"operation '{operation}' is no longer available")
+        # Transition to 'approved' FIRST (atomic, guards a double-approve race); only then execute.
+        if not await self._store.decide_pending_approval(
+            approval_id, status="approved", approver=approver, decided_at=time.time()
+        ):
+            raise ApprovalError(409, "request was already decided")
+        params = json.loads(str(row["params"]))
+        result = await op.execute(params)
+        await self._store.record_audit(
+            "approval.approved",
+            actor=approver,
+            detail=json.dumps(
+                {
+                    "approval_id": approval_id,
+                    "operation": operation,
+                    "requester": str(row["requester"]),
+                    "result": result,
+                }
+            ),
+        )
+        return {
+            "operation": operation,
+            "requested_by": str(row["requester"]),
+            "approved_by": approver,
+            "result": result,
+        }
+
+    async def reject(self, approval_id: str, *, approver: str) -> dict[str, Any]:
+        """Decline a pending request without executing it (audited). Any ``approvals:approve`` holder
+        may reject — including the requester cancelling their own."""
+        row = await self._require_pending(approval_id)
+        if not await self._store.decide_pending_approval(
+            approval_id, status="rejected", approver=approver, decided_at=time.time()
+        ):
+            raise ApprovalError(409, "request was already decided")
+        operation = str(row["operation"])
+        await self._store.record_audit(
+            "approval.rejected",
+            actor=approver,
+            detail=json.dumps(
+                {
+                    "approval_id": approval_id,
+                    "operation": operation,
+                    "requester": str(row["requester"]),
+                }
+            ),
+        )
+        return {
+            "operation": operation,
+            "requested_by": str(row["requester"]),
+            "rejected_by": approver,
+        }
+
+    async def _require_pending(self, approval_id: str) -> Any:
+        row = await self._store.get_pending_approval(approval_id)
+        if row is None:
+            raise ApprovalError(404, "no such approval request")
+        if str(row["status"]) != "pending":
+            raise ApprovalError(409, f"request is already {row['status']}")
+        expires_at = row["expires_at"]
+        if expires_at is not None and float(expires_at) <= time.time():
+            raise ApprovalError(409, "request has expired")
+        return row
+
+    def _label(self, operation: str) -> str:
+        op = self._ops.get(operation)
+        return op.label if op is not None else operation

messagefoundry/api/auth_models.py

@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Pydantic request/response models for the auth + user-administration endpoints."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+# Upper bounds on free-text request fields (API-INPUT): reject absurd inputs before they reach the
+# store or argon2. Generous vs any legitimate value; the password cap also bounds argon2 work.
+_NAME_MAX = 256
+_PASSWORD_MAX = 1024
+_GROUP_MAX = 512
+
+
+class LoginRequest(BaseModel):
+    username: str = Field(max_length=_NAME_MAX)
+    password: str = Field(max_length=_PASSWORD_MAX)
+    provider: str = Field("local", max_length=16)  # 'local' | 'ad'
+
+
+class CurrentUser(BaseModel):
+    user_id: str
+    username: str
+    auth_provider: str
+    roles: list[str]
+    permissions: list[str]
+
+
+class LoginResponse(BaseModel):
+    token: str
+    token_type: str = "bearer"
+    must_change_password: bool = False
+    # The password was accepted but a second factor is still required before sensitive operations
+    # (WP-14): the client should prompt for a TOTP / recovery code and POST /auth/mfa-verify.
+    mfa_required: bool = False
+    user: CurrentUser
+
+
+class ProvidersInfo(BaseModel):
+    """What the login screen should offer."""
+
+    local: bool = True
+    ad: bool = False
+    kerberos: bool = False
+
+
+class UserSummary(BaseModel):
+    id: str
+    username: str
+    auth_provider: str
+    display_name: str | None = None
+    email: str | None = None
+    disabled: bool
+    roles: list[str]
+    channel_scope: list[str] | None = None  # per-channel RBAC: allowed connections; None = all
+
+
+class ChannelScope(BaseModel):
+    """A user's per-channel RBAC scope. ``None`` = all channels; a list = exactly those connections."""
+
+    channels: list[str] | None = Field(default=None, max_length=512)
+
+
+class UserCreateRequest(BaseModel):
+    username: str = Field(max_length=_NAME_MAX)
+    password: str = Field(max_length=_PASSWORD_MAX)
+    display_name: str | None = Field(default=None, max_length=_NAME_MAX)
+    email: str | None = Field(default=None, max_length=_NAME_MAX)
+    roles: list[str] = Field(default=[], max_length=64)
+
+
+class UserUpdateRequest(BaseModel):
+    display_name: str | None = Field(default=None, max_length=_NAME_MAX)
+    email: str | None = Field(default=None, max_length=_NAME_MAX)
+    disabled: bool | None = None
+
+
+class RolesUpdateRequest(BaseModel):
+    roles: list[str] = Field(max_length=64)
+
+
+class PasswordChangeRequest(BaseModel):
+    current_password: str = Field(max_length=_PASSWORD_MAX)
+    new_password: str = Field(max_length=_PASSWORD_MAX)
+
+
+class ReauthRequest(BaseModel):
+    """Step-up re-verification (ASVS 7.5.3): the caller re-supplies their current credential to refresh
+    the session's step-up window before a highly sensitive operation."""
+
+    password: str = Field(max_length=_PASSWORD_MAX)
+
+
+class PasswordResetResponse(BaseModel):
+    """The result of an admin password reset (ASVS 6.4.6): a one-time credential returned **once** for
+    the administrator to convey out-of-band. The user must change it on first login."""
+
+    temp_password: str
+    must_change_password: bool = True
+
+
+# --- MFA: native TOTP second factor (WP-14, ASVS 6.3.3) ----------------------
+
+
+class MfaVerifyRequest(BaseModel):
+    """Satisfy a session's second factor with a TOTP code **or** a single-use recovery code."""
+
+    code: str = Field(max_length=64)
+
+
+class MfaEnrollResponse(BaseModel):
+    """A staged (not-yet-active) TOTP enrollment: the base32 secret + the ``otpauth://`` URI the
+    console renders as a QR. Returned once; the secret is not active until confirmed."""
+
+    secret: str
+    otpauth_uri: str
+
+
+class MfaConfirmRequest(BaseModel):
+    """Confirm a staged enrollment by proving a live TOTP code from the authenticator app."""
+
+    code: str = Field(max_length=16)
+
+
+class MfaConfirmResponse(BaseModel):
+    """The one-time single-use recovery codes minted on enrollment — shown **once** for the user to
+    save (lost-authenticator escape hatch)."""
+
+    recovery_codes: list[str]
+
+
+class MfaStatusResponse(BaseModel):
+    """The caller's current MFA posture for ``GET /me/mfa``."""
+
+    enabled: bool
+    enrolled_at: float | None = None
+    recovery_codes_remaining: int = 0
+    required: bool = False
+
+
+class RoleInfo(BaseModel):
+    id: str
+    display_name: str
+    description: str | None = None
+    permissions: list[str]
+
+
+class AdGroupMapEntry(BaseModel):
+    ad_group: str = Field(max_length=_GROUP_MAX)
+    role: str = Field(max_length=64)
+
+
+class AdGroupMap(BaseModel):
+    entries: list[AdGroupMapEntry]
+
+
+class AdGroupScopeEntry(BaseModel):
+    """Maps an AD group to one allowed channel; channel ``*`` = all channels (per-channel RBAC C3)."""
+
+    ad_group: str = Field(max_length=_GROUP_MAX)
+    channel: str = Field(max_length=_NAME_MAX)
+
+
+class AdGroupScopeMap(BaseModel):
+    entries: list[AdGroupScopeEntry]
+
+
+class AuditEntry(BaseModel):
+    ts: float
+    actor: str | None = None
+    action: str
+    channel_id: str | None = None
+    detail: str | None = None
+
+
+class AuditList(BaseModel):
+    entries: list[AuditEntry]
+
+
+class SimpleMessage(BaseModel):
+    detail: str
+
+
+class SessionInfo(BaseModel):
+    """One active session in the self-service inventory (WP-10). ``id`` is the session's ``token_hash``
+    (a one-way hash of the opaque token, safe to expose) — pass it to ``DELETE /me/sessions/{id}``."""
+
+    id: str
+    created_at: float
+    last_used_at: float
+    expires_at: float
+    client: str | None = None
+    current: bool = False
+
+
+class SessionList(BaseModel):
+    sessions: list[SessionInfo]
+
+
+class SecurityEventInfo(BaseModel):
+    """One entry in the caller's security-event history (WP-L3-05, ASVS 6.3.5/6.3.7) — a view over the
+    audited ``auth.*`` actions. ``detail`` is the audit log's JSON metadata (PHI-free)."""
+
+    ts: float
+    action: str  # e.g. auth.login_success / auth.login_locked / auth.password_changed
+    detail: str | None = None
+
+
+class SecurityEventsList(BaseModel):
+    events: list[SecurityEventInfo]