mostlyright-data 0.20.0__tar.gz → 0.20.2__tar.gz

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.20.0
+Version: 0.20.2
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/
@@ -48,6 +48,18 @@ mr-data whoami
 
 `login` stores a device key on the current machine. `whoami` checks that key.
 
+New macOS/Linux logins use `~/.mostlyright/credentials.secure`, an unencrypted file restricted to
+your OS account (0600 inside a 0700 directory). Processes running as you and backups can read it.
+Older file-based logins migrate to this file without requesting Keychain access. Windows keeps
+DPAPI encryption as its default.
+Existing Keychain, DPAPI, or Secret Service logins keep their selected store; an unavailable store
+never causes an automatic switch to file storage.
+
+If an existing macOS login requests Keychain access, it is requesting the `md.mostlyright.cli`
+device credential. To switch that login to file storage, restore access to its Keychain item,
+run `mr-data auth logout` successfully, then run `mr-data login`. The `--credential-store secure-file`
+option does not move an existing native-store login.
+
 ## Check the installation
 
 ```bash

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/README.md

@@ -36,6 +36,18 @@ mr-data whoami
 
 `login` stores a device key on the current machine. `whoami` checks that key.
 
+New macOS/Linux logins use `~/.mostlyright/credentials.secure`, an unencrypted file restricted to
+your OS account (0600 inside a 0700 directory). Processes running as you and backups can read it.
+Older file-based logins migrate to this file without requesting Keychain access. Windows keeps
+DPAPI encryption as its default.
+Existing Keychain, DPAPI, or Secret Service logins keep their selected store; an unavailable store
+never causes an automatic switch to file storage.
+
+If an existing macOS login requests Keychain access, it is requesting the `md.mostlyright.cli`
+device credential. To switch that login to file storage, restore access to its Keychain item,
+run `mr-data auth logout` successfully, then run `mr-data login`. The `--credential-store secure-file`
+option does not move an existing native-store login.
+
 ## Check the installation
 
 ```bash

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyright-data"
-version = "0.20.0"
+version = "0.20.2"
 description = "Mostly Right hosted CLI for reviewed datasets"
 readme = "README.md"
 requires-python = ">=3.11"

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/skills/mr-data-build/SKILL.md

@@ -252,6 +252,13 @@ machine that is only using the product installs from `pip` instead.
 
 ## Cloud authentication preflight
 
+New and legacy file-based logins on macOS/Linux use an owner-only, unencrypted private file.
+Windows keeps DPAPI encryption by default. Existing native-store logins retain their backend. Never bypass a Keychain/DPAPI/Secret Service refusal by
+selecting secure-file: that flag cannot migrate an existing native-store login. Restore access,
+then use a successful remote-first logout followed by login when the user wants file storage.
+An interrupted sign-in can retain a pending record; follow its recovery instruction instead of
+repeatedly starting another login.
+
 Authentication begins only when the next command will contact the Mostly Right cloud. Immediately
 before hosted `mr-data dataset create` or `mr-data recipe`, run
 `mr-data whoami --json` and read its `status`, and it intentionally does not report
@@ -933,16 +940,25 @@ finished work rather than a shape test. Where a source was never opened, and its
 a guess, two thousand rows a source is the fallback: it exercises every column, every cast and
 every declared check, and it comes back while the person who asked is still watching the page.
 
-**What bounds a source is how much it DECODES, not how much it weighs.** One confined decode may
-hand back 6,845,533 bytes, and a source over that is refused with `READER_BUDGET`, which names both
-sizes. The two quantities come apart constantly: a 10.4 MB document projected to a few columns
-decodes small and runs, while an 8.6 MB table read whole does not, and two members of one 3.6 MB
-archive land on opposite sides. So the fetched size predicts nothing on its own.
+**What bounds a source is how much it DECODES, not how much it weighs.** The two come apart
+constantly: a 10.4 MB document projected to a few columns decodes to a few hundred kilobytes,
+while an 8.6 MB table read whole decodes to 8.6 MB. So the fetched size predicts nothing on its
+own, and a source over either bound is refused with `READER_BUDGET`, which names both sizes.
+
+**How far a source may fetch depends on how it will be read.** A Reader-pinned source, and an
+unpinned `csv` one, fetch up to 256 MiB. An unpinned `ndjson` source fetches up to what one
+confined request carries, about 36 MB. An unpinned `json` or `parquet` source keeps 16 MiB,
+because neither has a row-at-a-time reader and both are read whole inside the clean room —
+pinning a Reader is the way past that. What a source may DECODE to is its Reader family's output
+budget, narrowed to at most 1 GiB, because the whole decoded relation is held in memory while it
+is classified and sealed. A wide source is still best narrowed by projection, which is what
+shrinks the decoded relation; a long source can still be split.
 
 `limits.max_source_bytes` states where fetching STOPS rather than how big the source is, so
 `mr-data recipe` does not refuse a large one. It registers the document and puts one sentence on
