nm-portal-cli 0.2.1__py3-none-any.whl

nama/__init__.py

@@ -0,0 +1,3 @@
+"""``nama``: the NM portal from a terminal."""
+
+__version__ = "0.2.1"

nama/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from nama.cli import main
+
+sys.exit(main())

nama/cli.py

@@ -0,0 +1,305 @@
+"""The ``nama`` command."""
+from __future__ import annotations
+
+import argparse
+import sys
+import urllib.parse
+from datetime import datetime
+from pathlib import Path
+
+from nama import __version__, download, portal as portal_api, signin, store, terminal
+
+#: A job in one of these states may still be writing its results.
+UNFINISHED = ("queued", "running", "cancelling")
+#: How the states a job stops in read after "job <id>".
+ENDED = {"failed": "failed", "cancelled": "was cancelled"}
+#: The archive's name in the job's folder, and the name it is saved under.
+ARCHIVE_NAME = "results.tar.gz"
+
+
+def _login(args) -> int:
+    portal = portal_api.normalize(args.portal)
+    if args.local:
+        entry = {"kind": "local", "token": portal_api.local_token(portal)}
+    else:
+        entry = signin.sign_in(portal)
+    store.put(portal, entry, make_default=True)
+    who = f" as {entry['email']}" if entry.get("email") else ""
+    terminal.say(f"Signed in to {portal}{who}.")
+    return 0
+
+
+def _logout(args) -> int:
+    portal, entry = store.get(_portal_arg(args))
+    problem = None
+    if entry["kind"] == "cognito":
+        try:
+            signin.revoke(entry)
+        except signin.SignInError as exc:
+            problem = exc
+    store.remove(portal)
+    terminal.say(f"Signed out of {portal}.")
+    if problem is not None:
+        terminal.say(f"nama: the portal did not take back the sign-in ({problem}); it "
+                     "stays usable until it expires", err=True)
+        return 1
+    return 0
+
+
+def _status(args) -> int:
+    portal, token = _signed_in(_portal_arg(args))
+    job = _api(portal, token, "GET", f"/api/jobs/{portal_api.segment(args.job_id)}")
+    rows = [
+        ("job", job["job_id"] + (f"  ({job['job_name']})" if job.get("job_name") else "")),
+        ("status", job["status"] + (f"  ({job['step']})" if job.get("step") else "")),
+        ("tool", job.get("tool_id")),
+        ("machine", job.get("target_id")),
+        ("submitted", _when(job.get("submitted_at"))),
+        ("finished", _when(job.get("finished_at"))),
+        ("error", job.get("error")),
+    ]
+    for label, value in rows:
+        if value:
+            terminal.say(f"{label:<10} {value}")
+    return 0
+
+
+def _jobs(args) -> int:
+    portal, token = _signed_in(_portal_arg(args))
+    query = urllib.parse.urlencode({"limit": args.limit, "offset": args.offset})
+    listing = _api(portal, token, "GET", f"/api/jobs?{query}")
+    jobs, total = listing["jobs"], listing.get("total")
+    if not jobs:
+        terminal.say("No jobs." if args.offset == 0 else
+                     f"No jobs past the first {args.offset}.")
+        return 0
+
+    names = listing.get("names") or {}
+    rows = [("JOB", "STATUS", "TOOL", "MACHINE", "SUBMITTED", "NAME")]
+    for job in jobs:
+        target = job.get("target_id")
+        rows.append(tuple(terminal.safe(cell) for cell in (
+            job["job_id"],
+            job["status"] + (f" ({job['step']})" if job.get("step") else ""),
+            job.get("tool_id") or "",
+            names.get(target, target) or "",
+            _when(job.get("submitted_at"), "%Y-%m-%d %H:%M") or "",
+            job.get("job_name") or "",
+        )))
+    widths = [max(len(row[i]) for row in rows) for i in range(len(rows[0]) - 1)]
+    for row in rows:
+        terminal.say(("  ".join(cell.ljust(w) for cell, w in zip(row, widths)) + "  "
+                      + row[-1]).rstrip())
+
+    last = args.offset + len(jobs)
+    footer = f"\n{args.offset + 1}-{last}" + (f" of {total}" if total is not None else "")
+    if total is not None and last < total:
+        portal_flag = f" --portal {portal}" if args.portal else ""
+        footer += f"; `nama jobs --offset {last}{portal_flag}` for older ones"
+    terminal.say(footer)
+    return 0
+
+
+def _download(args) -> int:
+    portal, token = _signed_in(_portal_arg(args))
+    job_path = f"/api/jobs/{portal_api.segment(args.job_id)}"
+    job = _api(portal, token, "GET", job_path)
+    job_id, state = job["job_id"], job["status"]
+    if state in UNFINISHED:
+        raise download.DownloadError(f"job {job_id} is {state}; download it once it "
+                                     "has finished")
+    folder = Path(job_id)
+    if args.archive:
+        return _download_archive(job, folder)
+
+    listing = _api(portal, token, "GET", f"{job_path}/results")
+    if listing.get("truncated"):
+        limit = listing.get("limit")
+        instead = (f"; `nama download {job_id} --archive` saves the archive of all of "
+                   "them" if job.get("download_url") else
+                   ", and it has no archive to save instead")
+        raise download.DownloadError(
+            f"job {job_id} has more result files than the portal lists at once"
+            f"{f' ({limit:,})' if isinstance(limit, int) else ''}, so none were saved"
+            f"{instead}")
+    files = listing["files"]
+    if not files:
+        terminal.say(f"Job {job_id} has no files under results/.")
+        return 0
+    if state != "done":
+        terminal.say(f"nama: job {job_id} {_ended(state)}; saving what it wrote before "
+                     "it stopped", err=True)
+
+    targets = [(f, download.local_path(folder, f["path"])) for f in files]
+    saved, saved_bytes = 0, 0
+    for listed, target in targets:
+        size = listed["size_bytes"]
+        if download.same_size(target, size):
+            continue
+        terminal.say(f"{listed['path']}  {download.human(size)}")
+        # A download can outlast the hour a token lasts.
+        _, token = _signed_in(portal)
+        link = _api(portal, token, "GET",
+                    f"{job_path}/results/{download.link_path(listed['path'])}")
+        if link["size_bytes"] != size:
+            raise download.DownloadError(
+                f"results/{listed['path']} was {size} bytes when listed and "
+                f"{link['size_bytes']} when its link was made; it was not saved")
+        with download.open_link(link["url"], listed["path"]) as resp:
+            download.write(resp, target, size)
+        saved, saved_bytes = saved + 1, saved_bytes + size
+
+    skipped = len(targets) - saved
+    if saved:
+        already = f"; {_count(skipped, 'file')} already there" if skipped else ""
+        terminal.say(f"Saved {_count(saved, 'file')} ({download.human(saved_bytes)}) to "
+                     f"{folder}/{already}.")
+    else:
+        terminal.say(f"All {_count(skipped, 'file')} already in {folder}/.")
+    return 0
+
+
+def _download_archive(job: dict, folder: Path) -> int:
+    job_id, state = job["job_id"], job["status"]
+    url = job.get("download_url")
+    if not url:
+        why = (f"job {job_id} has no archive" if state == "done" else
+               f"job {job_id} {_ended(state)}, and only a job that is done has an archive")
+        raise download.DownloadError(f"{why}; without --archive, `nama download` "
+                                     "saves its files one by one")
+    target = folder / ARCHIVE_NAME
+    with download.open_link(url, ARCHIVE_NAME) as resp:
+        size = download.length(resp)
+        if download.same_size(target, size):
+            terminal.say(f"{target} is already here.")
+            return 0
+        terminal.say(ARCHIVE_NAME
+                     + (f"  {download.human(size)}" if size is not None else ""))
+        download.write(resp, target, size)
+    terminal.say(f"Saved {target}.")
+    return 0
+
+
+def _ended(state: str) -> str:
+    return ENDED.get(state, f"is {state}")
+
+
+def _count(n: int, noun: str) -> str:
+    return f"{n} {noun}" + ("" if n == 1 else "s")
+
+
+def _portal_arg(args) -> str | None:
+    return portal_api.normalize(args.portal) if args.portal else None
+
+
+def _signed_in(portal: str | None) -> tuple[str, str]:
+    """The portal to use and a token for it, renewing the kept sign-in if due."""
+    portal, entry = store.get(portal)
+    try:
+        fresh = signin.renewed(entry)
+    except signin.SignInExpired as exc:
+        raise signin.SignInError(f"{exc}; run `nama login {portal}`") from None
+    if fresh is not entry:
+        store.put(portal, fresh, make_default=False)
+    return portal, signin.token(fresh)
+
+
+def _api(portal: str, token: str, method: str, path: str) -> dict:
+    try:
+        return portal_api.request(portal, token, method, path)
+    except portal_api.ApiError as exc:
+        if exc.status == 401:
+            raise portal_api.ApiError(401, f"{portal} did not accept the sign-in "
+                                           f"({exc.message}); run `nama login {portal}`") from None
+        raise
+
+
+def _when(epoch: float | None, fmt: str = "%Y-%m-%d %H:%M:%S %Z") -> str | None:
+    if epoch is None:
+        return None
+    return datetime.fromtimestamp(epoch).astimezone().strftime(fmt)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="nama", description="The NM portal from a terminal.")
+    parser.add_argument("--version", action="version", version=f"nama {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    login = commands.add_parser(
+        "login", help="sign in to a portal",
+        description="Sign in to a portal through its sign-in page. The portal becomes "
+                    "the one other commands use when none is named.")
+    login.add_argument("portal", help="the portal's address, e.g. https://nm-portal.example.com")
+    # For developers: a local portal, which has no sign-in page.
+    login.add_argument("--local", action="store_true", help=argparse.SUPPRESS)
+    login.set_defaults(run=_login)
+
+    portal_help = "the portal's address; by default the one last signed in to"
+
+    logout = commands.add_parser("logout", help="sign out of a portal")
+    logout.add_argument("--portal", help=portal_help)
+    logout.set_defaults(run=_logout)
+
+    status = commands.add_parser("status", help="show a job's status")
+    status.add_argument("job_id")
+    status.add_argument("--portal", help=portal_help)
+    status.set_defaults(run=_status)
+
+    jobs = commands.add_parser(
+        "jobs", help="list your jobs, newest first",
+        description="List your jobs on the portal, newest first, a page at a time.")
+    jobs.add_argument("--limit", type=_positive, default=10,
+                      help="how many jobs to list (default 10)")
+    jobs.add_argument("--offset", type=_not_negative, default=0,
+                      help="how many of the newest jobs to pass over (default 0)")
+    jobs.add_argument("--portal", help=portal_help)
+    jobs.set_defaults(run=_jobs)
+
+    fetch = commands.add_parser(
+        "download", help="save a job's results to this machine",
+        description="Save every file under a finished job's results/ into ./<job id>/ "
+                    "here, one by one. A file already there at the same size is "
+                    "passed over, so running it again picks up where it stopped.")
+    fetch.add_argument("job_id")
+    fetch.add_argument("--archive", action="store_true",
+                       help=f"save the job's single archive instead, as "
+                            f"./<job id>/{ARCHIVE_NAME}")
+    fetch.add_argument("--portal", help=portal_help)
+    fetch.set_defaults(run=_download)
+    return parser
+
+
+def _positive(value: str) -> int:
+    return _whole(value, 1)
+
+
+def _not_negative(value: str) -> int:
+    return _whole(value, 0)
+
+
+def _whole(value: str, least: int) -> int:
+    try:
+        n = int(value)
+    except ValueError:
+        n = None
+    if n is None or n < least:
+        raise argparse.ArgumentTypeError(f"{value!r} is not a whole number of {least} "
+                                         "or more")
+    return n
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        return args.run(args)
+    except (store.NotSignedIn, store.StoreError, signin.SignInError,
+            portal_api.ApiError, portal_api.AddressError, download.DownloadError) as exc:
+        terminal.say(f"nama: {exc}", err=True)
+        return 1
+    except KeyboardInterrupt:
+        terminal.say("\nnama: stopped", err=True)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nama/download.py

