Swagger Guide

@v1.api_route(    "/Users/{user_id}/policy-approval",    methods=["PATCH"],    tags=["Registration & Approval"],    summary="Admin approval: activate a pending user",    description=(        "Promote a pending user to an active role, optionally scoping them to "        "a Network. Covers both local self-registration (POST /Register) and "        "OIDC JIT-provisioned signups. The role is a plain UPDATE (RLS is "        "enforced by the static policies in 006_session_scoped_rls_policies.sql); "        "dataset, if given, is written to User.dataset_id and must match an "        "existing Network. Records an ADMIN_APPROVAL audit event in the same "        "transaction. Restricted to administrators; the target user must be "        "in the 'pending' state."    ),    status_code=status.HTTP_200_OK,    responses=merge(        {            200: response(                ApprovalResponse,                "Approved. The role change, the optional network scope, and "                "the ADMIN_APPROVAL audit event are all written in one "                "transaction.",                {                    "message": "User 'jdoe' (id=42) has been approved with role 'viewer'.",                    "user_id": 42,                    "granted_role": "viewer",                    "dataset_id": "IDROLOGIA",                },            )        },        UNAUTHORIZED,        {            # A second, differently-shaped 403 exists deeper in this            # handler for a PostgreSQL-privilege failure            # ({"message": "Insufficient database privileges."}) -- far            # rarer than this one, so it's not the documented example, but            # be aware both are possible on this code.            403: FORBIDDEN_ADMIN[403],        },        NOT_FOUND_PENDING_USER,        BAD_REQUEST_REJECTED,        DB_UNAVAILABLE,        DB_TIMEOUT,        INTERNAL,    ),)async def patch_policy_approval(    user_id: int,    request: AdminApprovalRequest,    current_user=Depends(get_current_user),):    # ------------------------------------------------------------------    # 1. Authorization: only administrators may approve pending users.    # ------------------------------------------------------------------    if current_user["role"] != "administrator":        raise HTTPException(            status_code=status.HTTP_403_FORBIDDEN,            detail="Forbidden: Administrator access required",        )     # ------------------------------------------------------------------    # 2. Acquire write pool connection and run all mutations atomically.    # ------------------------------------------------------------------    try:        write_pool = await get_pool_w() if POSTGRES_PORT_WRITE else await get_pool()         async with write_pool.acquire() as conn:            async with conn.transaction():                 # ------------------------------------------------------                # 2a. Fetch the target user's username and status.                #     We need the username to construct the RLS policy                #     name and pass as the first argument to the policy                #     function. status is checked separately below —                #     rejection is a status transition, not a role                #     change, so a rejected user still has role='pending'                #     and would otherwise still match the UPDATE's                #     WHERE clause in step 2b.                # ------------------------------------------------------                username_row = await conn.fetchrow(                    """                    SELECT username, status, requested_role, dataset_id,                        auth_provider                    FROM sensorthings."User"                    WHERE id = $1                    """,                    user_id,                )                 if username_row is None:                    raise HTTPException(                        status_code=status.HTTP_404_NOT_FOUND,                        detail="User not found or not in pending state",                    )                 if username_row["status"] == "rejected":                    raise HTTPException(                        status_code=status.HTTP_400_BAD_REQUEST,                        detail=(                            "This user's registration was rejected and "                            "cannot be approved directly. They must "                            "re-apply via POST /Register first."                        ),                    )                 username: str = username_row["username"]                 # request.role is the administrator's explicit choice and                # always wins; omitting it falls back to what the                # applicant themselves asked for at registration or OIDC                # login. Both missing means there is nothing to approve                # into.                target_role = request.role or username_row["requested_role"]                if target_role is None:                    raise HTTPException(                        status_code=status.HTTP_400_BAD_REQUEST,                        detail=(                            f"User '{username}' did not request a role at "                            "registration, so role must be specified "                            "explicitly."                        ),                    )                 # ------------------------------------------------------                # 2b. UPDATE the User row — role + status.                #     The WHERE clause includes role = 'pending' so we                #     only activate genuinely pending users; RETURNING id                #     confirms a row was touched.                # ------------------------------------------------------                updated_row = await conn.fetchrow(                    """                    UPDATE sensorthings."User"                    SET role   = $1,                        status = 'active'                    WHERE id   = $2                      AND role = 'pending'                    RETURNING id                    """,                    target_role,                    user_id,                )                 if updated_row is None:                    raise HTTPException(                        status_code=status.HTTP_404_NOT_FOUND,                        detail="User not found or not in pending state",                    )                 # ------------------------------------------------------                # 2c. Network scope. The role UPDATE above is the entire                #     capability grant (enforced by the static policies in                #     006_session_scoped_rls_policies.sql). This step only                #     sets *which rows* the user may touch, by writing a                #     Network name to User.dataset_id.                #                #     request.dataset: None  -> leave the applicant's                #       requested value unchanged.                #                     ""    -> clear any scope.                #                     name  -> must match a Network.                # ------------------------------------------------------                # With NETWORK=0 there are no Networks, so a requested scope is ignored.                granted_dataset_id = username_row["dataset_id"] if NETWORK else None                if NETWORK and request.dataset is not None:                    new_scope = request.dataset.strip() or None                    if new_scope is not None and NETWORK:                        exists = await conn.fetchval(                            'SELECT 1 FROM sensorthings."Network" WHERE name = $1',                            new_scope,                        )                        if not exists:                            raise HTTPException(                                status_code=status.HTTP_400_BAD_REQUEST,                                detail=(                                    f"No Network named '{new_scope}'. "                                    "dataset must match an existing Network."                                ),                            )                    await conn.execute(                        'UPDATE sensorthings."User" SET dataset_id = $1 WHERE id = $2',                        new_scope,                        user_id,                    )                    granted_dataset_id = new_scope                 # ------------------------------------------------------                # 2d. Append an ADMIN_APPROVAL record to the AuditLog.                #     Same connection / same transaction → atomic with                #     the UPDATE above.                # ------------------------------------------------------                await log_audit_event(                    conn=conn,                    action_type=AUDIT_ACTION_ADMIN_APPROVAL,                    actor_id=current_user["id"],                    dataset_id=granted_dataset_id,                    payload={                        "approved_user_id": user_id,                        "granted_role": target_role,                        "auth_provider": username_row["auth_provider"],                    },                )         logger.info(            "Admin approval: user '%s' (id=%d) granted role '%s' "            "scoped to '%s' by admin id=%d.",            username,            user_id,            target_role,            granted_dataset_id,            current_user["id"],        )         return JSONResponse(            status_code=status.HTTP_200_OK,            content={                "message": (                    f"User '{username}' (id={user_id}) has been approved "                    f"with role '{target_role}'."                ),                "user_id": user_id,                "granted_role": target_role,                "dataset_id": granted_dataset_id,            },        )     except HTTPException:        # Re-raise HTTPExceptions raised inside the transaction block        # (404s) without wrapping them in a 500.        raise    except InsufficientPrivilegeError:        return JSONResponse(            status_code=status.HTTP_403_FORBIDDEN,            content={"message": "Insufficient database privileges."},        )    except (PostgresConnectionError, TooManyConnectionsError):        logger.exception("Database unavailable during admin approval")        return JSONResponse(            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,            content={"message": "Database temporarily unavailable."},        )    except QueryCanceledError:        logger.exception("Database timeout during admin approval")        return JSONResponse(            status_code=status.HTTP_504_GATEWAY_TIMEOUT,            content={"message": "Database request timed out."},        )    except Exception:        logger.exception("Unexpected error during admin approval")        return JSONResponse(            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,            content={"message": "Internal server error."},        )

"""Pydantic schemas for PATCH /Users/{user_id}/policy-approval. Design decisions----------------* ``role`` is validated via ``validate_rbac_role`` at model instantiation  time (field_validator), so the endpoint handler never receives an  unknown or internal role (e.g. 'pending', 'administrator'). Named  ``role`` -- not ``assigned_role`` -- to match the other two  administrator-facing role-grant endpoints (POST /Users,  PATCH /Users/{id}/role); ``POST /Register``'s ``requested_role`` stays  a different name on purpose, since it means something different (an  applicant's stated preference, not a grant). * ``dataset`` is a plain string (a Network name), named to match  PATCH /Users/{id}/role's field of the same name. The model does not  validate it; the endpoint handler checks it against the Network table  before writing it to ``User.dataset_id``. * The model intentionally carries no auth context; the endpoint handler  enforces the administrator check via Depends(get_current_user). * This endpoint used to have a sibling, POST /Users/{id}/activate, built  independently five weeks earlier for OIDC signups and doing the same  "promote a pending user" job under different field names  (``role``/``dataset`` there vs. ``assigned_role``/``dataset_id`` here).  The two had already drifted (one logged ``auth_provider`` in its audit  event, the other didn't). ``activate`` has been removed; this endpoint  now covers both the local-registration and OIDC-signup approval paths,  under the field names that were already used by two of the three  admin-role-grant endpoints.""" from pydantic import BaseModel, ConfigDict, Field, field_validator from app.rbac_roles import ASSIGNABLE_ROLES, validate_rbac_role  class AdminApprovalRequest(BaseModel):    """Request body for PATCH /Users/{user_id}/policy-approval.     Fields    ------    role:       The application-layer RBAC role to grant to the target                user.  Optional -- if omitted, the endpoint falls back                to the ``requested_role`` the applicant stated at                registration or OIDC login (see register_request.py,                oidc_login.py). Supplying a value here always overrides                that default; the administrator is the final gatekeeper                either way. Must be one of the assignable roles defined                in ``VALID_RBAC_ROLES`` (viewer, editor, obs_manager,                sensor, qc, custom) if given.  The internal 'pending'                state and 'administrator' may NOT be set through this                endpoint.    dataset:    Name of the Network to scope the user to. Optional --                omit for unrestricted access, or to keep whatever the                applicant requested. Written to User.dataset_id and                forwarded to AuditLog. Must match an existing Network.    """     model_config = ConfigDict(        json_schema_extra={            "examples": [                {                    "role": "viewer",                    "dataset": "IDROLOGIA",                }            ]        }    )     role: str | None = Field(        default=None,        description=(            "RBAC role to grant. Omit to approve with the role the "            "applicant requested at registration or OIDC login. "            "`administrator` and `pending` are rejected -- see the "            "model docstring."        ),        examples=["viewer"],        # See app/models/role.py for why this is json_schema_extra and not        # a Literal/Enum type: the validator normalises with        # .strip().lower() after Pydantic's own coercion, and an enum type        # would reject non-canonical casing before that ever runs.        json_schema_extra={"enum": ASSIGNABLE_ROLES},    )    dataset: str | None = Field(        default=None,        description=(            "Name of the Network to scope this user to. Omit to leave the "            "applicant's requested value unchanged, or send an empty string "            "to clear any scope. Must match an existing Network. Ignored "            "when the deployment runs with NETWORK=0."        ),        examples=["IDROLOGIA"],    )     @field_validator("role")    @classmethod    def role_must_be_valid(cls, v: str | None) -> str | None:        """Pass the value through validate_rbac_role, unless omitted.         None means "use the applicant's requested_role" -- resolved by the        endpoint handler, which has the DB row this model doesn't. Only a        supplied value is validated here.         Raises ``ValueError`` (which Pydantic converts to a 422 response)        if the role is not one of the permitted assignable roles.        """        if v is None:            return None        return validate_rbac_role(v)  class ApprovalResponse(BaseModel):    """Documentation-only: the body PATCH .../policy-approval returns on    success. Built as a plain dict in the handler -- see app/models/error.py."""     message: str = Field(examples=["User 'jdoe' (id=42) has been approved with role 'viewer'."])    user_id: int = Field(examples=[42])    granted_role: str = Field(examples=["viewer"])    dataset_id: str | None = Field(default=None, examples=["IDROLOGIA"])

"""DELETE /Users — Deactivate a user (never a hard delete). Why deactivate instead of delete---------------------------------A real DELETE FROM sensorthings."User" fails unconditionally, for everycaller, including a true PostgreSQL superuser: AuditLog_actor_id_fkey isON DELETE SET NULL, and Postgres runs that enforcement trigger with the*referenced table's owner* privileges (both User and AuditLog are ownedby "administrator"), not the caller's. administrator was deliberatelynever granted UPDATE on AuditLog, since it's meant to be genuinelyappend-only. Loosening that guarantee just to make DELETE work wasconsidered and rejected -- the audit trail staying provably untouchable,even by an administrator, is the more important property to keep. This endpoint sets sensorthings."User".status = 'deleted' instead. Therow, and every AuditLog entry that references it, is left alone.DELETED_STATUS is enforced at the auth layer (see app/oauth.py:authenticate_user, get_current_user) -- checked live on every request,the same way role already is, so a deactivated user's still-valid JWTstops working on its very next use with no token revocation step needed. What this endpoint deliberately no longer does------------------------------------------------The previous hard-delete implementation also dropped per-user RLSpolicies and ran DROP ROLE. Neither is needed now: a deactivated user isrejected at the auth layer before any query runs, so a stale custompolicy naming them is harmless, and there is no per-user PostgreSQL roleto drop (the backend connects as one service account -- seeupdate/admin_approval.py's architecture note).""" from app import POSTGRES_PORT_WRITEfrom app.db.asyncpg_db import get_pool, get_pool_wfrom app.oauth import get_current_userfrom app.rbac_roles import DELETED_STATUSfrom app.v1.endpoints.functions import set_rolefrom asyncpg.exceptions import InsufficientPrivilegeErrorfrom fastapi import APIRouter, Depends, statusfrom fastapi.responses import JSONResponse, Response v1 = APIRouter()  @v1.api_route(    "/Users/{user_id}",    methods=["DELETE"],    tags=["Users"],    summary="Deactivate a User",    description=(        "Deactivates the given user, identified by id -- consistent with "        "every other /Users endpoint. The account and every audit-log "        "entry that references it are preserved, never physically "        "deleted. A deactivated account can no longer authenticate, "        "immediately: role and status are both checked live on every "        "request, so an already-issued token stops working on its next "        "use. The username stays permanently reserved (POST /Register "        "with the same username still returns 409)."    ),    status_code=status.HTTP_200_OK,    responses={        200: {"description": "Deactivated. Response body is empty."},        400: {            "description": "An attempt to deactivate the currently authenticated account.",            "content": {                "application/json": {                    "example": {                        "code": 400,                        "type": "error",                        "message": "Deactivating the currently authenticated user is not allowed.",                    }                }            },        },        403: {            "description": "The caller is not an administrator.",            "content": {"application/json": {"example": {"message": "Insufficient privileges"}}},        },        404: {            "description": "No user exists with that id.",            "content": {"application/json": {"example": {"code": 404, "type": "error", "message": "User not found"}}},        },        409: {            "description": "The user is already deactivated.",            "content": {                "application/json": {                    "example": {                        "code": 409,                        "type": "error",                        "message": "User 'jdoe' is already deactivated.",                    }                }            },        },        500: {            "description": "Unexpected error during deactivation.",            "content": {                "application/json": {                    "example": {"code": 500, "type": "error", "message": "Unexpected error while deactivating user"}                }            },        },    },)async def delete_user(    user_id: int,    current_user=Depends(get_current_user),    pool=Depends(get_pool_w) if POSTGRES_PORT_WRITE else Depends(get_pool),):    try:        async with pool.acquire() as connection:            async with connection.transaction():                if current_user is not None:                    if current_user["role"] != "administrator":                        raise InsufficientPrivilegeError                     await set_role(connection, current_user)                 # Check the user exists, and isn't already deactivated,                # before attempting the update.                row = await connection.fetchrow(                    """                    SELECT username, status FROM sensorthings."User"                    WHERE id = $1;                    """,                    user_id,                )                 if row is None:                    return JSONResponse(                        status_code=status.HTTP_404_NOT_FOUND,                        content={                            "code": 404,                            "type": "error",                            "message": "User not found",                        },                    )                 # Prevent authenticated administrators from deactivating                # themselves. Checked here, after the row is fetched, so                # it can compare by id (what current_user carries) rather                # than needing a second lookup by username.                if current_user is not None and current_user["id"] == user_id:                    return JSONResponse(                        status_code=status.HTTP_400_BAD_REQUEST,                        content={                            "code": 400,                            "type": "error",                            "message": "Deactivating the currently authenticated user is not allowed.",                        },                    )                 if row["status"] == DELETED_STATUS:                    return JSONResponse(                        status_code=status.HTTP_409_CONFLICT,                        content={                            "code": 409,                            "type": "error",                            "message": f"User '{row['username']}' is already deactivated.",                        },                    )                 await connection.execute(                    """                    UPDATE sensorthings."User"                    SET status = $1                    WHERE id = $2;                    """,                    DELETED_STATUS,                    user_id,                )         return Response(status_code=status.HTTP_200_OK)     except InsufficientPrivilegeError:        return JSONResponse(            status_code=status.HTTP_403_FORBIDDEN,            content={"message": "Insufficient privileges"},        )    except Exception:        return JSONResponse(            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,            content={                "code": 500,                "type": "error",                "message": "Unexpected error while deactivating user",            },        )

def test_deactivated_user_existing_jwt_is_rejected_on_next_use():    """The no-revocation-needed claim: a JWT minted *before* deactivation    (exactly like one a user already has sitting in a browser) must stop    working on its very next use, with nothing done to the token itself --    role/status are re-checked live against the database, not trusted from    the token's own claims. Commits for the same cross-connection-    visibility reason as the password test above.    """     async def _run():        username = f"{_MARKER}_carol"        setup_conn = await _connect_or_skip()        try:            await set_role(setup_conn, {"role": "administrator"})            await setup_conn.execute(                """                INSERT INTO sensorthings."User" (username, role, status)                VALUES ($1, 'viewer', 'active');                """,                username,            )        finally:            await setup_conn.close()         try:            await _reset_shared_pool()             # Mint a token the same way /Login does, while still active.            token, _ = create_access_token(data={"sub": username, "role": "viewer"})             # Confirm it works BEFORE deactivation -- otherwise a failure            # below wouldn't prove anything about deactivation            # specifically.            user = await get_current_user(token=token)            assert user["username"] == username             deactivate_conn = await _connect_or_skip()            try:                await set_role(deactivate_conn, {"role": "administrator"})                await deactivate_conn.execute(                    """                    UPDATE sensorthings."User" SET status = $1                    WHERE username = $2;                    """,                    DELETED_STATUS,                    username,                )            finally:                await deactivate_conn.close()             # Same token, no re-issue, no revocation call -- must now be            # rejected with 403.            with pytest.raises(Exception) as exc_info:                await get_current_user(token=token)            assert getattr(exc_info.value, "status_code", None) == 403        finally:            await _cleanup_committed_user(username)     asyncio.run(_run())  # ---------------------------------------------------------------------------# Handler-level tests (mocked connection, matching test_policy_role_switch.py)# ---------------------------------------------------------------------------  def _mock_pgpool(connection):    @asynccontextmanager    async def acquire_cm():        yield connection     class _Pool:        def acquire(self):            return acquire_cm()     return _Pool()  def _attach_transaction_cm(connection):    @asynccontextmanager    async def tx():        yield     connection.transaction = tx  

def test_delete_user_issues_update_not_delete():    """Confirms the handler's actual SQL shape: an UPDATE ... SET status,    never a DELETE or DROP ROLE, and that set_role() ran first (same    privileged-write pattern every other admin mutation in this codebase    uses).    """    connection = AsyncMock()    connection.execute = AsyncMock()    connection.fetchrow = AsyncMock(        return_value={"username": "targetuser", "status": "active"}    )    _attach_transaction_cm(connection)    current_user = {"id": 1, "username": "admin_user", "role": "administrator"}     response = asyncio.run(        delete_user_endpoint.delete_user(            user_id=2,            current_user=current_user,            pool=_mock_pgpool(connection),        )    )     sql_calls = [c.args[0] for c in connection.execute.await_args_list]    assert any('SET LOCAL ROLE "administrator";' in sql for sql in sql_calls)    assert any(        "UPDATE" in sql and "sensorthings" in sql and '"User"' in sql        for sql in sql_calls    )    assert not any("DELETE FROM" in sql for sql in sql_calls)    assert not any("DROP ROLE" in sql for sql in sql_calls)    assert response.status_code == 200

@v1.api_route(    "/Users/{user_id}/policy-approval",    methods=["PATCH"],    tags=["Registration & Approval"],    summary="Admin approval: activate a pending user",    description=(        "Promote a pending user to an active role, optionally scoping them to "        "a Network. Covers both local self-registration (POST /Register) and "        "OIDC JIT-provisioned signups. The role is a plain UPDATE (RLS is "        "enforced by the static policies in 006_session_scoped_rls_policies.sql); "        "dataset, if given, is written to User.dataset_id and must match an "        "existing Network. Records an ADMIN_APPROVAL audit event in the same "        "transaction. Restricted to administrators; the target user must be "        "in the 'pending' state."    ),    status_code=status.HTTP_200_OK,    responses=merge(        {            200: response(                ApprovalResponse,                "Approved. The role change, the optional network scope, and "                "the ADMIN_APPROVAL audit event are all written in one "                "transaction.",                {                    "message": "User 'jdoe' (id=42) has been approved with role 'viewer'.",                    "user_id": 42,                    "granted_role": "viewer",                    "dataset_id": "IDROLOGIA",                },            )        },        UNAUTHORIZED,        {            # A second, differently-shaped 403 exists deeper in this            # handler for a PostgreSQL-privilege failure            # ({"message": "Insufficient database privileges."}) -- far            # rarer than this one, so it's not the documented example, but            # be aware both are possible on this code.            403: FORBIDDEN_ADMIN[403],        },        NOT_FOUND_PENDING_USER,        BAD_REQUEST_REJECTED,        DB_UNAVAILABLE,        DB_TIMEOUT,        INTERNAL,    ),)async def patch_policy_approval(    user_id: int,    request: AdminApprovalRequest,    current_user=Depends(get_current_user),):    # ------------------------------------------------------------------    # 1. Authorization: only administrators may approve pending users.    # ------------------------------------------------------------------    if current_user["role"] != "administrator":        raise HTTPException(            status_code=status.HTTP_403_FORBIDDEN,            detail="Forbidden: Administrator access required",        )     # ------------------------------------------------------------------    # 2. Acquire write pool connection and run all mutations atomically.    # ------------------------------------------------------------------    try:        write_pool = await get_pool_w() if POSTGRES_PORT_WRITE else await get_pool()         async with write_pool.acquire() as conn:            async with conn.transaction():                 # ------------------------------------------------------                # 2a. Fetch the target user's username and status.                #     We need the username to construct the RLS policy                #     name and pass as the first argument to the policy                #     function. status is checked separately below —                #     rejection is a status transition, not a role                #     change, so a rejected user still has role='pending'                #     and would otherwise still match the UPDATE's                #     WHERE clause in step 2b.                # ------------------------------------------------------                username_row = await conn.fetchrow(                    """                    SELECT username, status, requested_role, dataset_id,                        auth_provider                    FROM sensorthings."User"                    WHERE id = $1                    """,                    user_id,                )                 if username_row is None:                    raise HTTPException(                        status_code=status.HTTP_404_NOT_FOUND,                        detail="User not found or not in pending state",                    )                 if username_row["status"] == "rejected":                    raise HTTPException(                        status_code=status.HTTP_400_BAD_REQUEST,                        detail=(                            "This user's registration was rejected and "                            "cannot be approved directly. They must "                            "re-apply via POST /Register first."                        ),                    )                 username: str = username_row["username"]                 # request.role is the administrator's explicit choice and                # always wins; omitting it falls back to what the                # applicant themselves asked for at registration or OIDC                # login. Both missing means there is nothing to approve                # into.                target_role = request.role or username_row["requested_role"]                if target_role is None:                    raise HTTPException(                        status_code=status.HTTP_400_BAD_REQUEST,                        detail=(                            f"User '{username}' did not request a role at "                            "registration, so role must be specified "                            "explicitly."                        ),                    )                 # ------------------------------------------------------                # 2b. UPDATE the User row — role + status.                #     The WHERE clause includes role = 'pending' so we                #     only activate genuinely pending users; RETURNING id                #     confirms a row was touched.                # ------------------------------------------------------                updated_row = await conn.fetchrow(                    """                    UPDATE sensorthings."User"                    SET role   = $1,                        status = 'active'                    WHERE id   = $2                      AND role = 'pending'                    RETURNING id                    """,                    target_role,                    user_id,                )                 if updated_row is None:                    raise HTTPException(                        status_code=status.HTTP_404_NOT_FOUND,                        detail="User not found or not in pending state",                    )                 # ------------------------------------------------------                # 2c. Network scope. The role UPDATE above is the entire                #     capability grant (enforced by the static policies in                #     006_session_scoped_rls_policies.sql). This step only                #     sets *which rows* the user may touch, by writing a                #     Network name to User.dataset_id.                #                #     request.dataset: None  -> leave the applicant's                #       requested value unchanged.                #                     ""    -> clear any scope.                #                     name  -> must match a Network.                # ------------------------------------------------------                # With NETWORK=0 there are no Networks, so a requested scope is ignored.                granted_dataset_id = username_row["dataset_id"] if NETWORK else None                if NETWORK and request.dataset is not None:                    new_scope = request.dataset.strip() or None                    if new_scope is not None and NETWORK:                        exists = await conn.fetchval(                            'SELECT 1 FROM sensorthings."Network" WHERE name = $1',                            new_scope,                        )                        if not exists:                            raise HTTPException(                                status_code=status.HTTP_400_BAD_REQUEST,                                detail=(                                    f"No Network named '{new_scope}'. "                                    "dataset must match an existing Network."                                ),                            )                    await conn.execute(                        'UPDATE sensorthings."User" SET dataset_id = $1 WHERE id = $2',                        new_scope,                        user_id,                    )                    granted_dataset_id = new_scope                 # ------------------------------------------------------                # 2d. Append an ADMIN_APPROVAL record to the AuditLog.                #     Same connection / same transaction → atomic with                #     the UPDATE above.                # ------------------------------------------------------                await log_audit_event(                    conn=conn,                    action_type=AUDIT_ACTION_ADMIN_APPROVAL,                    actor_id=current_user["id"],                    dataset_id=granted_dataset_id,                    payload={                        "approved_user_id": user_id,                        "granted_role": target_role,                        "auth_provider": username_row["auth_provider"],                    },                )         logger.info(            "Admin approval: user '%s' (id=%d) granted role '%s' "            "scoped to '%s' by admin id=%d.",            username,            user_id,            target_role,            granted_dataset_id,            current_user["id"],        )         return JSONResponse(            status_code=status.HTTP_200_OK,            content={                "message": (                    f"User '{username}' (id={user_id}) has been approved "                    f"with role '{target_role}'."                ),                "user_id": user_id,                "granted_role": target_role,                "dataset_id": granted_dataset_id,            },        )     except HTTPException:        # Re-raise HTTPExceptions raised inside the transaction block        # (404s) without wrapping them in a 500.        raise    except InsufficientPrivilegeError:        return JSONResponse(            status_code=status.HTTP_403_FORBIDDEN,            content={"message": "Insufficient database privileges."},        )    except (PostgresConnectionError, TooManyConnectionsError):        logger.exception("Database unavailable during admin approval")        return JSONResponse(            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,            content={"message": "Database temporarily unavailable."},        )    except QueryCanceledError:        logger.exception("Database timeout during admin approval")        return JSONResponse(            status_code=status.HTTP_504_GATEWAY_TIMEOUT,            content={"message": "Database request timed out."},        )    except Exception:        logger.exception("Unexpected error during admin approval")        return JSONResponse(            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,            content={"message": "Internal server error."},        )

"""Pydantic schemas for PATCH /Users/{user_id}/policy-approval. Design decisions----------------* ``role`` is validated via ``validate_rbac_role`` at model instantiation  time (field_validator), so the endpoint handler never receives an  unknown or internal role (e.g. 'pending', 'administrator'). Named  ``role`` -- not ``assigned_role`` -- to match the other two  administrator-facing role-grant endpoints (POST /Users,  PATCH /Users/{id}/role); ``POST /Register``'s ``requested_role`` stays  a different name on purpose, since it means something different (an  applicant's stated preference, not a grant). * ``dataset`` is a plain string (a Network name), named to match  PATCH /Users/{id}/role's field of the same name. The model does not  validate it; the endpoint handler checks it against the Network table  before writing it to ``User.dataset_id``. * The model intentionally carries no auth context; the endpoint handler  enforces the administrator check via Depends(get_current_user). * This endpoint used to have a sibling, POST /Users/{id}/activate, built  independently five weeks earlier for OIDC signups and doing the same  "promote a pending user" job under different field names  (``role``/``dataset`` there vs. ``assigned_role``/``dataset_id`` here).  The two had already drifted (one logged ``auth_provider`` in its audit  event, the other didn't). ``activate`` has been removed; this endpoint  now covers both the local-registration and OIDC-signup approval paths,  under the field names that were already used by two of the three  admin-role-grant endpoints.""" from pydantic import BaseModel, ConfigDict, Field, field_validator from app.rbac_roles import ASSIGNABLE_ROLES, validate_rbac_role  class AdminApprovalRequest(BaseModel):    """Request body for PATCH /Users/{user_id}/policy-approval.     Fields    ------    role:       The application-layer RBAC role to grant to the target                user.  Optional -- if omitted, the endpoint falls back                to the ``requested_role`` the applicant stated at                registration or OIDC login (see register_request.py,                oidc_login.py). Supplying a value here always overrides                that default; the administrator is the final gatekeeper                either way. Must be one of the assignable roles defined                in ``VALID_RBAC_ROLES`` (viewer, editor, obs_manager,                sensor, qc, custom) if given.  The internal 'pending'                state and 'administrator' may NOT be set through this                endpoint.    dataset:    Name of the Network to scope the user to. Optional --                omit for unrestricted access, or to keep whatever the                applicant requested. Written to User.dataset_id and                forwarded to AuditLog. Must match an existing Network.    """     model_config = ConfigDict(        json_schema_extra={            "examples": [                {                    "role": "viewer",                    "dataset": "IDROLOGIA",                }            ]        }    )     role: str | None = Field(        default=None,        description=(            "RBAC role to grant. Omit to approve with the role the "            "applicant requested at registration or OIDC login. "            "`administrator` and `pending` are rejected -- see the "            "model docstring."        ),        examples=["viewer"],        # See app/models/role.py for why this is json_schema_extra and not        # a Literal/Enum type: the validator normalises with        # .strip().lower() after Pydantic's own coercion, and an enum type        # would reject non-canonical casing before that ever runs.        json_schema_extra={"enum": ASSIGNABLE_ROLES},    )    dataset: str | None = Field(        default=None,        description=(            "Name of the Network to scope this user to. Omit to leave the "            "applicant's requested value unchanged, or send an empty string "            "to clear any scope. Must match an existing Network. Ignored "            "when the deployment runs with NETWORK=0."        ),        examples=["IDROLOGIA"],    )     @field_validator("role")    @classmethod    def role_must_be_valid(cls, v: str | None) -> str | None:        """Pass the value through validate_rbac_role, unless omitted.         None means "use the applicant's requested_role" -- resolved by the        endpoint handler, which has the DB row this model doesn't. Only a        supplied value is validated here.         Raises ``ValueError`` (which Pydantic converts to a 422 response)        if the role is not one of the permitted assignable roles.        """        if v is None:            return None        return validate_rbac_role(v)  class ApprovalResponse(BaseModel):    """Documentation-only: the body PATCH .../policy-approval returns on    success. Built as a plain dict in the handler -- see app/models/error.py."""     message: str = Field(examples=["User 'jdoe' (id=42) has been approved with role 'viewer'."])    user_id: int = Field(examples=[42])    granted_role: str = Field(examples=["viewer"])    dataset_id: str | None = Field(default=None, examples=["IDROLOGIA"])

def test_approval_writes_auth_provider_for_oidc_origin():    """The merged endpoint must cover the OIDC JIT-provisioning origin    just as well as local registration -- this is the path that used to    be served by the now-removed POST /Users/{id}/activate."""     async def _run():        connection = await _connect_or_skip()        try:            transaction = connection.transaction()            await transaction.start()            try:                admin_id = await _seed_admin(connection, f"{_MARKER}_admin2")                pending_id = await _seed_pending_user(                    connection, f"{_MARKER}_oidc_user", "google"                )                 response = await _call_policy_approval(                    connection,                    user_id=pending_id,                    request=AdminApprovalRequest(),                    current_user=_admin_current_user(admin_id, f"{_MARKER}_admin2"),                )                assert response.status_code == 200, response.body                 audit_row = await connection.fetchrow(                    """                    SELECT payload FROM sensorthings."AuditLog"                    WHERE action_type = 'ADMIN_APPROVAL'                      AND (payload ->> 'approved_user_id')::bigint = $1                    """,                    pending_id,                )                assert audit_row is not None                payload = json.loads(audit_row["payload"])                assert payload["auth_provider"] == "google"                assert payload["granted_role"] == "viewer"            finally:                await transaction.rollback()        finally:            await connection.close()     asyncio.run(_run())  

@v1.api_route(    "/Users/{user_id}/policy-approval",    methods=["PATCH"],    tags=["Registration & Approval"],    summary="Admin approval: activate a pending user",    description=(        "Promote a pending user to an active role, optionally scoping them to "        "a Network. Covers both local self-registration (POST /Register) and "        "OIDC JIT-provisioned signups. The role is a plain UPDATE (RLS is "        "enforced by the static policies in 006_session_scoped_rls_policies.sql); "        "dataset, if given, is written to User.dataset_id and must match an "        "existing Network. Records an ADMIN_APPROVAL audit event in the same "        "transaction. Restricted to administrators; the target user must be "        "in the 'pending' state."    ),    status_code=status.HTTP_200_OK,    responses=merge(        {            200: response(                ApprovalResponse,                "Approved. The role change, the optional network scope, and "                "the ADMIN_APPROVAL audit event are all written in one "                "transaction.",                {                    "message": "User 'jdoe' (id=42) has been approved with role 'viewer'.",                    "user_id": 42,                    "granted_role": "viewer",                    "dataset_id": "IDROLOGIA",                },            )        },        UNAUTHORIZED,        {            # A second, differently-shaped 403 exists deeper in this            # handler for a PostgreSQL-privilege failure            # ({"message": "Insufficient database privileges."}) -- far            # rarer than this one, so it's not the documented example, but            # be aware both are possible on this code.            403: FORBIDDEN_ADMIN[403],        },        NOT_FOUND_PENDING_USER,        BAD_REQUEST_REJECTED,        DB_UNAVAILABLE,        DB_TIMEOUT,        INTERNAL,    ),)async def patch_policy_approval(    user_id: int,    request: AdminApprovalRequest,    current_user=Depends(get_current_user),):    # ------------------------------------------------------------------    # 1. Authorization: only administrators may approve pending users.    # ------------------------------------------------------------------    if current_user["role"] != "administrator":        raise HTTPException(            status_code=status.HTTP_403_FORBIDDEN,            detail="Forbidden: Administrator access required",        )     # ------------------------------------------------------------------    # 2. Acquire write pool connection and run all mutations atomically.    # ------------------------------------------------------------------    try:        write_pool = await get_pool_w() if POSTGRES_PORT_WRITE else await get_pool()         async with write_pool.acquire() as conn:            async with conn.transaction():                 # ------------------------------------------------------                # 2a. Fetch the target user's username and status.                #     We need the username to construct the RLS policy                #     name and pass as the first argument to the policy                #     function. status is checked separately below —                #     rejection is a status transition, not a role                #     change, so a rejected user still has role='pending'                #     and would otherwise still match the UPDATE's                #     WHERE clause in step 2b.                # ------------------------------------------------------                username_row = await conn.fetchrow(                    """                    SELECT username, status, requested_role, dataset_id,                        auth_provider                    FROM sensorthings."User"                    WHERE id = $1                    """,                    user_id,                )                 if username_row is None:                    raise HTTPException(                        status_code=status.HTTP_404_NOT_FOUND,                        detail="User not found or not in pending state",                    )                 if username_row["status"] == "rejected":                    raise HTTPException(                        status_code=status.HTTP_400_BAD_REQUEST,                        detail=(                            "This user's registration was rejected and "                            "cannot be approved directly. They must "                            "re-apply via POST /Register first."                        ),                    )                 username: str = username_row["username"]                 # request.role is the administrator's explicit choice and                # always wins; omitting it falls back to what the                # applicant themselves asked for at registration or OIDC                # login. Both missing means there is nothing to approve                # into.                target_role = request.role or username_row["requested_role"]                if target_role is None:                    raise HTTPException(                        status_code=status.HTTP_400_BAD_REQUEST,                        detail=(                            f"User '{username}' did not request a role at "                            "registration, so role must be specified "                            "explicitly."                        ),                    )                 # ------------------------------------------------------                # 2b. UPDATE the User row — role + status.                #     The WHERE clause includes role = 'pending' so we                #     only activate genuinely pending users; RETURNING id                #     confirms a row was touched.                # ------------------------------------------------------                updated_row = await conn.fetchrow(                    """                    UPDATE sensorthings."User"                    SET role   = $1,                        status = 'active'                    WHERE id   = $2                      AND role = 'pending'                    RETURNING id                    """,                    target_role,                    user_id,                )                 if updated_row is None:                    raise HTTPException(                        status_code=status.HTTP_404_NOT_FOUND,                        detail="User not found or not in pending state",                    )                 # ------------------------------------------------------                # 2c. Network scope. The role UPDATE above is the entire                #     capability grant (enforced by the static policies in                #     006_session_scoped_rls_policies.sql). This step only                #     sets *which rows* the user may touch, by writing a                #     Network name to User.dataset_id.                #                #     request.dataset: None  -> leave the applicant's                #       requested value unchanged.                #                     ""    -> clear any scope.                #                     name  -> must match a Network.                # ------------------------------------------------------                # With NETWORK=0 there are no Networks, so a requested scope is ignored.                granted_dataset_id = username_row["dataset_id"] if NETWORK else None                if NETWORK and request.dataset is not None:                    new_scope = request.dataset.strip() or None                    if new_scope is not None and NETWORK:                        exists = await conn.fetchval(                            'SELECT 1 FROM sensorthings."Network" WHERE name = $1',                            new_scope,                        )                        if not exists:                            raise HTTPException(                                status_code=status.HTTP_400_BAD_REQUEST,                                detail=(                                    f"No Network named '{new_scope}'. "                                    "dataset must match an existing Network."                                ),                            )                    await conn.execute(                        'UPDATE sensorthings."User" SET dataset_id = $1 WHERE id = $2',                        new_scope,                        user_id,                    )                    granted_dataset_id = new_scope                 # ------------------------------------------------------                # 2d. Append an ADMIN_APPROVAL record to the AuditLog.                #     Same connection / same transaction → atomic with                #     the UPDATE above.                # ------------------------------------------------------                await log_audit_event(                    conn=conn,                    action_type=AUDIT_ACTION_ADMIN_APPROVAL,                    actor_id=current_user["id"],                    dataset_id=granted_dataset_id,                    payload={                        "approved_user_id": user_id,                        "granted_role": target_role,                        "auth_provider": username_row["auth_provider"],                    },                )         logger.info(            "Admin approval: user '%s' (id=%d) granted role '%s' "            "scoped to '%s' by admin id=%d.",            username,            user_id,            target_role,            granted_dataset_id,            current_user["id"],        )         return JSONResponse(            status_code=status.HTTP_200_OK,            content={                "message": (                    f"User '{username}' (id={user_id}) has been approved "                    f"with role '{target_role}'."                ),                "user_id": user_id,                "granted_role": target_role,                "dataset_id": granted_dataset_id,            },        )     except HTTPException:        # Re-raise HTTPExceptions raised inside the transaction block        # (404s) without wrapping them in a 500.        raise    except InsufficientPrivilegeError:        return JSONResponse(            status_code=status.HTTP_403_FORBIDDEN,            content={"message": "Insufficient database privileges."},        )    except (PostgresConnectionError, TooManyConnectionsError):        logger.exception("Database unavailable during admin approval")        return JSONResponse(            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,            content={"message": "Database temporarily unavailable."},        )    except QueryCanceledError:        logger.exception("Database timeout during admin approval")        return JSONResponse(            status_code=status.HTTP_504_GATEWAY_TIMEOUT,            content={"message": "Database request timed out."},        )    except Exception:        logger.exception("Unexpected error during admin approval")        return JSONResponse(            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,            content={"message": "Internal server error."},        )