-the receipt under `warnings` when the declared number is larger than any decode could return. Read
-that as "go and check this one", not as a failure.
+the receipt under `warnings` when the declared number is larger than a fetch can reach, and the
+sentence names the formats that stop earlier. Read that as "go and check this one", not as a
+failure.
 
 **Which remedy applies depends on which way the source is too big, and lowering the ceiling is
 never it** — that does not fetch less data, it truncates the sample or refuses the full run. A WIDE

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/thin/recipe.py

@@ -67,26 +67,20 @@ REQUIRED_DOCUMENT_MEMBERS: tuple[str, ...] = (
     "timezone",
 )
 
-#: The declared ``limits.max_source_bytes`` above which one source is worth a word, in bytes.
-#:
-#: ⚠ THIS NUMBER BOUNDS THE FETCH, AND WHAT REFUSES IS THE DECODE.  The two are different
-#: quantities and the old value conflated them.  3 MiB came from two observations -- a source that
-#: delivered 5.76 MB and died, one that delivered 1.15 MB and lived -- and neither was a
-#: measurement of anything the run enforces.  Measured properly: a 10,449,878-byte JSON source
-#: projected to five columns SUCCEEDS, while an 8,578,215-byte CSV read whole FAILS, and two
-#: members of ONE 3.6 MB archive land on opposite sides -- so the fetched size, which is what this
-#: member states, cannot order the outcomes at all.
-#:
-#: WHAT ORDERS THEM is how much the Reader DECODES, because the confined decode hands its output
-#: back over a bounded channel and carries it twice there: base64 and as parsed rows.  That
-#: ceiling is ``DELIVERABLE_READER_OUTPUT_BYTES`` on the backend, 6,845,533 bytes, and a source
-#: over it is refused by name with ``READER_BUDGET`` naming both sizes.
-#:
-#: So this stays a warning about a DECLARED ceiling being implausibly large, which is worth one
-#: sentence, and it no longer promises to predict a failure it cannot see.  It is set at the
-#: backend's own output ceiling: a document declaring more than one decode can return is a
-#: document whose author has not measured the source, whatever the source turns out to weigh.
-READER_SOURCE_BYTE_CEILING = 6_845_533
+#: The declared ``limits.max_source_bytes`` above which one source is worth a word, in bytes --
+#: for a source that is read through descriptors, which is a Reader-pinned one or an unpinned
+#: ``csv`` one. That is the hosted fetch cap.
+READER_SOURCE_BYTE_CEILING = 268_435_456
+
+#: The same ceiling for an unpinned ``ndjson`` source. It has an inline streaming pass and no
+#: descriptor-backed one, so its bytes travel inside one confined request and what bounds the
+#: fetch is what that request can carry.
+NDJSON_SOURCE_BYTE_CEILING = 37_745_664
+
+#: And for an unpinned ``json`` or ``parquet`` source, which has no streaming pass at all: both
+#: are read whole inside the clean room, so the fetch keeps the drained read's tighter bound.
+#: Pinning a Reader is what moves a source off this ceiling.
+DRAINED_SOURCE_BYTE_CEILING = 16_777_216
 
 #: How many undescribed columns the warning names before it counts the rest. A table plan admits
 #: 512 columns, and a sentence that spelt every one of them out would be the wall the `numbered`
@@ -194,24 +188,16 @@ def check_document(document: dict[str, Any]) -> None:
 
 
 def source_byte_warnings(sources: Any) -> list[str]:
-    """One sentence per source whose declared ceiling is larger than one Clean room reliably holds.
+    """One sentence per source whose declared ceiling is larger than the hosted lane fetches.
 
     ⚠ WARNINGS, AND NOT A GATE, FOR THE REASON :data:`READER_SOURCE_BYTE_CEILING` GIVES: the
     declared number is where fetching STOPS, not how big the source is. A gate over it refuses
