cryptnox-id-cli 1.0.2__py3-none-any.whl

cryptnox_id_cli/cli/commands/readers.py

@@ -0,0 +1,64 @@
+"""``readers`` — list PC/SC readers (passive, no card session)."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+
+from cryptnox_id_cli.cli.context import AppContext
+from cryptnox_id_cli.transport.pcsc import ReaderInfo, reader_states
+
+
+@click.command("readers")
+@click.pass_obj
+def command(app: AppContext) -> None:
+    """List all PC/SC readers, card presence, ATR and the recommended --reader."""
+    infos: list[ReaderInfo] = reader_states()
+    preferred_with_card = [r for r in infos if r.is_preferred and r.present]
+    first_preferred = next((r for r in infos if r.is_preferred), None)
+    # Recommend a single reader only when it is unambiguous (one Cryptnox/ACS reader has a card).
+    recommended = preferred_with_card[0] if len(preferred_with_card) == 1 else None
+    payload = {
+        "readers": [
+            {
+                "index": r.index,
+                "name": r.name,
+                "card_present": r.present,
+                "atr": r.atr_hex or None,
+                "preferred": r.is_preferred,
+            }
+            for r in infos
+        ],
+        "recommended_reader": recommended.name if recommended else None,
+        "preferred_with_card": [r.index for r in preferred_with_card],
+    }
+
+    def human(c: Console) -> None:
+        if not infos:
+            c.print("[yellow]No PC/SC readers found.[/yellow]")
+            return
+        table = app.out.table("#", "Reader", "Card", "ATR", title="PC/SC readers")
+        for r in infos:
+            name = r.name + (" [green](preferred)[/green]" if r.is_preferred else "")
+            card = "[green]present[/green]" if r.present else "[dim]empty[/dim]"
+            table.add_row(str(r.index), name, card, r.atr_hex or "-")
+        c.print(table)
+        if recommended is not None:
+            c.print(
+                f"\nRecommended: [bold]--reader {recommended.index}[/bold]  ({recommended.name})"
+            )
+        elif len(preferred_with_card) > 1:
+            picks = "  ".join(f"--reader {r.index} ({r.name})" for r in preferred_with_card)
+            c.print(
+                f"\n[yellow]Multiple Cryptnox/ACS readers have a card[/yellow] - choose one "
+                f"(PICC = contactless, ICC = contact):\n  {picks}"
+            )
+        elif first_preferred is not None:
+            c.print(
+                f"\n[yellow]Cryptnox/ACS reader {first_preferred.index} has no card[/yellow]; "
+                "insert one or pass --reader."
+            )
+        else:
+            c.print("\n[yellow]No Cryptnox/ACS reader detected; pass --reader explicitly.[/yellow]")
+
+    app.out.result(payload, human)

cryptnox_id_cli/cli/commands/report.py

@@ -0,0 +1,217 @@
+"""``report`` — machine-readable, secret-safe status reports.
+
+Reports contain only non-secret, shareable data: states, versions, object
+presence, public identifiers. No PINs, keys, private material or sensitive
+APDU payloads — by construction (they reuse the read-only inspectors).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import json
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from cryptnox_id_cli import CLI_NAME, __version__
+from cryptnox_id_cli.applets.fido.ctap import Ctap2Client, describe_get_info
+from cryptnox_id_cli.applets.mifare.desfire import DesfireNotSelectedError, DesfireTransport
+from cryptnox_id_cli.cli.commands.info import _read_cplc
+from cryptnox_id_cli.cli.context import AppContext
+from cryptnox_id_cli.state import StateDetector
+from cryptnox_id_cli.transport.elevation import FIDO_WINDOWS_MESSAGE
+from cryptnox_id_cli.transport.errors import (
+    AppletNotFoundError,
+    CardAccessDeniedError,
+    CryptnoxError,
+)
+
+
+@click.group("report")
+def command() -> None:
+    """Export readable, secret-safe JSON reports."""
+
+
+def _envelope(kind: str) -> dict[str, object]:
+    return {
+        "report": kind,
+        "generated_by": f"{CLI_NAME} {__version__}",
+        "generated_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "safe_to_share": True,
+    }
+
+
+def _card_section(app: AppContext) -> dict[str, object]:
+    with app.open_session() as session:
+        state = StateDetector(session).detect()
+        cplc = _read_cplc(session)
+    return {"reader": app.resolved_reader, "state": state.to_dict(), "cplc": cplc}
+
+
+def _piv_section(app: AppContext) -> dict[str, object]:
+    with app.open_session() as session:
+        st = StateDetector(
+            session, probe_fido=False, probe_desfire=False, probe_genuine=False
+        ).detect()
+    return {
+        "state": st.piv.label,
+        "apt": st.piv_apt.to_dict() if st.piv_apt else None,
+        "pin": st.piv_pin.to_dict() if st.piv_pin else None,
+        "puk": st.piv_puk.to_dict() if st.piv_puk else None,
+        "objects_present": st.piv_objects,
+        "notes": st.notes,
+    }
+
+
+def _mifare_section(app: AppContext) -> dict[str, object]:
+    try:
+        with app.open_session() as session:
+            dtx = DesfireTransport(session)
+            version = dtx.get_version().to_dict()
+            free = None
+            with contextlib.suppress(CryptnoxError):
+                free = dtx.get_free_memory()
+            aids = [a.hex().upper() for a in dtx.application_ids()]
+        return {
+            "state": "DesfireReachable",
+            "version": version,
+            "free_memory": free,
+            "applications": aids,
+        }
+    except DesfireNotSelectedError:
+        return {
+            "state": "DesfireNeedsContactlessReader",
+            "note": "DESFire (the default MIFARE applet) did not answer on this interface.",
+        }
+    except CryptnoxError as exc:
+        return {"state": "Unknown", "error": str(exc)}
+
+
+def _genuine_section(app: AppContext) -> dict[str, object]:
+    from cryptnox_id_cli.applets.genuine.genuine import GenuinenessApplet
+
+    try:
+        with app.open_session() as session:
+            gen = GenuinenessApplet(session)
+            if not gen.try_select():
+                return {
+                    "state": "GenuinenessNotPresent",
+                    "note": "genuineness applet not found (contact-only; absent over contactless).",
+                }
+            info = gen.get_info()
+            leaf_der = gen.get_cert()
+        subject = None
+        if leaf_der:
+            from cryptography import x509
+
+            subject = x509.load_der_x509_certificate(leaf_der).subject.rfc4514_string()
+        return {
+            "state": "GenuinenessPersonalized" if leaf_der else "GenuinenessPresent",
+            "leaf_subject": subject,
+            "info": info.hex if info else None,
+            "note": "state only; run `genuine verify` to prove the device key + chain.",
+        }
+    except CryptnoxError as exc:
+        return {"state": "Unknown", "error": str(exc)}
+
+
+def _fido_section(app: AppContext) -> dict[str, object]:
+    try:
+        with app.open_session() as session:
+            ctap = Ctap2Client(session)
+            version = ctap.select()
+            info = describe_get_info(ctap.get_info())
+        return {"state": "FidoPersonalized", "select_version": version, "get_info": info}
+    except CardAccessDeniedError:
+        return {"state": "FidoBlockedByOS", "note": FIDO_WINDOWS_MESSAGE}
+    except AppletNotFoundError:
+        return {"state": "FidoNotPresent"}
+    except CryptnoxError as exc:
+        return {"state": "Unknown", "error": str(exc)}
+
+
+def _emit(app: AppContext, payload: dict[str, object], out: str | None) -> None:
+    text = json.dumps(payload, indent=2, default=str)
+    if out:
+        Path(out).write_text(text + "\n", encoding="utf-8")
+
+    def human(c: Console) -> None:
+        if out:
+            c.print(f"[green]Report written to {out}[/green] (secret-safe JSON).")
+        else:
+            c.print(text)
+
+    app.out.result(payload, human)
+
+
+def _out_option(fn):
+    return click.option(
+        "--out", "out_", type=click.Path(dir_okay=False), help="Write the JSON report to FILE."
+    )(fn)
+
+
+@command.command("card")
+@_out_option
+@click.pass_obj
+def card(app: AppContext, out_: str | None) -> None:
+    """Full card detection report (all three functions)."""
+    payload = _envelope("card")
+    payload.update(_card_section(app))
+    _emit(app, payload, out_)
+
+
+@command.command("piv")
+@_out_option
+@click.pass_obj
+def piv(app: AppContext, out_: str | None) -> None:
+    """PIV applet report."""
+    payload = _envelope("piv")
+    payload["piv"] = _piv_section(app)
+    _emit(app, payload, out_)
+
+
+@command.command("mifare")
+@_out_option
+@click.pass_obj
+def mifare(app: AppContext, out_: str | None) -> None:
+    """MIFARE DESFire report."""
+    payload = _envelope("mifare")
+    payload["mifare"] = _mifare_section(app)
+    _emit(app, payload, out_)
+
+
+@command.command("fido")
+@_out_option
+@click.pass_obj
+def fido(app: AppContext, out_: str | None) -> None:
+    """FIDO2 authenticator report."""
+    payload = _envelope("fido")
+    payload["fido"] = _fido_section(app)
+    _emit(app, payload, out_)
+
+
+@command.command("genuine")
+@_out_option
+@click.pass_obj
+def genuine(app: AppContext, out_: str | None) -> None:
+    """Genuineness / attestation applet report (state only)."""
+    payload = _envelope("genuine")
+    payload["genuine"] = _genuine_section(app)
+    _emit(app, payload, out_)
+
+
+@command.command("full")
+@_out_option
+@click.pass_obj
+def full(app: AppContext, out_: str | None) -> None:
+    """Everything: card + per-function sections (DESFire probed first)."""
+    payload = _envelope("full")
+    # DESFire first: it answers only while no JavaCard applet is selected.
+    payload["mifare"] = _mifare_section(app)
+    payload["card"] = _card_section(app)
+    payload["piv"] = _piv_section(app)
+    payload["fido"] = _fido_section(app)
+    payload["genuine"] = _genuine_section(app)
+    _emit(app, payload, out_)

