pjdev-gitlab 5.2.0__tar.gz → 5.4.0__tar.gz

{pjdev_gitlab-5.2.0 → pjdev_gitlab-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pjdev-gitlab
-Version: 5.2.0
+Version: 5.4.0
 Project-URL: Documentation, https://gitlab.purplejay.io/keystone/python/-/tree/main/pjdev-gitlab/README.md
 Project-URL: Issues, https://gitlab.purplejay.io/keystone/python/-/issues
 Project-URL: Source, https://gitlab.purplejay.io/keystone/python
@@ -94,8 +94,70 @@ TOKEN="$(uvx --from 'pjdev-gitlab' pjdev-gitlab-auth \
 The library is instance-agnostic: `--client-id` (or `GL_OAUTH_CLIENT_ID`) is
 required and the host defaults to `https://gitlab.com` (override with
 `--gitlab-url` / `GL_GITLAB_URL`). Other flags: `--client-secret`,
-`--redirect-port`, `--scopes`, `--force` (each with a `GL_OAUTH_*` env
-equivalent).
+`--redirect-port`, `--scopes`, `--admin-mode`, `--force` (each with a
+`GL_OAUTH_*` env equivalent).
+
+### Admin mode (instance admin API)
+
+GitLab gates its instance admin API behind **admin mode**: `/license`, the admin
+projection of `/users` (the one carrying `email` and `external`),
+`/users/:id/memberships` and friends answer `403` — or, worse, answer `200` with
+a *narrower* record — unless the credential itself was granted the `admin_mode`
+scope. Being an administrator is not enough; the token has to carry it.
+
+```python
+token = oauth_service.get_access_token(
+    gitlab_url="https://gitlab.example.com",
+    client_id="<client id>",
+    admin_mode=True,          # -> requests "api admin_mode"
+)
+```
+
+```bash
+pjdev-gitlab-auth --gitlab-url https://gitlab.example.com \
+  --client-id <id> --admin-mode          # or GL_OAUTH_ADMIN_MODE=1
+```
+
+Two things this handles that are easy to get wrong:
+
+- **The cache is scope-aware.** Tokens are cached per host, so a previously
+  minted `api` token would otherwise be handed straight back to an
+  `admin_mode` request and then 403 on every admin call. A cached token whose
+  recorded grant does not cover what is being asked for is rejected and the
+  browser flow re-runs. (Refreshing cannot widen a grant either, so that path is
+  skipped too.)
+- **A silently narrowed grant is an error.** GitLab issues whatever the
+  *application registration* allows, so an app registered for `api` alone
+  answers an `api admin_mode` request with an `api` token and no complaint.
+  `get_access_token` compares the granted scopes against the requested ones and
+  raises `OAuthError` naming the missing scope, instead of letting you discover
+  it as a 403 later.
+
+The OAuth application must therefore be registered with **both** `api` and
+`admin_mode`. A personal access token works too — select both scopes when
+creating it, and initialize with `auth_scheme="private-token"`.
+
+#### `users_service` — the admin user API
+
+```python
+from pjdev_gitlab import config_service, users_service
+
+config_service.init(token=token, gitlab_url=..., auth_scheme="bearer")
+
+external = await users_service.list_external_users()
+for user in external:
+    print(user.username, user.email)
+```
+
+`list_users`, `get_user` and `list_external_users` all verify that GitLab
+actually returned the admin projection and raise
+`users_service.AdminModeRequired` when it did not. That check exists because the
+public projection *omits* `email` and `external` rather than erroring, so
+`row.get("external")` reads as `None` and a naive caller concludes "no external
+users" — a confident wrong answer. `list_external_users` also filters on the
+`external` field of each returned record rather than trusting the server-side
+`external=true` parameter, so a silently ignored filter cannot shorten the list.
+`list_memberships` wraps the admin-only `/users/:id/memberships`.
 
 #### `pjdev-gitlab-sync` console script
 

{pjdev_gitlab-5.2.0 → pjdev_gitlab-5.4.0}/README.md

@@ -66,8 +66,70 @@ TOKEN="$(uvx --from 'pjdev-gitlab' pjdev-gitlab-auth \
 The library is instance-agnostic: `--client-id` (or `GL_OAUTH_CLIENT_ID`) is
 required and the host defaults to `https://gitlab.com` (override with
 `--gitlab-url` / `GL_GITLAB_URL`). Other flags: `--client-secret`,
-`--redirect-port`, `--scopes`, `--force` (each with a `GL_OAUTH_*` env
-equivalent).
+`--redirect-port`, `--scopes`, `--admin-mode`, `--force` (each with a
+`GL_OAUTH_*` env equivalent).
+
+### Admin mode (instance admin API)
+
+GitLab gates its instance admin API behind **admin mode**: `/license`, the admin
+projection of `/users` (the one carrying `email` and `external`),
+`/users/:id/memberships` and friends answer `403` — or, worse, answer `200` with
+a *narrower* record — unless the credential itself was granted the `admin_mode`
+scope. Being an administrator is not enough; the token has to carry it.
+
+```python
+token = oauth_service.get_access_token(
+    gitlab_url="https://gitlab.example.com",
+    client_id="<client id>",
+    admin_mode=True,          # -> requests "api admin_mode"
+)
+```
+
+```bash
+pjdev-gitlab-auth --gitlab-url https://gitlab.example.com \
+  --client-id <id> --admin-mode          # or GL_OAUTH_ADMIN_MODE=1
+```
+
+Two things this handles that are easy to get wrong:
+
+- **The cache is scope-aware.** Tokens are cached per host, so a previously
+  minted `api` token would otherwise be handed straight back to an
+  `admin_mode` request and then 403 on every admin call. A cached token whose
+  recorded grant does not cover what is being asked for is rejected and the
+  browser flow re-runs. (Refreshing cannot widen a grant either, so that path is
+  skipped too.)
+- **A silently narrowed grant is an error.** GitLab issues whatever the
+  *application registration* allows, so an app registered for `api` alone
+  answers an `api admin_mode` request with an `api` token and no complaint.
+  `get_access_token` compares the granted scopes against the requested ones and
+  raises `OAuthError` naming the missing scope, instead of letting you discover
+  it as a 403 later.
+
+The OAuth application must therefore be registered with **both** `api` and
+`admin_mode`. A personal access token works too — select both scopes when
+creating it, and initialize with `auth_scheme="private-token"`.
+
+#### `users_service` — the admin user API
+
+```python
+from pjdev_gitlab import config_service, users_service
+
+config_service.init(token=token, gitlab_url=..., auth_scheme="bearer")
+
+external = await users_service.list_external_users()
+for user in external:
+    print(user.username, user.email)
+```
+
+`list_users`, `get_user` and `list_external_users` all verify that GitLab
+actually returned the admin projection and raise
+`users_service.AdminModeRequired` when it did not. That check exists because the
+public projection *omits* `email` and `external` rather than erroring, so
+`row.get("external")` reads as `None` and a naive caller concludes "no external
+users" — a confident wrong answer. `list_external_users` also filters on the
+`external` field of each returned record rather than trusting the server-side
+`external=true` parameter, so a silently ignored filter cannot shorten the list.
+`list_memberships` wraps the admin-only `/users/:id/memberships`.
 
 #### `pjdev-gitlab-sync` console script
 

{pjdev_gitlab-5.2.0 → pjdev_gitlab-5.4.0}/src/pjdev_gitlab/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2026-present Chris O'Neill <chris@purplejay.io>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "5.2.0"
+__version__ = "5.4.0"

{pjdev_gitlab-5.2.0 → pjdev_gitlab-5.4.0}/src/pjdev_gitlab/__init__.py

@@ -17,5 +17,6 @@ __all__ = [
     "oauth_service",
     "packages_service",
     "repo_files_service",
+    "users_service",
     "work_items_service",
 ]

{pjdev_gitlab-5.2.0 → pjdev_gitlab-5.4.0}/src/pjdev_gitlab/models.py

@@ -90,6 +90,33 @@ class Author(GitlabBase):
     email: Optional[str] = None
 
 
+class User(GitlabBase):
+    """An instance user as returned by ``GET /users``.
+
+    The admin-only fields (``email``, ``external``, ``is_admin``, ...) are
+    optional because GitLab omits them from the public projection; see
+    :mod:`pjdev_gitlab.users_service`, which refuses to hand back records that
+    are missing them rather than letting ``external=None`` read as "not
+    external".
+    """
+
+    id: int
+    username: str
+    name: Optional[str] = None
+    state: Optional[str] = None
+    web_url: Optional[str] = None
+    public_email: Optional[str] = None
+    created_at: Optional[datetime] = None
+    bot: bool = False
+    # Admin projection only.
+    email: Optional[str] = None
+    external: Optional[bool] = None
+    is_admin: Optional[bool] = None
+    last_sign_in_at: Optional[datetime] = None
+    last_activity_on: Optional[str] = None
+    using_license_seat: Optional[bool] = None
+
+
 class Label(GitlabBase):
     id: Optional[int] = None
     name: str

{pjdev_gitlab-5.2.0 → pjdev_gitlab-5.4.0}/src/pjdev_gitlab/oauth_cli.py

@@ -22,6 +22,11 @@ Usage::
 The registered OAuth application must be a non-confidential (PKCE) app with the
 requested scope (default ``api``) and Redirect URI exactly
 ``http://localhost:<redirect-port>/callback``.
+
+Pass ``--admin-mode`` (or ``GL_OAUTH_ADMIN_MODE=1``) to also request the
+``admin_mode`` scope that GitLab requires for the instance admin API -- the
+application registration must include it, or the flow fails with a clear error
+rather than handing back a token that 403s on every admin endpoint.
 """
 
 from __future__ import annotations
@@ -31,6 +36,7 @@ import os
 import sys
 
 from pjdev_gitlab.oauth_service import (
+    ADMIN_MODE_SCOPE,
     DEFAULT_REDIRECT_PORT,
     DEFAULT_SCOPES,
     OAuthError,
@@ -71,6 +77,16 @@ def main() -> int:
         default=None,
         help=f'space-separated scopes (or GL_OAUTH_SCOPES; default "{DEFAULT_SCOPES}")',
     )
+    parser.add_argument(
+        "--admin-mode",
+        action="store_true",
+        default=None,
+        help=(
+            f"also request the {ADMIN_MODE_SCOPE!r} scope, required by the instance "
+            "admin API (or GL_OAUTH_ADMIN_MODE=1). The OAuth application must be "
+            "registered with that scope."
+        ),
+    )
     parser.add_argument(
         "--force",
         action="store_true",
@@ -89,6 +105,12 @@ def main() -> int:
         return 2
     client_secret = args.client_secret or os.environ.get("GL_OAUTH_CLIENT_SECRET") or None
     scopes = args.scopes or os.environ.get("GL_OAUTH_SCOPES") or DEFAULT_SCOPES
+    admin_mode = (
+        args.admin_mode
+        if args.admin_mode is not None
+        else os.environ.get("GL_OAUTH_ADMIN_MODE", "").strip().lower()
+        in ("1", "true", "yes", "on")
+    )
 
     port_raw = (
         args.redirect_port
@@ -108,6 +130,7 @@ def main() -> int:
             client_secret=client_secret,
             redirect_port=redirect_port,
             scopes=scopes,
+            admin_mode=admin_mode,
             force=args.force,
         )
     except OAuthError as exc:

{pjdev_gitlab-5.2.0 → pjdev_gitlab-5.4.0}/src/pjdev_gitlab/oauth_service.py

@@ -48,6 +48,12 @@ import httpx
 
 DEFAULT_REDIRECT_PORT = 7331
 DEFAULT_SCOPES = "api"
+# GitLab gates the instance admin API (/license, /users admin view,
+# /users/:id/memberships, ...) behind "admin mode". A token only carries it when
+# the credential itself was granted this scope, and the OAuth application must
+# be registered with it -- an app registered for "api" alone will hand back an
+# api-only token no matter what the authorize request asked for.
+ADMIN_MODE_SCOPE = "admin_mode"
 # Treat a token as expired this many seconds early to avoid racing the clock.
 EXPIRY_SKEW_SECONDS = 60
 # How long to wait for the browser redirect before giving up.
@@ -96,7 +102,36 @@ def save_cache(path: Path, data: dict[str, Any]) -> None:
     tmp.replace(path)
 
 
-def token_if_valid(cache: Optional[dict[str, Any]]) -> Optional[str]:
+def parse_scopes(value: Optional[str]) -> set[str]:
+    """Split a scope string ("api admin_mode" or "api,admin_mode") into a set."""
+    if not value:
+        return set()
+    return {scope for scope in value.replace(",", " ").split() if scope}
+
+
+def scopes_satisfy(granted: Optional[str], required: Optional[str]) -> bool:
+    """True when every required scope appears in ``granted``."""
+    return parse_scopes(required) <= parse_scopes(granted)
+
+
+def with_admin_mode(scopes: str = DEFAULT_SCOPES) -> str:
+    """Return ``scopes`` with :data:`ADMIN_MODE_SCOPE` added. Idempotent."""
+    requested = parse_scopes(scopes) | {ADMIN_MODE_SCOPE}
+    # "api" first, then the rest alphabetically, so the string is stable.
+    return " ".join(sorted(requested, key=lambda scope: (scope != "api", scope)))
+
+
+def token_if_valid(
+    cache: Optional[dict[str, Any]], required_scopes: Optional[str] = None
+) -> Optional[str]:
+    """Return the cached access token when it is still usable.
+
+    The cache is keyed by host only, so a token minted earlier for a *narrower*
+    scope set would otherwise be handed back to a caller that has since asked
+    for more -- e.g. reusing an ``api`` token for an ``api admin_mode`` request,
+    which then 403s on every admin endpoint. Passing ``required_scopes`` rejects
+    that token so the caller re-authorizes instead.
+    """
     if not cache:
         return None
     token = cache.get("access_token")
@@ -105,6 +140,14 @@ def token_if_valid(cache: Optional[dict[str, Any]]) -> Optional[str]:
         return None
     if time.time() >= expires_at - EXPIRY_SKEW_SECONDS:
         return None
+    if required_scopes:
+        # A cache entry written before scopes were recorded has an *unknown*
+        # grant, not an empty one. Every token this library has ever minted
+        # asked for DEFAULT_SCOPES, so assume that much -- enough to keep
+        # existing caches working, never enough to satisfy a wider request.
+        granted = cache["scope"] if "scope" in cache else DEFAULT_SCOPES
+        if not scopes_satisfy(granted, required_scopes):
+            return None
     return token
 
 
@@ -292,6 +335,7 @@ def get_access_token(
     client_secret: Optional[str] = None,
     redirect_port: int = DEFAULT_REDIRECT_PORT,
     scopes: str = DEFAULT_SCOPES,
+    admin_mode: bool = False,
     force: bool = False,
     cache_dir: Optional[Path] = None,
     on_status: Optional[StatusFn] = None,
@@ -306,6 +350,11 @@ def get_access_token(
     reported via ``on_status`` (defaults to printing to stderr). Raises
     :class:`OAuthError` on any unrecoverable failure.
 
+    ``admin_mode=True`` adds the ``admin_mode`` scope, which GitLab requires for
+    the instance admin API. A cached token granted only the narrower scopes is
+    *not* reused for such a request -- it would 403 on every admin endpoint --
+    so the browser flow runs again to re-consent.
+
     The returned token is an OAuth access token: send it as a Bearer credential,
     e.g. ``config_service.init(token=<token>, auth_scheme="bearer")``.
     """
@@ -314,18 +363,33 @@ def get_access_token(
     status = on_status or _default_status
     cache_dir = cache_dir or default_cache_dir()
     redirect_uri = f"http://localhost:{redirect_port}/callback"
+    if admin_mode:
+        scopes = with_admin_mode(scopes)
 
     path = cache_path(cache_dir, gitlab_url)
     cache = None if force else load_cache(path)
 
-    # 1. Reuse a still-valid cached access token.
-    token = token_if_valid(cache)
+    # 1. Reuse a still-valid cached access token, but only if it was granted at
+    #    least the scopes being asked for now.
+    token = token_if_valid(cache, scopes)
     if token:
         status("Reusing cached access token.")
         return token
 
-    # 2. Silently refresh an expired token if we have a refresh token.
-    if cache and cache.get("refresh_token"):
+    # 2. Silently refresh an expired token if we have a refresh token. A refresh
+    #    preserves the original grant's scopes, so it cannot widen them -- when
+    #    the caller now wants more, skip straight to re-consent.
+    cached_scope = cache.get("scope", DEFAULT_SCOPES) if cache else None
+    if (
+        cache
+        and cache.get("refresh_token")
+        and not scopes_satisfy(cached_scope, scopes)
+    ):
+        status(
+            f"Cached token was granted {cached_scope or 'no'} scope(s) but "
+            f"{scopes!r} is required; re-authorizing."
+        )
+    elif cache and cache.get("refresh_token"):
         status("Access token expired; refreshing silently ...")
         payload = refresh_access_token(
             gitlab_url=gitlab_url,
@@ -334,7 +398,8 @@ def get_access_token(
             refresh_value=cache["refresh_token"],
         )
         if payload:
-            return store_token_response(path, payload, scopes)
+            # A refresh keeps the original grant; record that, not the request.
+            return store_token_response(path, payload, cached_scope or scopes)
         status("Refresh failed; falling back to browser sign-in.")
 
     # 3. Full browser flow.
@@ -350,5 +415,20 @@ def get_access_token(
         timeout_seconds=timeout_seconds,
     )
     token = store_token_response(path, payload, scopes)
+
+    # GitLab silently narrows the grant to whatever the application is
+    # registered for, so an app registered for "api" alone answers an
+    # "api admin_mode" request with an api-only token. Fail loudly here rather
+    # than let the caller discover it as a 403 on the first admin endpoint.
+    granted = payload.get("scope", scopes)
+    if not scopes_satisfy(granted, scopes):
+        missing = " ".join(sorted(parse_scopes(scopes) - parse_scopes(granted)))
+        raise OAuthError(
+            f"the OAuth application granted scope(s) {granted!r} but {scopes!r} "
+            f"was requested (missing: {missing}). Add the missing scope(s) to the "
+            f"application registration at {gitlab_url.rstrip('/')}/-/user_settings/applications "
+            "(or Admin area -> Applications for an instance-wide app), then retry."
+        )
+
     status("Authenticated. Short-lived token obtained.")
     return token

pjdev_gitlab-5.4.0/src/pjdev_gitlab/users_service.py

@@ -0,0 +1,247 @@
+"""Instance user administration: the admin projection of ``GET /users``.
+
+GitLab answers ``GET /users`` for any authenticated caller, but the *shape* of
+the response depends on the credential. A plain ``api`` token gets the public
+projection -- username, name, avatar, web_url. Only a credential carrying the
+``admin_mode`` scope (see :mod:`pjdev_gitlab.oauth_service`) gets the admin
+projection, which adds ``email``, ``external``, ``is_admin``, ``last_sign_in_at``
+and the rest.
+
+The failure mode this module exists to prevent: the public projection simply
+*omits* those keys rather than erroring, so naive code reads
+``row.get("external")`` as ``None``, concludes "no external users", and reports
+a confident wrong answer. Every entry point here checks for the admin-only keys
+first and raises :class:`AdminModeRequired` instead.
+"""
+
+from typing import Any, Optional
+
+from httpx import AsyncClient
+
+from pjdev_gitlab.api_utilities import (
+    async_retry_http,
+    encode_path_segment,
+    http_client,
+    paginate,
+)
+from pjdev_gitlab.models import User
+
+_IGNORE_4XX = [400, 401, 403, 404]
+
+# Keys present only in the admin projection of a user record. Their absence is
+# how we detect a credential that never entered admin mode.
+ADMIN_ONLY_USER_FIELDS = ("email", "external", "is_admin")
+
+
+class AdminModeRequired(RuntimeError):
+    """The credential lacks admin mode, so admin-only user fields are invisible.
+
+    Mint a token with the ``admin_mode`` scope -- ``oauth_service`` accepts
+    ``admin_mode=True`` (``pjdev-gitlab-auth --admin-mode``), and a personal
+    access token needs ``api`` plus ``admin_mode`` selected at creation.
+    """
+
+
+def assert_admin_projection(row: dict[str, Any]) -> None:
+    """Raise :class:`AdminModeRequired` if ``row`` is the public projection."""
+    missing = [field for field in ADMIN_ONLY_USER_FIELDS if field not in row]
+    if missing:
+        raise AdminModeRequired(
+            "GitLab returned the public user projection, without "
+            f"{', '.join(missing)}. The token is not in admin mode: mint one "
+            "with the 'admin_mode' scope (pjdev-gitlab-auth --admin-mode, or a "
+            "PAT created with both 'api' and 'admin_mode')."
+        )
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def _fetch_user_rows(
+    params: dict[str, Any], client: Optional[AsyncClient]
+) -> list[dict[str, Any]]:
+    async def _exec(_client: AsyncClient) -> list[dict[str, Any]]:
+        return await paginate(_client, "/users", params=params)
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+async def list_users(
+    *,
+    active: Optional[bool] = None,
+    blocked: Optional[bool] = None,
+    external: Optional[bool] = None,
+    exclude_internal: Optional[bool] = None,
+    without_project_bots: Optional[bool] = None,
+    search: Optional[str] = None,
+    extra_params: Optional[dict[str, Any]] = None,
+    client: Optional[AsyncClient] = None,
+) -> list[User]:
+    """List instance users via the admin projection of ``GET /users``.
+
+    Requires admin mode; raises :class:`AdminModeRequired` otherwise. The
+    boolean filters map to GitLab's query parameters, which it accepts only as
+    the string ``"true"`` -- passing ``False`` omits the parameter rather than
+    sending ``false``, matching GitLab's own semantics.
+    """
+    params: dict[str, Any] = dict(extra_params or {})
+    for name, value in (
+        ("active", active),
+        ("blocked", blocked),
+        ("external", external),
+        ("exclude_internal", exclude_internal),
+        ("without_project_bots", without_project_bots),
+    ):
+        if value:
+            params[name] = "true"
+    if search:
+        params["search"] = search
+
+    # The projection check runs outside the retry decorator on purpose: that
+    # decorator funnels every exception into an ExceptionGroup, which would bury
+    # the one message the caller actually needs to read.
+    rows = await _fetch_user_rows(params, client)
+    if rows:
+        assert_admin_projection(rows[0])
+    return [User.model_validate(row) for row in rows]
+
+
+async def list_external_users(
+    *,
+    active_only: bool = True,
+    include_bots: bool = False,
+    client: Optional[AsyncClient] = None,
+) -> list[User]:
+    """List users flagged ``external`` on the instance.
+
+    Filtering happens client-side on the ``external`` field rather than through
+    GitLab's ``external=true`` parameter, so a silently ignored or renamed
+    parameter cannot turn into a falsely short list -- the flag on each returned
+    record is the authority.
+    """
+    users = await list_users(active=active_only or None, client=client)
+    return [user for user in users if user.external and (include_bots or not user.bot)]
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def _fetch_user_row(
+    user_id: Any, client: Optional[AsyncClient]
+) -> dict[str, Any]:
+    async def _exec(_client: AsyncClient) -> dict[str, Any]:
+        r = await _client.get(f"/users/{encode_path_segment(user_id)}")
+        r.raise_for_status()
+        return r.json()
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+async def get_user(user_id: Any, *, client: Optional[AsyncClient] = None) -> User:
+    """Fetch one user via ``GET /users/:id``, requiring the admin projection."""
+    row = await _fetch_user_row(user_id, client)
+    assert_admin_projection(row)
+    return User.model_validate(row)
+
+
+class UserUpdateNotApplied(RuntimeError):
+    """GitLab answered 200 but returned a record that does not reflect the change.
+
+    ``PUT /users/:id`` drops attributes it will not apply instead of rejecting
+    the request -- an administrator cannot be flagged ``external``, for one.
+    Without this check a caller marking seats external reads the 200 as done
+    while the seat stays billable, which is the same class of confident-wrong
+    answer the projection check above exists to prevent.
+    """
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def _put_user_row(
+    user_id: Any, payload: dict[str, Any], client: Optional[AsyncClient]
+) -> dict[str, Any]:
+    async def _exec(_client: AsyncClient) -> dict[str, Any]:
+        r = await _client.put(f"/users/{encode_path_segment(user_id)}", json=payload)
+        r.raise_for_status()
+        return r.json()
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+async def update_user(
+    user_id: Any,
+    *,
+    external: Optional[bool] = None,
+    extra_fields: Optional[dict[str, Any]] = None,
+    client: Optional[AsyncClient] = None,
+) -> User:
+    """Update a user via ``PUT /users/:id`` and return the updated record.
+
+    Admin-only, and the response is the admin projection, so a credential
+    without admin mode raises :class:`AdminModeRequired` (or is refused
+    outright with a 403). ``external`` is sent as a JSON boolean -- the string
+    ``"true"`` dance in :func:`list_users` applies to query parameters, not to
+    a request body -- and passing ``None`` leaves the flag alone rather than
+    clearing it.
+
+    ``extra_fields`` is merged into the payload for attributes without a named
+    parameter here. Only ``external`` is verified against the response:
+    GitLab defers some writes rather than applying them (an ``email`` change
+    waits on confirmation and echoes back the old address), so checking every
+    field would report those as failures.
+    """
+    payload: dict[str, Any] = dict(extra_fields or {})
+    if external is not None:
+        payload["external"] = external
+    if not payload:
+        raise ValueError("update_user needs at least one field to change")
+
+    row = await _put_user_row(user_id, payload, client)
+
+    # Both checks sit outside the retry decorator on purpose: it funnels every
+    # exception into an ExceptionGroup, which would bury the message.
+    assert_admin_projection(row)
+    if external is not None and row.get("external") != external:
+        raise UserUpdateNotApplied(
+            f"GitLab accepted PUT /users/{user_id} but returned "
+            f"external={row.get('external')!r} after a request for "
+            f"external={external!r}. GitLab refuses to flag an administrator "
+            "external, and drops the attribute silently when it does."
+        )
+    return User.model_validate(row)
+
+
+async def set_user_external(
+    user_id: Any, external: bool = True, *, client: Optional[AsyncClient] = None
+) -> User:
+    """Flag a user ``external``, or clear the flag with ``external=False``.
+
+    External users do not consume a billable seat, so this is the write half of
+    :func:`list_external_users`.
+    """
+    return await update_user(user_id, external=external, client=client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def list_memberships(
+    user_id: Any, *, client: Optional[AsyncClient] = None
+) -> list[dict[str, Any]]:
+    """List a user's direct group and project memberships.
+
+    ``GET /users/:id/memberships`` is admin-only and 403s without admin mode, so
+    the error is surfaced by the request itself rather than a projection check.
+    """
+
+    async def _exec(_client: AsyncClient) -> list[dict[str, Any]]:
+        return await paginate(
+            _client, f"/users/{encode_path_segment(user_id)}/memberships"
+        )
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)