-    recipes that run -- three of this repository's own acceptance documents among them -- and still
-    admits a source that declares 1 MiB and delivers 6. So nothing here decides anything; it hands
-    the agent that wrote the number the measurement it would otherwise learn from a run that died.
-
-    ⚠ THE LARGEST SOURCE DECIDES, NOT THE SUM. One Reader opens one source at a time inside one
-    Clean room, so eight 2 MiB sources are worth nothing and one 6 MiB source is worth a sentence.
-    A warning over the total would shout at recipes that run and stay quiet about the one that
-    will not.
+    recipes that run and still admits a source that declares 1 MiB and delivers 6. So nothing here
+    decides anything; it tells the agent that wrote the number that the hosted lane will not honour
+    it.
 
-    ⚠ AND THE SENTENCE NAMES THE FIX, which is the whole reason it is written here rather than left
-    to a mid-run refusal. It also says what the fix is NOT: a smaller declared ceiling, which
-    truncates the fetch rather than decoding less. Narrowing what the reader projects is the answer
-    when the source is wide; splitting the source is the answer when it is long. Splitting a wide
-    source does nothing, which is why the two cases are named separately.
+    ⚠ THE LARGEST SOURCE DECIDES, NOT THE SUM. One source is fetched at a time, so the sentence is
+    about the one that overstates its ceiling rather than about the total.
 
     A declared ceiling that is not a whole number of bytes is left alone: the document admits no
     fractional number at all, ``read_document`` has already refused one, and re-deciding here what
@@ -228,25 +214,45 @@ def source_byte_warnings(sources: Any) -> list[str]:
         if not isinstance(limits, Mapping):
             continue
         declared = limits.get("max_source_bytes")
-        if type(declared) is not int or declared <= READER_SOURCE_BYTE_CEILING:
+        if type(declared) is not int:
+            continue
+        ceiling, why = _source_byte_ceiling(source)
+        if declared <= ceiling:
             continue
         named = source.get("name")
         where = f"{named!r}" if isinstance(named, str) and named else f"sources[{index}]"
         said.append(
-            f"source {where} declares limits.max_source_bytes of {declared:,} bytes, which is "
-            f"more than one confined decode can hand back ({READER_SOURCE_BYTE_CEILING:,}). That "
-            "is a ceiling on fetching rather than a measurement of the source, so this registers "
-            "and runs. What decides the run is how much the Reader DECODES, not how much is "
-            "fetched: a wide document projected to a few columns decodes small however large it "
-            "arrives, and a compact archive member can decode past the ceiling. A source that "
-            "does is refused by name with READER_BUDGET, which states both sizes. Lowering this "
-            "ceiling does not help, because it bounds the fetch and truncates rather than "
-            "decoding less. Narrow the projection, or split the source and union the parts in a "
-            "first transform step"
+            f"source {where} declares limits.max_source_bytes of {declared:,} bytes, and {why} "
+            f"stops at {ceiling:,}. That is a ceiling on fetching rather than a measurement of "
+            "the source, so this registers and runs, and the fetch stops there whatever the "
+            "document says. An unpinned source that answers ndjson stops at "
+            f"{NDJSON_SOURCE_BYTE_CEILING:,} and one that answers json or parquet at "
+            f"{DRAINED_SOURCE_BYTE_CEILING:,}, and pinning a Reader is what moves it off "
+            "those. Declare what the source actually weighs"
         )
     return said
 
 