cryptnox_id_cli/cli/commands/shell.py

@@ -0,0 +1,130 @@
+"""The ``shell`` command — a captive interactive prompt.
+
+Launched from a Start-menu shortcut or by hand, it reads a line, runs it as a
+subcommand (type ``piv info`` — no program-name prefix), and loops. Only this
+CLI's own commands run; it is not an OS shell. Global options passed when
+launching the shell (``--reader``, ``--json``, …) carry into every command.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import shlex
+import sys
+
+import click
+
+from cryptnox_id_cli import CLI_NAME
+from cryptnox_id_cli.cli.context import AppContext
+
+_PROMPT = f"{CLI_NAME}> "
+_BANNER = (
+    f"{CLI_NAME} interactive shell. Type a command without the "
+    f"'{CLI_NAME}' prefix (e.g. 'piv info').\n"
+    "  help            show available commands\n"
+    "  <command> -h    help for a command\n"
+    "  clear           clear the screen\n"
+    "  exit / quit     leave the shell\n"
+)
+
+
+def _global_args(app: AppContext) -> list[str]:
+    """Reconstruct the global options the shell was launched with, so every command
+    inherits them (the reader choice above all)."""
+    args: list[str] = []
+    if app.reader:
+        args += ["--reader", app.reader]
+    if app.json:
+        args.append("--json")
+    if app.verbose:
+        args.append("--verbose")
+    if app.apdu_log_path:
+        args += ["--apdu-log", app.apdu_log_path]
+    if app.dry_run:
+        args.append("--dry-run")
+    if app.yes:
+        args.append("--yes")
+    if app.timeout != 15:
+        args += ["--timeout", str(app.timeout)]
+    if app.no_color:
+        args.append("--no-color")
+    return args
+
+
+@click.command("shell")
+@click.pass_context
+def command(ctx: click.Context) -> None:
+    """Start an interactive prompt that runs this CLI's subcommands."""
+    root = ctx.find_root().command  # the top-level group; avoids importing main (circular)
+    app = ctx.obj
+    base = _global_args(app)
+
+    # Line editing / history only when attached to a real terminal. Two reasons: readline
+    # is pointless on piped input, and (crucially) an imported readline makes input() read
+    # the terminal fd directly, which would bypass a redirected sys.stdin - so a piped or
+    # test-driven stdin must go through sys.stdin.readline() instead.
+    interactive = sys.stdin.isatty()
+    if interactive:  # pragma: no cover - terminal-only
+        # Windows stdlib has no readline; input() still works, just without history.
+        with contextlib.suppress(ImportError):
+            import readline  # noqa: F401
+
+    def _next_line() -> str:
+        if interactive:
+            return input(_PROMPT)
+        line = sys.stdin.readline()
+        if not line:  # EOF on a pipe
+            raise EOFError
+        return line.rstrip("\n")
+
+    click.echo(_BANNER)
+    while True:
+        try:
+            line = _next_line().strip()
+        except EOFError:  # Ctrl-D / end of pipe
+            click.echo()
+            break
+        except KeyboardInterrupt:  # Ctrl-C cancels the line, not the shell
+            click.echo()
+            continue
+
+        if not line:
+            continue
+        low = line.lower()
+        if low in ("exit", "quit"):
+            break
+        if low == "help":
+            line = "--help"
+        elif low == "clear":
+            click.clear()
+            continue
+
+        try:
+            argv = base + shlex.split(line)
+        except ValueError as exc:  # unbalanced quotes
+            click.echo(f"error: {exc}", err=True)
+            continue
+
+        # Re-enter the root group for this one line. standalone_mode=False keeps Click
+        # from calling sys.exit on our behalf; a fresh AppContext per command preserves
+        # the per-command SCP03 session semantics the applets require. Errors are already
+        # routed through the group's funnel; catch the SystemExit it raises so the loop
+        # survives, and catch Click's own usage errors here.
+        #
+        # sys.argv must mirror the line being run: the Windows FIDO elevation offer
+        # rebuilds its UAC relaunch from sys.argv (transport/elevation.relaunch_command),
+        # and the shell's own argv says "shell" - relaunching THAT would open a hidden
+        # elevated shell waiting on input, hanging both processes. Swap it in, restore
+        # after.
+        saved_argv = sys.argv
+        try:
+            sys.argv = [saved_argv[0], *argv]
+            root.main(args=argv, prog_name=CLI_NAME, standalone_mode=False)
+        except SystemExit:
+            pass  # error already reported via the group's funnel; keep the shell alive
+        except click.ClickException as exc:
+            exc.show()
+        except (KeyboardInterrupt, EOFError):
+            click.echo()
+        finally:
+            sys.argv = saved_argv