@@ -0,0 +1,94 @@
+"""Saving a job's files to this machine.
+
+The files come straight from storage, through links the portal signs, and
+never pass through the portal. Each is written under a temporary name beside
+its own and renamed once every byte has arrived, so a file under its own name
+is whole.
+"""
+from __future__ import annotations
+
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from http.client import HTTPException, HTTPResponse
+from pathlib import Path
+
+from nama import portal as portal_api
+
+CHUNK_BYTES = 1 << 20
+PARTIAL_SUFFIX = ".part"
+
+
+class DownloadError(Exception):
+    """A file could not be saved whole."""
+
+
+def link_path(listed: str) -> str:
+    """A path from a results listing as it goes in the address that asks for
+    its link: each part encoded on its own, the slashes kept."""
+    return "/".join(urllib.parse.quote(part, safe="") for part in listed.split("/"))
+
+
+def local_path(folder: Path, listed: str) -> Path:
+    """Where a file the portal listed is saved, inside ``folder``. Refuses a
+    path that would land outside it."""
+    parts = listed.split("/")
+    if "\\" in listed or any(part in ("", ".", "..") for part in parts):
+        raise DownloadError(f"the portal listed {listed!r}, which is not a path "
+                            "inside the job's folder; nothing more is saved")
+    return folder.joinpath(*parts)
+
+
+def open_link(url: str, name: str) -> HTTPResponse:
+    """Start fetching a signed storage link. No Authorization header: storage
+    refuses a signed link that also carries one."""
+    try:
+        return urllib.request.urlopen(url, timeout=portal_api.TIMEOUT_SECONDS)
+    except urllib.error.HTTPError as exc:
+        raise DownloadError(f"storage refused {name}: {exc.code} {exc.reason}") from None
+    except urllib.error.URLError as exc:
+        raise DownloadError(f"cannot reach storage for {name}: {exc.reason}") from None
+
+
+def length(resp: HTTPResponse) -> int | None:
+    value = resp.headers.get("Content-Length")
+    return int(value) if value is not None else None
+
+
+def write(resp: HTTPResponse, target: Path, size: int | None) -> None:
+    """Stream ``resp`` into ``target``, checking the byte count against
+    ``size`` when there is one."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    partial = target.with_name(target.name + PARTIAL_SUFFIX)
+    written = 0
+    try:
+        with open(partial, "wb") as out:
+            while chunk := resp.read(CHUNK_BYTES):
+                out.write(chunk)
+                written += len(chunk)
+        if size is not None and written != size:
+            raise DownloadError(f"{target} arrived with {written} bytes of {size}; "
+                                "it was not saved")
+        os.replace(partial, target)
+    except (OSError, HTTPException) as exc:
+        partial.unlink(missing_ok=True)
+        raise DownloadError(f"{target} was not saved: {exc}") from None
+    except BaseException:
+        partial.unlink(missing_ok=True)
+        raise
+
+
+def same_size(target: Path, size: int | None) -> bool:
+    """Whether ``target`` is already here at ``size`` bytes."""
+    return size is not None and target.is_file() and target.stat().st_size == size
+
+
+def human(size: int) -> str:
+    """A byte count for reading: 8.4 MB, 512 bytes."""
+    value = float(size)
+    for unit in ("bytes", "KB", "MB", "GB", "TB"):
+        if value < 1000 or unit == "TB":
+            break
+        value /= 1000
+    return f"{size} bytes" if unit == "bytes" else f"{value:.1f} {unit}"

nama/portal.py

@@ -0,0 +1,102 @@
+"""Requests to a portal, over its public addresses and its API."""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+#: Long enough for a slow answer, short enough that a portal that has stopped
+#: answering shows as an error rather than a command that never returns.
+TIMEOUT_SECONDS = 30
+
+#: The only hosts nama reaches over plain http: this machine, where a local
+#: portal runs. Anywhere else the sign-in would cross the network unencrypted.
+LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1")
+
+
+class ApiError(RuntimeError):
+    """A portal's refusal or failure, with the status it answered (0 when it
+    could not be reached)."""
+
+    def __init__(self, status: int, message: str):
+        super().__init__(f"{status}: {message}" if status else message)
+        self.status = status
+        self.message = message
+
+
+class AddressError(ValueError):
+    """Something given as a portal's address that is not one."""
+
+
+class _Unfollowed(urllib.request.HTTPRedirectHandler):
+    """Refuses every redirect: Python sends a request's headers, the sign-in
+    among them, on to wherever a redirect points."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        fp.close()
+        raise ApiError(code, f"{req.full_url} redirects to {newurl}; nama does not "
+                             "follow a redirect, so as not to send the sign-in there")
+
+
+_OPENER = urllib.request.build_opener(_Unfollowed)
+
+
+def normalize(address: str) -> str:
+    """A portal's address as it is kept: scheme, host and port. Anything after
+    them, such as the page a browser was showing, is not part of it."""
+    split = urllib.parse.urlsplit(address.strip())
+    try:
+        split.port
+    except ValueError:
+        split = None
+    if (split is None or split.scheme not in ("http", "https") or not split.hostname
+            or split.username is not None):
+        raise AddressError(f"{address!r} is not a portal's address; give it whole, "
+                           "as https://... or, for a local portal, http://localhost:...")
+    if split.scheme == "http" and split.hostname not in LOCAL_HOSTS:
+        raise AddressError(f"{address} is not encrypted, and the sign-in goes with every "
+                           f"request; use https://{split.netloc}")
+    return f"{split.scheme}://{split.netloc}"
+
+
+def site_config(portal: str) -> dict:
+    """The settings the portal gives its website, which name its sign-in page."""
+    return request(portal, None, "GET", "/config.json")
+
+
+def local_token(portal: str) -> str:
+    """The token a local portal takes: it has no sign-in page."""
+    return request(portal, None, "GET", "/local")["token"]
+
+
+def request(portal: str, token: str | None, method: str, path: str) -> dict:
+    """Return the parsed JSON answer, or raise ApiError. A redirect is refused."""
+    headers = {"Accept": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    req = urllib.request.Request(f"{portal}{path}", headers=headers, method=method)
+    try:
+        with _OPENER.open(req, timeout=TIMEOUT_SECONDS) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as exc:
+        raw = exc.read()
+        try:
+            parsed = json.loads(raw.decode("utf-8"))
+            message = parsed.get("error") or parsed.get("message") or str(parsed)
+        except (ValueError, AttributeError):
+            message = raw.decode("utf-8", "replace").strip() or exc.reason
+        raise ApiError(exc.code, message) from None
+    except urllib.error.URLError as exc:
+        raise ApiError(0, f"cannot reach {portal}: {exc.reason}") from None
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except ValueError:
+        raise ApiError(0, f"{portal}{path} did not answer with JSON") from None
+
+
+def segment(value: str) -> str:
+    """One path segment, percent-encoded."""
+    return urllib.parse.quote(value, safe="")

nama/signin.py

@@ -0,0 +1,285 @@
+"""Signing in through a portal's sign-in page, as its website does: the
+authorization code flow with PKCE (Proof Key for Code Exchange).
+
+The command makes a one-time secret, sends the person's browser to the sign-in
+page with a hash of it, and listens on a fixed port of this machine for the
+browser to be sent back with a code. Only the holder of the secret can turn
+that code into tokens. When the browser is on another machine, the address it
+is sent back to does not load there, and the person pastes it here instead.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import queue
+import secrets
+import sys
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from nama import portal as portal_api, terminal
+
+#: The portal's sign-in settings for nama list this address and no other, so
+#: the port cannot move.
+CALLBACK_PORT = 18780
+CALLBACK_URL = f"http://localhost:{CALLBACK_PORT}/"
+SCOPES = "openid email profile"
+
+#: A sign-in's ID token is renewed when it has less than this left.
+RENEW_BEFORE_SECONDS = 120
+
+
+class SignInError(Exception):
+    """Signing in, renewing or signing out did not succeed."""
+
+
+class SignInExpired(SignInError):
+    """The sign-in can no longer be renewed; the person signs in again."""
+
+
+class _Refused(SignInError):
+    """The sign-in service's refusal, with its OAuth error code."""
+
+    def __init__(self, message: str, error: str):
+        super().__init__(message)
+        self.error = error
+
+
+def sign_in(portal: str) -> dict:
+    """Sign in to ``portal`` and return the sign-in to keep."""
+    config = portal_api.site_config(portal)
+    client_id = config.get("cliClientId")
+    if not client_id:
+        hint = (" It is a local portal: use `nama login --local`."
+                if config.get("userPoolClientId") == "local" else "")
+        raise SignInError(f"{portal} does not offer command-line sign-in: its "
+                          f"config.json names no cliClientId.{hint}")
+    domain = config.get("cognitoDomainUrl")
+    if not isinstance(domain, str) or not domain.startswith("https://"):
+        raise SignInError(f"{portal} names its sign-in page as {domain!r}, which is not "
+                          "an https:// address; nama signs in only over an encrypted "
+                          "connection")
+    domain = domain.rstrip("/")
+
+    verifier = secrets.token_urlsafe(64)
+    challenge = _b64(hashlib.sha256(verifier.encode("ascii")).digest())
+    state = secrets.token_urlsafe(24)
+    address = f"{domain}/oauth2/authorize?" + urllib.parse.urlencode({
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": CALLBACK_URL,
+        "scope": SCOPES,
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    })
+
+    returned = _wait_for_return(portal, address)
+    code = _code_from(returned, state)
+    tokens = _token_request(domain, {
+        "grant_type": "authorization_code",
+        "client_id": client_id,
+        "code": code,
+        "redirect_uri": CALLBACK_URL,
+        "code_verifier": verifier,
+    })
+    claims = _claims(tokens["id_token"])
+    return {
+        "kind": "cognito",
+        "cognito_domain": domain,
+        "client_id": client_id,
+        "email": claims.get("email"),
+        "id_token": tokens["id_token"],
+        "refresh_token": tokens["refresh_token"],
+        "expires_at": claims["exp"],
+    }
+
+
+def renewed(entry: dict) -> dict:
+    """The sign-in with an ID token that has time left, renewed if need be.
+    Returns the same dict when nothing changed."""
+    if entry["kind"] == "local" or entry["expires_at"] - time.time() > RENEW_BEFORE_SECONDS:
+        return entry
+    tokens = _token_request(entry["cognito_domain"], {
+        "grant_type": "refresh_token",
+        "client_id": entry["client_id"],
+        "refresh_token": entry["refresh_token"],
+    })
+    return {
+        **entry,
+        "id_token": tokens["id_token"],
+        "refresh_token": tokens.get("refresh_token") or entry["refresh_token"],
+        "expires_at": _claims(tokens["id_token"])["exp"],
+    }
+
+
+def token(entry: dict) -> str:
+    return entry["token"] if entry["kind"] == "local" else entry["id_token"]
+
+
+def revoke(entry: dict) -> None:
+    """Cancel the sign-in with the portal, so its renewal token stops working."""
+    _post(f"{entry['cognito_domain']}/oauth2/revoke", {
+        "token": entry["refresh_token"],
+        "client_id": entry["client_id"],
+    })
+
+
+def _wait_for_return(portal: str, address: str) -> str:
+    """The address the browser was sent back to, from the listener or pasted."""
+    answers: queue.Queue = queue.Queue()
+    server = _listen(answers)
+    _say(f"Sign in to {portal} in a browser, at this address:")
+    _say()
+    _say(f"  {address}")
+    _say()
+    if server is None:
+        _say(f"(Port {CALLBACK_PORT} is in use on this machine, so nama cannot see the")
+        _say(" browser come back; paste the address as below.)")
+    _say("If the browser is on another machine, it ends on a page that does not")
+    _say("load. Copy that page's address from the address bar and paste it here.")
+    if server is not None and _has_own_browser():
+        webbrowser.open(address)
+
+    threading.Thread(target=_read_pasted, args=(answers,), daemon=True).start()
+    try:
+        while True:
+            source, text = answers.get()
+            if source == "eof":
+                if server is None:
+                    raise SignInError("nothing to read the address from: the port is in "
+                                      "use and nothing can be pasted here")
+                continue
+            if source == "pasted" and not ("code=" in text or "error=" in text):
+                if text:
+                    _say("That is not the address the sign-in ended on. Paste the whole "
+                        "address from the browser's address bar.")
+                continue
+            return text
+    finally:
+        if server is not None:
+            server.shutdown()
+            server.server_close()
+
+
+def _listen(answers: queue.Queue) -> HTTPServer | None:
+    class Return(BaseHTTPRequestHandler):
+        def do_GET(self):
+            query = urllib.parse.urlsplit(self.path).query
+            if not ("code=" in query or "error=" in query):
+                self.send_error(404)
+                return
+            answers.put(("listener", query))
+            body = (b"<!doctype html><title>nama</title><p>Back with nama. You can "
+                    b"close this tab; the terminal says whether signing in worked.</p>")
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *args):
+            pass
+
+    try:
+        server = HTTPServer(("127.0.0.1", CALLBACK_PORT), Return)
+    except OSError:
+        return None
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server
+
+
+def _read_pasted(answers: queue.Queue) -> None:
+    # os.read, not sys.stdin: a thread still blocked in sys.stdin's buffered
+    # reader when the command ends makes Python abort at exit.
+    pending = b""
+    while True:
+        try:
+            chunk = os.read(0, 4096)
+        except OSError:
+            chunk = b""
+        if not chunk:
+            answers.put(("eof", None))
+            return
+        pending += chunk
+        while b"\n" in pending:
+            line, pending = pending.split(b"\n", 1)
+            answers.put(("pasted", line.decode("utf-8", "replace").strip()))
+
+
+def _say(text: str = "") -> None:
+    terminal.say(text, err=True)
+
+
+def _has_own_browser() -> bool:
+    """Whether a browser opened here would be in front of the person. Over SSH
+    it would not, and Python could start a text browser in the terminal."""
+    if os.environ.get("SSH_CONNECTION"):
+        return False
+    if sys.platform in ("darwin", "win32"):
+        return True
+    return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+
+def _code_from(returned: str, state: str) -> str:
+    query = returned.split("?", 1)[1] if "?" in returned else returned
+    params = urllib.parse.parse_qs(query.split("#", 1)[0])
+    if "error" in params:
+        detail = params.get("error_description", params["error"])[0]
+        raise SignInError(f"the sign-in page refused: {detail}")
+    if params.get("state", [None])[0] != state:
+        raise SignInError("that address is from a different sign-in; run `nama login` again")
+    if "code" not in params:
+        raise SignInError("that address holds no sign-in code")
+    return params["code"][0]
+
+
+def _token_request(domain: str, form: dict) -> dict:
+    try:
+        return _post(f"{domain}/oauth2/token", form)
+    except _Refused as exc:
+        if exc.error == "invalid_grant" and form["grant_type"] == "refresh_token":
+            raise SignInExpired("the sign-in has expired or was cancelled") from None
+        raise
+
+
+def _post(url: str, form: dict) -> dict:
+    data = urllib.parse.urlencode(form).encode("ascii")
+    req = urllib.request.Request(url, data=data, method="POST", headers={
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept": "application/json",
+    })
+    try:
+        with urllib.request.urlopen(req, timeout=portal_api.TIMEOUT_SECONDS) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as exc:
+        raw = exc.read().decode("utf-8", "replace")
+        try:
+            parsed = json.loads(raw)
+            error = parsed.get("error", "")
+            detail = error
+            if parsed.get("error_description"):
+                detail = f"{error}: {parsed['error_description']}"
+        except (ValueError, AttributeError):
+            error, detail = "", raw.strip() or exc.reason
+        raise _Refused(f"{exc.code} from {url}: {detail}", error) from None
+    except urllib.error.URLError as exc:
+        raise SignInError(f"cannot reach {url}: {exc.reason}") from None
+    return json.loads(raw) if raw else {}
+
+
+def _claims(jwt: str) -> dict:
+    """A token's claims, read and not checked: the portal checks the signature."""
+    payload = jwt.split(".")[1]
+    return json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
+
+
+def _b64(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")

nama/store.py

@@ -0,0 +1,73 @@
+"""The sign-ins kept on this machine: one per portal, in one file that only its
+owner can read, and the portal last signed in to as the one a command uses
+when none is named."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+class NotSignedIn(Exception):
+    """No sign-in is kept for the portal asked about."""
+
+
+class StoreError(Exception):
+    """The file of sign-ins cannot be read."""
+
+
+def path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
+    return Path(base) / "nama" / "sign-ins.json"
+
+
+def _read() -> dict:
+    try:
+        return json.loads(path().read_text())
+    except FileNotFoundError:
+        return {"default": None, "portals": {}}
+    except ValueError as exc:
+        raise StoreError(f"{path()} cannot be read ({exc}); delete it and sign in "
+                         "again") from None
+
+
+def _write(state: dict) -> None:
+    target = path()
+    target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    temp = target.with_suffix(".tmp")
+    fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    os.fchmod(fd, 0o600)
+    with os.fdopen(fd, "w") as f:
+        json.dump(state, f, indent=2)
+    os.replace(temp, target)
+
+
+def get(portal: str | None) -> tuple[str, dict]:
+    """The portal named, or the default one, and its sign-in."""
+    state = _read()
+    if portal is None:
+        portal = state["default"]
+        if portal is None:
+            raise NotSignedIn("not signed in to any portal; run `nama login "
+                              "https://nm-portal.example.com`, with the portal's own "
+                              "address")
+    entry = state["portals"].get(portal)
+    if entry is None:
+        raise NotSignedIn(f"not signed in to {portal}; run `nama login {portal}`")
+    return portal, entry
+
+
+def put(portal: str, entry: dict, *, make_default: bool) -> None:
+    state = _read()
+    state["portals"][portal] = entry
+    if make_default:
+        state["default"] = portal
+    _write(state)
+
+
+def remove(portal: str) -> None:
+    state = _read()
+    state["portals"].pop(portal, None)
+    if state["default"] == portal:
+        state["default"] = None
+    _write(state)

nama/terminal.py

@@ -0,0 +1,23 @@
+"""Printing to the terminal text that comes from elsewhere: the portal, the
+tool that ran a job, the machine it ran on.
+
+A terminal acts on control characters rather than showing them: they move the
+cursor, rewrite what is already on the screen and, in some terminals, set the
+clipboard. Everything nama prints goes through ``say``, which shows each such
+character as its escape, ``\\x1b`` for one, instead.
+"""
+from __future__ import annotations
+
+import re
+import sys
+
+#: Every control character but tab and newline: C0, DEL and C1.
+_CONTROL = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+
+
+def safe(text: object) -> str:
+    return _CONTROL.sub(lambda m: f"\\x{ord(m.group()):02x}", str(text))
+
+
+def say(text: object = "", *, err: bool = False) -> None:
+    print(safe(text), file=sys.stderr if err else sys.stdout, flush=True)

nm_portal_cli-0.2.1.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: nm-portal-cli
+Version: 0.2.1
+Summary: The NM portal from a terminal
+Requires-Python: >=3.12

nm_portal_cli-0.2.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+nama/__init__.py,sha256=ezbXL_FvDOTTZPCVnW-roulsBPd7JVzpsN8IU4g9QmY,70
+nama/__main__.py,sha256=hefzpCFgr3oZYfWANBU-lSQ4b5sXB8Jdx-mG8i22_rM,56
+nama/cli.py,sha256=I_9qeKIwitvb8km9j0WV7Y9B-TtHRCcqA6zzMlyyW3s,12086
+nama/download.py,sha256=hr-arTUfVVR89EnDihadzTZVSI-io4VP9XXUkm8P9fw,3506
+nama/portal.py,sha256=m7RjUzKpsVblL9XTr2zY-dMQ4KFHJMiE70oay4UOf8M,3992
+nama/signin.py,sha256=IGXyS5Xik3YRSuGHvp3g8-9ZmHbo02tDhQ2grzvy6FY,10577
+nama/store.py,sha256=BQrVj1A_DQX0vXsiueXUW3YUZLw7BWipqxgiZZUfP80,2212
+nama/terminal.py,sha256=u-RVpRNcMvflEg0zAQsuOaWAwm8MaB8sG7ob-jtb4_g,830
+nm_portal_cli-0.2.1.dist-info/METADATA,sha256=LVdN3FfxH3ClYtBmIaFjkF5Y4FEN0_1Q9TvE-0o13Fs,120
+nm_portal_cli-0.2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+nm_portal_cli-0.2.1.dist-info/entry_points.txt,sha256=HTZYQWBOByJovHQVld1IAHz5ggF1whVLiYnb7JcN5kc,39
+nm_portal_cli-0.2.1.dist-info/top_level.txt,sha256=q1f2veWOLFh5b5Fvccr7kmzWD167MTJe3w918LdfqXk,5
+nm_portal_cli-0.2.1.dist-info/RECORD,,

nm_portal_cli-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nm_portal_cli-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nama = nama.cli:main

nm_portal_cli-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+nama