+def _source_byte_ceiling(source: Mapping[str, Any]) -> tuple[int, str]:
+    """The fetch ceiling one declared source is held to, and the phrase that names it.
+
+    A document declares a Reader pin on ``connector.parameters`` and declares no wire format at
+    all: the format is what the response turns out to be. So the one thing this client can read
+    off the document is whether the source is pinned. A pinned source fetches to the hosted cap
+    whatever its wire format. An unpinned source is held to the same cap here, and the sentence
+    says which formats stop earlier, because that is decided by bytes this client has not seen.
+    """
+
+    connector = source.get("connector")
+    parameters = connector.get("parameters") if isinstance(connector, Mapping) else None
+    if isinstance(parameters, list) and any(
+        isinstance(parameter, Mapping) and parameter.get("name") == "reader.family_id"
+        for parameter in parameters
+    ):
+        return READER_SOURCE_BYTE_CEILING, "a Reader-pinned source's fetch"
+    return READER_SOURCE_BYTE_CEILING, "an unpinned source's fetch"
+
+
 def columns_without_description(table: Any) -> list[str]:
     """The declared columns carrying no description, in the order the document declares them.
 
@@ -469,8 +475,10 @@ def recipe(args: argparse.Namespace, *, client: StudioV4Client | None = None) ->
 
 __all__ = [
     "COMMAND_HELP",
+    "DRAINED_SOURCE_BYTE_CEILING",
     "MAX_DOCUMENT_BYTES",
     "NAMED_UNDESCRIBED_COLUMNS",
+    "NDJSON_SOURCE_BYTE_CEILING",
     "READER_SOURCE_BYTE_CEILING",
     "REGISTER_SCHEMA",
     "REQUIRED_DOCUMENT_MEMBERS",

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/ux/commands/auth.py

@@ -48,7 +48,9 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
         dest="auth_command", required=True, help="device-authority operation"
     )
     nested_json = argparse.ArgumentParser(add_help=False)
-    nested_json.add_argument("--json", action="store_true", help=argparse.SUPPRESS)
+    nested_json.add_argument(
+        "--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS
+    )
 
     status = subcommands.add_parser(
         "status", parents=[nested_json], help="validate the effective device credential"
@@ -56,7 +58,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
     status.add_argument(
         "--credential-store",
         choices=("secure-file",),
-        help="explicitly use the secure-file fallback for first credential migration",
+        help="select private-file storage for legacy credential migration",
     )
     status.set_defaults(auth_operation="status")
 
@@ -95,7 +97,9 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
     )
     login.add_argument("--device-name", help="what to call this device in Cloud")
     login.add_argument(
-        "--credential-store", choices=("secure-file",), help="explicit secure-file store"
+        "--credential-store",
+        choices=("secure-file",),
+        help="select private-file storage; cannot change an existing native store",
     )
     login.set_defaults(auth_operation="login")
     rotate = subcommands.add_parser(
@@ -103,7 +107,9 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
     )
     rotate.add_argument("--device-name", help="what to call the replacement device")
     rotate.add_argument(
-        "--credential-store", choices=("secure-file",), help="explicit secure-file store"
+        "--credential-store",
+        choices=("secure-file",),
+        help="select private-file storage; cannot change an existing native store",
     )
     rotate.set_defaults(auth_operation="rotate")
     logout = subcommands.add_parser(
@@ -117,7 +123,9 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
         help="remove local state without claiming remote revocation",
     )
     logout.add_argument(
-        "--credential-store", choices=("secure-file",), help="explicit secure-file store"
+        "--credential-store",
+        choices=("secure-file",),
+        help="select private-file storage; cannot change an existing native store",
     )
     logout.set_defaults(auth_operation="logout")
     recover = subcommands.add_parser(
@@ -131,7 +139,9 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
         help="clear only a stale login lease; remote mint remains unproved",
     )
     recover.add_argument(
-        "--credential-store", choices=("secure-file",), help="explicit secure-file store"
+        "--credential-store",
+        choices=("secure-file",),
+        help="select private-file storage; cannot change an existing native store",
     )
     recover.set_defaults(auth_operation="recover")
 
@@ -145,9 +155,17 @@ def run(args: argparse.Namespace) -> dict[str, Any]:
     if operation == "devices_revoke":
         return device_revoke_payload(args.key_id)
     if operation == "login":
-        return login_payload(device_name=args.device_name, credential_store=args.credential_store)
+        return login_payload(
+            device_name=args.device_name,
+            credential_store=args.credential_store,
+            announce=not args.json,
+        )
     if operation == "rotate":
-        return rotate_payload(device_name=args.device_name, credential_store=args.credential_store)
+        return rotate_payload(
+            device_name=args.device_name,
+            credential_store=args.credential_store,
+            announce=not args.json,
+        )
     if operation == "logout":
         return logout_payload(local_only=args.local_only, credential_store=args.credential_store)
     if operation == "recover":
@@ -491,6 +509,19 @@ def recover_payload(
         with credential_lock(store.config_dir):
             envelope = store.load_under_held_lock()
             if envelope is None:
+                if local_only:
+                    # Resume a crash after deleting an empty pending store but before
+                    # removing its selector. Never claim remote cleanup from local absence.
+                    remove_credential_manifest_under_held_lock(path)
+                    return _with_environment_authority(
+                        {
+                            "schema_version": _RECOVERY_SCHEMA,
+                            "status": "local_recovery_completed",
+                            "remote_revocation": "unproved",
+                            "local_state": "removed",
+                            "mint_outcome": "unproved",
+                        }
+                    )
                 return _mutation_error(
                     _RECOVERY_SCHEMA,
                     status="refused",
@@ -516,16 +547,37 @@ def recover_payload(
                 )
             if envelope.state == "login_pending":
                 if not local_only:
-                    return _mutation_error(
-                        _RECOVERY_SCHEMA, status="refused", local_state="pending"
+                    return {
+                        **_mutation_error(
+                            _RECOVERY_SCHEMA, status="refused", local_state="pending"
+                        ),
+                        "next_action": "Finish or stop the previous sign-in. If it has stopped, "
+                        "run mr-data auth recover --local-only, then retry logout or login. "
+                        "Local recovery does not prove remote revocation.",
+                    }
+                # The outer lock already owns this generation. Calling the standalone
+                # recovery helper here would try to acquire the same non-reentrant lock.
+                if envelope.active is None:
+                    # Keep the selector retryable if the native delete refuses access.
+                    store.delete_under_held_lock(
+                        expected_generation=envelope.generation,
+                        expected_states=frozenset({"login_pending"}),
+                    )
+                    remove_credential_manifest_under_held_lock(path)
+                else:
+                    store.replace_under_held_lock(
+                        CredentialEnvelope.active_envelope(
+                            generation=envelope.generation + 1, active=envelope.active
+                        ),
+                        expected_generation=envelope.generation,
+                        expected_states=frozenset({"login_pending"}),
                     )
-                store.recover_login_lease_local_only()
                 return _with_environment_authority(
                     {
                         "schema_version": _RECOVERY_SCHEMA,
                         "status": "local_recovery_completed",
                         "remote_revocation": "unproved",
-                        "local_state": "recovered",
+                        "local_state": "active" if envelope.active is not None else "removed",
                         "mint_outcome": "unproved",
                     }
                 )
@@ -652,16 +704,29 @@ def _cleanup_environment_revoked_stored_target(
         return "pending"
 
 
-def login_payload(*, device_name: str | None, credential_store: str | None) -> dict[str, Any]:
-    from mostlyright.data_harness.ux.login import run_login
+def login_payload(
+    *, device_name: str | None, credential_store: str | None, announce: bool = False
+) -> dict[str, Any]:
+    from mostlyright.data_harness.ux.login import announce_device_code, run_login
 
-    return run_login(device_name=device_name, credential_store=credential_store)
+    return run_login(
+        device_name=device_name,
+        credential_store=credential_store,
+        announce=announce_device_code if announce else None,
+    )
 
 
-def rotate_payload(*, device_name: str | None, credential_store: str | None) -> dict[str, Any]:
-    from mostlyright.data_harness.ux.login import run_login
+def rotate_payload(
+    *, device_name: str | None, credential_store: str | None, announce: bool = False
+) -> dict[str, Any]:
+    from mostlyright.data_harness.ux.login import announce_device_code, run_login
 
-    return run_login(device_name=device_name, force=True, credential_store=credential_store)
+    return run_login(
+        device_name=device_name,
+        force=True,
+        credential_store=credential_store,
+        announce=announce_device_code if announce else None,
+    )
 
 
 def tokens_payload(operation: str) -> dict[str, Any]:

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/ux/commands/login.py

@@ -22,8 +22,10 @@ from mostlyright.data_harness.ux.login import CLOUD_URL_ENV, announce_device_cod
 
 DESCRIPTION = (
     "Sign in to the Mostly Right cloud from this machine. Prints a short code and opens a browser "
-    "to approve it there, then stores a durable device credential at ~/.mostlyright/credentials, "
-    f"mode 0600. The raw credential is never printed; only its prefix and last four characters "
+    "to approve it there. New macOS/Linux logins use ~/.mostlyright/credentials.secure, an "
+    "unencrypted file restricted to your OS account (0600). Windows uses DPAPI encryption; "
+    "existing logins keep their selected store. "
+    f"The raw credential is never printed; only its prefix and last four characters "
     f"are. Set {CLOUD_URL_ENV} to sign in against a different cloud."
 )
 
@@ -42,7 +44,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--credential-store",
         choices=("secure-file",),
-        help="explicitly use the secure-file credential store",
+        help="use the private-file store (default on macOS/Linux; existing stores are preserved)",
     )
 
 

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/ux/commands/whoami.py

@@ -18,7 +18,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--credential-store",
         choices=("secure-file",),
-        help="explicitly use the secure-file fallback for first credential migration",
+        help="select private-file storage for legacy credential migration",
     )
 
 

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/ux/credential_native.py

@@ -56,8 +56,8 @@ class MacOSKeychainBackend:
             if payload is not None and len(payload) > MAX_CREDENTIAL_ENVELOPE_BYTES:
                 raise ValueError("oversized item")
             return payload
-        except Exception:
-            raise _native_refusal("Keychain", "copy") from None
+        except Exception as error:
+            raise _keychain_refusal("read", error) from None
 
     def write(self, payload: bytes) -> None:
         if len(payload) > MAX_CREDENTIAL_ENVELOPE_BYTES:
@@ -67,16 +67,16 @@ class MacOSKeychainBackend:
         mutable = bytearray(payload)
         try:
             self._ffi.write(mutable, service=_SERVICE, account=_ACCOUNT)
-        except Exception:
-            raise _native_refusal("Keychain", "store") from None
+        except Exception as error:
+            raise _keychain_refusal("write", error) from None
         finally:
             _zero(mutable)
 
     def delete(self) -> None:
         try:
             self._ffi.delete(service=_SERVICE, account=_ACCOUNT)
-        except Exception:
-            raise _native_refusal("Keychain", "delete") from None
+        except Exception as error:
+            raise _keychain_refusal("delete", error) from None
 
 
 class DPAPIBackend:
@@ -91,7 +91,6 @@ class DPAPIBackend:
             # keeps replace/fsync/link checks identical without making secure-file a fallback.
             self._blob = SecureFileBackend(
                 config_dir,
-                explicit=True,
                 filename="credentials.dpapi",
             )
         except Exception:
@@ -248,8 +247,8 @@ def native_backend(
             if executable is None:
                 raise CredentialStoreError(
                     "CREDENTIAL_STORE_UNAVAILABLE",
-                    "Secret Service probe failed; explicitly select "
-                    "--credential-store secure-file to use an owner-controlled file",
+                    "Secret Service is unavailable; restore secret-tool and the desktop "
+                    "secret service to access the existing login",
                 )
             return SecretServiceBackend(executable=executable)
     except CredentialStoreError:
@@ -258,8 +257,7 @@ def native_backend(
         pass
     raise CredentialStoreError(
         "CREDENTIAL_STORE_UNAVAILABLE",
-        "native protected storage is unavailable; explicitly select "
-        "--credential-store secure-file to use an owner-controlled file",
+        "the existing login uses native protected storage that is unavailable on this system",
     )
 
 
@@ -270,6 +268,21 @@ def _native_refusal(adapter: str, outcome: str) -> CredentialStoreError:
     )
 
 
+class _KeychainStatusError(OSError):
+    """Carry only the numeric Security.framework result, never native error text."""
+
+    def __init__(self, status: int) -> None:
+        self.status = status
+        super().__init__("Keychain operation failed")
+
+
+def _keychain_refusal(operation: str, error: Exception) -> CredentialStoreError:
+    detail = f"Keychain {operation} failed"
+    if isinstance(error, _KeychainStatusError):
+        detail += f" (OSStatus {error.status})"
+    return CredentialStoreError("CREDENTIAL_STORE_UNAVAILABLE", detail)
+
+
 def _zero(value: bytearray) -> None:
     for index in range(len(value)):
         value[index] = 0
@@ -491,8 +504,10 @@ class _MacOSSecurityFramework:
             status = self._security.SecItemCopyMatching(rich_query, ctypes.byref(result))
             if status == self._NOT_FOUND:
                 return None
-            if status != self._SUCCESS or not result.value:
-                raise OSError("SecItemCopyMatching failed")
+            if status != self._SUCCESS:
+                raise _KeychainStatusError(status)
+            if not result.value:
+                raise OSError("SecItemCopyMatching returned no data")
             length = self._core.CFDataGetLength(result)
             if length < 0 or length > MAX_CREDENTIAL_ENVELOPE_BYTES:
                 raise OSError("invalid Keychain item size")
@@ -525,7 +540,7 @@ class _MacOSSecurityFramework:
                 if status == self._DUPLICATE:
                     status = self._security.SecItemUpdate(query, attributes)
             if status != self._SUCCESS:
-                raise OSError("Keychain write failed")
+                raise _KeychainStatusError(status)
         finally:
             self._core.CFRelease(attributes)
             self._core.CFRelease(data)
@@ -537,7 +552,7 @@ class _MacOSSecurityFramework:
         try:
             status = self._security.SecItemDelete(query)
             if status not in {self._SUCCESS, self._NOT_FOUND}:
-                raise OSError("SecItemDelete failed")
+                raise _KeychainStatusError(status)
         finally:
             self._core.CFRelease(query)
             self._release_all(owned)

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/ux/credential_store.py

@@ -324,7 +324,7 @@ class CredentialBackend(Protocol):
 
 
 class SecureFileBackend:
-    """Explicit, atomic 0600 fallback backend; never selected implicitly."""
+    """Atomic owner-only file backend, selected by policy or a saved manifest."""
 
     name = "secure-file"
 
@@ -332,14 +332,8 @@ class SecureFileBackend:
         self,
         config_dir: Path,
         *,
-        explicit: bool,
         filename: str = SECURE_FILE_NAME,
     ) -> None:
-        if explicit is not True:
-            raise CredentialStoreError(
-                "CREDENTIAL_STORE_EXPLICIT_REQUIRED",
-                "secure-file storage requires explicit selection",
-            )
         self.config_dir = Path(config_dir)
         if not filename or filename in {".", ".."} or Path(filename).name != filename:
             raise CredentialStoreError(

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/ux/credentials.py

@@ -11,7 +11,8 @@ import contextlib
 import os
 import secrets
 import stat
-from collections.abc import Mapping
+import sys
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -175,12 +176,12 @@ def store_credentials(
                 )
             control = _read_control(path)
             if control is None:
-                backend = _backend_for(directory, selector or _native_backend_name(directory))
+                backend = _backend_for(directory, selector or _default_backend_name())
                 current = None
             else:
                 kind, value = _parse_control(control, path)
                 if kind == "legacy":
-                    backend = _backend_for(directory, selector or _native_backend_name(directory))
+                    backend = _backend_for(directory, selector or _default_backend_name())
                     current = None
                 else:
                     backend_name = value["backend"]
@@ -232,7 +233,7 @@ def read_credentials(
                 return _active_credentials(envelope)
 
             legacy = _legacy_credentials(value, path)
-            backend = _backend_for(directory, selector or _native_backend_name(directory))
+            backend = _backend_for(directory, selector or _default_backend_name())
             envelope = CredentialEnvelope.active_envelope(
                 generation=1,
                 active=legacy._protected(),
@@ -295,6 +296,7 @@ def credential_transaction_store(
     *,
     config_dir: Path | None = None,
     credential_store: str | None = None,
+    announce_store: Callable[[str], None] | None = None,
 ) -> tuple[CredentialStore, Path] | None:
     """Return the selected protected store and its non-secret manifest path.
 
