s3dgraphy 1.6.0.dev53__tar.gz → 1.6.0.dev54__tar.gz

{s3dgraphy-1.6.0.dev53/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev54}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev53
+Version: 1.6.0.dev54
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
@@ -35,7 +35,7 @@ Requires-Dist: pandas>=2.0.0
 Requires-Dist: lxml>=4.9.0
 Requires-Dist: openpyxl>=3.0.0
 Requires-Dist: networkx>=3.0
-Requires-Dist: dtcstamp>=0.1.4
+Requires-Dist: dtcstamp>=0.1.5
 Provides-Extra: rdf
 Requires-Dist: rdflib>=7.0; extra == "rdf"
 Provides-Extra: rdf-embedded

{s3dgraphy-1.6.0.dev53 → s3dgraphy-1.6.0.dev54}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev53"
+version = "1.6.0.dev54"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -56,7 +56,7 @@ dependencies = [
     # the four above. It has zero dependencies of its own and is one module, so
     # it can also simply be copied; s3dgraphy depends on it rather than
     # vendoring it, because two copies of a format rule drift.
-    "dtcstamp>=0.1.4",  # 0.1.1 lacks stamp_description: import s3dgraphy.stamp fails (MICRO-DTCSTAMP-012)
+    "dtcstamp>=0.1.5",  # 0.1.1 lacks stamp_description: import s3dgraphy.stamp fails (MICRO-DTCSTAMP-012)
 ]
 
 [project.urls]

{s3dgraphy-1.6.0.dev53 → s3dgraphy-1.6.0.dev54}/src/s3dgraphy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.6.0.dev53"
+__version__ = "1.6.0.dev54"
 __datamodel_version__ = "1.5.5"  # s3Dgraphy connections datamodel version
 
 # s3Dgraphy/__init__.py

s3dgraphy-1.6.0.dev54/src/s3dgraphy/__main__.py

