intflow-authctl 0.1.8__py3-none-any.whl

intflow_auth/__init__.py

@@ -0,0 +1,3 @@
+"""Intflow Auth application package."""
+
+__version__ = "0.1.8"

intflow_auth/admin_auth.py

@@ -0,0 +1,512 @@
+"""Admin session authorization guard."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from fastapi import HTTPException, Request, status
+
+from intflow_auth.api.rate_limits import client_ip_subject, enforce_rate_limit
+from intflow_auth.audit import (
+    AuditEventInput,
+    AuditEventType,
+    AuditResult,
+    write_audit_event,
+)
+from intflow_auth.config import Settings
+from intflow_auth.operator_admin_tokens import (
+    OperatorAdminTokenRecord,
+    OperatorAdminTokenStatus,
+    OperatorAdminTokenStore,
+    hash_operator_admin_token,
+    mark_operator_admin_token_expired,
+    mark_operator_admin_token_used,
+    operator_admin_token_is_expired,
+)
+from intflow_auth.roles import (
+    RoleName,
+    has_admin_access,
+)
+from intflow_auth.sessions import (
+    SESSION_COOKIE_NAME,
+    SessionError,
+    SessionRecord,
+    validate_session_token,
+)
+from intflow_auth.store_resolver import (
+    client_ip as _client_ip,
+)
+from intflow_auth.store_resolver import (
+    get_audit_writer as _get_audit_writer,
+)
+from intflow_auth.store_resolver import (
+    get_operator_admin_token_store as _get_operator_admin_token_store,
+)
+from intflow_auth.store_resolver import (
+    get_request_settings as _get_settings,
+)
+from intflow_auth.store_resolver import (
+    get_role_assignment_store as _get_role_assignment_store,
+)
+from intflow_auth.store_resolver import (
+    get_session_store as _get_session_store,
+)
+from intflow_auth.store_resolver import (
+    get_user_identity_store as _get_user_identity_store,
+)
+from intflow_auth.usage_metadata import usage_metadata_update_due
+from intflow_auth.users import (
+    UserRecord,
+    UserStatus,
+)
+
+PRIMARY_OPERATOR_ADMIN_TOKEN_PEPPER_SOURCE = "operator_admin_token_pepper"
+LEGACY_REFRESH_TOKEN_PEPPER_SOURCE = "legacy_refresh_token_pepper"
+
+
+@dataclass(frozen=True, slots=True)
+class AdminSessionContext:
+    """Authorized admin request context."""
+
+    session: SessionRecord
+    user: UserRecord
+    roles: tuple[RoleName, ...]
+
+
+class AdminActorCredentialType(StrEnum):
+    """Supported admin authentication credential types."""
+
+    SESSION = "session"
+    OPERATOR_ADMIN_TOKEN = "operator_admin_token"
+
+
+@dataclass(frozen=True, slots=True)
+class AdminActorContext:
+    """Authorized admin actor context."""
+
+    credential_type: AdminActorCredentialType
+    user: UserRecord
+    roles: tuple[RoleName, ...]
+    effective_scopes: tuple[str, ...]
+    session: SessionRecord | None = None
+    operator_admin_token: OperatorAdminTokenRecord | None = None
+
+
+async def require_admin_session(request: Request) -> AdminSessionContext:
+    """Require an authenticated active operator/admin browser session."""
+    settings = _get_settings(request)
+    session_store = _get_session_store(request, settings)
+    token = request.cookies.get(SESSION_COOKIE_NAME)
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required.",
+        )
+
+    try:
+        session = await validate_session_token(session_store, token=token)
+    except SessionError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required.",
+        ) from exc
+
+    user = await _get_user_identity_store(request, settings).get_user(session.user_id)
+    if user is None or user.status is not UserStatus.ACTIVE:
+        await _audit_admin_access_denied(
+            request,
+            settings,
+            actor_user_id=session.user_id,
+            reason="inactive_user",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access denied.",
+        )
+
+    roles = await _get_role_assignment_store(request, settings).get_role_names(user.id)
+    if not has_admin_access(roles):
+        await _audit_admin_access_denied(
+            request,
+            settings,
+            actor_user_id=user.id,
+            reason="missing_privileged_role",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access denied.",
+        )
+
+    return AdminSessionContext(session=session, user=user, roles=roles)
+
+
+async def require_admin_actor(
+    request: Request,
+    *,
+    required_scopes: Sequence[str] = (),
+) -> AdminActorContext:
+    """Require an authorized admin actor from bearer token or browser session."""
+    settings = _get_settings(request)
+    try:
+        bearer_token = _extract_bearer_token(request)
+    except HTTPException:
+        _enforce_operator_admin_token_failure_rate_limits(
+            request,
+            settings,
+            bearer_token=None,
+            increment=True,
+        )
+        raise
+    if bearer_token is not None:
+        return await _require_operator_admin_token(
+            request,
+            settings,
+            bearer_token=bearer_token,
+            required_scopes=required_scopes,
+        )
+
+    session_context = await require_admin_session(request)
+    return AdminActorContext(
+        credential_type=AdminActorCredentialType.SESSION,
+        user=session_context.user,
+        roles=session_context.roles,
+        effective_scopes=("admin:*",),
+        session=session_context.session,
+    )
+
+
+async def _require_operator_admin_token(
+    request: Request,
+    settings: Settings,
+    *,
+    bearer_token: str,
+    required_scopes: Sequence[str],
+) -> AdminActorContext:
+    _enforce_operator_admin_token_failure_rate_limits(
+        request,
+        settings,
+        bearer_token=bearer_token,
+        increment=False,
+    )
+    store = _get_operator_admin_token_store(request, settings)
+    token_record, pepper_source = await _get_operator_admin_token_record(
+        store,
+        bearer_token=bearer_token,
+        settings=settings,
+    )
+    if token_record is None:
+        _enforce_operator_admin_token_failure_rate_limits(
+            request,
+            settings,
+            bearer_token=bearer_token,
+            increment=True,
+        )
+        await _audit_operator_admin_token_rejected(
+            request,
+            settings,
+            actor_user_id=None,
+            token_record=None,
+            reason="unknown_token",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required.",
+        )
+
+    if token_record.status is not OperatorAdminTokenStatus.ACTIVE:
+        _enforce_operator_admin_token_failure_rate_limits(
+            request,
+            settings,
+            bearer_token=bearer_token,
+            increment=True,
+        )
+        await _audit_operator_admin_token_rejected(
+            request,
+            settings,
+            actor_user_id=token_record.user_id,
+            token_record=token_record,
+            reason=f"token_{token_record.status.value}",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required.",
+        )
+
+    now = _utc_now()
+    if operator_admin_token_is_expired(token_record, now):
+        expired = mark_operator_admin_token_expired(token_record)
+        await store.save(expired)
+        _enforce_operator_admin_token_failure_rate_limits(
+            request,
+            settings,
+            bearer_token=bearer_token,
+            increment=True,
+        )
+        await _audit_operator_admin_token_rejected(
+            request,
+            settings,
+            actor_user_id=token_record.user_id,
+            token_record=expired,
+            reason="token_expired",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required.",
+        )
+
+    user = await _get_user_identity_store(request, settings).get_user(token_record.user_id)
+    if user is None or user.status is not UserStatus.ACTIVE:
+        _enforce_operator_admin_token_failure_rate_limits(
+            request,
+            settings,
+            bearer_token=bearer_token,
+            increment=True,
+        )
+        await _audit_operator_admin_token_rejected(
+            request,
+            settings,
+            actor_user_id=token_record.user_id,
+            token_record=token_record,
+            reason="inactive_user",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access denied.",
+        )
+
+    roles = await _get_role_assignment_store(request, settings).get_role_names(user.id)
+    if not has_admin_access(roles):
+        _enforce_operator_admin_token_failure_rate_limits(
+            request,
+            settings,
+            bearer_token=bearer_token,
+            increment=True,
+        )
+        await _audit_operator_admin_token_rejected(
+            request,
+            settings,
+            actor_user_id=user.id,
+            token_record=token_record,
+            reason="missing_privileged_role",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access denied.",
+        )
+
+    if not _has_required_scopes(token_record.scopes, required_scopes):
+        _enforce_operator_admin_token_failure_rate_limits(
+            request,
+            settings,
+            bearer_token=bearer_token,
+            increment=True,
+        )
+        await _audit_operator_admin_token_rejected(
+            request,
+            settings,
+            actor_user_id=user.id,
+            token_record=token_record,
+            reason="missing_token_scope",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access denied.",
+        )
+
+    used = token_record
+    should_update_usage = usage_metadata_update_due(token_record.last_used_at, now)
+    if should_update_usage or pepper_source == LEGACY_REFRESH_TOKEN_PEPPER_SOURCE:
+        used = mark_operator_admin_token_used(
+            token_record,
+            client_ip=_client_ip(request),
+            clock=lambda: now,
+        )
+        await store.save(used)
+        await _audit_operator_admin_token_used(
+            request,
+            settings,
+            actor_user_id=user.id,
+            token=used,
+            pepper_source=pepper_source,
+        )
+
+    return AdminActorContext(
+        credential_type=AdminActorCredentialType.OPERATOR_ADMIN_TOKEN,
+        user=user,
+        roles=roles,
+        effective_scopes=used.scopes,
+        operator_admin_token=used,
+    )
+
+
+async def _get_operator_admin_token_record(
+    store: OperatorAdminTokenStore,
+    *,
+    bearer_token: str,
+    settings: Settings,
+) -> tuple[OperatorAdminTokenRecord | None, str]:
+    primary_hash = hash_operator_admin_token(
+        bearer_token,
+        pepper=settings.operator_admin_token_pepper,
+    )
+    token_record = await store.get_by_token_hash(primary_hash)
+    if token_record is not None:
+        return token_record, PRIMARY_OPERATOR_ADMIN_TOKEN_PEPPER_SOURCE
+
+    if not settings.operator_admin_token_legacy_refresh_pepper_fallback_enabled:
+        return None, PRIMARY_OPERATOR_ADMIN_TOKEN_PEPPER_SOURCE
+
+    legacy_hash = hash_operator_admin_token(
+        bearer_token,
+        pepper=settings.refresh_token_pepper,
+    )
+    if legacy_hash == primary_hash:
+        return None, PRIMARY_OPERATOR_ADMIN_TOKEN_PEPPER_SOURCE
+
+    token_record = await store.get_by_token_hash(legacy_hash)
+    if token_record is None:
+        return None, PRIMARY_OPERATOR_ADMIN_TOKEN_PEPPER_SOURCE
+    return token_record, LEGACY_REFRESH_TOKEN_PEPPER_SOURCE
+
+
+async def _audit_admin_access_denied(
+    request: Request,
+    settings: Settings,
+    *,
+    actor_user_id: str | None,
+    reason: str,
+) -> None:
+    await write_audit_event(
+        _get_audit_writer(request, settings),
+        AuditEventInput(
+            event_type=AuditEventType.ADMIN_ACCESS_DENIED,
+            result=AuditResult.DENIED,
+            actor_user_id=actor_user_id,
+            client_ip=_client_ip(request),
+            user_agent=request.headers.get("user-agent"),
+            payload={"reason": reason, "path": request.url.path},
+        ),
+        fail_closed=False,
+    )
+
+
+async def _audit_operator_admin_token_used(
+    request: Request,
+    settings: Settings,
+    *,
+    actor_user_id: str,
+    token: OperatorAdminTokenRecord,
+    pepper_source: str,
+) -> None:
+    payload = {
+        "token_id": token.id,
+        "token_fingerprint": token.token_fingerprint,
+        "path": request.url.path,
+    }
+    if pepper_source == LEGACY_REFRESH_TOKEN_PEPPER_SOURCE:
+        payload["legacy_hash_fallback"] = True
+    await write_audit_event(
+        _get_audit_writer(request, settings),
+        AuditEventInput(
+            event_type=AuditEventType.OPERATOR_ADMIN_TOKEN_USED,
+            result=AuditResult.SUCCESS,
+            actor_user_id=actor_user_id,
+            client_ip=_client_ip(request),
+            user_agent=request.headers.get("user-agent"),
+            payload=payload,
+        ),
+        fail_closed=False,
+    )
+
+
+async def _audit_operator_admin_token_rejected(
+    request: Request,
+    settings: Settings,
+    *,
+    actor_user_id: str | None,
+    token_record: OperatorAdminTokenRecord | None,
+    reason: str,
+) -> None:
+    payload: dict[str, object] = {"reason": reason, "path": request.url.path}
+    if token_record is not None:
+        payload["token_id"] = token_record.id
+        payload["token_fingerprint"] = token_record.token_fingerprint
+        payload["token_status"] = token_record.status.value
+    await write_audit_event(
+        _get_audit_writer(request, settings),
+        AuditEventInput(
+            event_type=AuditEventType.OPERATOR_ADMIN_TOKEN_REJECTED,
+            result=AuditResult.DENIED,
+            actor_user_id=actor_user_id,
+            client_ip=_client_ip(request),
+            user_agent=request.headers.get("user-agent"),
+            payload=payload,
+        ),
+        fail_closed=False,
+    )
+
+
+def _extract_bearer_token(request: Request) -> str | None:
+    authorization = request.headers.get("authorization")
+    if authorization is None:
+        return None
+    scheme, separator, credentials = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not separator or not credentials.strip():
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required.",
+        )
+    return credentials.strip()
+
+
+def _enforce_operator_admin_token_failure_rate_limits(
+    request: Request,
+    settings: Settings,
+    *,
+    bearer_token: str | None,
+    increment: bool,
+) -> None:
+    enforce_rate_limit(
+        request,
+        settings,
+        name="admin_bearer_failure_ip",
+        limit=settings.rate_limit_admin_bearer_failure_ip_per_window,
+        subjects=(client_ip_subject(request),),
+        increment=increment,
+    )
+    if bearer_token is None:
+        return
+    enforce_rate_limit(
+        request,
+        settings,
+        name="admin_bearer_failure_token",
+        limit=settings.rate_limit_admin_bearer_failure_token_per_window,
+        subjects=(_operator_admin_token_hash_prefix_subject(settings, bearer_token),),
+        increment=increment,
+    )
+
+
+def _operator_admin_token_hash_prefix_subject(
+    settings: Settings,
+    bearer_token: str,
+) -> str:
+    token_hash = hash_operator_admin_token(
+        bearer_token,
+        pepper=settings.operator_admin_token_pepper,
+    )
+    return f"operator_admin_token_hash_prefix:{token_hash[:16]}"
+
+
+def _has_required_scopes(
+    token_scopes: Sequence[str],
+    required_scopes: Sequence[str],
+) -> bool:
+    if not required_scopes:
+        return True
+    scope_set = set(token_scopes)
+    return "admin:*" in scope_set or all(scope in scope_set for scope in required_scopes)
+
+
+def _utc_now() -> datetime:
+    return datetime.now(UTC)

intflow_auth/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API package."""

