shuttlecheck 0.3.0__tar.gz → 0.4.0__tar.gz

{shuttlecheck-0.3.0/shuttlecheck.egg-info → shuttlecheck-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shuttlecheck
-Version: 0.3.0
+Version: 0.4.0
 Summary: Check media filenames, folder structure and deliverables against a written convention. Read-only.
 Author-email: MVRK Systems <hello@mvrk.systems>
 License: Proprietary — free to use, no redistribution
@@ -30,9 +30,11 @@ Requires-Dist: xxhash>=3.0
 Requires-Dist: tzdata>=2024.1; sys_platform == "win32"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: app
+Requires-Dist: pywebview>=5.0; extra == "app"
 Dynamic: license-file
 
-# ShuttleCheck
+# ShuttleCheck™
 
 **Check media filenames, folder structure and deliverables against a written
 convention.** Nothing in this package renames, moves or deletes anything.
@@ -130,13 +132,18 @@ No spec to be told about, no account, no connection.
 
 ## What this package will not do
 
-It will not rename, move or delete anything. That boundary is the point: it is
-the command a stranger will run on a live job, because running it cannot cost
-them anything.
+It will not rename, move or delete anything of yours. That boundary is the
+point: it is the command a stranger will run on a live job, because running
+it cannot cost them anything.
 
-Conforming files, the reversible journal, sealing drives and per-vendor specs
-are licensed separately as ShuttleCheck Pro. Asking for one of those commands
-here prints an explanation rather than an error.
+**Sealing is the one exception, and it is free.** `seal` writes an ASC MHL
+hash list and the convention alongside your media, touching none of it. A
+manifest is only worth what the far end can read for nothing, so the half
+that writes one cannot be the paid half.
+
+Conforming files to a convention, and undoing a conform run, are licensed
+separately as ShuttleCheck Pro. Asking for one of those commands here prints
+an explanation rather than an error.
 
 ## Licence
 
@@ -144,3 +151,7 @@ Free to install and use. Not open source: no right to redistribute or modify.
 See <https://mvrk.systems/shuttlecheck>.
 
 Made by [MVRK Systems](https://mvrk.systems).
+
+---
+
+ShuttleCheck™ and DailiesDrop™ are trademarks of MVRK Systems.

{shuttlecheck-0.3.0 → shuttlecheck-0.4.0}/PYPI.md

@@ -1,4 +1,4 @@
-# ShuttleCheck
+# ShuttleCheck™
 
 **Check media filenames, folder structure and deliverables against a written
 convention.** Nothing in this package renames, moves or deletes anything.
@@ -96,13 +96,18 @@ No spec to be told about, no account, no connection.
 
 ## What this package will not do
 
-It will not rename, move or delete anything. That boundary is the point: it is
-the command a stranger will run on a live job, because running it cannot cost
-them anything.
+It will not rename, move or delete anything of yours. That boundary is the
+point: it is the command a stranger will run on a live job, because running
+it cannot cost them anything.
 
-Conforming files, the reversible journal, sealing drives and per-vendor specs
-are licensed separately as ShuttleCheck Pro. Asking for one of those commands
-here prints an explanation rather than an error.
+**Sealing is the one exception, and it is free.** `seal` writes an ASC MHL
+hash list and the convention alongside your media, touching none of it. A
+manifest is only worth what the far end can read for nothing, so the half
+that writes one cannot be the paid half.
+
+Conforming files to a convention, and undoing a conform run, are licensed
+separately as ShuttleCheck Pro. Asking for one of those commands here prints
+an explanation rather than an error.
 
 ## Licence
 
@@ -110,3 +115,7 @@ Free to install and use. Not open source: no right to redistribute or modify.
 See <https://mvrk.systems/shuttlecheck>.
 
 Made by [MVRK Systems](https://mvrk.systems).
+
+---
+
+ShuttleCheck™ and DailiesDrop™ are trademarks of MVRK Systems.

{shuttlecheck-0.3.0 → shuttlecheck-0.4.0}/pyproject.toml

@@ -1,67 +1,74 @@
-[project]
-name = "shuttlecheck"
-version = "0.3.0"
-description = "Check media filenames, folder structure and deliverables against a written convention. Read-only."
-readme = { file = "PYPI.md", content-type = "text/markdown" }
-requires-python = ">=3.11"
-license = { text = "Proprietary — free to use, no redistribution" }
-authors = [{ name = "MVRK Systems", email = "hello@mvrk.systems" }]
-keywords = [
-    "broadcast", "post-production", "dailies", "media", "naming-convention",
-    "file-naming", "delivery", "conformance", "validation", "vfx", "video",
-]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Environment :: Console",
-    "Environment :: Web Environment",
-    "Intended Audience :: End Users/Desktop",
-    "License :: Other/Proprietary License",
-    "Natural Language :: English",
-    "Operating System :: OS Independent",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Topic :: Multimedia :: Video",
-    "Topic :: System :: Archiving",
-    "Topic :: Utilities",
-]
-dependencies = [
-    "PyYAML>=6.0",
-    "jsonschema>=4.20",
-    # xxh64 is the checksum the ASC MHL specification is usually written with
-    # and the one DailiesDrop records, and it is not in the standard library.
-    # A dependency in the read-only half looks like the wrong place for it
-    # until you notice that verifying a drive the appliance sealed is exactly
-    # what this half is for: without it, the common case degrades to "this
-    # installation cannot check those checksums".
-    "xxhash>=3.0",
-    # Windows ships no system tz database, so zoneinfo cannot resolve the
-    # agenda timezone without this. Required, not optional, on a target platform.
-    "tzdata>=2024.1; sys_platform == 'win32'",
-]
-
-[project.optional-dependencies]
-dev = ["pytest>=8.0"]
-
-[project.urls]
-Homepage = "https://mvrk.systems/shuttlecheck"
-Documentation = "https://mvrk.systems/shuttlecheck#checks"
-
-[project.scripts]
-shuttlecheck = "shuttlecheck.cli:main"
-
-[build-system]
-requires = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"
-
-[tool.setuptools]
-packages = ["shuttlecheck"]
-
-[tool.setuptools.package-data]
-# Neither schema is documentation. The validator refuses to run without the
-# spec schema, and the telemetry contract is checked against every batch before
-# it is sent, so a build that cannot read it sends nothing at all. Both travel
-# inside the wheel.
-shuttlecheck = ["schema.json", "telemetry-v1.schema.json", "ui_assets/*",
-                "ui_assets/fonts/*"]
+[project]
+name = "shuttlecheck"
+version = "0.4.0"
+description = "Check media filenames, folder structure and deliverables against a written convention. Read-only."
+readme = { file = "PYPI.md", content-type = "text/markdown" }
+requires-python = ">=3.11"
+license = { text = "Proprietary — free to use, no redistribution" }
+authors = [{ name = "MVRK Systems", email = "hello@mvrk.systems" }]
+keywords = [
+    "broadcast", "post-production", "dailies", "media", "naming-convention",
+    "file-naming", "delivery", "conformance", "validation", "vfx", "video",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: End Users/Desktop",
+    "License :: Other/Proprietary License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Video",
+    "Topic :: System :: Archiving",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "PyYAML>=6.0",
+    "jsonschema>=4.20",
+    # xxh64 is the checksum the ASC MHL specification is usually written with
+    # and the one DailiesDrop records, and it is not in the standard library.
+    # A dependency in the read-only half looks like the wrong place for it
+    # until you notice that verifying a drive the appliance sealed is exactly
+    # what this half is for: without it, the common case degrades to "this
+    # installation cannot check those checksums".
+    "xxhash>=3.0",
+    # Windows ships no system tz database, so zoneinfo cannot resolve the
+    # agenda timezone without this. Required, not optional, on a target platform.
+    "tzdata>=2024.1; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+# The downloadable tool's own window, drawn by whatever webview the operating
+# system already has: WebView2 on Windows, WKWebView on macOS, WebKitGTK on
+# Linux. An extra rather than a dependency, because `pip install shuttlecheck`
+# is a library and a CLI and should not pull in a GUI stack, and because the
+# app falls back to a browser wherever this is missing. See
+# shuttlecheck/window.py.
+app = ["pywebview>=5.0"]
+
+[project.urls]
+Homepage = "https://mvrk.systems/shuttlecheck"
+Documentation = "https://mvrk.systems/shuttlecheck#checks"
+
+[project.scripts]
+shuttlecheck = "shuttlecheck.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["shuttlecheck"]
+
+[tool.setuptools.package-data]
+# Neither schema is documentation. The validator refuses to run without the
+# spec schema, and the telemetry contract is checked against every batch before
+# it is sent, so a build that cannot read it sends nothing at all. Both travel
+# inside the wheel.
+shuttlecheck = ["schema.json", "telemetry-v1.schema.json", "ui_assets/*",
+                "ui_assets/fonts/*"]

shuttlecheck-0.4.0/shuttlecheck/admission.py

@@ -0,0 +1,292 @@
+"""Letting a unit in, on the local network, with no service in the middle.
+
+`docs/TRANSPORT.md` section 3a.
+
+**Why this exists beside enrolment.** The fleet service is how a unit finds a
+destination it has never met, across networks. It is not how a unit and a
+destination on the same switch meet, and requiring it there would mean a
+machine in a basement with no route out cannot take delivery from a unit two
+metres away. It can.
+
+**Why this is not `endpoints.pair`.** Pairing names a unit: a serial and a
+label off the front of the box, a statement about what this destination
+expects. Its own docstring says it is deliberately not a connection. Admitting
+is the separate step that gives a named unit something it can present, and
+keeping the two apart is the difference between "we expect this serial" and
+"this caller has proved it is that serial". The screens say it that way round
+too.
+
+**What a token is worth.** It authenticates a unit to this destination and
+nothing else. It is not an account, it does not reach the fleet, it cannot
+mint anything, and it is useless on any other machine. It never reaches a
+screen; the admission code does, because a code is made to be read aloud.
+
+**What a code is worth.** Seven characters, one use, ten minutes, five wrong
+answers and the window shuts. That is deliberately not a password: it is the
+few seconds in which somebody standing at the destination says a unit may come
+in. Nothing is reachable through it once it closes.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+import time
+from datetime import datetime, timezone
+
+from . import endpoints, store
+
+# No O, 0, I or 1. The code is read out across a machine room, and the two
+# pairs people mishear are the two pairs that are not in here.
+ALPHABET = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
+CODE_LENGTH = 7
+
+# Long enough to walk to the unit and type it, short enough that a window
+# somebody forgot about is not an open door by the afternoon.
+WINDOW_SECONDS = 600
+
+# A seven character code out of this alphabet is one in thirty four billion.
+# The cap is not arithmetic, it is so that a window being hammered closes
+# rather than quietly standing there being hammered.
+MAX_ATTEMPTS = 5
+
+
+def _path():
+    return store.home() / "admissions.json"
+
+
+def _read() -> dict:
+    row = store._read_json(_path(), {})
+    if not isinstance(row, dict):
+        return {}
+    if not isinstance(row.get("units"), dict):
+        row["units"] = {}
+    return row
+
+
+def _write(row: dict) -> None:
+    store._write_json(_path(), row)
+    store._restrict(_path())
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+# --------------------------------------------------------------------------
+# The window
+# --------------------------------------------------------------------------
+
+def _live(row: dict) -> dict:
+    """The window, if there is one and it has not run out."""
+    win = row.get("window")
+    if not isinstance(win, dict):
+        return {}
+    if float(win.get("expires") or 0) <= time.time():
+        return {}
+    if int(win.get("attempts") or 0) >= MAX_ATTEMPTS:
+        return {}
+    return win
+
+
+def open_window(serial: str = "") -> dict:
+    """Start the few minutes in which a unit may be admitted.
+
+    A window may name a serial or not. Named, only that unit may use it, which
+    is what you want when four units are in the same rack. Unnamed, the first
+    unit to answer is admitted and the serial it declares is recorded.
+
+    Opening a second window replaces the first. Two codes live at once would
+    mean somebody reading out the one that has already been superseded.
+    """
+    serial = endpoints.normalise_serial(serial)
+    if serial and not endpoints.SERIAL.match(serial):
+        raise ValueError(
+            f"a unit serial looks like {endpoints.SERIAL_SHAPE} and is "
+            f"printed on the front of the appliance")
+
+    code = "".join(secrets.choice(ALPHABET) for _ in range(CODE_LENGTH))
+    row = _read()
+    row["window"] = {
+        "code": code,
+        "serial": serial,
+        "opened": _now(),
+        "expires": time.time() + WINDOW_SECONDS,
+        "attempts": 0,
+    }
+    _write(row)
+
+    # The port has to be answering for a code to be worth anything. This is
+    # one of the three states that mean this machine will answer a unit, so
+    # the listener follows it the way it follows the other two.
+    from . import listener
+    listener.start()
+    return window()
+
+
+def window() -> dict:
+    """What the screen shows. The code is in here on purpose.
+
+    A token never reaches a screen. A code is made to be read aloud, lasts ten
+    minutes and opens nothing once it is used, so showing it is the whole of
+    what it is for.
+    """
+    win = _live(_read())
+    if not win:
+        return {"open": False}
+    return {
+        "open": True,
+        "code": win["code"],
+        "serial": win.get("serial", ""),
+        "secondsLeft": max(0, int(float(win["expires"]) - time.time())),
+        "attemptsLeft": MAX_ATTEMPTS - int(win.get("attempts") or 0),
+    }
+
+
+def close_window() -> dict:
+    row = _read()
+    row.pop("window", None)
+    _write(row)
+    _follow()
+    return {"open": False}
+
+
+def _bump() -> None:
+    """Count a failed attempt against the window, if one is open."""
+    row = _read()
+    win = row.get("window")
+    if isinstance(win, dict):
+        win["attempts"] = int(win.get("attempts") or 0) + 1
+        row["window"] = win
+        _write(row)
+
+
+# --------------------------------------------------------------------------
+# Admitting
+# --------------------------------------------------------------------------
+
+def admit(code: str, serial: str, label: str = "") -> dict:
+    """Spend the window and issue this unit a token.
+
+    Returns the unit's half of the answer, or `{}` for every kind of no. The
+    caller is a stranger on the network and the four ways to fail here, a
+    wrong code, a closed window, the wrong serial for a named window, and a
+    serial that is not shaped like one, are all the same answer to it. A
+    caller that could tell them apart could map the difference between a
+    window that is open and one that is not.
+    """
+    row = _read()
+    win = _live(row)
+    if not win:
+        return {}
+
+    serial = endpoints.normalise_serial(serial)
+    presented = str(code or "").strip().upper()
+
+    # Constant time on the code, and the serial checks run whatever the code
+    # did, so no branch here times differently from another.
+    code_ok = hmac.compare_digest(presented, str(win.get("code") or ""))
+    shape_ok = bool(endpoints.SERIAL.match(serial))
+    named = str(win.get("serial") or "")
+    serial_ok = (not named) or hmac.compare_digest(serial, named)
+
+    if not (code_ok and shape_ok and serial_ok):
+        _bump()
+        return {}
+
+    token = secrets.token_urlsafe(32)
+    units = row.get("units") or {}
+    units[serial] = {
+        "token": token,
+        "at": _now(),
+        "label": endpoints._screen_safe(label) or "",
+    }
+    row["units"] = units
+    row.pop("window", None)
+    _write(row)
+
+    # An admitted unit is a unit this destination expects. Two lists that can
+    # disagree about that would be one list too many.
+    if not any(u.serial == serial for u in endpoints.units()):
+        try:
+            endpoints.pair(serial, endpoints._screen_safe(label))
+        except ValueError:
+            pass
+
+    return {
+        "token": token,
+        "serial": serial,
+        "destination": endpoints.destination_id(),
+        "machine": _machine(),
+    }
+
+
+def _machine() -> str:
+    from . import receive
+    try:
+        return receive.machine_name()
+    except Exception:                                          # noqa: BLE001
+        return ""
+
+
+# --------------------------------------------------------------------------
+# What the listener asks
+# --------------------------------------------------------------------------
+
+def serial_for_token(token: str) -> str:
+    """Which admitted unit presented this, or empty.
+
+    Every held token is compared, and the comparison does not stop at the
+    first match, so the time this takes says nothing about which unit it was
+    or whether it matched at all.
+    """
+    presented = str(token or "")
+    if not presented:
+        return ""
+    found = ""
+    for serial, row in (_read().get("units") or {}).items():
+        if not isinstance(row, dict):
+            continue
+        if hmac.compare_digest(presented, str(row.get("token") or "")):
+            found = serial
+    return found
+
+
+def admitted() -> list:
+    """The serials that hold a token, oldest first."""
+    rows = (_read().get("units") or {}).items()
+    return [s for s, _ in sorted(rows, key=lambda kv: str(
+        kv[1].get("at", "") if isinstance(kv[1], dict) else ""))]
+
+
+def any_admitted() -> bool:
+    return bool(_read().get("units"))
+
+
+def is_admitted(serial: str) -> bool:
+    return endpoints.normalise_serial(serial) in (_read().get("units") or {})
+
+
+def revoke(serial: str) -> bool:
+    """Discard a unit's token. The unit is not told.
+
+    It finds out when its next request is refused, which is the only way a
+    revocation can work on a link that may be down.
+    """
+    serial = endpoints.normalise_serial(serial)
+    row = _read()
+    units = row.get("units") or {}
+    if serial not in units:
+        return False
+    units.pop(serial)
+    row["units"] = units
+    _write(row)
+    _follow()
+    return True
+
+
+def _follow() -> None:
+    """Close the port if nothing holds it open any more."""
+    from . import listener, receive
+    if not receive.receiving():
+        listener.stop()