remoteRF-server 1.1.0.dev30__py3-none-any.whl → 1.1.0.dev32__py3-none-any.whl

remoteRF_server/server/commands.py

@@ -153,6 +153,8 @@ def _table() -> list[Command]:
         Command(("cluster invite",), "Invite code for a lab: cluster invite <name>", _federation("invite"), "Clusters"),
         Command(("cluster join",), "Join with a code: cluster join <code>", _federation("join"), "Clusters"),
         Command(("cluster remove",), "Leave or disband: cluster remove <name>", _federation("remove"), "Clusters"),
+        Command(("cluster groups",), "Groups you share: cluster groups <name> [add|remove <group>]", _federation("groups"), "Clusters"),
+        Command(("cluster codes",), "Student codes for a cluster: cluster codes <name> [count]", _federation("codes"), "Clusters"),
         Command(("cluster accept",), "", _federation("accept"), "Clusters", hidden=True),
         Command(("global cluster",), "", _federation("cluster"), "Global", hidden=True),
         # ---- gist ----

remoteRF_server/server/federation/__init__.py

@@ -6,9 +6,9 @@ permission aggregation, resources, reservations, or broker authorization.
 
 import remoterf_federation_core as _federation_core
 
-if _federation_core.__version__ != "0.14.0":
+if _federation_core.__version__ != "0.15.0":
     raise RuntimeError(
-        "RemoteRF Server federation requires remoterf-federation-core==0.14.0; "
+        "RemoteRF Server federation requires remoterf-federation-core==0.15.0; "
         f"found {_federation_core.__version__}"
     )
 

remoteRF_server/server/federation/cli.py

@@ -75,6 +75,11 @@ def cmd_clusters() -> int:
         else:
             owner = _lab({"display_name": item.get("peer_name"), "deployment_id": item["peer"]})
             rows.append(f"{item['name']}  owned by {owner}  {item['state']}")
+            for peer in item.get("peers", []):
+                rows.append(f"    {_lab(peer)}  {peer['state'] or 'joining'}")
+        shared = ", ".join(group["group_name"] for group in item["groups"]) or "none"
+        rows.append(f"    sharing: {shared}" + ("" if item["groups"] else f"  (`cluster groups {item['name']} add <group>`)"))
+        rows.append(f"    {item['students']} of your users enrolled, {item['visitors']} visiting")
     print()
     print_panel("Clusters", rows, literal=True)
     print()
@@ -88,13 +93,15 @@ def _ask_for(verb: str) -> str:
     if verb == "join":
         return _input("Invite code from the other lab: ")
     names = [name for name, item in sorted(cluster.load().items()) if item.get("role") == "owner"]
-    if verb == "remove":
+    if verb in ("remove", "groups", "codes"):
         names = sorted(cluster.load())
     if verb == "accept":
         names = [name for name, item in sorted(cluster.load().items()) if item.get("state") == "pending"]
     what = {"create": "Name for the new cluster (short slug, e.g. ucla-lab)",
             "invite": "Which cluster to invite a lab into",
             "accept": "Which cluster's pending join to accept",
+            "groups": "Which cluster's shared groups to show",
+            "codes": "Which cluster to make student codes for",
             "remove": "Which cluster to leave (revokes the contract)"}[verb]
     if verb != "create" and names:
         print(f"  Your clusters: {', '.join(names)}")
@@ -114,6 +121,10 @@ def _input(prompt: str) -> str:
         return ""
 
 
+_USAGE = ("Usage: cluster list | cluster create|invite|remove <name> | cluster join <code> | "
+          "cluster groups <name> [add|remove <group>] | cluster codes <name> [count]")
+
+
 def cmd_cluster(argv: list[str]) -> int:
     from ...common.utils.ansi_codes import Sty
     from . import cluster
@@ -123,7 +134,7 @@ def cmd_cluster(argv: list[str]) -> int:
     words = [a for a in argv[1:] if not a.startswith("--")]
     if verb == "list" and not words:
         return cmd_clusters()
-    if not words and verb in ("create", "invite", "accept", "join", "remove"):
+    if not words and verb in ("create", "invite", "accept", "join", "remove", "groups", "codes"):
         # Leaving the argument out asks for it (docs/deployment-groups.md §8).
         answer = _ask_for(verb)
         if not answer:
@@ -137,7 +148,7 @@ def cmd_cluster(argv: list[str]) -> int:
             _print(f"  Created cluster {arg}. Hand out an invite with `cluster invite {arg}`.", Sty.GRAY)
         elif verb == "invite" and arg:
             code = cluster.invite(arg, auto="--manual" not in argv)
-            _print("  On the other lab's server run (single use, 24h):", Sty.GRAY)
+            _print("  On the other lab's server run (single use, 7 days):", Sty.GRAY)
             _print(f"    cluster join {code}", Sty.BOLD)
         elif verb == "join" and len(argv) > 1:
             # A code pasted from chat or email may arrive wrapped across lines.
@@ -149,8 +160,25 @@ def cmd_cluster(argv: list[str]) -> int:
             _print(f"  Accepted. {arg} activates once both servers confirm (about a minute).", Sty.GRAY)
         elif verb == "remove" and arg:
             _print(f"  {arg}: {cluster.remove(arg)}.", Sty.GRAY)
