make-azure 0.2.0__tar.gz

make_azure-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.env
+
+# wrangler caches its Pages upload state here (site/ is deployed by direct upload).
+.wrangler/
+
+# The VS Code extension in editors/vscode: `dist/` is above, and these two are what
+# building a .vsix leaves behind. `npm install` is never run there -- the extension has
+# no runtime dependency and both CLIs come from `npx --yes` -- so node_modules/ is
+# listed to catch the day somebody tries.
+node_modules/
+*.vsix

make_azure-0.2.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: make-azure
+Version: 0.2.0
+Summary: Azure tasks for mkrun -- sign in with azure-identity, and create a free-tier virtual machine with nothing billed left behind.
+Project-URL: Homepage, https://make.optersoft.com
+Author-email: "Optersoft, S.L." <david@optersoft.com>
+License-Expression: MIT OR Apache-2.0
+Keywords: az,azure,free tier,mk,mkrun,virtual machine
+Requires-Python: >=3.11
+Requires-Dist: azure-identity>=1.16
+Requires-Dist: mkrun>=0.4.1
+Description-Content-Type: text/markdown
+
+# make-azure
+
+A virtual machine on **Azure's free tier**, for [`mkrun`](https://pypi.org/project/mkrun/):
+signed in with Microsoft's own `azure-identity`, created with every field that
+decides the bill set explicitly, and removed with nothing billed left behind.
+No `az` CLI.
+
+```python
+# Makefile.py in a consuming repo
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["mkrun>=0.4.1", "make-azure>=0.2"]
+# ///
+from make_azure import azure  # importing is what registers the group
+from make_azure.vm import Azure
+
+Azure.configure(tenant="contoso.onmicrosoft.com", location="swedencentral")  # optional
+```
+
+```console
+$ mk azure.login --tenant <id or domain>   # once; a browser opens
+$ mk azure.login --tenant <t> --device-code  # no browser here: enter a code elsewhere
+$ mk azure.account                         # which subscription, and is it a free one
+$ mk azure.vm box                          # Ubuntu 24.04 on a B1s, SSH open
+$ mk azure.vm arm --size Standard_B2pts_v2
+$ mk azure.vms                             # what the subscription has
+$ mk azure.delete box                      # the VM and everything it made
+$ mk -n azure.vm box                       # the plan; nothing is sent, no sign-in needed
+```
+
+## Signing in
+
+`azure.login` runs the sign-in inside its own process, so the browser's
+redirect goes back to the process that is waiting for it. It keeps two things:
+
+- an **authentication record** (account, tenant, username; no secret) in
+  `~/.make/azure/<tenant>.json`, which says which account later calls use;
+- the **tokens**, in MSAL's encrypted cache: the macOS Keychain, or libsecret
+  on Linux. Unencrypted storage is refused, never fallen back to.
+
+Every later task gets its token silently from those two. It never opens a
+browser in the middle of `azure.vm`: an expired sign-in is an error that says
+`mk azure.login`.
+
+In CI, an identity in the environment wins: `AZURE_CLIENT_ID` + `AZURE_TENANT_ID`
+with `AZURE_FEDERATED_TOKEN_FILE` (workload identity) or `AZURE_CLIENT_SECRET`.
+The secret's name marks it as a credential, so mkrun withholds it from child
+processes and redacts it.
+
+⚠ **There is no `az` fallback**, on purpose. One address can be both a personal
+Microsoft account and a work account, and silently reusing whichever `az`
+session is around is how the wrong one gets used.
+
+⚠ **MFA is asked for at sign-in, on purpose.** Since Azure's mandatory MFA
+(2025), Resource Manager answers any create, update or delete made without it
+with `401 RequestDisallowedByAzure` and a claims challenge (`acrs: p1`). Reads
+still pass, so everything up to the first write would work and then fail.
+`azure.login` asks for those claims up front, and `arm` answers a challenge
+silently if one still comes. The user does MFA once, at sign-in, as the portal
+makes them.
+
+⚠ **School and work tenants often block `--device-code`.** Microsoft's managed
+Conditional Access policy against device-code phishing answers
+`AADSTS53003` *"does not meet the criteria"* after a successful sign-in, and
+the device-code flow then polls until its code expires (about 15 minutes):
+Ctrl-C. Use the browser flow, which the same policy allows. Measured on a
+school tenant (Azure for Students), 2026-10-07: device code refused, browser
+admitted, VM created, SSH in, deleted.
+
+Two browser-flow traps, both with a fix on screen:
+
+- **The redirect has to reach this process.** The sign-in URL is printed as
+  well as opened. Open it in the browser you actually sign in with; if you sign
+  in in some other tab, nothing comes back and `azure.login` times out after 5
+  minutes.
+- **`state mismatch: … vs None`** means an *old* `localhost:8400` tab (a
+  previous *"Authentication complete"* page, reloaded or restored) answered
+  first. Close every such tab and run `azure.login` again.
+
+`azure-identity` signs in as the Azure CLI's public client
+(`04b07795-8ddb-461a-bbee-02f9e1bf7b46`), so a tenant that blocks `az` outright
+blocks this too.
+
+## What "free" means here
+
+An Azure free account gives, for its first 12 months, **750 hours a month** of
+each of `Standard_B1s`, `Standard_B2ats_v2` (AMD) and `Standard_B2pts_v2` (Arm).
+That's one VM running all month. It also gives **two 64 GiB P6 managed disks**.
+Azure for Students carries the same free services. Everything else bills:
+
+| | a portal or `az vm create` default | here |
+|---|---|---|
+| OS disk | 30 GiB → billed as **P4**, a meter the offer does not cover | **64 GiB Premium SSD = P6**, the free one |
+| size | `Standard_DS1_v2` and friends | `Standard_B1s`; anything outside the three is refused |
+| resource group | one you name, shared | `<name>-rg`, one per VM, so `delete` takes all of it |
+| public IP | Standard static IPv4 | the same, **and it is billed** (about $3.65 a month) |
+
+⚠ **The public IPv4 is the one cost.** Basic public IPs, which the free account
+used to cover, were retired on 2025-09-30, and a Standard IPv4 bills by the hour
+whether or not the VM runs. `--no-public-ip` leaves it out; the VM is then
+reachable only from inside its network.
+
+⚠ **A pay-as-you-go subscription takes the same request and pays for it.**
+`azure.vm` reads the subscription's offer (`quotaId`) and refuses anything but
+a free account or Azure for Students. A free account upgraded to pay-as-you-go
+keeps its free hours until month 12 but reports the paid offer; `--paid-ok` is
+for that case.
+
+It also refuses, before creating anything: a sign-in that reaches no
+subscription, or several when none is named; a region that will not sell the
+size to this subscription (free accounts are often restricted in busy regions,
+so try another `--location`); and a name already taken. A second VM of the
+same size is allowed, with a warning: two running all month exceed the 750 hours.
+
+## How it talks to Azure
+
+Plain REST to Resource Manager through `make.http`, with a bearer token from
+`azure-identity`. No `azure-mgmt-*` SDKs. The VM is **one template
+deployment** (`template.py`): network, NSG, IP, NIC and VM in a single request.
+Azure works out the order, and a failure reports Azure's own reason
+(`SkuNotAvailable: …`). `azure-identity` is imported only when a token is
+needed, so `mk --list` never pays its import time.
+
+## Settings
+
+`Azure.configure(...)` in the task file, an `[azure]` table in the config file,
+or `MAKE_AZURE_<FIELD>` in the environment:
+
+| field | default | |
+|---|---|---|
+| `tenant` | the only one `azure.login` saved | tenant id or domain |
+| `subscription` | the only one the sign-in reaches | id or display name |
+| `location` | `westeurope` | any region with B-series capacity |
+| `size` | `Standard_B1s` | one of the three free sizes |
+| `admin` | `azureuser` | the login user |
+| `ssh_key` | `~/.ssh/id_ed25519.pub`, then `id_rsa.pub` | the public key the VM accepts |
+
+The group is `azure`, and it merges with a repo's own `azure.*` tasks; this
+package claims `login`, `account`, `vm`, `vms` and `delete`, nothing else.