intflow_auth/api/admin_app_roles.py

@@ -0,0 +1,197 @@
+"""Admin APIs for application-local role assignments."""
+
+from fastapi import APIRouter, HTTPException, Request, status
+from fastapi.responses import Response
+
+from intflow_auth.admin_auth import AdminActorContext, require_admin_actor
+from intflow_auth.api.dependencies import (
+    client_ip,
+    get_app_role_assignment_store,
+    get_audit_writer,
+    get_oauth_client_store,
+    get_request_settings,
+    get_user_identity_store,
+    require_admin_actor_csrf,
+)
+from intflow_auth.api.pagination import admin_page_request
+from intflow_auth.app_roles import (
+    AppRoleAssignmentError,
+    AppRoleAssignmentRecord,
+    AppRoleName,
+    assign_app_admin,
+    list_client_app_admins_page,
+    remove_app_admin,
+)
+from intflow_auth.audit import (
+    AuditEventInput,
+    AuditEventType,
+    AuditResult,
+    write_audit_event,
+)
+from intflow_auth.config import Settings
+from intflow_auth.pagination import PaginationError
+
+ADMIN_APP_ROLES_READ_SCOPE = "admin:app_roles:read"
+ADMIN_APP_ROLES_WRITE_SCOPE = "admin:app_roles:write"
+
+router = APIRouter(tags=["Admin Clients"])
+
+
+@router.get("/v1/admin/clients/{client_id}/admins")
+async def list_oauth_client_admins(
+    request: Request,
+    client_id: str,
+    limit: int | None = None,
+    cursor: str | None = None,
+) -> dict[str, object]:
+    """List app-admin assignments for one OAuth client."""
+    settings = get_request_settings(request)
+    await require_admin_actor(request, required_scopes=(ADMIN_APP_ROLES_READ_SCOPE,))
+    page_request = admin_page_request(limit=limit, cursor=cursor)
+    try:
+        page = await list_client_app_admins_page(
+            get_app_role_assignment_store(request, settings),
+            get_oauth_client_store(request, settings),
+            client_id=client_id,
+            page=page_request,
+        )
+    except AppRoleAssignmentError as exc:
+        raise _app_role_http_error(exc) from exc
+    except PaginationError as exc:
+        raise _bad_list_request(str(exc)) from exc
+    return {
+        "admins": [_assignment_response(assignment) for assignment in page.items],
+        "next_cursor": page.next_cursor,
+    }
+
+
+@router.put("/v1/admin/clients/{client_id}/admins/{user_id}")
+async def grant_oauth_client_admin(
+    request: Request,
+    client_id: str,
+    user_id: str,
+) -> dict[str, object]:
+    """Grant app-admin assignment for one OAuth client and internal user."""
+    settings = get_request_settings(request)
+    context = await require_admin_actor(
+        request,
+        required_scopes=(ADMIN_APP_ROLES_WRITE_SCOPE,),
+    )
+    require_admin_actor_csrf(context, request, settings)
+    try:
+        assignment, created = await assign_app_admin(
+            get_app_role_assignment_store(request, settings),
+            get_oauth_client_store(request, settings),
+            get_user_identity_store(request, settings),
+            client_id=client_id,
+            user_id=user_id,
+            assigned_by_user_id=context.user.id,
+        )
+    except AppRoleAssignmentError as exc:
+        raise _app_role_http_error(exc) from exc
+    await _audit_app_admin_change(
+        request,
+        settings,
+        context=context,
+        event_type=AuditEventType.APP_ADMIN_ASSIGNED,
+        client_id=client_id,
+        user_id=user_id,
+        changed=created,
+        assignment=assignment,
+    )
+    return {
+        "assignment": _assignment_response(assignment),
+        "created": created,
+    }
+
+
+@router.delete(
+    "/v1/admin/clients/{client_id}/admins/{user_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def revoke_oauth_client_admin(
+    request: Request,
+    client_id: str,
+    user_id: str,
+) -> Response:
+    """Revoke app-admin assignment for one OAuth client and internal user."""
+    settings = get_request_settings(request)
+    context = await require_admin_actor(
+        request,
+        required_scopes=(ADMIN_APP_ROLES_WRITE_SCOPE,),
+    )
+    require_admin_actor_csrf(context, request, settings)
+    try:
+        changed = await remove_app_admin(
+            get_app_role_assignment_store(request, settings),
+            get_oauth_client_store(request, settings),
+            get_user_identity_store(request, settings),
+            client_id=client_id,
+            user_id=user_id,
+        )
+    except AppRoleAssignmentError as exc:
+        raise _app_role_http_error(exc) from exc
+    await _audit_app_admin_change(
+        request,
+        settings,
+        context=context,
+        event_type=AuditEventType.APP_ADMIN_REMOVED,
+        client_id=client_id,
+        user_id=user_id,
+        changed=changed,
+    )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+def _assignment_response(assignment: AppRoleAssignmentRecord) -> dict[str, object]:
+    return {
+        "id": assignment.id,
+        "client_id": assignment.client_id,
+        "user_id": assignment.user_id,
+        "role_name": assignment.role_name.value,
+        "assigned_by_user_id": assignment.assigned_by_user_id,
+        "assigned_at": assignment.assigned_at,
+    }
+
+
+def _app_role_http_error(exc: AppRoleAssignmentError) -> HTTPException:
+    detail = str(exc)
+    if "not found" in detail:
+        return HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=detail)
+    return HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=detail)
+
+
+def _bad_list_request(detail: str) -> HTTPException:
+    return HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail)
+
+
+async def _audit_app_admin_change(
+    request: Request,
+    settings: Settings,
+    *,
+    context: AdminActorContext,
+    event_type: AuditEventType,
+    client_id: str,
+    user_id: str,
+    changed: bool,
+    assignment: AppRoleAssignmentRecord | None = None,
+) -> None:
+    payload: dict[str, object] = {
+        "role_name": AppRoleName.ADMIN.value,
+        "changed": changed,
+    }
+    if assignment is not None:
+        payload["assignment_id"] = assignment.id
+    await write_audit_event(
+        get_audit_writer(request, settings),
+        AuditEventInput(
+            event_type=event_type,
+            result=AuditResult.SUCCESS,
+            actor_user_id=context.user.id,
+            target_user_id=user_id,
+            client_id=client_id,
+            client_ip=client_ip(request),
+            user_agent=request.headers.get("user-agent"),
+            payload=payload,
+        ),
+    )