From 7f6a993e4558b05edaf050546ff5d9bd1d801fd3 Mon Sep 17 00:00:00 2001 From: Jer Miller Date: Sat, 13 Jun 2026 17:26:03 -0600 Subject: [PATCH] feat(link): store assigned + client labels, compose display_label MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both pairing labels are now optional and stored as distinct fields: device_label stays the home-assigned/renameable label, while the new journal-local client_label (omit-when-empty, legacy-tolerant on read) holds the client's hostname/self-name. The old client-wins collapse is gone. sol link join --label is optional, defaulting to the sanitized client hostname with a path-safe linked-system fallback; sol call link pair --device-label is optional. The server composes display_label (assigned (client) when they differ) in _entry_to_json and the pair-complete event; the workspace and CLI render it instead of hand-composing. Cert CN and peer journal-source labels keep their prior non-empty semantics via a derived cert_label. No wire/protocol record shape changed — client_label is local-only. Co-Authored-By: Claude Opus 4.8 (1M context) --- solstone/apps/link/call.py | 15 ++- solstone/apps/link/routes.py | 52 +++++--- .../apps/link/tests/test_api_devices_role.py | 36 +++++- solstone/apps/link/tests/test_by_code.py | 112 +++++++++++++++++- solstone/apps/link/tests/test_pair_copy.py | 1 - solstone/apps/link/tests/test_pair_start.py | 47 ++++++++ .../tests/test_peer_journal_source_pairing.py | 32 +++++ solstone/apps/link/tests/test_rename_route.py | 2 + .../apps/link/tests/test_workspace_copy.py | 1 - .../apps/link/tests/test_workspace_states.py | 24 ++++ solstone/apps/link/workspace.html | 10 +- .../apps/observer/tests/test_pl_pairing.py | 2 + solstone/think/link/auth.py | 21 +++- solstone/think/link/join_cli.py | 39 +++++- tests/link/test_auth.py | 56 +++++++++ tests/link/test_link_join_label_validation.py | 23 +++- tests/link/test_link_join_observer.py | 52 +++++++- tests/test_link_call_parity.py | 69 ++++++++++- 18 files changed, 551 insertions(+), 43 deletions(-) diff --git a/solstone/apps/link/call.py b/solstone/apps/link/call.py index 128888ee6..dee8e0b32 100644 --- a/solstone/apps/link/call.py +++ b/solstone/apps/link/call.py @@ -272,8 +272,8 @@ def private_link_disable() -> None: @app.command() @convey_cli def pair( - device_label: str = typer.Option( - ..., "--device-label", help="Label for the linked system being paired" + device_label: str | None = typer.Option( + None, "--device-label", help="Label for the linked system being paired" ), as_role: str | None = typer.Option( None, @@ -305,7 +305,7 @@ def pair( raise typer.Exit(2) client = get_client() - payload = {"device_label": device_label} + payload = {"device_label": device_label or ""} if as_role is not None: payload["role"] = as_role mint = client.request( @@ -325,7 +325,8 @@ def pair( typer.echo(f"manual code: {manual_code}") typer.echo(f"Pair URL: {url}") typer.echo(f"CA fingerprint: sha256:{ca_fp}") - typer.echo(f"Device: {device_label}{' (peer)' if as_role == 'peer' else ''}") + if device_label: + typer.echo(f"Device: {device_label}{' (peer)' if as_role == 'peer' else ''}") typer.echo("") typer.echo("Waiting for linked system…") @@ -341,7 +342,8 @@ def pair( if new_entries: entry = new_entries[-1] suffix = " (peer)" if entry["role"] == "peer" else "" - typer.echo(f"Paired: {entry['device_label']}{suffix}") + label = entry.get("display_label") or entry["device_label"] + typer.echo(f"Paired: {label}{suffix}") typer.echo(f" fingerprint: {entry['fingerprint']}") typer.echo(f" paired_at: {entry['paired_at']}") raise typer.Exit(0) @@ -387,8 +389,9 @@ def list_devices() -> None: typer.echo("") typer.echo(heading) for device in entries: + label = device.get("display_label") or device["device_label"] typer.echo( - f"- {device['device_label']}" + f"- {label}" f" — added {_relative_time(device['paired_at'])}" f" — last seen {_relative_time(device['last_seen_at'])}" f" [{device['fingerprint_short']}]" diff --git a/solstone/apps/link/routes.py b/solstone/apps/link/routes.py index fdde73ad0..54e09563a 100644 --- a/solstone/apps/link/routes.py +++ b/solstone/apps/link/routes.py @@ -160,6 +160,14 @@ def _default_device_label() -> str: ) +def _display_label(assigned: str, client: str) -> str: + assigned = (assigned or "").strip() + client = (client or "").strip() + if assigned and client and assigned != client: + return f"{assigned} ({client})" + return assigned or client + + def _rough_network(mode: str) -> str: return "anywhere" if mode == "pl-via-spl" else "network" @@ -537,9 +545,7 @@ def api_pair_nonce_status() -> Any: def pair_start() -> Any: """Generate a single-use 5-minute nonce and return link-ready payload.""" payload = request.get_json(silent=True) or {} - device_label = ( - str(payload.get("device_label") or "").strip() or _default_device_label() - ) + device_label = str(payload.get("device_label") or "").strip() raw_role = payload.get("role", "") role = "" if raw_role is None else raw_role if not isinstance(role, str) or role not in VALID_ROLES: @@ -614,13 +620,15 @@ def pair_start() -> Any: def _complete_pairing( consumed: Nonce, csr_pem: str, - device_label: str, + assigned_label: str, + client_label: str, *, network: str, sender_instance_id: str | None = None, ) -> tuple[dict[str, Any], str, str]: ca = load_or_generate_ca(ca_dir()) - client_cert_pem, fingerprint = sign_csr(ca, csr_pem, device_label) + cert_label = client_label or assigned_label or _default_device_label() + client_cert_pem, fingerprint = sign_csr(ca, csr_pem, cert_label) state = LinkState.load_or_create() paired_at = _utc_now_iso() @@ -643,18 +651,19 @@ def _complete_pairing( if is_peer(consumed.role): journal_source_record_path = mint_pl_journal_source_record( fingerprint=fingerprint, - device_label=device_label, + device_label=cert_label, paired_at=paired_at, peer_instance_id=sender_instance_id, ) create_state_directory(Path(get_journal()), journal_source_record_path.stem) _authorized().add( fingerprint=fingerprint, - device_label=device_label, + device_label=assigned_label, instance_id=state.instance_id, role="peer" if is_peer(consumed.role) else "", paired_at=paired_at, network=network, + client_label=client_label, ) except Exception: if journal_source_record_path is not None: @@ -693,7 +702,7 @@ def pair() -> Any: Body (JSON): { "csr": "", // required - "device_label": "", // optional (falls back to nonce label) + "device_label": "", // optional client self-name "nonce": "" // optional: may be in body instead of query } @@ -736,21 +745,28 @@ def pair() -> Any: detail="nonce expired or used", ) - effective_label = device_label or (consumed.device_label or _default_device_label()) + assigned_label = consumed.device_label + client_label = device_label network = _rough_network(g.identity.mode) try: response, fingerprint, paired_at = _complete_pairing( consumed, csr_pem, - effective_label, + assigned_label, + client_label, network=network, sender_instance_id=sender_instance_id, ) except ValueError as exc: logger.info("pair: bad csr: %s", exc) return error_response(PAIRING_KEY_INVALID, detail=f"bad csr: {exc}") - _emit_pair_complete(effective_label, fingerprint, paired_at, network=network) + _emit_pair_complete( + _display_label(assigned_label, client_label), + fingerprint, + paired_at, + network=network, + ) return jsonify(response) @@ -790,20 +806,27 @@ def by_code() -> Any: detail="nonce expired or used", ) - effective_label = device_label or consumed.device_label or _default_device_label() + assigned_label = consumed.device_label + client_label = device_label network = _rough_network(g.identity.mode) try: response, fingerprint, paired_at = _complete_pairing( consumed, csr_pem, - effective_label, + assigned_label, + client_label, network=network, sender_instance_id=sender_instance_id, ) except ValueError as exc: logger.info("by-code: bad csr: %s", exc) return error_response(PAIRING_KEY_INVALID, detail=f"bad csr: {exc}") - _emit_pair_complete(effective_label, fingerprint, paired_at, network=network) + _emit_pair_complete( + _display_label(assigned_label, client_label), + fingerprint, + paired_at, + network=network, + ) return jsonify(response) @@ -919,6 +942,7 @@ def _entry_to_json(entry: ClientEntry) -> dict[str, Any]: "fingerprint": entry.fingerprint, "fingerprint_short": short_fp, "device_label": entry.device_label, + "display_label": _display_label(entry.device_label, entry.client_label), "paired_at": entry.paired_at, "last_seen_at": entry.last_seen_at, "role": entry.role, diff --git a/solstone/apps/link/tests/test_api_devices_role.py b/solstone/apps/link/tests/test_api_devices_role.py index 5ecfa259d..cd1bf7f82 100644 --- a/solstone/apps/link/tests/test_api_devices_role.py +++ b/solstone/apps/link/tests/test_api_devices_role.py @@ -5,7 +5,10 @@ from __future__ import annotations import json -from solstone.think.link.auth import AuthorizedClients +import pytest + +from solstone.apps.link import routes as link_routes +from solstone.think.link.auth import AuthorizedClients, ClientEntry from solstone.think.link.paths import authorized_clients_path @@ -26,6 +29,35 @@ def test_devices_api_includes_role_field(link_env) -> None: } +@pytest.mark.parametrize( + ("assigned", "client", "expected"), + [ + ("assigned", "client", "assigned (client)"), + ("same", "same", "same"), + ("assigned", "", "assigned"), + ("", "client", "client"), + ("", "", ""), + ], +) +def test_entry_to_json_composes_display_label( + assigned: str, + client: str, + expected: str, +) -> None: + entry = ClientEntry( + fingerprint="sha256:abcdef", + device_label=assigned, + paired_at="2026-04-19T00:00:00Z", + instance_id="inst-1", + client_label=client, + ) + + payload = link_routes._entry_to_json(entry) + + assert payload["display_label"] == expected + assert "client_label" not in payload + + def test_devices_api_legacy_entry_defaults_to_role_less(link_env) -> None: env = link_env() path = authorized_clients_path() @@ -51,3 +83,5 @@ def test_devices_api_legacy_entry_defaults_to_role_less(link_env) -> None: devices = response.get_json()["devices"] assert len(devices) == 1 assert devices[0]["role"] == "" + assert devices[0]["display_label"] == "legacy" + assert "client_label" not in devices[0] diff --git a/solstone/apps/link/tests/test_by_code.py b/solstone/apps/link/tests/test_by_code.py index fdbb71535..e1afa25cc 100644 --- a/solstone/apps/link/tests/test_by_code.py +++ b/solstone/apps/link/tests/test_by_code.py @@ -35,6 +35,11 @@ def _make_csr(label: str = "test") -> str: return csr.public_bytes(serialization.Encoding.PEM).decode("ascii") +def _cert_common_name(cert_pem: str) -> str: + cert = x509.load_pem_x509_certificate(cert_pem.encode("utf-8")) + return cert.subject.get_attributes_for_oid(NameOID.COMMON_NAME)[0].value + + def _start_pair(env, device_label: str = "Test Phone") -> dict: response = env.client.post( "/app/link/pair-start", @@ -63,7 +68,82 @@ def test_by_code_happy_path(link_env) -> None: ) assert response.status_code == 200 - _assert_pair_response(response.get_json()) + payload = response.get_json() + _assert_pair_response(payload) + assert _cert_common_name(payload["client_cert"]) == "Test Phone" + entries = link_routes._authorized().snapshot() + assert len(entries) == 1 + assert entries[0].device_label == "Test Phone" + assert entries[0].client_label == "" + + +def test_by_code_stores_distinct_assigned_and_client_labels(link_env) -> None: + env = link_env() + started = _start_pair(env, "Assigned Phone") + + response = env.client.post( + "/app/link/by-code", + json={ + "code": started["manual_code"], + "csr": _make_csr("client-csr"), + "device_label": "Client Phone", + }, + ) + + assert response.status_code == 200 + payload = response.get_json() + _assert_pair_response(payload) + assert _cert_common_name(payload["client_cert"]) == "Client Phone" + entries = link_routes._authorized().snapshot() + assert len(entries) == 1 + assert entries[0].device_label == "Assigned Phone" + assert entries[0].client_label == "Client Phone" + + +def test_by_code_client_only_label_stores_assigned_empty(link_env) -> None: + env = link_env() + started = _start_pair(env, "") + + response = env.client.post( + "/app/link/by-code", + json={ + "code": started["manual_code"], + "csr": _make_csr("client-only"), + "device_label": "Client Only", + }, + ) + + assert response.status_code == 200 + payload = response.get_json() + _assert_pair_response(payload) + assert _cert_common_name(payload["client_cert"]) == "Client Only" + entries = link_routes._authorized().snapshot() + assert len(entries) == 1 + assert entries[0].device_label == "" + assert entries[0].client_label == "Client Only" + + +def test_by_code_empty_labels_use_default_for_certificate_only( + link_env, + monkeypatch: pytest.MonkeyPatch, +) -> None: + env = link_env() + monkeypatch.setattr(link_routes, "_default_device_label", lambda: "Default Device") + started = _start_pair(env, "") + + response = env.client.post( + "/app/link/by-code", + json={"code": started["manual_code"], "csr": _make_csr("empty-labels")}, + ) + + assert response.status_code == 200 + payload = response.get_json() + _assert_pair_response(payload) + assert _cert_common_name(payload["client_cert"]) == "Default Device" + entries = link_routes._authorized().snapshot() + assert len(entries) == 1 + assert entries[0].device_label == "" + assert entries[0].client_label == "" @pytest.mark.parametrize("variant", ["lowercase", "no_hyphen", "whitespace"]) @@ -220,3 +300,33 @@ def test_successful_pairing_emits_pair_complete_once( r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z", kwargs["paired_at"], ) + + +def test_pair_complete_event_uses_display_label( + link_env, + monkeypatch: pytest.MonkeyPatch, +) -> None: + env = link_env() + calls = [] + + def mock_emit(*args, **kwargs): + calls.append((args, kwargs)) + return True + + monkeypatch.setattr("solstone.apps.link.routes.emit", mock_emit) + started = _start_pair(env, "Assigned Phone") + + response = env.client.post( + "/app/link/by-code", + json={ + "code": started["manual_code"], + "csr": _make_csr("display-event"), + "device_label": "Client Phone", + }, + ) + + assert response.status_code == 200 + assert len(calls) == 1 + args, kwargs = calls[0] + assert args == ("link", "pair_complete") + assert kwargs["device_label"] == "Assigned Phone (Client Phone)" diff --git a/solstone/apps/link/tests/test_pair_copy.py b/solstone/apps/link/tests/test_pair_copy.py index 0a98d467c..b175330af 100644 --- a/solstone/apps/link/tests/test_pair_copy.py +++ b/solstone/apps/link/tests/test_pair_copy.py @@ -21,7 +21,6 @@ U4_COPY_VALUES = [ copy.CA_FP_LABEL, copy.CA_FP_NOTE, copy.DEVICE_LABEL_FIELD_LABEL, - copy.DEVICE_LABEL_DEFAULT_FORMAT, copy.EXPIRED_BUTTON, copy.PAIR_ERROR_BODY, copy.SUCCESS_HEADING, diff --git a/solstone/apps/link/tests/test_pair_start.py b/solstone/apps/link/tests/test_pair_start.py index 51c5cd462..27d60293d 100644 --- a/solstone/apps/link/tests/test_pair_start.py +++ b/solstone/apps/link/tests/test_pair_start.py @@ -57,6 +57,53 @@ def test_pair_start_shape_and_locked_order(link_env) -> None: assert "qr_payload" not in payload +def test_pair_start_omitted_assigned_label_stores_empty(link_env) -> None: + env = link_env() + + response = env.client.post("/app/link/pair-start", json={}) + + assert response.status_code == 200 + payload = response.get_json() + assert list(payload.keys()) == PAIR_START_KEYS + assert payload["device_label"] == "" + snap = link_routes._nonces().snapshot() + assert len(snap) == 1 + assert snap[0].device_label == "" + + +def test_pair_start_blank_assigned_label_stores_empty(link_env) -> None: + env = link_env() + + response = env.client.post( + "/app/link/pair-start", + json={"device_label": " "}, + ) + + assert response.status_code == 200 + payload = response.get_json() + assert payload["device_label"] == "" + snap = link_routes._nonces().snapshot() + assert len(snap) == 1 + assert snap[0].device_label == "" + + +def test_pair_start_allows_lenient_assigned_label(link_env) -> None: + env = link_env() + label = "device — added Jun 13!" + + response = env.client.post( + "/app/link/pair-start", + json={"device_label": label}, + ) + + assert response.status_code == 200 + payload = response.get_json() + assert payload["device_label"] == label + snap = link_routes._nonces().snapshot() + assert len(snap) == 1 + assert snap[0].device_label == label + + def test_pair_start_mints_distinct_nonce_and_manual_code(link_env) -> None: env = link_env() diff --git a/solstone/apps/link/tests/test_peer_journal_source_pairing.py b/solstone/apps/link/tests/test_peer_journal_source_pairing.py index 8caee6f11..2c29e1274 100644 --- a/solstone/apps/link/tests/test_peer_journal_source_pairing.py +++ b/solstone/apps/link/tests/test_peer_journal_source_pairing.py @@ -44,10 +44,13 @@ def _pair( *, role: str, label: str = "Pair Device", + client_label: str | None = None, sender_instance_id: object = None, ) -> dict: started = _start_pair(env, role=role, label=label) body = {"nonce": started["nonce"], "csr": _make_csr(label)} + if client_label is not None: + body["device_label"] = client_label if sender_instance_id is not None: body["sender_instance_id"] = sender_instance_id response = env.client.post( @@ -114,6 +117,32 @@ def test_peer_role_pairing_mints_journal_source_state_dir_and_authorized( assert len(entries) == 1 assert entries[0].fingerprint == response["fingerprint"] assert entries[0].role == "peer" + assert entries[0].device_label == "Peer Laptop" + assert entries[0].client_label == "" + + +def test_peer_pairing_uses_client_label_for_source_and_preserves_assigned( + link_env, +) -> None: + env = link_env() + + response = _pair( + env, + role="peer", + label="Assigned Peer", + client_label="Client Peer", + ) + + source = journal_sources.load_journal_source_by_fingerprint(response["fingerprint"]) + assert source is not None + assert source["device_label"] == "Client Peer" + + entries = link_routes._authorized().snapshot() + assert len(entries) == 1 + assert entries[0].fingerprint == response["fingerprint"] + assert entries[0].role == "peer" + assert entries[0].device_label == "Assigned Peer" + assert entries[0].client_label == "Client Peer" def test_peer_role_pairing_records_sender_instance_id(link_env) -> None: @@ -270,6 +299,7 @@ def test_peer_journal_source_mint_failure_does_not_add_authorized( _consumed_nonce("peer"), _make_csr("mint"), "Peer Laptop", + "", network="network", ) @@ -325,6 +355,7 @@ def test_peer_state_dir_failure_unlinks_journal_source_and_skips_authorized( _consumed_nonce("peer"), _make_csr("state-dir"), "Peer Laptop", + "", network="network", ) @@ -376,6 +407,7 @@ def test_peer_journal_source_rolls_back_when_authorized_add_fails( _consumed_nonce("peer"), _make_csr("rollback"), "Peer Laptop", + "", network="network", ) diff --git a/solstone/apps/link/tests/test_rename_route.py b/solstone/apps/link/tests/test_rename_route.py index 09af6ec19..156414707 100644 --- a/solstone/apps/link/tests/test_rename_route.py +++ b/solstone/apps/link/tests/test_rename_route.py @@ -21,6 +21,7 @@ def _add_device() -> None: "old name", "inst-1", paired_at=PAIRED_AT, + client_label="client-host", ) @@ -38,6 +39,7 @@ def test_rename_updates_paired_device_label(link_env) -> None: entry = _authorized().get(FINGERPRINT) assert entry is not None assert entry.device_label == "new name" + assert entry.client_label == "client-host" def test_rename_empty_label_returns_invalid_request(link_env) -> None: diff --git a/solstone/apps/link/tests/test_workspace_copy.py b/solstone/apps/link/tests/test_workspace_copy.py index 48a39d063..34cf255d9 100644 --- a/solstone/apps/link/tests/test_workspace_copy.py +++ b/solstone/apps/link/tests/test_workspace_copy.py @@ -22,7 +22,6 @@ MODAL_COPY_VALUES = [ copy.CA_FP_LABEL, copy.CA_FP_NOTE, copy.DEVICE_LABEL_PLACEHOLDER, - copy.DEVICE_LABEL_DEFAULT_FORMAT, copy.EXPIRED_BUTTON, copy.PAIR_ERROR_BODY, copy.SUCCESS_HEADING, diff --git a/solstone/apps/link/tests/test_workspace_states.py b/solstone/apps/link/tests/test_workspace_states.py index 193904bcf..dd441d38f 100644 --- a/solstone/apps/link/tests/test_workspace_states.py +++ b/solstone/apps/link/tests/test_workspace_states.py @@ -175,6 +175,30 @@ def test_pair_complete_single_refresh(link_env) -> None: assert "refreshDevices" in init_body +def test_workspace_uses_server_display_label_for_device_titles(link_env) -> None: + env = link_env() + response = env.client.get("/app/link/") + + assert response.status_code == 200 + body = response.get_data(as_text=True) + + assert "label.textContent = device.display_label || '';" in body + assert "label.textContent = `${device.display_label || ''}${suffix}`;" in body + assert ( + ".replace('{label}', device.display_label || device.device_label || '')" in body + ) + assert "const previous = device.device_label || '';" in body + assert "String(device.device_label || '').toLowerCase().includes(needle)" in body + + commit_start = body.index("async function commit()") + commit_end = body.index("function cancel()", commit_start) + commit_body = body[commit_start:commit_end] + assert "device.device_label = persisted;" in commit_body + assert "replaceRenameInput(input, persisted);" in commit_body + assert "refreshDevices();" in commit_body + assert "renderRecentlyPaired(latestDevices);" not in commit_body + + def test_pair_modal_error_state_present(link_env) -> None: env = link_env() response = env.client.get("/app/link/") diff --git a/solstone/apps/link/workspace.html b/solstone/apps/link/workspace.html index 7e11255c9..64b9d04d7 100644 --- a/solstone/apps/link/workspace.html +++ b/solstone/apps/link/workspace.html @@ -188,7 +188,7 @@
@@ -1318,7 +1318,7 @@ const persisted = typeof data.label === 'string' ? data.label : input.value.trim(); device.device_label = persisted; replaceRenameInput(input, persisted); - renderRecentlyPaired(latestDevices); + refreshDevices(); } catch (err) { device.device_label = previous; replaceRenameInput(input, previous); @@ -1368,7 +1368,7 @@ const label = document.createElement('span'); label.className = 'link-device-label'; - label.textContent = device.device_label || ''; + label.textContent = device.display_label || ''; title.appendChild(statusWrap); title.appendChild(label); @@ -1567,7 +1567,7 @@ const suffix = device.role === 'observer' || device.role === 'peer' ? ` (${device.role})` : ''; - label.textContent = `${device.device_label || ''}${suffix}`; + label.textContent = `${device.display_label || ''}${suffix}`; const network = document.createElement('span'); network.textContent = networkLabel(device.network); const time = document.createElement('span'); @@ -1948,7 +1948,7 @@ function openUnpair(device) { unpairTarget = device; unpairTitle.textContent = (window.LinkCopy.UNPAIR_TITLE_FORMAT || "unpair '{label}'?") - .replace('{label}', device.device_label || ''); + .replace('{label}', device.display_label || device.device_label || ''); unpairModal.hidden = false; unpairConfirm.focus(); } diff --git a/solstone/apps/observer/tests/test_pl_pairing.py b/solstone/apps/observer/tests/test_pl_pairing.py index 198458e89..997cc1953 100644 --- a/solstone/apps/observer/tests/test_pl_pairing.py +++ b/solstone/apps/observer/tests/test_pl_pairing.py @@ -168,6 +168,7 @@ def test_attestation_failure_does_not_write_observer_or_authorized( consumed, _make_csr("attestation"), "Observer Laptop", + "", network="network", ) @@ -201,6 +202,7 @@ def test_peer_journal_source_rolls_back_when_authorized_add_fails( consumed, _make_csr("rollback"), "Peer Laptop", + "", network="network", ) diff --git a/solstone/think/link/auth.py b/solstone/think/link/auth.py index bd0f78211..999191aed 100644 --- a/solstone/think/link/auth.py +++ b/solstone/think/link/auth.py @@ -3,9 +3,10 @@ """authorized_clients.json — the PL revocation ledger. -Entry shape is fixed by the spl protocol (see github.com/solpbc/spl -proto/pairing.md §6), plus solstone-specific `last_seen_at` and `network` -fields for UX: +The spl-protocol-fixed core shape is unchanged: `fingerprint`, `device_label`, +`paired_at`, `instance_id`, and `role`. `device_label` is the home-assigned, +renameable label for the paired client. Solstone also stores local-only +`last_seen_at`, `network`, and `client_label` fields for UX: { "fingerprint": "sha256:", @@ -14,7 +15,8 @@ fields for UX: "instance_id": "", "role": "", "last_seen_at": "2026-04-19T18:03:12Z", // optional; null/absent = never - "network": "network" // optional; local display label source + "network": "network", // optional; local display label source + "client_label": "jer-laptop" // optional; client self-name/hostname } Role-less linked systems are stored with `role: ""`; peers are stored with @@ -23,7 +25,8 @@ takes effect within ~500 ms of the file write. Convey's pair and unpair routes own the pairing writer surface; the secure listener updates `last_seen_at` and uses this ledger for TLS verification and per-request authorization. -`last_seen_at` and `network` are local-only — never transmitted externally. +`last_seen_at`, `network`, and `client_label` are local-only — never transmitted +externally. """ from __future__ import annotations @@ -52,6 +55,7 @@ class ClientEntry: role: str = "" last_seen_at: str | None = None network: str | None = None + client_label: str = "" class AuthorizedClients: @@ -99,6 +103,7 @@ class AuthorizedClients: role: str = "", paired_at: str | None = None, network: str | None = None, + client_label: str = "", ) -> None: paired_at = paired_at or dt.datetime.now(dt.UTC).strftime("%Y-%m-%dT%H:%M:%SZ") entry = ClientEntry( @@ -109,6 +114,7 @@ class AuthorizedClients: role=role, last_seen_at=None, network=network, + client_label=client_label, ) with self._lock: with hold_lock(self._path): @@ -176,7 +182,7 @@ class AuthorizedClients: self.reload_if_stale() with self._lock: for entry in self._entries.values(): - if entry.device_label == label: + if label and entry.device_label == label: return entry return None @@ -206,6 +212,7 @@ class AuthorizedClients: continue last_seen = item.get("last_seen_at") network = item.get("network") + client_label = item.get("client_label") out[fp] = ClientEntry( fingerprint=fp, device_label=str(item.get("device_label", "")), @@ -214,6 +221,7 @@ class AuthorizedClients: role=item.get("role") if isinstance(item.get("role"), str) else "", last_seen_at=last_seen if isinstance(last_seen, str) else None, network=network if isinstance(network, str) else None, + client_label=client_label if isinstance(client_label, str) else "", ) return out @@ -227,6 +235,7 @@ class AuthorizedClients: "role": e.role, **({"last_seen_at": e.last_seen_at} if e.last_seen_at else {}), **({"network": e.network} if e.network else {}), + **({"client_label": e.client_label} if e.client_label else {}), } for e in entries.values() ] diff --git a/solstone/think/link/join_cli.py b/solstone/think/link/join_cli.py index f6bff3a24..df65dab6b 100644 --- a/solstone/think/link/join_cli.py +++ b/solstone/think/link/join_cli.py @@ -32,6 +32,7 @@ import ipaddress import json import os import re +import socket import ssl import sys import urllib.error @@ -55,6 +56,7 @@ from solstone.think.utils import get_journal VALID_ROLES = {"", "phone", "observer", "peer"} MANUAL_CODE_RE = re.compile(r"^[0-9A-HJKMNP-TV-Z]{8}$") LABEL_RE = re.compile(r"^[A-Za-z0-9_.-]+$") +DEFAULT_CLIENT_LABEL = "linked-system" BUNDLE_FILES = { "private.pem", "cert.pem", @@ -85,7 +87,12 @@ def add_arguments(parser: argparse.ArgumentParser) -> None: parser.add_argument("--home", help="Receiver base URL") parser.add_argument("--code", required=True, help="Manual code or pair-link URL") parser.add_argument("--as", dest="as_role", help="Optional tag to join as") - parser.add_argument("--label", required=True, help="Local credentials label") + parser.add_argument( + "--label", + required=False, + default=None, + help="Local credentials label (defaults to this machine's hostname)", + ) def main(args: argparse.Namespace) -> int: @@ -93,10 +100,13 @@ def main(args: argparse.Namespace) -> int: if as_role not in VALID_ROLES: return _fail("invalid role; expected one of: phone, observer, peer", code=2) - label = str(args.label) - label_error = _label_error(label) - if label_error is not None: - return _fail(label_error, code=2) + if args.label is not None: + label = str(args.label) + label_error = _label_error(label) + if label_error is not None: + return _fail(label_error, code=2) + else: + label = _hostname_client_label() try: pair_request = _parse_pair_request(str(args.code).strip(), args.home) @@ -226,6 +236,25 @@ def _label_error(label: str) -> str | None: return None +def _sanitize_client_label(raw: str) -> str: + if not re.search(r"[A-Za-z0-9_.-]", raw): + return "" + label = re.sub(r"[^A-Za-z0-9_.-]", "-", raw) + label = re.sub(r"\.{2,}", "-", label) + label = label.lstrip(".")[:80] + if not label or _label_error(label) is not None: + return "" + return label + + +def _hostname_client_label() -> str: + try: + raw = socket.gethostname() + except OSError: + raw = "" + return _sanitize_client_label(raw) or DEFAULT_CLIENT_LABEL + + def _validate_instance_id(value: str) -> str | None: if not _INSTANCE_ID_RE.fullmatch(value): return f"bad instance_id from receiver: {value!r}" diff --git a/tests/link/test_auth.py b/tests/link/test_auth.py index 6c2dece2e..4e583c7a3 100644 --- a/tests/link/test_auth.py +++ b/tests/link/test_auth.py @@ -97,6 +97,7 @@ def test_add_then_last_seen_key_absent_in_payload(tmp_path: Path) -> None: payload = _load_payload(path) assert payload[0]["role"] == "" assert "last_seen_at" not in payload[0] + assert "client_label" not in payload[0] def test_network_round_trips(tmp_path: Path) -> None: @@ -113,6 +114,20 @@ def test_network_round_trips(tmp_path: Path) -> None: assert reloaded.network == "anywhere" +def test_client_label_round_trips(tmp_path: Path) -> None: + path = tmp_path / "auth.json" + store = AuthorizedClients(path) + + store.add("sha256:abc", "Assigned", "inst-1", client_label="client-host") + + payload = _load_payload(path) + assert payload[0]["client_label"] == "client-host" + + reloaded = AuthorizedClients(path).get("sha256:abc") + assert reloaded is not None + assert reloaded.client_label == "client-host" + + def test_missing_network_defaults_to_none(tmp_path: Path) -> None: path = tmp_path / "auth.json" path.write_text( @@ -137,6 +152,30 @@ def test_missing_network_defaults_to_none(tmp_path: Path) -> None: assert entry.network is None +def test_missing_client_label_defaults_to_empty(tmp_path: Path) -> None: + path = tmp_path / "auth.json" + path.write_text( + json.dumps( + [ + { + "fingerprint": "sha256:abc", + "device_label": "Jer", + "paired_at": "2026-04-19T00:00:00Z", + "instance_id": "inst-1", + } + ], + indent=2, + ) + + "\n", + encoding="utf-8", + ) + + entry = AuthorizedClients(path).get("sha256:abc") + + assert entry is not None + assert entry.client_label == "" + + def test_touch_last_seen_unknown_fp_returns_false(tmp_path: Path) -> None: store = AuthorizedClients(tmp_path / "auth.json") @@ -222,6 +261,20 @@ def test_update_label_preserves_network(tmp_path: Path) -> None: assert _load_payload(path)[0]["network"] == "anywhere" +def test_update_label_preserves_client_label(tmp_path: Path) -> None: + path = tmp_path / "auth.json" + store = AuthorizedClients(path) + + store.add("sha256:abc", "old name", "inst-1", client_label="client-host") + assert store.update_label("sha256:abc", "new name") is True + + entry = store.get("sha256:abc") + assert entry is not None + assert entry.device_label == "new name" + assert entry.client_label == "client-host" + assert _load_payload(path)[0]["client_label"] == "client-host" + + @pytest.mark.parametrize( ("label", "message"), [ @@ -278,11 +331,14 @@ def test_find_by_label(tmp_path: Path) -> None: assert store.find_by_label("Jer") is None store.add("sha256:abc", "Jer", "inst-1") + store.add("sha256:empty", "", "inst-1", client_label="client-host") entry = store.find_by_label("Jer") assert entry is not None assert entry.fingerprint == "sha256:abc" assert entry.role == "" assert store.find_by_label("Nope") is None + assert store.find_by_label("") is None + assert store.find_by_label("client-host") is None time.sleep(0.02) path.write_text( diff --git a/tests/link/test_link_join_label_validation.py b/tests/link/test_link_join_label_validation.py index ac304b94a..4a10de0c1 100644 --- a/tests/link/test_link_join_label_validation.py +++ b/tests/link/test_link_join_label_validation.py @@ -4,13 +4,14 @@ from __future__ import annotations import argparse +import json import pytest from solstone.think.link import join_cli -def _args(label: str) -> argparse.Namespace: +def _args(label: str | None) -> argparse.Namespace: return argparse.Namespace( home="http://receiver", code="ABCD-EFGH", @@ -64,3 +65,23 @@ def test_valid_labels_reach_http_stage( assert result == 1 assert len(calls) == 1 + + +def test_explicit_valid_label_is_sent_verbatim( + tmp_path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config")) + calls = [] + + def fake_urlopen(request, **_kwargs): + calls.append(json.loads(request.data.decode("utf-8"))) + raise join_cli.urllib.error.URLError("stop") + + monkeypatch.setattr(join_cli.urllib.request, "urlopen", fake_urlopen) + + result = join_cli.main(_args("Laptop.v2")) + + assert result == 1 + assert len(calls) == 1 + assert calls[0]["device_label"] == "Laptop.v2" diff --git a/tests/link/test_link_join_observer.py b/tests/link/test_link_join_observer.py index dedaebacd..b07ce8516 100644 --- a/tests/link/test_link_join_observer.py +++ b/tests/link/test_link_join_observer.py @@ -10,7 +10,9 @@ from pathlib import Path from typing import Any import pytest +from cryptography import x509 from cryptography.hazmat.primitives import serialization +from cryptography.x509.oid import NameOID from solstone.apps.link.routes import _build_pair_link from solstone.think.link import join_cli @@ -40,7 +42,7 @@ def _args( home: str | None = "http://receiver", code: str = "ABCD-EFGH", as_role: str | None = None, - label: str = "laptop", + label: str | None = "laptop", ) -> argparse.Namespace: return argparse.Namespace(home=home, code=code, as_role=as_role, label=label) @@ -89,6 +91,11 @@ def _configure_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: return config_home +def _csr_common_name(csr_pem: str) -> str: + csr = x509.load_pem_x509_csr(csr_pem.encode("utf-8")) + return csr.subject.get_attributes_for_oid(NameOID.COMMON_NAME)[0].value + + def test_short_code_happy_path_writes_bundle( tmp_path: Path, monkeypatch: pytest.MonkeyPatch, @@ -125,6 +132,49 @@ def test_short_code_happy_path_writes_bundle( assert peer["role"] == "" +def test_short_code_omitted_label_uses_sanitized_hostname( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + config_home = _configure_home(tmp_path, monkeypatch) + monkeypatch.setattr(join_cli.socket, "gethostname", lambda: "Lab Host.local") + calls: list[tuple[str, dict[str, Any]]] = [] + _mock_urlopen(monkeypatch, _success_payload(tmp_path), calls=calls) + + result = join_cli.main(_args(label=None)) + + assert result == 0 + assert calls[0][1]["device_label"] == "Lab-Host.local" + assert _csr_common_name(calls[0][1]["csr"]) == "Lab-Host.local" + bundle = config_home / "solstone-observer" / "spl" / "Lab-Host.local" + assert bundle.is_dir() + peer = json.loads((bundle / "peer.json").read_text("utf-8")) + assert peer["label"] == "Lab-Host.local" + + +@pytest.mark.parametrize("hostname", ["", "!!!"]) +def test_short_code_omitted_label_falls_back_to_default_client_label( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + hostname: str, +) -> None: + config_home = _configure_home(tmp_path, monkeypatch) + monkeypatch.setattr(join_cli.socket, "gethostname", lambda: hostname) + calls: list[tuple[str, dict[str, Any]]] = [] + _mock_urlopen(monkeypatch, _success_payload(tmp_path), calls=calls) + + result = join_cli.main(_args(label=None)) + + assert join_cli.DEFAULT_CLIENT_LABEL == "linked-system" + assert join_cli._label_error(join_cli.DEFAULT_CLIENT_LABEL) is None + assert result == 0 + assert calls[0][1]["device_label"] == join_cli.DEFAULT_CLIENT_LABEL + bundle = config_home / "solstone-observer" / "spl" / join_cli.DEFAULT_CLIENT_LABEL + assert bundle.is_dir() + peer = json.loads((bundle / "peer.json").read_text("utf-8")) + assert peer["label"] == join_cli.DEFAULT_CLIENT_LABEL + + def test_url_happy_path_posts_to_pair_token( tmp_path: Path, monkeypatch: pytest.MonkeyPatch, diff --git a/tests/test_link_call_parity.py b/tests/test_link_call_parity.py index bf1ebfd12..07c7fa8cf 100644 --- a/tests/test_link_call_parity.py +++ b/tests/test_link_call_parity.py @@ -64,9 +64,17 @@ def _add_device( role: str = "", paired_at: str = PAIRED_AT, last_seen_at: str | None = None, + client_label: str = "", ) -> None: store = _authorized() - store.add(fingerprint, label, "inst-1", role=role, paired_at=paired_at) + store.add( + fingerprint, + label, + "inst-1", + role=role, + paired_at=paired_at, + client_label=client_label, + ) if last_seen_at is not None: store.touch_last_seen(fingerprint, now=_parse_iso(last_seen_at)) @@ -170,6 +178,25 @@ def test_pair_mints_default_and_peer_roles( assert nonces[0].role == expected_role +def test_pair_without_device_label_mints_empty_label( + runner, + monkeypatch, +): + monkeypatch.setattr(link_call, "_detect_lan_ip", lambda: None) + monkeypatch.setattr(link_call, "time", _TimeoutTime()) + + result = runner.invoke( + link_call.app, + ["pair", "--timeout", "1"], + ) + + assert result.exit_code == 2 + assert "\nDevice: " not in result.stdout + nonces = _nonces().snapshot() + assert len(nonces) == 1 + assert nonces[0].device_label == "" + + def test_pair_uses_minted_port_and_convey_host_override(runner, monkeypatch): monkeypatch.setattr(link_call, "_detect_lan_ip", lambda: "192.168.1.50") monkeypatch.setattr(link_call, "time", _TimeoutTime()) @@ -212,6 +239,28 @@ def test_pair_reports_newly_paired_device(runner, monkeypatch): ) in result.stdout +def test_pair_reports_display_label_for_newly_paired_device(runner, monkeypatch): + def add_device() -> None: + if not _authorized().snapshot(): + _add_device( + "sha256:" + ("1" * 64), + "", + client_label="client-host", + ) + + monkeypatch.setattr(link_call, "_detect_lan_ip", lambda: None) + monkeypatch.setattr(link_call, "time", _PairingTime(on_sleep=add_device)) + + result = runner.invoke(link_call.app, ["pair", "--timeout", "5"]) + + assert result.exit_code == 0 + assert ( + "Paired: client-host\n" + " fingerprint: sha256:1111111111111111111111111111111111111111111111111111111111111111\n" + f" paired_at: {PAIRED_AT}\n" + ) in result.stdout + + def test_pair_reports_nonce_consumed_fallback(runner, monkeypatch): def consume_nonce() -> None: nonces = _nonces().snapshot() @@ -290,6 +339,24 @@ def test_list_grouped_output_and_device_line(runner, monkeypatch): ) +def test_list_uses_display_label_when_assigned_label_is_empty(runner, monkeypatch): + monkeypatch.setattr(link_call, "_now_utc", lambda: _parse_iso(FROZEN_NOW)) + _add_device( + "sha256:0123456789abcdef0000", + "", + paired_at=PAIRED_AT, + client_label="client-host", + ) + + result = runner.invoke(link_call.app, ["list"]) + + assert result.exit_code == 0 + assert result.stdout == ( + "Linked systems:\n" + "- client-host — added 1 hour ago — last seen never [0123456789abcdef]\n" + ) + + def test_list_legacy_observer_role_uses_linked_systems_heading(runner): _add_device("sha256:bbbbbbbbbbbbbbbb0000", "observer", role="observer") -- 2.51.2