codexLB-up 1.25.0b10__py3-none-any.whl

app/modules/scim/management_api.py

@@ -0,0 +1,156 @@
+"""Issuing, rotating and revoking SCIM credentials (``security:write``).
+
+Issue and rotate carry one gate the rest of the module does not:
+``assert_can_delegate(principal.grants, ADMIN_GRANTS)``. The reasoning is
+§4.6-A1's, applied to a fourth lever. A SCIM token lets a machine assert who
+somebody is *and* attach a role, with no human in the loop per push, which is
+the same class of lever as writing an OIDC connection or turning on e-mail
+linking — and those are gated on admin-level delegation precisely because
+``security:write`` is permission to administer sign-in, not permission to
+become somebody else. Revoking is never gated: the narrowing direction stays
+open everywhere in this plan.
+
+The plaintext appears in the response to issue and to rotate and nowhere else —
+not in a list, not in a later read, not in a log line, not in an audit row.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+
+from app.core.audit.service import AuditActor, AuditService, AuditTarget
+from app.core.auth.dashboard_access import (
+    ADMIN_GRANTS,
+    DashboardPrincipal,
+    InsufficientDelegationError,
+    Permission,
+    assert_can_delegate,
+)
+from app.core.auth.dependencies import require_dashboard_permission, set_dashboard_error_format
+from app.core.exceptions import DashboardNotFoundError, DashboardPermissionError
+from app.db.models import DashboardScimToken
+from app.dependencies import ScimTokensContext, get_scim_tokens_context
+from app.modules.scim.api import SCIM_BASE_PATH
+from app.modules.scim.repository import SCIM_PROVIDER
+from app.modules.scim.schemas import (
+    ScimTokenCreateRequest,
+    ScimTokenIssuedResponse,
+    ScimTokenListResponse,
+    ScimTokenResponse,
+)
+from app.modules.scim.tokens import generate_token, hash_token, token_prefix
+
+router = APIRouter(
+    prefix="/api/scim-tokens",
+    tags=["dashboard"],
+    dependencies=[
+        Depends(require_dashboard_permission(Permission.SECURITY_WRITE)),
+        Depends(set_dashboard_error_format),
+    ],
+)
+
+#: Every token this release issues owns the install's single identity
+#: namespace. The column is enforced on every lookup and insert anyway, because
+#: deriving the namespace from the request instead is the bug the requirement
+#: exists to prevent, and a scoping field that exists and is unenforced is
+#: worse than none.
+DEFAULT_PROVIDER_KEY = "default"
+
+
+def _response(row: DashboardScimToken) -> ScimTokenResponse:
+    return ScimTokenResponse(
+        id=row.id,
+        label=row.label,
+        token_prefix=row.token_prefix,
+        created_at=row.created_at,
+        created_by_user_id=row.created_by_user_id,
+        last_used_at=row.last_used_at,
+        rotated_at=row.rotated_at,
+    )
+
+
+def _require_admin_delegation(principal: DashboardPrincipal) -> None:
+    try:
+        assert_can_delegate(principal.grants, ADMIN_GRANTS)
+    except InsufficientDelegationError as exc:
+        raise DashboardPermissionError(
+            "Issuing an automatic-account-management credential needs the permissions it could hand out",
+            code="insufficient_delegation",
+        ) from exc
+
+
+def _audit(action: str, principal: DashboardPrincipal, row: DashboardScimToken, request: Request) -> None:
+    """The row id and the label travel; the secret and its digest never do.
+
+    The audit sanitiser drops keys by exact name from a fixed set and knows
+    none of these, so it is not a safety net here — the rule is simply that no
+    detail dictionary ever carries the credential under any name.
+    """
+
+    AuditService.log_async(
+        action,
+        actor_ip=request.client.host if request.client else None,
+        details={"label": row.label, "token_prefix": row.token_prefix, "provider": SCIM_PROVIDER},
+        actor=AuditActor.from_principal(principal),
+        target=AuditTarget("scim_token", row.id),
+    )
+
+
+@router.get("", response_model=ScimTokenListResponse)
+async def list_scim_tokens(
+    context: ScimTokensContext = Depends(get_scim_tokens_context),
+) -> ScimTokenListResponse:
+    rows = await context.repository.list_tokens()
+    return ScimTokenListResponse(tokens=[_response(row) for row in rows], base_path=SCIM_BASE_PATH)
+
+
+@router.post("", response_model=ScimTokenIssuedResponse, status_code=201)
+async def issue_scim_token(
+    request: Request,
+    payload: ScimTokenCreateRequest,
+    context: ScimTokensContext = Depends(get_scim_tokens_context),
+    principal: DashboardPrincipal = Depends(require_dashboard_permission(Permission.SECURITY_WRITE)),
+) -> ScimTokenIssuedResponse:
+    _require_admin_delegation(principal)
+    secret = generate_token()
+    row = await context.repository.create(
+        label=payload.label,
+        token_hash=hash_token(secret),
+        token_prefix=token_prefix(secret),
+        provider_key=DEFAULT_PROVIDER_KEY,
+        created_by_user_id=principal.user_id,
+    )
+    _audit("scim_token_issued", principal, row, request)
+    return ScimTokenIssuedResponse(token=_response(row), secret=secret)
+
+
+@router.post("/{token_id}/rotate", response_model=ScimTokenIssuedResponse)
+async def rotate_scim_token(
+    token_id: str,
+    request: Request,
+    context: ScimTokensContext = Depends(get_scim_tokens_context),
+    principal: DashboardPrincipal = Depends(require_dashboard_permission(Permission.SECURITY_WRITE)),
+) -> ScimTokenIssuedResponse:
+    _require_admin_delegation(principal)
+    secret = generate_token()
+    # In place on the same row: the id, the label and the sync history survive,
+    # and the previous secret stops working the moment this commits, because
+    # the row is the only verifier there is.
+    row = await context.repository.rotate(token_id, token_hash=hash_token(secret), token_prefix=token_prefix(secret))
+    if row is None:
+        raise DashboardNotFoundError("No such token", code="scim_token_not_found")
+    _audit("scim_token_rotated", principal, row, request)
+    return ScimTokenIssuedResponse(token=_response(row), secret=secret)
+
+
+@router.delete("/{token_id}", status_code=204)
+async def revoke_scim_token(
+    token_id: str,
+    request: Request,
+    context: ScimTokensContext = Depends(get_scim_tokens_context),
+    principal: DashboardPrincipal = Depends(require_dashboard_permission(Permission.SECURITY_WRITE)),
+) -> None:
+    row = await context.repository.get(token_id)
+    if row is None or not await context.repository.delete(token_id):
+        raise DashboardNotFoundError("No such token", code="scim_token_not_found")
+    _audit("scim_token_revoked", principal, row, request)

app/modules/scim/repository.py

@@ -0,0 +1,212 @@
+"""Queries and writes for SCIM bearer tokens and the accounts they provision.
+
+Two concerns live here because they share one rule: every read and every write
+is bound to the ``provider_key`` carried on the token row. An account the token
+did not provision has no ``scim`` identity in that namespace and is therefore
+not addressable at all — which is what stands in for ``assert_can_act_on`` on a
+surface that has no principal.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+from datetime import UTC, datetime
+
+from sqlalchemy import delete, func, or_, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.db.models import (
+    AuditLog,
+    DashboardIdentity,
+    DashboardRoleRecord,
+    DashboardScimToken,
+    DashboardUser,
+)
+
+#: The provider string on every identity row this surface writes.
+SCIM_PROVIDER = "scim"
+#: How many resources one list page may carry, whatever the caller asks for.
+#: RFC 7644 §3.4.2.4 lets a server return fewer than ``count``; clamping is the
+#: bound on a read, the way the body cap is the bound on a write.
+MAX_LIST_COUNT = 200
+
+
+def _identity_query():
+    return select(DashboardIdentity).options(
+        selectinload(DashboardIdentity.user).selectinload(DashboardUser.role).selectinload(DashboardRoleRecord.grants)
+    )
+
+
+class ScimTokensRepository:
+    """The credential rows. Nothing here ever returns or accepts a plaintext token."""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def get_by_hash(self, token_hash: str) -> DashboardScimToken | None:
+        stmt = select(DashboardScimToken).where(DashboardScimToken.token_hash == token_hash)
+        return (await self._session.execute(stmt)).scalar_one_or_none()
+
+    async def get(self, token_id: str) -> DashboardScimToken | None:
+        return await self._session.get(DashboardScimToken, token_id)
+
+    async def list_tokens(self) -> Sequence[DashboardScimToken]:
+        stmt = select(DashboardScimToken).order_by(DashboardScimToken.created_at.asc(), DashboardScimToken.id.asc())
+        return (await self._session.execute(stmt)).scalars().all()
+
+    async def count_tokens(self) -> int:
+        return int((await self._session.execute(select(func.count()).select_from(DashboardScimToken))).scalar_one())
+
+    async def create(
+        self,
+        *,
+        label: str,
+        token_hash: str,
+        token_prefix: str,
+        provider_key: str,
+        created_by_user_id: str | None,
+    ) -> DashboardScimToken:
+        row = DashboardScimToken(
+            id=str(uuid.uuid4()),
+            label=label,
+            token_hash=token_hash,
+            token_prefix=token_prefix,
+            provider_key=provider_key,
+            created_by_user_id=created_by_user_id,
+        )
+        self._session.add(row)
+        await self._session.commit()
+        await self._session.refresh(row)
+        return row
+
+    async def rotate(self, token_id: str, *, token_hash: str, token_prefix: str) -> DashboardScimToken | None:
+        """Replace the verifier on the same row; the id, label and sync history survive."""
+
+        updated = await self._session.execute(
+            update(DashboardScimToken)
+            .where(DashboardScimToken.id == token_id)
+            .values(token_hash=token_hash, token_prefix=token_prefix, rotated_at=datetime.now(UTC))
+            .returning(DashboardScimToken.id)
+            .execution_options(synchronize_session=False)
+        )
+        if updated.scalar_one_or_none() is None:
+            await self._session.rollback()
+            return None
+        await self._session.commit()
+        self._session.expire_all()
+        return await self.get(token_id)
+
+    async def delete(self, token_id: str) -> bool:
+        deleted = await self._session.execute(
+            delete(DashboardScimToken)
+            .where(DashboardScimToken.id == token_id)
+            .returning(DashboardScimToken.id)
+            .execution_options(synchronize_session=False)
+        )
+        if deleted.scalar_one_or_none() is None:
+            await self._session.rollback()
+            return False
+        await self._session.commit()
+        return True
+
+    async def record_used(self, token_id: str, now: datetime) -> None:
+        """Advance ``last_used_at`` monotonically, so replicas may write out of order.
+
+        The guard is the whole point: two replicas serving two pushes can
+        commit in either order, and a blind ``SET`` would let the older one win
+        and make the card's "last sync" go backwards.
+        """
+
+        await self._session.execute(
+            update(DashboardScimToken)
+            .where(DashboardScimToken.id == token_id)
+            .where(or_(DashboardScimToken.last_used_at.is_(None), DashboardScimToken.last_used_at < now))
+            .values(last_used_at=now)
+            .execution_options(synchronize_session=False)
+        )
+        await self._session.commit()
+
+
+class ScimUsersRepository:
+    """Accounts as this surface sees them: through their ``scim`` identity row."""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def get_identity_by_subject(self, provider_key: str, subject: str) -> DashboardIdentity | None:
+        """The identity a push names. ``subject`` is compared exactly: it is opaque."""
+
+        stmt = (
+            _identity_query()
+            .where(DashboardIdentity.provider == SCIM_PROVIDER)
+            .where(DashboardIdentity.provider_key == provider_key)
+            .where(DashboardIdentity.subject == subject)
+        )
+        return (await self._session.execute(stmt)).scalar_one_or_none()
+
+    async def get_identity_by_user(self, provider_key: str, user_id: str) -> DashboardIdentity | None:
+        """The resource a SCIM ``id`` names, or ``None`` when it is outside this namespace.
+
+        An account without a ``scim`` identity here is not a resource of this
+        token, whatever else it is on the install, and the route answers ``404``
+        rather than distinguishing "no such account" from "not yours".
+        """
+
+        stmt = (
+            _identity_query()
+            .where(DashboardIdentity.provider == SCIM_PROVIDER)
+            .where(DashboardIdentity.provider_key == provider_key)
+            .where(DashboardIdentity.user_id == user_id)
+        )
+        return (await self._session.execute(stmt)).scalars().first()
+
+    async def audit_row_exists(self, action: str, user_id: str) -> bool:
+        """Whether this surface has already recorded ``action`` against that account.
+
+        The audit row is the marker for the decisions this surface makes once
+        per account rather than once per push — an identity provider re-pushes
+        its whole directory on a schedule, and a row per push buries the one an
+        operator needs. ``idx_audit_logs_target`` covers the predicate.
+        """
+
+        stmt = (
+            select(AuditLog.id)
+            .where(AuditLog.action == action)
+            .where(AuditLog.target_type == "user")
+            .where(AuditLog.target_id == user_id)
+            .limit(1)
+        )
+        return (await self._session.execute(stmt)).scalars().first() is not None
+
+    async def list_identities(
+        self, provider_key: str, *, user_name: str | None, offset: int, limit: int
+    ) -> tuple[Sequence[DashboardIdentity], int]:
+        """One page of this namespace's resources plus the unpaged total.
+
+        Disabled and invited accounts are included on purpose: a deprovisioned
+        person has to stay rediscoverable by the filter that found them.
+        """
+
+        base = (
+            select(DashboardIdentity.id)
+            .where(DashboardIdentity.provider == SCIM_PROVIDER)
+            .where(DashboardIdentity.provider_key == provider_key)
+        )
+        if user_name is not None:
+            base = base.where(func.lower(DashboardIdentity.user_name) == user_name.casefold())
+        total = int((await self._session.execute(select(func.count()).select_from(base.subquery()))).scalar_one())
+        page = _identity_query().where(DashboardIdentity.id.in_(base))
+        rows = (
+            (
+                await self._session.execute(
+                    page.order_by(DashboardIdentity.created_at.asc(), DashboardIdentity.id.asc())
+                    .offset(offset)
+                    .limit(limit)
+                )
+            )
+            .scalars()
+            .all()
+        )
+        return rows, total

