mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/commands/auth.py

@@ -0,0 +1,744 @@
+"""Remote-truthful device authentication status and metadata commands."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.key_seam import LEGACY_API_KEY_ENV
+from mostlyright.data_harness.ux.cloud_auth import CloudAuthClient, CloudAuthError
+from mostlyright.data_harness.ux.commands import CommandSpec
+from mostlyright.data_harness.ux.credential_store import (
+    CredentialEnvelope,
+    CredentialStoreError,
+    credential_lock,
+)
+from mostlyright.data_harness.ux.credentials import (
+    LoginError,
+    credential_transaction_store,
+    credentials_path,
+    read_credentials,
+    remove_credential_manifest_under_held_lock,
+    resolve_cloud_credentials,
+)
+
+_STATUS_SCHEMA = "mr-data-auth-status.v1"
+_DEVICES_SCHEMA = "mr-data-auth-devices.v1"
+_TOKEN_SCHEMA = "mr-data-auth-token-boundary.v1"
+_LOGOUT_SCHEMA = "mr-data-auth-logout.v1"
+_RECOVERY_SCHEMA = "mr-data-auth-recovery.v1"
+_ROTATE_SCHEMA = "mr-data-auth-rotate.v1"
+_DEVICE_REVOKE_SCHEMA = "mr-data-auth-device-revoke.v1"
+_REFUSAL_CODES = frozenset({"CLOUD_AUTH_FORBIDDEN", "CLOUD_AUTH_NOT_FOUND"})
+
+DESCRIPTION = (
+    "Inspect the effective Mostly Right device authority through Cloud. Status validates only the "
+    "effective credential and shows stored metadata separately. Device inventory is metadata-only; "
+    "Studio access tokens are ephemeral transport credentials, not local credentials."
+)
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    """Declare the whole offline-discoverable auth hierarchy."""
+
+    parser.description = DESCRIPTION
+    subcommands = parser.add_subparsers(
+        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)
+
+    status = subcommands.add_parser(
+        "status", parents=[nested_json], help="validate the effective device credential"
+    )
+    status.add_argument(
+        "--credential-store",
+        choices=("secure-file",),
+        help="explicitly use the secure-file fallback for first credential migration",
+    )
+    status.set_defaults(auth_operation="status")
+
+    devices = subcommands.add_parser(
+        "devices", parents=[nested_json], help="inspect or manage Cloud device keys"
+    )
+    device_commands = devices.add_subparsers(
+        dest="devices_command", required=True, help="device-key operation"
+    )
+    device_commands.add_parser(
+        "list", parents=[nested_json], help="list Cloud device-key metadata in Cloud order"
+    ).set_defaults(auth_operation="devices_list")
+    revoke = device_commands.add_parser(
+        "revoke",
+        parents=[nested_json],
+        help="revoke one Cloud device key with remote-first local cleanup",
+    )
+    revoke.add_argument("key_id", metavar="KEY_ID", help="Cloud device-key identifier")
+    revoke.set_defaults(auth_operation="devices_revoke")
+
+    tokens = subcommands.add_parser(
+        "tokens", parents=[nested_json], help="describe the Studio transport-token boundary"
+    )
+    token_commands = tokens.add_subparsers(
+        dest="tokens_command", required=True, help="transport-token operation"
+    )
+    token_commands.add_parser(
+        "list", parents=[nested_json], help="explain why ephemeral tokens cannot be listed"
+    ).set_defaults(auth_operation="tokens_list")
+    token_commands.add_parser(
+        "revoke", parents=[nested_json], help="explain why ephemeral tokens cannot be revoked"
+    ).set_defaults(auth_operation="tokens_revoke")
+
+    login = subcommands.add_parser(
+        "login", parents=[nested_json], help="sign in with a device code"
+    )
+    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"
+    )
+    login.set_defaults(auth_operation="login")
+    rotate = subcommands.add_parser(
+        "rotate", parents=[nested_json], help="replace a device key safely"
+    )
+    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"
+    )
+    rotate.set_defaults(auth_operation="rotate")
+    logout = subcommands.add_parser(
+        "logout",
+        parents=[nested_json],
+        help="remotely revoke then remove stored authority",
+    )
+    logout.add_argument(
+        "--local-only",
+        action="store_true",
+        help="remove local state without claiming remote revocation",
+    )
+    logout.add_argument(
+        "--credential-store", choices=("secure-file",), help="explicit secure-file store"
+    )
+    logout.set_defaults(auth_operation="logout")
+    recover = subcommands.add_parser(
+        "recover",
+        parents=[nested_json],
+        help="resume or explicitly clear interrupted credential state",
+    )
+    recover.add_argument(
+        "--local-only",
+        action="store_true",
+        help="clear only a stale login lease; remote mint remains unproved",
+    )
+    recover.add_argument(
+        "--credential-store", choices=("secure-file",), help="explicit secure-file store"
+    )
+    recover.set_defaults(auth_operation="recover")
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    operation = args.auth_operation
+    if operation == "status":
+        return status_payload(credential_store=args.credential_store)
+    if operation == "devices_list":
+        return devices_list_payload()
+    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)
+    if operation == "rotate":
+        return rotate_payload(device_name=args.device_name, credential_store=args.credential_store)
+    if operation == "logout":
+        return logout_payload(local_only=args.local_only, credential_store=args.credential_store)
+    if operation == "recover":
+        return recover_payload(local_only=args.local_only, credential_store=args.credential_store)
+    if operation == "tokens_list":
+        return tokens_payload("list")
+    if operation == "tokens_revoke":
+        return tokens_payload("revoke")
+    return _reserved_lifecycle_payload(operation.removeprefix("reserved_"))
+
+
+def exit_code(payload: Mapping[str, Any]) -> int:
+    """Derive the one command exit from the one receipt payload."""
+
+    status = payload.get("status")
+    if status in {
+        "authenticated",
+        "not_authenticated",
+        "listed",
+        "logged_out",
+        "local_recovery_completed",
+        "recovered",
+        "device_authenticated",
+        "rotated",
+        "revoked",
+    }:
+        return 0
+    if status in {"unsupported", "not_implemented", "refused"}:
+        return 2
+    return 1
+
+
+def status_payload(*, credential_store: str | None = None) -> dict[str, Any]:
+    """Project remote identity for exactly one effective source, never two."""
+
+    try:
+        effective = resolve_cloud_credentials(credential_store=credential_store)
+    except LoginError as error:
+        if error.code == "LOGIN_REQUIRED":
+            return {
+                "schema_version": _STATUS_SCHEMA,
+                "status": "not_authenticated",
+                "effective_source": None,
+                "stored_state": _stored_state(credential_store),
+                "remote_validation": "not_attempted",
+            }
+        return _storage_error_payload(error, source=None)
+
+    stored_state = _stored_state(credential_store)
+    try:
+        current = CloudAuthClient(effective.cloud_url, effective.raw_key).current()
+    except CloudAuthError as error:
+        status = "refused" if error.code in _REFUSAL_CODES else "error"
+        payload: dict[str, Any] = {
+            "schema_version": _STATUS_SCHEMA,
+            "status": status,
+            "effective_source": effective.source,
+            "stored_state": stored_state,
+            "remote_validation": "refused" if status == "refused" else "failed",
+            "error_code": error.code,
+        }
+        if error.retry_after_seconds is not None:
+            payload["retry_after_seconds"] = error.retry_after_seconds
+        return payload
+
+    payload = {
+        "schema_version": _STATUS_SCHEMA,
+        "status": "authenticated",
+        "effective_source": effective.source,
+        "stored_state": stored_state,
+        "remote_validation": "validated",
+        **current.to_receipt(),
+    }
+    if effective.source == "environment":
+        payload["environment_notice"] = (
+            "MOSTLYRIGHT_API_KEY is effective for this process; mr-data cannot unset a "
+            "parent-process environment credential."
+        )
+    return payload
+
+
+def devices_list_payload() -> dict[str, Any]:
+    """List only Cloud's allowlisted device metadata, in its supplied order."""
+
+    try:
+        effective = resolve_cloud_credentials()
+    except LoginError as error:
+        return _devices_login_error(error)
+    try:
+        devices = CloudAuthClient(effective.cloud_url, effective.raw_key).list_devices()
+    except CloudAuthError as error:
+        status = "refused" if error.code in _REFUSAL_CODES else "error"
+        payload: dict[str, Any] = {
+            "schema_version": _DEVICES_SCHEMA,
+            "status": status,
+            "effective_source": effective.source,
+            "error_code": error.code,
+        }
+        if error.retry_after_seconds is not None:
+            payload["retry_after_seconds"] = error.retry_after_seconds
+        return payload
+    return {
+        "schema_version": _DEVICES_SCHEMA,
+        "status": "listed",
+        "effective_source": effective.source,
+        "devices": [device.to_receipt() for device in devices],
+    }
+
+
+def reserved_device_revoke_payload(key_id: str) -> dict[str, Any]:
+    """Parse the future mutation coordinate without performing a local mutation early."""
+
+    del key_id
+    return {
+        "schema_version": _DEVICES_SCHEMA,
+        "status": "not_implemented",
+        "detail": "device revoke is reserved for the remote-first lifecycle command",
+    }
+
+
+def _store_for_mutation(
+    *, config_dir: Path | None, credential_store: str | None
+) -> tuple[Any, Path] | None:
+    return credential_transaction_store(config_dir=config_dir, credential_store=credential_store)
+
+
+def _mutation_error(
+    schema: str,
+    error: Exception | None = None,
+    *,
+    status: str = "error",
+    remote_revocation: str = "unproved",
+    local_state: str = "retained",
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "schema_version": schema,
+        "status": status,
+        "remote_revocation": remote_revocation,
+        "local_state": local_state,
+    }
+    if isinstance(error, (CloudAuthError, LoginError, CredentialStoreError)):
+        payload["error_code"] = error.code
+    return _with_environment_authority(payload)
+
+
+def _client(
+    cloud_url: str,
+    raw_key: str,
+    cloud_client_factory: Any | None,
+) -> Any:
+    factory = CloudAuthClient if cloud_client_factory is None else cloud_client_factory
+    return factory(cloud_url, raw_key)
+
+
+def _remove_local_under_lock(
+    store: Any,
+    path: Path,
+    envelope: CredentialEnvelope,
+    *,
+    fail_after_protected_delete: bool = False,
+) -> str:
+    """Remove the manifest before protected state, never inventing durable remote proof."""
+
+    remove_credential_manifest_under_held_lock(path)
+    # This fault seam models the only recoverable cleanup crash: the protected
+    # logout_pending envelope remains selected by the native default or an
+    # explicit secure-file selector and can replay its exact Cloud DELETE.
+    if fail_after_protected_delete:
+        return "pending"
+    store.delete_under_held_lock(
+        expected_generation=envelope.generation, expected_states=frozenset({envelope.state})
+    )
+    return "removed"
+
+
+def _with_environment_authority(payload: dict[str, Any]) -> dict[str, Any]:
+    if LEGACY_API_KEY_ENV in os.environ:
+        payload["environment_authority"] = "remains_effective"
+    return payload
+
+
+def logout_payload(
+    *,
+    local_only: bool = False,
+    config_dir: Path | None = None,
+    credential_store: str | None = None,
+    cloud_client_factory: Any | None = None,
+    fail_after_pending: bool = False,
+    fail_after_protected_delete: bool = False,
+) -> dict[str, Any]:
+    """Remotely prove self-revocation before normal local credential deletion.
+
+    ``fail_after_pending`` is a deterministic fault-injection seam used only by the transaction
+    tests: it models a crash after the remote commit and durable pending transition.
+    """
+
+    try:
+        opened = _store_for_mutation(config_dir=config_dir, credential_store=credential_store)
+    except LoginError as error:
+        if local_only:
+            return _local_only_unreadable(config_dir=config_dir, error=error)
+        return _mutation_error(_LOGOUT_SCHEMA, error)
+    if opened is None:
+        return _mutation_error(_LOGOUT_SCHEMA, status="refused", local_state="not_configured")
+    store, path = opened
+
+    if local_only:
+        try:
+            with credential_lock(store.config_dir):
+                envelope = store.load_under_held_lock()
+                if envelope is None:
+                    remove_credential_manifest_under_held_lock(path)
+                else:
+                    _remove_local_under_lock(store, path, envelope)
+        except CredentialStoreError:
+            # Explicit local-only recovery is the one path permitted to remove unreadable
+            # protected bytes.  It makes no claim that Cloud was reached or that revocation won.
+            try:
+                with credential_lock(store.config_dir):
+                    store.backend.delete()
+                    remove_credential_manifest_under_held_lock(path)
+            except (LoginError, CredentialStoreError) as error:
+                return _mutation_error(_LOGOUT_SCHEMA, error)
+        except LoginError as error:
+            return _mutation_error(_LOGOUT_SCHEMA, error)
+        return _with_environment_authority(
+            {
+                "schema_version": _LOGOUT_SCHEMA,
+                "status": "local_recovery_completed",
+                "remote_revocation": "unproved",
+                "local_state": "removed",
+            }
+        )
+
+    try:
+        effective = resolve_cloud_credentials(
+            config_dir=config_dir, credential_store=credential_store
+        )
+    except LoginError as error:
+        return _mutation_error(_LOGOUT_SCHEMA, error)
+    if effective.source != "stored_device":
+        return _mutation_error(_LOGOUT_SCHEMA, status="refused")
+
+    try:
+        with credential_lock(store.config_dir):
+            envelope = store.load_under_held_lock()
+            if envelope is None or envelope.state != "active" or envelope.active is None:
+                return _mutation_error(_LOGOUT_SCHEMA, status="refused")
+            active = envelope.active
+            client = _client(active.cloud_url, active.raw_key, cloud_client_factory)
+            current = client.current()
+            if current.device.key_id != active.key_id:
+                return _mutation_error(_LOGOUT_SCHEMA, status="error")
+            # Persist the replay coordinate before the irrevocable remote call.  If the
+            # process dies after Cloud accepts DELETE, recovery owns this exact credential
+            # and may ask Cloud only for the documented same-secret replay proof.
+            pending = CredentialEnvelope.pending_logout(
+                generation=envelope.generation + 1, active=active
+            )
+            store.replace_under_held_lock(
+                pending,
+                expected_generation=envelope.generation,
+                expected_states=frozenset({"active"}),
+            )
+            try:
+                client.revoke(active.key_id, exact_secret_same_key_replay=True)
+            except CloudAuthError as error:
+                return _mutation_error(
+                    _LOGOUT_SCHEMA,
+                    error,
+                    status="recovery_required",
+                    remote_revocation="unproved",
+                    local_state="pending",
+                )
+            if fail_after_pending:
+                return _mutation_error(
+                    _LOGOUT_SCHEMA,
+                    status="recovery_required",
+                    remote_revocation="proved",
+                    local_state="pending",
+                )
+            try:
+                state = _remove_local_under_lock(
+                    store,
+                    path,
+                    pending,
+                    fail_after_protected_delete=fail_after_protected_delete,
+                )
+                if state == "pending":
+                    return _mutation_error(
+                        _LOGOUT_SCHEMA,
+                        status="recovery_required",
+                        remote_revocation="proved",
+                        local_state="pending",
+                    )
+            except (LoginError, CredentialStoreError) as error:
+                return _mutation_error(
+                    _LOGOUT_SCHEMA,
+                    error,
+                    status="recovery_required",
+                    remote_revocation="proved",
+                    local_state="pending",
+                )
+    except (CloudAuthError, LoginError, CredentialStoreError) as error:
+        return _mutation_error(_LOGOUT_SCHEMA, error)
+    return _with_environment_authority(
+        {
+            "schema_version": _LOGOUT_SCHEMA,
+            "status": "logged_out",
+            "remote_revocation": "proved",
+            "local_state": "removed",
+        }
+    )
+
+
+def _local_only_unreadable(*, config_dir: Path | None, error: LoginError) -> dict[str, Any]:
+    """Remove an unreadable control file only when the caller made local-only intent explicit."""
+
+    path = credentials_path(config_dir)
+    try:
+        if path.exists() or path.is_symlink():
+            path.unlink()
+    except OSError:
+        return _mutation_error(_LOGOUT_SCHEMA, error)
+    return _with_environment_authority(
+        {
+            "schema_version": _LOGOUT_SCHEMA,
+            "status": "local_recovery_completed",
+            "remote_revocation": "unproved",
+            "local_state": "removed",
+        }
+    )
+
+
+def recover_payload(
+    *,
+    local_only: bool = False,
+    config_dir: Path | None = None,
+    credential_store: str | None = None,
+    cloud_client_factory: Any | None = None,
+) -> dict[str, Any]:
+    """Resume one closed durable transaction state without inventing remote proof."""
+
+    try:
+        opened = _store_for_mutation(config_dir=config_dir, credential_store=credential_store)
+    except LoginError as error:
+        return _mutation_error(_RECOVERY_SCHEMA, error)
+    if opened is None:
+        return _mutation_error(_RECOVERY_SCHEMA, status="refused", local_state="not_configured")
+    store, path = opened
+    try:
+        with credential_lock(store.config_dir):
+            envelope = store.load_under_held_lock()
+            if envelope is None:
+                return _mutation_error(
+                    _RECOVERY_SCHEMA,
+                    status="refused",
+                    remote_revocation="unproved",
+                    local_state="retained",
+                )
+            if envelope.state == "logout_pending":
+                assert envelope.active is not None
+                client = _client(
+                    envelope.active.cloud_url,
+                    envelope.active.raw_key,
+                    cloud_client_factory,
+                )
+                client.revoke(envelope.active.key_id, exact_secret_same_key_replay=True)
+                _remove_local_under_lock(store, path, envelope)
+                return _with_environment_authority(
+                    {
+                        "schema_version": _RECOVERY_SCHEMA,
+                        "status": "recovered",
+                        "remote_revocation": "proved",
+                        "local_state": "removed",
+                    }
+                )
+            if envelope.state == "login_pending":
+                if not local_only:
+                    return _mutation_error(
+                        _RECOVERY_SCHEMA, status="refused", local_state="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",
+                        "mint_outcome": "unproved",
+                    }
+                )
+            if envelope.state == "revoke_pending":
+                assert envelope.active is not None and envelope.prior is not None
+                client = _client(
+                    envelope.prior.cloud_url, envelope.prior.raw_key, cloud_client_factory
+                )
+                client.revoke(envelope.prior.key_id, exact_secret_same_key_replay=True)
+                cleanup = CredentialEnvelope.pending_cleanup(
+                    generation=envelope.generation + 1,
+                    active=envelope.active,
+                    prior=envelope.prior,
+                )
+                store.replace_under_held_lock(
+                    cleanup,
+                    expected_generation=envelope.generation,
+                    expected_states=frozenset({"revoke_pending"}),
+                )
+                envelope = cleanup
+            if envelope.state == "cleanup_pending":
+                assert envelope.active is not None
+                active = CredentialEnvelope.active_envelope(
+                    generation=envelope.generation + 1, active=envelope.active
+                )
+                store.replace_under_held_lock(
+                    active,
+                    expected_generation=envelope.generation,
+                    expected_states=frozenset({"cleanup_pending"}),
+                )
+                return _with_environment_authority(
+                    {
+                        "schema_version": _RECOVERY_SCHEMA,
+                        "status": "recovered",
+                        "remote_revocation": "proved",
+                        "local_state": "active",
+                    }
+                )
+            return _mutation_error(_RECOVERY_SCHEMA, status="refused", local_state="active")
+    except (CloudAuthError, LoginError, CredentialStoreError) as error:
+        return _mutation_error(_RECOVERY_SCHEMA, error, local_state="pending")
+
+
+def device_revoke_payload(
+    key_id: str,
+    *,
+    config_dir: Path | None = None,
+    credential_store: str | None = None,
+    cloud_client_factory: Any | None = None,
+) -> dict[str, Any]:
+    """Revoke a sibling remotely, or use the logout transaction for the stored current key."""
+
+    try:
+        effective = resolve_cloud_credentials(
+            config_dir=config_dir, credential_store=credential_store
+        )
+        client = _client(effective.cloud_url, effective.raw_key, cloud_client_factory)
+        current = client.current()
+    except (CloudAuthError, LoginError) as error:
+        return _mutation_error(_DEVICE_REVOKE_SCHEMA, error)
+    if current.device.key_id == key_id and effective.source == "stored_device":
+        result = logout_payload(
+            config_dir=config_dir,
+            credential_store=credential_store,
+            cloud_client_factory=cloud_client_factory,
+        )
+        return {
+            "schema_version": _DEVICE_REVOKE_SCHEMA,
+            "status": "revoked" if result["status"] == "logged_out" else result["status"],
+            "remote_revocation": result["remote_revocation"],
+            "local_state": result["local_state"],
+        }
+    try:
+        client.revoke(key_id)
+    except CloudAuthError as error:
+        return _mutation_error(_DEVICE_REVOKE_SCHEMA, error)
+    local_state = (
+        "environment_remains_effective" if effective.source == "environment" else "retained"
+    )
+    if effective.source == "environment":
+        local_state = _cleanup_environment_revoked_stored_target(
+            key_id, config_dir=config_dir, credential_store=credential_store
+        )
+    payload: dict[str, Any] = {
+        "schema_version": _DEVICE_REVOKE_SCHEMA,
+        "status": "revoked",
+        "remote_revocation": "proved",
+        "local_state": local_state,
+    }
+    if effective.source == "environment":
+        payload["environment_authority"] = "remains_effective"
+    return payload
+
+
+def _cleanup_environment_revoked_stored_target(
+    key_id: str,
+    *,
+    config_dir: Path | None,
+    credential_store: str | None,
+) -> str:
+    """Remove only a stored key whose already-proved sibling DELETE targeted it."""
+
+    try:
+        opened = _store_for_mutation(config_dir=config_dir, credential_store=credential_store)
+        if opened is None:
+            return "retained"
+        store, path = opened
+        with credential_lock(store.config_dir):
+            envelope = store.load_under_held_lock()
+            if envelope is None or envelope.state != "active" or envelope.active is None:
+                return "retained"
+            if envelope.active.key_id != key_id:
+                return "retained"
+            pending = CredentialEnvelope.pending_logout(
+                generation=envelope.generation + 1, active=envelope.active
+            )
+            store.replace_under_held_lock(
+                pending,
+                expected_generation=envelope.generation,
+                expected_states=frozenset({"active"}),
+            )
+            return _remove_local_under_lock(store, path, pending)
+    except (LoginError, CredentialStoreError):
+        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
+
+    return run_login(device_name=device_name, credential_store=credential_store)
+
+
+def rotate_payload(*, device_name: str | None, credential_store: str | None) -> dict[str, Any]:
+    from mostlyright.data_harness.ux.login import run_login
+
+    return run_login(device_name=device_name, force=True, credential_store=credential_store)
+
+
+def tokens_payload(operation: str) -> dict[str, Any]:
+    """Tell the truth about a capability Studio does not expose."""
+
+    if operation not in {"list", "revoke"}:
+        return {
+            "schema_version": _TOKEN_SCHEMA,
+            "status": "error",
+            "error_code": "AUTH_TOKEN_OPERATION_INVALID",
+        }
+    return {
+        "schema_version": _TOKEN_SCHEMA,
+        "status": "unsupported",
+        "operation": operation,
+        "detail": (
+            "Studio access tokens are minted ephemerally for transport, not locally stored, "
+            "not listable, and not individually revocable. Rotate, revoke, or log out the "
+            "device key instead."
+        ),
+    }
+
+
+def _stored_state(credential_store: str | None) -> dict[str, Any]:
+    try:
+        stored = read_credentials(credential_store=credential_store)
+    except LoginError as error:
+        return {"status": "unavailable", "error_code": error.code}
+    if stored is None:
+        return {"status": "not_configured"}
+    return {"status": "available", "device": stored.to_receipt()}
+
+
+def _storage_error_payload(error: LoginError, *, source: str | None) -> dict[str, Any]:
+    return {
+        "schema_version": _STATUS_SCHEMA,
+        "status": "error",
+        "effective_source": source,
+        "stored_state": {"status": "unavailable", "error_code": error.code},
+        "remote_validation": "not_attempted",
+        "error_code": error.code,
+    }
+
+
+def _devices_login_error(error: LoginError) -> dict[str, Any]:
+    return {
+        "schema_version": _DEVICES_SCHEMA,
+        "status": "error",
+        "effective_source": None,
+        "error_code": error.code,
+    }
+
+
+def _reserved_lifecycle_payload(operation: str) -> dict[str, Any]:
+    return {
+        "schema_version": _STATUS_SCHEMA,
+        "status": "not_implemented",
+        "detail": f"auth {operation} is reserved for the remote-first credential lifecycle",
+    }
+
+
+SPEC = CommandSpec(
+    name="auth",
+    help="inspect remotely validated device authority and token boundaries",
+    add_arguments=add_arguments,
+    run=run,
+    exit_code=exit_code,
+)