make_azure-0.2.0/README.md

@@ -0,0 +1,139 @@
+# make-azure
+
+A virtual machine on **Azure's free tier**, for [`mkrun`](https://pypi.org/project/mkrun/):
+signed in with Microsoft's own `azure-identity`, created with every field that
+decides the bill set explicitly, and removed with nothing billed left behind.
+No `az` CLI.
+
+```python
+# Makefile.py in a consuming repo
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["mkrun>=0.4.1", "make-azure>=0.2"]
+# ///
+from make_azure import azure  # importing is what registers the group
+from make_azure.vm import Azure
+
+Azure.configure(tenant="contoso.onmicrosoft.com", location="swedencentral")  # optional
+```
+
+```console
+$ mk azure.login --tenant <id or domain>   # once; a browser opens
+$ mk azure.login --tenant <t> --device-code  # no browser here: enter a code elsewhere
+$ mk azure.account                         # which subscription, and is it a free one
+$ mk azure.vm box                          # Ubuntu 24.04 on a B1s, SSH open
+$ mk azure.vm arm --size Standard_B2pts_v2
+$ mk azure.vms                             # what the subscription has
+$ mk azure.delete box                      # the VM and everything it made
+$ mk -n azure.vm box                       # the plan; nothing is sent, no sign-in needed
+```
+
+## Signing in
+
+`azure.login` runs the sign-in inside its own process, so the browser's
+redirect goes back to the process that is waiting for it. It keeps two things:
+
+- an **authentication record** (account, tenant, username; no secret) in
+  `~/.make/azure/<tenant>.json`, which says which account later calls use;
+- the **tokens**, in MSAL's encrypted cache: the macOS Keychain, or libsecret
+  on Linux. Unencrypted storage is refused, never fallen back to.
+
+Every later task gets its token silently from those two. It never opens a
+browser in the middle of `azure.vm`: an expired sign-in is an error that says
+`mk azure.login`.
+
+In CI, an identity in the environment wins: `AZURE_CLIENT_ID` + `AZURE_TENANT_ID`
+with `AZURE_FEDERATED_TOKEN_FILE` (workload identity) or `AZURE_CLIENT_SECRET`.
+The secret's name marks it as a credential, so mkrun withholds it from child
+processes and redacts it.
+
+⚠ **There is no `az` fallback**, on purpose. One address can be both a personal
+Microsoft account and a work account, and silently reusing whichever `az`
+session is around is how the wrong one gets used.
+
+⚠ **MFA is asked for at sign-in, on purpose.** Since Azure's mandatory MFA
+(2025), Resource Manager answers any create, update or delete made without it
+with `401 RequestDisallowedByAzure` and a claims challenge (`acrs: p1`). Reads
+still pass, so everything up to the first write would work and then fail.
+`azure.login` asks for those claims up front, and `arm` answers a challenge
+silently if one still comes. The user does MFA once, at sign-in, as the portal
+makes them.
+
+⚠ **School and work tenants often block `--device-code`.** Microsoft's managed
+Conditional Access policy against device-code phishing answers
+`AADSTS53003` *"does not meet the criteria"* after a successful sign-in, and
+the device-code flow then polls until its code expires (about 15 minutes):
+Ctrl-C. Use the browser flow, which the same policy allows. Measured on a
+school tenant (Azure for Students), 2026-10-07: device code refused, browser
+admitted, VM created, SSH in, deleted.
+
+Two browser-flow traps, both with a fix on screen:
+
+- **The redirect has to reach this process.** The sign-in URL is printed as
+  well as opened. Open it in the browser you actually sign in with; if you sign
+  in in some other tab, nothing comes back and `azure.login` times out after 5
+  minutes.
+- **`state mismatch: … vs None`** means an *old* `localhost:8400` tab (a
+  previous *"Authentication complete"* page, reloaded or restored) answered
+  first. Close every such tab and run `azure.login` again.
+
+`azure-identity` signs in as the Azure CLI's public client
+(`04b07795-8ddb-461a-bbee-02f9e1bf7b46`), so a tenant that blocks `az` outright
+blocks this too.
+
+## What "free" means here
+
+An Azure free account gives, for its first 12 months, **750 hours a month** of
+each of `Standard_B1s`, `Standard_B2ats_v2` (AMD) and `Standard_B2pts_v2` (Arm).
+That's one VM running all month. It also gives **two 64 GiB P6 managed disks**.
+Azure for Students carries the same free services. Everything else bills:
+
+| | a portal or `az vm create` default | here |
+|---|---|---|
+| OS disk | 30 GiB → billed as **P4**, a meter the offer does not cover | **64 GiB Premium SSD = P6**, the free one |
+| size | `Standard_DS1_v2` and friends | `Standard_B1s`; anything outside the three is refused |
+| resource group | one you name, shared | `<name>-rg`, one per VM, so `delete` takes all of it |
+| public IP | Standard static IPv4 | the same, **and it is billed** (about $3.65 a month) |
+
+⚠ **The public IPv4 is the one cost.** Basic public IPs, which the free account
+used to cover, were retired on 2025-09-30, and a Standard IPv4 bills by the hour
+whether or not the VM runs. `--no-public-ip` leaves it out; the VM is then
+reachable only from inside its network.
+
+⚠ **A pay-as-you-go subscription takes the same request and pays for it.**
+`azure.vm` reads the subscription's offer (`quotaId`) and refuses anything but
+a free account or Azure for Students. A free account upgraded to pay-as-you-go
+keeps its free hours until month 12 but reports the paid offer; `--paid-ok` is
+for that case.
+
+It also refuses, before creating anything: a sign-in that reaches no
+subscription, or several when none is named; a region that will not sell the
+size to this subscription (free accounts are often restricted in busy regions,
+so try another `--location`); and a name already taken. A second VM of the
+same size is allowed, with a warning: two running all month exceed the 750 hours.
+
+## How it talks to Azure
+
+Plain REST to Resource Manager through `make.http`, with a bearer token from
+`azure-identity`. No `azure-mgmt-*` SDKs. The VM is **one template
+deployment** (`template.py`): network, NSG, IP, NIC and VM in a single request.
+Azure works out the order, and a failure reports Azure's own reason
+(`SkuNotAvailable: …`). `azure-identity` is imported only when a token is
+needed, so `mk --list` never pays its import time.
+
+## Settings
+
+`Azure.configure(...)` in the task file, an `[azure]` table in the config file,
+or `MAKE_AZURE_<FIELD>` in the environment:
+
+| field | default | |
+|---|---|---|
+| `tenant` | the only one `azure.login` saved | tenant id or domain |
+| `subscription` | the only one the sign-in reaches | id or display name |
+| `location` | `westeurope` | any region with B-series capacity |
+| `size` | `Standard_B1s` | one of the three free sizes |
+| `admin` | `azureuser` | the login user |
+| `ssh_key` | `~/.ssh/id_ed25519.pub`, then `id_rsa.pub` | the public key the VM accepts |
+
+The group is `azure`, and it merges with a repo's own `azure.*` tasks; this
+package claims `login`, `account`, `vm`, `vms` and `delete`, nothing else.