+        elif verb == "groups" and len(words) == 1:
+            shared = cluster.groups(arg)
+            _print(f"  {arg} shares: " + (", ".join(g["group_name"] for g in shared) or "nothing yet"), Sty.GRAY)
+            _print(f"  Attach one with `cluster groups {arg} add <group>`; students of every lab in the "
+                   "cluster get it. Group names stay on this server.", Sty.GRAY)
+        elif verb == "groups" and len(words) == 3 and words[1] in ("add", "remove"):
+            if words[1] == "add":
+                _print(f"  {cluster.attach_group(arg, words[2])} is now shared with {arg}.", Sty.GRAY)
+            else:
+                _print(f"  {cluster.detach_group(arg, words[2])} is no longer shared with {arg}.", Sty.GRAY)
+        elif verb == "codes" and arg:
+            count = int(words[1]) if len(words) > 1 else 1
+            codes = cluster.mint_codes(arg, count=count)
+            _print(f"  Give each of your users one code; they enter it in the Client like any enrollment "
+                   f"code (single use, {cluster.CODE_DAYS} days):", Sty.GRAY)
+            for code in codes:
+                _print(f"    {code}", Sty.BOLD)
         else:
-            print("Usage: cluster list | cluster create|invite|remove <name> | cluster join <code>", file=sys.stderr)
+            print(_USAGE, file=sys.stderr)
             return 2
     except (cluster.ClusterError, ContractError, RuntimeError, OSError) as exc:
         _print(f"  {exc}", Sty.WARNING)
@@ -162,7 +190,7 @@ def main(argv) -> int:
     # `cluster <verb> …` from the table; `global cluster …` is the old spelling.
     if argv and argv[0] in ("cluster", "clusters"):
         argv = argv[1:] or ["list"]
-    if argv and argv[0] in ("list", "create", "invite", "join", "accept", "remove"):
+    if argv and argv[0] in ("list", "create", "invite", "join", "accept", "remove", "groups", "codes"):
         return cmd_cluster(argv)
-    print("Usage: cluster list | cluster create|invite|remove <name> | cluster join <code>", file=sys.stderr)
+    print(_USAGE, file=sys.stderr)
     return 2

remoteRF_server/server/federation/cluster.py

@@ -33,19 +33,25 @@ import json
 import os
 import re
 import secrets
+import sqlite3
 import time
+from datetime import datetime
 from pathlib import Path
 from typing import Optional
 from uuid import uuid4
 
-from remoterf_federation_core import ContractError, canonical_json
+from remoterf_federation_core import ContractError, FederationError, canonical_json
 
 from .. import global_onboarding as g
 from .contracts import ContractStore
+from .migrations import migrate_gate_f_usergroups_schema
 from .trust import TrustedKeyStore
 
 CAPABILITIES = ["DEVICE_CONTROL", "DEVICE_READ", "DEVICE_RESERVE", "FEDERATED_ENROLL", "PERMISSIONS_READ"]
 CONTRACT_DAYS = 365
+CODE_PREFIX = "cluster."          # a student code minted here, redeemed here
+CLUSTER_CODE = "cluster"          # the `code_name` a cluster enrolment carries to a partner
+CODE_DAYS = 7
 _NAME = re.compile(r"^[a-z0-9][a-z0-9-]{0,62}$")
 _STATE_FILE = "clusters.json"
 
@@ -115,6 +121,20 @@ def _find(clusters: dict, name: str) -> dict:
     return clusters[name]
 
 
+def _parties(cluster: dict) -> list[tuple[str, dict]]:
+    """Every lab we hold a contract with in this cluster: (deployment_id, party)."""
+    if cluster["role"] == "owner":
+        return list(cluster["members"].items())
+    return [(cluster["peer"], cluster)] + list(cluster.get("peers", {}).items())
+
+
+def contract_cluster(contract_id: str) -> tuple[str, dict] | None:
+    for name, cluster in load().items():
+        if any(party.get("contract_id") == contract_id for _, party in _parties(cluster)):
+            return name, cluster
+    return None
+
+
 # -----------------------------
 # Identity and stores
 # -----------------------------
@@ -182,6 +202,22 @@ def _pin_self() -> dict:
     return me
 
 
+def _identity_of(deployment_id: str) -> Optional[dict]:
+    """A pinned lab's identity, as it would advertise it."""
+    rows = [row for row in _trust().list(deployment_id) if row["state"] == "active"]
+    if not rows:
+        return None
+    row = rows[-1]
+    return {key: row[key] for key in ("deployment_id", "kid", "public_key_b64", "public_key_sha256")} | {
+        "valid_from": int(row["valid_from"]), "valid_until": row["valid_until"]}
+
+
+def _usergroups() -> sqlite3.Connection:
+    conn = sqlite3.connect(_db_path(), timeout=10.0)
+    migrate_gate_f_usergroups_schema(conn)
+    return conn
+
+
 # -----------------------------
 # Invite codes
 # -----------------------------
@@ -279,8 +315,12 @@ def _propose(cluster: dict, member: dict, peer: str) -> None:
     """Owner: pin the joiner and propose its bilateral contract."""
     joiner = member.pop("joiner")
     _pin(joiner, source="cluster_invite")
+    _contract_with(member, joiner)
+
+
+def _contract_with(party: dict, other: dict) -> None:
     me = _identity()
-    a, b = sorted([me, joiner], key=lambda item: item["deployment_id"])
+    a, b = sorted([me, other], key=lambda item: item["deployment_id"])
     now = int(time.time())
     terms = {
         "contract_id": str(uuid4()),
@@ -297,8 +337,8 @@ def _propose(cluster: dict, member: dict, peer: str) -> None:
         "supersedes_version": None,
     }
     _contracts().propose(terms, actor_admin_ref="cluster")
-    member.update(state="proposed", contract_id=terms["contract_id"])
-    _publish(member)
+    party.update(state="proposed", contract_id=terms["contract_id"])
+    _publish(party)
 
 
 def accept(name: str, peer: str | None = None) -> dict:
@@ -335,13 +375,13 @@ def remove(name: str) -> str:
     clusters = load()
     cluster = _find(clusters, name)
     outcome = "removed"