@@ -308,7 +310,7 @@ def credential_transaction_store(
     path = directory / CREDENTIALS_FILENAME
     selector = _selector(credential_store)
     if not os.path.lexists(path):
-        backend = _backend_for(directory, selector or _native_backend_name(directory))
+        backend = _backend_for(directory, selector or _default_backend_name())
         return CredentialStore(directory, backend), path
     raw = _read_control(path)
     if raw is None:
@@ -325,6 +327,8 @@ def credential_transaction_store(
         raise LoginError("LOGIN_CREDENTIALS_UNREADABLE", "the stored credential is unreadable")
     backend_name = value["backend"]
     _require_selector_agrees(selector, backend_name)
+    if announce_store is not None and backend_name != "secure-file":
+        announce_store(backend_name)
     return CredentialStore(directory, _backend_for(directory, backend_name)), path
 
 
@@ -388,17 +392,16 @@ def _selector(value: str | None) -> str | None:
     return value
 
 
-def _native_backend_name(directory: Path) -> str:
-    try:
-        return native_backend(directory).name
-    except CredentialStoreError as error:
-        raise login_store_error(error) from None
+def _default_backend_name() -> str:
+    # DPAPI is non-interactive and encrypts the Windows blob; its file ACL gate proves
+    # allowed writers, not absence of inherited readers, so plaintext is not the default there.
+    return "dpapi" if sys.platform == "win32" else "secure-file"
 
 
 def _backend_for(directory: Path, backend_name: str) -> CredentialBackend:
     if backend_name == "secure-file":
         try:
-            return SecureFileBackend(directory, explicit=True)
+            return SecureFileBackend(directory)
         except CredentialStoreError as error:
             raise login_store_error(error) from None
     try:
@@ -594,10 +597,7 @@ def _install_manifest(path: Path, backend_name: str) -> None:
 def login_store_error(error: CredentialStoreError) -> LoginError:
     suffix = error.code.removeprefix("CREDENTIAL_")
     details = {
-        "CREDENTIAL_STORE_UNAVAILABLE": (
-            "native protected storage is unavailable; explicitly select "
-            "--credential-store secure-file to use an owner-controlled file"
-        ),
+        "CREDENTIAL_STORE_UNAVAILABLE": error.detail or "the credential store is unavailable",
         "CREDENTIAL_STORE_WRITE_FAILED": "the protected credential could not be written",
         "CREDENTIAL_STORE_READBACK_FAILED": (
             "the protected credential could not be verified after writing"

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/ux/login.py

@@ -472,6 +472,18 @@ def announce_device_code(authorization: DeviceAuthorization) -> None:
     print("Waiting for approval...", file=sys.stderr, flush=True)
 
 
+def announce_credential_store(backend: str) -> None:
+    """Explain an existing native login before the OS can request access to it."""
+
+    if backend == "keychain":
+        print(
+            "This login uses macOS Keychain. macOS may ask to access mr-data's own device "
+            "credential (md.mostlyright.cli); no other saved passwords are requested.",
+            file=sys.stderr,
+            flush=True,
+        )
+
+
 def run_login(
     *,
     cloud_url: str | None = None,
@@ -508,7 +520,9 @@ def run_login(
         refuse_existing_credentials(config_dir=config_dir)
     try:
         opened = credential_transaction_store(
-            config_dir=config_dir, credential_store=credential_store
+            config_dir=config_dir,
+            credential_store=credential_store,
+            announce_store=announce_credential_store if announce is not None else None,
         )
     except LoginError:
         raise

{mostlyright_data-0.20.0 → mostlyright_data-0.20.2}/src/mostlyright/data_harness/ux/remediation.py

@@ -11,7 +11,7 @@ neither affordable nor honest:
 * **Families.** Every code prefix is assigned to a family -- 224 of them, plus 18 compound
   prefixes, across 38 families. A family is one paragraph: what this class of failure is about,
   where to look, and what to do. Every prefix has one, so no code can fail to say something useful.
-* **Curated codes.** The 103 failures a person actually meets get their own exact sentences, and
+* **Curated codes.** The 107 failures a person actually meets get their own exact sentences, and
   where one command is the whole answer, the command itself.
 
 Those four counts are not a note somebody remembered to update:
@@ -436,7 +436,8 @@ FAMILIES: dict[str, Family] = {
             "on this machine.",
             "The message names the step that stopped: starting sign-in, waiting for browser "
             "approval, or storing the credential.",
-            "A stopped sign-in stores nothing. Run mr-data login again to retry.",
+            "A stopped sign-in may retain the previous login or a pending sign-in record. "
+            "Follow the storage or recovery instruction in the message before retrying.",
         )
     ),
     # Catalog facts and provenance require remediation distinct from Recipe source files.
@@ -1770,6 +1771,41 @@ CODES: dict[str, Remediation] = {
             "mr-data login --force.",
         ),
     ),
+    "LOGIN_CREDENTIAL_STORE_UNAVAILABLE": Remediation(
+        lines=(
+            "The selected credential store could not be accessed. The message names the "
+            "backend and operation when available.",
+            "For an existing macOS Keychain login, unlock your login keychain and allow access "
+            "to the md.mostlyright.cli item, then retry the original command. mr-data requests "
+            "its own device credential, not other saved passwords.",
+            "The secure-file flag cannot switch an existing Keychain login. To move to file "
+            "storage, restore access and run mr-data auth logout successfully, then mr-data login.",
+        ),
+    ),
+    "LOGIN_CREDENTIAL_STORE_CONFLICT": Remediation(
+        lines=(
+            "The requested storage differs from the existing login's storage. Nothing was "
+            "moved to another store.",
+            "Retry without --credential-store to use the existing store. On macOS/Linux, to use "
+            "private-file storage instead, first run mr-data auth logout successfully, then "
+            "mr-data login.",
+        ),
+    ),
+    "LOGIN_CREDENTIAL_LOGIN_PENDING": Remediation(
+        lines=(
+            "A previous device sign-in is still recorded as pending. It may still be running.",
+            "Finish or stop that sign-in first. If it has stopped, run "
+            "mr-data auth recover --local-only to clear its pending record before retrying. "
+            "This does not prove that any remotely issued device key was revoked.",
+        ),
+    ),
+    "LOGIN_CREDENTIAL_RECOVERY_REQUIRED": Remediation(
+        lines=(
+            "The stored login has an unfinished operation. Starting another sign-in would "
+            "lose its recovery record.",
+            "Run mr-data auth recover and follow its result before retrying sign-in.",
+        ),
+    ),
     # `mr-data` narrows a credential directory it already owns, so what is left for this code to
     # report is something it may not touch on its own.
     "LOGIN_CREDENTIAL_STORE_PERMISSIONS": Remediation(