cli-login 0.4.0__tar.gz → 0.4.1__tar.gz

{cli_login-0.4.0 → cli_login-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-login
-Version: 0.4.0
+Version: 0.4.1
 Summary: Browser sign-in for CLIs without long-lived keys: PKCE, remote approval, secure storage and renewal.
 Author: Anthus AI
 License: MIT
@@ -222,6 +222,26 @@ Each product deployment runs one broker, built from `infra/broker.yaml`.
 The broker and the approval pages must run the same cli-login version. Products should pin an exact version, since
 releases before 1.0 may change behaviour.
 
+## The product's app client
+
+cli-login creates no Cognito client; each product signs its CLI in with an app client it defines. Use these settings
+unless the product has a reviewed reason not to:
+
+| Setting | Default |
+| --- | --- |
+| OAuth flow | Authorization code only, with PKCE (S256) |
+| Client secret | None (a public client) |
+| Explicit auth flows | `ALLOW_REFRESH_TOKEN_AUTH` only |
+| Refresh token | 7 days |
+| Access and ID tokens | 60 minutes |
+| Token revocation | On, so `logout()` can revoke the refresh token |
+| Callbacks | Exact URLs: one fixed loopback port for local sign-in and `https://<product-domain>/cli/callback` for remote sign-in |
+
+Seven days lets an agent on a cloud machine keep working for a week without a person signing in again, while a
+lost or leaked refresh token stops working within the week. Access tokens stay short, so an API sees a revocation
+within an hour. Cognito matches callbacks exactly, with no port wildcard, so the loopback port is fixed and
+registered.
+
 ## Where sessions are stored
 
 Sessions live only in a secure store, tried in this order. There is no plaintext fallback: if nothing is
@@ -240,7 +260,10 @@ and tests). Any other value is refused.
 ### Cloud machines and containers
 
 A cloud machine usually has no desktop keyring, and Docker's default seccomp profile blocks the kernel keyring
-calls. Start the memory agent once per product, then sign in again:
+calls. Start the memory agent once per product, then sign in again. The error message prints the exact command,
+with the full path of the interpreter that has `cli-login` installed; use that one. A bare `python` cannot import
+the library when a product installs it in a private environment (`pipx`, `uv tool`), so in these examples
+`python` stands for that interpreter:
 
 ```bash
 python -m cli_login.stores.agent serve --namespace <product-namespace> --background
@@ -276,7 +299,7 @@ as with ssh-agent.
   requester label, the matching code the approver must confirm, and `expected_email` narrow the risk. They do not
   remove it, and the CLI always prints the identity it signed in as.
 - **Tokens can leak.** They are short-lived and renewable, and logout revokes the refresh token. A stolen refresh
-  token works until it expires or is revoked.
+  token works until it is revoked or expires (7 days with the default app client).
 - **The broker never holds a token.** It holds an authorization code until the right CLI collects it, and the
   code is useless without the verifier.
 - **Cognito only, for now.** The library targets Amazon Cognito user pools with the authorization-code flow and PKCE.

{cli_login-0.4.0 → cli_login-0.4.1}/README.md

@@ -206,6 +206,26 @@ Each product deployment runs one broker, built from `infra/broker.yaml`.
 The broker and the approval pages must run the same cli-login version. Products should pin an exact version, since
 releases before 1.0 may change behaviour.
 
+## The product's app client
+
+cli-login creates no Cognito client; each product signs its CLI in with an app client it defines. Use these settings
+unless the product has a reviewed reason not to:
+
+| Setting | Default |
+| --- | --- |
+| OAuth flow | Authorization code only, with PKCE (S256) |
+| Client secret | None (a public client) |
+| Explicit auth flows | `ALLOW_REFRESH_TOKEN_AUTH` only |
+| Refresh token | 7 days |
+| Access and ID tokens | 60 minutes |
+| Token revocation | On, so `logout()` can revoke the refresh token |
+| Callbacks | Exact URLs: one fixed loopback port for local sign-in and `https://<product-domain>/cli/callback` for remote sign-in |
+
+Seven days lets an agent on a cloud machine keep working for a week without a person signing in again, while a
+lost or leaked refresh token stops working within the week. Access tokens stay short, so an API sees a revocation
+within an hour. Cognito matches callbacks exactly, with no port wildcard, so the loopback port is fixed and
+registered.
+
 ## Where sessions are stored
 
 Sessions live only in a secure store, tried in this order. There is no plaintext fallback: if nothing is