cryptnox_id_cli/cli/context.py

@@ -0,0 +1,71 @@
+"""The per-invocation application context shared by all commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TextIO
+
+from cryptnox_id_cli import CLI_NAME
+from cryptnox_id_cli.output.render import Output
+from cryptnox_id_cli.secrets.redaction import Redactor
+from cryptnox_id_cli.transport.pcsc import CardSession, RawConnection, connect, pick_reader
+
+
+@dataclass
+class AppContext:
+    reader: str | None = None
+    json: bool = False
+    verbose: bool = False
+    apdu_log_path: str | None = None
+    dry_run: bool = False
+    yes: bool = False
+    timeout: int = 15
+    no_color: bool = False
+    elevated_result_out: str | None = None
+
+    resolved_reader: str | None = field(default=None, init=False)
+    out: Output = field(init=False)
+    redactor: Redactor = field(init=False)
+    _log_fh: TextIO | None = field(default=None, init=False)
+
+    def __post_init__(self) -> None:
+        self.out = Output(
+            json=self.json,
+            no_color=self.no_color,
+            verbose=self.verbose,
+            result_path=self.elevated_result_out,
+        )
+        self.redactor = Redactor()
+
+    def _trace(self, line: str) -> None:
+        if self.verbose:
+            self.out.err.print(f"[dim]apdu {line}[/dim]")
+
+    def _ensure_log(self) -> TextIO | None:
+        if self.apdu_log_path and self._log_fh is None:
+            self._log_fh = open(self.apdu_log_path, "a", encoding="utf-8")  # noqa: SIM115
+            self._log_fh.write(f"# {CLI_NAME} APDU transcript (secrets redacted)\n")
+        return self._log_fh
+
+    def make_session(self, conn: RawConnection, *, reader_name: str | None = None) -> CardSession:
+        """Wrap an already-open connection in a CardSession with our redactor/log."""
+        return CardSession(
+            conn,
+            redactor=self.redactor,
+            apdu_log=self._ensure_log(),
+            trace=self._trace,
+            reader_name=reader_name,
+        )
+
+    def open_session(self) -> CardSession:
+        """Connect to the resolved reader (Cryptnox/ACS-first) and return a CardSession."""
+        name = pick_reader(self.reader)
+        self.resolved_reader = name
+        return self.make_session(connect(name), reader_name=name)
+
+    def close(self) -> None:
+        if self._log_fh is not None:
+            try:
+                self._log_fh.close()
+            finally:
+                self._log_fh = None

cryptnox_id_cli/cli/dryrun.py

@@ -0,0 +1,181 @@
+"""Fail-closed enforcement of the global ``--dry-run`` promise.
+
+``--dry-run`` is documented as "write nothing to the card". Only a few commands can
+actually *plan* their card operations; historically every other command silently ignored
+the flag and executed for real - so ``--dry-run fido reset ...`` wiped the authenticator
+it promised to spare. This module closes that hole centrally:
+
+* commands in :data:`PLANS_OWN` implement ``app.dry_run`` themselves (they show a plan
+  and send nothing) - left alone;
+* commands in :data:`READ_ONLY` cannot change card state (and consume no secrets or
+  retry counters) - left alone;
+* everything else - :data:`NO_DRY_RUN`, and any future command nobody classified - is
+  wrapped so that under ``--dry-run`` it REFUSES to run before opening a card session.
+
+Refusing a read-only-but-unclassified command costs an error message; executing a
+mutating one costs a card. Fail closed. A unit test asserts every leaf command is
+classified in exactly one of the three sets, so adding a command forces the decision.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+from cryptnox_id_cli.cli.context import AppContext
+
+#: Commands that implement ``app.dry_run`` themselves: they detect, plan, print the
+#: intended steps, and send nothing. Verified by reading each implementation.
+PLANS_OWN = frozenset(
+    {
+        "apdu select",
+        "apdu send",
+        "apdu transcript",
+        "factory piv preperso finalize",
+        "factory piv preperso load-config",
+        "piv perso import-key",
+        "piv perso import-p12",
+        "piv quickstart",
+    }
+)
+
+#: Commands that cannot mutate card state and consume no cardholder secrets or retry
+#: counters, so running them under ``--dry-run`` is harmless. Local-file writers
+#: (``report``, ``generate-chuid``, ``--out`` exports) belong here: the promise is
+#: about the card. ``shell`` is a container - each forwarded line re-enters the root
+#: group and gets its own guard.
+READ_ONLY = frozenset(
+    {
+        "doctor",
+        "info",
+        "readers",
+        "shell",
+        "factory piv preperso export-config",
+        "factory piv preperso init-config",
+        "factory piv preperso inspect-defaults",
+        "factory piv preperso status",
+        "fido config show",
+        "fido get-info",
+        "fido info",
+        "fido pin status",
+        "fido ping",
+        "genuine info",
+        "genuine verify",
+        "mifare apps list",
+        "mifare files list",
+        "mifare free-memory",
+        "mifare info",
+        "mifare read",
+        "mifare record read",
+        "mifare sdm read",
+        "mifare value get",
+        "mifare version",
+        "piv admin status",
+        "piv certs export",
+        "piv certs inspect",
+        "piv certs list",
+        "piv discover",
+        "piv export-attestation",
+        "piv info",
+        "piv objects list",
+        "piv objects read",
+        "piv perso generate-ccc",
+        "piv perso generate-chuid",
+        "piv perso generate-discovery",
+        "piv pin status",
+        "piv preperso",
+        "piv slots",
+        "piv status",
+        "piv validate",
+        "piv verify-attestation",
+        "report card",
+        "report fido",
+        "report full",
+        "report genuine",
+        "report mifare",
+        "report piv",
+    }
+)
+
+#: Commands that mutate the card, or consume secrets / retry counters (a wrong PIN in a
+#: "read" like ``fido credential list`` still burns an attempt), and have no planning
+#: mode. Under ``--dry-run`` these refuse to run. The listing is deliberate: the
+#: partition test forces every new command to be classified here or above.
+NO_DRY_RUN = frozenset(
+    {
+        "fido config min-pin-length",
+        "fido config toggle-always-uv",
+        "fido credential assert",
+        "fido credential create",
+        "fido credential delete",
+        "fido credential list",
+        "fido credential self-test",
+        "fido pin change",
+        "fido pin set",
+        "fido reset",
+        "mifare app create",
+        "mifare app delete",
+        "mifare files create-standard",
+        "mifare format",
+        "mifare keys authenticate",
+        "mifare keys change",
+        "mifare record clear",
+        "mifare record create",
+        "mifare record write",
+        "mifare sdm setup",
+        "mifare value create",
+        "mifare value credit",
+        "mifare value debit",
+        "mifare write",
+        "piv admin authenticate",
+        "piv perso generate-csr",
+        "piv perso generate-key",
+        "piv perso import-cert",
+        "piv perso self-sign-cert",
+        "piv perso set-pin",
+        "piv perso set-puk",
+        "piv perso smoke-test",
+        "piv perso write-object",
+        "piv perso write-standard-objects",
+        "piv pin change",
+        "piv pin unblock",
+        "piv pin verify",
+        "piv puk change",
+    }
+)
+
+
+def _refusing(path: str, fn: Callable[..., Any]) -> Callable[..., Any]:
+    @functools.wraps(fn)
+    def inner(*args: Any, **kwargs: Any) -> Any:
+        ctx = click.get_current_context(silent=True)
+        app = ctx.find_object(AppContext) if ctx is not None else None
+        if app is not None and app.dry_run:
+            raise click.ClickException(
+                f"--dry-run: '{path}' cannot preview its card operations, so it refuses to "
+                "run (fail-closed; nothing was sent to the card). Run it without --dry-run "
+                "to execute."
+            )
+        return fn(*args, **kwargs)
+
+    return inner
+
+
+def install_guard(root: click.Group) -> None:
+    """Wrap every leaf command not known to be dry-run-safe. Idempotent."""
+    if getattr(root, "_dry_run_guard", False):  # pragma: no cover - import-time reentry
+        return
+    root._dry_run_guard = True  # type: ignore[attr-defined]
+    _wrap(root, "")
+
+
+def _wrap(group: click.Group, prefix: str) -> None:
+    for name, cmd in group.commands.items():
+        path = f"{prefix}{name}"
+        if isinstance(cmd, click.Group):
+            _wrap(cmd, path + " ")
+        elif path not in READ_ONLY and path not in PLANS_OWN and cmd.callback is not None:
+            cmd.callback = _refusing(path, cmd.callback)