app/modules/scim/schemas.py

@@ -0,0 +1,145 @@
+"""The SCIM 2.0 wire shapes this surface reads and writes (RFC 7643 / RFC 7644).
+
+Attributes this product does not model are ignored rather than refused. Every
+identity provider sends more than a core user — ``meta``, ``title``,
+``locale``, phone numbers, an enterprise extension — and refusing those would
+turn a routine Okta or Entra push into a ``400`` while protecting nothing: the
+bound on a request is the declared body size (checked before the body is read)
+plus the length and cardinality caps below, not the attribute vocabulary.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.modules.shared.schemas import DashboardModel
+
+USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User"
+LIST_RESPONSE_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:ListResponse"
+PATCH_OP_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:PatchOp"
+
+#: 64 KiB. A core user resource is a few hundred bytes and the largest patch
+#: this surface accepts is a few kilobytes; the global ingress budget of 32 MiB
+#: is not a bound for this endpoint in any useful sense.
+MAX_BODY_BYTES = 64 * 1024
+#: Cardinality caps. A multi-valued attribute an identity provider fills with
+#: thousands of entries is a denial of service, not a user.
+MAX_MULTI_VALUED = 8
+MAX_PATCH_OPERATIONS = 32
+
+#: ``active`` arrives as a JSON boolean from most identity providers and as the
+#: strings ``"True"``/``"False"`` from Entra ID's SCIM client. Both mean the
+#: same thing, and guessing wrong deprovisions the wrong people.
+_TRUE_STRINGS = frozenset({"true", "1"})
+_FALSE_STRINGS = frozenset({"false", "0"})
+
+
+def coerce_active(value: Any) -> bool | None:
+    """A SCIM ``active`` value as a boolean, or ``None`` when it is not one."""
+
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        folded = value.strip().casefold()
+        if folded in _TRUE_STRINGS:
+            return True
+        if folded in _FALSE_STRINGS:
+            return False
+    return None
+
+
+class ScimModel(BaseModel):
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+
+class ScimMultiValue(ScimModel):
+    value: str | None = Field(default=None, max_length=320)
+    type: str | None = Field(default=None, max_length=32)
+    primary: bool = False
+
+
+class ScimName(ScimModel):
+    formatted: str | None = Field(default=None, max_length=128)
+    given_name: str | None = Field(default=None, alias="givenName", max_length=64)
+    family_name: str | None = Field(default=None, alias="familyName", max_length=64)
+
+
+class ScimUserRequest(ScimModel):
+    """A ``POST`` or ``PUT`` body.
+
+    Every attribute is optional at the model level; which of them a given
+    operation requires is the service's rule, so the refusal names the
+    attribute in RFC 7644's envelope instead of FastAPI's.
+    """
+
+    schemas: list[str] = Field(default_factory=list, max_length=MAX_MULTI_VALUED)
+    user_name: str | None = Field(default=None, alias="userName", max_length=256)
+    external_id: str | None = Field(default=None, alias="externalId", max_length=512)
+    display_name: str | None = Field(default=None, alias="displayName", max_length=128)
+    active: Any = None
+    name: ScimName | None = None
+    emails: list[ScimMultiValue] = Field(default_factory=list, max_length=MAX_MULTI_VALUED)
+    roles: list[ScimMultiValue] = Field(default_factory=list, max_length=MAX_MULTI_VALUED)
+
+
+#: A patch ``path`` is looked up and, when this resource does not model it,
+#: dropped — so its length bounds nothing that gets stored, and a cap tight
+#: enough to refuse a real one only turns a routine push into a ``400``. The
+#: schema-qualified spellings identity providers send are long:
+#: ``urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.displayName``
+#: is 78 characters, and vendors mint longer custom schema URNs. This matches
+#: ``externalId``'s cap, which is the widest opaque string on the resource;
+#: with ``MAX_PATCH_OPERATIONS`` it stays an order of magnitude inside the body
+#: bound, which is the bound that actually protects this endpoint.
+MAX_PATCH_PATH_LENGTH = 512
+
+
+class ScimPatchOperation(ScimModel):
+    op: str = Field(max_length=16)
+    path: str | None = Field(default=None, max_length=MAX_PATCH_PATH_LENGTH)
+    value: Any = None
+
+
+class ScimPatchRequest(ScimModel):
+    schemas: list[str] = Field(default_factory=list, max_length=MAX_MULTI_VALUED)
+    operations: list[ScimPatchOperation] = Field(
+        default_factory=list, alias="Operations", max_length=MAX_PATCH_OPERATIONS
+    )
+
+
+class ScimTokenResponse(DashboardModel):
+    """A token row as the dashboard sees it: never the secret, only its head."""
+
+    id: str
+    label: str
+    token_prefix: str
+    created_at: datetime
+    created_by_user_id: str | None = None
+    last_used_at: datetime | None = None
+    rotated_at: datetime | None = None
+
+
+class ScimTokenIssuedResponse(DashboardModel):
+    """The one and only response that carries a plaintext token."""
+
+    token: ScimTokenResponse
+    #: Shown once. Never listed, never logged, never audited, never returned again.
+    secret: str
+
+
+class ScimTokenListResponse(DashboardModel):
+    tokens: list[ScimTokenResponse]
+    #: Where the identity provider points its SCIM connector.
+    base_path: str
+
+
+class ScimTokenCreateRequest(DashboardModel):
+    #: ``str_strip_whitespace`` so the value the length bounds are checked
+    #: against is the value that gets stored: trimming after validation would
+    #: let ``"   "`` past ``min_length`` and store an unnamed credential.
+    model_config = ConfigDict(extra="forbid", populate_by_name=True, str_strip_whitespace=True)
+
+    label: str = Field(min_length=1, max_length=64)