@@ -224,7 +244,10 @@ and tests). Any other value is refused.
 ### Cloud machines and containers
 
 A cloud machine usually has no desktop keyring, and Docker's default seccomp profile blocks the kernel keyring
-calls. Start the memory agent once per product, then sign in again:
+calls. Start the memory agent once per product, then sign in again. The error message prints the exact command,
+with the full path of the interpreter that has `cli-login` installed; use that one. A bare `python` cannot import
+the library when a product installs it in a private environment (`pipx`, `uv tool`), so in these examples
+`python` stands for that interpreter:
 
 ```bash
 python -m cli_login.stores.agent serve --namespace <product-namespace> --background
@@ -260,7 +283,7 @@ as with ssh-agent.
   requester label, the matching code the approver must confirm, and `expected_email` narrow the risk. They do not
   remove it, and the CLI always prints the identity it signed in as.
 - **Tokens can leak.** They are short-lived and renewable, and logout revokes the refresh token. A stolen refresh
-  token works until it expires or is revoked.
+  token works until it is revoked or expires (7 days with the default app client).
 - **The broker never holds a token.** It holds an authorization code until the right CLI collects it, and the
   code is useless without the verifier.
 - **Cognito only, for now.** The library targets Amazon Cognito user pools with the authorization-code flow and PKCE.

{cli_login-0.4.0 → cli_login-0.4.1}/docs/design.md

@@ -41,7 +41,7 @@ A product describes one **target**:
 
 The library does the rest:
 
-- **Local sign-in.** PKCE (S256), a loopback callback on a free port, state and nonce, and the token
+- **Local sign-in.** PKCE (S256), a loopback callback on a fixed, registered port, state and nonce, and the token
   exchange. It checks each token's issuer, client, `token_use`, expiry and nonce.
 - **Remote sign-in.** It calls the broker's `/start`, prints the approval URL and matching code, polls `/poll`
   at the interval given, waits longer on `slow_down`, and exchanges the code (see the protocol below).
@@ -152,6 +152,9 @@ What this guarantees:
 
 ## A product's API
 
+The product's app client defaults to a 7-day refresh token with 60-minute access and ID tokens, code flow with PKCE
+and no secret; see [the README](../README.md#the-products-app-client).
+
 The CLI calls the product's API with `Authorization: Bearer <access token>`. The API verifies the token as it
 would for a browser session. A request that carries both a cookie and a bearer token is refused.
 

{cli_login-0.4.0 → cli_login-0.4.1}/docs/protocol.md

@@ -108,6 +108,11 @@ is sent as the OpenID `nonce`, and the ID token must carry it back or the login
 `enroll(tokens, state, enrollment)` then runs before anything is stored, and if it raises the tokens are discarded
 and the refresh token is revoked on a best-effort basis.
 
+A `nonce_mismatch` stores nothing, tells the person to start the sign-in again, and is never retried with a different
+expected nonce. Its error carries `diagnostics` that tell the cases apart without exposing anything: whether `enroll`
+was given, whether the broker handed over a nonce, and eight-character SHA-256 tags of the transaction, the CLI's own
+nonce, the nonce it expected and the nonce the ID token carried.
+
 A network failure during the exchange is **not** retried, because the code may already be spent. The CLI starts
 again.
 

{cli_login-0.4.0 → cli_login-0.4.1}/features/remote_sign_in.feature

@@ -56,6 +56,8 @@ Feature: Remote sign-in from another device
     When the CLI starts a remote sign-in
     And the person approves it but the sign-in provider answers tokens for a different nonce
     Then the CLI reports that the tokens were for a different request
+    And the report tells the person to start the sign-in again and that nothing was saved
+    And the report carries one-way tags that tell the cases apart and no nonce or token
     And no session is stored
 
   Scenario: Someone who reads the link in chat and approves first does not get the session

{cli_login-0.4.0 → cli_login-0.4.1}/features/steps/remote_sign_in_steps.py

@@ -114,7 +114,7 @@ def run_cli(context, on_poll):
     try:
         remote_login(Target(), context.stored.append, http=product.http, out=context.printed.append,
                      clock=lambda: product.now, sleep=sleep, host="cloud-box",
-                     expected_email=getattr(context, "expected_email", None))
+                     expected_email=getattr(context, "expected_email", None), login_command="app login --remote example.test")
     except RemoteLoginError as error:
         context.error = error
 
@@ -289,6 +289,20 @@ def step_nonce(context):
     assert context.error.code == "nonce_mismatch"
 
 
+@then("the report tells the person to start the sign-in again and that nothing was saved")
+def step_nonce_again(context):
+    message = str(context.error)
+    assert "Start the sign-in again with `app login --remote example.test`." in message and "nothing was saved" in message
+
+
+@then("the report carries one-way tags that tell the cases apart and no nonce or token")
+def step_nonce_tags(context):
+    diagnostics = context.error.diagnostics
+    assert set(diagnostics) == {"enroll", "broker_nonce", "transaction", "own_nonce", "expected_nonce", "received_nonce"}
+    assert diagnostics["received_nonce"] != diagnostics["expected_nonce"]
+    assert "another" not in str(context.error) and getattr(context, "transaction", "no-transaction") not in str(context.error)
+
+
 @then("the page says the link is no longer valid")
 def step_gone(context):
     assert context.page.status == 410, context.page.status

{cli_login-0.4.0 → cli_login-0.4.1}/features/steps/stores_agent_steps.py

@@ -1,4 +1,5 @@
 import os
+import shlex
 import shutil
 import socket
 import stat
@@ -219,3 +220,18 @@ def windows(context):
             raise AssertionError("expected refusal")
 
 
+
+
+@then("the start-up advice names the running interpreter by its full path")
+def advice_path(context):
+    words = shlex.split(agent.agent_command(NS, state_dir=context.state_dir))
+    assert words[0] == sys.executable and os.path.isabs(words[0]), words[0]
+
+
+@then("pasting the start-up advice into a shell starts a running agent")
+def advice_runs(context):
+    context.add_cleanup(agent.stop, NS, state_dir=context.state_dir)
+    done = subprocess.run(agent.agent_command(NS, state_dir=context.state_dir), shell=True, capture_output=True,
+                          text=True, timeout=60, check=False)
+    assert done.returncode == 0, done.stderr
+    assert agent.status(NS, state_dir=context.state_dir) is not None

{cli_login-0.4.0 → cli_login-0.4.1}/features/stores_agent.feature

@@ -40,6 +40,11 @@ Feature: The memory agent
     Given no memory agent is running
     Then a client store is unavailable with guidance mentioning "agent serve"
 
+  Scenario: The start-up advice works when pasted, even where the library is installed in a private environment
+    Given no memory agent is running
+    Then the start-up advice names the running interpreter by its full path
+    And pasting the start-up advice into a shell starts a running agent
+
   Scenario: A second agent for the same product is refused
     Given a running memory agent for the namespace "example-product"
     Then starting another agent for the namespace "example-product" fails

cli_login-0.4.1/project/events/2026-10-31T15-05-12.601Z__80377f48-3218-4a3d-9f7e-9c4db44de2f0.json

@@ -0,0 +1,23 @@
+{
+  "schema_version": 1,
+  "event_id": "80377f48-3218-4a3d-9f7e-9c4db44de2f0",
+  "issue_id": "cli-login-79ca92d5-4534-4bea-bfe1-aaeaa5037b49",
+  "event_type": "issue_created",
+  "occurred_at": "2026-10-31T15:05:12.601Z",
+  "actor_id": "home",
+  "payload": {
+    "title": "Document a 7-day refresh token as the default app client setting",
+    "description": "Ryan (2026-10-31): one week (seven days) should be the default refresh-token lifetime for the product app clients that cli-login signs in with. Access and ID tokens stay at 60 minutes. cli-login creates no Cognito client, so the default is the documented app client setup in README.md and docs/design.md.\n\nDone when:\n- README.md has a section listing the app client settings: code flow, PKCE, no client secret, refresh 7 days, access and ID 60 minutes, token revocation on, and exact callbacks with a fixed loopback port.\n- The security-limits bullet names the 7-day window.\n- docs/design.md points to that section.",
+    "issue_type": "story",
+    "status": "open",
+    "priority": 2,
+    "assignee": null,
+    "parent": "cli-login-333326d6-56fb-48cc-bee1-b2a349b145a4",
+    "labels": [],
+    "agent": {
+      "platform": "claude_code",
+      "model": "claude-opus-5-5",
+      "name": "Prospectus implementation"
+    }
+  }
+}

cli_login-0.4.1/project/events/2026-10-31T15-27-42.778Z__65bd906f-6801-4df1-ae7b-2112c3629b32.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "event_id": "65bd906f-6801-4df1-ae7b-2112c3629b32",
+  "issue_id": "cli-login-79ca92d5-4534-4bea-bfe1-aaeaa5037b49",
+  "event_type": "state_transition",
+  "occurred_at": "2026-10-31T15:27:42.778Z",
+  "actor_id": "home",
+  "payload": {
+    "from_status": "open",
+    "to_status": "closed"
+  }
+}

cli_login-0.4.1/project/events/2026-10-31T15-27-43.836Z__5da8b7b7-4903-4767-a638-3cb0d95c32a0.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "event_id": "5da8b7b7-4903-4767-a638-3cb0d95c32a0",
+  "issue_id": "cli-login-79ca92d5-4534-4bea-bfe1-aaeaa5037b49",
+  "event_type": "state_transition",
+  "occurred_at": "2026-10-31T15:27:43.836Z",
+  "actor_id": "home",
+  "payload": {
+    "from_status": "open",
+    "to_status": "closed"
+  }
+}

cli_login-0.4.1/project/issues/cli-login-79ca92d5-4534-4bea-bfe1-aaeaa5037b49.json

@@ -0,0 +1,28 @@
+{
+  "id": "cli-login-79ca92d5-4534-4bea-bfe1-aaeaa5037b49",
+  "title": "Document a 7-day refresh token as the default app client setting",
+  "description": "Ryan (2026-10-31): one week (seven days) should be the default refresh-token lifetime for the product app clients that cli-login signs in with. Access and ID tokens stay at 60 minutes. cli-login creates no Cognito client, so the default is the documented app client setup in README.md and docs/design.md.\n\nDone when:\n- README.md has a section listing the app client settings: code flow, PKCE, no client secret, refresh 7 days, access and ID 60 minutes, token revocation on, and exact callbacks with a fixed loopback port.\n- The security-limits bullet names the 7-day window.\n- docs/design.md points to that section.",
+  "type": "story",
+  "status": "closed",
+  "priority": 2,
+  "assignee": null,
+  "creator": null,
+  "parent": "cli-login-333326d6-56fb-48cc-bee1-b2a349b145a4",
+  "labels": [],
+  "dependencies": [],
+  "comments": [],
+  "created_at": "2026-10-31T15:05:12.601696Z",
+  "updated_at": "2026-10-31T15:27:43.836828Z",
+  "closed_at": "2026-10-31T15:27:43.836802Z",
+  "agent": {
+    "platform": "claude_code",
+    "model": "claude-opus-5-5",
+    "name": "Prospectus implementation"
+  },
+  "right_now_summary": null,
+  "right_now_updated_at": null,
+  "custom": {
+    "project_label": "cli-login",
+    "source": "shared"
+  }
+}

{cli_login-0.4.0 → cli_login-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cli-login"
-version = "0.4.0"
+version = "0.4.1"
 description = "Browser sign-in for CLIs without long-lived keys: PKCE, remote approval, secure storage and renewal."
 readme = "README.md"
 requires-python = ">=3.10"

{cli_login-0.4.0 → cli_login-0.4.1}/src/cli_login/__init__.py

@@ -1,4 +1,4 @@
 """Browser sign-in for CLIs without long-lived keys. See README.md and docs/protocol.md."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 PROTOCOL_VERSION = 1

{cli_login-0.4.0 → cli_login-0.4.1}/src/cli_login/broker/handler_test.py

@@ -332,3 +332,28 @@ def test_a_malformed_product_nonce_or_enrollment_is_refused_and_nothing_is_bound
     transaction = started(b)
     assert b.bind({"transaction": transaction, "nonce_hash": sha256_hex("n"), **extra}) == {"ok": False, "error": "unavailable"}
     assert b.describe({"transaction": transaction})["ok"] is True
+
+
+def test_a_second_bind_cannot_replace_the_nonce_or_enrollment_of_the_first():
+    b = broker()
+    transaction = started(b)
+    assert b.bind({"transaction": transaction, "nonce_hash": sha256_hex("n1"), "nonce": "challenge-nonce-0001",
+                   "enrollment": "proof-1"}) == {"ok": True}
+    assert b.bind({"transaction": transaction, "nonce_hash": sha256_hex("n2"), "nonce": "challenge-nonce-0002",
+                   "enrollment": "proof-2"}) == {"ok": False, "error": "unavailable"}
+    item = b.store.get(transaction)
+    assert item["oidc_nonce"] == "challenge-nonce-0001" and item["enrollment"] == "proof-1" and item["nonce_hash"] == sha256_hex("n1")
+
+
+def test_a_code_completed_for_one_transaction_is_never_handed_to_another_transactions_poll():
+    clock = Clock()
+    b = broker(clock)
+    first, second = started(b), started(b)
+    b.bind({"transaction": first, "nonce_hash": sha256_hex("n1"), "nonce": "challenge-nonce-0001", "enrollment": "proof-1"})
+    b.bind({"transaction": second, "nonce_hash": sha256_hex("n2")})
+    assert b.complete({"transaction": first, "nonce": "n2", "code": "code-1"}) == {"ok": False, "error": "unavailable"}
+    assert b.complete({"transaction": first, "nonce": "n1", "code": "code-1"}) == {"ok": True}
+    clock.now += 5
+    assert b.poll({"transaction": second, "poll_secret": SECRET}, "ip")[1]["error"] == "authorization_pending"
+    status, answer = b.poll({"transaction": first, "poll_secret": SECRET}, "ip")
+    assert status == 200 and answer["code"] == "code-1" and answer["nonce"] == "challenge-nonce-0001"

{cli_login-0.4.0 → cli_login-0.4.1}/src/cli_login/broker/pages_test.py

@@ -172,3 +172,47 @@ def test_when_prepare_fails_nothing_is_bound_and_the_link_still_works():
 def counter():
     tokens = iter(f"tok{n:02d}" for n in range(99))
     return lambda _n: next(tokens)
+
+
+def post_approve(pages, transaction, csrf):
+    return pages.approve("POST", {}, {"t": transaction, "csrf": csrf, "action": "approve", "confirm": "yes"}, {CSRF_COOKIE: csrf})
+
+
+def test_a_replayed_approval_cannot_change_the_nonce_the_first_approval_bound():
+    broker, _, transaction = world()
+    challenges = iter(["challenge-nonce-0001", "challenge-nonce-0002"])
+    pages = ApprovalPages(broker.handle, authorize_endpoint=AUTHORIZE, product="Example", privileges="Act as you.",
+                          prepare=lambda t, described: (next(challenges), "sealed-proof"), token=counter())
+    csrf = cookie(pages.approve("GET", {"t": transaction}, {}, {}), CSRF_COOKIE)
+    first = post_approve(pages, transaction, csrf)
+    replay = post_approve(pages, transaction, csrf)  # back button, a second tab or a double submit with the old cookie
+    assert first.status == 303 and replay.status == 410
+    assert cookie(replay, NONCE_COOKIE) is None and "Location" not in dict(replay.headers)
+    assert broker.store.get(transaction)["oidc_nonce"] == "challenge-nonce-0001"
+
+
+def test_two_approvals_that_race_bind_one_nonce_and_only_that_one_reaches_the_provider():
+    import threading
+
+    broker, _, transaction = world()
+    meeting = threading.Barrier(2, timeout=5)
+    challenges, lock = iter(["challenge-nonce-0001", "challenge-nonce-0002"]), threading.Lock()
+
+    def prepare(t, described):
+        meeting.wait()  # both requests have seen the transaction pending before either binds
+        with lock:
+            return next(challenges), "sealed-proof"
+
+    pages = ApprovalPages(broker.handle, authorize_endpoint=AUTHORIZE, product="Example", privileges="Act as you.",
+                          prepare=prepare, token=lambda _n: "t" * 32)
+    csrf = cookie(pages.approve("GET", {"t": transaction}, {}, {}), CSRF_COOKIE)
+    answers = []
+    threads = [threading.Thread(target=lambda: answers.append(post_approve(pages, transaction, csrf))) for _ in range(2)]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join()
+    assert sorted(page.status for page in answers) == [303, 410]
+    sent = next(page for page in answers if page.status == 303)
+    nonce = parse_qs(urlsplit(header(sent, "Location")).query)["nonce"][0]
+    assert broker.store.get(transaction)["oidc_nonce"] == nonce

{cli_login-0.4.0 → cli_login-0.4.1}/src/cli_login/remote.py

@@ -30,9 +30,10 @@ from .errors import AuthError, OAuthError
 class RemoteLoginError(OAuthError):
     """A remote sign-in that did not finish. ``transient`` says whether trying again later may work."""
 
-    def __init__(self, code: str, message: str, *, transient: bool = False):
+    def __init__(self, code: str, message: str, *, transient: bool = False, diagnostics: Mapping[str, str] | None = None):
         self.code = code
         self.transient = transient
+        self.diagnostics = dict(diagnostics or {})
         AuthError.__init__(self, message)
 
 
@@ -55,6 +56,15 @@ def default_http(method: str, url: str, *, json_body=None, form=None, timeout: f
     return status, body if isinstance(body, dict) else {}, {key.lower(): value for key, value in headers.items()}
 
 
+def _fingerprint(value: object) -> str:
+    """A short, non-reversible tag for comparing two values in a report; the value itself is never shown."""
+    if value is None:
+        return "none"
+    if not isinstance(value, str):
+        return "invalid"
+    return hashlib.sha256(value.encode()).hexdigest()[:8]
+
+
 def _b64url(data: bytes) -> str:
     return base64.urlsafe_b64encode(data).decode().rstrip("=")
 
@@ -103,6 +113,7 @@ def remote_login(
     expected_email: str | None = None,
     enroll: Callable[[Mapping[str, Any], str, str | None], Any] | None = None,
     token=secrets.token_urlsafe,
+    login_command: str | None = None,
 ):
     """Sign in through the target's broker and return what ``store_token_set`` returns.
 
@@ -120,6 +131,11 @@ def remote_login(
     enrollment of each login (the Cyclotron lab enrolls each Cognito login at Prospectus). Only then does the CLI
     accept an OpenID nonce chosen by the product's approval page, which the broker hands over with the code;
     without ``enroll`` the CLI checks its own nonce and nothing else.
+
+    ``login_command`` is the command that starts this sign-in again; the nonce-mismatch error names it. That error
+    also carries ``diagnostics``: whether ``enroll`` was given, whether the broker handed over a nonce, and short
+    one-way tags of the transaction and of the nonces (never a token or a nonce), so a failure that does not repeat
+    can still be told apart from one that does.
     """
     broker = getattr(target, "broker_endpoint", None)
     if not broker:
@@ -207,7 +223,21 @@ def remote_login(
     claims = _claims(tokens.get("id_token"))
     expected_nonce = answer.get("nonce") if enroll is not None and isinstance(answer.get("nonce"), str) else nonce
     if claims.get("nonce") != expected_nonce:
-        raise RemoteLoginError("nonce_mismatch", "The sign-in answered tokens for a different request; nothing was saved.")
+        diagnostics = {
+            "enroll": "on" if enroll is not None else "off",
+            "broker_nonce": "none" if answer.get("nonce") is None else "handed",
+            "transaction": _fingerprint(transaction),
+            "own_nonce": _fingerprint(nonce),
+            "expected_nonce": _fingerprint(expected_nonce),
+            "received_nonce": _fingerprint(claims.get("nonce")),
+        }
+        again = f"Start the sign-in again with `{login_command}`." if login_command else "Start the sign-in again."
+        raise RemoteLoginError(
+            "nonce_mismatch",
+            f"The sign-in answered tokens for a different request; nothing was saved. {again} "
+            f"If it repeats, report these tags (one-way, no secrets): {' '.join(f'{k}={v}' for k, v in diagnostics.items())}.",
+            diagnostics=diagnostics,
+        )
     email = claims.get("email") if isinstance(claims.get("email"), str) else None
     if expected_email is not None and (email or "").casefold() != expected_email.casefold():
         raise RemoteLoginError("unexpected_identity", "Someone other than the expected person approved this sign-in; nothing was saved.")

{cli_login-0.4.0 → cli_login-0.4.1}/src/cli_login/remote_test.py

@@ -354,3 +354,57 @@ def test_a_refused_enrollment_stores_nothing():
         remote_login(Target(), stored.append, http=world.http, out=world.printed.append, clock=world.clock,
                      sleep=world.sleep, host="cloud-box", enroll=enrolling(world, calls, fail=True))
     assert raised.value.code == "enrollment_refused" and stored == []
+
+
+def test_a_nonce_mismatch_says_to_start_again_and_reports_one_way_tags_without_any_nonce():
+    world, stored = World(), []
+    original = world.http
+
+    def swapped(method, url, **kwargs):
+        status, body, headers = original(method, url, **kwargs)
+        if url == TOKEN and status == 200:
+            body["id_token"] = jwt({"nonce": "someone-elses-nonce"})
+        return status, body, headers
+
+    world.http = swapped
+    with pytest.raises(RemoteLoginError) as raised:
+        remote_login(Target(), stored.append, http=world.http, out=world.printed.append, clock=world.clock, sleep=world.sleep,
+                     host="cloud-box", login_command="app login --remote example.test")
+    error = raised.value
+    assert error.code == "nonce_mismatch" and stored == []
+    assert "nothing was saved" in str(error) and "Start the sign-in again with `app login --remote example.test`." in str(error)
+    tag = hashlib.sha256(b"someone-elses-nonce").hexdigest()[:8]
+    assert error.diagnostics["received_nonce"] == tag and error.diagnostics["enroll"] == "off"
+    assert error.diagnostics["broker_nonce"] == "none" and error.diagnostics["expected_nonce"] == error.diagnostics["own_nonce"]
+    assert error.diagnostics["transaction"] == hashlib.sha256(world.transaction.encode()).hexdigest()[:8]
+    assert "someone-elses-nonce" not in str(error) and world.transaction not in str(error)
+    assert all(len(value) <= 8 for key, value in error.diagnostics.items() if key.endswith("nonce") or key == "transaction")
+
+
+def test_the_diagnostics_tell_a_page_that_used_the_product_nonce_from_a_cli_that_did_not_enroll():
+    world, stored = World(product_nonce="challenge-nonce-0001"), []
+    with pytest.raises(RemoteLoginError) as raised:
+        remote_login(Target(), stored.append, http=world.http, out=world.printed.append, clock=world.clock,
+                     sleep=world.sleep, host="cloud-box")
+    diagnostics = raised.value.diagnostics
+    assert diagnostics["enroll"] == "off" and diagnostics["broker_nonce"] == "handed"
+    assert diagnostics["received_nonce"] == hashlib.sha256(b"challenge-nonce-0001").hexdigest()[:8] != diagnostics["expected_nonce"]
+    assert stored == [] and "Start the sign-in again." in str(raised.value)
+
+
+def test_an_enrolling_cli_that_gets_the_other_nonce_refuses_and_never_retries_with_it():
+    world, stored, calls = World(product_nonce="challenge-nonce-0001"), [], []
+    original = world.http
+
+    def swapped(method, url, **kwargs):
+        status, body, headers = original(method, url, **kwargs)
+        if url == TOKEN and status == 200:
+            body["id_token"] = jwt({"nonce": "own-nonce-not-the-products"})
+        return status, body, headers
+
+    world.http = swapped
+    with pytest.raises(RemoteLoginError) as raised:
+        remote_login(Target(), stored.append, http=world.http, out=world.printed.append, clock=world.clock,
+                     sleep=world.sleep, host="cloud-box", enroll=enrolling(world, calls))
+    assert raised.value.code == "nonce_mismatch" and raised.value.diagnostics["enroll"] == "on"
+    assert raised.value.diagnostics["broker_nonce"] == "handed" and stored == [] and calls == [] and len(world.exchanges) == 1

{cli_login-0.4.0 → cli_login-0.4.1}/src/cli_login/stores/agent.py

@@ -28,6 +28,7 @@ import ctypes
 import json
 import os
 import re
+import shlex
 import signal
 import socket
 import stat
@@ -60,13 +61,19 @@ def _require_unix() -> None:
 
 
 def agent_command(namespace: str, *, state_dir: Path | str | None = None, socket_path: Path | str | None = None) -> str:
-    """The command that starts this namespace's agent, for guidance in error messages."""
-    command = f"{os.path.basename(sys.executable) or 'python'} -m cli_login.stores.agent serve --namespace {namespace}"
+    """The command that starts this namespace's agent, for guidance in error messages.
+
+    It names the interpreter that is running right now by its full path, because the library may be installed
+    only in a private environment (``pipx``, ``uv tool``) where a bare ``python`` cannot import it. Every part
+    is shell-quoted, so the line works when pasted.
+    """
+    parts = [sys.executable or "python", "-m", "cli_login.stores.agent", "serve", "--namespace", str(namespace)]
     if state_dir is not None:
-        command += f" --state-dir {state_dir}"
+        parts += ["--state-dir", str(state_dir)]
     if socket_path is not None:
-        command += f" --socket {socket_path}"
-    return command + " --background"
+        parts += ["--socket", str(socket_path)]
+    parts.append("--background")
+    return " ".join(shlex.quote(part) for part in parts)
 
 
 def socket_path_for(namespace: str, state_dir: Path | str | None = None, environ=None) -> Path:

{cli_login-0.4.0 → cli_login-0.4.1}/src/cli_login/stores/agent_test.py

@@ -1,4 +1,5 @@
 import os
+import shlex
 import shutil
 import socket
 import stat
@@ -203,6 +204,32 @@ def test_the_command_line_serves_in_the_background_reports_and_stops(state):
     assert run("status").returncode == 1
 
 
+def test_the_advice_names_the_running_interpreter_by_full_path():
+    words = shlex.split(agent.agent_command("ns"))
+    assert words[0] == sys.executable and os.path.isabs(words[0])
+    assert words[1:] == ["-m", "cli_login.stores.agent", "serve", "--namespace", "ns", "--background"]
+
+
+def test_the_advice_quotes_paths_with_spaces(monkeypatch):
+    monkeypatch.setattr(sys, "executable", "/opt/my tools/venv/bin/python")
+    command = agent.agent_command("ns", state_dir="/tmp/a b", socket_path="/tmp/it's/agent.sock")
+    assert shlex.split(command) == [
+        "/opt/my tools/venv/bin/python", "-m", "cli_login.stores.agent", "serve", "--namespace", "ns",
+        "--state-dir", "/tmp/a b", "--socket", "/tmp/it's/agent.sock", "--background",
+    ]
+
+
+@unix
+def test_the_advice_works_when_pasted_into_a_shell(state):
+    command = agent.agent_command("ns", state_dir=state)
+    try:
+        started = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=60, check=False)
+        assert started.returncode == 0, started.stderr
+        assert agent.status("ns", state_dir=state) is not None
+    finally:
+        agent.stop("ns", state_dir=state)
+
+
 def test_windows_is_not_supported(monkeypatch, tmp_path):
     monkeypatch.setattr(sys, "platform", "win32")
     with pytest.raises(AuthError, match="Windows"):