-    parties = list(cluster["members"].values()) if cluster["role"] == "owner" else [cluster]
-    for party in parties:
+    for _, party in _parties(cluster):
         _revoke(party.get("contract_id"))
         try:
             _publish(party)
         except g.GlobalError:
             outcome = "removed locally; could not reach Global to tell the other lab"
+    _forget_accounts(name, cluster)
     del clusters[name]
     save(clusters)
     return outcome
@@ -374,11 +414,182 @@ def list_clusters() -> list[dict]:
                     state = store.show(cluster["contract_id"], 1)["state"]
                 except ContractError:
                     pass
-            item.update(peer=cluster["peer"], peer_name=cluster.get("peer_name"), state=state)
+            peers = [{"deployment_id": peer, "display_name": party.get("display_name"), "state": party.get("state")}
+                     for peer, party in sorted(cluster.get("peers", {}).items())]
+            item.update(peer=cluster["peer"], peer_name=cluster.get("peer_name"), state=state, peers=peers)
+        item.update(groups=groups(name), **_account_counts(name))
         out.append(item)
     return out
 
 
+# -----------------------------
+# Groups and students: what a cluster actually shares
+# -----------------------------
+# Attaching is local -- a partner never sees group names, only the devices a
+# proxy in those groups may use. A student redeems one cluster code at home
+# and is enrolled at every lab in the cluster; each lab puts the proxy into
+# whatever it has attached.
+
+def _group(conn, ref: str) -> tuple[int, str]:
+    row = conn.execute(
+        "SELECT group_id,group_name FROM UserGroups WHERE group_name=? OR CAST(group_id AS TEXT)=?",
+        (ref, ref),
+    ).fetchone()
+    if row is None:
+        raise ClusterError(f"no user group named {ref}")
+    return int(row[0]), row[1]
+
+
+def groups(name: str) -> list[dict]:
+    cluster = _find(load(), name)
+    out = []
+    with _usergroups() as conn:
+        for group_id in cluster.get("groups", []):
+            row = conn.execute("SELECT group_name FROM UserGroups WHERE group_id=?", (group_id,)).fetchone()
+            if row is not None:
+                out.append({"group_id": group_id, "group_name": row[0]})
+    return out
+
+
+def _account_counts(name: str) -> dict:
+    with _usergroups() as conn:
+        rows = dict(conn.execute(
+            "SELECT kind,COUNT(*) FROM ClusterAccounts WHERE cluster_name=? GROUP BY kind", (name,)).fetchall())
+    return {"students": rows.get("local", 0), "visitors": rows.get("proxy", 0)}
+
+
+def attach_group(name: str, ref: str) -> str:
+    clusters = load()
+    cluster = _find(clusters, name)
+    with _usergroups() as conn:
+        group_id, group_name = _group(conn, ref)
+        if group_id in cluster.get("groups", []):
+            raise ClusterError(f"{group_name} is already attached to {name}")
+        cluster.setdefault("groups", []).append(group_id)
+        conn.execute(
+            "INSERT OR IGNORE INTO UsersLookup(user_id,group_id) "
+            "SELECT local_account_id,? FROM ClusterAccounts WHERE cluster_name=?",
+            (group_id, name),
+        )
+    save(clusters)
+    return group_name
+
+
+def detach_group(name: str, ref: str) -> str:
+    clusters = load()
+    cluster = _find(clusters, name)
+    with _usergroups() as conn:
+        group_id, group_name = _group(conn, ref)
+        if group_id not in cluster.get("groups", []):
+            raise ClusterError(f"{group_name} is not attached to {name}")
+        cluster["groups"].remove(group_id)
+        conn.execute(
+            "DELETE FROM UsersLookup WHERE group_id=? AND user_id IN "
+            "(SELECT local_account_id FROM ClusterAccounts WHERE cluster_name=?)",
+            (group_id, name),
+        )
+    save(clusters)
+    return group_name
+
+
+def _forget_accounts(name: str, cluster: dict) -> None:
+    with _usergroups() as conn:
+        for group_id in cluster.get("groups", []):
+            conn.execute(
+                "DELETE FROM UsersLookup WHERE group_id=? AND user_id IN "
+                "(SELECT local_account_id FROM ClusterAccounts WHERE cluster_name=?)",
+                (group_id, name),
+            )
+        conn.execute("DELETE FROM ClusterAccounts WHERE cluster_name=?", (name,))
+
+
+def join_account(conn, name: str, cluster: dict, local_account_id: int, *, kind: str) -> None:
+    """Put an account (a local student or a partner's proxy) into the cluster
+    and every group attached to it. Runs inside the caller's transaction."""
+    conn.execute(
+        "INSERT OR IGNORE INTO ClusterAccounts(cluster_name,local_account_id,kind,joined_at) VALUES (?,?,?,?)",
+        (name, int(local_account_id), kind, int(time.time())),
+    )
+    for group_id in cluster.get("groups", []):
+        conn.execute("INSERT OR IGNORE INTO UsersLookup(user_id,group_id) VALUES (?,?)",
+                     (int(local_account_id), int(group_id)))
+
+
+def mint_codes(name: str, *, count: int = 1, uses: int = 1, days: int = CODE_DAYS) -> list[str]:
+    _find(load(), name)
+    if not 1 <= count <= 200 or uses < 1 or days < 1:
+        raise ClusterError("count must be 1-200, uses and days at least 1")
+    codes = [CODE_PREFIX + secrets.token_urlsafe(18) for _ in range(count)]
+    with _usergroups() as conn:
+        conn.executemany(
+            "INSERT INTO EnrollmentCodes(code_name,group_id,uses,duration_sec,created_at,cluster_name) "
+            "VALUES (?,-1,?,?,?,?)",
+            [(code, uses, days * 86400, datetime.now().isoformat(sep=" "), name) for code in codes],
+        )
+    return codes
+
+
+def redeem_code(local_account_id: int, code_name: str) -> Optional[str]:
+    """A student types a cluster code at home: returns the cluster joined, or None."""
+    if not code_name.startswith(CODE_PREFIX):
+        return None
+    clusters = load()
+    with _usergroups() as conn:
+        row = conn.execute(
+            "SELECT code_id,cluster_name,uses,duration_sec,created_at FROM EnrollmentCodes "
+            "WHERE code_name=? AND cluster_name IS NOT NULL",
+            (code_name,),
+        ).fetchone()
+        if row is None or int(row[2]) <= 0 or row[1] not in clusters:
+            return None
+        if int(row[3]) > 0:
+            try:
+                created = datetime.fromisoformat(str(row[4]))
+            except ValueError:
+                return None
+            if (datetime.now() - created).total_seconds() >= int(row[3]):
+                return None
+        conn.execute("UPDATE EnrollmentCodes SET uses=uses-1 WHERE code_id=?", (row[0],))
+        conn.execute("DELETE FROM EnrollmentCodes WHERE code_id=? AND uses<=0", (row[0],))
+        join_account(conn, row[1], clusters[row[1]], local_account_id, kind="local")
+    return row[1]
+
+
+def enroll_students(home, notify=None, *, only_account: int | None = None) -> None:
+    """HOME: enrol every local student at every active lab they are not yet
+    at. Idempotent; the tick retries whatever failed."""
+    notify = notify or (lambda text: None)
+    enroller, plane = getattr(home, "federation_enroller", None), getattr(home, "federation_devices", None)
+    if enroller is None or plane is None:
+        return
+    clusters = load()
+    with _usergroups() as conn:
+        rows = conn.execute(
+            "SELECT cluster_name,local_account_id FROM ClusterAccounts WHERE kind='local'"
+            + (" AND local_account_id=?" if only_account is not None else ""),
+            (only_account,) if only_account is not None else (),
+        ).fetchall()
+    for name, account in rows:
+        cluster = clusters.get(name)
+        if cluster is None:
+            continue
+        enrolled = plane.enrolled(account)
+        for peer, party in _parties(cluster):
+            if party.get("state") != "active" or not party.get("contract_id") or peer in enrolled:
+                continue
+            try:
+                enroller.outbound.execute(
+                    local_account_id=account, destination_deployment_id=peer,
+                    contract_id=party["contract_id"], contract_version=1,
+                    action="federated_enroll", code_name=CLUSTER_CODE,
+                )
+            except (FederationError, OSError) as exc:
+                notify(f"[cluster] {name}: could not enrol account {account} at "
+                       f"{party.get('display_name') or peer}: {getattr(exc, 'code', exc)}")
+                continue
+            plane.record_enrollment(local_account_id=account, destination_deployment_id=peer)
+
+
 # -----------------------------
 # Agent: one pass per Global liveness tick
 # -----------------------------