make_azure-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "make-azure"
+version = "0.2.0"
+description = "Azure tasks for mkrun -- sign in with azure-identity, and create a free-tier virtual machine with nothing billed left behind."
+readme = "README.md"
+requires-python = ">=3.11"
+# Same dual licence as mkrun, for the same reason: this member is generic and
+# publishable. The licence texts live at the repository root; a built wheel
+# carries the SPDX expression, which is what PEP 639 asks for.
+license = "MIT OR Apache-2.0"
+authors = [{ name = "Optersoft, S.L.", email = "david@optersoft.com" }]
+keywords = ["azure", "virtual machine", "free tier", "az", "mk", "mkrun"]
+# azure-identity owns the sign-in (MSAL, the encrypted token cache) and nothing
+# else: the API calls are plain REST through `make.http`. Not the azure-mgmt-*
+# SDKs -- three more packages and a slow import to wrap about six URLs. It is
+# imported lazily, so `mk --list` never pays for it.
+dependencies = ["mkrun>=0.4.1", "azure-identity>=1.16"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/make_azure"]
+
+[project.urls]
+Homepage = "https://make.optersoft.com"
+
+# The runner is the other half of this repository, so resolve it from the
+# working tree instead of PyPI, exactly as the other members do.
+[tool.uv.sources]
+mkrun = { workspace = true }
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+# No [tool.ruff] here on purpose: every member shares the root config, so they
+# cannot drift apart by an isort option.

make_azure-0.2.0/src/make_azure/__init__.py

@@ -0,0 +1,30 @@
+"""Azure tasks for mkrun -- the `azure` group.
+
+Today it is one thing: a virtual machine on Azure's free tier. `azure.login`
+signs in (azure-identity, no `az` CLI), `azure.vm` creates the VM, `azure.vms`
+lists them, `azure.delete` removes one with everything it made, `azure.account`
+says whether the subscription carries free services.
+
+Importing is what registers it:
+
+    # Makefile.py
+    from make_azure import azure
+
+The group merges with a repo's own `azure.*` tasks -- groups are namespaces,
+and this package claims only the five names above.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+__all__ = ["arm", "auth", "azure", "template", "vm"]
+
+
+def __getattr__(name: str):
+    """Import on first access, keeping module scope import-free -- startup is a feature."""
+    if name in __all__:
+        import importlib
+
+        return importlib.import_module(f".{name}", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

make_azure-0.2.0/src/make_azure/arm.py

@@ -0,0 +1,207 @@
+"""Azure Resource Manager over plain HTTPS, through `make.http`.
+
+Every call is `https://management.azure.com/<path>?api-version=<v>` with a
+bearer token from `auth`. Three things ARM does that a naive client misses:
+
+- **Errors come in an envelope**: `{"error": {"code", "message", "details"}}`.
+  The code is the thing to read (`SkuNotAvailable`, `InvalidTemplateDeployment`,
+  `AuthorizationFailed`), so it leads the message.
+- **Long operations answer 201/202 and keep going.** A deployment is polled until
+  its `provisioningState` is terminal; a delete is polled at its `Location`
+  header until that stops answering 202.
+- **Lists page**: a `nextLink` is followed until there is none.
+
+Under `--dry-run` nothing is sent and every call returns `None`, which callers
+read as "unknown" -- a dry run prints the whole plan, as `make_cloudflare.pages`
+does.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+from urllib.parse import urlencode
+
+from make import http, note
+from make.errors import MakeError
+
+from . import auth
+
+__all__ = ["BASE", "call", "collect", "wait_deployment", "wait_location"]
+
+BASE = "https://management.azure.com"
+
+#: How long to wait for a VM deployment or a group delete before giving up.
+TIMEOUT = 20 * 60
+
+
+class _Token:
+    """One token per task run: fetched on first use, reused after."""
+
+    value: str | None = None
+    tenant: str | None = None
+
+
+def _bearer(tenant: str, claims: str | None = None) -> str:
+    if claims or _Token.value is None or _Token.tenant != tenant:
+        _Token.value, _Token.tenant = auth.token(tenant, claims=claims), tenant
+    return _Token.value
+
+
+def _challenge(answer: http.Response) -> str | None:
+    """The claims a 401 asks for, decoded -- ARM's way of saying "do MFA first"."""
+    import base64
+    import re
+
+    header = answer.headers.get("www-authenticate", "")
+    if answer.status != 401 or "insufficient_claims" not in header:
+        return None
+    found = re.search(r'claims="([^"]+)"', header)
+    if not found:
+        return None
+    encoded = found.group(1)
+    try:
+        return base64.b64decode(encoded + "=" * (-len(encoded) % 4)).decode()
+    except ValueError:
+        return None
+
+
+def reset() -> None:
+    _Token.value = _Token.tenant = None
+
+
+def url(path: str, api_version: str, **query: str) -> str:
+    return f"{BASE}{path}?" + urlencode({"api-version": api_version, **query})
+
+
+def request(method: str, target: str, *, tenant: str = "", body: Any = None) -> http.Response | None:
+    """One request to a full URL; `None` under `--dry-run`. Raises on an ARM error."""
+    from make.context import current
+
+    # A dry run sends nothing, so it needs no sign-in either: the plan prints on a
+    # machine that has never run `azure.login`.
+    bearer = "<token>" if current().dry_run else _bearer(tenant)
+    headers = {"Authorization": f"Bearer {bearer}"}
+    data = None
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+        data = json.dumps(body).encode()
+    answer = http.request(target, method=method, headers=headers, data=data, timeout=120.0)
+    if answer.skipped:
+        return None
+    claims = _challenge(answer)
+    if claims:
+        # Reads pass without MFA; a write gets this. Answer it once, silently, and
+        # retry; a second refusal is a real one and is raised below.
+        headers["Authorization"] = f"Bearer {_bearer(tenant, claims)}"
+        answer = http.request(target, method=method, headers=headers, data=data, timeout=120.0)
+    if answer.status == 0:
+        raise MakeError(f"{method} {target.split('?')[0]}: no answer from Azure")
+    if answer.status >= 400 and answer.status != 404:
+        error = _error(method, target, answer)
+        if _challenge(answer):
+            error.hint = "Azure wants MFA for this; `mk azure.login` signs in with it"
+        raise error
+    return answer
+
+
+def call(
+    method: str,
+    path: str,
+    api_version: str,
+    *,
+    tenant: str = "",
+    body: Any = None,
+    missing_ok: bool = False,
+    **query: str,
+) -> Any:
+    """One ARM call, returning the parsed body. A 404 is `None` when `missing_ok`."""
+    answer = request(method, url(path, api_version, **query), tenant=tenant, body=body)
+    if answer is None:
+        return None
+    if answer.status == 404:
+        if missing_ok:
+            return None
+        raise _error(method, answer.url, answer)
+    return _json(answer)
+
+
+def collect(path: str, api_version: str, *, tenant: str = "", **query: str) -> list[dict] | None:
+    """Every item of a list, across pages; `None` under `--dry-run`."""
+    found: list[dict] = []
+    target: str | None = url(path, api_version, **query)
+    while target:
+        answer = request("GET", target, tenant=tenant)
+        if answer is None:
+            return None
+        page = _json(answer)
+        found.extend(page.get("value") or [])
+        target = page.get("nextLink")
+    return found
+
+
+def wait_deployment(
+    path: str, api_version: str, *, tenant: str = "", timeout: float = TIMEOUT
+) -> dict | None:
+    """Poll a deployment until it succeeds; raise with Azure's own reason if it does not."""
+    started = time.monotonic()
+    last = ""
+    while True:
+        found = call("GET", path, api_version, tenant=tenant)
+        if found is None:
+            return None
+        state = (found.get("properties") or {}).get("provisioningState", "?")
+        if state == "Succeeded":
+            return found
+        if state in ("Failed", "Canceled"):
+            error = (found.get("properties") or {}).get("error") or {}
+            raise MakeError(f"deployment {state.lower()}: {_describe(error)}")
+        elapsed = time.monotonic() - started
+        if elapsed > timeout:
+            raise MakeError(
+                f"deployment still {state} after {elapsed / 60:.0f} minutes", hint="see the portal"
+            )
+        if state != last:
+            note(f"{state.lower()}...")
+            last = state
+        time.sleep(5)
+
+
+def wait_location(answer: http.Response | None, *, tenant: str = "", timeout: float = TIMEOUT) -> None:
+    """Follow a 202's `Location` until the operation stops answering 202."""
+    if answer is None or answer.status != 202:
+        return
+    location = answer.headers.get("location") or answer.headers.get("azure-asyncoperation")
+    if not location:
+        return
+    started = time.monotonic()
+    while True:
+        time.sleep(min(int(answer.headers.get("retry-after", "10") or 10), 30))
+        answer = request("GET", location, tenant=tenant)
+        if answer is None or answer.status != 202:
+            return
+        if time.monotonic() - started > timeout:
+            raise MakeError(f"still running after {timeout / 60:.0f} minutes", hint="see the portal")
+
+
+def _json(answer: http.Response) -> Any:
+    try:
+        return json.loads(answer.body) if answer.body.strip() else {}
+    except ValueError:
+        return {}
+
+
+def _describe(error: dict) -> str:
+    """`Code: message`, descending into `details` -- where the useful reason usually is."""
+    parts = [f"{error.get('code', '?')}: {error.get('message', '')}".strip()]
+    for detail in error.get("details") or []:
+        parts.append(_describe(detail))
+    return "; ".join(p for p in parts if p and p != "?:")
+
+
+def _error(method: str, target: str, answer: http.Response) -> MakeError:
+    payload = _json(answer)
+    error = payload.get("error") if isinstance(payload, dict) else None
+    detail = _describe(error) if isinstance(error, dict) else answer.body[:300]
+    return MakeError(f"{method} {target.split('?')[0].removeprefix(BASE)} -> {answer.status}: {detail}")