@@ -0,0 +1,121 @@
+"""`python -m s3dgraphy <command>` — the library's own commands.
+
+    python -m s3dgraphy room-import <em.json> --node <url> --room <id>
+                                    [--dry-run] [--pack-tilesets 3tz] …
+
+One command for now: the first door of the room importer
+(:mod:`s3dgraphy.room_import`). `--help` on it says the rest.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shlex
+import subprocess
+import sys
+
+
+def _token(args) -> str:
+    if args.token_cmd:
+        out = subprocess.run(shlex.split(args.token_cmd), capture_output=True,
+                             text=True, check=True).stdout
+        lines = [l.strip() for l in out.splitlines() if l.strip()]
+        return lines[-1] if lines else ""
+    if args.token_file:
+        with open(os.path.expanduser(args.token_file), encoding="utf-8") as fh:
+            return fh.read().strip()
+    return (args.token or os.environ.get("EM_TOKEN") or "").strip()
+
+
+def room_import_main(argv) -> int:
+    p = argparse.ArgumentParser(
+        prog="python -m s3dgraphy room-import",
+        description="Bring an EM study (an em.json and its folder) into a room "
+                    "of a StratiGraph node: the files go up once, what is outside "
+                    "the folder stays a reference, the graph is seated last.")
+    p.add_argument("em_json", help="the study's em.json")
+    p.add_argument("--node", required=True, help="the node's base, e.g. https://em.localhost:8443/em")
+    p.add_argument("--room", required=True, help="the room's id")
+    p.add_argument("--title", default=None, help="the room's title (default: the study's name)")
+    p.add_argument("--base", default=None,
+                   help="the folder the em.json's relative paths start from "
+                        "(default: the em.json's folder)")
+    p.add_argument("--visibility", default="restricted", choices=("restricted", "public"))
+    p.add_argument("--token", default=None, help="an access token (or EM_TOKEN)")
+    p.add_argument("--token-file", default=None, help="a file holding the token")
+    p.add_argument("--token-cmd", default=None,
+                   help="a command printing a token (run again when it runs out), "
+                        "e.g. stratigraph-server/dev-stack/token.sh")
+    p.add_argument("--dry-run", action="store_true",
+                   help="the plan only: what goes up, what the node has, "
+                        "references, missing. Writes nothing")
+    p.add_argument("--pack-tilesets", default=None, choices=("3tz",),
+                   help="a tileset folder goes up as one canonical .3tz")
+    p.add_argument("--journal", default=None, help="the journal (default: beside the em.json)")
+    p.add_argument("--work-dir", default=None, help="where packed archives are written")
+    p.add_argument("--report-dir", default=None, help="where the report goes (default: beside the journal)")
+    p.add_argument("--by-reference", action="store_true",
+                   help="a personal node: register files by reference (asset-reference) "
+                        "instead of sending their bytes")
+    p.add_argument("--elsewhere", default="host", choices=("host", "reference", "move"),
+                   help="a file the node keeps at home in ANOTHER room: host it here "
+                        "without moving it (default), leave it a reference to that "
+                        "room, or move its home here")
+    p.add_argument("--workers", type=int, default=4)
+    p.add_argument("--reseed", action="store_true", help="send every operation again")
+    p.add_argument("--json", action="store_true", help="print the whole report as JSON")
+    args = p.parse_args(argv)
+
+    from .room_import import room_import
+    from .room_import import access
+    token = _token(args) or None
+    if token and args.token_cmd:
+        access.set_renewer(args.node.rstrip("/"), token, lambda: _token(args))
+    elif token:
+        access.adopt(args.node.rstrip("/"), token)
+    report = room_import(args.em_json, node=args.node, room=args.room, title=args.title,
+                         base_dir=args.base, visibility=args.visibility, token=token,
+                         dry_run=args.dry_run, pack_tilesets=args.pack_tilesets,
+                         journal_path=args.journal, work_dir=args.work_dir,
+                         report_dir=args.report_dir, by_reference=args.by_reference,
+                         workers=args.workers, reseed=args.reseed,
+                         elsewhere=args.elsewhere)
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=1, default=str))
+    elif args.dry_run:
+        plan = report["plan"]
+        from .room_import.inventory import human_size
+        print(f"plan for {args.room} on {args.node}:")
+        print(f"  {plan['resources']} resources · " + ", ".join(
+            f"{g} {n}" for g, n in plan["groups"].items()))
+        print(f"  to upload: {plan['upload']['files']} file(s), {human_size(plan['upload']['bytes'])}")
+        print(f"  already on the node: {plan['already']['files']} file(s), "
+              f"{human_size(plan['already']['bytes'])}")
+        print(f"  references: {plan['references']} · missing: {plan['missing']}")
+        for t in plan["trees"]:
+            print(f"  tree {t['name']}: {t['files']} file(s)")
+        for pk in report.get("packs") or []:
+            print(f"  pack: {pk}")
+        print(f"  {sum(report['requests'].values())} request(s), {report['seconds']} s")
+    else:
+        print(report["sentence"])
+        for f in report.get("report_files") or []:
+            print(f"  report: {f}")
+    return 1 if report.get("failed") else 0
+
+
+COMMANDS = {"room-import": room_import_main}
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help") or argv[0] not in COMMANDS:
+        print(__doc__.strip())
+        return 0 if (not argv or argv[0] in ("-h", "--help")) else 2
+    return COMMANDS[argv[0]](argv[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{s3dgraphy-1.6.0.dev53 → s3dgraphy-1.6.0.dev54}/src/s3dgraphy/api.py

@@ -3068,6 +3068,25 @@ def resolve_file(entry: Dict[str, Any], **kwargs) -> Dict[str, Any]:
     return resolve(entry, **kwargs)
 
 
+# ── a study into a room, from a folder (MICRO-ROOM-IMPORT, 15 Oct 2026) ──────
+def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = None,
+                base_dir: Optional[str] = None, visibility: str = "restricted",
+                token: Optional[str] = None, dry_run: bool = False,
+                pack_tilesets: Optional[str] = None, **kwargs) -> Dict[str, Any]:
+    """Bring the study of ``em_json`` and every file of its folder into
+    ``room`` on ``node``: what is in the folder goes up once (HEAD by sha256
+    first), what is outside stays a reference by digest, the resources become
+    hosted keeping their path, the graph is seated last as operations, then
+    ``study-access``. ``dry_run``: the plan only, nothing written.
+    ``pack_tilesets="3tz"``: a tileset folder goes up as one canonical
+    ``.3tz``. → the report. The one engine of the three doors (the command,
+    EMStudio, EM Tools); see :mod:`s3dgraphy.room_import`."""
+    from .room_import import room_import as _run
+    return _run(em_json, node=node, room=room, title=title, base_dir=base_dir,
+                visibility=visibility, token=token, dry_run=dry_run,
+                pack_tilesets=pack_tilesets, **kwargs)
+
+
 # ── S1 · the Storage list and «find moved» (E.D., 11 Oct 2026) ────────────────
 def storage_rows(graph: Graph, results: Sequence[Dict[str, Any]],
                  graph_name: str = "") -> List[Dict[str, Any]]:

s3dgraphy-1.6.0.dev54/src/s3dgraphy/room_import/__init__.py

@@ -0,0 +1,64 @@
+"""A study into a room, from a folder: ONE engine, three doors.
+
+E.D., 15 Oct 2026: «mi manca un importer secco per i dataset di Extended
+Matrix, con tutti i suoi dati locali». Until today the gesture existed twice —
+«Bring into a room…» in EM Tools (`sync_manager/bring.py`, Python inside
+Blender) and in EMStudio (`seedOpsForContainer` and the inventory, in
+TypeScript) — and the two diverged: different resources seen, different
+resolving, the graph seated first in one and last in the other (the table is
+in the report of MICRO-ROOM-IMPORT). Two implementations of one gesture are two
+behaviours to correct.
+
+So: **one engine, here**, pure Python, no Blender, testable with a fake node;
+**three doors** that call it — the command (`python -m s3dgraphy room-import`,
+:func:`s3dgraphy.api.room_import`), EMStudio through its bridge, EM Tools'
+Files and «Bring into a room» (where only the SCENE stays: exporting a model
+from the scene before it goes up, materialising what comes down). It also
+works on a folder nobody ever opened in Blender — a dataset from Zenodo.
+
+The parts of EM Tools without `bpy` were MOVED here, not copied
+(`inventory`, `node` ← `asset_upload` + `rooms_list` + `room_access` +
+`handoff`, `access`, `trust`): EM Tools imports them from s3Dgraphy.
+
+THE RULES
+
+1. **What is in the folder goes up.** What the graph cites outside it
+   (`onedrive://`, `smb://`, the NAS, http, `blend://`) becomes a reference by
+   digest: its locator and checksum stay, `residency: reference`. **A file
+   goes up once**: if the node has it (HEAD by sha256) it is not sent again,
+   and a file the study names twice is one upload.
+2. **Restart.** A second run uploads nothing and duplicates nothing: files are
+   asked for by digest, the operations are idempotent, and the journal
+   (`.em_room_import.json` beside the em.json) remembers what was hashed and
+   what was seeded. A cut run starts again where it was.
+3. **The graph is seated last**, as in `bring.py`: the room receives the
+   resources already hosted, in one seeding, through `POST …/ops` in parts —
+   the same operations `dev-stack/seed_rooms.py` and EMStudio send.
+4. **Stamps travel with their files**: a `<file>.stamp.json` beside a file
+   goes up with it (`data.stamp_asset` on the resource).
+5. **The report says everything**: uploaded N (size), already on the node,
+   references M, missing K, the room's link — json and md.
+
+A hosted resource keeps its path: `data.url` becomes the room's address and
+the old locator stays as a second address of the same bytes (`addresses`); a
+`resource_file` keeps it in `data.path`, as EMStudio writes it. A file at home
+in ANOTHER room of the node (F1, `X-EM-Home-Room`) is not moved without a
+person's yes: it becomes a reference to the room it lives in.
+
+A TILESET in a folder (`packaging: directory`, thousands of files) goes up
+file by file, with a list of its members (`members_manifest`, dtcstamp's
+canonical form) — or, with `--pack-tilesets 3tz`, as ONE canonical `.3tz`
+written by dtcstamp (s3Dgraphy stays a reader), a sibling representation
+(`dtc_derived_from` the folder, a DTC step `packing` with its stamp); the
+folder stays as a reference. See :mod:`.pack`.
+
+Defaults to confirm (E.D.): the name `room_import` / `room-import`, a new
+room's visibility `restricted`.
+"""
+
+from .engine import (JOURNAL_NAME, Interrupted, Journal, make_plan, markdown,
+                     room_import, summarise_plan)
+from .errors import RoomError
+
+__all__ = ["JOURNAL_NAME", "Interrupted", "Journal", "RoomError", "make_plan",
+           "markdown", "room_import", "summarise_plan"]

s3dgraphy-1.6.0.dev54/src/s3dgraphy/room_import/access.py

@@ -0,0 +1,368 @@
+"""The access to a node, renewed before it runs out — and said when it cannot be.
+
+Moved here from EM Tools (`sync_manager/access.py`, 3bfdb93) on 15 Oct 2026
+(MICRO-ROOM-IMPORT). One change: what used to reach into EM Tools' own modules
+after a renewal (`_follow`: the REST session and the per-graph rooms carry the
+new token) is now a hook, `ON_RENEWED`, that EM Tools fills. And a token that
+came from a COMMAND (`set_renewer`: `dev-stack/token.sh`, for the room
+importer run from a shell) is renewed by running it again.
+
+Measured on 4 Oct 2026: «Archive this .blend» failed about fifteen minutes after
+entering the room with «could not reach the room: [Errno 32] Broken pipe». The
+node had answered **401** (em-dev-server's log, four times between 13:49:09 and
+13:49:34) while Blender was still sending the file, and the realm says why: the
+`em-tools` client issues access tokens that live **900 s**
+(`access.token.lifespan`, read from Keycloak's admin API). Blender kept only the
+access token, so after fifteen minutes every call was refused — and a refusal
+that arrives before a large body is sent reads, on this side, as a cut pipe.
+
+Now the sign-in keeps what the realm gives beside the access token — the refresh
+token, the token endpoint, the client — in memory, like the token itself
+(`room.py`'s rule: never on disk). Every call to a node goes through `urlopen`
+here, which:
+
+* **before** the call, renews an access that expires within `SKEW` seconds (more
+  for a call that carries a body: the node reads the header first, and a large
+  body must not set off on a token about to die);
+* **after** a 401 — or a cut pipe on an access that has expired — renews once and
+  sends again, when the body can be sent again;
+* when the realm will not renew (the sign-in session idled out: 30 minutes on
+  the dev realm), raises `AccessExpired`, whose sentence says what happened:
+  «the access to <node> has expired: sign in again», never «Broken pipe».
+
+A token that came from somewhere else (pasted) has no refresh token: it is used
+until it expires, and then the same sentence.
+
+Calls carry the token they were given, often a copy taken minutes ago (a
+per-graph room keeps one in `room_session._where`). The header is therefore
+matched by LINEAGE: any token this session ever received for a node is replaced
+by that node's newest one. Stale copies heal at the one place every call
+crosses.
+
+Standard library only (it runs inside Blender's Python too).
+"""
+
+from __future__ import annotations
+
+import base64
+import errno
+import json
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional
+
+from .errors import RoomError
+
+#: renew when the access has less than this left (seconds)
+SKEW = 60
+#: …and this much for a call that carries a body
+SKEW_BODY = 180
+
+#: base → {token, refresh_token, expires_at, token_endpoint, client_id}
+_creds: Dict[str, Dict[str, Any]] = {}
+#: every token this session received → the base it belongs to
+_lineage: Dict[str, str] = {}
+_lock = threading.RLock()
+
+#: the last access that ran out, for the panel's «Sign in again» (base or "")
+EXPIRED = {"base": "", "line": ""}
+
+#: what the sentence of an expiry tells the person to do; EM Tools sets its
+#: own (EM ▸ Where you work ▸ Sign in again)
+SIGN_IN_HINT = "sign in again"
+
+#: called as `hook(base, new_token)` after every renewal: whoever keeps a copy
+#: of the token (EM Tools' REST session, its per-graph rooms) follows it here
+ON_RENEWED: List[Callable[[str, str], None]] = []
+
+#: base → a callable that returns a NEW access token (a command run again)
+_renewers: Dict[str, Callable[[], str]] = {}
+
+
+class AccessExpired(RoomError):
+    """The access to a node ran out and could not be renewed: sign in again."""
+
+    def __init__(self, base: str, why: str = ""):
+        self.base = base
+        sentence = (f"the access to {base or 'the node'} has expired: "
+                    f"{SIGN_IN_HINT}")
+        if why:
+            sentence += f" — {why}"
+        super().__init__(sentence, status=401)
+
+
+def _norm(base: str) -> str:
+    return (base or "").strip().rstrip("/")
+
+
+def expiry_of(token: str) -> Optional[float]:
+    """The `exp` claim of a JWT, read and not verified (the node verifies)."""
+    try:
+        part = str(token).split(".")[1]
+        claims = json.loads(base64.urlsafe_b64decode(part + "=" * (-len(part) % 4)))
+        exp = claims.get("exp")
+        return float(exp) if exp is not None else None
+    except Exception:  # noqa: BLE001 — an opaque token: no expiry to read
+        return None
+
+
+def subject_of(token: str) -> str:
+    """Who a JWT is about (`sub`, else the name), read and not verified."""
+    try:
+        part = str(token).split(".")[1]
+        claims = json.loads(base64.urlsafe_b64decode(part + "=" * (-len(part) % 4)))
+        return str(claims.get("sub") or claims.get("preferred_username") or "")
+    except Exception:  # noqa: BLE001 — an opaque token: no subject to read
+        return ""
+
+
+def _life_of(token: str) -> Optional[float]:
+    """How long the realm let this access live (`exp - iat`), when it says."""
+    try:
+        part = str(token).split(".")[1]
+        claims = json.loads(base64.urlsafe_b64decode(part + "=" * (-len(part) % 4)))
+        return float(claims["exp"]) - float(claims["iat"])
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def remember(base: str, token: str, *, refresh_token: str = "",
+             expires_in: Optional[float] = None, token_endpoint: str = "",
+             client_id: str = "") -> None:
+    """Keep what a sign-in returned, in memory, for `base`."""
+    if not token:
+        return
+    base = _norm(base)
+    expires_at = (time.time() + float(expires_in)) if expires_in else expiry_of(token)
+    life = float(expires_in) if expires_in else _life_of(token)
+    with _lock:
+        old = _creds.get(base) or {}
+        _creds[base] = {
+            "token": token,
+            "refresh_token": refresh_token or "",
+            "expires_at": expires_at,
+            "life": life,
+            "token_endpoint": token_endpoint or old.get("token_endpoint") or "",
+            "client_id": client_id or old.get("client_id") or "",
+        }
+        _lineage[token] = base
+    if EXPIRED["base"] == base:
+        EXPIRED.update({"base": "", "line": ""})
+
+
+def adopt(base: str, token: Optional[str]) -> None:
+    """A token that reached the session another way (pasted, a link): known by
+    its base, so a refusal can be said as an expiry. No refresh token."""
+    if not token:
+        return
+    base = _norm(base)
+    with _lock:
+        if token in _lineage:
+            return
+        held = (_creds.get(base) or {}).get("token")
+        if held and subject_of(held) != subject_of(token):
+            # ANOTHER PERSON on the same node: a lineage of its own. Measured
+            # (5 Oct 2026, the room list smoke): the viewer's pasted token
+            # joined dev's lineage, and `fresh` handed every call dev's token
+            # — the node answered as dev to a viewer
+            for t in [t for t, bb in _lineage.items() if bb == base]:
+                _lineage.pop(t, None)
+            _creds.pop(base, None)
+        _lineage[token] = base
+        if base not in _creds:
+            _creds[base] = {"token": token, "refresh_token": "",
+                            "expires_at": expiry_of(token), "life": _life_of(token),
+                            "token_endpoint": "", "client_id": ""}
+
+
+def set_renewer(base: str, token: str, renewer: Callable[[], str]) -> None:
+    """`token` for `base`, renewed by calling `renewer()` — a token that came
+    from a command (`dev-stack/token.sh`) is renewed by running it again. The
+    expiry is read from the token itself."""
+    adopt(base, token)
+    with _lock:
+        _renewers[_norm(base)] = renewer
+
+
+def forget(base: Optional[str] = None) -> None:
+    """Drop what is kept for `base` (every base when None)."""
+    with _lock:
+        for b in ([_norm(base)] if base else list(_creds)):
+            _creds.pop(b, None)
+            _renewers.pop(b, None)
+            for t in [t for t, bb in _lineage.items() if bb == b]:
+                _lineage.pop(t, None)
+
+
+def base_of(token: Optional[str]) -> Optional[str]:
+    return _lineage.get(token or "")
+
+
+def _left(cred: Dict[str, Any]) -> Optional[float]:
+    exp = cred.get("expires_at")
+    return None if exp is None else exp - time.time()
+
+
+def _post_form(url: str, fields: Dict[str, str], timeout: float = 30.0) -> Dict[str, Any]:
+    from .trust import urlopen as _open
+    request = urllib.request.Request(
+        url, data=urllib.parse.urlencode(fields).encode(), method="POST",
+        headers={"Content-Type": "application/x-www-form-urlencoded"})
+    with _open(request, timeout=timeout) as answer:
+        return json.loads(answer.read() or b"{}")
+
+
+def renew(base: str) -> str:
+    """A new access for `base` through its refresh token → the new token.
+
+    Raises `AccessExpired` with the reason when there is nothing to renew with,
+    or the realm refuses (the sign-in session idled out)."""
+    base = _norm(base)
+    with _lock:
+        cred = dict(_creds.get(base) or {})
+        renewer = _renewers.get(base)
+    if renewer is not None and not cred.get("refresh_token"):
+        try:
+            token = str(renewer() or "").strip()
+        except Exception as exc:  # noqa: BLE001 — the command's own failure
+            raise _expired(base, f"the command that gives the access failed: {exc}") from exc
+        if not token:
+            raise _expired(base, "the command that gives the access printed nothing")
+        with _lock:
+            _creds[base] = {"token": token, "refresh_token": "",
+                            "expires_at": expiry_of(token), "life": _life_of(token),
+                            "token_endpoint": "", "client_id": ""}
+            _lineage[token] = base
+        _follow(base, token)
+        return token
+    if not cred.get("refresh_token") or not cred.get("token_endpoint"):
+        raise _expired(base, "this access cannot be renewed from here")
+    try:
+        payload = _post_form(cred["token_endpoint"], {
+            "grant_type": "refresh_token",
+            "refresh_token": cred["refresh_token"],
+            "client_id": cred.get("client_id") or "",
+            # NO client_secret: a public client
+        })
+    except urllib.error.HTTPError as exc:
+        detail = ""
+        try:
+            detail = json.loads(exc.read() or b"{}").get("error_description") or ""
+        except Exception:  # noqa: BLE001
+            pass
+        raise _expired(base, f"the realm would not renew it ({exc.code}"
+                             + (f": {detail}" if detail else "") + ")") from exc
+    except (urllib.error.URLError, OSError, ValueError) as exc:
+        raise RoomError(f"could not reach the sign-in of {base} to renew the "
+                        f"access: {getattr(exc, 'reason', exc)}") from exc
+    token = str(payload.get("access_token") or "")
+    if not token:
+        raise _expired(base, "the realm returned no access token")
+    remember(base, token,
+             refresh_token=str(payload.get("refresh_token") or cred["refresh_token"]),
+             expires_in=payload.get("expires_in"),
+             token_endpoint=cred["token_endpoint"], client_id=cred.get("client_id", ""))
+    _follow(base, token)
+    print(f"[EM access] renewed the access to {base}")
+    return token
+
+
+def _expired(base: str, why: str) -> AccessExpired:
+    exc = AccessExpired(base, why)
+    EXPIRED.update({"base": base, "line": str(exc)})
+    return exc
+
+
+def _follow(base: str, token: str) -> None:
+    """Whoever keeps a copy of the token follows it (`ON_RENEWED`)."""
+    for hook in list(ON_RENEWED):
+        try:
+            hook(base, token)
+        except Exception:  # noqa: BLE001 — one follower's trouble is its own
+            pass
+
+
+def fresh(token: Optional[str], *, margin: float = SKEW) -> Optional[str]:
+    """The newest token of `token`'s lineage, renewed when it has less than
+    `margin` seconds left. A token this session does not know is returned as is."""
+    base = base_of(token)
+    if not token or base is None:
+        return token
+    with _lock:
+        cred = dict(_creds.get(base) or {})
+    current = cred.get("token") or token
+    left = _left(cred)
+    life = cred.get("life")
+    if life:
+        # an access that lives less than the margin would be renewed at every
+        # call (measured with a 60 s access: 195 renewals in one bring)
+        margin = min(margin, life / 4)
+    if left is not None and left < margin:
+        if cred.get("refresh_token") or base in _renewers:
+            return renew(base)
+        if left <= 0:
+            raise _expired(base, "")
+    return current
+
+
+def _bearer(request) -> Optional[str]:
+    value = request.get_header("Authorization") or ""
+    return value[7:].strip() if value.lower().startswith("bearer ") else None
+
+
+def _resendable(request) -> bool:
+    data = request.data
+    return data is None or isinstance(data, (bytes, bytearray))
+
+
+def _cut(exc: BaseException) -> bool:
+    """A pipe cut or a connection reset — what a 401 before a body looks like."""
+    reason = getattr(exc, "reason", exc)
+    code = getattr(reason, "errno", None)
+    return code in (errno.EPIPE, errno.ECONNRESET) or isinstance(
+        reason, (BrokenPipeError, ConnectionResetError))
+
+
+def urlopen(request, timeout: Optional[float] = None):
+    """`urllib.request.urlopen` for a call to a node — TLS through `trust`, the
+    access renewed before it runs out and once more after a refusal."""
+    from .trust import urlopen as _open
+    if isinstance(request, str):
+        request = urllib.request.Request(request)
+    token = _bearer(request)
+    base = base_of(token)
+    if token and base is not None:
+        margin = SKEW_BODY if request.data is not None else SKEW
+        current = fresh(token, margin=margin)
+        if current and current != token:
+            request.add_header("Authorization", f"Bearer {current}")
+            token = current
+    try:
+        return _open(request, timeout=timeout)
+    except urllib.error.HTTPError as exc:
+        if exc.code != 401 or base is None:
+            raise
+    except (urllib.error.URLError, OSError) as exc:
+        if base is None or not _cut(exc):
+            raise
+        with _lock:
+            left = _left(_creds.get(base) or {})
+        if left is None or left > 0:
+            raise                # a cut, not an expiry: the caller says it
+    # 401, or a cut on an access that ran out: renew once and send again
+    token = renew(base)
+    if not _resendable(request):
+        # a streamed body cannot be read twice: the access is renewed, the
+        # gesture is the person's to repeat
+        raise RoomError(f"the access to {base} ran out during the call and has "
+                        f"been renewed: press the button again", status=401)
+    request.add_header("Authorization", f"Bearer {token}")
+    try:
+        return _open(request, timeout=timeout)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 401:
+            raise _expired(base, "the node refused the renewed access too") from exc
+        raise