@@ -452,6 +663,76 @@ def _advance(party: dict, peer: str, directory: list[dict], *, label: str, notif
         notify(f"[cluster] {label} was ended by the other lab")
 
 
+def _publish_roster(name: str, cluster: dict) -> None:
+    """Owner: whenever the active member set changes, sign and post it so the
+    members can pin each other and mesh."""
+    active = sorted(peer for peer, member in cluster["members"].items() if member.get("state") == "active")
+    if active == cluster.get("roster"):
+        return
+    key, _, me = g._signing_material()
+    members = []
+    for peer in active:
+        identity = _identity_of(peer)
+        if identity is not None:
+            members.append({"identity": identity, "display_name": cluster["members"][peer].get("display_name")})
+    roster = {"cluster_name": name, "owner": me, "issued_at": int(time.time()), "members": members}
+    signature = base64.b64encode(key.sign(canonical_json(roster).encode())).decode("ascii")
+    g.call("POST", "/v2/broker/clusters/roster", {"protocol_version": "2", "roster": roster, "signature": signature})
+    cluster["roster"] = active
+
+
+def _roster_signed_by(owner: str, roster: dict, signature: str) -> bool:
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    for row in _trust().list(owner):
+        if row["state"] != "active":
+            continue
+        try:
+            Ed25519PublicKey.from_public_bytes(base64.b64decode(row["public_key_b64"])).verify(
+                base64.b64decode(signature), canonical_json(roster).encode())
+            return True
+        except (InvalidSignature, ValueError):
+            continue
+    return False
+
+
+def _mesh(name: str, cluster: dict, rosters: list[dict], directory: list[dict], notify) -> None:
+    """Member: pin the other members the owner vouches for and hold one
+    contract with each. The lower deployment id proposes; the other accepts."""
+    me = g._signing_material()[2]
+    peers = cluster.setdefault("peers", {})
+    for item in rosters:
+        roster = item.get("roster") or {}
+        if roster.get("owner") != cluster["peer"] or roster.get("cluster_name") != name:
+            continue
+        if not _roster_signed_by(cluster["peer"], roster, item.get("signature", "")):
+            notify(f"[cluster] {name}: ignored a member list not signed by the owner")
+            continue
+        listed = {m["identity"]["deployment_id"]: m for m in roster.get("members", [])
+                  if m["identity"]["deployment_id"] != me}
+        for peer, member in listed.items():
+            if peer in peers:
+                continue
+            _pin(member["identity"], source="cluster_invite")
+            peers[peer] = {"display_name": member.get("display_name"), "contract_id": None,
+                           "state": "joined", "published": []}
+            if me < peer:
+                _contract_with(peers[peer], member["identity"])
+        for peer in [p for p in peers if p not in listed]:
+            _revoke(peers[peer].get("contract_id"))
+            try:
+                _publish(peers[peer])
+            except g.GlobalError:
+                pass
+            notify(f"[cluster] {name}: {peers[peer].get('display_name') or peer} left")
+            del peers[peer]
+        break
+    for peer, party in peers.items():
+        _advance(party, peer, directory, label=f"{name}: {party.get('display_name') or peer}",
+                 notify=notify, is_member=me > peer)
+
+
 def _collect_joins(name: str, cluster: dict, broker_invites: list[dict], notify) -> None:
     """Owner: turn redeemed invites into members; drop invites Global no longer holds."""
     seen = {item["invite_id"]: item for item in broker_invites}
@@ -478,14 +759,16 @@ def _collect_joins(name: str, cluster: dict, broker_invites: list[dict], notify)
             notify(f"[cluster] {peer} wants to join {name}: run `cluster accept {name}`")
 
 
-def tick(notify=None) -> None:
-    """One agent pass: move every cluster and member one step closer to active."""
+def tick(notify=None, home=None) -> None:
+    """One agent pass: move every cluster and member one step closer to active,
+    then (given the HOME runtime) enrol students wherever they are missing."""
     notify = notify or (lambda text: None)
     clusters = load()
     if not clusters:
         return
     directory = None
     broker_invites = None
+    rosters = None
     for name, cluster in clusters.items():
         if cluster["role"] == "owner":
             if cluster["invites"]:
@@ -500,8 +783,17 @@ def tick(notify=None) -> None:
             for peer, member in cluster["members"].items():
                 _advance(member, peer, directory, label=f"{name}: {member.get('display_name') or peer}",
                          notify=notify, is_member=False)
+            try:
+                _publish_roster(name, cluster)
+            except g.GlobalError as exc:
+                notify(f"[cluster] {name}: could not publish the member list: {exc}")
         else:
             if directory is None:
                 directory = g.call("GET", "/v2/broker/contracts")["contracts"]
             _advance(cluster, cluster["peer"], directory, label=name, notify=notify, is_member=True)
+            if rosters is None:
+                rosters = g.call("GET", "/v2/broker/clusters/roster")["rosters"]
+            _mesh(name, cluster, rosters, directory, notify)
         save(clusters)
+    if home is not None:
+        enroll_students(home, notify)

remoteRF_server/server/federation/enrollment.py

@@ -8,7 +8,7 @@ import sqlite3
 import time
 from datetime import datetime
 from pathlib import Path
-from uuid import uuid4
+from uuid import NAMESPACE_URL, uuid4, uuid5
 
 from remoterf_federation_core import (
     FederationError,
@@ -24,6 +24,8 @@ from remoterf_federation_core import (
 )
 
 from .destination import ActionRegistry, FederationBusinessError, ServerFederationExecutor
+
+CLUSTER_CODE = "cluster"
 from .migrations import configure_connection, migrate_gate_f_usergroups_schema
 from .principals import PreparedFederatedAccount, prepare_federated_account
 
@@ -294,6 +296,19 @@ class ServerFederatedEnrollHandler:
         """Never mutates owner authorization; invalid cases wait for owner tx."""
         claims = action.claims
         payload = action.request.value["payload"]
+        if payload["code_name"] == CLUSTER_CODE:
+            # No code to check: the home lab's signature under an active
+            # cluster contract is the vouching. Prepare a proxy only once.
+            with sqlite3.connect(self.usergroups_path) as conn:
+                if get_principal_tx(conn, claims["iss"], claims["sub"]) is not None:
+                    return None
+            return self.account_preparer(
+                self.reservations_path,
+                issuer_deployment_id=claims["iss"],
+                remote_subject_id=claims["sub"],
+                perms_path=self.perms_path,
+                now=int(self.clock()),
+            )
         with sqlite3.connect(self.usergroups_path) as conn:
             conn.row_factory = sqlite3.Row
             receipt = conn.execute(
@@ -367,10 +382,42 @@ class ServerFederatedEnrollHandler:
             "membership_present": membership_present,
         }
 
+    def _cluster_enroll(self, tx, action, now):
+        """Cluster enrolment: the contract names the cluster; the proxy joins
+        every group attached to it here. Re-running only re-adds memberships."""
+        from . import cluster as cluster_module
+
+        claims = action.claims
+        found = cluster_module.contract_cluster(claims["contract_id"])
+        if found is None:
+            raise FederationBusinessError("code_invalid")
+        name, cluster = found
+        principal = get_principal_tx(tx, claims["iss"], claims["sub"])
+        if principal is None:
+            prepared = action.prepared
+            if not isinstance(prepared, PreparedFederatedAccount):
+                raise RuntimeError("federated proxy preparation unavailable")
+            principal = resolve_or_create_principal_tx(
+                tx, issuer=claims["iss"], subject=claims["sub"], prepared=prepared, now=now
+            )
+        elif principal[4] != "active":
+            raise FederationBusinessError("principal_disabled")
+        else:
+            tx.execute("UPDATE FederatedPrincipals SET last_seen_at=? WHERE id=?", (now, principal[0]))
+        cluster_module.join_account(tx, name, cluster, int(principal[3]), kind="proxy")
+        self._audit(tx, action, code="ok", principal_id=principal[0], metadata={"cluster": name})
+        # Group names stay local; the home lab learns only which cluster admitted it.
+        return self._result(
+            action, redemption_id=str(uuid5(NAMESPACE_URL, f"remoterf-cluster:{name}:{principal[0]}")),
+            membership_present=True, groups=[{"group_id": "0", "group_name": f"cluster {name}"}], now=now,
+        )
+
     def __call__(self, tx, action):
         claims = action.claims
         payload = action.request.value["payload"]
         now = int(self.clock())
+        if payload["code_name"] == CLUSTER_CODE:
+            return self._cluster_enroll(tx, action, now)
         receipt = lookup_redemption_tx(
             tx, claims["iss"], claims["sub"], claims["request_id"]
         )

remoteRF_server/server/federation/home_devices.py

@@ -116,6 +116,10 @@ class ServerHomeDevices:
                 (int(local_account_id), canonical_uuid(destination_deployment_id), int(self.clock())),
             )
 
+    def enrolled(self, local_account_id: int) -> set[str]:
+        with self._connect() as conn:
+            return self._enrolled_at(conn, local_account_id)
+
     def _enrolled_at(self, conn, local_account_id: int) -> set[str]:
         rows = conn.execute(
             "SELECT destination_deployment_id FROM FederatedEnrollments WHERE local_account_id=?",

remoteRF_server/server/federation/migrations.py

@@ -769,6 +769,16 @@ def migrate_gate_f_usergroups_schema(conn: sqlite3.Connection) -> None:
     group_columns = {str(item[1]) for item in conn.execute("PRAGMA table_info(UserGroups)")}
     if "lan_only" not in group_columns:
         conn.execute("ALTER TABLE UserGroups ADD COLUMN lan_only INTEGER NOT NULL DEFAULT 0")
+    # Cluster codes enrol into a cluster, not a group (group_id is -1 then);
+    # ClusterAccounts remembers who joined so attached groups can follow.
+    if "cluster_name" not in columns:
+        conn.execute("ALTER TABLE EnrollmentCodes ADD COLUMN cluster_name TEXT")
+    conn.executescript(
+        "CREATE TABLE IF NOT EXISTS ClusterAccounts ("
+        "cluster_name TEXT NOT NULL, local_account_id INTEGER NOT NULL, "
+        "kind TEXT NOT NULL CHECK(kind IN ('local','proxy')), joined_at INTEGER NOT NULL, "
+        "PRIMARY KEY(cluster_name,local_account_id));"
+    )
     conn.executescript(_GATE_F_DDL)
     conn.execute(
         "INSERT OR IGNORE INTO SchemaMigrations "

remoteRF_server/server/global_onboarding.py

@@ -987,7 +987,11 @@ def _cluster_tick() -> None:
             print(text)
 
     try:
-        cluster.tick(notify)
+        from .reservation import reservation_handler
+    except Exception:  # noqa: BLE001
+        reservation_handler = None
+    try:
+        cluster.tick(notify, home=reservation_handler)
     except Exception as exc:  # noqa: BLE001
         logging.getLogger("remoteRF_server.global").warning("cluster tick failed: %s", exc)
 

remoteRF_server/server/reservation.py

@@ -321,6 +321,17 @@ class ReservationHandler:
                             "UC": map_arg("Federated enrollment confirmed."),
                             "federation": map_arg(canonical_json(result)),
                         }
+                    if code_name.startswith("cluster."):
+                        from .federation import cluster as cluster_module
+
+                        joined = cluster_module.redeem_code(acc_id, code_name)
+                        if joined is None:
+                            return {"UE": map_arg(f"Failed to enroll {username}. Invalid or expired code.")}
+                        try:
+                            cluster_module.enroll_students(self, only_account=acc_id)
+                        except Exception:  # noqa: BLE001 - the tick retries
+                            pass
+                        return {"UC": map_arg(f"Enrolled {username} in cluster {joined}.")}
                     if RELAYED.get() and user_group_handler.code_is_lan_only(code_name=code_name):
                         return {"UE": map_arg(lan_only_hint("This enrollment code"))}
                     if user_group_handler.enroll_user_with_code(uid=acc_id, code_name=code_name):

remoteRF_server/server/user_group_cli.py

@@ -37,7 +37,7 @@ def _invites(rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         code = str(row.get("code_name", ""))
         # A federation-bound code is redeemed through its signed invitation,
         # never typed as a Global invite.
-        federated = row.get("federation_contract_id") is not None
+        federated = row.get("federation_contract_id") is not None or row.get("cluster_name")
         row["invite"] = code if federated else invite(
             code, lan_only=lan_only.get(int(row.get("group_id", -1)), False)
         )
@@ -562,17 +562,18 @@ def list_enrollment_codes_local(session) -> None:
             row.get("federation_contract_id"),
             row.get("federation_contract_version"),
             row.get("allowed_issuer_deployment_id"),
+            row.get("cluster_name"),
         )
         buckets.setdefault(key, []).append(row)
 
     width = content_width()
     lines: List[str] = []
-    for (gid, uses, duration, contract, version, issuer), items in sorted(
+    for (gid, uses, duration, contract, version, issuer, cluster_name), items in sorted(
         buckets.items(), key=lambda kv: (kv[0][0], kv[0][3] or "", -kv[0][1], kv[0][2])
     ):
         group = groups.get(gid, {})
         head = " · ".join([
-            f"group {gid} {group.get('group_name', '?')}".rstrip(),
+            f"cluster {cluster_name}" if cluster_name else f"group {gid} {group.get('group_name', '?')}".rstrip(),
             f"{_plural(uses, 'use')} left",
             _fmt_duration(duration),
             _plural(len(items), "code"),

remoteRF_server/server/user_group_handler.py

@@ -610,7 +610,7 @@ class UserGroupHandler:
             self.cursor.execute(
                 "SELECT code_id, code_name, group_id, uses, duration_sec, "
                 "federation_contract_id, federation_contract_version, "
-                "allowed_issuer_deployment_id, federation_expires_at "
+                "allowed_issuer_deployment_id, federation_expires_at, cluster_name "
                 "FROM EnrollmentCodes"
             )
             rows = self.cursor.fetchall() or []
@@ -631,6 +631,7 @@ class UserGroupHandler:
                             "federation_contract_version": r[6],
                             "allowed_issuer_deployment_id": r[7],
                             "federation_expires_at": r[8],
+                            "cluster_name": r[9],
                         }
                     )
                 except Exception:

{remoterf_server-1.1.0.dev30.dist-info → remoterf_server-1.1.0.dev32.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remoteRF-server
-Version: 1.1.0.dev30
+Version: 1.1.0.dev32
 Summary: RemoteRF server-side control package
 License: GPL-3.0-or-later
 Classifier: Programming Language :: Python :: 3
@@ -9,7 +9,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: remoterf-federation-core==0.14.0
+Requires-Dist: remoterf-federation-core==0.15.0
 Requires-Dist: grpcio<2.0.0,>=1.81.1
 Requires-Dist: protobuf<7.0.0,>=6.33.5
 Requires-Dist: numpy

{remoterf_server-1.1.0.dev30.dist-info → remoterf_server-1.1.0.dev32.dist-info}/RECORD

@@ -52,35 +52,35 @@ remoteRF_server/host/host_tunnel_server.py,sha256=sz06xOtFbaDZSy1UQfw6faKhJmuOy5
 remoteRF_server/server/__init__.py,sha256=-1h_xQjiE66oiWRO-vnLGJ4smpgUNhFuV-ZreW9_tD4,667
 remoteRF_server/server/acc_perms.py,sha256=2loCvstVu8uvsb2uCv2Sk7iNQ5GyO_sBIkPQFzqOaRI,13334
 remoteRF_server/server/cert_provider.py,sha256=CRDrZL4DSf-eL6wzPJzwucrzPLOr2PvNRq5V--oZtr0,6272
-remoteRF_server/server/commands.py,sha256=dH19PK86cUiZhTnN9jC1RdM1t_t6dPuL6x-bdACxkSY,17008
+remoteRF_server/server/commands.py,sha256=9ExGTi3nG7wqgSAyOEIFMDz0iBFLwC8QJdXrKNZNB5A,17277
 remoteRF_server/server/console.py,sha256=J91LfwPVmBgielOxfE740NOYduekggyZkqi-47y_A4w,4472
 remoteRF_server/server/control.py,sha256=Uq1Fk0zIoHHX_EXfz3OuNle8urvO_UhAiB5Lk5cs2e4,5177
 remoteRF_server/server/device_manager.py,sha256=nRTvk_jeZFU3QnlM6qf3DIckU2V2e_gyDeD5gW14KQI,38802
 remoteRF_server/server/direct_path.py,sha256=CQs0uPTANJq6Bn-TzsV0APmD3hYKH8xYvczXZZk1OXk,15229
 remoteRF_server/server/dynamic_v2.py,sha256=AMhQEFhNAvCNcF-PdfCCQQLmeoaR7s1Os8et1KFGn_8,70814
-remoteRF_server/server/global_onboarding.py,sha256=UwTkVZYTGspHaKcHtAV7TA9DnxH5OB82d5LDc4EDIr4,39730
+remoteRF_server/server/global_onboarding.py,sha256=boLAKXCKvcsIY3TDiFwduMaHdDMB9Cr104MyWJYZ-BA,39891
 remoteRF_server/server/grpc_server.py,sha256=91FpJubzN_Wfuk6fW_owIEzNCukd333sAGW68FUU8pk,46787
 remoteRF_server/server/host_dynamic_v2.py,sha256=1rJQwP4knSd0EXkByrSn_ryjLx81f6sp6SNYr_aEass,8105
-remoteRF_server/server/reservation.py,sha256=Cv8A7U2N6trUJayW8TJw1KDfFZhZED2UMF3iDLcpaSs,66731
+remoteRF_server/server/reservation.py,sha256=83rEWlfKauxqDOgv2IdDa8JBZWsLf_l0v1sEv9xl1RM,67411
 remoteRF_server/server/rpc_manager.py,sha256=BDvsTSVRxwNF2ujuMbIb5TYNAUI6AH4xXBuXrb8lltM,17223
-remoteRF_server/server/user_group_cli.py,sha256=FGdzhzRfIukmwpzEUKRiT15d7l2kcw_xgkJp_ZXx_TY,24947
-remoteRF_server/server/user_group_handler.py,sha256=EpL3zbz_e8j_MwF88ewxE4J0V61TrUuc-XkVIKVNSuo,41716
+remoteRF_server/server/user_group_cli.py,sha256=6zNquuedH_q6pwq4trzRkEfE0wzAe7-RkFlGMWR-ZnM,25072
+remoteRF_server/server/user_group_handler.py,sha256=1ax73W_P3H6GDxQS13evwA7G7skIElFVLuS0MFqsFyU,41780
 remoteRF_server/server/v2_errors.py,sha256=IS3hIhf5tDe7jaOrDAVQPjGBpqAjN7442BlJYgfJo7g,3331
 remoteRF_server/server/deployment/__init__.py,sha256=YV86uafd8XiGD7sLaqNfO5xxmt5te2R6DUhD-w1lZuY,77
 remoteRF_server/server/deployment/capabilities.py,sha256=20RxmGG03VoQQZnV3jGhc-3i9B5hOl5fCopnsErFjPk,872
-remoteRF_server/server/federation/__init__.py,sha256=MZLqqh0Lzzh1t59VXrkS_bdpMO5znk1UVBjRGPvnUCg,735
+remoteRF_server/server/federation/__init__.py,sha256=auqdGiGnEGIKQiXX2jFVt8iWmfyZ-V3w4dUmtWDKAZE,735
 remoteRF_server/server/federation/admin.py,sha256=t3F17FIytekzclPICmaFJEA4-F5OuWcDx3rgmFga17A,9187
-remoteRF_server/server/federation/cli.py,sha256=Ax0tQw7_giLUP5lX1Y6x3sS1cbUbU2PxYur5k_5f3Po,7028
-remoteRF_server/server/federation/cluster.py,sha256=2C8ys2BwUSxCLlYGvNjWU840q8e6H2ShGfl380yzA0I,19970
+remoteRF_server/server/federation/cli.py,sha256=hQt6tM2y42EzKE2WDzBat3pxEqLjreunogjI_kauxYk,8849
+remoteRF_server/server/federation/cluster.py,sha256=dsraUf7wKG4GdqcyhdO195v1ypwSRpFcJdyY5uatHCM,32932
 remoteRF_server/server/federation/contracts.py,sha256=NYh7lb_9etJHFfzXwevjC4HfSBUypLxg5xGeBgydLF4,29305
 remoteRF_server/server/federation/destination.py,sha256=XawmGCiVbL_MfNNn8xwV9_bYxUDW1L7efCpL11K2JAc,35909
 remoteRF_server/server/federation/devices.py,sha256=n5MvnD0UZyl4sFpiekG9ProanWXTYizYq6YchCflLgY,18061
-remoteRF_server/server/federation/enrollment.py,sha256=1RFwc-XJ9oYGg-WIIwPzvMpdELR_410p8hTD1FNWktU,20693
+remoteRF_server/server/federation/enrollment.py,sha256=HsyyPpMzuQ289sxHj4XLTbiCVpp3er1YXBXQ6OZyEfw,23168
 remoteRF_server/server/federation/home.py,sha256=-_0__wJN50Y1-Dd396_iUZjGESBkoBNGISXb8gbLrjM,23982
-remoteRF_server/server/federation/home_devices.py,sha256=HTOC1FCYLCOQ97jtQw9q0h_QaYtLr2JnLc0Zu_t25Cw,18595
+remoteRF_server/server/federation/home_devices.py,sha256=lbsw201HBOYPP5vbN172vdm2O_ouCdZBo1cRYCVScmg,18754
 remoteRF_server/server/federation/identity.py,sha256=UtQJKm2mChWZto0ZCg385k_ObrwOUtxY7XFyU_s5Q10,7436
 remoteRF_server/server/federation/legacy_state.py,sha256=SpeTZHFqymNYGWG7A3B-78dIRIVLYltBbE2zGDWzt-Q,19838
-remoteRF_server/server/federation/migrations.py,sha256=Sh6GdClQod0p5LMWyQLwAgTHkZouLSxgPKmGSvCi2Do,50018
+remoteRF_server/server/federation/migrations.py,sha256=wClgRrwelcqHebSLJEDQR98WWUgzaEMrio8DLVOfcdA,50594
 remoteRF_server/server/federation/permissions.py,sha256=ou4uFsMAGHnDeBW6zbpGeUTwp0thlYXT5nIAgd3B1rg,15861
 remoteRF_server/server/federation/principals.py,sha256=CsRYa8POmtMaxKzAGwY14sxBTNS5uKjM1nUE19mjpoQ,10410
 remoteRF_server/server/federation/runtime.py,sha256=5CoDlu0jSQrFdwRoGL2Z4_CWxnA46B3j6-eNQo8N2FI,7624
@@ -90,9 +90,9 @@ remoteRF_server/tools/gen_certs.py,sha256=Vbyu8JjRu__UYPVmyCRXt5SOw0Za1HV7g1md3G
 remoteRF_server/tools/gist_status.py,sha256=SFv2iQgQrIKT9gxKrU-_Dr7S0p0rE4wQM6J3OC6FcoM,4649
 remoteRF_server/tools/gist_status_testing.py,sha256=IYw7UkPjAUpKDTtIlnYGb5g6SJkwz4TRGUfJJ6f4LhQ,2690
 remoteRF_server/tools/introspect_uhd.py,sha256=vUpPb0rM9tsHPxWadS3EfMDE-gMd-TvNV0TjrZOQqBY,4531
-remoterf_server-1.1.0.dev30.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-remoterf_server-1.1.0.dev30.dist-info/METADATA,sha256=HAEJaoA51VNwScm3KxXvq650DbitxyOWXy1ChAXpD3s,42069
-remoterf_server-1.1.0.dev30.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-remoterf_server-1.1.0.dev30.dist-info/entry_points.txt,sha256=_bbKk65PfYi-n6zUjqOiOwcalf_Ws1TCGATIe1TukxE,136
-remoterf_server-1.1.0.dev30.dist-info/top_level.txt,sha256=NuYWe8dSx3qdbxshWBwOgx68EHmJ9I8Zvxam4ARsQ_I,30
-remoterf_server-1.1.0.dev30.dist-info/RECORD,,
+remoterf_server-1.1.0.dev32.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+remoterf_server-1.1.0.dev32.dist-info/METADATA,sha256=E5JcHfXHeFhGNYFGR6kxbeehuNFsCStN4wJr9E6RrCk,42069
+remoterf_server-1.1.0.dev32.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+remoterf_server-1.1.0.dev32.dist-info/entry_points.txt,sha256=_bbKk65PfYi-n6zUjqOiOwcalf_Ws1TCGATIe1TukxE,136
+remoterf_server-1.1.0.dev32.dist-info/top_level.txt,sha256=NuYWe8dSx3qdbxshWBwOgx68EHmJ9I8Zvxam4ARsQ_I,30
+remoterf_server-1.1.0.dev32.dist-info/RECORD,,